使用说明

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+至<1ms 通过内存遍历将块视为图实体(故障排除.md -“快速图遍历到块”）。在GraphML source_id属性发现之后， 93.7%的实体 现在有可检索的源块（从0.15%增加到0.15%）(宪法).

4.通用MCP兼容性

对于用户：适用于Claude Desktop、Cline、Dust.tt、任何MCP客户端。一次集成，随处使用。

我们怎么做：平面参数签名（非嵌套Pydantic模型）、JSON-RPC 2.0合规性、流媒体服务器发送事件。在多个客户端上进行了测试。

为什么重要：“Pydantic验证错误”问题记录在故障排除.md 显示嵌套参数破坏了Dust.tt兼容性。扁平参数确保此服务器在没有特定于客户端的解决方法的情况下普遍工作。

5.设计性能

对于用户：每个优化都有前后指标记录。没有神秘的性能回归，完全的架构透明。

证据: 故障排除.md 文件 7项主要优化工作 量化改进：

预先计算的图形索引： 50倍加速
双策略检索： 16% → 92.7% 语料库覆盖率
快速块遍历： 500毫秒→ <1ms
LLM缓存单例： -5-20秒用于重叠查询

6.经验验证的质量

对于用户：变化是由法学硕士作为评判标准，而不是直觉来测试的。相信更新会提高质量。

我们怎么做：OPIK评估框架，配备GPT-4o-mini判断工具，用于测量意义匹配、幻觉、答案相关性和潜伏期。用于模型、温度、超时和执行顺序的A/B比较控制。

证据：实验-设计-比率比较.md评估揭示了9公社限制错误（平均匹配：0.037→ 0.60+ 修复后）。系统测试 100%成功率 （54/54查询）和 低幻觉 向量RAG（0.25比0.54）验证了生产准备就绪。

7.迭代架构

对于用户：系统是通过解决现实世界的问题而不是象牙塔设计发展起来的。久经考验的架构。

示例：GraphML source_id 属性发现是在调试过程中发现的，为什么99.85%的块检索失败。调查显示，区块没有通过 HAS_SOURCE 边缘如预期，但用分号分隔 source_id 属性。这种架构见解（记录在故障排除.md)从根本上改变了块的访问方式，提高了覆盖率 0.15%至93.7%.

快速入门-5分钟内开始跑步

卷曲测试

# 1. Initialize session
curl -s -i -X POST "https://graphragmcp-production.up.railway.app/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}, "id": 1}'

# Note the mcp-session-id header in response

# 2. List available communes
curl -s -X POST "https://graphragmcp-production.up.railway.app/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "grand_debat_list_communes", "arguments": {}}, "id": 2}'

# 3. Run your first query
curl -s -X POST "https://graphragmcp-production.up.railway.app/mcp" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: YOUR_SESSION_ID" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "grand_debat_query", "arguments": {"params": {"commune_id": "Rochefort", "query": "Quelles sont les principales préoccupations fiscales?", "mode": "local"}}}, "id": 3}'

在MCP客户端中配置

克劳德桌面 → See 第5.1节
Cline/VS代码 → See 第5.2节
灰尘.tt → See 第5.3节
自定义MCP客户端 → See 第5.4节

理解数据集

什么是Grand Débat National？

这 全国大辩论 （2019）是一项法国公民协商倡议，公民为“生活手册”做出了贡献，该手册记录了对公共政策的担忧、建议和观点。此服务器对以下公民的贡献进行索引 Charente Maritime的50个社区创建了一个独特的公民研究工具。

覆盖范围和结构

地理范围：法国夏朗德省50个市镇
实体总数：8000多个提取的概念、主题、政策建议
结构：每个社区都是一个单独的知识图谱
实体类型 （摘自法语公民捐款）：
- 提案（政策建议/意见）
- 主题（专题类别）
- 公共服务 （公共服务）
- 救济金 （不满/投诉）
- 概念（概念实体）
- 意见（公民意见/观点）
- 机构行为者 （机构行为者）
- 公民（公民参考）
- 加上其他：改革民主（民主改革）、领土（领土）、协商（协商）、VERBATIM（直接引用）、CLUSTERSEMANTIQUE（语义集群）、TYPEIMOT（税收类型）、改革财政（财政改革）、MESUREECOLOGIQUE（生态措施）等。
关系类型 （提取系统定义了26种语义类型）：
- 一次流：SOUMET（提交）、REPOND_A（响应）、APPARTIENT_A（属于）、FAIL_PARTIE_DE（部分）
- 内容提取：express（express）、formulates（formulates）、raises（raises）、content（contains）
- 主题：关注（关注）、CIBLE（目标）、GERE（管理）
- 共识：贡献A（贡献），揭示（揭示），SINSCRIT_DANS（题写）
- 按程序添加：HAS_SOURCE（实体→块来源），来源_BY（块→实体）
- 备注GraphML文件主要存储RELATED_TO边；语义类型在提取提示中定义

