Document MCP

🚀 MCP文檔索引器

MCP文檔索引器是一個基於Python的MCP（模型上下文協議）服務器，它利用LanceDB向量數據庫和本地大語言模型（LLMs），實現本地文檔的索引和搜索功能。

✨ 主要特性

• 即時文檔監控：自動對配置文件夾中新添加或修改的文檔進行索引。
• 多格式支持：支持處理PDF、Word（docx/doc）、文本、Markdown和RTF等格式的文件。
• 本地大語言模型集成：使用Ollama進行文檔摘要和關鍵詞提取，所有處理都在本地完成，數據不會離開你的計算機。
• 向量搜索：利用LanceDB和句子轉換器實現語義搜索。
• MCP集成：通過模型上下文協議提供搜索和目錄工具。
• 增量索引：僅處理有更改的文件，節省資源。
• 性能優化：設計上在標準筆記本電腦（如M1/M2 MacBook）上也能有不錯的性能表現。

📦 安裝指南

前提條件

1. 安裝 Python 3.9+。
2. 安裝 uv 包管理器：

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

3. 安裝 Ollama（用於本地大語言模型）：

# 安裝Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 拉取一個模型（例如，llama3.2）
ollama pull llama3.2:3b

安裝MCP文檔索引器

# 克隆倉庫
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

# 嵌入模型（句子轉換器）
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桌面版集成

將以下內容添加到Claude桌面版配置文件（~/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中使用索引器：

"Search my documents for information about machine learning"
"Show me all PDFs I've indexed"
"What documents mention Python programming?"
"Get details about /Users/me/Documents/report.pdf"
"Reindex the latest version of my thesis"

架構

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

文件處理流程

1. 文件檢測：Watchdog監控配置的文件夾以檢測文件更改。
2. 文檔解析：從PDF、Word和文本文件中提取文本。
3. 文本分塊：將文檔分割成有重疊的塊，以便更好地檢索。
4. 大語言模型處理：使用Ollama生成摘要並提取關鍵詞。
5. 嵌入生成：使用句子轉換器創建向量嵌入。
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上創建一個問題。
• 查看故障排除部分。
• 查看控制檯輸出中的日誌。