GitHub Model Context Protocol (MCP) サーバーとツール呼び出し評価

読み取り操作と確認ゲート付き書き込み操作を公開する本番グレードの FastMCP GitHub サーバー。ツール選択、引数の正確性、破壊的操作の確認安全性を評価する30ケースの評価ハーネスを備えています。

エグゼクティブサマリーと評価マトリクス

LLMエージェントのツール呼び出しには厳格な安全境界が必要です。このMCPサーバーは、すべての変更操作に対してサーバーレベルの確認ゲートを適用します。未確認のリクエストはGitHub上で変更を実行せず、ドライラン・プレビューを返します。

ベンチマーク性能（30のラベル付きシナリオ）

標準的なツール呼び出し、指定不足・曖昧なクエリ、破壊的な確認ゲート付きアクションをテストする30ケースのベンチマークで評価しました：

Related MCP server: github-mcp-tool

ツールアーキテクチャと操作

flowchart TD
    A[User Request] --> B[LLM Tool-Calling Engine]
    B --> C{Tool Category}
    
    C -- Read Tool --> D[Execute GitHub API Call Directly]
    D --> E[Return API Payload]
    
    C -- Write / Destructive --> F{confirm == true ?}
    F -- Yes --> G[Execute State Mutation on GitHub]
    G --> H[Return Success / Number / URL]
    
    F -- No --> I[Return Dry-Run Preview of Mutation]

利用可能なツール

読み取り操作（即時実行）

• list_issues(owner, repo, state): リポジトリ内のオープン／クローズ済みのイシューを一覧表示します。

• get_issue(owner, repo, issue_number): 単一イシューの詳細なメタデータを取得します。

• list_pull_requests(owner, repo, state): リポジトリ内のプルリクエストを一覧表示します。

• get_pull_request(owner, repo, pr_number): PRの詳細とマージ可否を取得します。

• search_code(query, owner, repo): GitHubコードベースをグローバルまたはリポジトリ単位で検索します。

破壊的操作（確認ゲート付き）

• create_issue(owner, repo, title, body, confirm=False): 確認された場合のみイシューを作成します。それ以外の場合はプレビューを返します。

• close_issue(owner, repo, issue_number, confirm=False): 確認された場合のみイシューをクローズします。それ以外の場合はプレビューを返します。

• add_comment(owner, repo, issue_number, body, confirm=False): 確認された場合のみイシュー／PRにコメントします。それ以外の場合はプレビューを返します。

• merge_pull_request(owner, repo, pr_number, confirm=False): 確認された場合のみPRをマージします。それ以外の場合はプレビューを返します。

プロジェクト構成

├── app/
│   ├── __init__.py          # Public MCP server & client exports
│   ├── server.py            # FastMCP server definition & tool routing
│   └── github_client.py     # GitHub REST API client with dry-run previews
├── eval/
│   ├── __init__.py          # Evaluation package
│   ├── tool_schemas.py      # OpenAI-compatible function definitions & prompt
│   ├── test_set.json        # 30 labeled evaluation test cases
│   └── run_eval.py          # Benchmark harness scoring tool, args, and confirm flags
├── requirements.txt         # Dependencies (mcp, requests, openai)
├── WRITEUP.md               # Detailed evaluation report & iteration analysis
└── README.md

クイックスタートと使用方法

1. インストール

git clone https://github.com/vishalmurugan1986/github-mcp-server.git
cd github-mcp-server

pip install -r requirements.txt

2. 環境設定

export NVIDIA_API_KEY="nvapi-your-key-here"
# Optional: real GitHub write access
export GITHUB_TOKEN="ghp_your_personal_access_token"

3. MCPサーバーの実行

python -m app.server

標準I/O経由でMCPクライアント（Claude Desktopやカスタムエージェントなど）を接続します。

4. ツール呼び出し評価スイートの実行

python -m eval.run_eval

結果は eval/results.json に保存され、完全な指標の内訳とともに出力されます。

安全設計の原則

1. 多層防御による確認: プロンプトの指示だけに頼るのではなく、確認ガードは app/github_client.py に直接ハードコードされています。未確認のリクエストが誤って変更を引き起こすことはありません。

2. 曖昧さの拒否: リポジトリ、イシュー番号、パラメータが指定されていない場合は、モデルは実行を拒否して明確化の質問をするよう指示されており、プレースホルダーの幻覚を回避します。