mcp-gh-pr-mini

mcp-gh-pr-mini

GitHub のプルリクエストを操作する、二重認証に対応した最小構成の MCP（Model Context Protocol）サーバーです。

このツールを使うと、MCP 経由で GitHub リポジトリのプルリクエストを作成、一覧表示、詳細や差分の確認、レビュアーの依頼、コメントの投稿ができます。Personal Access Token（PAT）と GitHub CLI の両方の認証方式に対応しています。

最新バージョン：1.4.0 - draft パラメーターによるドラフト PR 作成に対応しました。

✨ 特徴

🎯 利用可能な MCP ツール

create_pull_request

GitHub リポジトリに新しいプルリクエストを作成します。

• パラメーター：owner、repo、title、body、head（ソースブランチ）、base（対象ブランチ）、draft（任意）
• 戻り値：すぐにアクセスできる PR 番号と URL
• 機能：
  • ✅ レビュー可能な PR を作成します（デフォルト）
  • ✅ draft: true でドラフト PR を作成します 🆕 v1.4.0
  • ✅ 成功メッセージにドラフトのステータスを表示します
• テスト済み：✅ PAT と GitHub CLI の両方の認証方式で動作します

update_pull_request

GitHub リポジトリの既存のプルリクエストを更新します。

• パラメーター：owner、repo、pr_number、任意の title、body、base、state（open/closed）
• 戻り値：確認メッセージと更新後の PR 詳細
• 機能：
  • ✅ タイトルと説明を更新します
  • ✅ 対象ブランチ（base）を変更します
  • ✅ プルリクエストをオープンまたはクローズします
  • ✅ 部分更新に対応します（指定したフィールドのみを変更します）
• テスト済み：✅ PR のメタデータとステータスを正常に更新します

list_open_pull_requests

リポジトリ内のオープン中のプルリクエストをすべて一覧表示します。

• パラメーター：owner、repo、任意の limit（デフォルト：10）
• 戻り値：PR 番号、タイトル、作成者、URL
• テスト済み：✅ オープン中の PR がないリポジトリも適切に処理します

get_pull_request 🆕 v1.3.0

特定のプルリクエストに関する詳細情報を取得します。

• パラメーター：owner、repo、pr_number
• 戻り値：PR のタイトル、説明、ステータス、作成者、ブランチ、メタデータ
• 機能：
  • ✅ タイトルや本文を含む PR の詳細情報をすべて取得します
  • ✅ PR のステータス、作成者、ブランチ情報を表示します
  • ✅ 作成日時と更新日時を表示します
  • ✅ PR への直接リンクを提供します
• 使用例：gh pr view {pr_number} --repo {owner/repository} --json title,body と同様です
• テスト済み：✅ あらゆるエッジケースを網羅した包括的な単体テストを 17 件実施済みです

get_pull_request_diff

プルリクエストの統合差分を取得します。

• パラメーター：owner、repo、pr_number
• 戻り値：すべてのファイル変更を示す、統合形式の完全な差分
• テスト済み：✅ 新規、変更、削除されたファイルの差分を正しく整形します

request_reviewers

既存のプルリクエストにレビュアーを追加します。

• パラメーター：owner、repo、pr_number、reviewers（GitHub ユーザー名の配列）
• 戻り値：レビュアーの割り当てを確認するメッセージ
• テスト済み：✅ プルリクエストにレビュアーを正常に割り当てます

add_pr_comment

プルリクエストの会話に一般コメントを追加します。

• パラメーター：owner、repo、pr_number、body（コメント本文）
• 戻り値：参照用のコメント ID と URL
• 特別な機能：
  • ✅ コメントの先頭に「[AI] Generated using MCP」を自動で付加します
  • ✅ 両方の認証方式でテスト済みです

add_review_comment

変更されたファイルの特定の行（または差分内の位置）にコードレビューコメントを追加します。

• パラメーター：owner、repo、pr_number、body、path（ファイルパス）、および次のいずれか：
  • line（推奨）：ファイル内の行番号。任意で side（LEFT/RIGHT、デフォルトは RIGHT）と、複数行コメント用の start_line/start_side を指定できます
  • position（非推奨）：差分内のオフセット。後方互換性のために維持されています
  • subject_type: "file"：対象の行が差分ハンクの範囲外にある場合のファイル単位のコメント（line/position は指定しません）
