Document MCP

🚀 MCP Document Indexer

このプロジェクトは、PythonベースのMCP（Model Context Protocol）サーバーで、LanceDBベクターデータベースとローカルの大規模言語モデル（LLM）を使用して、ローカルのドキュメントをインデックス化し、検索することができます。

✨ 主な機能

• リアルタイムドキュメント監視：設定されたフォルダ内の新規および変更されたドキュメントを自動的にインデックス化します。
• 複数フォーマット対応：PDF、Word（docx/doc）、テキスト、Markdown、RTFファイルをサポートします。
• ローカルLLM統合：Ollamaを使用してドキュメントの要約とキーワード抽出を行います。データは一切外部に送信されません。
• ベクター検索：LanceDBとsentence transformersを使用した意味検索を行います。
• MCP統合：Model Context Protocolを介して検索とカタログツールを公開します。
• 増分インデックス化：変更されたファイルのみを処理してリソースを節約します。
• パフォーマンス最適化：標準的なラップトップ（例：M1/M2 MacBook）でも適切なパフォーマンスを発揮するように設計されています。

📦 インストール

前提条件

1. Python 3.9以上 がインストールされていること
2. uv パッケージマネージャー:

curl -LsSf https://astral.sh/uv/install.sh | sh

3. Ollama（ローカルLLM用）:

# Ollamaをインストール
curl -fsSL https://ollama.com/install.sh | sh

# モデルを取得（例：llama3.2）
ollama pull llama3.2:3b

MCP Document Indexerのインストール

# リポジトリをクローン
git clone https://github.com/yairwein/mcp-doc-indexer.git
cd mcp-doc-indexer

# uvでインストール
uv sync

# またはパッケージとしてインストール
uv add mcp-doc-indexer

📚 ドキュメント

設定

インデクサーは、環境変数または .env ファイルを使用して設定できます。

# 監視するフォルダ（カンマ区切り）
WATCH_FOLDERS="/Users/me/Documents,/Users/me/Research"

# LanceDBのストレージパス
LANCEDB_PATH="./vector_index"

# 要約用のOllamaモデル
LLM_MODEL="llama3.2:3b"

# テキストチャンク設定
CHUNK_SIZE=1000
CHUNK_OVERLAP=200

# 埋め込みモデル（sentence-transformers）
EMBEDDING_MODEL="all-MiniLM-L6-v2"

# インデックス化するファイルタイプ
FILE_EXTENSIONS=".pdf,.docx,.doc,.txt,.md,.rtf"

# 最大ファイルサイズ（MB）
MAX_FILE_SIZE_MB=100

# Ollama APIのURL
OLLAMA_BASE_URL="http://localhost:11434"

使用方法

スタンドアロンサービスとして実行

# 環境変数を設定
export WATCH_FOLDERS="/path/to/documents"
export LANCEDB_PATH="./my_index"

# インデクサーを実行
uv run python -m src.main

Claude Desktopと統合

Claude Desktopの設定ファイル (~/Library/Application Support/Claude/claude_desktop_config.json) に以下を追加します。

{
  "mcpServers": {
    "doc-indexer": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mcp-doc-indexer",
        "python",
        "-m",
        "src.main"
      ],
      "env": {
        "WATCH_FOLDERS": "/Users/me/Documents,/Users/me/Research",
        "LANCEDB_PATH": "/Users/me/.mcp-doc-index",
        "LLM_MODEL": "llama3.2:3b"
      }
    }
  }
}

MCPツール

インデクサーは、MCPを介して以下のツールを公開します。

search_documents

自然言語クエリを使用してドキュメントを検索します。

• パラメーター:
  • query: 検索クエリテキスト
  • limit: 最大結果数（デフォルト: 10）
  • search_type: "documents" または "chunks"

get_catalog

要約付きですべてのインデックス化されたドキュメントをリストします。

• パラメーター:
  • skip: スキップするドキュメント数（デフォルト: 0）
  • limit: 返す最大ドキュメント数（デフォルト: 100）

