Skip to main content
Glama
lesskao

SNOMED GraphRAG MCP Server

by lesskao
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Remote

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 已启动

Related MCP server: neo4j-mcp

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 返回明确提示，不抛错。

Available Tools

2 tools
graph_search_conceptB

在 SNOMED 图中按 FSN 或 sctid 检索概念。 keyword: 关键词（FSN 子串或 sctid） limit: 返回条数

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
keywordYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must fully disclose behavioral traits. It only mentions search criteria and parameters but omits key details such as behavior on no results, pagination, performance characteristics, or error handling. The existence of an output schema is not leveraged in the description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short (two lines) and includes parameter explanations, avoiding unnecessary fluff. However, it could be slightly more structured (e.g., separating purpose from parameter details) without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that an output schema exists and parameters are few, the description is minimally adequate for a basic search tool. It covers the core functionality but lacks edge-case handling, error states, or performance notes that would make it fully complete for an agent unfamiliar with SNOMED.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning beyond the schema by explaining that 'keyword' is an FSN substring or sctid, and 'limit' is the number of returned results. Since schema description coverage is 0%, this compensation is valuable, though it could specify the default limit explicitly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool searches for concepts in the SNOMED graph using FSN or sctid. It clearly identifies the verb ('检索' - retrieve/search) and resource ('概念' - concepts), and differentiates from the sibling tool graph_get_related by specifying the search method.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidelines are provided about when to use this tool versus alternatives. The sibling graph_get_related is listed but the description does not mention any context, prerequisites, or exclusion criteria, leaving the agent without guidance for choosing the appropriate tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedgraph_get_related
    • First observedgraph_search_concept
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.1/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have completely distinct purposes: graph_search_concept retrieves concepts by search, and graph_get_related fetches related concepts via relationships. There is no overlap or ambiguity.

Naming Consistency5/5

Both tools follow the consistent 'graph_<verb>_<noun>' pattern with snake_case. 'graph_search_concept' and 'graph_get_related' are parallel and predictable.

Tool Count2/5

With only 2 tools for a complex domain like SNOMED CT, the server is severely under-scoped. Typical SNOMED interactions require many more operations (e.g., detail retrieval, hierarchy browsing, multiple relation types).

Completeness2/5

The tool surface has major gaps: no tool to get full concept details (descriptions, synonyms), no hierarchy navigation, and graph_get_related is limited to a single relation type (SPECIMEN_SOURCE_IDENTITY). Missing core CRUD-like operations for a knowledge graph.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Neo4j GraphRAG MCP Server

    neo4j-field
    A
    license
    A
    quality
    C
    maintenance
    An MCP server that enables LLMs to perform semantic and fulltext searches within Neo4j while executing complex, search-augmented Cypher queries for GraphRAG applications. It provides tools for database schema discovery and supports multi-provider embeddings to facilitate advanced graph traversals.
    5
    2
    MIT

  • neo4j-mcp

    lesleslie
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for Neo4j graph database operations, enabling Cypher queries, node/relationship management, and schema discovery.
    1
    BSD 3-Clause

  • Neo4j MCP Server

    alvaropaco
    A
    license
    A
    quality
    B
    maintenance
    MCP server for Neo4j that provides abstract graph operations for LLMs, enabling safe and consistent interaction with Neo4j databases through tools like search, insert, update, delete, and schema introspection.
    8
    MIT