GraphRAG MCP服务器：面向LLM的生产级知识图检索
远程MCP（模型上下文协议）服务器在 全国大辩论 数据集。使用图优先架构查询具有8000多个实体的50个社区 比矢量RAG快29倍 内置出处追踪功能，将每个答案追溯到公民捐款。
实时端点（无需注册）:
https://graphragmcp-production.up.railway.app/mcp______________________________________________________________________
是什么让这个特别
这不仅仅是另一个RAG系统。GraphRAG MCP Server基于七项宪法原则构建，在速度、透明度和质量方面具有可衡量的优势。
1.闪电快速图形遍历
对于用户：查询将在1-2秒内返回，而不是30-60秒。互动体验，实时分析。
我们怎么做：启动时加载的预先计算的图索引启用O（1）邻居查找。没有针对每个查询的图解析。
证据: 性能提升50倍 记录在 故障排除.md --图形加载时间从每次查询25-30秒缩短到0.5秒。与传统的矢量RAG相比，GraphRAG实现了 响应时间快29倍 （平均延迟1.3秒vs 45秒，在54个查询中测量） 实验评估).
______________________________________________________________________
2.无孤立节点-万物互联
对于用户：每一条信息都是通过关系进行语境化的。你会得到更丰富的背景，更好的答案，没有孤立的事实。
我们怎么做：以社区为中心的设计，每个实体都跟踪其源社区和连接。图操作只返回具有关系的实体——孤立节点会被自动过滤。
为什么重要：没有上下文的信息只是噪音。图形结构确保当你询问税务问题时，你不仅会得到关键字匹配，还会得到主题、相关概念以及共同讨论它们的公民贡献。
______________________________________________________________________
3.完全透明-答案来源
对于用户：查看支持每项索赔的公民捐款。验证准确性，建立信任，审核响应。
我们怎么做：文本块是具有实体双向边的一级图节点。每个回复都包含可通过图表追踪的源报价： chunk → entity → response.
证据：块检索优化减少了文件I/O **500ms+至\ Entities │ │ │ │ Chunks connected via source_id attribute │ │ │ └─────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ OpenAI API │ │ (GPT-4o-mini for query synthesis) │ └─────────────────────────────────────────────────────────────┘
### 组件
- **FastMCP+Uvicorn**：具有TransportSecuritySettings的MCP协议服务器，用于反向代理兼容性
- **GraphIndex**：预计算的图索引（功能007）支持O（1）邻居查找，在服务器启动时加载
- **纳米石墨**：具有双策略检索的图遍历和查询引擎
- **存储**：GraphML图（实体关系）、JSON存储（块、社区报告、实体向量）
- **LLM**：GPT-4o-mini用于查询合成和社区报告生成
### 数据流
1. **客户端初始化MCP会话** → 接收 `mcp-session-id`
1. **工具调用已发出** （例如。， `grand_debat_query`)带有会话ID
1. **GraphIndex检索实体** 通过O（1）邻接列表查找
1. **图的遍历** 使用加权Dijkstra查找相关实体/块
1. **已组装上下文** 从块（通过 `source_id` 属性）+社区报告
1. **LLM综合答案** 有来源引用和来源链
1. **响应流式传输** 通过服务器发送事件（SSE）
### 关键架构决策
- **预计算**：启动时加载所有50个commune图（无延迟加载），以确保O（1）查找
- **先绘图**：块是图节点，起源是图边（双向块↔实体连接）
- **加权遍历**：具有关系类型权重的Dijkstra算法（关注度：1.0，HAS_SOURCE：0.9，APPARTIENT_A:0.3，RELATED_TO:0.1）
- **双重战略**：对于跨社区查询，将社区关键字+全球实体搜索相结合，实现92.7%的覆盖率
______________________________________________________________________
## 数据结构
每个commune文件夹都包含预索引的GraphRAG数据：
law_data/ ├── Rochefort/ │ ├── vdb_entities.json # Entity vector database │ ├── kv_store_text_chunks.json # Original contribution texts │ ├── kv_store_community_reports.json # AI-generated community summaries │ ├── kv_store_full_docs.json # Full documents │ ├── kv_store_llm_response_cache.json # Cached LLM responses │ └── graph_chunk_entity_relation.graphml # Knowledge graph ├── Andilly/ │ └── ... └── ... (50 communes total)
### GraphML架构
**节点**:
- `entity_name`：实体标识符（每个社区唯一）
- `entity_type`：公社、概念、主题、市民贡献、大块
- `description`：自然语言描述
- `source_id`: **关键属性** --以分号分隔的块ID（例如，“chunk_001chunk_002“）
**边缘**:
- `relationship_type` 或 `type`：关注、有来源、有装置、有关系
- `weight`：关系强度（可选）
**块**：通过连接 `source_id` 属性（不通过 `HAS_SOURCE` edges——这是在failures.md中记录的一个关键发现）。
______________________________________________________________________
## 部署
### 环境变量
|变量|描述|必填|默认|示例|
|----------|-------------|----------|---------|---------|
| `OPENAI_API_KEY` |用于LLM调用的OpenAI API密钥|是|-| `sk-...` |
| `GRAND_DEBAT_DATA_PATH` |公社数据目录的路径|否| `./law_data` | `/data/communes` |
| `PORT` |HTTP服务器端口|否| `8080` | `8000` |
| `ENABLE_OPIK_LOGGING` |启用评估日志|否| `true` | `false` |
| `OPIK_API_KEY` |用于日志记录的Opik API密钥（可选）|否|-| `...` |
______________________________________________________________________
### 部署到铁路
Install Railway CLI
npm install -g @railway/cli
Login
railway login
Link to project
railway link
Set environment variables
railway variables --set "OPENAI_API_KEY=your-key"
Deploy
railway up
**重要**：铁路使用反向代理(`railway-edge`).服务器包括 `TransportSecuritySettings(enable_dns_rebinding_protection=False)` 防止HTTP 421“无效主机标头”错误（请参阅 [故障排除.md](troubleshooting.md)).
______________________________________________________________________
### 部署到云端运行
gcloud run deploy grand-debat-mcp \ --source . \ --region europe-west1 \ --allow-unauthenticated \ --set-env-vars "OPENAI_API_KEY=your-key"
______________________________________________________________________
### 码头工人
Build
docker build -t grand-debat-mcp .
Run
docker run -p 8080:8080 \ -e OPENAI_API_KEY="your-key" \ -v $(pwd)/law_data:/app/law_data \ grand-debat-mcp
______________________________________________________________________
### 本地开发
**先决条件**：Python 3.11+，OpenAI API密钥
Clone repository
git clone https://github.com/ArthurSrz/graphRAGmcp.git cd graphRAGmcp
Install dependencies
pip install -r requirements.txt
Set environment variables
export OPENAI_API_KEY="your-api-key" export GRAND_DEBAT_DATA_PATH="./law_data"
Run with stdio (for MCP Inspector testing)
python server.py --stdio
Run as HTTP server
python server.py --port 8000
**使用MCP检查员进行测试**:
npx @modelcontextprotocol/inspector python server.py --stdio
______________________________________________________________________
## 故障排除
### 常见问题
#### 1.“主机标头无效”（HTTP 421）
**原因**：MCP SDK的DNS重新绑定保护拒绝来自反向代理（Railway、Cloud Run）的请求，其中Host标头与允许列表不匹配。
**解决方案**：服务器包括 `TransportSecuritySettings(enable_dns_rebinding_protection=False)` --安全性在代理层处理。如果您正在运行自定义部署，请确保此设置存在于 `server.py`.
______________________________________________________________________
#### 2.“必填字段”Pydantic验证错误
**原因**：嵌套的Pydantic模型破坏了Dust.tt和其他需要平面参数模式的MCP客户端。
**解决方案**：此服务器使用扁平参数 `Annotated[type, Field(description="...")]` 为了实现通用客户端兼容性。如果您正在修改工具，请避免使用嵌套参数。
______________________________________________________________________
#### 3.查询结果为空
**原因**：公社ID不匹配（例如，使用 `Saint-Jean-d'Angély` 而不是 `Saint_Jean_Dangely`).
**解决方案**：始终使用 `grand_debat_list_communes` 以获得准确的社区ID。响应包括正确的下划线格式的名称。
______________________________________________________________________
#### 4.会话错误
**原因**：缺失 `mcp-session-id` 工具调用中的标题。
**解决方案**:
1. 呼叫 `initialize` 方法优先→ 提取 `mcp-session-id` 从响应标头
1. 包含 `mcp-session-id: ` 所有后续文件中的标题 `tools/call` 请求：
______________________________________________________________________
#### 5.首次查询速度慢
**原因**：服务器启动后的第一个查询会预热缓存（LLM响应缓存初始化、实体向量加载）。
**解决方案**：预期行为——后续查询更快（~1-2s）。这是每次服务器重启的一次性成本。
______________________________________________________________________
**详细故障排除**，请参阅 [故障排除.md](troubleshooting.md) 它记录了所有主要的优化、错误修复和架构发现。
______________________________________________________________________
## 查询示例
### 发现
**列出所有公社**:
{"name": "grand_debat_list_communes", "arguments": {}}
**搜索与退休相关的实体**:
{ "name": "grand_debat_search_entities", "arguments": {"params": {"commune_id": "Marans", "pattern": "retraite", "limit": 20}} }
______________________________________________________________________
### 目标研究（本地模式）
**Rochefort的财政问题**:
{ "name": "grand_debat_query", "arguments": {"params": {"commune_id": "Rochefort", "query": "Quelles sont les principales préoccupations fiscales des citoyens?", "mode": "local"}} }
**退休话题**:
{ "name": "grand_debat_query", "arguments": {"params": {"commune_id": "Saint_Xandre", "query": "Que disent les citoyens sur les retraites?", "mode": "local"}} }
______________________________________________________________________
### 主题分析（全球模式）
**Surgères的总体主题**:
{ "name": "grand_debat_query", "arguments": {"params": {"commune_id": "Surgères", "query": "Quels sont les grands thèmes abordés par les citoyens?", "mode": "global"}} }
**Rivedoux Plage的社区集群**:
{ "name": "grand_debat_get_communities", "arguments": {"params": {"commune_id": "Rivedoux_Plage", "limit": 10}} }
______________________________________________________________________
### 来源与验证
**从Andilly获得原创贡献**:
{ "name": "grand_debat_get_contributions", "arguments": {"params": {"commune_id": "Andilly", "limit": 5}} }
**具有完整来源跟踪的查询** （本地模式自动包含带引号的源块）：
{ "name": "grand_debat_query", "arguments": {"params": {"commune_id": "Rochefort", "query": "Préoccupations environnementales?", "mode": "local"}} }
______________________________________________________________________
## 贡献与支持
### 问题和Bug报告
- **GitHub 问题**：报告错误，请求功能→
- **GitHub讨论**：提问，分享用例→
### 绩效反馈
- 使用基准报告性能回归（延迟测量前后）
- 绩效改进应包括量化的影响（见 [故障排除.md](troubleshooting.md) 模板）
### 文档改进
- 欢迎通过Pull Requests进行更正和澄清
- 专注于面向用户的文档（集成指南、示例、故障排除）
______________________________________________________________________
## 链接和资源
- **MCP协议文件**: [https://modelcontextprotocol.io](https://modelcontextprotocol.io)
- **全国大辩论背景**: [https://granddebat.fr](https://granddebat.fr)
- **OPIK评估仪表板**: [https://www.comet.com/opik](https://www.comet.com/opik)
- **实验评估报告**: [docs/eval/exprimental-design-rag-comparison.md](docs/eval/experimental-design-rag-comparison.md)
- **故障排除和优化历史记录**: [故障排除.md](troubleshooting.md)
- **GraphIndex实现**: [graph_index.py](graph_index.py)
- **宪法原则（完整版）**: [.define/memory/constitution.md](.specify/memory/constitution.md)
______________________________________________________________________
## 许可证
麻省理工学院