Repo Graphrag MCP

🚀 Repo GraphRAG MCP Server

Repo GraphRAG MCP Serverは、MCP（Model Context Protocol）サーバーです。LightRAGとTree-sitterを使用して、リポジトリやディレクトリ内のコードとテキストベースのドキュメント（テキストのみ；PDFやWord、Excelは解析されません）から知識グラフを構築し、Q&Aや実装計画に活用します。 グラフ構築（graph_create）、実装計画（graph_plan）、Q&A（graph_query）のためのツールを提供します。

• 📊 知識グラフの作成（graph_create）：コードやドキュメントを分析して知識グラフと埋め込みインデックスを構築します（増分更新に対応）
• 🔧 実装計画（graph_plan）：知識グラフに基づいて、修正や追加の要求に対する実装計画と具体的な変更手順を出力します（必要に応じてベクトル検索と組み合わせることができます）
• 🔍 Q&A（graph_query）：知識グラフに基づいて質問に回答します（必要に応じてベクトル検索と組み合わせることができます）

目次

• 🚀 クイックスタート
  • 1. インストール
  • 2. 環境設定
  • 3. 環境変数（LLM設定）
  • 4. MCPクライアントの設定
  • 5. 使用方法
• ⚙️ 設定オプション
  • LLMプロバイダー
  • 埋め込みモデル
  • graph_planとgraph_queryの計画/クエリ設定
  • エンティティのマージ
  • 詳細な環境変数
• 🧬 サポートされる言語
• 🏗️ MCP構造
• 🛠️ スタンドアロン実行
• 🙏 謝辞
• 📄 ライセンス

🚀 クイックスタート

前提条件

• Python 3.10以上
• uvパッケージマネージャー
• 選択したLLMプロバイダーの資格情報（必要な環境変数を設定します；以下のLLMプロバイダーのセクションを参照）

1. インストール

# GitHubからクローン
git clone https://github.com/yumeiriowl/repo-graphrag-mcp.git
cd repo-graphrag-mcp

# 依存関係のインストール
uv sync

2. 環境設定

# 設定ファイルのコピー
cp .env.example .env

# 設定ファイルの編集
nano .env  # または任意のエディター

3. 環境変数（LLM設定）

.envファイルで設定を構成します。

例：Anthropicモデルの使用

# グラフ作成用のLLMプロバイダー
GRAPH_CREATE_PROVIDER=anthropic  # またはopenai、gemini、azure_openai

# 計画とQ&A用のプロバイダー
GRAPH_ANALYSIS_PROVIDER=anthropic # またはopenai、gemini、azure_openai

# APIキー（選択したプロバイダーに対応する変数を設定）
ANTHROPIC_API_KEY=your_anthropic_api_key # またはopenai、gemini、azure_openai

# AZURE_OPENAI_API_KEY=your_azure_openai_api_key
# AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
# AZURE_API_VERSION=azure_openai_api_version

# OPENAI_API_KEY=your_openai_api_key
# OPENAI_BASE_URL=http://localhost:1234/v1  # LM Studioまたは他のOpenAI互換のローカルサーバー用

# GEMINI_API_KEY=your_gemini_api_key

# グラフ作成用のLLMモデル
GRAPH_CREATE_MODEL_NAME=claude-3-5-haiku-20241022

# 計画とQ&A用のLLMモデル
GRAPH_ANALYSIS_MODEL_NAME=claude-sonnet-4-20250514

4. MCPクライアントの設定

Claude Code

claude mcp add repo-graphrag \
-- uv --directory /absolute/path/to/repo-graphrag-mcp run server.py

VS Code GitHub Copilot拡張機能

mcp.json:

{
  "servers": {
    "repo-graphrag-server": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/repo-graphrag-mcp",
        "run",
        "server.py"
      ]
    }
  }
}

その他のMCPクライアント

MCPプロトコルをサポートする任意のクライアントを使用できます。

5. 使用方法

MCPクライアントでは、以下のツールが利用可能です。すべてのコマンドはgraph:で始める必要があります。

graph_create - 知識グラフの構築/更新

対象のリポジトリ/ディレクトリを分析し、知識グラフとベクトル埋め込みインデックスを構築します（増分更新に対応）。GRAPH_CREATE_PROVIDERとGRAPH_CREATE_MODEL_NAMEを使用します。

