github-repo-mcp

github-repo-mcp

あらゆる AI エージェント（Claude Desktop、Claude Code、Cursor）が、人間が README、コミットログ、イシュートラッカーを手作業で読むのではなく、公開 GitHub リポジトリについて直接推論できるようにする MCP（Model Context Protocol）サーバーです。

これが存在する理由

なじみのないリポジトリを評価する（「活発にメンテナンスされているか？」「この issue は本当に初心者向けか？」「最近何が変わったか？」）のは、すべての開発者が行う反復的な手作業です。このサーバーは、その作業を、MCP 対応のエージェントが使える 4 つの呼び出し可能なツールに変えます。

ツール

ツール	機能
get_repo_health	コミットの新しさ、issue のトリアージ率、コントリビューター数に基づく、決定論的な 0～100 の健全性スコアです。アーカイブ済みのリポジトリにはすぐにフラグを立てます。
summarize_recent_commits	過去 N 日間のコミットを種類（feature／fix／docs／refactor／chore）別に分類し、「何が変わったか」をすばやく確認できるようにします。
find_good_first_issues	初心者向けラベルの付いた issue を見つけ、それぞれの実際のわかりやすさを評価し、誤ったラベルが付いているように見えるもの（例：「good first issue」タグが付いているにもかかわらず、コアアーキテクチャに関わるもの）にフラグを立てます。
ask_repo	埋め込みベースのセマンティック検索（Voyage AI + Qdrant コサイン類似度）を使い、README + docs/*.md + 上位の issue スレッドを対象に自由記述形式で Q&A を行います。

セットアップ

npm install
cp .env.example .env
# Add a GitHub personal access token to .env — raises the rate limit from 60/hr to 5000/hr.
# No special scopes needed for public repo data: https://github.com/settings/tokens
#
# ask_repo also needs, both free tier:
#   VOYAGE_API_KEY  — https://dashboard.voyageai.com/ (API Keys -> Create new key)
#   QDRANT_URL, QDRANT_API_KEY — https://cloud.qdrant.io/ (create a free cluster)
npm run build

Claude Desktop でローカル実行する

Claude Desktop の MCP 設定（claude_desktop_config.json）に次の内容を追加します。

{
  "mcpServers": {
    "github-repo-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/github-repo-mcp/build/index.js"],
      "env": { "GITHUB_TOKEN": "your_token_here" }
    }
  }
}

Claude Desktop を再起動してから、次のように試してください。「github-repo-mcp を使って facebook/react の健全性を確認し、初心者向けの issue を 1 つ見つけてください。」

アーキテクチャに関する補足

• スクレイピングではなく GitHub API — トークンを使えば、明確に文書化されており、レート制限にも十分な余裕があります。
• 決定論的なスコアリング、生成的な説明 — get_repo_health のスコアは固定の計算式（新しさ + issue のトリアージ + コントリビューターの多様性）に基づくもので、LLM による推測ではありません。これにより、数値を再現可能に保てます。呼び出し元のエージェントにいる LLM が、その数値をもとに「なぜそうなのか」を説明できます。
• find_good_first_issues による誤ラベルの検出 — 実際には「good first issue」ラベルが誤って付けられていることがよくあります。このツールは、本文の長さ、警戒すべきキーワード（architecture、migration、security）、コメント数を確認し、誤ったラベルの issue を検出します。ラベルが付いているものをそのまま提示するだけではありません。

デモ

docs/demo.md では、facebook/react を対象とした実際の（モックではない）プロトコルのやり取りを紹介しています。埋め込みベースの ask_repo が、ソーステキストと共通する単語がないクエリに対して正しい回答を取得する例も含まれています。

ask_repo の検索の仕組み

ask_repo は当初、README を対象としたキーワードベースのウィンドウ検索として始まり（git の履歴を参照）、src/rag.ts に実装された埋め込みベースの RAG にアップグレードされました。

1. リポジトリに対する初回のクエリ時に、README と docs/*.md（トップレベルのファイル、最大 15 件）、さらに最も議論された上位 8 件のイシュースレッド（タイトルと本文、約 500 語のチャンク、50 語のオーバーラップ）を分割します
2. 各チャンクを Voyage AI（voyage-3.5-lite）で埋め込みます
3. ベクトルを Qdrant Cloud に保存します。リポジトリごとに 1 つのコレクション（repo_<owner>_<name>）を使用します
4. クエリごとに、質問を埋め込み、コサイン類似度検索で上位 5 件のチャンクを取得します
5. 同じリポジトリへの2回目以降のクエリでは、コレクションの points_count で確認して再インデックスを省略します。埋め込まれるのはクエリ自体のみです

キーワードマッチングより埋め込みを使う理由： キーワードの重複が必要な検索では、文字どおり同じ単語が含まれていなければなりません。「React をインストールするには？」という質問と「はじめに」というタイトルの README セクションには共通する単語がないため、決してマッチしません。埋め込みでは、正確な言い回しに関係なく、意味的に類似したテキストがベクトル空間上で近くに配置されます。そのため、言い換えや同義語にも対応でき、キーワード検索で実際に発生する検索失敗を防げます。

既知の簡略化（src/rag.ts の ponytail: コメントで示されています）。それぞれに明記されたアップグレード方法があります。

• イシュースレッドでは、コメントのやり取り全体ではなく、タイトルと本文のみをインデックス化します（Issue ごとに追加の API 呼び出しが 1 回必要になるのを避けます）。回答に元の報告だけでなく解決に関する議論も反映する必要がある場合は、/issues/{n}/comments を取得してください。
• チャンクのサイズは、実際のトークナイザーではなく、トークン数の近似値として単語数を使用します。
• 古さのチェックはありません。一度インデックス化されたリポジトリは、ドキュメントが変更されてもインデックス化されたままです。コンテンツが古くなる場合は、TTL を追加するか、保存済みのインデックスと pushed_at を照合してください。

ライセンス

MIT