Repo Graphrag MCP

🚀 Repo GraphRAG MCP 服務器

Repo GraphRAG MCP 服務器是一個 MCP（模型上下文協議）服務器，它使用 LightRAG 和 Tree-sitter 從倉庫或目錄中的代碼和基於文本的文檔（僅文本，不解析 PDF/Word/Excel 文件）構建知識圖譜，並利用該圖譜進行問答和實現規劃。 它提供了用於圖譜構建（graph_create）、實現規劃（graph_plan）和問答（graph_query）的工具。

• 📊 知識圖譜創建（graph_create）：分析代碼/文檔以構建知識圖譜和嵌入索引（支持增量更新）
• 🔧 實現規劃（graph_plan）：根據知識圖譜（可選地結合向量搜索）為修改/添加請求輸出實現計劃和具體的更改步驟
• 🔍 問答（graph_query）：根據知識圖譜（可選地結合向量搜索）回答問題

🚀 快速開始

前提條件

• 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

# 用於規劃和問答的提供商
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

# 用於規劃和問答的 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 - 問答

根據知識圖譜（可選地結合向量搜索），回答有關目標倉庫/目錄的問題。使用 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：全局社區搜索

令牌預算（輸入側）

輸入側令牌預算控制為規劃和問答組裝的上下文量（LightRAG QueryParam）。這些與模型輸出令牌限制無關。

• MAX_TOTAL_TOKENS：每個查詢的總體輸入上下文預算（實體 + 關係 + 檢索到的塊 + 系統提示）。默認值：30000。
• MAX_ENTITY_TOKENS：實體上下文的預算（輸入側）。默認值：6000。
• MAX_RELATION_TOKENS：關係上下文的預算（輸入側）。默認值：8000。

注意：輸出令牌限制通過 GRAPH_ANALYSIS_MAX_TOKEN_SIZE（用於規劃/問答）和 GRAPH_CREATE_MAX_TOKEN_SIZE（用於圖譜創建任務）分別控制。如果顯著增加輸入預算，請確保您的模型的總上下文窗口能夠容納輸入和輸出。

實體合併

此 MCP 可以根據語義相似度將從文檔中提取的實體與從代碼中提取的實體進行合併。目標是將引用（例如，代碼中定義並在文檔中提及的類或函數）統一為一個合併後的實體。

• 工作原理：名稱通過排除規則進行規範化和過濾；文檔實體和當前遍代碼實體進行嵌入，並使用餘弦相似度（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 文件。