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 項目採用相同的許可證。