mcp-neo4j-data-modeling

🔍📊 Neo4j 数据建模 MCP 服务

mcp-name: io.github.neo4j-contrib/mcp-neo4j-data-modeling

🌟 概述

这是一个 Model Context Protocol（MCP）服务实现，提供用于创建、可视化和管理 Neo4j 图数据模型的工具。此服务支持定义节点、关系和属性，以设计可交互可视化的图数据库架构。

此 MCP 服务可支持如下所述的数据建模工作流。

• 蓝色步骤由 Agent 处理
• 紫色步骤由数据建模 MCP 服务处理
• 绿色步骤由用户处理

演示

如需查看端到端演示，了解如何使用数据建模和 Cypher MCP 服务开发数据模型、生成数据导入脚本并验证使用场景，请参阅此 Github 仓库。

🧩 组件

📦 资源

此服务提供以下资源：

架构

• resource://schema/node

  • 获取 Node 对象的 JSON 架构
  • 返回：定义 Node 结构的 JSON 架构

• resource://schema/relationship

  • 获取 Relationship 对象的 JSON 架构
  • 返回：定义 Relationship 结构的 JSON 架构

• resource://schema/property

  • 获取 Property 对象的 JSON 架构
  • 返回：定义 Property 结构的 JSON 架构

• resource://schema/data_model

  • 获取 DataModel 对象的 JSON 架构
  • 返回：定义 DataModel 结构的 JSON 架构

示例数据模型

• resource://examples/patient_journey_model

  • 获取真实世界的患者就诊历程医疗保健数据模型（JSON 格式）
  • 返回：用于跟踪患者就诊、病症、药物和护理计划的 JSON DataModel

• resource://examples/supply_chain_model

  • 获取真实世界的供应链数据模型（JSON 格式）
  • 返回：用于跟踪产品、订单、库存和地点的 JSON DataModel

• resource://examples/software_dependency_model

  • 获取真实世界的软件依赖关系图数据模型（JSON 格式）
  • 返回：用于跟踪软件依赖关系、安全漏洞、提交记录和贡献者分析的 JSON DataModel

• resource://examples/oil_gas_monitoring_model

  • 获取真实世界的石油和天然气设备监控数据模型（JSON 格式）
  • 返回：用于监控石油和天然气设备、传感器、警报和维护情况的工业级 JSON DataModel

• resource://examples/customer_360_model

  • 获取真实世界的 Customer 360 数据模型（JSON 格式）
  • 返回：用于客户关系管理的 JSON DataModel，涵盖账户、联系人、订单、工单和调查问卷

• resource://examples/fraud_aml_model

  • 获取真实世界的欺诈与反洗钱数据模型（JSON 格式）
  • 返回：用于金融欺诈检测和反洗钱的 JSON DataModel，涵盖客户、交易、警报和合规信息

• resource://examples/health_insurance_fraud_model

  • 获取真实世界的医疗保险欺诈检测数据模型（JSON 格式）
  • 返回：用于医疗保健欺诈检测的 JSON DataModel，可跟踪调查、处方、执行情况和受益人关系

数据导入

• resource://neo4j_data_ingest_process
  • 获取推荐的数据导入流程详解，了解如何使用数据模型将数据导入 Neo4j
  • 返回：介绍数据导入流程的 Markdown 文档

🛠️ 工具

此服务提供以下核心工具：

✅ 验证工具

• validate_node

  • 验证单个节点结构
  • 输入：
    • node (Node)：要验证的节点
    • return_validated (bool, optional)：如果为 True，则返回已验证的节点对象，而不是 True
  • 返回：如果有效则返回 True（或在 return_validated=True 时返回已验证的 Node 对象）；如果无效则抛出 ValueError

• validate_relationship

  • 验证单个关系结构
  • 输入：
    • relationship (Relationship)：要验证的关系
    • return_validated (bool, optional)：如果为 True，则返回已验证的关系对象，而不是 True
  • 返回：如果有效则返回 True（或在 return_validated=True 时返回已验证的 Relationship 对象）；如果无效则抛出 ValueError

