MCP Server Zep Cloud

🚀 Zep Cloud MCP 服務器

Zep Cloud MCP 服務器搭建了 Claude Desktop 與 Zep Cloud API 之間的橋樑，實現了對 AI 助手記憶的有效管理。

🚀 快速開始

安裝與配置

1. 克隆倉庫

git clone [your-repository-url]
cd mcp-server

2. 創建並激活虛擬環境（推薦）

python -m venv venv
source venv/bin/activate  # 在 Windows 上使用 `venv\Scripts\activate`
pip install -r requirements.txt

3. 配置環境變量

• 複製 .env.example 到 .env 並添加你的 API 密鑰：

  cp .env.example .env
  nano .env
  

  更新以下內容：

  ZEPCLOUD_API_KEY=your_api_key_here
  

4. 啟動服務器

python core/zep_cloud_server.py

使用說明

通過終端訪問工具

• 訪問 http://localhost:5000，使用你的 Zep Cloud API 密鑰登錄。
• 瀏覽可用工具並按需使用。

配置 Claude Desktop

1. 複製 claude_desktop_config.json.example 到 claude_desktop_config.json：

   cp claude_desktop_config.json.example claude_desktop_config.json
   

2. 更新配置文件中的路徑和 API 密鑰：

   {
     "mcp_server_url": "http://localhost:5000",
     "api_key": "your_api_key_here"
   }
   

✨ 主要特性

• 用戶管理：可在 Zep Cloud 中創建、檢索、更新和刪除用戶。
• 集合管理：能夠創建和管理記憶收藏集。
• 記憶操作：支持添加、檢索和搜索記憶。
• 現代實現：採用 FastMCP 方法，實現了更高效且易於維護的服務器。
• 降回模式：若無法連接到 Zep Cloud API（如因身份驗證或網絡問題），將切換到本地模式，不過僅支持部分功能。

📦 安裝指南

克隆倉庫

git clone [your-repository-url]
cd mcp-server

創建並激活虛擬環境（推薦）

python -m venv venv
source venv/bin/activate  # 在 Windows 上使用 `venv\Scripts\activate`
pip install -r requirements.txt

配置環境變量

• 複製 .env.example 到 .env 並添加你的 API 密鑰：

  cp .env.example .env
  nano .env
  

  更新以下內容：

  ZEPCLOUD_API_KEY=your_api_key_here
  

啟動服務器

python core/zep_cloud_server.py

💻 使用示例

可用工具

• 用戶管理：create_user, get_user, update_user, delete_user, list_users
• 集合管理：create_collection, get_collection, update_collection, delete_collection, list_collections
• 記憶操作：add_memory, get_memory, list_memories, search_memories

📚 詳細文檔

倉庫結構

該倉庫已組織如下目錄：

• core/：核心功能文件

  • zep_cloud_client.py：Zep Cloud API 的客戶端實現
  • zep_cloud_server.py：提供 Claude Desktop 工具的 MCP 服務器
  • run_server.py：直接運行服務器的獨立腳本

• scripts/：操作實用腳本

  • check_user_exists.py：檢查 Zep Cloud 中是否存在用戶
  • create_specific_user.py：創建特定用戶到 Zep Cloud 的腳本
  • run_server.sh / run_server.bat：帶有環境設置的運行服務器的 Shell 腳本
  • 多種其他測試和調試實用腳本

• tests/：按功能組織的測試腳本

  • test_specific_user.py：所有用戶操作的全面測試
  • test_zep_cloud_client.py：Zep Cloud 客戶端單元測試
  • test_comprehensive.py：所有功能的完整 API 測試

• config/：配置文件

  • .env.example：環境配置模板
  • .env.new：更新後的環境配置
  • claude_desktop_config.json.example：Claude Desktop 配置模板
  • requirements.txt：包依賴項

🔧 技術細節

現代實現

使用 FastMCP 方法實現更高效和可維護的服務器。

降回模式

如果無法連接到 Zep Cloud API（由於身份驗證問題、網絡問題等），將切換到本地模式，僅支持部分功能。

⚠️ 重要提示

API 密鑰保護

• 絕不要將 API 密鑰提交到版本控制。.gitignore 文件配置為忽略 .env 文件。
• 使用提供的 .env.example 作為模板，並使用實際 API 密鑰創建自己的 .env 文件。

配置文件

• 個人配置文件如 claude_desktop_config.json 包含系統特定路徑，不應提交到版本控制中。
• 使用提供的 claude_desktop_config.json.example 作為參考來創建和更新配置文件。

📄 故障排除

有關故障排除信息，請參閱 AUTHENTICATION_NOTE.md 文檔，其中包含關於 API 連接性和身份驗證問題的詳細信息。