🚀 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 的安装和生命周期：
- 自动设置 Docker：如果未安装 Docker，服务器将自动安装。
- 容器管理：memvid 包会自行处理 Docker 容器的构建和管理。
- 生命周期管理：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 设置
- 复制示例配置：
cp example_mcp_config.json ~/.config/claude-desktop/config.json
- 或者手动添加到你的 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"
}
}
}
}
- 重启 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：要发送到聊天系统的消息。
使用工作流程
- 添加内容：使用
add_text、add_chunks或add_pdf添加数据。 - 构建视频：使用
build_video创建视频内存表示。 - 搜索或聊天：使用
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工具检查服务器状态。
故障排除
常见问题
- JSON 解析错误：所有输出都已正确重定向到标准错误输出，以防止协议干扰。
- 导入错误：服务器会优雅地处理缺少 memvid 包的情况，并显示清晰的错误消息。
- 连接问题：检查 Claude Desktop 日志并使用
get_server_status诊断问题。 - 视频构建失败：确保有足够的磁盘空间和有效的路径。
日志配置
服务器实现了全面的标准输出重定向，以防止任何库输出干扰 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 文件。
🤝 贡献
- 分叉（Fork）仓库。
- 创建功能分支。
- 进行更改。
- 如有必要，添加测试。
- 提交拉取请求（Pull Request）。
📚 相关项目
- Memvid - 底层视频内存技术。
- Model Context Protocol - 协议规范。
- Claude Desktop - 兼容 MCP 的 AI 客户端。
本 README 经过优化，以提高生产可靠性并遵循 MCP 最佳实践。