Bitbucket Server MCP

用于 Bitbucket Server 拉取请求管理的 MCP (Model Context Protocol) 服务器。该服务器提供工具和资源，通过 MCP 协议与 Bitbucket Server API 进行交互。

✨ 新功能

• 🔧 自定义 HTTP 请求头: 通过 BITBUCKET_CUSTOM_HEADERS 环境变量为所有请求添加自定义请求头（适用于零信任令牌或代理）

• 📋 PR 发现: 使用 list_pull_requests 按状态、作者或方向列出并筛选拉取请求（修复 #14）

• 🌿 分支管理: 使用 list_branches 列出分支（支持默认分支检测），使用 delete_branch 删除已合并的分支

• 📝 提交历史: 使用 list_commits 浏览提交历史（支持分支和作者筛选）

• ✅ PR 批准: 使用 approve_pull_request 和 unapprove_pull_request 批准或取消批准拉取请求

• 🔍 高级搜索: 使用 search 工具在存储库中搜索代码和文件（支持项目/存储库筛选）

• 📄 文件操作: 使用 get_file_content 和 browse_repository 读取文件内容并浏览存储库目录

• 💬 评论管理: 使用 get_comments 工具提取并筛选 PR 评论

• 🔍 项目发现: 使用 list_projects 列出所有可访问的 Bitbucket 项目

• 📁 存储库浏览: 使用 list_repositories 探索跨项目的存储库

• 🔧 灵活的项目支持: 使默认项目成为可选 - 可按命令指定或使用 BITBUCKET_DEFAULT_PROJECT

• 📖 增强的文档: 改进了 README，包含使用示例和更好的配置指南

Related MCP server: Bitbucket MCP Server

要求

• Node.js >= 16

安装

通过 Smithery 安装

通过 Smithery 自动为 Claude Desktop 安装 Bitbucket Server：

npx -y @smithery/cli install @garc33/bitbucket-server-mcp-server --client claude

手动安装

npm install

构建

npm run build

功能

该服务器提供以下工具，用于全面的 Bitbucket Server 集成：

list_projects

发现并探索 Bitbucket 项目：列出所有可访问的项目及其详细信息。对于项目发现和查找在其他操作中使用的正确项目键至关重要。

使用场景：

• 当您不知道确切的项目键时查找可用项目

• 探索项目结构和权限

• 发现您有权访问的新项目

参数：

• limit: 返回的项目数量（默认：25，最大：1000）

• start: 分页的起始索引（默认：0）

list_repositories

浏览并发现存储库：探索特定项目内或所有可访问项目中的存储库。返回全面的存储库信息，包括克隆 URL 和元数据。

使用场景：

• 为其他操作查找存储库 slug

• 探索跨项目的代码库结构

• 发现您有权访问的存储库

• 浏览特定项目的存储库

参数：

• project: Bitbucket 项目键（可选，如果未提供则使用 BITBUCKET_DEFAULT_PROJECT）

• limit: 返回的存储库数量（默认：25，最大：1000）

• start: 分页的起始索引（默认：0）

create_pull_request

提交代码更改以供审查：创建一个新的拉取请求以提交代码更改、请求审查或合并功能分支。自动处理分支引用和审查者分配。

使用场景：

• 提交功能开发以供审查

• 提出错误修复

• 请求从功能分支合并代码

• 协作处理代码更改

参数：

• project: Bitbucket 项目键（可选，如果未提供则使用 BITBUCKET_DEFAULT_PROJECT）

• repository (必需): 存储库 slug

• title (必需): 清晰、描述性的 PR 标题

• description: 带有上下文的详细描述（支持 Markdown）

• sourceBranch (必需): 包含更改的源分支

• targetBranch (必需): 要合并的目标分支

• reviewers: 审查者用户名数组

• sourceProject: 源存储库的项目键（用于来自 fork 的跨存储库 PR）

• sourceRepository: 源存储库的 slug（用于来自 fork 的跨存储库 PR）

• includeDefaultReviewers: 自动获取并包含为目标分支配置的默认审查者（默认：true）

update_pull_request

安全更新拉取请求：修改现有拉取请求的标题、描述或审查者，而不会丢失任何元数据。使用读-改-写模式来保留所有未明确更改的字段。

使用场景：

• 创建后修复 PR 标题或描述

