Graphiti MCP But Working

🚀 Graphiti MCP Server - 增强版分支

Graphiti 是一个用于构建和查询时间感知知识图谱的框架，专为在动态环境中运行的 AI 智能体量身定制。与传统的检索增强生成（RAG）方法不同，Graphiti 能够持续将用户交互、结构化和非结构化企业数据以及外部信息整合到一个连贯且可查询的图中。该框架支持增量数据更新、高效检索和精确的历史查询，而无需对整个图进行重新计算，非常适合开发交互式、上下文感知的 AI 应用程序。

这是 Graphiti 的一个增强版模型上下文协议（MCP）服务器实现。MCP 服务器通过 MCP 协议公开 Graphiti 的关键功能，使 AI 助手能够与 Graphiti 的知识图谱功能进行交互。

✨ 主要特性

此分支的关键增强功能

此增强版本在原始实现的基础上进行了多项重要改进：

1. 🚀 与最新的 Graphiti 核心兼容：使用 graphiti-core 的当前版本，具备所有最新特性和改进。
2. 🤖 支持 GPT - 5、O1、O3 模型：能够正确处理 OpenAI 的推理模型，并自动调整参数（禁用温度、推理和冗长参数）。
3. 🔒 基于令牌的身份验证：具备生产就绪的随机数令牌身份验证系统，可通过 SSE 传输实现安全的公共部署。
4. 📊 新增 list_group_ids 工具：可发现和管理知识图谱中跨节点和关系的所有组 ID。
5. 🛡️ 增强的安全性：采用纯 ASGI 中间件的身份验证，使用常量时间令牌比较以防止时序攻击。
6. 🔇 遥测控制：对于注重隐私的部署，可自动禁用遥测（在导入 graphiti_core 之前设置）。
7. ⚡ 简化依赖：移除了 Azure OpenAI 依赖，便于设置和部署。

关于 Azure 支持

关于 Azure OpenAI 的说明：由于与新的身份验证中间件存在实现冲突，在重构过程中移除了对 Azure OpenAI 的支持。如果您需要此增强版 MCP 服务器支持 Azure OpenAI，欢迎提交拉取请求！原始实现可在 上游 Graphiti 仓库 中找到。

关于此分支

此分支在保持与最新 Graphiti 核心兼容的同时，添加了适用于安全公共部署的生产就绪功能。它侧重于与 OpenAI API 兼容以及增强安全特性。

Graphiti MCP 服务器公开的主要高级功能

• 情节管理：添加、检索和删除情节（文本、消息或 JSON 数据）。
• 实体管理：搜索和管理知识图谱中的实体节点和关系。
• 搜索功能：使用语义和混合搜索查找事实（边）和节点摘要。
• 组管理：使用 group_id 过滤来组织和管理相关数据组。
• 图维护：清除图并重建索引。

🚀 快速开始

克隆此增强版分支

git clone https://github.com/michabbb/graphiti-mcp-but-working.git
cd graphiti-mcp-but-working

或者

gh repo clone michabbb/graphiti-mcp-but-working
cd graphiti-mcp-but-working

对于 Claude Desktop 和其他仅支持 stdio 的客户端

1. 记录此目录的完整路径。

pwd

2. 安装 Graphiti 先决条件。
3. 配置 Claude、Cursor 或其他 MCP 客户端以使用 带有 。查看客户端文档以了解在哪里找到其 MCP 配置文件。

对于 Cursor 和其他支持 sse 的客户端（推荐）

1. 配置环境变量（将 .env.example 复制为 .env，并设置 OPENAI_API_KEY）。
2. 使用 Docker Compose 启动服务。

docker compose up

3. 将 MCP 客户端指向 http://localhost:8000/sse。

对于安全的公共部署，请参阅 身份验证指南 以设置随机数令牌身份验证。

📦 安装指南

先决条件

1. 确保已安装 Python 3.10 或更高版本。
2. 运行中的 Neo4j 数据库（需要版本 5.26 或更高）。
3. 用于 LLM 操作的 OpenAI API 密钥。

设置步骤

1. 克隆仓库并导航到 mcp_server 目录。
2. 使用 uv 创建虚拟环境并安装依赖项：

# 如果尚未安装 uv，请进行安装
curl -LsSf https://astral.sh/uv/install.sh | sh

# 一步完成创建虚拟环境和安装依赖项
uv sync

📚 详细文档

配置

服务器使用以下环境变量：

您可以在项目目录的 .env 文件中设置这些变量。