• validate_data_model

  • 验证整个数据模型结构
  • 输入：
    • data_model (DataModel)：要验证的数据模型
    • return_validated (bool, optional)：如果为 True，则返回已验证的数据模型对象，而不是 True
  • 返回：如果有效则返回 True（或在 return_validated=True 时返回已验证的 DataModel 对象）；如果无效则抛出 ValueError

👁️ 可视化工具

• get_mermaid_config_str
  • 为数据模型生成 Mermaid 图表配置字符串，适用于支持 Mermaid 可视化的工具
  • 输入：
    • data_model (DataModel)：要可视化的数据模型
  • 返回：表示该数据模型的 Mermaid 配置字符串

🔄 导入/导出工具

这些工具可与 Arrows 集成。Arrows 是一款图形绘制 Web 应用，可通过直观的可视化界面创建详细的 Neo4j 数据模型。

• load_from_arrows_json

  • 从 Arrows 应用的 JSON 格式加载数据模型
  • 输入：
    • arrows_data_model_dict (dict)：从 Arrows 应用导出的 JSON 字典
  • 返回：DataModel 对象

• export_to_arrows_json

  • 将数据模型导出为 Arrows 应用的 JSON 格式
  • 输入：
    • data_model (DataModel)：要导出的数据模型
  • 返回：与 Arrows 应用兼容的 JSON 字符串

• load_from_owl_turtle

  • 从 OWL Turtle 格式加载数据模型
  • 输入：
    • owl_turtle_str (str)：本体的 OWL Turtle 字符串表示
  • 返回：从本体中提取节点和关系后的 DataModel 对象
  • 注意：此转换会造成信息丢失——OWL Classes 会转换为 Nodes，ObjectProperties 会转换为 Relationships，DatatypeProperties 会转换为 Node 属性。

• export_to_owl_turtle

  • 将数据模型导出为 OWL Turtle 格式
  • 输入：
    • data_model (DataModel)：要导出的数据模型
  • 返回：以 OWL Turtle 格式表示的数据模型字符串
  • 注意：此转换会造成信息丢失——由于 OWL 不支持为 ObjectProperties 设置属性，因此不会保留关系属性。

• export_to_pydantic_models

  • 将数据模型导出为 Pydantic 模型
  • 输入：
    • data_model (DataModel)：要导出的数据模型
  • 返回：表示 Pydantic 模型的 Python 文件字符串，包含节点、关系和完整数据模型的导入语句与模型定义

• export_to_neo4j_graphrag_pkg_schema

  • 将数据模型导出为 Neo4j GraphRAG Python Package 架构格式
  • 输入：
    • data_model (DataModel)：要导出的数据模型
  • 返回：包含 Neo4j GraphRAG Python Package 架构的字典

• load_from_neo4j_graphrag_pkg_schema

  • 从 Neo4j GraphRAG Python Package 架构格式加载数据模型
  • 输入：
    • neo4j_graphrag_python_package_schema (dict)：Neo4j GraphRAG Python Package 架构字典
  • 返回：DataModel 对象

📚 示例数据模型工具

这些工具可访问为常见用例和领域预先构建的示例数据模型。

• list_example_data_models

  • 列出所有可用的示例数据模型及其描述
  • 输入：无
  • 返回：包含示例名称、描述、节点/关系数量和使用说明的字典

• get_example_data_model

  • 从可用模板中获取示例图数据模型
  • 输入：
    • example_name（str）：要加载的示例名称（'patient_journey'、'supply_chain'、'software_dependency'、'oil_gas_monitoring'、'customer_360'、'fraud_aml' 或 'health_insurance_fraud'）
  • 返回：ExampleDataModelResponse，包含 DataModel 对象和 Mermaid 可视化配置

📝 Cypher 数据导入工具

这些工具可用于根据数据模型创建 Cypher 数据导入查询。这些查询随后可供其他 MCP 服务或应用程序用于将数据加载到 Neo4j。

• get_constraints_cypher_queries

  • 生成用于为数据模型中的所有节点创建约束（例如唯一键）的 Cypher 查询
  • 输入：
    • data_model（DataModel）：用于生成约束的数据模型
  • 返回：约束的 Cypher 语句列表

