SNOMED GraphRAG MCP Server

基于 Neo4j 与 SNOMED 子集的 GraphRAG MCP 服务，提供 graph_search_concept、graph_get_related 两个 Tools。

---

1. 快速开始

环境：Python 3.10+、Neo4j 5.x（Docker Desktop 且 Docker 已运行）、uv 或 pip、PowerShell 或 CMD。以下在项目根执行。

1.1 数据与 Neo4j

# 生成 concept_minimal、复制 DR
python scripts/gen_concept_minimal.py
copy SNOMED_CSV\DR_118170007_new.csv docker\import\

# 启动 Neo4j
cd docker && docker compose up -d --force-recreate && cd ..

# Neo4j 启动约 10s 后执行 build（PowerShell）
Get-Content docker\import\build_minimal.cypher -Raw | docker exec -i neo4j cypher-shell -u neo4j -p password

# 校验（PowerShell）
$env:NEO4J_PASSWORD="password"
uv run python scripts/check_neo4j.py

CMD 下：type docker\import\build_minimal.cypher | docker exec -i neo4j cypher-shell -u neo4j -p password；set NEO4J_PASSWORD=password 再执行 check_neo4j.py。Neo4j 密码非 password 时替换。

1.2 安装依赖

uv sync

或 pip install "mcp[cli]" neo4j。

1.3 配置 MCP（Cursor / Claude Desktop）

在 MCP 配置中加入（cwd、command 改成本机项目绝对路径）：

{
  "mcpServers": {
    "snomed-graph-rag": {
      "command": "D:/ai/gientech/code/rag-neo-mcp-week6/.venv/Scripts/python.exe",
      "args": ["-u", "-m", "mcp_server.main"],
      "cwd": "D:/ai/gientech/code/rag-neo-mcp-week6",
      "env": { "PYTHONUNBUFFERED": "1", "NEO4J_PASSWORD": "password" }
    }
  }
}

• Cursor：设置 → MCP，或编辑 %USERPROFILE%\.cursor\mcp.json。完整示例见 mcp_config_example.json。
• 若出现「No server info found」：确保 command 指向 项目根\.venv\Scripts\python.exe，args 含 -u，或改用 run_mcp.bat 作 command、args: []。

1.4 重启 Cursor，确认 Docker 中 Neo4j 已启动

---

2. 探索更复杂的 RAG 应用场景和范式

相对「文档切片 + 向量检索 + 一次查回」的简单 RAG，本项目从应用场景和检索范式两方面做更复杂探索，并落实到实现。

2.1 应用场景

维度	简单 RAG	本项目
数据形态	扁平文本/切片	领域知识图谱：SNOMED 本体（ObjectConcept、RoleGroup、定义关系）
领域	通用文档	医学术语：FSN、sctid、SPECIMEN_SOURCE_IDENTITY 等
语义结构	语义相似	显式关系：(概念)-[:HAS_ROLE_GROUP]->(RoleGroup)-[关系类型]->(目标概念)

本项目实现：build_minimal.cypher 构建 ObjectConcept、RoleGroup、HAS_ROLE_GROUP、SPECIMEN_SOURCE_IDENTITY；mcp_server/neo4j_client + Cypher 查询该图。

2.2 检索范式

• 多范式并存（非单一向量检索）：
  • graph_search_concept：按 FSN 子串或 sctid 的关键词/属性检索（图上的索引查找）；
  • graph_get_related：按图结构 + 关系类型的图遍历检索，模式
    (c:ObjectConcept)-[:HAS_ROLE_GROUP]->(rg:RoleGroup)-[r]->(c2:ObjectConcept)，type(r) IN $types。
• 图原生检索：用 Cypher 在 Neo4j 上做模式匹配，关系类型直接参与查询，替代「向量检索 + 过滤」。

2.3 工具化 / Agent 范式

• RAG 即工具：图检索封装为 MCP 的 graph_search_concept、graph_get_related，由 Cursor/LLM 按问题选工具、组合调用，而非固定一条检索流水线。
• 检索与生成解耦：模型根据自然语言选工具与参数（如 rel_types），再基于图返回结果生成回答（Tool-augmented / Agent-RAG）。

---

3. MCP 应用

3.1 在 Cursor 里用

• 在对话中用自然语言提问，例如：「sctid 119299002 有哪些 SPECIMEN_SOURCE_IDENTITY 相关概念？」、「按 FSN 搜 Concept (119299002)」。
• 模型会自动选 graph_search_concept 或 graph_get_related，把 Neo4j 查到的结果当上下文再回答。
• 流程：提问 → Cursor 调用 Tool → MCP 查 Neo4j → 文本结果给模型 → 生成回答。

3.2 两个 Tool

Tool	作用
graph_search_concept	按 FSN 子串或 sctid 检索 ObjectConcept；参数 keyword、limit。
graph_get_related	按 sctid 与关系类型（如 SPECIMEN_SOURCE_IDENTITY）查经 RoleGroup 的相邻概念；参数 sctid、rel_types（可选）。

3.3 示例问题

• 「sctid 119299002 有哪些 SPECIMEN_SOURCE_IDENTITY 相关概念？」→ graph_get_related
• 「在 SNOMED 图里查和 116154003 有定义关系的概念」→ graph_get_related
• 「按 FSN 搜 Concept (119299002)」→ graph_search_concept

3.4 前端界面（可选）

不通过 Cursor 时，可在浏览器查图：uv sync --extra web，然后
$env:NEO4J_PASSWORD="password"；uv run uvicorn web.app:app --host 127.0.0.1 --port 8000，打开 http://127.0.0.1:8000。

3.5 错误与边界

sctid 不存在、keyword 无匹配、Neo4j 断线时，Tool 返回明确提示，不抛错。