覆盖率最高的社区

公社	实体	社区	贡献
罗什福特	812	140	102
马伦纳斯_希尔斯_布鲁阿奇	659	119	52
Saint-Xandre	537	78	41
圣_简_天使	505	0	50
里维德_普拉格	387	56	28
L_Gue_Dallere	356	17	21
Surgères	330	54	26

用例公民研究、政策分析、民主参与研究、公民关切的专题分析（税收、公共服务、环境问题、民主参与）。

集成指南

5.1克劳德桌面

添加到 ~/.config/claude/claude_desktop_config.json （macOS/Linux）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "grand-debat": {
      "url": "https://graphragmcp-production.up.railway.app/mcp",
      "transport": "streamable-http"
    }
  }
}

重新启动克劳德桌面验证工具是否出现在MCP工具列表中（锤子图标）。

5.2临床/VS代码

添加到MCP设置(.vscode/mcp.json 或Cline扩展设置）：

{
  "grand-debat": {
    "url": "https://graphragmcp-production.up.railway.app/mcp",
    "transport": "streamable-http"
  }
}

重新加载VS代码窗口。验证工具是否出现在Cline的工具面板中。

5.3粉尘吨

Dust.tt原生支持远程MCP服务器。看灰尘远程MCP服务器文档.

安装步骤:

首选 灰尘管理 → 开发者 → MCP服务器
点击 添加远程服务器
输入服务器URL: https://graphragmcp-production.up.railway.app/mcp
给它起个名字（例如，“大辩论GraphRAG”）
点击同步 --灰尘会自动发现所有5个工具
将服务器分配给您想要的空间

用于粉尘剂:

@agent Query the Grand Debat data for Rochefort about fiscal concerns

代理将自动初始化会话，调用 grand_debat_query，并返回GraphRAG供电的响应。

5.4自定义MCP客户端

需求：基于HTTP的JSON-RPC 2.0，用于流式响应的服务器发送事件（SSE）。

会话流程:

初始化: POST /mcp 随着 initialize 方法→ 接收 mcp-session-id 在响应标头中
呼叫工具: POST /mcp 随着 tools/call 方法，包括 mcp-session-id 头球
解析SSE：答复如下 event: message 随着 data: {...} 包含JSON-RPC结果

示例（Python）:

import httpx

session = httpx.Client(base_url="https://graphragmcp-production.up.railway.app")

# Initialize
resp = session.post("/mcp", json={
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "custom", "version": "1.0"}},
    "id": 1
}, headers={"Accept": "application/json, text/event-stream"})

session_id = resp.headers["mcp-session-id"]

# Call tool
resp = session.post("/mcp", json={
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {"name": "grand_debat_list_communes", "arguments": {}},
    "id": 2
}, headers={"mcp-session-id": session_id, "Accept": "application/json, text/event-stream"})

print(resp.text)  # Parse SSE response

MCP工具参考

6.1我应该使用哪种工具？

Want to see what's available?
  ↓
  grand_debat_list_communes

Have a specific question about a commune?
  ↓
  grand_debat_query (mode: "local")

Need a thematic overview?
  ↓
  grand_debat_query (mode: "global")

Looking for specific entities/themes?
  ↓
  grand_debat_search_entities

Want to explore topic clusters?
  ↓
  grand_debat_get_communities

Need to read original citizen texts?
  ↓
  grand_debat_get_contributions

6.2工具详细信息

`grand_debat_list_communes`

目的通过统计数据（实体计数、社区计数、捐款计数）发现所有50个可用的公社。

何时使用：了解数据集覆盖率的第一步，或为查询获取确切的公社ID。

参数：无

退货：公社对象数组 name, total_entities, total_communities, total_contributions.

示例:

{
  "name": "grand_debat_list_communes",
  "arguments": {}
}

响应:

{
  "communes": [
    {"name": "Rochefort", "total_entities": 812, "total_communities": 140, "total_contributions": 102},
    {"name": "Marennes_Hiers_Brouage", "total_entities": 659, "total_communities": 119, "total_contributions": 52},
    ...
  ]
}

`grand_debat_query`

目的：主查询工具——使用GraphRAG以本地（基于实体）或全局（基于社区）模式回答问题。

何时使用：这是您回答有关公民问题的主要工具。使用 本地模式 为了进行有针对性的事实调查， 全局模式 主题概述。

参数:

参数	类型	必填	说明
`commune_id`	string	是	确切的公社名称（使用 `grand_debat_list_communes` 获取有效ID）
`query`	string	是	自然语言问题（此数据集建议使用法语）
`mode`	string	是	`"local"` （基于实体）或 `"global"` （社区）

