AI导哈

Zep云MCP服务器

MCP Server for Zep Cloud是一个连接LLM客户端和Zep云API的桥梁，用于管理AI助手的记忆功能。

  • by Vasiliy-Bondarenko
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 vasiliy-bondarenko/mcp-server-zep-cloud

使用说明

Zep Cloud的MCP服务器

Zep Cloud的MCP服务器提供了LLM客户端和Zep Cloud API之间的桥梁，为人工智能助手实现内存管理。

概述

MCP服务器，用于通过Zep Cloud API存储和检索用户记忆、偏好、程序和事实关系。它充当语义记忆层，使AI助手能够在对话中维护用户的上下文。

工具

  1. 用户管理:

    • create_user：使用可选的元数据、名称和电子邮件创建新用户
    • get_user：按ID获取用户详细信息
    • update_user：更新用户的元数据
    • delete_user：永久删除用户
    • list_users：列出支持分页的用户

  2. 图的运算:

    • search_graph：搜索用户或组的内存图（灵活的user_id/group_id）
    • add_graph_data：添加带有可选时间戳和源信息的数据

  3. 组管理:

    • create_group：创建共享知识的新组
    • get_group：按ID获取组信息
    • update_group：更新组设置（当前受API限制）
    • delete_group：永久删除组

  4. 连接性:

    • check_connection：验证API连接和配置

环境变量

名称 描述 默认值
ZEP_API_KEY Zep云服务的API密钥 无
MCP_HOST 将服务器绑定到的主机 0.0.0.0
MCP_PORT 运行服务器的端口 8080

安装

使用Smithery

npx @smithery/cli install mcp-server-zep-cloud --client claude

使用Claude Desktop手动安装

  1. 克隆此存储库：
git clone https://github.com/yourusername/mcp-server-zep-cloud.git
cd mcp-server-zep-cloud
  1. 安装依赖项：
pip install -r config/requirements.txt
  1. 通过添加配置Claude Desktop claude_desktop_config.json:
{
  "mcpServers": {
    "zep-cloud": {
      "command": "python",
      "args": ["/path/to/mcp-server-zep-cloud/core/run_server.py"],
      "env": {
        "ZEP_API_KEY": "your_api_key_here"
      }
    }
  }
}

配置文件位于：

  • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
  • 窗户： %APPDATA%\Claude\claude_desktop_config.json

使用Docker

Dockerfile可用于构建和运行MCP服务器：

# Build the container
docker build -t mcp-server-zep-cloud .

# Run the container
docker run -p 8080:8080 \
  -e ZEP_API_KEY="your-api-key" \
  mcp-server-zep-cloud

错误处理

服务器使用全面的错误处理系统来提供清晰的反馈：

错误响应格式

所有工具响应都遵循一致的格式：

{
  "status": "ok|error",
  "error": "error description or empty string",
  "data": {...}  // only present when status is "ok"
}

错误类型

不可恢复的错误 （需要用户操作）：

  • "API key not configured" -未设置ZEP_API_KEY环境变量
  • "Invalid API key" -Zep Cloud身份验证失败
  • "Access denied - check account status" -帐户访问问题

可恢复错误 （临时问题）：

  • 网络超时和连接错误
  • 速率限制
  • 服务临时停机

连接状态

使用 check_connection 用于验证API连接的工具：

成功响应：

{"status": "ok", "error": "", "connected": true, "message": "Connected to Zep Cloud API"}

错误响应：

{"status": "error", "error": "API key not configured", "connected": false}

存储库结构

mcp-server-zep-cloud/
├── core/                          # Core MCP server implementation
│   ├── run_server.py             # Main MCP server entry point - this is just a wrapper, not real functionality in here
│   ├── zep_cloud_server.py       # Main ZepMCPServer class with 12 MCP tools
│   └── zep_cloud_client.py       # Zep SDK wrapper (legacy, not used)
│
├── tests/                         # Comprehensive test suite
│   └── test_mcp_e2e.py           # E2E tests for all 12 MCP tools (717 lines)
│
├── scripts/                       # Development and testing utilities
│   ├── run_server.sh             # Server startup with proxy config
│   ├── check_security.sh         # Security validation
│   └── test_*.py                 # Individual API testing scripts
│
├── config/                        # Configuration and dependencies
│   ├── requirements.txt          # Python dependencies
│   └── claude_desktop_config.json.example  # Claude Desktop config template
│
├── context/                       # Session and development context
│   └── *.md                      # Saved development sessions
│
├── venv/                         # Python virtual environment
├── run_tests.sh                  # Test runner with proxy configuration
├── smithery.yaml                 # Smithery package metadata
├── Dockerfile                    # Container deployment
└── .env                         # Environment variables (not in repo)

关键文件说明

核心实施：

  • core/zep_cloud_server.py （293行）-带12个工具的主MCP服务器：
    • 用户管理：创建用户、更新用户、获取用户、删除用户、列表用户
    • 图形操作：add_Graph_data、search_Graph
    • 组管理：创建组、获取组、更新组、删除组
    • 连接：check_connection

测试与开发：

  • tests/test_mcp_e2e.py （717行）-31次E2E测试，通过率93.5%
  • run_tests.sh -Cloudflare旁路的HTTP_PROXY=127.0.0.1:12334的测试运行器
  • scripts/run_server.sh -具有环境隔离功能的开发服务器

配置：

  • .env -ZEP_API_KEY和代理设置（从模板创建）
  • config/requirements.txt -zep云、fastmcp、pytest依赖关系

安全考虑

  • API密钥保护：永远不要将API密钥提交给版本控制
  • 环境变量：对敏感数据使用环境变量
  • 有限制的访问：将服务器限制在受信任的网络

支持其他客户

此MCP服务器旨在与任何兼容MCP的客户端配合使用。它已经过以下测试：

  • 克劳德桌面
  • 克劳德在网络浏览器中

发展

Zep文档位于https://help.getzep.com/，但很多都不正确。缺少参数等。 对于真实的参数，他们建议调查真实的API客户端https://github.com/getzep/zep-python/tree/main/src/zep_cloud.例如，分组方法如下：https://github.com/getzep/zep-python/blob/main/src/zep_cloud/group/client.py等等。

测试运行器

仅通过此脚本运行测试-它包括Cloudflare旁路的必要代理配置。

# Run all tests
./run_tests.sh test_mcp_e2e.py

# Run specific test
./run_tests.sh tests/test_mcp_e2e.py::TestMCPGraphData::test_add_graph_data_text

# Run with verbose output
./run_tests.sh test_mcp_e2e.py -v

测试覆盖率

  • 31次E2E测试 涵盖所有12个MCP工具
  • 通过率93.5% （29/31项测试通过）
  • 已知问题：由于group.update（）的Zep API错误，跳过了2个测试

以开发模式运行

cd scripts
./run_server.sh

项目状态📊

  • 生产就绪：MCP服务器功能齐全，随时可用
  • 测试覆盖率：29/31次测试通过（成功率93.5%）
  • 已知问题：由于带有的Zep API错误，跳过了2个测试 group.update() 返回502
  • 文档：所有12个工具的完整MCP文档

贡献🤝

添加新功能时：

  1. 先写测试（TDD方法）
  2. 实现最少的代码以通过测试
  3. 添加MCP格式文档
  4. 确保所有测试通过

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP