比特桶服务器-MCP服务器

Name: 比特桶服务器-MCP服务器
Author: garc33

作者：garc3345 星标更新：2025-10-10

安装使用来源：spider==github.com

项目介绍

Bitbucket Server MCP

MCP（模型上下文协议）服务器用于管理Bitbucket Server的拉取请求。此服务器提供了通过MCP协议与Bitbucket Server API交互的工具和资源。

✨ 新功能

🔍 高级搜索：使用 search 工具在项目/仓库过滤条件下跨仓库搜索代码和文件
📄 文件操作：使用 get_file_content 和 browse_repository 工具读取文件内容并浏览仓库目录
💬 评论管理：使用 get_comments 工具提取和过滤PR评论
🔍 项目发现：使用 list_projects 列出所有可访问的Bitbucket项目
📁 仓库浏览：使用 list_repositories 在项目之间浏览仓库
🔧 灵活的项目支持：默认项目可选——按命令指定或使用 BITBUCKET_DEFAULT_PROJECT
📖 增强的文档：改进了包含使用示例和更好的配置指导的README

要求

Node.js >= 16

安装

通过 Smithery 安装

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

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：审阅者用户名数组

`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用于线程回复

`get_diff`

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

用例：

审查特定代码更改
了解修改范围
在合并前分析影响
检查实现细节
代码质量评估
处理大型文件而不会产生过多输出

参数：

project：Bitbucket项目键（可选，未提供时使用 BITBUCKET_DEFAULT_PROJECT）
repository（必需）：仓库slug
prId（必需）：拉取请求ID
contextLines：更改周围的上下文行数（默认：10）
maxLinesPerFile：每个文件的最大行数（可选，未指定时使用 BITBUCKET_DIFF_MAX_LINES_PER_FILE 环境变量，设置为0表示无限制）

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

文件头和元数据（始终保留）
开始处允许行数的前60%
截断消息及文件统计
结束处允许行数的后40%
如何查看完整diff的明确指示

`get_reviews`

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

用例：

检查PR是否准备好合并
查看谁已经审查过更改
了解审查反馈
监控审批要求
跟踪审查进度

`get_activities`

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

用例：

阅读评论讨论和反馈
审查完整的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文件中的config
function project:MYPROJECT - 在特定项目中搜索"function"
bug fix repo:PROJ/my-repo - 在特定仓库中搜索

`get_file_content`

分页读取文件内容：从仓库中检索特定文件的内容，支持通过分页处理大型文件。

用例：

阅读源代码文件
查看配置文件
提取文档内容
检查特定文件版本

参数：

project：Bitbucket项目键（可选，未提供时使用 BITBUCKET_DEFAULT_PROJECT）
repository（必需）：仓库slug
filePath（必需）：仓库中的文件路径
branch：分支或提交哈希（可选，默认为主/主分支）
limit：每次请求的最大行数（默认：100，最大：1000）
start：分页起始行号（默认：0）

`browse_repository`

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

用例：

浏览仓库结构
导航目录树
查找文件和文件夹
了解项目组织

参数：

project：Bitbucket项目键（可选，未提供时使用 BITBUCKET_DEFAULT_PROJECT）
repository（必需）：仓库slug
path：要浏览的目录路径（可选，默认为根目录）
branch：分支或提交哈希（可选，默认为主/主分支）
limit：返回的最大项数（默认：50）

使用示例

列出项目和仓库

# 列出所有可访问项目
list_projects

# 列出默认项目中的仓库（如果设置了 BITBUCKET_DEFAULT_PROJECT）
list_repositories

# 列出特定项目中的仓库
list_repositories --project "MYPROJECT"

# 使用分页列出项目
list_projects --limit 10 --start 0

搜索和文件操作

# 跨所有项目搜索README文件
search --query "README" --type "file" --limit 10

# 在项目中搜索特定代码模式
search --query "function getUserData" --type "code" --project "MYPROJECT"

# 使用文件扩展名过滤搜索
search --query "config ext:yml" --project "MYPROJECT"

# 浏览仓库结构
browse_repository --project "MYPROJECT" --repository "my-repo"

# 浏览特定目录
browse_repository --project "MYPROJECT" --repository "my-repo" --path "src/components"

# 读取文件内容
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "package.json" --limit 20

# 从大型文件中读取特定行
get_file_content --project "MYPROJECT" --repository "my-repo" --filePath "docs/CHANGELOG.md" --start 100 --limit 50

操作拉取请求

# 创建拉取请求（使用默认项目）
create_pull_request --repository "my-repo" --title "Feature: 新功能" --sourceBranch "feature/new-feature" --targetBranch "main"

# 在特定项目中创建拉取请求
create_pull_request --project "MYPROJECT" --repository "my-repo" --title "Bugfix: 严重问题" --sourceBranch "bugfix/critical" --targetBranch "develop" --description "修复严重问题 #123"

# 获取拉取请求详情
get_pull_request --repository "my-repo" --prId 123

# 仅获取PR评论（无审查/提交）
get_comments --project "MYPROJECT" --repository "my-repo" --prId 123

# 获取完整的PR活动时间线
get_activities --repository "my-repo" --prId 123

# 使用squash策略合并拉取请求
merge_pull_request --repository "my-repo" --prId 123 --strategy "squash" --message "Feature: 新功能 (#123)"

依赖项

@modelcontextprotocol/sdk - MCP协议实现的SDK
axios - API请求的HTTP客户端
winston - 日志框架

配置

服务器需要在VSCode MCP设置文件中进行配置。这里是一个示例配置：

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/path/to/bitbucket-server/build/index.js"],
      "env": {
        "BITBUCKET_URL": "https://your-bitbucket-server.com",
        // 认证（选择一种）：
        // 选项1：个人访问令牌
        "BITBUCKET_TOKEN": "your-access-token",
        // 选项2：用户名/密码
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_PASSWORD": "your-password",
        // 可选：默认项目
        "BITBUCKET_DEFAULT_PROJECT": "your-default-project"
      }
    }
  }
}

环境变量

BITBUCKET_URL（必需）：您的Bitbucket Server实例的基本URL
认证（必须提供以下之一）：
- BITBUCKET_TOKEN：个人访问令牌
- BITBUCKET_USERNAME 和 BITBUCKET_PASSWORD：基本认证凭据
BITBUCKET_DEFAULT_PROJECT（可选）：未在工具调用中指定时使用的默认项目键
BITBUCKET_DIFF_MAX_LINES_PER_FILE（可选）：diff中每个文件的默认最大行数。设置以防止大型文件产生过多输出。可以在 get_diff 调用中通过 maxLinesPerFile 参数覆盖。
BITBUCKET_READ_ONLY（可选）：设置为 true 启用只读模式

注意：有了新的可选项目支持，现在可以：

设置 BITBUCKET_DEFAULT_PROJECT 以默认情况下与特定项目一起工作
使用 list_projects 发现可用项目
使用 list_repositories 跨项目浏览仓库
通过在任何工具调用中指定 project 参数来覆盖默认项目

只读模式

服务器支持只读模式，适用于您希望防止对Bitbucket仓库进行任何修改的部署。启用后，只有安全的非修改操作可用。

启用只读模式：设置环境变量 BITBUCKET_READ_ONLY=true

只读模式下的可用工具：

list_projects - 浏览和列出项目
list_repositories - 浏览和列出仓库
get_pull_request - 查看拉取请求详情
get_diff - 查看代码更改和diff
get_reviews - 查看审查历史和状态
get_activities - 查看拉取请求时间线
get_comments - 查看拉取请求评论
search - 跨仓库搜索代码和文件
get_file_content - 读取文件内容
browse_repository - 浏览仓库结构

只读模式下禁用的工具：

create_pull_request - 创建新的拉取请求
merge_pull_request - 合并拉取请求
decline_pull_request - 拒绝拉取请求
add_comment - 向拉取请求添加评论

行为：

当 BITBUCKET_READ_ONLY 未设置或设置为任何非 true 的值时，所有工具正常运行（向后兼容）
当 BITBUCKET_READ_ONLY=true 时，写入操作被过滤掉，如果调用则返回错误