Name: Bitbucket服务器协议服务
Author: diomonogatari

使用说明

MCP服务器损坏

Atlassian Bitbucket server（Stash）的模型上下文协议（MCP）服务器，作为Docker镜像发布在 Docker 中心。它让人工智能助手通过41个专门构建的工具访问您的存储库、拉取请求、代码审查、构建和搜索。

特性

41工具 涵盖全面的Bitbucket服务器工作流程：

类别	工具	亮点
项目	1	发现项目
仪表盘	5	以用户为中心的PR视图+服务器信息
仓库	3	转发、概述、文件内容
Git	3	分支、标签、文件列表
搜索	4	代码、提交、PR、用户
历史	5	列出/检查提交、比较引用、完整提交上下文
拉取请求	8	列表/获取/上下文/差异+创建/更新/合并+批准
评论	4	读、写、用代码上下文回复
任务	4	用于审核任务的完整CRUD
构建	3	每次提交/PR/回购的CI/CD状态
集成	1	Jira问题链接

工作流优化工具

这些工具将多个API调用减少为单个调用：

get_pull_request_context --完成公关，包括评论、任务、差异、活动
get_repository_overview --一次调用中包含分支、标签和打开的PR
get_commit_context --提交带有更改和差异的细节

韧性

断路器 --防止Bitbucket不可用时发生级联故障
使用回退重试 --暂时错误的自动重试（429502503504）
故障弱化 -当API失败时返回缓存的数据
响应截断 --50KB限制可防止上下文溢出
缓存失效 --写入操作会自动刷新相关缓存

入门指南

先决条件

Docker 桌面版已安装
Bitbucket服务器（自托管）实例
具有存储库读/写权限的个人访问令牌

VS代码/副本——MCP配置

将以下内容添加到VS Code MCP配置文件中（命令选项板→ MCP: Open user configuration):

{
  "servers": {
    "stash-bitbucket": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BITBUCKET_URL",
        "-e", "BITBUCKET_TOKEN",
        "diomonogatari/stash-mcp:latest"
      ],
      "env": {
        "BITBUCKET_URL": "https://your-stash-server.com/",
        "BITBUCKET_TOKEN": "your_personal_access_token"
      },
      "type": "stdio"
    }
  }
}

就是这样。VS Code将在首次使用时提取图像并自动启动服务器。

提示--固定到特定标签 而不是 latest （例如。 diomonogatari/stash-mcp:1.1.0) 以避免在发布新版本时运行过时的本地映像。当本地镜像已经具有 latest 标签。如果你必须使用 latest，用力拉 docker run --pull=always ... diomonogatari/stash-mcp:latest.

与Claude Desktop一起使用

打开 设置→ 开发者→ 编辑配置 （或编辑 claude_desktop_config.json 直接）并在下面添加服务器 mcpServers 按键：

{
  "mcpServers": {
    "stash-bitbucket": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BITBUCKET_URL",
        "-e", "BITBUCKET_TOKEN",
        "diomonogatari/stash-mcp:latest"
      ],
      "env": {
        "BITBUCKET_URL": "https://your-stash-server.com/",
        "BITBUCKET_TOKEN": "your_personal_access_token"
      }
    }
  }
}

配置文件位置：

操作系统	路径
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
窗户	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

保存后退出并重新启动Claude Desktop。Bitbucket工具出现在工具（滑块）图标。Docker桌面必须正在运行。

注： Claude Desktop使用 mcpServers 密钥（和否 "type" 字段），而上面的VS代码示例使用 servers 钥匙。这 command 和 args 完全相同。

与Claude Code一起使用

claude mcp add stash-bitbucket \
  --transport stdio \
  --env BITBUCKET_URL=https://your-stash-server.com/ \
  --env BITBUCKET_TOKEN=your_personal_access_token \
  -- docker run -i --rm -e BITBUCKET_URL -e BITBUCKET_TOKEN diomonogatari/stash-mcp:latest

