@droplinkperformance/bitbucket-mcp-server

プロバイダ非依存・AIレビュー優先のModel Context Protocol（MCP）サーバー（Bitbucket Cloud 向け）。

このサーバーの主な価値は、Bitbucket API に対する CRUD ではなく、AI によるコードレビューとプルリクエスト分析です。主要な依存関係（SCM アクセス、キャッシュ、トークン保存、レート制限、LLM、イベント）はすべてプロバイダ非依存のインターフェースの背後に隠されており、同じビジネスロジックを後日 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: 認証インジェクション、自動ページネーション、リトライ/バックオフ、レート制限処理、キャッシュ、シークレットマスキング。

• 2 つの認証戦略: OAuth 2.0（認可コード、ローテーションするリフレッシュトークンの永続化付き）と Bearer トークン。

• 大規模な PR をチャンクに分割し、標準の ReviewResult を返す CodeReviewAgent によるAI コードレビュー（analyze_pull_request）。

• プラグイン可能な 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。バージョンと npm 公開は、マージに Conventional Commits が含まれる場合のみ行われます:

その他のメッセージは公開をスキップします。GitHub シークレット NPM_TOKEN（droplinkperformance 組織の npm Automation トークン）が必要です。

npm リリース成功後、同じワークフローがメタデータを MCP Registry に io.github.droplinkperformance/bitbucket-mcp-server として公開します（OIDC、追加シークレット不要）。github.com/mcp はそのレジストリから同期します。サーバーが表示されない場合は、partnerships@github.com にメールしてください。

最初のリリースで 0.x を維持するには、最初の conventional マージの前に現在のコミットにタグを付けます（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（Bitbucket → 個人設定 → メールエイリアス にある Atlassian アカウントのメールアドレス）を設定します。API トークンは Bearer ではなく HTTP Basic 認証を使用します。

アプリパスワード（レガシー、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

ロードマップ

• Phase 1（本リリース）: 認証、抽象化、BitbucketClient、ツール自動検出、PR ツール、analyze_pull_request。

• Phase 2: Pipelines + 全文ページネーションログ、pipeline-investigator エージェント、auto_review_pull_request（ドライラン / インラインコメント公開）。

• Phase 3: 残りの CRUD — リポジトリ、コミット、ブランチ、タグ、課題、ワークスペース、メンバー、検索。

• Phase 4: analyze_dotnet_pull_request（dotnet-review エージェント）、高度なエージェント、自動化ワークフロー。

• Phase 5: Docker、Compose、Helm、本番デプロイガイド。

ライセンス

MIT