bitbucket-pr-review-mcp

言語モデルがBitbucket Cloudのプルリクエストを読み、それについてコメントを残せるようにするMCPサーバーです。コメントは関連する行にアンカーされ、さらに上部に1件のサマリーが付きます。

このサーバーは素材を提供し、言葉を投稿します。意見を形成するわけではありません。レビューを行うのは呼び出し側のモデルであり、ここにはレビュープロンプトもモデルの認証情報も含まれません。

• 仕組みと理由: docs/architecture.md

• その背後にある決定: docs/adr/

• 使用する言語: CONTEXT.md

できないこと

コメントの作成と更新は可能です。プルリクエストの承認、却下、マージはできません。ブランチやファイルへの書き込みもできず、コメントの削除も一切行いません。

Bitbucketには、コメントとマージを分離する権限は販売されていません。 このサーバーに渡す認証情報は、あなたのプルリクエストをマージできる能力を持っています。トークンやスコープでそれを防ぐことはできません。防いでいるのは、ツールがそれを要求しないこと、HTTPクライアント内の単一のチョークポイントが要求の構築方法に関係なくそれを拒否すること、そして — このコードが正しいことに依存しない部分 — リポジトリ自体にあなた自身が設定するブランチ制限です。ADR-0002を参照し、始める前にをお読みください。

Related MCP server: Bitbucket MCP Server

始める前に

許可リストに登録するリポジトリには、ブランチ制限を設定してください。 Bitbucketで: リポジトリ設定 → ブランチ制限。デフォルトブランチへのマージを許可する人を制限し、チームが期待する承認を要求してください。Bitbucketは、このサーバーが何をするかに関係なくそれを強制します。これが、このリポジトリのバグが発生しても生き残る唯一の保証です。1分で完了し、「このコードは慎重だと信じている」と「そうでなくても構わない」の違いになります。

インストール

uvとPython 3.13が必要です。同じ3つのコマンドがWindows、macOS、Linuxで動作します:

git clone <this repository>
cd bitbucket-pr-review-mcp
uv sync

次に、それに触れることを許可するリポジトリを指定します:

cp config/repositories.yaml.example config/repositories.yaml

...そしてそれを編集します。ファイルには workspace/repo エントリがリストされ、シークレットは含まれず、コミットされることを意図しています:

repositories:
  - streamstech/db-explorer
  - streamstech/lent-manager

ワークスペース全体は jantrik/* のように記述できます。これはここで最も広いエントリです — 書いた後に作成されたリポジトリもカバーするため、サーバーは起動のたびにそれを明示します:

repositories:
  - jantrik/*

サーバーはリストなしでは起動を拒否します。リストがないことは、認証情報が到達できるすべてのリポジトリに触れる許可と区別がつきません。ワークスペース全体より狭いパターン (*/db-explorer、streamstech/db-*) も同じ理由で拒否されます: それらは命名に関する推測であり、次にそのように命名されるものを何でも受け入れてしまうからです。

Bitbucketアカウントの接続

セットアップを実行し、表示されるリンクを開きます:

uv run bb-pr-mcp --setup

それはあなた自身のマシン上でページを提供します — ループバックのみ、ランダムなポート、使い捨てリンク、5分で消えます — Atlassianアカウントのメールアドレス (Bitbucketユーザー名でも、トークンに付けた名前でもありません) とAPIトークンを求めます。何かを保存する前に、そのペアをBitbucketに対して検証し、表示名を表示します。その後、認証情報をOSのキーチェーンに保存して閉じます。

トークンはhttps://id.atlassian.com/manage-profile/security/api-tokensで、正確に次の4つのスコープで作成してください:

それ以上は不要です。リポジトリへの書き込み、管理、パイプラインの実行ができるトークンは、フォームで拒否され、起動時にも再度拒否されます。

セットアップ時にトークンの有効期限を入力すると、有効期限の1週間前に警告が表示され、レビュー中に401に遭遇することはありません。

--setup を明示的に実行する必要はありません。認証情報が保存されていない場合、すべてのツールはエラーではなくセットアップURLで応答します。

いつでも確認できます:

uv run bb-pr-mcp --check

これにより、許可リスト、認証情報とそのスコープが検証され、誰として投稿するかが表示され、シェルステータスで終了します — 0 正常、1 使用可能な認証情報なし、2 スコープが間違っているトークン。

削除する

uv run bb-pr-mcp --forget