这将在以下位置注册服务器本地范围（当前项目，只有你）。使用 --scope user 使其可用于您的所有项目，或 --scope project 将其提交给共享 .mcp.json.验证 claude mcp list 或 /mcp 会话内的命令（它应该报告 stash-bitbucket 与41连接工具），并用 claude mcp remove stash-bitbucket.

高级配置

传递其他环境变量以调整弹性和缓存行为：

{
  "servers": {
    "stash-bitbucket": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "BITBUCKET_URL",
        "-e", "BITBUCKET_TOKEN",
        "-e", "BITBUCKET_RETRY_COUNT",
        "-e", "BITBUCKET_CIRCUIT_TIMEOUT",
        "-e", "BITBUCKET_CACHE_TTL_SECONDS",
        "-e", "BITBUCKET_READ_ONLY_MODE",
        "-e", "BITBUCKET_PROJECTS",
        "diomonogatari/stash-mcp:latest"
      ],
      "env": {
        "BITBUCKET_URL": "https://your-stash-server.com/",
        "BITBUCKET_TOKEN": "your_personal_access_token",
        "BITBUCKET_RETRY_COUNT": "5",
        "BITBUCKET_CIRCUIT_TIMEOUT": "60",
        "BITBUCKET_CACHE_TTL_SECONDS": "120",
        "BITBUCKET_READ_ONLY_MODE": "false",
        "BITBUCKET_PROJECTS": "PROJ,TEAM"
      },
      "type": "stdio"
    }
  }
}

配置参考

设置	环境变量	默认值	说明
服务器URL	`BITBUCKET_URL`	--	比特桶服务器基本URL(必需的)
访问令牌	`BITBUCKET_TOKEN`	--	个人访问令牌(必需的)
重试计数	`BITBUCKET_RETRY_COUNT`	3	最大重试次数（0-10）
电路超时	`BITBUCKET_CIRCUIT_TIMEOUT`	30	断路器持续时间（秒）（5–300）
缓存TTL	`BITBUCKET_CACHE_TTL_SECONDS`	60	缓存生存时间（秒）（10–600）
只读模式	`BITBUCKET_READ_ONLY_MODE`	false	禁用写入操作(`true` 或 `1`)
项目	`BITBUCKET_PROJECTS`	--	启动时缓存逗号分隔的项目密钥（例如。 `PROJ,TEAM`).如果省略，则从最近的存储库中派生范围。

工具参考

有关所有41个工具的详细文档，请参阅 docs/TOOLSET.md.

常见工作流

代码审查

1. get_pull_request_context (with includeComments=true, includeDiff=true)
2. Review the diff and existing comments
3. add_pull_request_comment (for feedback)
4. create_pull_request_task (for required changes)
5. approve_pull_request (when satisfied)

Bug调查

1. search_commits (messageContains="JIRA-123")
2. get_commit_context (includeDiff=true)
3. search_code (to find current implementation)

存储库探索

1. get_repository_overview (quick overview)
2. list_files (browse structure)
3. get_file_content (read specific files)

输出优化

对于列表操作，请使用 minimalOutput=true 为了减小响应大小：

list_repositories --仅返回存储库蛞蝓
list_branches --仅返回分支名称
list_pull_requests --返回精简的PR摘要

贡献

设置

克隆存储库 带有子模块:

git clone --recurse-submodules https://github.com/diomonogatari/stash-mcp.git

如果你已经克隆了，没有子模块：

git submodule update --init --recursive

安装 .NET 10.0 SDK

建筑

# Build the solution
dotnet build stash-mcp.slnx

# Run tests
dotnet test stash-mcp.slnx

本地运行

dotnet run --project src/StashMcpServer/StashMcpServer.csproj -- \
  --stash-url https://your-server.com/ --pat your_pat

双人冲刺(--)分开 dotnet run 从应用程序参数中提取参数。

CLI标志

标志	默认值	描述
`--stash-url`	`BITBUCKET_URL` env var	比特桶服务器基本URL
`--pat`	`BITBUCKET_TOKEN` env-var	个人访问令牌
`--log-level`	`Information`	日志级别： `Verbose`, `Debug`, `Information`, `Warning`, `Error`, `Fatal`

