GitHub MCP Server

安全で構造化されたツールを使って、AI アシスタントが GitHub とやり取りできるようにするプロジェクトです。

わかりやすく言うと、AI が GitHub の仕組みを推測するのではなく、このプロジェクトは「自分のリポジトリを一覧表示する」「オープンな Issue を表示する」「ファイルを読み取る」といった明確なアクションメニューを AI に提供します。AI が適切なアクションを選び、このサーバーが GitHub と通信し、AI が理解できるクリーンな形式で答えが返ってきます。

これは何を解決するのか

チャットボットは言葉を扱うのは得意ですが、あなたの GitHub アカウントに自動的にライブアクセスすることはできません。

このプロジェクトが作るのは、その間を取り持つ橋です:

1. あなたが普通の英語で質問します（例:「Show open issues in microsoft/vscode」）。

2. AI モデル（Groq）がどの GitHub ツールを使うかを判断します。

3. MCP サーバーが、実際の GitHub API に対してそのツールを実行します。

4. 結果をクリーンに整形（正規化）して AI に返します。

5. AI がその結果をあなたにわかりやすい言葉で説明します。

MCP とは Model Context Protocol のことです。標準的なプラグのようなものだと考えてください。互換性のある AI クライアントは、このサーバーに接続してそのツールを利用できます。

Related MCP server: GitHub MCP Server

全体像（アーキテクチャ）

You
  ↓
AI Agent (client/agent.py)  ← talks to Groq LLM
  ↓
MCP Server (notebooks/server.py)  ← menu of GitHub tools
  ↓
GitHub Client  ← HTTP calls with your token
  ↓
GitHub REST API
  ↓
GitHub

設計ルール（重要）

ツールは薄く保ちます:

1. 入力をチェックする（リポジトリ名は有効か?）。

2. GitHub クライアントを呼び出す。

3. レスポンスを安定した形に正規化する。

4. そのクリーンなデータをエージェントに返す。

GitHub の複雑な部分はすべてクライアント層の中に留めます — ツール全体に散らばらせません。

プロジェクトフォルダ（各パートの役割）

ツールでできること

サーバーは数多くの GitHub アクションを公開しています。シンプルにグループ化すると:

読み取り（安全に探索）

• 自分のリポジトリを一覧表示する

• リポジトリの詳細を取得する

• Issue とプルリクエストを一覧 / 取得する

• PR の差分を取得する

• ブランチ、コミット、ラベルを一覧表示する

• リポジトリ内のコードを検索する

• ファイルの内容を読み取る

• GitHub Actions ワークフローの実行を一覧表示する

書き込み（GitHub に変更を加える）

• Issue、コメント、PR、ブランチ、ラベルを作成する

• Issue を更新する、ラベルを追加 / 削除する

• Issue を再オープンする

破壊的（壊す可能性あり — 保護されています)

これらはデフォルトで追加の確認が必要です:

• merge_pull_request

• delete_file

• create_repository

• create_or_update_file

• close_issue

これらのツールでは、エージェントは通常、次の手順を踏みます:

1. dry_run=true で呼び出す → プレビューにのみ留める

2. もう一度 confirm=true で呼び出す → 実際に実行する

この挙動は環境変数で厳しくも緩くもできます（下記参照）。

正規化されたレスポンス（AI がこれを好む理由）

生の GitHub レスポンスは巨大で、しかも頻繁に変わります。このプロジェクトは安定した形を返します。

一覧系ツール（list tools） は常に次のようになります:

{
  "count": 20,
  "items": [ ... ],
  "page": 1,
  "per_page": 20,
  "has_next": true,
  "has_prev": false,
  "next_page": 2,
  "prev_page": null,
  "last_page": 5
}

次のページを取得するには、同じツールを page=2（または page=next_page）で再び呼び出します。

Issue の例:

{
  "number": 42,
  "title": "Bug in login",
  "state": "open",
  "author": "some-user",
  "labels": ["bug"],
  "comments": 3,
  "html_url": "https://github.com/...",
  "is_pull_request": false
}

補足: get_issues はプルリクエストを除外します（GitHub の issues API はプルリクエストが混ざって返ってくるため）。

安全機能

環境変数（任意）:

GITHUB_MCP_DESTRUCTIVE_MODE=confirm
GITHUB_MCP_DESTRUCTIVE_ALLOWLIST=merge_pull_request,delete_file

