微信扫一扫article
README
🚀 MCP文档索引器
MCP文档索引器是一个基于Python的MCP（模型上下文协议）服务器，它利用LanceDB向量数据库和本地大语言模型（LLMs），实现本地文档的索引和搜索功能。
✨ 主要特性
- 实时文档监控：自动对配置文件夹中新添加或修改的文档进行索引。
- 多格式支持：支持处理PDF、Word（docx/doc）、文本、Markdown和RTF等格式的文件。
- 本地大语言模型集成：使用Ollama进行文档摘要和关键词提取，所有处理都在本地完成，数据不会离开你的计算机。
- 向量搜索：利用LanceDB和句子转换器实现语义搜索。
- MCP集成：通过模型上下文协议提供搜索和目录工具。
- 增量索引：仅处理有更改的文件，节省资源。
- 性能优化：设计上在标准笔记本电脑（如M1/M2 MacBook）上也能有不错的性能表现。
📦 安装指南
前提条件
- 安装 Python 3.9+。
- 安装 uv 包管理器：
curl -LsSf https://astral.sh/uv/install.sh | sh
- 安装 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 │
└──────────────┘
文件处理流程
- 文件检测：Watchdog监控配置的文件夹以检测文件更改。
- 文档解析：从PDF、Word和文本文件中提取文本。
- 文本分块：将文档分割成有重叠的块，以便更好地检索。
- 大语言模型处理：使用Ollama生成摘要并提取关键词。
- 嵌入生成：使用句子转换器创建向量嵌入。
- 向量存储：将文档和块存储在LanceDB中。
- 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 文件。
🤝 贡献
欢迎贡献代码！请按照以下步骤操作：
- 分叉仓库。
- 创建功能分支。
- 为新功能添加测试。
- 提交拉取请求。
💬 支持
如果遇到问题或有疑问：
- 在GitHub上创建一个问题。
- 查看故障排除部分。
- 查看控制台输出中的日志。