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 文件。