ロギング（デバッグ用）

サーバーはJSON ログを stderr のみに出力します。

なぜ stderr か? MCP はプロトコルに stdout を使うからです。もし stdoutにログを出力すると、AI との接続が壊れてしまいます。

ログに記録されるもの:

• リクエストメソッドとパス

• HTTP ステータス

• 所要時間

• 残りのレート制限

記録されないもの:

• GitHub トークン

• Authorization ヘッダー

• 秘密情報のように見える値（PAT、Bearer トークン等）

ログ行の例:

{"ts":"2026-08-23T12:00:00+00:00","level":"INFO","event":"github_request","method":"GET","path":"/repos/microsoft/vscode/issues","status_code":200,"duration_ms":120.5}

AI エージェント（client/agent.py）

エージェントは:

1. MCP サーバーをサブプロセスとして起動する（notebooks/server.py）。

2. サーバーからツールの一覧を取得する。

3. あなたの質問とツール一覧を Groq に送信する。

4. Groq がツールを必要とするなら、エージェントは MCP 経由でそれを呼び出す。

5. ツールの結果を Groq に送り返して、最終的な回答を得る。

便利なコマンド（プロジェクトフォルダで、仮想環境を有効にした状態）:

# See all registered tools
python client/agent.py --list-tools

# Only show which tool the AI would pick (no GitHub write)
python client/agent.py --dry-run "list my github repos"

# One real question, then exit
python client/agent.py --once "show open issues for microsoft/vscode"

# Interactive chat
python client/agent.py

# Check tool-picking quality on many sample prompts
python client/test_tool_picking.py

ループの上限（任意）:

python client/agent.py --max-rounds 5 --once "..."

または .env 内で:

AGENT_MAX_TOOL_ROUNDS=8
AGENT_MAX_TOOL_CALLS=16
AGENT_MAX_CONSECUTIVE_ERRORS=3

環境変数

MCP サーバーに必須

エージェント（チャット / ツール選択）に必須

任意

.env.example を .env にコピーして実際の値を記入してください。完全な手順は SETUP.md を参照してください。

技術スタック（知りたい向け）

• Python 3.13+（プロジェクトは 3.13 で開発）

• MCP（mcp Python パッケージ）— ツールサーバーのプロトコル

• httpx — GitHub 通信用 HTTP クライアント

• Pydantic — スキーマ / バリデーション

• python-dotenv — .env の読み込み

• OpenAI 互換クライアント → エージェントには Groq

• Jupyter（任意）— 学習用ノートブック

セットアップと実行方法

丁寧なガイドはこちら:

👉 SETUP.md — Python のインストール、キーの作成、.env の設定、最初のコマンドの実行まで。

簡易版（Python をすでに知っている場合）:

cd "path\to\Github-MCP-server"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env
# edit .env with your tokens
python client/agent.py --list-tools
python client/agent.py --once "list my github repos"

学習パス（推奨）

1. この README を読む（いまここです）。

2. SETUP.md を完了し、--list-tools が動くようにする。

3. docs/ARCHITECTURE_HLD_LLD.md で HLD + LLD のフローを読む。

4. 読み取りのみのシンプルな質問で --dry-run と --once を試す。

5. 50 シナリオの手動テスト計画を実行する: tests/MANUAL_TESTING_50_SCENARIOS.md

   • 自動ツール選択: python client/run_manual_scenarios.py

6. notebooks/01_github_mcp_server.ipynb を開いて各レイヤがどう作られたかを見る。

7. それから初めて、dry_run + confirm を使った書き込み / 破壊的ツールを試す。

トラブルシューティング（早見）

***

## セキュリティの注意

* `.env` をコミットしないこと。
* GitHub や Groq のトークンをチャット、スクリーンショット、GitHub Issues に貼り付けないこと。
* **必要なスコープだけ**を持つ GitHub トークンを選ぶこと。
* 環境を完全に信頼できる場合を除き、`GITHUB_MCP_DESTRUCTIVE_MODE=confirm`（また `deny`）を維持すること。
* 古い実験で `server_1.py` がトークンを表示していたなら、そのデバッグ出力を共有しない — `server.py` を使うこと。

***

## ライセンス・所有権

これは GitHub MCP サーバーとエージェントの個人的な学習用 Gen-AI プロジェクトです。公開前に必要な所有権とライセンスを調整してください。