Memvid MCP Server 🎥

这是一个模型上下文协议（MCP）服务器，它将Memvid视频内存功能暴露给AI客户端。此服务器允许您将文本、PDF和其他内容编码成视频内存格式，以便进行高效的语义搜索和聊天交互。

🌟 特性

• 文本编码：向视频内存添加文本片段或全文档
• PDF处理：从PDF文件中提取并编码内容
• 视频内存构建：生成数据的压缩视频表示形式
• 语义搜索：使用自然语言查询已编码的数据
• 聊天界面：与已编码的知识库进行对话
• 多连接支持：处理多个并发客户端连接
• 详细日志记录：通过stderr进行详细的调试日志记录
• 优雅关闭：适当的资源清理和信号处理

📋 要求

• Python 3.10 或更高版本
• uv 包管理器
• memvid 包
• 兼容MCP的客户端（例如，Claude Desktop）

🚀 安装

1. 设置环境

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

2. 安装依赖项

uv add -e .

H.265 编码与Docker

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

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

memvid包（安装在虚拟环境中）包含所有必要的Docker配置，并会自动：

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

无需手动设置Docker或外部仓库路径。

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以加载服务器。

🛠️ 可用工具

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解析错误：所有输出都正确重定向到stderr，以防止干扰协议
2. 导入错误：服务器优雅地处理缺失的memvid包，并提供清晰的错误消息
3. 连接问题：检查Claude Desktop日志并使用get_server_status诊断问题
4. 视频构建失败：确保有足够的磁盘空间和有效的路径

日志配置

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

• 所有memvid操作都被包装在stdout重定向中
• 进度条、警告和模型加载消息被捕获
• 只有结构化的JSON响应被发送到Claude Desktop
• 所有的诊断信息都被记录到stderr

错误消息

• "Memvid不可用"：安装memvid包：uv add memvid
• "视频内存未构建"：在搜索或聊天之前运行build_video
• "LLM不可用"：预期警告——memvid可以在没有外部LLM提供商的情况下工作

📄 许可证

MIT许可证 - 查看LICENSE文件获取详情。

🤝 贡献

1. 分叉仓库
2. 创建一个特性分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

📚 相关项目

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

---

生成改进版，提高生产可靠性并遵循MCP最佳实践。