@droplinkperformance/bitbucket-mcp-server

面向 Bitbucket Cloud 的、与提供商无关的、以 AI 审查优先的 Model Context Protocol（MCP）服务器。

该服务器的核心价值是AI 驱动的代码审查和拉取请求分析，而非针对 Bitbucket API 的 CRUD 操作。每个主要依赖（SCM 访问、缓存、令牌存储、速率限制、LLM、事件）都隐藏在提供商无关的接口之后，因此相同的业务逻辑未来可以无需修改用例、代理或领域契约即可适配 GitHub / GitLab / Azure DevOps 以及 OpenAI / Anthropic / Gemini / Bedrock。

状态：第一阶段。参见路线图。

功能特性（第一阶段）

• 双传输方式：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）。

工具

所有工具输入均接受 workspace（如果设置了 BITBUCKET_DEFAULT_WORKSPACE 则可选）以及（适用时）repository。

Related MCP server: Atlassian Bitbucket MCP Server

架构

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。代理也可以使用 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 发布：

其他消息则跳过发布。需要 GitHub 密钥 NPM_TOKEN（droplinkperformance 组织的 npm Automation 令牌）。

npm 发布成功后，同一工作流会将元数据发布到 MCP Registry，标识为 io.github.droplinkperformance/bitbucket-mcp-server（使用 OIDC，无需额外密钥）。github.com/mcp 会从该注册表同步；如果服务器未出现，请发送邮件至 partnerships@github.com。

为了在首次发布时保持 0.x 版本，请在第一次常规合并之前为当前提交打标签（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

关键变量：

认证

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。授权 URL 可通过 OAuthProvider.buildAuthorizeUrl() 构建，返回的 ?code= 可通过 OAuthProvider.loginWithCode(code) 进行交换。

LLM 提供商

设置 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

Streamable 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": "you@company.com",
        "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

路线图

• 第一阶段（本版本）： 认证、抽象层、BitbucketClient、工具自动发现、PR 工具、analyze_pull_request。

• 第二阶段： Pipelines + 全文分页日志、pipeline-investigator 代理、auto_review_pull_request（试运行 / 发布内联评论）。

• 第三阶段： 其余 CRUD — 仓库、提交、分支、标签、问题、工作区、成员、搜索。

• 第四阶段： analyze_dotnet_pull_request（dotnet-review 代理）、高级代理、自动化工作流。

• 第五阶段： Docker、Compose、Helm、生产部署指南。

许可证

MIT