• 添加或替换审查者而不丢失现有审查者

• 更新 PR 元数据而不影响批准状态

参数：

• project: Bitbucket 项目键（可选，如果未提供则使用 BITBUCKET_DEFAULT_PROJECT）

• repository (必需): 存储库 slug

• prId (必需): 要更新的拉取请求 ID

• title: 新标题（如果省略，则保留当前标题）

• description: 新描述（如果省略，则保留当前描述）

• reviewers: 作为用户名数组的新审查者列表（如果省略，则保留当前审查者）

get_pull_request

全面的 PR 信息：检索详细的拉取请求信息，包括状态、审查者、提交和所有元数据。对于在采取行动前了解 PR 状态至关重要。

使用场景：

• 检查 PR 批准状态

• 审查 PR 详细信息和进度

• 在合并前了解更改

• 监控 PR 状态

参数：

• project: Bitbucket 项目键（可选，如果未提供则使用 BITBUCKET_DEFAULT_PROJECT）

• repository (必需): 存储库 slug

• prId (必需): 拉取请求 ID

merge_pull_request

集成已批准的更改：将已批准的拉取请求合并到目标分支。支持根据您的工作流偏好选择不同的合并策略。

使用场景：

• 完成代码审查流程

• 集成已批准的功能

• 将错误修复应用到主分支

• 发布代码更改

参数：

• project: Bitbucket 项目键（可选，如果未提供则使用 BITBUCKET_DEFAULT_PROJECT）

• repository (必需): 存储库 slug

• prId (必需): 拉取请求 ID

• message: 自定义合并提交消息

• strategy: 合并策略：

  • merge-commit (默认): 创建保留历史记录的合并提交

  • squash: 将所有提交合并为一个

  • fast-forward: 移动分支指针而不创建合并提交

decline_pull_request

拒绝不合适的更改：拒绝不应合并的拉取请求，并向作者提供反馈。

使用场景：

• 拒绝不符合标准的更改

• 关闭与项目方向冲突的 PR

• 请求重大返工

• 防止不需要的代码集成

参数：

• project: Bitbucket 项目键（可选，如果未提供则使用 BITBUCKET_DEFAULT_PROJECT）

• repository (必需): 存储库 slug

• prId (必需): 拉取请求 ID

• message: 拒绝原因（有助于作者反馈）

add_comment

参与代码审查：向拉取请求添加评论以进行审查反馈、讨论和协作。支持线程化对话。

使用场景：

• 提供代码审查反馈

• 询问有关特定更改的问题

• 建议改进

• 参与技术讨论

• 记录审查决定

参数：

• project: Bitbucket 项目键（可选，如果未提供则使用 BITBUCKET_DEFAULT_PROJECT）

• repository (必需): 存储库 slug

• prId (必需): 拉取请求 ID

• text (必需): 评论内容（支持 Markdown）

• parentId: 用于线程化回复的父评论 ID

• state: 评论状态：OPEN（默认，立即发布）或 PENDING（草稿，仅在审查发布前对您可见）

get_diff

分析代码更改：检索代码差异，准确显示拉取请求中添加、删除或修改的内容。支持按文件截断以有效管理大型差异。

使用场景：

• 审查特定代码更改

• 了解修改范围

• 在合并前分析影响

• 检查实现细节

• 代码质量评估

• 处理大文件而不产生过多的输出

参数：

• project: Bitbucket 项目键（可选，如果未提供则使用 BITBUCKET_DEFAULT_PROJECT）

• repository (必需): 存储库 slug

• prId (必需): 拉取请求 ID

• contextLines: 更改周围的上下文行数（默认：10）

• maxLinesPerFile: 每个文件显示的最大行数（可选，如果未指定则使用 BITBUCKET_DIFF_MAX_LINES_PER_FILE 环境变量，设置为 0 表示无限制）

大文件处理： 当文件超过 maxLinesPerFile 限制时，它会显示：

• 文件头和元数据（始终保留）

• 从开头开始允许行数的 60%

• 带有文件统计信息的截断消息

• 从结尾开始允许行数的 40%

• 关于如何查看完整差异的清晰指示

get_reviews

跟踪审查进度：获取审查历史、批准状态和审查者反馈，以了解审查状态。

使用场景：

• 检查 PR 是否准备好合并

• 查看谁审查了更改