构建Docker镜像

docker build -t diomonogatari/stash-mcp:dev .
docker run -i --rm \
  -e BITBUCKET_URL=https://your-stash-server.com/ \
  -e BITBUCKET_TOKEN=your_personal_access_token \
  diomonogatari/stash-mcp:dev

故障排除

Docker镜像未更新

Docker在以下情况下跳过pull latest 标记已在本地存在。强制进行新的拉动：

docker pull diomonogatari/stash-mcp:latest

或固定到特定的版本标签（例如。 diomonogatari/stash-mcp:1.1.0).

连接被拒绝/超时

验证 BITBUCKET_URL 包括尾随斜线和协议 (https://your-server.com/)
确保Docker容器可以访问您的Bitbucket服务器（检查公司VPN、代理或防火墙规则）
对于macOS/Windows上的Docker桌面，请使用 host.docker.internal 如果 Bitbucket在主机上运行

权限错误（401/403）

验证个人访问令牌是否具有 存储库读取 （以及 存储库写入 如果你需要写操作）权限
检查令牌是否未过期
集 BITBUCKET_READ_ONLY_MODE=true 如果只需要读取权限

服务器启动后无响应

提高日志级别以查看发生了什么： --log-level Debug （CLI）或附加 --log-level Debug 在图像之后姓名在 docker run 命令
检查 BITBUCKET_PROJECTS 变量（如果设置）包含有效的项目密钥--无效的密钥会导致启动缓存失败默默地

建筑

┌──────────────────────────────────────────────────────────┐
│                      MCP Server Layer                    │
│  ┌──────────────────────────────────────────────────┐    │
│  │ Domain Tool Classes (9 classes, 41 tools)        │    │
│  │  ProjectTools  RepositoryTools  PullRequestTools │    │
│  │  SearchTools   GitTools   HistoryTools           │    │
│  │  BuildTools    DashboardTools  IntegrationTools  │    │
│  └──────────┬───────────────────────────────────────┘    │
│             │ inherits ToolBase (shared helpers)         │
│  ┌──────────▼───────────────────────────────────────┐    │
│  │ Formatting  │ DiffFormatter  ResponseTruncation  │    │
│  │             │ MinimalOutputFormatter (50KB limit)│    │
│  └──────────┬───────────────────────────────────────┘    │
│             │                                            │
│  ┌──────────▼───────────────────────────────────────┐    │
│  │           ResilientApiService                    │    │
│  │  • Circuit Breaker (Polly)                       │    │
│  │  • Retry with Exponential Backoff                │    │
│  │  • Graceful Degradation (stale cache)            │    │
│  │  • Cache Invalidation on Writes                  │    │
│  └──────────┬───────────────────────────────────────┘    │
│             │                                            │
│  ┌──────────▼──────┐ ┌──────────────────────────────┐    │
│  │ Cache Layer      │ │ IMemoryCache (TTL=60s)      │    │
│  │ (Static)         │ │ ConcurrentDict (projects)   │    │
│  └──────────┬──────┘ └──────────────────────────────┘    │
│             │                                            │
│  Transport: stdio                                        │
└─────────────┼────────────────────────────────────────────┘
              │
              ▼
       Bitbucket Server API (via Bitbucket.Net submodule)

有关详细的体系结构文档，请参阅 docs/ARCHITECTURE.md.

安全

切勿将您的个人访问令牌提交给源代码管理。

使用环境变量（如上面的配置示例所示）
将PAT权限限制在所需的最小范围内
在可用的情况下使用安全的凭据存储

文档

建筑 --系统设计和文件夹结构
工具参考 --所有41个工具的详细文档
本地Bitbucket --在Docker中运行一个真正的Bitbucket服务器进行端到端测试
贡献 --开发设置和拉取请求指南
安全 --漏洞报告和凭证安全
更新日志 --版本历史和发行说明

明星历史

许可证

看许可证了解详情。