get_document_info

特定のドキュメントの詳細情報を取得します。

• パラメーター:
  • file_path: ドキュメントのパス

reindex_document

特定のドキュメントの再インデックス化を強制します。

• パラメーター:
  • file_path: 再インデックス化するドキュメントのパス

get_indexing_stats

現在のインデックス化統計情報を取得します。

Claudeでの使用例

設定後、Claudeでインデクサーを使用できます。

"機械学習に関する情報を私のドキュメントから検索して"
"私がインデックス化したすべてのPDFを表示して"
"Pythonプログラミングを含むドキュメントはどれ？"
"/Users/me/Documents/report.pdfの詳細を取得して"
"私の論文の最新バージョンを再インデックス化して"

🔧 技術詳細

アーキテクチャ

┌─────────────────┐     ┌──────────────┐     ┌─────────────┐
│  File Monitor   │────▶│   Document   │────▶│  Local LLM  │
│   (Watchdog)    │     │    Parser    │     │  (Ollama)   │
└─────────────────┘     └──────────────┘     └─────────────┘
                               │                      │
                               ▼                      ▼
                        ┌──────────────┐     ┌─────────────┐
                        │   LanceDB    │◀────│  Embeddings │
                        │   Storage    │     │  (ST Model) │
                        └──────────────┘     └─────────────┘
                               │
                               ▼
                        ┌──────────────┐
                        │  FastMCP     │
                        │   Server     │
                        └──────────────┘
                               │
                               ▼
                        ┌──────────────┐
                        │    Claude    │
                        │   Desktop    │
                        └──────────────┘

ファイル処理パイプライン

1. ファイル検出：Watchdogが設定されたフォルダの変更を監視します。
2. ドキュメント解析：PDF、Word、テキストファイルからテキストを抽出します。
3. テキストチャンク化：ドキュメントを重複するチャンクに分割して、より良い検索結果を得ます。
4. LLM処理：Ollamaを使用して要約を生成し、キーワードを抽出します。
5. 埋め込み生成：sentence transformersを使用してベクター埋め込みを作成します。
6. ベクターストレージ：LanceDBにドキュメントとチャンクを保存します。
7. MCP公開：MCPを介して検索とカタログツールを利用可能にします。

パフォーマンスに関する考慮事項

• 増分インデックス化：変更されたファイルのみを再処理します。
• 非同期処理：複数のドキュメントを並列に処理します。
• バッチ操作：複数のファイルを効率的にバッチインデックス化します。
• デバウンシング：急速に変更されるファイルの重複処理を防止します。
• サイズ制限：メモリ問題を防ぐために、最大ファイルサイズを設定可能です。

トラブルシューティング

Ollamaが利用できない場合

Ollamaが実行されていないか、モデルが利用できない場合、インデクサーは要約なしで単純なテキスト抽出にフォールバックします。

# Ollamaの状態を確認
ollama list

# 必要なモデルを取得
ollama pull llama3.2:3b

パーミッションの問題

インデクサーが監視フォルダに読み取りアクセスできることを確認します。

chmod -R 755 /path/to/documents

メモリ使用量

大規模なドキュメントコレクションの場合、以下を検討してください。

• CHUNK_SIZE を減らして、より小さなチャンクを作成します。
• MAX_FILE_SIZE_MB を制限して、非常に大きなファイルをスキップします。
• より小さな埋め込みモデルを使用します。

開発

テストの実行

uv run pytest tests/

コードフォーマット

uv run black src/
uv run ruff src/

パッケージのビルド

uv build

📄 ライセンス

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

貢献

貢献は大歓迎です！以下の手順に従ってください。

1. リポジトリをフォークします。
2. 機能ブランチを作成します。
3. 新しい機能に対するテストを追加します。
4. プルリクエストを送信します。

サポート

問題や質問がある場合は、以下を行ってください。

• GitHubでイシューを開きます。
• トラブルシューティングセクションを確認します。
• コンソール出力のログを確認します。