これにより、このデバイスのキーチェーンから認証情報が削除され、それ以外は何もされません — トークンはAtlassianで失効させるまで存在し続け、コマンドはそれを明示します。次のツール呼び出しで新しいセットアップリンクが提供されます。

意図的にツールはありません。認証情報を削除するツールは、プルリクエストの説明がモデルに呼び出させるツールであり、何も得られません。削除したい人はすでにターミナルにいます。

モデルがトークンを見ることはない

トークンはブラウザからキーチェーンへ、そこからAuthorizationヘッダーに入ります。ツールの引数になることも、ツールの回答に含まれることも、エラーメッセージに含まれることも、セットアップURLに含まれることもありません — そこには異なる使い捨てトークンが含まれており、それはこのマシン上の1つのフォームに入力する権利のみを付与します。tests/test_the_token_never_reaches_the_model.py は、それらのすべての場所でそれを探します。

キーチェーンが利用できない場合

認証情報はOSのキーチェーンに入り、他にはどこにも入りません — ファイルには決して入りません。macOSとWindowsではそのまま動作します。Linuxでは、Secret Service (gnome-keyring または KWallet) が実行され、ロック解除されている必要があります。ない場合は、ファイルにフォールバックするのではなく、サーバーは停止します (ADR-0003)。

実行

サーバーはstdioを介してMCPを話します。クライアントをそれに向けます:

{
  "mcpServers": {
    "bitbucket-pr-review": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/bitbucket-pr-review-mcp", "bb-pr-mcp"]
    }
  }
}

Windowsでは、同じ形式でWindowsパスを使用します ("C:\\path\\to\\bitbucket-pr-review-mcp")。それ以外はプラットフォーム間で違いはありません。

Claude Codeの場合:

claude mcp add bitbucket-pr-review -- uv run --directory /path/to/bitbucket-pr-review-mcp bb-pr-mcp

Dockerで実行

イメージは他のものと同様にstdioを介してMCPを話すため、ポートはなく、upするものもありません。ビルドして、-iを付けて実行し、それに話しかけます。

docker build -t bitbucket-pr-review-mcp:local .

コンテナにはキーチェーンがなく、セットアップページも役に立ちません。コンテナ内部のループバックポートにバインドするため、ブラウザからは到達できません。したがって、コンテナ化された実行は、保存する代わりに認証情報を与えられます。これは本当のダウングレードです — 環境変数はdocker inspectやプロセスを読み取れるものに表示されます — そしてそれはフォールバックではなく決定です。それに劣化するものはなく、両方の変数を設定する必要があり、起動は毎回それを明示します。ADR-0007を参照してください。

このリポジトリにないファイルに認証情報を置きます:

BB_MCP_EMAIL=you@yourcompany.com
BB_MCP_API_TOKEN=ATATT...
BB_MCP_TOKEN_EXPIRES_ON=2027-08-24

次にそれを確認し、クライアントに配線します:

docker run --rm \
  --env-file /path/to/env.docker \
  -v /path/to/repositories.yaml:/config/repositories.yaml:ro \
  bitbucket-pr-review-mcp:local --check

{
  "mcpServers": {
    "bitbucket-pr-review": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/path/to/env.docker",
        "-v", "/path/to/repositories.yaml:/config/repositories.yaml:ro",
        "bitbucket-pr-review-mcp:local"
      ]
    }
  }
}

docker-compose.yaml は同じフラグを一度だけ書き留めます: docker compose run --rm bitbucket-pr-review。このディレクトリから.env.docker(gitignored)を読み取ります。

知っておくべき点:

• Windowsでは、-v にWindowsスタイルのパスを使用します (d:/path/to/repositories.yaml:/config/...)。Git Bashの場合は、コマンドの前に MSYS_NO_PATHCONV=1 を付けるか、パスが書き換えられます。

• 許可リストはマウントされ、焼き付けられません。 サーバーが触れることができるリポジトリを指定します。そのリストはイメージではなく、イメージを実行する人に属します。

• --setup はコンテナ内で2で終了し、セットアップが代わりに実行できる場所を示します。トークンのローテーションは、新しいトークンで再起動することを意味します。

• コンテナは非rootユーザーとして、読み取り専用で、すべてのケーパビリティを落として実行されます。

共有サーバーへの接続

共有デプロイ — 複数の人、1つのサーバー、それぞれが自分のBitbucketアカウントを持つ — は単一のオリジンの背後で実行されます。MCPエンドポイントとKeycloakの両方がそこから提供されます。発行者は、トークン、ディスカバリードキュメント、ブラウザ、構成で同じ意味を持つ文字列であるためです。