• 了解审查反馈

• 监控批准要求

• 跟踪审查进度

get_activities

检索拉取请求活动：获取拉取请求的完整活动时间线，包括评论、审查、提交和其他事件。

使用场景：

• 阅读评论讨论和反馈

• 审查完整的 PR 时间线

• 跟踪从 PR 添加/删除的提交

• 查看批准和审查历史

• 了解完整的 PR 生命周期

参数：

• project: Bitbucket 项目键（可选，如果未提供则使用 BITBUCKET_DEFAULT_PROJECT）

• repository (必需): 存储库 slug

• prId (必需): 拉取请求 ID

get_comments

仅提取 PR 评论：筛选拉取请求活动以仅返回评论，从而更容易专注于讨论内容，而无需审查或其他活动。

使用场景：

• 阅读 PR 讨论线程

• 提取反馈和问题

• 专注于评论内容而无干扰

• 分析对话流程

参数：

• project: Bitbucket 项目键（可选，如果未提供则使用 BITBUCKET_DEFAULT_PROJECT）

• repository (必需): 存储库 slug

• prId (必需): 拉取请求 ID

search

高级代码和文件搜索：使用 Bitbucket 搜索 API 在存储库中进行搜索，支持项目/存储库筛选和查询优化。同时搜索文件内容和文件名。注意：搜索仅适用于存储库的默认分支。

使用场景：

• 在项目中查找特定代码模式

• 按名称或内容定位文件

• 在特定项目或存储库中搜索

• 按文件扩展名筛选

参数：

• query (必需): 搜索查询字符串

• project: 用于限制搜索范围的 Bitbucket 项目键

• repository: 用于特定存储库搜索的存储库 slug

• type: 查询优化 - "file"（将查询用引号括起来以进行精确文件名匹配）或 "code"（默认搜索行为）

• limit: 返回的结果数量（默认：25，最大：100）

• start: 分页的起始索引（默认：0）

查询语法示例：

• "README.md" - 查找精确文件名

• config ext:yml - 在 YAML 文件中查找配置

• function project:MYPROJECT - 在特定项目中搜索 "function"

• bug fix repo:PROJ/my-repo - 在特定存储库中搜索

get_file_content

分页读取文件内容：通过分页检索存储库中特定文件的内容，支持大文件。

使用场景：

• 读取源代码文件

• 查看配置文件

• 提取文档内容

• 检查特定文件版本

参数：

• project: Bitbucket 项目键（可选，如果未提供则使用 BITBUCKET_DEFAULT_PROJECT）

• repository (必需): 存储库 slug

• filePath (必需): 存储库中的文件路径

• branch: 分支或提交哈希（可选，默认为 main/master）

• limit: 每个请求的最大行数（默认：100，最大：1000）

• start: 分页的起始行号（默认：0）

browse_repository

探索存储库结构：浏览存储库中的文件和目录，以了解项目组织并定位特定文件。

使用场景：

• 探索存储库结构

• 导航目录树

• 查找文件和文件夹

• 了解项目组织

参数：

• project: Bitbucket 项目键（可选，如果未提供则使用 BITBUCKET_DEFAULT_PROJECT）

• repository (必需): 存储库 slug

• path: 要浏览的目录路径（可选，默认为根目录）

• branch: 分支或提交哈希（可选，默认为 main/master）

• limit: 返回的最大项目数（默认：50）

list_pull_requests

发现并筛选拉取请求：列出存储库中的拉取请求，支持按状态、作者和方向筛选。返回 PR 元数据，包括标题、作者、分支、审查者和状态。

使用场景：

• 查找存储库中的打开 PR

• 列出您自己的拉取请求

• 查看等待审查的 PR

• 获取已合并或已拒绝 PR 的概览

• 监控项目中的 PR 活动

参数：

• project: Bitbucket 项目键（可选，如果未提供则使用 BITBUCKET_DEFAULT_PROJECT）

• repository (必需): 存储库 slug

• state: 按 PR 状态筛选 — OPEN（默认）、MERGED、DECLINED 或 ALL

• author: 按作者用户名筛选（精确匹配）

• direction: INCOMING（针对此存储库的 PR，默认）或 OUTGOING（来自此存储库的 PR）

• limit: 返回的 PR 数量（默认：25，最大：1000）

• start: 分页的起始索引（