GitHub GraphQL API MCP

# GitHub GraphQL API MCP [English](README.md) | [中文](README_zh.md) | [日本語](README_ja.md) | [Español](README_es.md) | [Français](README_fr.md) GitHub GraphQL APIのクエリと使用のためのMCP（Model Context Protocol）ベースのツールです。このプロジェクトは、MCP クライアントツール（Claude AIなど）を通じてGitHub GraphQLスキーマを探索し、GraphQLクエリを実行できるサーバーを提供します。 ## 目次 - [なぜGitHub GraphQL APIを使用するのか](#なぜgithub-graphql-apiを使用するのか) - [アプリケーションシナリオ](#アプリケーションシナリオ) - [特徴](#特徴) - [公式 GitHub MCP Server との比較](#公式-github-mcp-server-との比較) - [前提条件](#前提条件) - [インストールと使用方法](#インストールと使用方法) - [Claudeデスクトップでの設定](#claudeデスクトップでの設定) - [利用可能なツール](#利用可能なツール) - [使用例](#使用例) - [注意事項](#注意事項) - [ライセンス](#ライセンス) ## なぜGitHub GraphQL APIを使用するのか GitHub GraphQL APIは従来のREST APIに比べて大きな利点があります： - **必要なデータの正確な取得**：GraphQLはクライアントが必要なフィールドを正確に指定できるため、余分なデータの取得を避けられます - **トークン消費の削減**：必要なフィールドのみをリクエストすることで、APIレスポンスのサイズが大幅に削減され、AIモデルのトークン消費を抑えられます - **関連データを一度のリクエストで取得**：一つのクエリで複数の関連リソースを取得でき、リクエスト数を減らせます - **自己文書化**：内蔵のドキュメントシステムにより、外部ドキュメントなしでAPIスキーマを直接照会し理解できます - **強力な型システム**：型チェックを提供し、エラーを減らします このプロジェクトはこれらの利点を活用し、GitHub GraphQL APIスキーマを効果的に探索し、最適化されたクエリを実行するためのツールを提供して、AIアシスタントに効率的なGitHubデータ取得機能を提供します。 ## アプリケーションシナリオ ### 基本機能 このツールは以下の一般的な操作を簡単に実行できます： 1. **リポジトリ基本情報クエリ**：リポジトリ名、説明、スター数、ブランチリストなどの基本情報を取得 2. **課題データの検索**：特定のリポジトリの課題リスト、詳細、またはコメント内容をクエリ 3. **ユーザープロフィールアクセス**：ユーザーの個人プロフィール、貢献統計などの公開情報を取得 4. **Pull Requestステータス表示**：PRの基本ステータス、コメント内容、マージ情報を取得 5. **プロジェクト依存関係クエリ**：プロジェクトの依存パッケージリストとバージョン情報を検索 ### 高度な探索機能 GraphQLの柔軟なクエリ機能により、以下の高度な分析機能も実装できます： 1. **リポジトリ貢献傾向分析**：コミットデータを集計して、コード更新頻度と貢献者の参加度を分析し、プロジェクトの活動度を評価 2. **課題管理と分類**：カスタム条件に従って課題データを整理し、優先的に処理すべき問題を発見してプロジェクト管理効率を向上 3. **コードレビューパターン分析**：PRコメントとレビュープロセスを分析し、共通の問題パターンを特定してコードレビューワークフローを最適化 4. **貢献者ネットワーク可視化**：プロジェクト貢献者間のコラボレーション関係を構築し、主要な貢献者と専門分野を発見 5. **依存関係の健全性評価**：プロジェクト依存関係の更新頻度と潜在的なセキュリティ問題を評価し、依存関係管理の提案を提供 ## 特徴 - GitHub GraphQLスキーマのルートタイプ（Query/Mutation）のクエリ - 特定タイプの詳細ドキュメントの取得 - 特定フィールドのドキュメントとパラメータのクエリ - GitHub GraphQL APIクエリを直接実行し、必要なデータを正確に取得してトークン消費を削減 - 多言語サポート（英語/中国語/日本語など） ## 公式 GitHub MCP Server との比較 公式の [github-mcp-server](https://github.com/github/github-mcp-server) と比較して、このプロジェクトは特定のシナリオにおいて明確な利点を提供します： | 機能 | GitHub GraphQL API MCP | 公式 GitHub MCP Server | |------|------------------------|------------------------| | **コアメカニズム** | 単一の GraphQL クエリ | 複数の REST API / 粒度の細かいツール | | **データ取得** | **ワンショット**：リポジトリの詳細、Issue、PR、履歴、リリースを一度のリクエストで取得可能 | **マルチステップ**：`search_repositories`、`get_file_contents`、`list_commits` など、複数のツールを連鎖させる必要がある | | **効率** | 高い。ネットワーク遅延と往復回数を最小限に抑える。 | 複雑なデータ収集では低い。連続したツール呼び出しによる高い遅延が発生する。 | | **トークン使用量** | **最適化**。リクエストされたフィールドのみを返す。 | **高い**。中間ツールの出力（完全な JSON レスポンス）がコンテキストウィンドウを消費する。 | | **柔軟性** | **高い**。クライアントが必要な正確なデータ構造を定義できる。 | **固定**。クライアントは事前定義された API レスポンス構造を使用する必要がある。 | | **API カバレッジ** | **完全**。GitHub GraphQL API で公開されているすべてのフィールドにアクセス可能。 | **部分的**。メンテナによってハードコードされた特定の REST エンドポイントに限定される。 | | **イントロスペクション** | **組み込み**。AI はスキーマをクエリして新しい API フィールドについて動的に学習できる。 | **なし**。AI はトレーニングデータに依存する。ツールの更新なしに新しい API 機能を発見できない。 | | **保守性** | **ゼロコード更新**。多くの場合、GitHub の新機能をサポートするためにスキーマファイルを更新するだけで済む。 | **コード重視**。新機能ごとに新しい Go ハンドラと構造体定義を作成する必要がある。 | | **複雑さ** | LLM が GraphQL を記述する必要がある（スキーマイントロスペクションツールによってサポート）。 | 単純な関数呼び出しを好む LLM には簡単だが、呼び出し間の状態管理が難しい。 | **例**：「プロジェクトの最新の重要な更新」を取得するには、このツールはリリース、最近のコミット、未解決の Issue を**一度に**取得できますが、公式サーバーでは 5 回以上の個別のツール呼び出しと往復が必要になる場合があります。 ### AI エージェントにとって重要な理由 1. **コンテキストウィンドウの効率**：公式ツールはしばしば巨大な JSON オブジェクト（例：完全なリポジトリオブジェクトは 5KB 以上になることがある）を返します。GraphQL を使用すると、`name` と `description` のみを取得でき、トークンを 99% 節約できます。これは長い会話や複雑なタスクにとって重要です。 2. **複雑な推論**：AI エージェントはしばしばデータ関係をたどる必要があります（例：「この Issue をクローズした PR の作成者を見つける」）。REST/公式ツールでは、これは「検索 -> ID 取得 -> PR 取得 -> 作成者取得」というマルチステップのプロセスになります。GraphQL では、これは単一のネストされたクエリであり、AI はデータの配管ではなく論理的な推論に集中できます。 3. **将来への対応**：GitHub が新機能（例：Discussions の新しいフィールド）を追加した場合、この MCP サーバーはスキーマイントロスペクションを通じて即座にサポートできますが、公式サーバーはコードの更新を待つ必要があります。 ## 前提条件 - Python 3.10以上 - GitHub個人アクセストークン（GitHub APIにアクセスするため） - Poetry（推奨される依存関係管理ツール） ## インストールと使用方法 管理には現在最速かつ最もシンプルなPythonプロジェクト管理ツールである[uv](https://github.com/astral-sh/uv)を使用することをお勧めします。また、標準のpipを使用することもできます。 ### 方法1：uvを使用する（推奨、最速） uvを使用すると、仮想環境を手動で作成したり依存関係をインストールしたりする必要はなく、すべて自動的に処理されます。 1. **uvをインストール**（すでにインストール済みの場合はスキップ）： ```bash # MacOS / Linux curl -lsSf https://astral.sh/uv/install.sh | sh # Windows powershell -c "irm https://astral.sh/uv/install.ps1 | iex" ``` 2. **環境変数を設定**： `.env.example`を`.env`にコピーし、GitHubトークンを入力します： ```bash cp .env.example .env # .envファイルを編集してトークンを入力 ``` 3. **ワンクリック実行**： ```bash uv run github_graphql_api_mcp_server.py ``` *uvは自動的に仮想環境を作成し、すべての依存関係をダウンロードしてインストールし、サーバーを起動します。* ### 方法2：標準のpip 追加のツールをインストールしたくない場合は、従来のPython方式を使用できます： 1. **仮想環境の作成と有効化**： ```bash python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate ``` 2. **依存関係のインストール**： ```bash pip install -r requirements.txt ``` 3. **環境変数を設定**： 上記と同様に`.env`ファイルを作成して設定します。 4. **実行**： ```bash python github_graphql_api_mcp_server.py ``` ## Claudeデスクトップでの設定 Claudeデスクトップアプリでこのサーバーを設定し、ワンクリックで起動できます： 1. Claudeデスクトップアプリを開く 2. 設定に移動し、MCPサーバー設定セクションを見つける 3. 以下の設定を追加（実際のパスに合わせて修正）： ```json { "mcpServers": { "github_mcp": { "command": "/path/to/uv", "args": [ "run", "--directory", "<プロジェクトパス>", "github_graphql_api_mcp_server.py" ] } } } ``` 設定例（uvを使用）： ```json { "mcpServers": { "github_mcp": { "command": "/Users/username/.cargo/bin/uv", "args": [ "run", "--directory", "/Users/username/github/github_graphql_api_mcp/", "github_graphql_api_mcp_server.py" ] } } } ``` 標準Pythonを使用する場合（方法2）： ```json { "mcpServers": { "github_mcp": { "command": "/path/to/project/.venv/bin/python", "args": [ "github_graphql_api_mcp_server.py" ] } } } ``` 設定完了後、Claudeデスクトップアプリから直接MCPサーバーを起動できるため、手動での起動が不要になります。 ### 利用可能なツール サーバーは以下のツールを提供します： 1. **print_type_field**：GitHub GraphQLスキーマのルートタイプのフィールドをクエリ 2. **graphql_schema_root_type**：ルートタイプ（Query/Mutation）のドキュメントを取得 3. **graphql_schema_type**：特定タイプのドキュメントをクエリ 4. **call_github_graphql**：GitHub GraphQL APIクエリを実行 ### 使用例 MCPクライアントでサーバーに接続した後、以下が可能です： 1. ルートタイプのドキュメントをクエリ： ``` graphql_schema_root_typeツールを使用、パラメータtype_name="QUERY" ``` 2. 特定タイプのフィールドをクエリ： ``` print_type_fieldツールを使用、パラメータtype_name="QUERY", type_fields_name="repository" ``` 3. 特定タイプのドキュメントをクエリ： ``` graphql_schema_typeツールを使用、パラメータtype_name="Repository" ``` 4. GraphQLクエリを実行： ``` call_github_graphqlツールを使用、パラメータ： graphql=""" query { viewer { login name } } """ ``` #### スクリーンショット例 以下はGitHub GraphQL API MCPをClaudeで使用する例です：  ## 注意事項 - 使用前にGitHubトークンが適切な権限を持っていることを確認 - トークンは`.env`ファイルに保存され、このファイルはバージョン管理システムにコミットすべきではない - クエリはGitHub APIの使用制限に従う必要がある ## ライセンス このプロジェクトはMITライセンスの下で提供されています。これは非常に寛容なライセンスで、著作権表示とライセンス表示を保持する限り、ユーザーは自由にこのソフトウェアを使用、修正、配布、商用化することができます。 詳細な条件については[MITライセンス](https://opensource.org/licenses/MIT)を参照してください。