Claude DesktopもClaude Codeも、localhost を介してサーバーに直接到達しません。 Claudeの カスタムコネクタ は、ユーザーのマシンではなくAnthropicのインフラストラクチャによってフェッチされるため、ラップトップ上のサーバーは、どのように構成しても到達できません。ローカルループはmcp-remoteを経由します: これはユーザーのマシンで実行され、ブラウザでOAuthフローを実行し、サーバーにHTTPを話すstdioブリッジです。サーバーが公開httpsアドレスを持つと、カスタムコネクタは直接到達し、ブリッジは不要になります。

どのクライアントIDがどこに使われるか

レルムには3つのOAuthクライアントがあります。3つの異なるものが認証され、それらは交換可能ではないためです。間違ったものを使うと最初のステップで失敗し、KeycloakエラーページにInvalid parameter: redirect_uriが表示されます — これはクライアントではなくパラメータを指定し、すべての原因で同じメッセージです。

分割はコールバックが着地する場所に従います。コネクタのコールバックはhttps://claude.ai/api/mcp/auth_callbackで、Anthropicのインフラ上にあるため、そのクライアントは機密であり、シークレットはそこにあります。ブリッジのコールバックは誰かのラップトップ上のループバックポートであるため、そのクライアントはシークレットを一切保持しません — ラップトップ上の設定ファイルにあるシークレットはシークレットではなく、PKCEがループバックフローを保護するものです。ホストされたコールバックをパブリッククライアントに登録すると、機密フローを何も保持できないクライアントに渡すことになるため、登録されておらず、Keycloakはそれを拒否します。

.env.example を .env にコピーし、起動します:

cp .env.example .env      # fill in the secrets; the defaults are the loopback stack
docker compose --profile shared up -d

これにより、Postgres、Keycloak、nginx、レビューサーバーが起動します。docker compose --profile shared ps は4つの正常なコンテナを表示し、http://localhost:8080/mcp は bitbucket:review スコープを指定するWWW-Authenticateヘッダー付きで401を返すはずです — 認証されていないリクエストが拒否されるのはシステムが機能していることです。

Claude Code

ブリッジを一度、すべてのプロジェクトに対して、-s user で登録します:

claude mcp add bitbucket-pr-review -s user -- npx -y mcp-remote http://localhost:8080/mcp 3334 --allow-http --static-oauth-client-info "{\"client_id\":\"bitbucket-pr-review-cli\"}"

-s user はそれを ~/.claude.json のトップレベルの mcpServers キーに書き込み、すべてのディレクトリに適用されます。代替は -s local (このプロジェクトのみ、~/.claude.json 内の projects の下) と -s project (コミットされた .mcp.json) です。複数のスコープで登録しないでください。構成は別々で、ユーザースコープが優先され、後で編集するものが使用されているものではない可能性があります。

確認:

claude mcp get bitbucket-pr-review

これは Scope: User config と Status: ✔ Connected を報告するはずです。セッションは開始時にMCPサーバーを取得するため、実行中のClaude Codeは再起動するまで新しく登録されたサーバーを認識しません。

誰かにアカウントを与える

レルムには1人のユーザー dev / dev-only-not-for-production が含まれており、これは開発用の認証情報であり、そのように明示されています。他の誰もがログインする前にKeycloakでアカウントを持っている必要があります — それは後で /connect で自分で接続するBitbucketアカウントとは別のことです。

管理コンソールで。 http://localhost:8080/admin を開き、ブートストラップ管理者（.env の KC_BOOTSTRAP_ADMIN_USERNAME / KC_BOOTSTRAP_ADMIN_PASSWORD）としてサインインし、レルムピッカーを master から streamstech に切り替えて、Users → Add user を選択します。ユーザー名、メール、名と姓を入力し、Email verified にチェックを入れて作成します。次に Credentials → Set password で、Temporary をオフにします（初回ログイン時に変更を促す必要がない場合）。

またはコマンドラインから。 こちらは繰り返し実行するのに簡単です：

docker exec bitbucket-pr-review-mcp-keycloak-1 /opt/keycloak/bin/kcadm.sh \
  config credentials --server http://localhost:8080 --realm master \
  --user admin --password "$KC_BOOTSTRAP_ADMIN_PASSWORD"

docker exec bitbucket-pr-review-mcp-keycloak-1 /opt/keycloak/bin/kcadm.sh \
  create users -r streamstech \
  -s username=somebody -s email=somebody@example.com -s emailVerified=true \
  -s firstName=Some -s lastName=Body -s enabled=true

