Bitbucket MCP Server

🚀 Bitbucket MCP Server

Bitbucket MCP サーバーは、Bitbucket API とのやり取りを支援するツールを提供する MCP（Model Context Protocol）サーバーです。Bitbucket Cloud と Bitbucket Server の両方をサポートしています。

🚀 クイックスタート

この Bitbucket MCP サーバーを用いることで、Bitbucket API とのやり取りを容易に行うことができます。以下のセクションでは、インストール方法、設定方法、使用方法を説明します。

✨ 主な機能

現在実装されているツール

プルリクエストのコアライフサイクルツール

• get_pull_request - プルリクエストの詳細情報を取得します。
• list_pull_requests - フィルタ（状態、作成者、ページネーション）を使ってプルリクエストを一覧表示します。
• create_pull_request - 新しいプルリクエストを作成します。
• update_pull_request - プルリクエストの詳細（タイトル、説明、レビュワー、宛先ブランチ）を更新します。
• add_comment - プルリクエストにコメントを追加します（返信もサポート）。
• merge_pull_request - 様々な戦略でプルリクエストをマージします。
• list_pr_commits - プルリクエストに含まれるすべてのコミットを一覧表示します。
• delete_branch - マージ後にブランチを削除します。

ブランチ管理ツール

• list_branches - フィルタリングとページネーションを使ってブランチを一覧表示します。
• delete_branch - ブランチを削除します（保護チェック付き）。
• get_branch - 関連するプルリクエストを含むブランチの詳細情報を取得します。
• list_branch_commits - 高度なフィルタリングを使ってブランチ内のコミットを一覧表示します。

ファイルとディレクトリツール

• list_directory_content - リポジトリのパス内のファイルとディレクトリを一覧表示します。
• get_file_content - 大きなファイルに対してスマートなトランケーションを行いながらファイル内容を取得します。

コードレビューツール

• get_pull_request_diff - プルリクエストの差分/変更内容を取得します。
• approve_pull_request - プルリクエストを承認します。
• unapprove_pull_request - プルリクエストの承認を取り消します。
• request_changes - プルリクエストに変更を要求します。
• remove_requested_changes - プルリクエストの変更要求を取り消します。

📦 インストール

npx を使用する（推奨）

この MCP サーバーを使用する最も簡単な方法は、直接 npx を使用することです。

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/bitbucket-mcp-server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

Bitbucket Server の場合:

{
  "mcpServers": {
    "bitbucket": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/bitbucket-mcp-server"
      ],
      "env": {
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

ソースからインストール

1. このリポジトリをクローンまたはダウンロードします。
2. 依存関係をインストールします。

   npm install
   

3. TypeScript コードをビルドします。

   npm run build
   

認証設定

このサーバーは、Bitbucket のアプリパスワードを使用して認証を行います。

アプリパスワードの作成

1. Bitbucket アカウントにログインします。
2. https://bitbucket.org/account/settings/app-passwords/ に移動します。
3. 「アプリパスワードを作成」をクリックします。
4. 説明的なラベル（例: "MCP Server"）を付けます。
5. 以下のパーミッションを選択します。
   • アカウント: 読み取り
   • リポジトリ: 読み取り、書き込み
   • プルリクエスト: 読み取り、書き込み
6. 「作成」をクリックします。
7. 重要: 生成されたパスワードをすぐにコピーしてください（再度表示できなくなります！）

設定スクリプトの実行

node scripts/setup-auth.js

これにより、認証設定プロセスがガイドされます。

設定

サーバーを MCP 設定ファイル（通常は ~/.vscode-server/data/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json にあります）に追加します。

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your-username",
        "BITBUCKET_APP_PASSWORD": "your-app-password"
      }
    }
  }
}

以下を置き換えます。

• /absolute/path/to/bitbucket-mcp-server をこのディレクトリの実際のパスに置き換えます。
• your-username をあなたの Bitbucket ユーザー名（メールアドレスではない）に置き換えます。
• your-app-password をあなたが作成したアプリパスワードに置き換えます。

Bitbucket Server の場合は、以下を使用します。

{
  "mcpServers": {
    "bitbucket": {
      "command": "node",
      "args": ["/absolute/path/to/bitbucket-mcp-server/build/index.js"],
      "env": {
        "BITBUCKET_USERNAME": "your.email@company.com",
        "BITBUCKET_TOKEN": "your-http-access-token",
        "BITBUCKET_BASE_URL": "https://bitbucket.yourcompany.com"
      }
    }
  }
}

Bitbucket Server ユーザーに重要な注意事項:

