AI导哈

知识图谱操作工具

Graphiti MCP Server Extended 是一个扩展版本的知识图谱服务器，提供路径查找、子图提取和知识图谱遍历等高级图操作功能，适用于复杂知识图谱分析和关系发现。

  • by mkXultra
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 mkXultra/graphiti-mcp-server

使用说明

Graphiti MCP服务器扩展

的扩展版本 Graphiti MCP服务器 具有用于高级知识图操作的附加图操作工具。

此存储库是从原始Graphiti MCP Server分叉而来的，并添加了用于路径查找和子图提取的自定义工具，从而实现了更复杂的图分析功能。

🆕 附加功能

这个扩展版本增加了三个强大的图形操作工具：

1. find_paths_between_entities

在知识图中找到两个实体之间的所有路径。

特征：

  • 发现实体之间的多条路径
  • 可配置的最大路径深度
  • 返回详细的节点和边缘信息
  • 排除情节节点以获得更清晰的知识路径
  • 仅针对实体到实体关系进行了优化

参数：

  • from_uuid：启动实体UUID
  • to_uuid：目标实体UUID
  • max_depth：最大路径长度（默认值：5）
  • max_paths：要返回的最大路径数（默认值：10）

2. build_subgraph

提取以指定实体为中心的子图。

特征：

  • 从多个实体起点构建子图
  • 可配置的扩展深度（max_hop）
  • 子图中实体之间的可选路径查找
  • 返回带有邻接表的完整图结构
  • 自动排除较小响应大小的嵌入字段

参数：

  • entity_uuids：要包含的实体UUID列表
  • max_hop：与起始图元的最大距离（默认值：1）
  • include_paths：是否查找实体之间的路径（默认值：False）

3. traverse_knowledge_graph

从单个起始节点遍历知识图。

特征：

  • 具有可配置深度的单节点遍历
  • 嵌套结构，按层次显示关系
  • 循环检测，防止无限递归
  • 包含事实和关系的详细边缘信息

参数：

  • start_node_uuid：起始实体的UUID
  • depth：横向深度（0=仅节点，1=直接关系等）

🎯 设计理念

此扩展遵循Graphiti核心的设计原则：

  1. 以实体为中心：结果中仅包含实体节点和RELATES_TO边
  2. 偶发性排除：情节节点被有意排除在外，因为它们是用于数据来源，而不是知识结构
  3. 嵌入优化：所有嵌入字段都会自动排除，以保持响应大小可控
  4. MCP兼容性：响应大小已优化，以保持在MCP的25000个令牌限制范围内

📊 性能优化

  • 响应大小减少94% 通过智能嵌入排除
  • 单独查询 用于节点和边，以最大限度地减少数据传输
  • Pydantic模型_泵 通过嵌套字段排除实现高效序列化
  • Graphiti核心功能 始终用于一致性和性能

🚀 快速开始

选项1：使用Docker（推荐）

# Pull the pre-built image
docker pull ghcr.io/mkxultra/graphiti-mcp-server-extended:latest

# Run with docker-compose
docker compose up

# Or run standalone
docker run -p 8000:8000 \
  -e NEO4J_URI=bolt://your-neo4j:7687 \
  -e NEO4J_USER=neo4j \
  -e NEO4J_PASSWORD=your-password \
  -e OPENAI_API_KEY=your-api-key \
  ghcr.io/mkxultra/graphiti-mcp-server-extended:latest

选项2：本地安装

先决条件：

  1. Python 3.10或更高版本
  2. Neo4j数据库（5.26+版本）
  3. 用于LLM操作的OpenAI API密钥
# Clone this repository
git clone https://github.com/mkXultra/graphiti-mcp-server.git
cd graphiti-mcp-server

# Install dependencies with uv
curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

配置

创建一个 .env 文件：

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password
OPENAI_API_KEY=your_api_key
MODEL_NAME=gpt-4-mini

运行服务器

# Run with uv
uv run graphiti_mcp_server.py

# Or with Docker
docker compose up

🔧 MCP客户端配置

适用于克劳德桌面（stdio传输）

{
  "mcpServers": {
    "graphiti-extended": {
      "transport": "stdio",
      "command": "/path/to/uv",
      "args": [
        "run",
        "--directory",
        "/path/to/graphiti-mcp-server",
        "graphiti_mcp_server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password",
        "OPENAI_API_KEY": "sk-XXXXXXXX"
      }
    }
  }
}

用于光标（SSE传输）

