MCP知识图谱项目文档

项目概述

简介

MCP（Medical Cybernetics Platform）知识图谱项目旨在利用Neo4j图数据库构建和管理医学领域的知识图谱。该项目提供了丰富的功能模块，包括数据导入、实体操作、关系管理以及模式洞察等。

核心组件

1. MCP客户端：用于与Neo4j数据库进行交互。
2. 配置工具：负责配置文件的加载和验证。
3. Neo4j连接测试：确保数据库 connectivity 和基本查询功能。
4. 集成测试：验证整个系统的完整性和兼容性。

功能模块

1. MCP客户端功能

• 启动服务器：运行命令 task run 启动MCP服务。
• 工具列表：通过访问 /tools 接口获取可用工具信息。
• 模式洞察：调用 /schema 接口获取数据库 schema 详情，包括节点标签、关系类型及其属性。

2. MCP配置管理

• 配置文件加载：验证 config.yaml 文件的正确性。
• 连接测试：使用官方MCP SDK测试与数据库的连接状态。
• 工具可用性检查：确保所有必需工具均已安装到位。

3. Neo4j数据库连接

• 连通性验证：通过基础查询测试数据库是否可达。
• 环境配置：检查和确认运行环境设置符合要求。

测试框架

测试脚本分类

1. mcp_neo4j_knowledge_graph/test_mcp_client.py：

   • 验证服务器启动状态
   • 测试工具列表接口
   • 模式洞察功能验证
   • 实体创建操作测试

   task test-client  # 仅运行客户端测试
   

2. mcp_neo4j_knowledge_graph/test_mcp_config.py：

   • 测试配置文件加载逻辑
   • 验证MCP SDK连接状态
   • 确保所有工具可用

   task test-config  # 仅运行配置测试
   

3. mcp_neo4j_knowledge_graph/test_neo4j_connection.py：

   • 测试数据库连通性
   • 验证基本查询功能
   • 确认环境配置无误

   task test-db  # 仅运行数据库测试
   

测试运行方式

1. 全部测试：

   task test  # 运行所有测试包括 pytest 和集成测试
   

2. 按类型运行：

   task test-client    # 运行MCP客户端测试
   task test-config    # 运行MCP配置测试
   task test-db        # 运行Neo4j连接测试
   task test-integration  # 运行集成测试
   

3. 直接使用 pytest：

   poetry run pytest  # 执行所有pytest兼容的测试用例
   

开发环境

使用 Task 命令

项目提供了多个开发任务命令：

# 格式化代码
task format

# 运行代码检查
task lint

# 执行测试
task test

# 启动开发环境
task dev

直接运行工具

借助 Poetry 管理的开发工具包括：

• black：代码格式化
• isort：导入排序
• flake8：代码检查
• pytest：单元测试

使用方法如下：

# 格式化代码
poetry run black .

# 排序导入
poetry run isort .

# 运行代码检查
poetry run flake8

# 执行测试
poetry run pytest

错误处理

服务器实现了全面的错误处理机制，涵盖以下场景：

• 数据库连接问题
• 无效查询
• 节点缺失
• 请求格式错误
• 模式验证失败
• 关系创建异常
• 实体更新冲突

所有错误均返回符合MCP协议的错误信息。

Docker 配置

Neo4j容器配置如下：

• 端口：7474（HTTP）和 7687（Bolt）
• 默认凭据：neo4j/password
• APOC插件启用
• 文件导入导出允许
• 健康检查配置

可在 docker-compose.yml 文件中修改这些设置。

Task 命令参考

# 启动服务
task run

# 执行测试
task test

# 格式化代码
task format

# 运行检查
task lint

# 启动开发环境