Neo4j MCP 服务器

这是一个使用 Neo4j 作为后端存储的知识图谱管理的内存控制协议 (MCP) 服务器实现。它提供了一个基于标准输入输出接口，用于以图数据库格式存储和检索知识。

前提条件

• Python 3.8+
• Neo4j 数据库（本地或远程）
• Poetry（Python 包管理器）
• Docker 和 Docker Compose（用于运行 Neo4j）
• Go Task（可选，用于任务自动化）

安装

1. 克隆仓库：

git clone <repository-url>
cd neo4j_mcp_server

1. 如果你还没有安装 Poetry，请先安装：

curl -sSL https://install.python-poetry.org | python3 -

1. 安装依赖项：

poetry install

配置

Claude 桌面配置

对于在 Ubuntu 上运行 Claude 桌面的用户，可以通过在以下位置添加 MCP 服务器到你的 Claude 桌面配置文件来配置 MCP 服务器：

~/.config/Claude/claude_desktop_config.json

在配置之前，你需要构建独立的可执行文件：

task build

这将在 dist/neo4j_mcp_server 创建一个二进制文件。确保在你的配置中更新路径指向这个构建的可执行文件。

示例配置文件在 example_mcp_config.json 中提供。你可以复制并修改这个文件：

cp example_mcp_config.json ~/.config/Claude/claude_desktop_config.json

然后编辑配置文件中的 command 路径，使其指向你构建的可执行文件：

{
  "mcpServers": [
    {
      "name": "neo4j-knowledge-graph",
      "command": ["/path/to/your/dist/neo4j_mcp_server"],
      ...
    }
  ]
}

配置包括：

• 服务器名称和描述
• 启动服务器的命令（指向构建的可执行文件的路径）
• 可用工具及其参数
• 必需字段和数据类型

运行服务器

使用 Task（推荐）

如果你已经安装了 Go Task，可以使用提供的 Taskfile 来管理服务器：

# Show available tasks
task

# Start everything (Docker + Server)
task run

# Start development environment (Docker + Server + Test)
task dev

# Stop all services
task down

直接使用 Docker Compose

1. 启动 Neo4j 容器：

docker-compose up -d

1. 等待 Neo4j 准备就绪（容器将在 docker ps 中显示为 "healthy"）

直接运行 MCP 服务器

使用以下命令启动服务器：

poetry run python mcp_neo4j_knowledge_graph/mcp/server.py

服务器将以标准输入输出模式启动，准备好接收 MCP 协议消息。

可用工具

1. 创建实体

在知识图谱中创建新实体。每个实体必须有类型和属性。如果未明确提供 ID，则会从 name 属性自动设置 ID。

参数：

• entities: 实体对象列表，每个包含：
  • type: 字符串 - 实体类型（例如，Person, Organization）
  • properties: 对象 - 实体属性的键值对（必须包含 'id' 或 'name'）

示例输入：

{
    "entities": [{
        "type": "Person",
        "properties": {
            "name": "John Doe",
            "occupation": "Developer",
            "age": 30
        }
    }]
}

2. 创建关系

在现有实体之间创建关系。所有引用的实体在创建关系之前必须存在。

参数：

• relations: 关系对象列表，每个包含：
  • type: 字符串 - 关系类型（例如，KNOWS, WORKS_FOR）
  • from: 字符串 - 源实体的 ID
  • to: 字符串 - 目标实体的 ID

示例输入：

{
    "relations": [{
        "type": "KNOWS",
        "from": "john_doe",
        "to": "jane_smith"
    }]
}

3. 搜索实体

搜索知识图谱中的实体。
（原文似乎在此处中断，没有提供关于“搜索实体”的更多详细信息或示例。）

在知识图谱中搜索实体，具有强大的文本匹配和过滤功能。可以用于按文本搜索、按类型列出实体、查找具有特定属性的实体，或这些过滤器的任意组合。

参数：

• search_term: 字符串（可选）- 在实体属性中搜索的文本。如果未提供，则根据其他过滤条件返回实体。
• entity_type: 字符串（可选）- 按实体类型（例如，人、组织）过滤结果。如果单独提供，将返回该类型的全部实体。
• properties: 字符串列表（可选）- 用于过滤的属性名称列表：
  • 结合 search_term 使用：在这些属性中搜索指定的术语
  • 不结合 search_term 使用：返回定义了这些属性中的任何一个的实体
• include_relationships: 布尔值（可选，默认为 false）- 是否包含连接的实体及其关系
• fuzzy_match: 布尔值（可选，默认为 true）- 当提供了 search_term 时，是否使用不区分大小写的部分匹配

示例输入：

// Search by text with type filter
{
    "search_term": "John",
    "entity_type": "Person",
    "properties": ["name", "occupation"],
    "include_relationships": true
}

// List all entities of a type
{
    "entity_type": "Person"
}

// Find entities with specific properties
{
    "properties": ["email", "phone"],
    "entity_type": "Contact"
}

// Combine filters
{
    "entity_type": "Person",
    "properties": ["email"],
    "search_term": "example.com",
    "fuzzy_match": true
}