退货：结构化响应 answer （综合答案）， sources （实体名称或社区报告）， provenance （带引号的源代码块）。

示例（本地模式）:

{
  "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": "Surgères",
      "query": "Quels sont les grands thèmes abordés par les citoyens?",
      "mode": "global"
    }
  }
}

提示:

使用来自的精确公社ID grand_debat_list_communes （例如。， Saint_Jean_Dangely 不 Saint-Jean-d'Angély)
本地模式查找特定实体→ 导线图→ 检索源块（~1-2s）
全局模式使用AI生成的社区摘要→ 对于宽泛的主题，速度更快（约1-3s）

`grand_debat_search_entities`

目的：搜索与关键字模式匹配的实体（主题、概念、参与者）。

何时使用：当你需要查找数据中提到的特定主题而不需要问完整的问题时。

参数:

参数	类型	必填	说明
`commune_id`	string	是	在社区中搜索
`pattern`	string	Yes	要匹配的关键字或短语（不区分大小写，部分匹配）
`limit`	integer	否	要返回的最大结果（默认值：20）

退货：实体数组 entity_name, entity_type, description.

示例:

{
  "name": "grand_debat_search_entities",
  "arguments": {
    "params": {
      "commune_id": "Marans",
      "pattern": "retraite",
      "limit": 20
    }
  }
}

`grand_debat_get_communities`

目的：检索人工智能生成的主题社区报告（Louvain算法聚类）。

何时使用：探索GraphRAG系统如何将实体组织成主题集群。

参数:

参数	类型	必填	说明
`commune_id`	string	是	从社区检索社区
`limit`	integer	否	要返回的最大社区数（默认值：10）

退货：社区对象数组 level, title, summary, rank, findings.

示例:

{
  "name": "grand_debat_get_communities",
  "arguments": {
    "params": {
      "commune_id": "Rivedoux_Plage",
      "limit": 10
    }
  }
}

`grand_debat_get_contributions`

目的：获取公民原始贡献文本（源文件）。

何时使用：阅读公民的原始输入，验证引用，理解提取实体之外的上下文。

参数:

参数	类型	必填	说明
`commune_id`	string	是	公社从中检索贡献
`limit`	integer	否	返回的最大贡献（默认值：5）

退货：贡献对象数组 full_doc_id, content, commune, tokens, chunk_order_index.

示例:

{
  "name": "grand_debat_get_contributions",
  "arguments": {
    "params": {
      "commune_id": "Andilly",
      "limit": 5
    }
  }
}

查询模式说明

7.1本地模式-基于实体的检索

它的作用：查找与查询匹配的特定实体，遍历图以查找相关实体和关系，通过图边检索源块，使用上下文将答案与LLM合成。

最适合:

有针对性的问题（“公民对养老金有什么看法？”）
事实调查（“是否存在对财政政策的担忧？”）
具体议题（“提及环境问题”）

运作原理：关键字匹配→ 基于加权Dijkstra的图展开→ 通过以下方式检索块 source_id 属性→ LLM合成与来源。

演出：~1-2秒（图遍历<1ms，LLM调用是大部分延迟）。

示例问题:

“罗什福的税务问题是什么？”
“公民对养老金有什么看法？”
“提到生态转型？”

7.2全球模式-基于社区的分析

它的作用：选择相关的社区报告（人工智能生成的主题摘要），将社区摘要作为背景，将高级概述与法学硕士相结合。

最适合:

概述（“主要主题是什么？”）
主题模式（“公民关切概述”）
多主题分析（“哪些主题一起讨论？”）

运作原理：通过关键字匹配进行社区选择→ 报告检索（预生成）→ 结合主题背景的法学硕士综合。

演出：约1-3秒（由于社区摘要的上下文较大，速度稍慢）。

示例问题:

“辩论的主要议题是什么？”
“公民关注的概述？”
“讨论的主要主题？”

7.3选择正确的模式

问题类型	模式	原因
具体事实	本地	带出处的直接实体检索
主题概述	全球	社区摘要提供了高层次的模式
多公社	局部	交叉图遍历（集 `commune_id` 为null或查询全部）
探索性	全球性	更高层次的模式，无需深入细节
来源关键	本地	完整块→实体→响应追踪

性能和质量

8.1基准绩效

延迟: 1.3秒平均值 对比 矢量RAG为45秒 — 快29倍 (实验设计-射线比较.md)

可靠性: 100%成功率 （54/54项查询评价成功）

覆盖: 92.7%的语料库覆盖率 采用双策略检索（从单一策略的16%上升）

