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 最佳實踐。