bitbucket-mcp-server

@droplinkperformance/bitbucket-mcp-server

面向 AI 代码审查、与提供商无关的 Model Context Protocol（MCP）服务，适用于 Bitbucket Cloud。

此服务的主要价值在于 AI 驱动的代码审查和拉取请求分析，而非对 Bitbucket API 执行 CRUD 操作。所有主要依赖项（SCM 访问、缓存、令牌存储、速率限制、LLM、事件）都封装在与提供商无关的接口之后，因此相同的业务逻辑日后可在不更改用例、Agent 或领域契约的情况下支持 GitHub / GitLab / Azure DevOps 和 OpenAI / Anthropic / Gemini / Bedrock。

状态：Phase 1。请参阅路线图。

功能（Phase 1）

• 双传输方式：stdio（Cursor / Claude Desktop）和 Streamable HTTP（Node http，用于远程/生产环境）。
• 通过 ToolRegistry 自动发现工具，无需手动注册。
• 每个工具都显式使用 BitbucketContext（workspace + 可选的 repository），支持多工作区。
• 弹性 BitbucketClient：注入身份验证、自动分页、重试/退避、速率限制处理、缓存、密钥屏蔽。
• 两种身份验证策略：OAuth 2.0（授权码模式，并持久化轮换的刷新令牌）和 Bearer 令牌。
• AI 代码审查（analyze_pull_request）由 CodeReviewAgent 提供支持，可将大型 PR 分块处理并返回标准 ReviewResult。
• 可插拔的 LLM 提供商（OpenAI / Anthropic / Gemini / Bedrock）、缓存（内存 / Redis）和 令牌存储（文件 / 内存 / Redis）。

工具

工具	描述
get_current_user	已通过身份验证的用户。
list_pull_requests	列出 PR（按状态/查询筛选）。
get_pull_request	按 ID 获取 PR。
create_pull_request	创建 PR。
update_pull_request	编辑开放状态 PR 的标题和/或描述。
get_pull_request_diff	原始统一差异。
get_pull_request_files	已更改的文件和行数统计。
get_pull_request_comments	PR 评论。
comment_pull_request	添加评论（可选择行内评论）。
analyze_pull_request	AI 审查，返回标准 ReviewResult。

所有工具输入都接受 workspace（如果设置了 BITBUCKET_DEFAULT_WORKSPACE，则为可选），并在适用时接受 repository。

架构

src/
  index.ts            entry: chooses transport
  container.ts        composition root (the only place wiring concretes)
  mcp/                McpServer + ToolRegistry (auto-discovery) + transports
  tools/              thin MCP adapters (*.tool.ts) -> call exactly one use-case
  application/        use-cases (CQRS-ish: command|query) with Input/Output DTOs
  agents/             autonomous workflows implementing Agent<TInput,TOutput>
  domain/             provider-agnostic types, repository contracts, ReviewResult
  repositories/bitbucket/  Bitbucket implementations of the contracts
  clients/bitbucket/  resilient REST client
  auth/               AuthProvider (+ token/oauth) and TokenStore implementations
  cache/              CacheProvider (+ memory/redis)
  ratelimit/          RateLimitStrategy (+ bitbucket)
  llm/                LlmProvider (+ openai/anthropic/gemini/bedrock)
  events/             EventBus (+ in-memory)
  services/           reusable services (masking, chunking)
  telemetry/          OpenTelemetry bootstrap + metrics
  infrastructure/     config, logger, http, attachments
  shared/             errors, result envelope, http-status, BitbucketContext

流程：tool -> use-case -> (agent | repository contract) -> repositories/bitbucket -> BitbucketClient。Agent 还可以使用 LlmProvider 和 EventBus。工具不包含业务逻辑。

要求

• Node.js 23+

安装

已发布为 @droplinkperformance/bitbucket-mcp-server。

npx -y @droplinkperformance/bitbucket-mcp-server

从源代码安装：

npm install
npm run build

发布

合并到 main 后会运行 .github/workflows/release.yml：测试、构建，然后运行 semantic-release。只有合并内容包含 Conventional Commits 时才会更新版本并发布到 npm：

提交	版本更新
fix:	patch
feat:	minor
BREAKING CHANGE / feat!:	major

其他提交信息不会触发发布。需要 GitHub 密钥 NPM_TOKEN（droplinkperformance 组织的 npm Automation 令牌）。

npm 发布成功后，同一工作流会等待该版本在 npm 注册表中可见，然后以 io.github.droplinkperformance/bitbucket-mcp-server 的名称将元数据发布到 MCP 注册表（OIDC，无需额外密钥）。如需为当前 package.json 版本重新发布 MCP 元数据而不创建新版本，请手动运行工作流并选择 仅发布 MCP。github.com/mcp 会从该注册表同步；如果看不到此服务，请发送邮件至 [email protected]。

为了让首次发布保持在 0.x，请在首次 Conventional Commits 合并前为当前提交打标签（git tag v0.1.0 && git push origin v0.1.0）；否则 semantic-release 会从 1.0.0 开始。

配置

