星战科技xingzhan.cloud
返回市场
比特桶-MCP服务器

比特桶-MCP服务器

作者：pdogra129911 星标更新：2025-10-14
安装使用来源：spider==github.com

项目介绍

Bitbucket MCP 服务器

npm 版本 许可证：MIT

这是一个 MCP（模型上下文协议）服务器，提供了与 Bitbucket API 交互的工具，支持 Bitbucket Cloud 和 Bitbucket Server。

功能

当前实现的工具

核心 PR 生命周期工具

  • get_pull_request - 获取拉取请求的详细信息
  • list_pull_requests - 列出拉取请求（带过滤器：状态、作者、分页）
  • create_pull_request - 创建新的拉取请求
  • update_pull_request - 更新 PR 细节（标题、描述、审阅者、目标分支）
  • add_comment - 在拉取请求中添加评论（支持回复）
  • merge_pull_request - 使用各种策略合并拉取请求
  • list_pr_commits - 列出属于某个拉取请求的所有提交
  • delete_branch - 合并后删除分支

分支管理工具

  • list_branches - 列出分支（带过滤和分页）
  • delete_branch - 删除分支（带保护检查）
  • get_branch - 获取详细的分支信息（包括关联的 PR）
  • list_branch_commits - 列出分支中的提交（高级过滤）

文件和目录工具

  • list_directory_content - 列出仓库路径中的文件和目录
  • get_file_content - 获取文件内容（大文件智能截断）

代码审查工具

  • get_pull_request_diff - 获取拉取请求的差异/更改
  • approve_pull_request - 批准拉取请求
  • unapprove_pull_request - 取消批准拉取请求
  • request_changes - 要求对拉取请求进行更改
  • remove_requested_changes - 移除拉取请求中的更改要求

搜索工具

  • search_code - 在仓库中搜索代码（目前仅支持 Bitbucket Server）

项目和仓库发现工具

  • list_projects - 列出所有可访问的 Bitbucket 项目/工作区（带过滤）
  • list_repositories - 列出项目中的仓库或所有可访问项目的仓库

安装

使用 npx（推荐）

使用此 MCP 服务器最简单的方法是直接通过 npx：

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/bitbucket-mcp-server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

对于 Bitbucket Server：

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/bitbucket-mcp-server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

从源码安装

  1. 克隆或下载此仓库
  2. 安装依赖项： 
    npm install
  3. 构建 TypeScript 代码： 
    npm run build

认证设置

此服务器使用 Bitbucket 应用密码进行认证。

创建应用密码

  1. 登录到您的 Bitbucket 帐户
  2. 导航至：https://bitbucket.org/account/settings/app-passwords/
  3. 点击“创建应用密码”
  4. 给它一个描述性的标签（例如，“MCP 服务器”）
  5. 选择以下权限：
    • 帐户：读取
    • 仓库：读取、写入
    • 拉取请求：读取、写入
  6. 点击“创建”
  7. 重要：立即复制生成的密码（您无法再次查看它！）

运行设置脚本

node scripts/setup-auth.js

这将引导您完成认证设置过程。

配置

将服务器添加到您的 MCP 设置文件中（通常位于 ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）：

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

替换：

  • /absolute/path/to/bitbucket-mcp-server 为该目录的实际路径
  • your-username 为您在 Bitbucket 中的用户名（非电子邮件）
  • your-app-password 为您创建的应用密码

对于 Bitbucket Server，请使用：

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

重要提示：Bitbucket Server 用户

  • 使用完整的电子邮件地址作为用户名（例如，“john.doe@company.com”）
  • 这是为了使审批/审查操作正确运行

使用方法

配置完成后，您可以使用可用的工具：

获取拉取请求

{
  "tool": "get_pull_request",
  "arguments": {
    "workspace": "PROJ",  // 必需 - 您的项目键
    "repository": "my-repo",
    "pull_request_id": 123
  }
}

