Zep Cloud 的 MCP 服务器

Zep Cloud 的 MCP 服务器提供了一个 Claude Desktop 和 Zep Cloud API 之间的桥梁，从而实现 AI 助手的内存管理。

仓库结构

该仓库已组织成以下目录：

• core/: 核心功能文件

  • zep_cloud_client.py: Zep Cloud API 的客户端实现
  • zep_cloud_server.py: MCP 服务器，为 Claude Desktop 提供工具
  • 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: 包依赖项

功能

• 用户管理: 在 Zep Cloud 中创建、检索、更新和删除用户
• 集合管理: 创建和管理内存集合
• 内存操作: 添加、检索和搜索内存
• 现代实现: 使用 FastMCP 方法来实现更高效和可维护的服务器
• 回退模式: 如果 Zep Cloud API 不可访问，则自动以回退模式运行

要求

• Python 3.8+
• Zep Cloud API 密钥

安装

1. 克隆此仓库：

git clone https://github.com/yourusername/mcp-server-zep-cloud.git
cd mcp-server-zep-cloud

2. 创建并激活虚拟环境：

# 在 macOS/Linux 上
python -m venv venv
source venv/bin/activate

# 在 Windows 上
python -m venv venv
venv\Scripts\activate

3. 安装所需的包：

pip install -r config/requirements.txt

4. 将 config/.env.example 文件复制到 .env 并添加您的 Zep Cloud API 密钥：

cp config/.env.example .env

编辑 .env 文件并添加您的 Zep Cloud API 密钥：

ZEP_API_KEY=your_api_key_here

用法

启动服务器

要在 macOS/Linux 上启动服务器：

cd scripts
./run_server.sh

或者在 Windows 上：

cd scripts
run_server.bat

服务器将默认在 http://127.0.0.1:8000 上启动。

测试 API 连接

要测试用户是否存在于 Zep Cloud 中：

cd scripts
python check_user_exists.py [user_id]

要在 Zep Cloud 中创建特定用户：

cd scripts
python create_specific_user.py

回退模式

如果服务器无法连接到 Zep Cloud API（由于身份验证问题、网络问题或其他原因），它将自动以回退模式启动。 在此模式下：

• 所有 API 操作都将被模拟并返回成功
• 不会将实际数据发送到 Zep Cloud API 或从 Zep Cloud API 接收数据
• 将记录警告消息，指示服务器正在回退模式下运行
• 服务器将保持运行状态，允许 Claude Desktop 集成正常工作

要了解有关潜在身份验证问题以及如何解决这些问题的更多信息，请参阅 AUTHENTICATION_NOTE.md 文件。

配置 Claude Desktop

1. 打开您的 Claude Desktop 配置文件，位于：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 使用 Python 可执行文件和服务器脚本的绝对路径更新配置：

{
  "mcpServers": {
    "zep-cloud": {
      "command": "/ABSOLUTE/PATH/TO/venv/bin/python",
      "args": [
        "/ABSOLUTE/PATH/TO/core/zep_cloud_server.py"
      ]
    }
  }
}

重要提示:

• 将 /ABSOLUTE/PATH/TO/ 替换为虚拟环境中 Python 可执行文件和服务器脚本的实际路径。
• 使用绝对路径，而不是相对路径。
• 在 Windows 上，在路径中使用双反斜杠（例如，C:\\Users\\YourUsername\\...）。

Claude Desktop 中可用的工具

配置完成后，Claude Desktop 将可以访问以下工具：

1. 用户管理:

   • create_user: 创建新用户
   • get_user: 获取用户的详细信息
   • update_user: 更新用户的元数据
   • delete_user: 删除用户
   • list_users: 列出所有用户

2. 集合管理:

   • create_collection: 创建新集合
   • get_collection: 获取集合的详细信息
   • update_collection: 更新集合的元数据
   • delete_collection: 删除集合
   • list_collections: 列出所有集合

3. 内存操作:

   • add_memory: 为用户将内存添加到集合
   • get_memory: 为用户从集合中获取内存
   • list_memories: 为用户从集合中列出内存
   • search_memories: 为用户从集合中搜索内存

4. 连接性:

   • check_connection: 检查与 Zep Cloud API 的连接状态

故障排除

有关故障排除信息，请参阅 AUTHENTICATION_NOTE.md 文档，其中包含有关 API 连接和身份验证问题的详细信息。

安全注意事项

API 密钥保护

• 切勿将您的 API 密钥提交到版本控制。 .gitignore 文件已配置为防止提交 .env 文件。
• 使用提供的 .env.example 作为模板，并使用您的实际 API 密钥创建您自己的 .env 文件。
• 定期轮换您的 API 密钥，尤其是在您怀疑它们可能已泄露的情况下。

配置文件

• 像 claude_desktop_config.json 这样的个人配置文件包含特定于系统的路径，不应提交到版本控制。
• 使用提供的 claude_desktop_config.json.example 作为参考来创建您自己的配置。

首次设置以进行贡献

1. 在添加任何代码或配置文件之前，始终确保已提交 .gitignore
2. 将 .env.example 复制到 .env 并添加您的 API 密钥
3. 将 claude_desktop_config.json.example 复制到 claude_desktop_config.json 并使用您的路径进行更新
4. 在提交之前验证是否忽略了敏感文件：

   git status --ignored
   

安全检查

在提交代码之前，请始终检查您是否意外包含了：

• API 密钥或凭据
• 个人文件路径或用户名
• 可能包含敏感信息的日志文件
• 包含调试信息的临时文件