// Return all entities (no filters)
{}

返回：

{
    "results": [
        {
            "id": "john_doe",
            "type": ["Entity", "Person"],
            "properties": {
                "name": "John Doe",
                "email": "john@example.com"
            },
            "relationships": [  // Only included if include_relationships is true
                {
                    "type": "WORKS_AT",
                    "direction": "outgoing",
                    "node": {
                        "id": "tech_corp",
                        "type": "Company",
                        "properties": {
                            "name": "Tech Corp"
                        }
                    }
                }
            ]
        }
    ]
}

注意事项：

• 当没有提供任何过滤条件时，返回所有实体
• 实体类型过滤是精确匹配（非模糊）
• 属性存在性检查通过 IS NOT NULL 完成
• 当 fuzzy_match 为真时，文本搜索支持不区分大小写的部分匹配
• 空结果以空数组形式返回，而不是错误
• 性能考虑：
  • 按类型过滤比文本搜索更高效
  • 属性存在性检查经过优化
  • 考虑使用特定属性而非搜索所有属性
  • 大量的结果集可能在未来版本中进行分页

4. 更新实体

更新知识图谱中的现有实体。支持添加/移除属性和标签。

参数：

• updates: 更新对象列表，每个对象包含：
  • id: 字符串（必填）- 要更新的实体ID
  • properties: 对象（可选）- 要更新或添加的属性
  • remove_properties: 字符串列表（可选）- 要移除的属性名称
  • add_labels: 字符串列表（可选）- 要添加到实体的标签
  • remove_labels: 字符串列表（可选）- 要从实体移除的标签

示例输入：

{
    "updates": [{
        "id": "john_doe",
        "properties": {
            "occupation": "Senior Developer",
            "salary": 100000
        },
        "remove_properties": ["temporary_note"],
        "add_labels": ["Verified"],
        "remove_labels": ["Pending"]
    }]
}

5. 删除实体

从知识图谱中删除实体，并可选择级联删除关联的关系。

参数：

• entity_ids: 字符串列表（必填）- 要删除的实体ID列表
• cascade: 布尔值（可选，默认为 false）- 是否删除关联的关系
• dry_run: 布尔值（可选，默认为 false）- 预览删除影响而不实际更改

示例输入：

{
    "entity_ids": ["john_doe", "jane_smith"],
    "cascade": true,
    "dry_run": true
}

返回：

{}

• success: 布尔值 - 操作是否成功
• deleted_entities: 已删除实体的列表
• deleted_relationships: 已删除关系的列表
• errors: 错误消息列表（如果有）
• impacted_entities: 会受到影响的实体列表（仅在 dry_run 时有效）
• impacted_relationships: 会受到影响的关系列表（仅在 dry_run 时有效）

6. 反省模式

检索有关 Neo4j 数据库模式的全面信息，包括节点标签、关系类型及其属性。

参数：无需提供

返回：

• schema: 包含以下内容的对象：
  • node_labels: 数据库中所有节点标签的列表
  • relationship_types: 所有关系类型的列表
  • node_properties: 标签到属性名称列表的映射
  • relationship_properties: 关系类型到属性名称列表的映射

示例输入：

{}

测试

测试脚本

项目包含了针对系统不同方面的多个测试脚本：

1. mcp_neo4j_knowledge_graph/test_mcp_client.py - 测试 MCP 客户端功能

   • 验证服务器启动
   • 测试工具列表
   • 测试模式反省
   • 测试实体创建

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

2. mcp_neo4j_knowledge_graph/test_mcp_config.py - 测试 MCP 配置

   • 验证配置文件加载
   • 使用官方 MCP SDK 测试服务器连接
   • 确认所有必需工具可用

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

3. mcp_neo4j_knowledge_graph/test_neo4j_connection.py - 测试 Neo4j 数据库连接

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

   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

项目包含几个开发任务：

# Format code
task format

# Run linter
task lint

# Run tests
task test

# Start development environment
task dev

直接运行

该项目使用了几个开发工具，这些工具会随着 Poetry 自动安装：

• black 用于代码格式化
• isort 用于导入排序
• flake8 用于代码检查
• pytest 用于测试

你可以使用 Poetry 运行这些工具：

# Format code
poetry run black .

# Sort imports
poetry run isort .

# Run linter
poetry run flake8

# Run tests
poetry run pytest

错误处理

服务器对以下情况进行了全面的错误处理：

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

所有错误都将以MCP协议格式返回适当的错误消息。

Docker配置

Neo4j容器配置了以下设置：

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

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

任务命令参考

• task - 显示可用任务
• task run - 启动Docker和MCP服务器
• task dev - 启动开发环境（Docker + 服务器 + 测试）
• task docker - 启动Neo4j数据库
• task server - 运行MCP服务器
• task test - 运行所有测试
• task test-client - 运行MCP客户端测试
• task test-config - 运行MCP配置测试
• task test-db - 运行数据库测试
• task test-integration - 运行集成测试
• task down - 停止所有Docker服务
• task format - 使用black和isort格式化代码
• task lint - 运行flake8 linter
• task help - 显示所有任务的详细帮助信息