来源: 93.7%的实体 具有可检索的源块（在GraphML source_id发现后为0.15%）

8.2质量验证

框架：OPIK评估平台，GPT-4o-mini作为LLM判断（一致性温度=0）。

指标:

meaning_match：响应和预期答案之间的语义对等
hallucination：颠倒的忠诚分数（1=忠诚，0=幻觉）
answer_relevance：如何直接回答问题
usefulness：回答公民问题的实用工具

结果（来自实验设计rag comparison.md）：

图RAG： 较低的幻觉率 比向量RAG（0.25比0.54）
图RAG： 等效语义精度 矢量RAG（0.30 LLM精度分数）
图RAG： 快35倍 在保持质量的同时延迟

8.3关键优化

简要总结，链接至故障排除.md:

预先计算的图形索引: 50倍加速 （25-30s→ 0.5通过在启动时将所有commune图加载到内存中的邻接列表中
双策略检索: 16% → 92.7% 覆盖 通过结合社区关键字+全局实体搜索进行跨社区查询
快速块遍历: 500ms+文件I/O→ <1内存中的ms 通过将块视为具有双向边的图实体
GraphML源_id修复: 0.15% → 93.7% 成功率 通过发现块是通过以下方式连接的 source_id 属性（不是 HAS_SOURCE 边缘）
LLM缓存单例: -5-20秒用于重叠查询 通过防止每个请求的冗余缓存初始化
加权图遍历：使用Dijkstra算法将语义关系（CONCERTE:1.0）优先于结构关系（RELATED_TO:0.1）
DNS重新绑定保护修复程序：通过禁用MCP SDK的DNS重新绑定检查（代理处理安全性）解决铁路/云运行上的HTTP 421错误

架构概述

┌─────────────────────────────────────────────────────────────┐
│                   MCP Client (Claude, Cline, etc.)          │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ Streamable HTTP / MCP Protocol
                              ▼
┌─────────────────────────────────────────────────────────────┐
│              Grand Debat MCP Server (Railway)               │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ FastMCP + Uvicorn                                    │  │
│  │                                                       │  │
│  │ Tools:                                                │  │
│  │  - grand_debat_list_communes                         │  │
│  │  - grand_debat_query (local/global)                  │  │
│  │  - grand_debat_search_entities                       │  │
│  │  - grand_debat_get_communities                       │  │
│  │  - grand_debat_get_contributions                     │  │
│  │                                                       │  │
│  │ GraphIndex (in-memory adjacency lists)               │  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    nano_graphrag Engine                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐ │
│  │   Entities  │  │ Communities │  │   Text Chunks       │ │
│  │   (VDB)     │  │  (Reports)  │  │ (Contributions)     │ │
│  └─────────────┘  └─────────────┘  └─────────────────────┘ │
│                                                             │
│  ┌─────────────────────────────────────────────────────┐   │
│  │              Knowledge Graph (GraphML)               │   │
│  │   Entities ──relationships──> 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用于查询合成和社区报告生成

数据流

客户端初始化MCP会话 → 接收 mcp-session-id
工具调用已发出 （例如。， grand_debat_query)带有会话ID
GraphIndex检索实体 通过O（1）邻接列表查找
图的遍历 使用加权Dijkstra查找相关实体/块
已组装上下文 从块（通过 source_id 属性）+社区报告
LLM综合答案 有来源引用和来源链
响应流式传输 通过服务器发送事件（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).

部署到云端运行

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 工具调用中的标题。

解决方案:

呼叫 initialize 方法优先→ 提取 mcp-session-id 从响应标头
包含 mcp-session-id: <your-session-id> 所有后续文件中的标题 tools/call 请求：

5.首次查询速度慢

原因：服务器启动后的第一个查询会预热缓存（LLM响应缓存初始化、实体向量加载）。

解决方案：预期行为——后续查询更快（~1-2s）。这是每次服务器重启的一次性成本。

详细故障排除，请参阅故障排除.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/ArthurSrz/graphRAGmcp/问题
GitHub讨论：提问，分享用例→ github/ArthurSrz/graphRAGmcp/讨论

绩效反馈

使用基准报告性能回归（延迟测量前后）
绩效改进应包括量化的影响（见故障排除.md 模板）

文档改进

欢迎通过Pull Requests进行更正和澄清
专注于面向用户的文档（集成指南、示例、故障排除）

链接和资源

MCP协议文件: https://modelcontextprotocol.io
全国大辩论背景: https://granddebat.fr
OPIK评估仪表板: https://www.comet.com/opik
实验评估报告: docs/eval/exprimental-design-rag-comparison.md
故障排除和优化历史记录: 故障排除.md
GraphIndex实现: graph_index.py
宪法原则（完整版）: .define/memory/constitution.md

许可证

麻省理工学院