• 戻り値：レビューコメントの ID と URL
• テスト済み：✅ 行番号、差分内の位置、ファイル単位のコメントによるインラインコードコメントの追加に成功しています

get_pr_comments

プルリクエストのすべてのコメントを取得します。

• パラメーター：owner、repo、pr_number
• 戻り値：会話コメントとレビューコメントを分類した一覧
• 機能：
  • ✅ 一般的な PR コメントとコードレビューコメントを分けて表示します
  • ✅ コメントのメタデータ（作成者、日付、URL）を表示します
  • ✅ AI が生成したコメント識別子を表示します

get_pr_changes_for_commenting

レビューコメントを追加できる位置情報とともに、ファイルの変更内容を取得します。

• パラメーター：owner、repo、pr_number
• 戻り値：コメントを追加できる位置情報を含む、ファイル変更の詳細
• 機能：
  • ✅ 変更されたすべてのファイルを、ステータス（追加、変更、削除）とともに一覧表示します
  • ✅ インラインコメント用の正確な位置番号を提示します
  • ✅ 各ファイルのパッチ情報全体を表示します

認証方法 🔐

• Personal Access Token（PAT）：従来のトークンベースの認証
• GitHub CLI：既存の gh CLI 認証を活用します
• 自動検出：利用可能な認証方法の中から最適なものを自動的に選択します
• インテリジェントなフォールバック：認証方法に問題が発生した場合、別の認証方法にシームレスに切り替えます
  • 優先：PAT 認証（設定されている場合）
  • フォールバック：GitHub CLI 認証（利用可能な場合）
  • 認証エラー時にユーザーが操作する必要はありません
  • 認証方法を問わず、一貫した API 応答を維持します

🛠️ セットアップ

このツールは、ローカル環境で MCP サーバーとして実行されます。 Copilot Agent などのツールや、MCP 互換クライアントで利用できます。

必要条件

• Node.js がインストールされていること
• MCP 互換拡張機能を備えた VSCode（例：Copilot Agent）

🔐 認証システム

推奨：GitHub CLI 認証

gh auth login  # One-time setup
npx mcp-gh-pr-mini  # Works immediately

代替：Personal Access Token

PAT 認証を使用する場合は、環境変数 GITHUB_PERSONAL_ACCESS_TOKEN を設定してください。

必要な PAT 権限：

権限	アクセスレベル
Pull requests	読み取りと書き込み
Issues	読み取りと書き込み
Metadata	読み取り（自動）

settings.json での設定

GitHub CLI 認証を使用する場合

"mcp": {
  "servers": {
    "mcp-gh-pr-mini": {
      "command": "npx",
      "args": ["mcp-gh-pr-mini"]
    }
  }
}

Personal Access Token を使用する場合

"mcp": {
  "servers": {
    "mcp-gh-pr-mini": {
      "command": "npx",
      "args": ["mcp-gh-pr-mini"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "{Your Fine-Grained GitHub Token}"
      }
    }
  }
}

🔐 認証の詳細

デュアル認証システム

この MCP サーバーは、利用可能な認証方法を自動的に検出し、最適な方法を使用する、インテリジェントなデュアル認証システムを備えています。

GitHub CLI（推奨）⭐

• シームレスな統合：既存の GitHub CLI 認証を使用します
• 幅広い対応：GitHub CLI のすべての認証方法（OAuth、PAT、SSH）で動作します
• 設定不要：gh auth login の実行後、追加のトークン設定は不要です
• エンタープライズ対応：組織の SSO と SAML を完全にサポートします
• 自動検出：サーバーが GitHub CLI の利用可否と認証状態を検出します

Personal Access Token（代替）

• 直接 API アクセス：Personal Access Token を使用して GitHub の REST API にアクセスします
• 詳細な制御：権限を細かく設定できる Personal Access Token をサポートします
• 必要な権限：
  • Pull requests：読み取りと書き込み
  • Issues：読み取りと書き込み
  • Contents：読み取りと書き込み
• フォールバック対応：GitHub CLI を利用できない場合、自動的にフォールバックとして使用されます

認証フロー 🔄

