Memvid MCP Server

🚀 Memvid MCP Server 🎥

Memvidのビデオメモリ機能をAIクライアントに公開するModel Context Protocol (MCP)サーバーです。このサーバーを使用すると、テキスト、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デーモンが起動します。

venvにインストールされたmemvidパッケージには、必要なすべてのDocker構成が含まれており、自動的に以下のことを行います。

• 必要に応じてmemvid-h265コンテナを構築する
• codec='h265'が指定された場合、H.265エンコーディングにDockerを使用する
• すべてのコンテナのライフサイクルを内部で処理する

手動での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を再起動してサーバーを読み込む。

💻 使用例

基本的な使用法

このサーバーの基本的な使用手順は以下の通りです。

利用可能なツール

get_server_status

メンビッドサーバーの現在の状態を確認します。バージョン情報も含まれます。

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. ビデオ構築失敗：十分なディスクスペースと有効なパスがあることを確認します。

ログ設定

サーバーは、MCP JSON-RPCプロトコルへの干渉を防ぐために、包括的なstdoutリダイレクトを実装しています。

• すべてのmemvid操作はstdoutリダイレクトでラップされています。
• 進捗バー、警告、およびモデルの読み込みメッセージがキャプチャされます。
• 構造化されたJSON応答のみがClaude Desktopに送信されます。
• すべての診断情報はstderrにログに記録されます。

エラーメッセージ

• "Memvid not available"：memvidパッケージをインストールしてください：uv add memvid
• "Video memory not built"：検索またはチャットする前にbuild_videoを実行してください。
• "LLM not available"：予期される警告です - memvidは外部のLLMプロバイダーなしでも機能します。

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

🤝 コントリビューション

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. 変更を加える
4. 適用可能な場合はテストを追加する
5. プルリクエストを送信する

📚 関連プロジェクト

• Memvid - 基礎となるビデオメモリ技術
• Model Context Protocol - プロトコル仕様
• Claude Desktop - MCP互換のAIクライアント

本READMEは、本番環境の信頼性とMCPのベストプラクティスを考慮して改善されています。