运行服务器

使用 uv 直接运行 Graphiti MCP 服务器：

uv run graphiti_mcp_server.py

带选项运行：

uv run graphiti_mcp_server.py --model gpt-4.1-mini --transport sse

可用参数：

• --model：覆盖 MODEL_NAME 环境变量。
• --small-model：覆盖 SMALL_MODEL_NAME 环境变量。
• --temperature：覆盖 LLM_TEMPERATURE 环境变量。
• --transport：选择传输方法（sse 或 stdio，默认：sse）。
• --group-id：为图设置命名空间（可选）。如果未提供，默认为 "default"。
• --destroy-graph：如果设置，在启动时销毁所有 Graphiti 图。
• --use-custom-entities：启用使用预定义的 ENTITY_TYPES 进行实体提取。

并发和 LLM 提供商 429 速率限制错误

Graphiti 的摄入管道设计为支持高并发，由 SEMAPHORE_LIMIT 环境变量控制。默认情况下，SEMAPHORE_LIMIT 设置为 10 个并发操作，以帮助防止来自 LLM 提供商的 429 速率限制错误。如果遇到此类错误，请尝试降低此值。

如果您的 LLM 提供商允许更高的吞吐量，可以增加 SEMAPHORE_LIMIT 以提高情节摄入性能。

Docker 部署

Graphiti MCP 服务器可以使用 Docker 进行部署。Dockerfile 使用 uv 进行包管理，确保依赖项的一致安装。

环境配置

在运行 Docker Compose 设置之前，您需要配置环境变量。有两种选择：

1. 使用 .env 文件（推荐）：
   • 复制提供的 .env.example 文件以创建 .env 文件：

cp .env.example .env

- 编辑 `.env` 文件以设置您的 OpenAI API 密钥和其他配置选项：

# LLM 操作必需
OPENAI_API_KEY=your_openai_api_key_here
MODEL_NAME=gpt-4.1-mini
# 可选：仅非标准 OpenAI 端点需要 OPENAI_BASE_URL
# OPENAI_BASE_URL=https://api.openai.com/v1

- 如果 `.env` 文件存在，Docker Compose 设置将配置为使用该文件（可选）。

2. 直接使用环境变量：
   • 您也可以在运行 Docker Compose 命令时设置环境变量：

OPENAI_API_KEY=your_key MODEL_NAME=gpt-4.1-mini docker compose up

Neo4j 配置

Docker Compose 设置包含一个 Neo4j 容器，具有以下默认配置：

• 用户名：neo4j
• 密码：demodemo
• URI：bolt://neo4j:7687（在 Docker 网络内）
• 内存设置针对开发使用进行了优化。

使用 Docker Compose 运行

Graphiti MCP 容器可在 zepai/knowledge - graph - mcp 中获取。下面的 Compose 设置使用该容器的最新构建。 使用 Docker Compose 启动服务：

docker compose up

或者，如果您使用的是旧版本的 Docker Compose：

docker-compose up

这将同时启动 Neo4j 数据库和 Graphiti MCP 服务器。Docker 设置：

• 使用 uv 进行包管理和运行服务器。
• 从 pyproject.toml 文件安装依赖项。
• 使用环境变量连接到 Neo4j 容器。
• 通过端口 8000 公开服务器以进行基于 HTTP 的 SSE 传输。
• 包含 Neo4j 的健康检查，以确保在启动 MCP 服务器之前它已完全运行。

与 MCP 客户端集成

配置

要将 Graphiti MCP 服务器与 MCP 兼容的客户端一起使用，请将其配置为连接到服务器：

⚠️ 重要提示

您需要安装 Python 包管理器 uv。请参阅 《uv 安装说明》。

确保设置 uv 二进制文件和 Graphiti 项目文件夹的完整路径。

{
  "mcpServers": {
    "graphiti-memory": {
      "transport": "stdio",
      "command": "/Users/<user>/.local/bin/uv",
      "args": [
        "run",
        "--isolated",
        "--directory",
        "/Users/<user>>/dev/zep/graphiti/mcp_server",
        "--project",
        ".",
        "graphiti_mcp_server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password",
        "OPENAI_API_KEY": "sk-XXXXXXXX",
        "MODEL_NAME": "gpt-4.1-mini"
      }
    }
  }
}

对于 SSE 传输（基于 HTTP），您可以使用以下配置：

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

可用工具

Graphiti MCP 服务器公开了以下工具：

