Atlassian Bitbucket MCP 服务器

本项目提供了一个模型上下文协议（MCP）服务器，作为AI助手（如Anthropic的Claude、Cursor AI或其他MCP兼容客户端）与您的Atlassian Bitbucket实例之间的桥梁。它允许AI安全地访问和实时交互您的仓库、拉取请求和工作区。

什么是MCP以及为什么使用此服务器？

模型上下文协议（MCP）是一个开放标准，使AI模型能够安全地连接到外部工具和数据源。此服务器特别为Bitbucket Cloud实现了MCP。

优点：

• 实时访问： 您的AI助手可以直接访问最新的Bitbucket数据（仓库、PR等）。
• 消除复制/粘贴： 不需要手动在Bitbucket和您的AI助手之间传输信息。
• 增强的AI功能： 使AI能够分析仓库、审查拉取请求、理解代码上下文，并直接与您的版本控制系统工作。
• 安全性： 您可以通过API凭证（Atlassian API令牌或Bitbucket应用程序密码）控制访问。AI通过服务器进行交互，敏感操作保持受控。

可用工具

此MCP服务器为您的AI助手提供了以下工具：

• List Workspaces (list-workspaces)

  • Purpose: Discover available Bitbucket workspaces you have access to and find their 'slugs' (unique identifiers).
  • Use When: You need to know which workspaces are available or find the slug for a specific workspace to use with other tools.
  • Conversational Example: "Show me all my Bitbucket workspaces."
  • Parameter Example: {} (no parameters needed for basic list) or { query: "devteam" } (to filter).

• Get Workspace (get-workspace)

  • Purpose: Retrieve detailed information about a specific workspace using its slug.
  • Use When: You know the workspace slug and need its full details or links to its contents.
  • Conversational Example: "Tell me more about the 'acme-corp' workspace."
  • Parameter Example: { workspaceSlug: "acme-corp" }

• List Repositories (list-repositories)

  • Purpose: List repositories within a specific workspace and find their 'slugs'. Requires the workspace slug.
  • Use When: You need to find repositories within a known workspace or get the slug for a specific repository.
  • Conversational Example: "List the repositories in the 'acme-corp' workspace."
  • Parameter Example: { workspaceSlug: "acme-corp" } or { workspaceSlug: "acme-corp", query: "backend" } (to filter).

• Get Repository (get-repository)

  • Purpose: Retrieve detailed information about a specific repository using its workspace and repository slugs.
  • Use When: You know the workspace and repository slugs and need full details like description, language, owner, etc.
  • Conversational Example: "Show me details for the 'backend-api' repository in the 'acme-corp' workspace."
  • Parameter Example: { workspaceSlug: "acme-corp", repoSlug: "backend-api" }

• List Pull Requests (list-pull-requests)

  • Purpose: List pull requests within a specific repository. Requires workspace and repository slugs.
  • Use When: You need to find open/merged/etc. pull requests in a known repository or get the ID for a specific PR.
  • Conversational Example: "Show me the open pull requests for the 'acme-corp/frontend-app' repository."
  • Parameter Example: { workspaceSlug: "acme-corp", repoSlug: "frontend-app", state: "OPEN" }

• Get Pull Request (get-pull-request)

  • Purpose: Retrieve detailed information about a specific pull request using its workspace slug, repository slug, and PR ID.
  • Use When: You know the identifiers for a specific PR and need its full description, reviewers, status, branches, etc.
  • Conversational Example: "Get the details for pull request #42 in the 'acme-corp/frontend-app' repo."
  • Parameter Example: { workspaceSlug: "acme-corp", repoSlug: "frontend-app", prId: "42" }

• Add Pull Request Comment (add-pr-comment)

  • Purpose: Add comments to a pull request, including both general PR comments and inline code comments.
  • Use When: You need to provide feedback, ask questions, or communicate with contributors on a specific PR.
  • Conversational Example: "Add a comment to pull request #42 in the 'acme-corp/frontend-app' repo saying 'This looks good to merge'."
  • Parameter Example: { workspaceSlug: "acme-corp", repoSlug: "frontend-app", prId: "42", content: "This looks good to merge" } or with inline comment: { workspaceSlug: "acme-corp", repoSlug: "frontend-app", prId: "42", content: "Consider a constant here", inline: { path: "src/utils.js", line: 42 } }

• Create Pull Request (create-pull-request)

  • Purpose: Create a new pull request from one branch to another within a repository.
  • Use When: You need to initiate a code review for a completed feature or bug fix, or want to merge changes from a feature branch into a main branch.
  • Conversational Example: "Create a pull request in the 'acme-corp/frontend-app' repo from the 'feature/new-login' branch to 'main' with the title 'Add new login screen'."
  • Parameter Example: { workspaceSlug: "acme-corp", repoSlug: "frontend-app", title: "Add new login screen", sourceBranch: "feature/new-login" } or with more options: { workspaceSlug: "acme-corp", repoSlug: "frontend-app", title: "Fix login bug", sourceBranch: "bugfix/login", description: "This fixes issue #123", destinationBranch: "develop", closeSourceBranch: true }