• ユーザー名として完全なメールアドレス（例: "john.doe@company.com"）を使用してください。
• これは、承認/レビューアクションが正しく機能するために必要です。

💻 使用例

基本的な使用法

プルリクエストの取得

{
  "tool": "get_pull_request",
  "arguments": {
    "workspace": "PROJ",  // 必須 - あなたのプロジェクトキー
    "repository": "my-repo",
    "pull_request_id": 123
  }
}

このコードは、指定したプルリクエストの詳細情報を取得します。戻り値には、タイトルや説明、作成者やレビュワー、ソースや宛先のブランチ、承認状態、Web UI や差分へのリンクなどが含まれます。

プルリクエストの一覧表示

{
  "tool": "list_pull_requests",
  "arguments": {
    "workspace": "PROJ",  // 必須 - あなたのプロジェクトキー
    "repository": "my-repo",
    "state": "OPEN",  // オプション: OPEN, MERGED, DECLINED, ALL (デフォルト: OPEN)
    "author": "username",  // オプション: 作成者でフィルタ（下記の注意を参照）
    "limit": 25,  // オプション: ページあたりの最大結果数 (デフォルト: 25)
    "start": 0  // オプション: ページネーションの開始インデックス (デフォルト: 0)
  }
}

このコードは、指定した条件に一致するプルリクエストを一覧表示します。戻り値には、プルリクエストの配列と、一致するプルリクエストの総数、ページネーション情報が含まれます。

高度な使用法

コメントの追加

// 一般的なコメント
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "このプルリクエストでの作業は素晴らしいです！"
  }
}

// 特定の行にインラインコメントを追加
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "これを別の関数に抽出することを検討してください",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT"  // ADDED, REMOVED, or CONTEXT
  }
}

// 既存のコメントに返信
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "この提案に同意します",
    "parent_comment_id": 456
  }
}

// コード提案付きのコメントを追加（1行）
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "この変数名はより説明的にすることができます。",
    "file_path": "src/utils/helpers.js",
    "line_number": 42,
    "line_type": "CONTEXT",
    "suggestion": "const userAuthenticationToken = token;"
  }
}

// 複数行のコード提案付きのコメントを追加
{
  "tool": "add_comment",
  "arguments": {
    "workspace": "PROJ",
    "repository": "my-repo",
    "pull_request_id": 123,
    "comment_text": "この関数は配列メソッドを使って簡素化できます。",
    "file_path": "src/utils/calculations.js",
    "line_number": 50,
    "suggestion_end_line": 55,
    "line_type": "CONTEXT",
    "suggestion": "function calculateTotal(items) {\n  return items.reduce((sum, item) => sum + item.price, 0);\n}"
  }
}

これらのコードは、プルリクエストにコメントを追加するさまざまな方法を示しています。コメントは、一般的なコメント、インラインコメント、返信コメント、コード提案付きのコメントなど、さまざまな形式で追加できます。

📚 ドキュメント

各ツールの詳細な使用方法や応答内容については、上記の使用例を参照してください。また、以下の点に注意してください。

コメントの返信に関する注意

• parent_comment_id を使用して、任意のコメント（一般的なコメントまたはインラインコメント）に返信できます。
• get_pull_request の応答では、Bitbucket Server は返信を replies 配列にネストして表示し、Bitbucket Cloud は返信コメントに parent_id フィールドを表示します。
• 返信に返信することもでき、ネストされた会話を作成できます。

インラインコメントに関する注意

• file_path: 差分に表示されるファイルのパス。
• line_number: 差分に表示される行番号。
• line_type:
  • ADDED - 新しく追加された行（差分で緑色）。
  • REMOVED - 削除された行（差分で赤色）。
  • CONTEXT - 変更されていないコンテキスト行。

コードスニペットを使用する場合の注意

• add_comment ツールは、コードスニペットを使用して自動的に行番号を見つけることができます。これは、AI ツールが差分を分析し、正確な行番号を特定するのが困難な場合に特に便利です。
• code_snippet は、見つけるコード行を指定するために使用します（line_number の代替）。
• search_context は、複数の一致がある場合にコンテキストを指定するために使用します。
• match_strategy は、複数の一致がある場合の処理方法を指定します。

🔧 技術詳細

このサーバーは、Bitbucket API とのやり取りを容易にするために開発されました。以下の点について注意してください。

• コードは TypeScript で記述されており、Node.js 環境で動作します。
• 認証には Bitbucket のアプリパスワードを使用しています。
• コメントの提案機能は、GitHub スタイルのマークダウン提案ブロックを使用しています。

📄 ライセンス

このプロジェクトは MIT ライセンスの下で公開されています。詳細については、LICENSE を参照してください。