• add_episode：向知识图谱添加情节（支持文本、JSON 和消息格式）。
• search_nodes：在知识图谱中搜索相关节点摘要。
• search_facts：在知识图谱中搜索相关事实（实体之间的边）。
• delete_entity_edge：从知识图谱中删除实体边。
• delete_episode：从知识图谱中删除情节。
• get_entity_edge：按 UUID 获取实体边。
• get_episodes：获取特定组的最新情节。
• clear_graph：清除知识图谱中的所有数据并重建索引。
• get_status：获取 Graphiti MCP 服务器和 Neo4j 连接的状态。

处理 JSON 数据

Graphiti MCP 服务器可以通过 add_episode 工具处理结构化 JSON 数据，设置 source="json"。这允许您从结构化数据中自动提取实体和关系：

add_episode(
    name="Customer Profile",
    episode_body="{\"company\": {\"name\": \"Acme Technologies\"}, \"products\": [{\"id\": \"P001\", \"name\": \"CloudSync\"}, {\"id\": \"P002\", \"name\": \"DataMiner\"}]}",
    source="json",
    source_description="CRM data"
)

与 Cursor IDE 集成

要将 Graphiti MCP 服务器与 Cursor IDE 集成，请按照以下步骤操作：

1. 使用 SSE 传输运行 Graphiti MCP 服务器：

python graphiti_mcp_server.py --transport sse --use-custom-entities --group-id <your_group_id>

提示：指定 group_id 以对图数据进行命名空间管理。如果未指定 group_id，服务器将使用 "default" 作为组 ID。 或者

docker compose up

2. 配置 Cursor 以连接到 Graphiti MCP 服务器。

{
  "mcpServers": {
    "graphiti-memory": {
      "url": "http://localhost:8000/sse"
    }
  }
}

3. 将 Graphiti 规则添加到 Cursor 的用户规则中。详情请参阅 cursor_rules.md。
4. 在 Cursor 中启动智能体会话。

此集成使 Cursor 中的 AI 助手能够通过 Graphiti 的知识图谱功能保持持久记忆。

与 Claude Desktop（Docker MCP 服务器）集成

Graphiti MCP 服务器容器使用 SSE MCP 传输。Claude Desktop 原生不支持 SSE，因此您需要使用像 mcp - remote 这样的网关。

1. 使用 SSE 传输运行 Graphiti MCP 服务器：

docker compose up

2. （可选）全局安装 mcp - remote： 如果您希望全局安装 mcp - remote，或者在使用 npx 获取包时遇到问题，可以全局安装它。否则，npx（用于下一步）将为您处理。

npm install -g mcp-remote

3. 配置 Claude Desktop： 打开您的 Claude Desktop 配置文件（通常为 claude_desktop_config.json），并按如下方式添加或修改 mcpServers 部分：

{
  "mcpServers": {
    "graphiti-memory": {
      // 您可以选择不同的名称
      "command": "npx", // 或者如果 npx 不在您的路径中，则为 mcp - remote 的完整路径
      "args": [
        "mcp-remote",
        "http://localhost:8000/sse" // 确保这与您的 Graphiti 服务器的 SSE 端点匹配
      ]
    }
  }
}

如果您已经有一个 mcpServers 条目，请将 graphiti-memory（或您选择的名称）作为其中的一个新键添加。 4. 重启 Claude Desktop 以使更改生效。

要求

• Python 3.10 或更高版本。
• Neo4j 数据库（需要版本 5.26 或更高）。
• OpenAI API 密钥（用于 LLM 操作和嵌入）。
• MCP 兼容的客户端。

遥测

Graphiti MCP 服务器使用 Graphiti 核心库，其中包括匿名遥测收集。当您初始化 Graphiti MCP 服务器时，会收集匿名使用统计信息，以帮助改进框架。

收集内容

• 匿名标识符和系统信息（操作系统、Python 版本）。
• Graphiti 版本和配置选择（LLM 提供商、数据库后端、嵌入器类型）。
• 绝不收集个人数据、API 密钥或实际图内容。

如何禁用

要在 MCP 服务器中禁用遥测，请设置环境变量：

export GRAPHITI_TELEMETRY_ENABLED=false

或者将其添加到 .env 文件中：

GRAPHITI_TELEMETRY_ENABLED=false

有关收集内容和原因的完整详细信息，请参阅 Graphiti 主 README 中的遥测部分。

📄 许可证

本项目与父 Graphiti 项目采用相同的许可证。