docker exec bitbucket-pr-review-mcp-keycloak-1 /opt/keycloak/bin/kcadm.sh \
  set-password -r streamstech --username somebody --new-password 'their-password'

Git Bash では、各コマンドの前に MSYS_NO_PATHCONV=1 を付けるか、/opt/keycloak/... が Windows パスに書き換えられて docker exec がファイルが存在しないと報告するのを防ぎます。

間違いやすい点が2つあり、どちらも作成時ではなく ログイン時 に失敗し、原因を示さないメッセージが表示されます：

• 名と姓は必須です。 Keycloak のユーザープロファイルはこれらを必須として扱うため、それらなしで作成されたアカウントは invalid_grant: Account is not fully set up で認証に失敗します。アカウント作成時に警告はありません。

• kcadm.sh set-password で -t を付けない場合はすでに永続的です。-t を付けると一時的になり、同じ必須アクションが保留されたままになります。

ロールやグループメンバーシップは不要です。新しいアカウントには default-roles-streamstech が自動的に付与され、それで十分です。このサーバーは OAuth フロー中に要求され同意される bitbucket:review スコープで認可を行い、事前に付与されるわけではありません。

アカウントは Keycloak のデータベース（ボリューム）に保存されます。再起動後も存続しますが、docker volume rm bitbucket-pr-review-mcp_keycloak-db を実行すると消えます。

Claude Desktop

Claude Desktop には mcp add コマンドがありません。claude_desktop_config.json を手動で編集します。その場所は Claude のインストール方法によって異なります：

Store のパスが人を陥れやすいものです。Store からのインストールは %APPDATA% のファイルを完全に無視し、間違ったファイルを編集してもエラーなしで何も変わりません。

{
  "mcpServers": {
    "bitbucket-pr-review": {
      "command": "cmd",
      "args": [
        "/c", "npx",
        "-y", "mcp-remote",
        "http://localhost:8080/mcp",
        "3335",
        "--allow-http",
        "--static-oauth-client-info", "{\"client_id\":\"bitbucket-pr-review-cli\"}"
      ]
    }
  }
}

deploy/claude_desktop_config.example.json には同じ内容が含まれています。その中の2つの詳細が実際に機能しています：

• Windows では npx の前に cmd /c を付けます。 Claude Desktop はシェルを介して起動しないため、裸の "command": "npx" は、自身のパスにスペースを含むバッチファイルに解決され、ログに 'C:\Program' is not recognized as an internal or external command というエラーで全体が失敗します。macOS では cmd と /c を削除し、"command": "npx" を使用します。

• ポート 3335 ではなく 3334 を使用します。 その番号はブリッジ自身のループバックポートであり、Claude Code の登録はすでに 3334 を使用しています。1つのポートに2つのブリッジがあると、後から起動した方が OAuth コールバックを受信できません。レルムは http://127.0.0.1:*/oauth/callback を登録するため、空いているポートならどれでも機能します。

Claude Desktop を再起動します（ウィンドウを閉じても実行中のままなので、トレイから完全に終了します）。そして起動を確認します：

tail -f "$LOCALAPPDATA/Packages/Claude_*/LocalCache/Roaming/Claude/logs/mcp-server-bitbucket-pr-review.log"

Proxy established successfully between local STDIO and remote StreamableHTTPClientTransport という行は、ブリッジがサーバーと通信していることを意味します。Server transport closed unexpectedly は、代わりに終了したことを意味します。その理由は数行上にあります。

最初のツール呼び出しで Keycloak ログインが開きます（開発レルムの dev / dev-only-not-for-production、または上で作成したアカウント）。サインイン後、ツール呼び出しは /connect へのリンクで応答し、そこで Atlassian アカウントを接続します。そのページでブラウザもサインインするため、リンクはトランスクリプトに表示しても安全です。

知っておくべき点がいくつかあります：

• ブリッジは 公開 OAuth クライアントで、シークレットはありません。 ラップトップの設定ファイルにあるクライアントシークレットはシークレットではありません。PKCE がループバックフローを保護します。

• そのコールバックは http://127.0.0.1:3334/oauth/callback です — localhost ではなく IP リテラル、そして Claude Code の /callback ではなく /oauth/callback です。レルムはそれらすべてを登録します。間違えるとフローの最後のステップで失敗するからです。

• サーバーが平文 http の間は --allow-http が必要です。 実際のデプロイは https であり、このサーバーはループバック以外の http で自分自身を説明することを拒否します。

