mcp-chat

基于 Neo4j 的聊天机器人 MCP 服务器实现方式整理。

MCP 服务器制作原则

Tool 设计——不是设计 API，而是设计模型的行为

• 不要镜像 REST API。不是每个端点对应一个 tool，而是按模型要执行的工作单元进行分组。

• Tool 数量要少，description 要长。Description 是一份文档，包含何时使用/不应使用、参数示例、返回值格式。Description 就是提示词。

• 输出要在 token 预算内设计。不要输出原始 JSON 转储，而是格式化为模型易于阅读的形式，大量结果要添加 limit + 分页参数。

结构标准模式

• Transport 分离——本地用 stdio，远程用 Streamable HTTP。将服务器逻辑与 transport 分离，便于同时支持两者。

• 输入验证用 schema——TS SDK 使用 zod schema 声明 tool 参数。不要手动编写验证代码。

• 错误返回 isError: true 结果，而不是 throw。让模型读取错误信息并重试，在消息中说明原因和解决方法。

• stdio 中 stdout 是协议通道。日志必须通过 stderr 输出。一个 console.log 就会导致服务器崩溃。

• 危险操作要用代码阻止，而不是靠提示词。例如在只读 tool 中拒绝写语句，强制注入 LIMIT。

开发工作流程

1. 使用 MCP Inspector 手动测试——npx @modelcontextprotocol/inspector node dist/index.js

2. 用实际模型验证 tool 选择场景——如果模型选错了 tool，修改的是 description 而不是代码。

3. 业务逻辑（查询验证器、格式化器）通过不依赖 MCP 的单元测试验证。

Related MCP server: Neo4j GraphRAG MCP Server

四种实现方式

1. 直接使用官方 Neo4j MCP 服务器

直接通过配置连接 Neo4j 官方提供的 MCP 服务器。

• mcp-neo4j-cypher ——提供让 LLM 查询 schema 并直接生成执行 Cypher 的 tool（get_schema、read_cypher、write_cypher）。

• mcp-neo4j-memory ——将对话中出现的实体/关系存储为知识图谱的长期记忆服务器。

2. 基于 Text2Cypher 的自建 MCP 服务器

自己构建 MCP 服务器，但 tool 采用“自然语言问题 → 生成 Cypher → 执行”的通用结构。与官方服务器类似，但可以自行控制以下内容：

• 注入 schema 说明（在提示词中提供图结构）

• 查询验证（强制只读、强制 LIMIT）

• 结果格式化

3. 领域专用 tool 方式

不让 LLM 处理 Cypher，而是预先定义领域相关的 tool。每个 tool 内部只执行参数化的 Cypher。

search_person(name)          → 파라미터화된 Cypher 실행
get_relationships(id, depth) → 파라미터화된 Cypher 실행
find_path(from, to)          → shortestPath 쿼리 실행

4. GraphRAG 方式

通过 Neo4j 的向量索引进行相似度搜索，然后从匹配节点出发扩展图（邻居节点、关系）构建上下文，仅暴露一个 retrieve(query) tool。

retrieve(query)
  1. query 임베딩 → 벡터 인덱스 유사도 검색
  2. 매칭된 노드에서 그래프 확장 (이웃 노드, 관계 수집)
  3. 수집된 서브그래프를 컨텍스트로 반환

推荐组合

实际工作中，2 + 3 混合是常见模式。常见问题用领域专用 tool 处理，其余只读问题用 Text2Cypher 作为后备方案。

技术栈参考

• TypeScript — @modelcontextprotocol/sdk

• Python — FastMCP