将 .env.example 复制为 .env 并填写相应值。使用 Node 内置标志加载：

node --env-file=.env dist/index.js

关键变量：

变量	默认值	说明
MCP_TRANSPORT	stdio	stdio 或 http。
HTTP_HOST / HTTP_PORT	0.0.0.0 / 3000	HTTP 传输绑定地址。
BITBUCKET_DEFAULT_WORKSPACE	–	工具未提供 workspace 时使用的备用值。
BITBUCKET_ACCESS_TOKEN	–	API 令牌（ATATT…）、应用密码或 OAuth 访问令牌
BITBUCKET_EMAIL	–	使用 API 令牌（ATATT…）时必填——你的 Atlassian 账户邮箱
BITBUCKET_CLIENT_ID / BITBUCKET_CLIENT_SECRET	–	使用 OAuth（未提供访问令牌时）必填。
BITBUCKET_REFRESH_TOKEN	–	用于无头 OAuth 的可选种子值。
TOKEN_STORE	file	file | memory | redis。
CACHE_PROVIDER	memory	memory | redis。
LLM_PROVIDER	openai	openai | anthropic | gemini | bedrock。
MAX_FILES_PER_CHUNK / MAX_DIFF_LINES_PER_CHUNK	50 / 5000	大型 PR 的分块阈值。
OTEL_ENABLED	false	未启用时使用空操作指标。

身份验证

Bearer（OAuth 访问令牌）： 仅设置 BITBUCKET_ACCESS_TOKEN（非 ATATT 令牌）。

API 令牌（推荐，ATATT…）： 设置 BITBUCKET_ACCESS_TOKEN 和 BITBUCKET_EMAIL（你的 Atlassian 账户邮箱，可在 Bitbucket → 个人设置 → 邮箱别名中找到）。API 令牌使用 HTTP Basic 身份验证，而非 Bearer。

应用密码（旧版，支持至 2026 年 6 月）： 设置 BITBUCKET_ACCESS_TOKEN 和 BITBUCKET_USERNAME（你的 Bitbucket 用户名）。

OAuth 2.0（授权码）： 设置 BITBUCKET_CLIENT_ID / BITBUCKET_CLIENT_SECRET。令牌会持久化到配置的 TOKEN_STORE；Bitbucket 会轮换刷新令牌，服务会在每次刷新时持久化新令牌。若要无头启动，请提供先前获取的 BITBUCKET_REFRESH_TOKEN。

使用的 Bitbucket OAuth 端点：授权 https://bitbucket.org/site/oauth2/authorize，令牌 https://bitbucket.org/site/oauth2/access_token。可以使用 OAuthProvider.buildAuthorizeUrl() 构建授权 URL，并通过 OAuthProvider.loginWithCode(code) 交换返回的 ?code=。

大模型提供方

设置 LLM_PROVIDER 和相应的密钥：

LLM_PROVIDER=openai      # OPENAI_API_KEY
LLM_PROVIDER=anthropic   # ANTHROPIC_API_KEY
LLM_PROVIDER=gemini      # GEMINI_API_KEY
LLM_PROVIDER=bedrock     # AWS creds + BEDROCK_MODEL_ID (needs @aws-sdk/client-bedrock-runtime)

ioredis（Redis 提供方）和 @aws-sdk/client-bedrock-runtime（Bedrock）均为可选依赖，且会延迟加载——仅在选择相应提供方时需要。

运行

stdio

MCP_TRANSPORT=stdio node --env-file=.env dist/index.js

可流式 HTTP

MCP_TRANSPORT=http HTTP_PORT=3000 node --env-file=.env dist/index.js
# health:   GET  http://localhost:3000/health
# endpoint: POST http://localhost:3000/mcp

MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Cursor

~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@droplinkperformance/bitbucket-mcp-server"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "BITBUCKET_ACCESS_TOKEN": "ATATT-your-api-token",
        "BITBUCKET_EMAIL": "[email protected]",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace",
        "LLM_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Claude Desktop

claude_desktop_config.json：

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": ["-y", "@droplinkperformance/bitbucket-mcp-server"],
      "env": {
        "BITBUCKET_ACCESS_TOKEN": "your-token",
        "BITBUCKET_DEFAULT_WORKSPACE": "your-workspace",
        "LLM_PROVIDER": "anthropic",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

开发

npm run dev          # tsx watch (stdio)
npm run typecheck
npm run lint
npm test
npm run test:coverage

路线图

• 阶段 1（此版本）： 身份验证、抽象层、BitbucketClient、工具自动发现、PR 工具、analyze_pull_request。
• 阶段 2： Pipelines + 完整文本分页日志、pipeline-investigator Agent、auto_review_pull_request（试运行 / 发布行内评论）。
• 阶段 3： 其余 CRUD——仓库、提交、分支、标签、问题、工作区、成员、搜索。
• 阶段 4： analyze_dotnet_pull_request（dotnet-review Agent）、高级 Agent、自动化工作流。
• 阶段 5： Docker、Compose、Helm、生产部署指南。

许可证

MIT