• 3334 引数はブリッジ自身のポートです、そしてレルムはそのポートでコールバックを登録します。2つの Claude クライアントが同時にブリッジする場合は、異なるポートが必要です。

• shared プロファイルの デフォルト は開発用設定です — パスワードが docker-compose.yaml にあるブートストラップ管理者、パスワードがレルムファイルにあるユーザーを含むレルム、そしてループバック上の平文 http。これらはすべてデフォルト値を持つ変数であり、実際のデプロイではどちらのファイルも編集せずに .env で上書きします。docs/deploying-the-shared-server.md を参照してください。

• オリジンを変更するにはレルムを再インポートする必要があります。 レルムは Keycloak のデータベースに一度インポートされます。--import-realm は既存のレルムをそのままにします。そのボリュームを名前で削除します — docker volume rm bitbucket-pr-review-mcp_keycloak-db — そして down -v は絶対に実行しないでください。資格情報ボールトも一緒に削除されるからです。

運用

uv run bb-pr-mcp --health
uv run bb-pr-mcp --rotate-key /path/to/new.key

--health はデプロイが実行に適しているかどうかを示します — TLS、ボールトキー、ストア、許可リスト、認可サーバーへの到達可能性、接続人数 — そして正常なら 0、確認すべきことがあれば 1、起動できない場合は 2 で終了します。

--rotate-key は、誰も再登録することなく、保存されているすべての資格情報を新しいキーで再シールし、残りの手順を実行する順序を指示します。

実際の環境で実行する前に docs/deploying-the-shared-server.md を読んでください。 ホストが1回侵害された場合のコストが、見た目よりも大きいこと、そしてそれに対して何をすべきかが記載されています。

接続中のユーザーと、ユーザーの削除

uv run bb-pr-mcp --who
uv run bb-pr-mcp --revoke alice@streamstech.com

--who は Bitbucket アカウントを接続した全員を一覧表示します：不透明 ID、Atlassian メール、接続日時、トークンの有効期限。回答するためにボールトを復号化し、復号化する価値のある1つのフィールド以外をすべて出力します。

--revoke は1人の保存された資格情報を削除します。メールまたは曖昧さのない不透明 ID の一部を受け取り、名前が2人に一致する場合は推測せずに拒否します。失効は次のツール呼び出しで有効になります、すでに実行中のサーバーでも同様です。共有サーバーは資格情報を保持せずに読み通すため、別のターミナルのオペレーターが再起動を待つ必要がありません。

しない ことは、読む価値のある部分です。誰かが去った後、3つの場所に何かが残ります。このコマンドはそのうちの1つを管理します：

• ここ。 保存された資格情報は削除されます。

• Keycloak。 彼らはまだサインインして新しいトークンを接続できます。それを止めるには、そこでアカウントを無効にします。

• Atlassian。 彼らの API トークンはまだ存在し、他の場所では引き続き機能します。それを失効できるのは、本人または Atlassian 管理者だけです。

コマンドは毎回これら3つすべてを言います。ステップ1の後にチェックされるオフボーディングチェックリストは、チェックリストがないより悪いからです。

どちらもツールではありません。これは意図的です。プルリクエストの説明が Caller を説得して同僚の接続を解除させてはならないからです。

ツール

プルリクエストは1つの文字列で指定されます：Bitbucket URL または短縮形 workspace/repo/id のいずれかです。

設定

以下はすべて動作するデフォルトがあります。環境変数または .env ファイルで設定し、すべて BB_MCP_ プレフィックスを付けます：

さらに2つ存在し、共有デプロイが完了するまで空です。上記のデバイスごとのインストールではどちらも不要です。stdio には呼び出し元が1つしかないからです。

上限に達した場合は、必ずレスポンスに明記されます。切り詰めが黙って行われることはありません。切り詰められた diff と完全な diff を区別できない Caller は、欠落した半分が問題なかったものと想定してレビューしてしまうからです。

開発

uv run pytest                    # the suite
uv run pytest --cov=src          # with coverage
uv run ruff check src tests      # lint
uv run ruff format src tests     # format

テストは決してネットワークに触れません。シームは HTTP トランスポートのみであり、それ以外にはありません。そのため、ガード、許可リスト、およびすべてのレスポンスリーダーが本番コードとして実行されます。tests/recorded/ には実際のプルリクエストから取得したレスポンスが保存されています。それがなぜ見た目以上に重要なのかは docs/architecture.md を参照してください。