1. 検出フェーズ：起動時に、サーバーが利用可能な認証方法を確認します
2. 優先方法の選択：一貫性を保つため、（設定されている場合）Personal Access Token を優先します
3. 自動フォールバック：PAT が失敗するか無効な場合、自動的に GitHub CLI に切り替えます
4. 透過的な動作：認証エラーがユーザーに表示されることはありません。フォールバックはシームレスに行われます
5. 一貫した操作性：使用する認証方法にかかわらず、すべての MCP ツールが同じように動作します

テスト済みのシナリオ ✅

• ✅ PAT のみ：有効な個人用アクセストークンで動作します
• ✅ GitHub CLI のみ：GitHub CLI 認証だけで動作します
• ✅ 自動フォールバック：無効な PAT から GitHub CLI にシームレスに切り替わります
• ✅ 混在環境：一方の方法が利用できなくなった場合のシナリオにも対応します
• ✅ エラーからの復旧：ユーザーに影響を与えることなく、認証の失敗を適切に処理します

🚀 使用例

基本的なワークフローの例

// 1. Create a pull request
create_pull_request({
  owner: "username",
  repo: "repository",
  title: "Add new feature",
  body: "Description of the changes",
  head: "feature-branch",
  base: "main"
})

// 1a. Create a draft pull request (NEW in v1.4.0)
create_pull_request({
  owner: "username",
  repo: "repository",
  title: "WIP: Add new feature",
  body: "Work in progress - not ready for review yet",
  head: "feature-branch",
  base: "main",
  draft: true  // Creates as draft PR
})

// 1.5. Get PR details to review information
get_pull_request({
  owner: "username",
  repo: "repository",
  pr_number: 1
})

// 1.6. Update the pull request if needed
update_pull_request({
  owner: "username",
  repo: "repository",
  pr_number: 1,
  title: "Add new feature (updated)",
  body: "Updated description with more details"
})

// 2. Get the diff to review changes
get_pull_request_diff({
  owner: "username",
  repo: "repository", 
  pr_number: 1
})

// 3. Add a general comment
add_pr_comment({
  owner: "username",
  repo: "repository",
  pr_number: 1,
  body: "This looks great! Just a few small suggestions."
})

// 4. Add a specific code review comment (line is preferred over position)
add_review_comment({
  owner: "username",
  repo: "repository",
  pr_number: 1,
  body: "Consider using const instead of let here for immutability.",
  path: "src/index.ts",
  line: 42
})

// 5. Request reviewers
request_reviewers({
  owner: "username",
  repo: "repository",
  pr_number: 1,
  reviewers: ["reviewer1", "reviewer2"]
})

コメントの操作

// Get all comments to review feedback
get_pr_comments({
  owner: "username",
  repo: "repository",
  pr_number: 1
})

// Get file changes to find reviewable positions
get_pr_changes_for_commenting({
  owner: "username", 
  repo: "repository",
  pr_number: 1
})
// Returns positions where you can add review comments

リポジトリの管理

// List all open PRs to get an overview
list_open_pull_requests({
  owner: "username",
  repo: "repository",
  limit: 5
})

💡 ベストプラクティス

認証の設定

1. 手軽さを重視するなら GitHub CLI を使用：一度 gh auth login を実行すれば、トークンの管理は不要です
2. CI/CD では PAT を使用：自動化された環境では個人用アクセストークンを使用します
3. 認証をテスト：ツールを使用する前に gh auth status で確認します

コメントの管理

• AI の識別：AI が生成したコメントには、すべて自動的に「[AI] Generated using MCP」という接頭辞が付きます
• 行を指定するコメント：非推奨の position（差分内のオフセット）よりも、line（実際のファイル行番号）を優先してください。差分のハンクを数え直す必要がありません
• ハンク外の行へのフォールバック：行が差分のハンク外にある場合は、代わりに subject_type: "file" を使用してファイルレベルのコメントを追加します
• レビューのワークフロー：差分を取得 → 問題を特定 → 対象を絞ったレビューコメントを追加

エラー処理

• 認証の失敗：システムが認証方法を自動的に切り替えます
• 無効な PR：存在しない PR やリポジトリもツールが適切に処理します
• ネットワークの問題：一時的な障害に備えたリトライロジックが組み込まれています

🤔 なぜ？

