Information
Neo4j MCP 服务器
这是一个使用 Neo4j 作为后端存储的知识图谱管理的内存控制协议 (MCP) 服务器实现。它提供了一个基于标准输入输出接口，用于以图数据库格式存储和检索知识。
前提条件
Python 3.8+
Neo4j 数据库（本地或远程）
Poetry（Python 包管理器）
Docker 和 Docker Compose（用于运行 Neo4j）
Go Task（可选，用于任务自动化）
安装
克隆仓库：
git clone
cd neo4j_mcp_server
如果你还没有安装 Poetry，请先安装：
curl -sSL https://install.python-poetry.org | python3 -
安装依赖项：
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
启动 Neo4j 容器：
docker-compose up -d
等待 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: 关系类型到属性名称列表的映射
示例输入：
\{\}
测试
测试脚本
项目包含了针对系统不同方面的多个测试脚本：
mcp_neo4j_knowledge_graph/test_mcp_client.py - 测试 MCP 客户端功能
验证服务器启动
测试工具列表
测试模式反省
测试实体创建
task test-client # 仅运行客户端测试
mcp_neo4j_knowledge_graph/test_mcp_config.py - 测试 MCP 配置
验证配置文件加载
使用官方 MCP SDK 测试服务器连接
确认所有必需工具可用
task test-config # 仅运行配置测试
mcp_neo4j_knowledge_graph/test_neo4j_connection.py - 测试 Neo4j 数据库连接
验证数据库连通性
测试基本查询功能
检查环境配置
task test-db # 仅运行数据库测试
运行测试
你可以通过多种方式运行测试：
同时运行所有测试：
task test # 运行所有测试，包括 pytest 和集成测试
单独运行特定类型的测试：
task test-client # 运行 MCP 客户端测试
task test-config # 运行 MCP 配置测试
task test-db # 运行 Neo4j 连接测试
task test-integration # 运行集成测试
直接使用 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 - 显示所有任务的详细帮助信息