返回关于拉取请求的详细信息，包括：

  • 标题和描述
  • 作者和审阅者
  • 源分支和目标分支
  • 审批状态
  • Web UI 和差异链接
  • 合并提交详情（当 PR 合并时）：
    • merge_commit_hash：合并提交的哈希值
    • merged_by：执行合并的人
    • merged_at：合并发生的时间
    • merge_commit_message：合并提交的消息
  • 活动评论及其嵌套回复（需要关注的未解决评论）：
    • active_comments：最近的 20 条顶级评论数组
      • 评论文本和作者
      • 创建日期
      • 是否为内联评论（带有文件路径和行号）
      • 嵌套回复（针对 Bitbucket Server）：
        • replies：具有相同结构的回复评论数组
        • 回复可以多层嵌套
      • 父级引用（针对 Bitbucket Cloud）：
        • parent_id：回复评论的父级评论 ID
    • active_comment_count：未解决评论总数（包括嵌套回复）
    • total_comment_count：所有评论总数（包括已解决和回复）
  • 文件更改：
    • file_changes：PR 中修改的所有文件数组
      • 文件路径
      • 状态（新增、修改、删除或重命名）
      • 旧路径（对于重命名文件）
    • file_changes_summary：汇总统计
      • 更改的文件总数
  • 以及更多...

搜索代码

在 Bitbucket 仓库中搜索代码（目前仅支持 Bitbucket Server）：

// 在特定仓库中搜索
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "search_query": "TODO",
    "limit": 50
  }
}

// 在工作区中的所有仓库中搜索
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "search_query": "deprecated",
    "file_pattern": "*.java",  // 可选：按文件模式过滤
    "limit": 100
  }
}

// 使用文件模式过滤搜索
{
  "tool": "search_code",
  "arguments": {
    "workspace": "PROJ",
    "repository": "frontend-app",
    "search_query": "useState",
    "file_pattern": "*.tsx",  // 仅在 .tsx 文件中搜索
    "start": 0,
    "limit": 25
  }
}

返回搜索结果，包括：

  • 文件路径和名称
  • 仓库和项目信息
  • 匹配的行，包括：
    • 行号
    • 整行内容
    • 显示精确匹配的高亮段落
  • 分页信息

示例响应：

{
  "message": "代码搜索成功完成",
  "workspace": "PROJ",
  "repository": "my-repo",
  "search_query": "TODO",
  "results": [
    {
      "file_path": "src/utils/helper.js",
      "file_name": "helper.js",
      "repository": "my-repo",
      "project": "PROJ",
      "matches": [
        {
          "line_number": 42,
          "line_content": "    // TODO: 实现错误处理",
          "highlighted_segments": [
            { "text": "    // ", "is_match": false },
            { "text": "TODO", "is_match": true },
            { "text": ": 实现错误处理", "is_match": false }
          ]
        }
      ]
    }
  ],
  "total_count": 15,
  "start": 0,
  "limit": 50,
  "has_more": false
}

注意：此工具目前仅适用于 Bitbucket Server。Bitbucket Cloud 支持计划在未来版本中提供。

列出拉取请求

{
  "tool": "list_pull_requests",
  "arguments": {
    "workspace": "PROJ",  // 必需 - 您的项目键
    "repository": "my-repo",
    "state": "OPEN",  // 可选：OPEN, MERGED, DECLINED, ALL（默认：OPEN）
    "author": "username",  // 可选：按作者过滤（见下方注释）
    "limit": 25,  // 可选：每页最大结果数（默认：25）
    "start": 0  // 可选：分页起始索引（默认：0）
  }
}

返回分页的拉取请求列表，包括：

  • 拉取请求数组，与 get_pull_request 的细节相同
  • 匹配的 PR 总数
  • 分页信息（has_more, next_start）

关于作者过滤的注意事项：

  • 对于 Bitbucket Cloud：使用用户名（例如，“johndoe”）
  • 对于 Bitbucket Server：使用完整的电子邮件地址（例如，“john.doe@company.com”）

创建拉取请求