{
  "mcpServers": {
    "graphiti-extended": {
      "transport": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

📚 可用工具

原始图形工具

  • add_memory：将剧集添加到知识图中
  • search_memory_nodes：搜索实体节点
  • search_memory_facts：搜索关系
  • delete_entity_edge：删除边缘
  • delete_episode：删除剧集
  • get_entity_edge：获取边缘细节
  • get_episodes：检索最近的剧集
  • clear_graph：重置图形

🆕 扩展工具（此叉）

  • find_paths_between_entities：发现实体之间的路径
  • build_subgraph：提取实体周围的子图
  • traverse_knowledge_graph：单节点图遍历

💡 使用示例

在实体之间查找路径

# Find how two people are connected
result = await find_paths_between_entities(
    from_uuid="person1_uuid",
    to_uuid="person2_uuid",
    max_depth=3,
    max_paths=5
)
# Returns multiple paths showing relationships

构建子图

# Extract a local graph around specific entities
result = await build_subgraph(
    entity_uuids=["entity1_uuid", "entity2_uuid"],
    max_hop=2,  # Include entities up to 2 hops away
    include_paths=True  # Find paths between included entities
)
# Returns complete subgraph with nodes, edges, and adjacency list

从单个节点遍历

# Traverse the graph from a single starting point
result = await traverse_knowledge_graph(
    start_node_uuid="entity_uuid",
    depth=2  # Traverse 2 levels deep
)
# Returns nested structure showing relationships hierarchically

🏗️ 建筑

graphiti-mcp-server/
├── graphiti_mcp_server.py    # Main MCP server
├── src/
│   └── tools/
│       ├── __init__.py
│       └── graph_functions.py  # New graph manipulation tools
├── tests/
│   └── test_graph_functions.py # Comprehensive test suite
└── docker-compose.yml          # Docker setup with Neo4j

🧪 测试

先决条件

测试套件需要一个单独的Neo4j测试数据库，以避免影响您的主要数据。

运行测试

# 1. Start the test database
docker-compose -f docker-compose.test.yml up -d

# 2. Wait for the database to be ready
sleep 5

# 3. Run all tests (using uv for dependency management)
OPENAI_API_KEY=dummy uv run python -m pytest src/tests/ -v

# Or run specific test class
OPENAI_API_KEY=dummy uv run python -m pytest src/tests/test_graph_functions.py::TestFindPathsBetweenEntities -v

# Or run specific test method
OPENAI_API_KEY=dummy uv run python -m pytest src/tests/test_graph_functions.py::TestFindPathsBetweenEntities::test_find_direct_path -v

# Alternative: without uv (requires manual dependency installation)
# OPENAI_API_KEY=dummy python3 -m pytest src/tests/ -v

# 4. Stop the test database when done
docker-compose -f docker-compose.test.yml down

测试数据库配置

  • 端口：7688（螺栓）
  • 端口：7475（HTTP）
  • 用户名：neo4j
  • 密码：testpassword

注： 这 OPENAI_API_KEY 可以是Graphiti核心所要求的任何虚拟值，但实际上并未在测试中使用。

🤝 贡献

欢迎投稿！此分叉在添加扩展功能的同时保持了与上游Graphiti项目的兼容性。

开发指南

  1. 遵循Graphiti核心设计模式
  2. 从知识操作中排除偶发节点
  3. 优化MCP令牌限制
  4. 尽可能使用Graphiti核心功能
  5. 为新功能添加全面的测试

📄 许可证

此项目与父Graphiti项目保持相同的许可证。

🙏 致谢

  • 原创 图形 Zep项目
  • 基于Graphiti核心框架构建
  • Anthropic的MCP协议

📊 技术细节

响应大小优化

  • 使用Pydantic的嵌套字段排除排除排除嵌入
  • 响应大小从约93596个令牌减少到约5861个令牌（减少94%）
  • 25000令牌限制下的MCP兼容响应

查询优化

  • 对路径、节点和边进行单独查询
  • 使用RELATES_TO边进行仅实体遍历
  • 多个实体的批处理

工具比较

工具 起点 结构 最适合
find_paths_between_entities 2个实体 仅路径 关系发现
build_subgraph 多个实体 全图 邻里探索
traverse_knowledge_graph 单个实体 嵌套层次结构 深度遍历

代码质量

  • 110+次综合测试，通过率100%
  • 全程键入提示
  • 一致的错误处理
  • 用于调试的广泛日志记录

相关 MCP