• get_node_cypher_ingest_query

  • 生成用于将节点记录列表导入 Neo4j 的 Cypher 查询
  • 输入：
    • node（Node）：节点定义（标签、键属性、属性）
  • 返回：用于批量导入节点的参数化 Cypher 查询（使用 $records）

• get_relationship_cypher_ingest_query

  • 生成用于将关系记录列表导入 Neo4j 的 Cypher 查询
  • 输入：
    • data_model（DataModel）：包含节点和关系的数据模型
    • relationship_type（str）：关系的类型
    • relationship_start_node_label（str）：起始节点的标签
    • relationship_end_node_label（str）：结束节点的标签
  • 返回：用于批量导入关系的参数化 Cypher 查询（使用 $records）

💡 提示词

• create_new_data_model
  • 提供结构化的参数化提示词，用于生成新的图数据模型
  • 输入：
    • data_context（str）：对数据的描述，以及需要重点关注的具体细节
    • use_cases（str）：数据模型需要满足的用例列表
    • desired_nodes（str，可选）：要纳入数据模型的节点标签
    • desired_relationships（str，可选）：要纳入数据模型的关系类型
  • 返回：结构化提示词，引导 Agent 完成 3 步流程：分析样本数据和示例、生成并验证数据模型，以及展示结果和可视化内容

🔧 在 Claude Desktop 中使用

💾 已发布的软件包

可在 PyPi 上找到：https://pypi.org/project/mcp-neo4j-data-modeling/

使用指定的传输方式，将服务添加到你的 claude_desktop_config.json 中：

"mcpServers": {
  "neo4j-data-modeling": {
    "command": "uvx",
    "args": [ "[email protected]", "--transport", "stdio" ]
  }
}

🏷️ 工具命名空间

此服务支持为服务工具设置命名空间：

"mcpServers": {
  "neo4j-data-modeling-app1": {
    "command": "uvx",
    "args": [ "[email protected]", "--transport", "stdio", "--namespace", "app1" ]
  },
  "neo4j-data-modeling-app2": {
    "command": "uvx", 
    "args": [ "[email protected]", "--transport", "stdio", "--namespace", "app2" ]
  }
}

启用命名空间后：

• 工具名称会添加前缀：app1-validate_node、app2-validate_node
• 每个命名空间独立运行

🌐 HTTP 传输模式

此服务支持 HTTP 传输，可用于基于 Web 的部署和微服务：

# Basic HTTP mode (defaults: host=127.0.0.1, port=8000, path=/mcp/)
mcp-neo4j-data-modeling --transport http

# Custom HTTP configuration
mcp-neo4j-data-modeling --transport http --host 127.0.0.1 --port 8080 --path /api/mcp/

# With namespace for multi-tenant deployment
mcp-neo4j-data-modeling --transport http --namespace myapp

HTTP 配置的环境变量：

export MCP_TRANSPORT=http
export NEO4J_MCP_SERVER_HOST=127.0.0.1
export NEO4J_MCP_SERVER_PORT=8080
export NEO4J_MCP_SERVER_PATH=/api/mcp/
export NEO4J_NAMESPACE=myapp
mcp-neo4j-data-modeling

🔄 传输模式

此服务支持三种传输模式：

• STDIO（默认）：供本地工具和 Claude Desktop 使用的标准输入/输出
• SSE：用于基于 Web 的部署的服务器发送事件
• HTTP：适用于现代 Web 部署和微服务的可流式 HTTP

🐳 使用 Docker

这里使用 Docker Hub 托管的 Data Modeling MCP 服务镜像，并通过 stdio 传输与 Claude Desktop 配合使用。

配置详情：

• -i：交互模式——保持 STDIN 打开，以便通过 stdio 传输进行通信
• --rm：容器退出时自动删除容器（清理）
• -p 8000:8000：端口映射——将主机端口 8000 映射到容器端口 8000
• NEO4J_TRANSPORT=stdio：使用 stdio 传输，以兼容 Claude Desktop