{
  "tool": "create_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "title": "添加新功能",
    "source_branch": "feature/new-feature",
    "destination_branch": "main",
    "description": "此 PR 添加了一个新功能...",  // 可选
    "reviewers": ["john.doe", "jane.smith"],  // 可选
    "close_source_branch": true  // 可选（默认：false）
  }
}

更新拉取请求

{
  "tool": "update_pull_request",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "title": "更新标题",  // 可选
    "description": "更新描述",  // 可选
    "destination_branch": "develop",  // 可选
    "reviewers": ["new.reviewer"]  // 可选 - 见下方注释
  }
}

关于审阅者的注意事项：

  • 当更新 PR 时不指定 reviewers 参数时，现有的审阅者及其审批状态会被保留
  • 当提供 reviewers 参数时：
    • 审阅者列表将被替换为新列表
    • 对于已经存在于 PR 上的审阅者，其审批状态会被保留
    • 新的审阅者将被添加且没有审批状态
  • 这样可以防止意外移除审阅者，当您只想更新 PR 描述或标题时

添加评论

向拉取请求添加评论，既可以作为一般评论，也可以针对特定代码行进行内联评论：

// 一般评论
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "这个 PR 很棒！"
  }
}

// 针对特定行的内联评论
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "考虑将这部分提取为一个单独的函数",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT"  // ADDED, REMOVED 或 CONTEXT
  }
}

// 回复现有评论
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "我同意这个建议",
    "parent_comment_id": 456
  }
}

// 添加带有代码建议的评论（单行）
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "这个变量名可以更具描述性。",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT",
    "suggestion": "const userAuthenticationToken = token;"
  }
}

// 添加带有多行代码建议的评论
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "这个函数可以通过数组方法简化。",
    "file_path": "src/utils/calculations.js",
    "line_number": 50,
    "suggestion_end_line": 55,
    "line_type": "CONTEXT",
    "suggestion": "function calculateTotal(items) {\n  return items.reduce((sum, item) => sum + item.price, 0);\n}"
  }
}

建议功能使用 GitHub 样式的 Markdown 建议块来格式化评论，Bitbucket 可以渲染这些块。添加建议时：

  • suggestion 是必需的，并包含替换代码
  • file_path 和 line_number 在使用建议时是必需的
  • suggestion_end_line 是可选的，用于多行建议（默认为 line_number）
  • 评论将被格式化为适用的 Bitbucket UI 中的 ````suggestion` Markdown 块

使用代码片段而不是行号

add_comment 工具现在支持自动查找行号，使用代码片段。这对于 AI 工具分析差异时特别有用，可能会难以确定确切的行号：

// 使用代码片段添加评论
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "这个变量名可以更具描述性",
    "file_path": "src/components/Button.res",
    "code_snippet": "let isDisabled = false",
    "search_context": {
      "before": ["let onClick = () => {"],
      "after": ["setLoading(true)"]
    }
  }
}

// 多个匹配时使用策略
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "考虑将这部分提取出来",
    "file_path": "src/utils/helpers.js",
    "code_snippet": "return result;",
    "search_context": {
      "before": ["const result = calculate();"],
      "after": ["}"]
    },
    "match_strategy": "best"  // 自动选择最高置信度匹配
  }
}

代码片段参数：

  • code_snippet：要查找的确切代码行（替代 line_number）
  • search_context：可选上下文，用于消除多个匹配
    • before：目标之前应该出现的行数组
    • after：目标之后应该出现的行数组
  • match_strategy：如何处理多个匹配
    • "strict"（默认）：显示所有匹配的错误
    • "best"：自动选择最高置信度匹配

严格模式下多个匹配的错误响应：

{
  "error": {
    "code": "MULTIPLE_MATCHES_FOUND",
    "message": "代码片段 'return result;' 在 3 个位置找到",
    "occurrences": [
      {
        "line_number": 42,
        "file_path": "src/utils/helpers.js",
        "preview": "  const result = calculate();\n> return result;\n}",
        "confidence": 0.9,
        "line