Memvid MCP Server

🚀 Memvid MCP 服务器 🎥

Memvid MCP 服务器是一个模型上下文协议（MCP）服务器，它向 AI 客户端开放 Memvid 视频内存功能。该服务器允许你将文本、PDF 等内容编码为视频内存格式，以实现高效的语义搜索和聊天交互。

✨ 主要特性

• 文本编码：将文本块或完整文本文档添加到视频内存中
• PDF 处理：从 PDF 文件中提取并编码内容
• 视频内存构建：生成数据的压缩视频表示
• 语义搜索：使用自然语言查询已编码的数据
• 聊天界面：与已编码的知识库进行对话
• 多连接支持：处理多个并发客户端连接
• 全面日志记录：详细记录到标准错误输出（stderr）以进行调试
• 优雅关闭：正确清理资源并处理信号

📦 安装指南

1. 搭建环境

cd /memvid_mcp_server
uv venv --python 3.12 --seed
source .venv/bin/activate

2. 安装依赖项

uv add -e .

使用 Docker 进行 H.265 编码

服务器会自动管理 Docker 的安装和生命周期：

1. 自动设置 Docker：如果未安装 Docker，服务器将自动安装。
2. 容器管理：memvid 包会自行处理 Docker 容器的构建和管理。
3. 生命周期管理：MCP 服务器启动时会启动 Docker 守护进程。

安装在虚拟环境中的 memvid 包包含所有必要的 Docker 配置，并将自动执行以下操作：

• 在需要时构建 memvid-h265 容器。
• 当指定 codec='h265' 时，使用 Docker 进行 H.265 编码。
• 在内部处理所有容器的生命周期。

无需手动设置 Docker 或指定外部仓库路径。使用位于 docker/ 目录中的 Dockerfile 构建 memvid-h265。

一旦 Docker 镜像构建完成，当在 build_video 中指定 video_codec='h265' 时，memvid 将自动检测并使用它。

3. 测试服务器（可选）

uv run python memvid_mcp_server/main.py

⚙️ 配置

Claude Desktop 设置

1. 复制示例配置：

cp example_mcp_config.json ~/.config/claude-desktop/config.json

2. 或者手动添加到你的 Claude Desktop 配置中：

{
  "mcpServers": {
    "memvid-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/ty/Repositories/memvid_mcp_server",
        "run",
        "python",
        "memvid_mcp_server/main.py"
      ],
      "env": {
        "PYTHONPATH": "/home/ty/Repositories/memvid_mcp_server",
        "PYTHONWARNINGS": "ignore"
      }
    }
  }
}

3. 重启 Claude Desktop 以加载服务器。

💻 使用示例

基础用法

以下是一个简单的使用流程示例：

# 添加文本
uv run python -c "from memvid_mcp_server import add_text; add_text('这是一段测试文本')"

# 构建视频
uv run python -c "from memvid_mcp_server import build_video; build_video('output_video.mp4', 'output_index.idx')"

# 搜索内存
uv run python -c "from memvid_mcp_server import search_memory; print(search_memory('测试文本'))"

高级用法

# 使用 H.265 编码构建视频
uv run python -c "from memvid_mcp_server import build_video; build_video('output_video_h265.mp4', 'output_index_h265.idx', codec='h265')"

# 与知识库进行聊天
uv run python -c "from memvid_mcp_server import chat_with_memvid; print(chat_with_memvid('关于测试文本的信息'))"

📚 详细文档

可用工具

• get_server_status：检查 memvid 服务器的当前状态，包括版本信息。
• add_chunks：将文本块列表添加到编码器。
  • chunks：要添加的文本字符串列表。
• add_text：将单个文本文档添加到编码器。
  • text：要添加的文本内容。
  • metadata：可选的元数据字典。
• add_pdf：处理 PDF 文件并将其添加到编码器。
  • pdf_path：PDF 文件的路径。
• build_video：根据所有添加的内容构建视频内存。
  • video_path：视频文件的输出路径。
  • index_path：索引文件的输出路径。
  • codec：要使用的视频编解码器（'h265' 或 'h264'，默认：'h265'）。
  • show_progress：构建过程中是否显示进度（默认：True）。
  • auto_build_docker：是否在需要时自动构建 Docker（默认：True）。
  • allow_fallback：是否允许回退选项（默认：True）。
• search_memory：对已构建的视频内存进行语义搜索。
  • query：自然语言搜索查询。
  • top_k：返回的结果数量（默认：5）。
• chat_with_memvid：与已编码的知识库进行对话。
  • message：要发送到聊天系统的消息。

使用工作流程

1. 添加内容：使用 add_text、add_chunks 或 add_pdf 添加数据。
2. 构建视频：使用 build_video 创建视频内存表示。
3. 搜索或聊天：使用 search_memory 进行查询或 chat_with_memvid 进行对话。

🔧 技术细节

开发

测试

# 安装开发依赖项
uv add --dev pytest pytest-asyncio black ruff mypy

# 运行测试
uv run pytest

# 格式化代码
uv run black memvid_mcp_server/
uv run ruff check memvid_mcp_server/

调试

• 检查 Claude Desktop 中的日志：~/Library/Logs/Claude/mcp*.log（macOS）或等效位置。
• 通过在环境中设置 LOG_LEVEL=DEBUG 启用调试日志记录。
• 使用 get_server_status 工具检查服务器状态。

故障排除

常见问题

1. JSON 解析错误：所有输出都已正确重定向到标准错误输出，以防止协议干扰。
2. 导入错误：服务器会优雅地处理缺少 memvid 包的情况，并显示清晰的错误消息。
3. 连接问题：检查 Claude Desktop 日志并使用 get_server_status 诊断问题。
4. 视频构建失败：确保有足够的磁盘空间和有效的路径。

日志配置

服务器实现了全面的标准输出重定向，以防止任何库输出干扰 MCP JSON-RPC 协议：

• 所有 memvid 操作都使用标准输出重定向进行包装。
• 捕获进度条、警告和模型加载消息。
• 仅将结构化的 JSON 响应发送到 Claude Desktop。
• 所有诊断信息都记录到标准错误输出。

错误消息

• "Memvid not available"：安装 memvid 包：uv add memvid。
• "Video memory not built"：在搜索或聊天之前运行 build_video。
• "LLM not available"：预期警告 - memvid 在没有外部大语言模型（LLM）提供商的情况下仍可工作。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

🤝 贡献

1. 分叉（Fork）仓库。
2. 创建功能分支。
3. 进行更改。
4. 如有必要，添加测试。
5. 提交拉取请求（Pull Request）。

📚 相关项目

• Memvid - 底层视频内存技术。
• Model Context Protocol - 协议规范。
• Claude Desktop - 兼容 MCP 的 AI 客户端。

本 README 经过优化，以提高生产可靠性并遵循 MCP 最佳实践。