要素:

• graph:（必須）
• 分析するディレクトリのパス（絶対パスが推奨）
• 作成するストレージ名（デフォルト: "storage"）

例:

graph: /absolute/path/to/your/repository my_project
graph: /absolute/path/to/your/repository my_project graphify
graph: C:\\projects\\myapp webapp_storage please create storage

増分更新について: 既存のストレージ名でgraph_createを再度実行すると、変更/追加/削除されたファイルのみが再分析され、それ以外はスキップされます。 埋め込みモデルや抽出設定（DOC_DEFINITION_LIST、NO_PROCESS_LIST、対象拡張子など）を変更した後に再構築する場合は、既存のストレージを削除するか、新しいストレージ名を指定してgraph_createまたはstandalone_graph_creator.pyで再作成します。

注意（パフォーマンス）: 最初のグラフ作成は、ファイル数が増えるにつれて時間がかかります。目安として、1000ファイル以上ある場合は、対象ディレクトリを絞り込むことを検討してください（処理時間は環境やファイルサイズに依存）。 増分更新では差分のみが再分析されるため、上記の目安は必ずしも更新に適用されません。

注意（初回ダウンロード）: 最初のグラフ作成時に指定された埋め込みモデルがキャッシュされていない場合、自動的にダウンロードされます（以降の実行ではキャッシュが使用されます）。

graph_plan - 実装サポート

知識グラフに基づいて（必要に応じてベクトル検索と組み合わせて）、MCPクライアント（エージェント）が実際の作業を実行できるように、詳細な実装計画と指示を提供します。GRAPH_ANALYSIS_PROVIDERとGRAPH_ANALYSIS_MODEL_NAMEを使用します。

要素:

• graph:（必須）
• 実装/修正要求
• ストレージ名（デフォルト: "storage"）

例:

graph: I want to add user authentication my_project
graph: my_project Add GraphQL support to the REST API
graph: Improve API performance under high load webapp_storage

graph_query - Q&A

知識グラフに基づいて（必要に応じてベクトル検索と組み合わせて）、対象のリポジトリ/ディレクトリに関する質問に回答します。GRAPH_ANALYSIS_PROVIDERとGRAPH_ANALYSIS_MODEL_NAMEを使用します。

要素:

• graph:（必須）
• 質問内容
• ストレージ名（デフォルト: "storage"）

例:

graph: Tell me about this project's API endpoints my_project
graph: my_project Explain the main classes and their roles
graph: About the database design webapp_storage

⚙️ 設定オプション

LLMプロバイダー

サポートされるプロバイダーと必要な環境変数

.envで識別子をGRAPH_CREATE_PROVIDER / GRAPH_ANALYSIS_PROVIDERとして指定します。

埋め込みモデル

• デフォルト: BAAI/bge-m3

• 互換性: Hugging Face sentence-transformers互換のモデルをサポート

• 初回実行: 指定された埋め込みモデルがキャッシュされていない場合、自動的にダウンロードされます。キャッシュの場所は環境や設定に依存します。ダウンロード時間とディスクスペースはモデルサイズに依存します。

• 認証が必要なモデル: 認証が必要なHugging Faceモデルの場合は、.envでHUGGINGFACE_HUB_TOKENを設定します。

  HUGGINGFACE_HUB_TOKEN=your_hf_token
  

graph_planとgraph_queryの計画/クエリ設定

実装に関する注意: このセクションの設定は、LightRAGの組み込みQueryParamに直接渡されます。このMCPは、カスタム検索やトークン予算のロジックを実装せず、LightRAGの動作をそのまま再利用します。

検索モード

検索モードはLightRAGに従います。.envのSEARCH_MODEに以下のいずれかを設定します。

• mix: ベクトル検索と知識グラフ検索の組み合わせ（推奨）
• hybrid: ローカル検索とグローバル検索の組み合わせ
• naive: 単純なベクトル検索
• local: コミュニティベースの検索
• global: グローバルコミュニティ検索

トークン予算（入力側）

入力側のトークン予算は、計画とQ&Aのためにどれだけのコンテキストを組み立てるかを制御します（LightRAG QueryParam）。これらはモデルの出力トークン制限とは独立しています。