接口哲学：简单输入，丰富输出

此服务器遵循“最小接口，最大细节”的方法：

1. 简单工具：仅请求必要的标识符（如 workspaceSlug、repoSlug、prId）。
2. 丰富细节：当你请求特定项目（如 get-repository）时，默认情况下服务器会提供所有相关信息（描述、所有者、链接等），而不需要额外的标志。

前提条件

• Node.js 和 npm：确保已安装 Node.js（包括 npm）。从 nodejs.org 下载。
• Bitbucket 账户：拥有一个活跃的 Bitbucket Cloud 账户，并且可以访问你想要连接的工作区和仓库。

快速入门指南

按照以下步骤将你的 AI 助手连接到 Bitbucket：

第 1 步：设置身份验证

你有两种方式来验证与 Bitbucket 的连接：

选项 A：Bitbucket 应用程序密码（建议仅用于 Bitbucket）

重要：像对待密码一样对待你的应用程序密码。不要分享它或将它提交到版本控制中。

1. 导航到你的 Bitbucket 个人设置：
   https://bitbucket.org/account/settings/app-passwords/
2. 点击 创建应用程序密码。
3. 给它一个 标签（例如，mcp-bitbucket-access）。
4. 授予以下 权限（至少需要）：
   • 工作区：读取
   • 仓库：读取
   • 拉取请求：读取
5. 点击 创建。
6. 立即复制生成的应用程序密码。之后你将无法再次查看它。安全地存储它。

选项 B：Atlassian API 令牌（如果连接其他 Atlassian 工具如 Jira/Confluence 时使用）

重要：像对待密码一样对待你的 API 令牌。

1. 转到你的 Atlassian API 令牌管理页面：
   https://id.atlassian.com/manage-profile/security/api-tokens
2. 点击 创建 API 令牌。
3. 给它一个描述性的 标签（例如，mcp-bitbucket-access）。
4. 点击 创建。
5. 立即复制生成的 API 令牌。安全地存储它。

第 2 步：配置服务器凭据

选择 下列之一 方法：

方法 A：全局 MCP 配置文件（推荐）

这使得凭据分离且组织良好。

1. 创建目录（如果需要）：~/.mcp/

2. 创建/编辑文件： ~/.mcp/configs.json

3. 添加配置： 根据你选择的身份验证方法，粘贴以下 JSON 结构之一，并替换占位符：

   使用 Bitbucket 应用密码：

   {
       "@aashari/mcp-server-atlassian-bitbucket": {
           "environments": {
               "ATLASSIAN_BITBUCKET_USERNAME": "<YOUR_BITBUCKET_USERNAME>",
               "ATLASSIAN_BITBUCKET_APP_PASSWORD": "<YOUR_COPIED_APP_PASSWORD>"
           }
       }
       // 如果需要，可以在这里添加其他服务器
   }
   

   • <YOUR_BITBUCKET_USERNAME>: 你的 Bitbucket 用户名。
   • <YOUR_COPIED_APP_PASSWORD>: 步骤 1B 中复制的应用密码。

   使用 Atlassian API 令牌：

   {
       "@aashari/mcp-server-atlassian-bitbucket": {
           "environments": {
               "ATLASSIAN_SITE_NAME": "<YOUR_ATLASSIAN_SITE_NAME_UNUSED_BUT_NEEDED>",
               "ATLASSIAN_USER_EMAIL": "<YOUR_ATLASSIAN_EMAIL>",
               "ATLASSIAN_API_TOKEN": "<YOUR_COPIED_API_TOKEN>"
           }
       }
       // 如果需要，可以在这里添加其他服务器
   }
   

   • <YOUR_ATLASSIAN_SITE_NAME_UNUSED_BUT_NEEDED>: 输入任何值（例如 bitbucket）。此字段是底层传输所需，但在使用 API 令牌时不会用于 Bitbucket API 身份验证。
   • <YOUR_ATLASSIAN_EMAIL>: 你的 Atlassian 账户电子邮件。
   • <YOUR_COPIED_API_TOKEN>: 步骤 1B 中复制的 API 令牌。

方法 B：环境变量（替代方案）

在运行服务器时设置环境变量。选择与你的身份验证相匹配的一组：

使用 Bitbucket 应用密码：

ATLASSIAN_BITBUCKET_USERNAME="<YOUR_USERNAME>" \
ATLASSIAN_BITBUCKET_APP_PASSWORD="<YOUR_APP_PASSWORD>" \
npx -y @aashari/mcp-server-atlassian-bitbucket