{
  "mcpServers": {
    "neo4j-data-modeling": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "8000:8000",
        "-e", "NEO4J_TRANSPORT=stdio",
        "-e", "NEO4J_NAMESPACE=myapp",
        "mcp/neo4j-data-modeling:latest"
      ]
    }
  }
}

🐳 Docker 部署

Neo4j Data Modeling MCP 服务可以使用 Docker 进行部署，以支持远程部署。Docker 部署应使用 HTTP 传输，以便通过 Web 访问。要将此部署与 Claude Desktop 等应用程序集成，您需要在 MCP 配置中使用代理，例如 mcp-remote。

📦 使用构建的镜像

使用 docker build -t mcp-neo4j-data-modeling:latest . 在本地构建后：

# Run with http transport (default for Docker)
docker run --rm -p 8000:8000 \
  -e NEO4J_TRANSPORT="http" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  -e NEO4J_MCP_SERVER_PATH="/mcp/" \
  mcp/neo4j-data-modeling:latest

# Run with security middleware for production
docker run --rm -p 8000:8000 \
  -e NEO4J_TRANSPORT="http" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  -e NEO4J_MCP_SERVER_PATH="/mcp/" \
  -e NEO4J_MCP_SERVER_ALLOWED_HOSTS="example.com,www.example.com" \
  -e NEO4J_MCP_SERVER_ALLOW_ORIGINS="https://example.com" \
  mcp/neo4j-data-modeling:latest

🔧 环境变量

变量	默认值	描述
NEO4J_TRANSPORT	stdio（本地），http（远程）	传输协议（stdio、http 或 sse）
NEO4J_MCP_SERVER_HOST	127.0.0.1（本地）	要绑定的主机
NEO4J_MCP_SERVER_PORT	8000	HTTP/SSE 传输使用的端口
NEO4J_MCP_SERVER_PATH	/mcp/	访问 MCP 服务的路径
NEO4J_NAMESPACE	（空值——无前缀）	工具名称的命名空间前缀（例如，myapp-validate_node）
NEO4J_MCP_SERVER_ALLOW_ORIGINS	（空值——默认安全）	允许的 CORS 来源列表，以逗号分隔
NEO4J_MCP_SERVER_ALLOWED_HOSTS	localhost,127.0.0.1	允许的主机列表，以逗号分隔（防止 DNS 重绑定）

🌐 用于旧版 Web 访问的 SSE 传输

使用 SSE 传输（适用于旧版 Web 客户端）时，服务会公开一个 HTTP 端点：

# Start the server with SSE transport
docker run -d -p 8000:8000 \
  -e NEO4J_TRANSPORT="sse" \
  -e NEO4J_MCP_SERVER_HOST="0.0.0.0" \
  -e NEO4J_MCP_SERVER_PORT="8000" \
  --name neo4j-data-modeling-mcp-server \
  mcp-neo4j-data-modeling:latest

# Test the SSE endpoint
curl http://localhost:8000/sse

# Use with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8000/sse

🚀 开发

📦 前置条件

1. 安装 uv（Universal Virtualenv）：

# Using pip
pip install uv

# Using Homebrew on macOS
brew install uv

# Using cargo (Rust package manager)
cargo install uv

2. 克隆代码库并设置开发环境：

# Clone the repository
git clone https://github.com/yourusername/mcp-neo4j-data-modeling.git
cd mcp-neo4j-data-modeling

# Create and activate virtual environment using uv
uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows

# Install dependencies including dev dependencies
uv pip install -e ".[dev]"

3. 运行测试

./test.sh

🔧 开发配置

# Add the server to your claude_desktop_config.json
"mcpServers": {
  "neo4j-data-modeling": {
    "command": "uv",
    "args": [
      "--directory", "path_to_repo/src",
      "run", "mcp-neo4j-data-modeling", "--transport", "stdio"]
  }
}

🐳 Docker

构建并运行 Docker 容器：

# Build the image
docker build -t mcp/neo4j-data-modeling:latest .

# Run the container
docker run mcp/neo4j-data-modeling:latest

📄 许可证

此 MCP 服务采用 MIT License 许可。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT License 的条款和条件。有关详情，请参阅项目代码库中的 LICENSE 文件。