用途
mcp-server-atlassian-bitbucket 是一个 Node.js/TypeScript 实现的 MCP（Model Context Protocol）服务器，用于将 AI 系统（LLM）连接到 Atlassian Bitbucket Cloud。通过标准 MCP 接口，AI 助手可以直接与工作区、仓库和拉取请求交互，把 AI 接入版本控制工作流。
主要能力
该服务器提供 6 个通用工具，可访问任意 Bitbucket API 端点。所有 API 工具支持以下通用参数：
- path（必填）：以 / 开头的 API 端点路径，系统会自动添加 /2.0 前缀。
- queryParams（可选）：查询参数的键值对，例如 {"pagelen": "25", "page": "2"}。
- jq（可选）：JMESPath 表达式，用于过滤或转换响应，强烈建议使用以减少 token 消耗。
- outputFormat（可选）："toon"（默认，比 JSON 减少 30-60% token）或 "json"。
- body（POST/PUT/PATCH 必填）：JSON 对象形式的请求体。
常见 API 路径覆盖工作区与仓库（列出工作区、列出仓库、获取仓库详情、列出分支、获取/删除分支、列出提交、获取提交详情、获取文件内容）、拉取请求（列出或创建 PR、获取/更新/删除 PR、获取 PR diff、列出/添加 PR 评论、批准或移除批准、请求更改、合并 PR、拒绝 PR、比较分支或提交），以及其他资源（issues、downloads、pipelines、deployments）。
使用方式
环境要求：Node.js 18.0.0 或更高版本；Bitbucket Cloud 账户（不支持 Bitbucket Server/Data Center）；认证凭据（推荐 Scoped API Token，或旧版 App Password）。
获取凭据：
推荐使用 Scoped API Token：前往 Atlassian API Tokens，点击 "Create API token with scopes"，选择 "Bitbucket" 产品，选择适当范围（只读：repository、workspace；完整功能：repository、workspace、pullrequest），复制生成的 token（以 ATATT 开头），配合 Atlassian 邮箱作为用户名使用。
旧版 App Password：前往 Bitbucket App Passwords，创建 app password，选择权限（Workspaces: Read；Repositories: Read，如需 AI 创建 PR/评论则加 Write；Pull Requests: Read，如需 PR 管理则加 Write）。注意 App Password 将于 2026 年 6 月前弃用。
连接 AI 助手：
Claude Desktop 用户：在配置文件 ~/.claude/claude_desktop_config.json 中添加配置（可选 Scoped API Token 或旧版 App Password），重启 Claude Desktop 后状态栏会显示 bitbucket 服务器。
其他 AI 助手：多数支持 MCP。方式一（推荐，始终最新版本）：配置 AI 助手运行 npx -y @aashari/mcp-server-atlassian-bitbucket。方式二：全局安装后配置 AI 助手使用 STDIO 传输的 MCP 服务器。支持的 AI 助手包括 Claude Desktop（官方支持）及任何兼容 MCP 的客户端。
替代配置：创建 ~/.mcp/configs.json 进行系统级配置。配置键也接受 "atlassian-bitbucket"、"@aashari/mcp-server-atlassian-bitbucket" 或 "mcp-server-atlassian-bitbucket"。
CLI 使用：CLI 镜像 MCP 工具，可直接在终端访问，所有命令返回 JSON 输出（非 TOON，TOON 仅用于 MCP 模式）。可用命令包括 get、delete（需 -p/--path 必填，-q/--query-params 可选，--jq 可选）、post、put、patch（需 -b/--body 必填）、clone（--workspace-slug 可选，--repo-slug 必填，--target-path 必填）。
调试：设置 DEBUG 环境变量查看详细日志。MCP 模式下日志写入 ~/.mcp/data/@aashari-mcp-server-atlassian-bitbucket.[session-id].log。可运行 HTTP 模式配合 MCP Inspector 进行交互式调试。
适用场景
- 开发者希望获得 AI 辅助进行代码审查和仓库管理。
- 团队负责人需要快速了解项目状态和拉取请求活动。
- DevOps 工程师自动化仓库工作流和分支管理。
- 任何希望通过自然语言与 Bitbucket 交互的人。
典型示例：询问 AI "列出我主工作区的所有仓库"、"显示所有需要审查的开放拉取请求"、"查找所有使用认证函数的 JavaScript 文件"、"比较我的功能分支和主分支"、"为我的新功能分支创建 PR"、"向 PR #123 添加测试结果评论"。
限制
- 仅支持 Bitbucket Cloud，不支持 Bitbucket Server/Data Center。
- 需要 Node.js 18.0.0 或更高版本。
- 需要有效的 Bitbucket 认证凭据。
- Bitbucket App Password 将于 2026 年 6 月前弃用，建议使用 Scoped API Token。
- Bitbucket Cloud 存在速率限制，建议使用过滤减少调用。
- 未过滤的 API 响应可能非常大，token 成本高，建议始终使用 JMESPath 过滤。
成本优化建议
- 始终使用 JMESPath 过滤，仅提取所需字段。
- 合理使用分页，设置 pagelen 查询参数限制结果。
- 先探索 schema，获取一个无过滤项查看可用字段，再过滤后续调用。
- 利用 TOON 格式，默认比 JSON 节省 30-60% token。
- 使用 Bitbucket 的 q 参数进行服务端过滤。
- 处理大响应时使用稀疏字段集（fields 参数）、分页、服务端过滤和 JQ 后处理。