• MAX_TOTAL_TOKENS: クエリごとの全体的な入力コンテキスト予算（エンティティ + 関係 + 検索されたチャンク + システムプロンプト）。デフォルト: 30000。
• MAX_ENTITY_TOKENS: エンティティコンテキストの予算（入力側）。デフォルト: 6000。
• MAX_RELATION_TOKENS: 関係コンテキストの予算（入力側）。デフォルト: 8000。

注意: 出力トークン制限は、GRAPH_ANALYSIS_MAX_TOKEN_SIZE（計画/Q&A用）とGRAPH_CREATE_MAX_TOKEN_SIZE（グラフ作成タスク用）で個別に制御されます。入力予算を大幅に増やす場合は、モデルの総コンテキストウィンドウが入力と出力の両方を収容できることを確認してください。

エンティティのマージ

このMCPは、ドキュメントから抽出されたエンティティとコードから抽出されたエンティティを意味的な類似性に基づいてマージすることができます。目的は、参照を統一することです（例えば、コードで定義され、ドキュメントで言及されたクラスや関数を1つの統合エンティティにまとめる）。

• 動作原理: 名前が正規化され、除外ルールを介してフィルタリングされます。ドキュメントエンティティと現在のパスのコードエンティティが埋め込まれ、コサイン類似度（FAISS）を使用して比較されます。閾値を超えるペアはマージされ、説明とファイルパスが統合されます。
• 制御:
  • MERGE_ENABLED（デフォルト: true）: エンティティマージを切り替えます。
  • MERGE_SCORE_THRESHOLD（デフォルト: 0.95）: マージのためのコサイン類似度の閾値。
  • 除外設定: MERGE_EXCLUDE_*リスト、プライベート名の除外、名前の長さの境界、およびカスタムパターン。
• 実行:
  • 有効にすると、マージはグラフ作成/更新フロー内で（エンティティ抽出後）実行されます。
  • スタンドアロンツールも実行できます: uv run standalone_entity_merger.py <storage_dir_path>

詳細な環境変数

すべての環境変数とデフォルト値は、.env.exampleを.envにコピーすることで構成できます。

すべての項目のクイックリファレンス

🧬 サポートされる言語 (v0.2.2)

以下の13の言語がサポートされています。

• Python
• C
• C++
• Rust
• C#
• Go
• Ruby
• Java
• Kotlin
• JavaScript
• TypeScript
• HTML
• CSS

🏗️ MCP構造

repo-graphrag-mcp/
├── README.md
├── CHANGELOG.md              # 変更履歴
├── LICENSE                   # ライセンス（MIT）
├── pyproject.toml            # パッケージ設定
├── server.py                 # MCPサーバーのエントリーポイント
├── .env.example              # 環境変数のテンプレート
├── standalone_graph_creator.py   # スタンドアロンのグラフビルダー
├── standalone_entity_merger.py   # スタンドアロンのエンティティマージャー
├── repo_graphrag/            # パッケージ
│   ├── config/               # 設定
│   ├── initialization/       # 初期化
│   ├── llm/                  # LLMクライアント
│   ├── processors/           # 分析/グラフ構築
│   ├── utils/                # ユーティリティ
│   ├── graph_storage_creator.py  # ストレージ作成
│   └── prompts.py            # プロンプト
└── logs/                     # ログ出力

🛠️ スタンドアロン実行

MCPクライアントなしでも実行できます。

standalone_graph_creator.py - 知識グラフの構築

リポジトリを分析して知識グラフを作成します。

uv run standalone_graph_creator.py <read_dir_path> <storage_name>

例:

uv run standalone_graph_creator.py /home/user/myproject my_storage
uv run standalone_graph_creator.py C:\\projects\\webapp webapp_storage

standalone_entity_merger.py - エンティティのマージ

既存のストレージ内のエンティティをマージします。

uv run standalone_entity_merger.py <storage_dir_path>

例:

uv run standalone_entity_merger.py /home/user/myproject/my_storage
uv run standalone_entity_merger.py C:\\projects\\webapp/webapp_storage

注意:

• ストレージディレクトリは、事前にgraph_createまたはstandalone_graph_creator.pyで作成する必要があります。

🙏 謝辞

このMCPは、以下のライブラリに基づいて構築されています。

• LightRAG - GraphRAGの実装
• Tree-sitter - コード解析

📄 ライセンス

このMCPは、MITライセンスの下で公開されています。詳細はLICENSEファイルを参照してください。