このプロジェクトは、MCP 経由で基本的なプルリクエストのタスクを実行するための、最小限で目的を絞った実装を提供します。 シンプルで理解しやすい設計のため、MCP サーバーを構築する際の参考として適しています。

🔧 トラブルシューティング

認証の問題

「Authentication failed」または「Unauthorized」

1. GitHub CLI の状態を確認：gh auth status を実行して認証を確認します
2. GitHub CLI を再認証：gh auth login を実行して認証情報を更新します
3. PAT の権限を確認：個人用アクセストークンに必要な権限があることを確認します：
   • プルリクエスト：読み取りと書き込み
   • Issue：読み取りと書き込み
   • コンテンツ：読み取りと書き込み
4. 簡単なコマンドでテスト：GitHub リポジトリで gh pr list を実行し、CLI からアクセスできることを確認します

「Repository not found」

• リポジトリへのアクセスを確認：認証方法で対象のリポジトリにアクセスできることを確認します
• リポジトリ名を確認：オーナー名とリポジトリ名のつづりが正しいことを確認します
• プライベートリポジトリへのアクセス：プライベートリポジトリでは、トークンまたは CLI に適切な権限があることを確認します

認証方法の優先順位

サーバーは次の順序でフォールバックします：

1. 個人用アクセストークン（GITHUB_PERSONAL_ACCESS_TOKEN が設定されている場合）
2. GitHub CLI（gh auth status が成功した場合）
3. エラー（どちらの方法も利用できない場合）

よくある問題

「Invalid position/line for review comment」（HTTP 422）

• 指定した line（または position）が差分のハンク範囲外である可能性があります。行レベルのレビューコメントを追加できるのは、変更または追加された行（およびその前後数行のコンテキスト）のみです
• 代わりに subject_type: "file" を指定して、ファイルレベルのコメントを追加してください
• 非推奨の position パラメーターが必要な場合でも、get_pr_changes_for_commenting を使用してパッチを確認し、有効な差分位置を特定できます

「Pull request not found」

• PR 番号が存在し、アクセス可能であることを確認します
• リポジトリへの読み取り権限があることを確認します
• PR が削除または移動されていないことを確認します

MCP サーバーの接続に関する問題

1. VSCode を再起動：MCP の接続を更新する必要がある場合があります
2. settings.json の構文を確認：MCP の設定が有効な JSON であることを確認します
3. npx のインストールを確認：npx mcp-gh-pr-mini --version を実行してテストします
4. デバッグログを有効化：環境変数に "DEBUG": "true" を追加します

デバッグモード

デバッグ環境変数を追加して、詳細なログを有効にします。

"mcp": {
  "servers": {
    "mcp-gh-pr-mini": {
      "command": "npx",
      "args": ["mcp-gh-pr-mini"],
      "env": {}
    }
  }
}

これにより、MCP サーバーのログに詳細な認証フローと API 呼び出しが表示されます。

サポート

問題が発生した場合：

1. 認証を確認する：gh auth status とトークンの権限を確認します
2. 最小限の例でテストする：まず公開リポジトリで PR の一覧表示を試します
3. デバッグログを確認する：デバッグモードを有効にして、詳細なエラー情報を確認します
4. 問題を報告する：デバッグログと具体的なエラーメッセージを含めます

📝 変更履歴

バージョン 1.4.0（2025-12-01）

• ✨ オプションの draft パラメーターによるドラフト PR 作成のサポートを追加
• 🎯 実装が完了する前に、ドラフトとして PR を作成
• 📊 成功メッセージにドラフトの状態を表示
• ✅ ドラフト PR 機能の包括的なテストカバレッジ

バージョン 1.3.0（2025-11-07）

• ✨ 詳細な PR 情報（タイトル、本文、状態、作成者、ブランチ）を取得する get_pull_request ツールを追加
• 📚 gh pr view --json title,body と同様の機能

バージョン 1.2.0

• 既存の PR を変更する update_pull_request ツールを追加
• PR の一部更新（タイトル、本文、状態、ベース）をサポート

バージョン 1.1.0

• コアとなる PR 管理機能を備えた初回リリース

🙏 お願い

MCP サーバーの構築はまだ始めたばかりなので、改善できる点があるかもしれません。 フィードバック、提案、コントリビューションをいつでも歓迎します！