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上创建一个问题。
• 查看故障排除部分。
• 查看控制台输出中的日志。