使用 Atlassian API 令牌：

ATLASSIAN_SITE_NAME="bitbucket" \
ATLASSIAN_USER_EMAIL="<YOUR_EMAIL>" \
ATLASSIAN_API_TOKEN="<YOUR_API_TOKEN>" \
npx -y @aashari/mcp-server-atlassian-bitbucket

第三步：连接你的 AI 助手

配置你的 MCP 客户端（如 Claude Desktop、Cursor 等）以运行此服务器。

Claude Desktop

1. 打开设置（齿轮图标）> 编辑配置。

2. 添加或合并到 mcpServers：

   {
       "mcpServers": {
           "aashari/mcp-server-atlassian-bitbucket": {
               "command": "npx",
               "args": ["-y", "@aashari/mcp-server-atlassian-bitbucket"]
           }
           // ... 其他服务器
       }
   }
   

3. 保存并重启 Claude Desktop。

4. 验证： 点击“工具”（锤子图标）；Bitbucket 工具应该会列出。

Cursor AI

1. 命令面板 (Cmd+Shift+P / Ctrl+Shift+P) > Cursor 设置 > MCP。
2. 点击 + 添加新的 MCP 服务器。
3. 输入：
   • 名称：aashari/mcp-server-atlassian-bitbucket
   • 类型：command
   • 命令：npx -y @aashari/mcp-server-atlassian-bitbucket
4. 点击 添加。
5. 验证： 等待服务器名称旁边的指示器变为绿色。

第四步：使用工具

你现在可以向你的 AI 助手询问有关你的 Bitbucket 实例的问题：

• "列出我有访问权限的所有 Bitbucket 工作区。"
• "显示'dev-team'工作区中的所有仓库。"
• "获取'dev-team'工作区中'main-api'仓库的信息。"
• "显示'dev-team/main-api'仓库的开放拉取请求。"
• "总结'dev-team/main-api'仓库中编号为42的拉取请求。"
• "在'dev-team/main-api'仓库中从'feature/login'分支向'main'创建一个标题为'Add new login feature'的拉取请求。"

作为命令行工具使用 (CLI)

您也可以直接从终端使用此包。请先设置凭证（上述方法A或B）。

使用 npx 快速使用

npx -y @aashari/mcp-server-atlassian-bitbucket list-workspaces
npx -y @aashari/mcp-server-atlassian-bitbucket get-repository --workspace my-team --repository my-api
npx -y @aashari/mcp-server-atlassian-bitbucket list-pull-requests --workspace my-team --repository my-api --state OPEN
npx -y @aashari/mcp-server-atlassian-bitbucket create-pull-request --workspace my-team --repository my-api --title "New feature" --source-branch feature/new-login

全局安装（可选）

1. npm install -g @aashari/mcp-server-atlassian-bitbucket
2. 使用 mcp-atlassian-bitbucket 命令：

mcp-atlassian-bitbucket list-workspaces --limit 5
mcp-atlassian-bitbucket get-pull-request --workspace my-team --repository my-api --pull-request 42
mcp-atlassian-bitbucket --help # See all commands

故障排除

• 认证错误 (401/403):
  • 检查 ~/.mcp/configs.json 或环境变量中的凭证。确保使用了正确的集合（应用密码或API令牌）。
  • 确认应用密码或API令牌是正确的、有效的，并且未被撤销。
  • 确保您的账户有权访问特定的Bitbucket资源。
• 服务器无法连接（在AI客户端中）:
  • 确保客户端配置中的命令 (npx ...) 是正确的。
  • 检查是否已安装Node.js/npm并且它们在您的PATH中。
  • 直接在终端运行 npx 命令以查看错误。
• 资源未找到 (404):
  • 核实工作区/仓库slug和PR ID是否正确（slug区分大小写）。
  • 检查您对特定资源的权限。
• 启用调试日志: 设置 DEBUG 环境变量为 true（例如，在 configs.json 中添加 "DEBUG": "true" 或运行 DEBUG=true npx ...）。

开发者：贡献

欢迎贡献！如果您希望参与贡献，请考虑以下几点：

• 架构: 服务器采用了分层方法（CLI/工具 -> 控制器 -> 服务）。更多详情请参见 .cursorrules 文件或代码注释。
• 设置: 克隆仓库，运行 npm install。使用 npm run dev:server 进行热重载运行或 npm run dev:cli -- <command> 测试CLI命令。
• 代码风格: 运行 npm run lint 和 npm run format。
• 测试: 为新功能添加测试 (npm test)。
• 一致性: 确保新的工具/命令遵循“最小接口，最大细节”理念，并与现有模式相匹配。

版本说明

该项目 (@aashari/mcp-server-atlassian-bitbucket) 遵循语义化版本控制，并独立于其他 @aashari/mcp-server-* 包进行版本管理。

许可证

ISC