文档索引MCP
这是干什么用的？
文档的本地第一语义搜索服务器。索引PDF、Word文档、PowerPoint、Excel文件和文本/标记，然后通过模型上下文协议（MCP）使用自然语言进行搜索。
- 语义搜索 -使用自然语言查询查找相关内容
- 边界感知分块 -尊重文档结构（章节、节、标题）
- 表格提取 -将文档中的表格提取为CSV格式
- 完全本地化 -没有外部API，没有云服务，没有Docker容器，没有PyTorch
- 轻量级 -基于ONNX的嵌入（约50MB，而PyTorch约2GB）
快速开始
1.添加到MCP配置中
需要 紫外线.如果你没有紫外线，请参阅 替代安装 在......下面
添加 .mcp.json 在项目根目录（适用于Claude Code）或Claude Desktop配置中：
{
"mcpServers": {
"doc-index": {
"command": "uvx",
"args": ["doc-index-mcp"]
}
}
}2.安装克劳德技能（可选）
该技能教克劳德如何有效地使用搜索工具（令牌预算、边界扩展等）：
uvx --from doc-index-mcp doc-index-install-skill就是这样——开始让克劳德索引和搜索你的文档。
支持格式
| 格式 | 扩展名 | 注释 |
|---|---|---|
| 文本 | .txt | 纯文本 |
| Markdown | .md, .markdown | 保留边界标题 |
.pdf | 使用页面标记提取文本 | |
| Word | .docx | 段落、标题、表格 |
| PowerPoint | .pptx | 幻灯片、笔记、表格 |
| Excel | .xlsx, .xls | 图纸作为表格 |
为什么没有外部服务？
| 组件 | 传统RAG | 此服务器 |
|---|---|---|
| 嵌入 | OpenAI API/托管模型 | 本地ONNX模型（fastembed） |
| 矢量数据库 | 松果体/编织体/Qdrant | 本地文件（usearch） |
| 存储 | 云/托管数据库 | 本地 .docindex/ 目录 |
| 依赖关系 | PyTorch（~2GB） | ONNX运行时（~50MB） |
工具
doc_index
为文档建立索引以进行语义搜索。
{
"file_path": "docs/manual.pdf",
"source_name": "manual"
}doc_search
使用自然语言搜索索引文档。
{
"query": "how to configure authentication",
"top_k": 5,
"expand_to_boundary": "section",
"max_return_tokens": 4096
}参数：
query-搜索查询sources-筛选特定来源（可选）top_k-结果数（默认值：5）expand_to_boundary-将结果展开到完整的“章节”、“部分”、“小节”或“页面”max_return_tokens-结果令牌预算（默认值：4096）include_siblings-展开时包含兄弟部分
doc_list
列出所有索引源。
doc_chunk
通过ID和可选邻居检索特定块。
{
"chunk_id": "manual:42",
"neighbors": 2
}doc_toc
获取索引文档的目录（章节、小节、小节）。在检索特定内容之前，使用此功能了解文档结构。
{
"source_name": "manual",
"max_depth": 3
}doc_get_content
按结构位置检索文档内容。只提供一个定位器： boundary_id, chapter, section，或 pages.
{
"source_name": "manual",
"chapter": "3",
"max_return_tokens": 8192
}read_document
无需索引即可阅读文档。返回格式化文本。
{
"file_path": "report.pdf",
"max_chars": 100000
}list_tables
列出文档中的所有表。
{
"file_path": "data.xlsx"
}extract_table
将特定表提取为CSV。
{
"file_path": "data.xlsx",
"table_index": 0,
"max_rows": 100
}环境变量
| 变量 | 描述 | 默认值 |
|---|---|---|
MCP_WORKING_DIR | 解析文件路径的基本目录 | 当前工作目录 |
DOC_INDEX_DIR | 用于存储矢量索引的目录 | .docindex 在工作目录中 |
替代安装
使用pip进行全局安装
pip install doc-index-mcp然后在你的 .mcp.json:
{
"mcpServers": {
"doc-index": {
"command": "doc-index-mcp"
}
}
}从源码安装
克隆仓库并安装依赖项：
git clone https://github.com/mike-anderson/doc-index-mcp.git
cd doc-index-mcp
pip install -e .然后指出你的 .mcp.json 在服务器入口点：
{
"mcpServers": {
"doc-index": {
"command": "python",
"args": ["/path/to/doc-index-mcp/src/server.py"]
}
}
}建筑
一切都在本地运行，不需要外部API、数据库或嵌入式服务器。
flowchart TB
subgraph Client["MCP Client (Claude Desktop, etc.)"]
LLM[LLM]
end
subgraph MCP["Doc Index MCP Server"]
Server[server.py]
subgraph Services["Local Services"]
Loader[Document Loader
PDF, DOCX, PPTX, XLSX]
Chunker[Boundary-Aware
Chunker]
Embedder[Embedder
ONNX Runtime]
VectorStore[Vector Store
usearch]
end
end
subgraph Storage["Local Filesystem"]
Docs[(Source
Documents)]
Index[(".docindex/
├── manifest.json
└── vectors/
├── index.usearch
├── chunks.jsonl
└── boundaries.json")]
end
subgraph Models["Embedded Model (downloaded once)"]
ONNX[BAAI/bge-small-en-v1.5
ONNX format ~50MB]
end
LLM |MCP Protocol| Server
Server --> Loader
Server --> Chunker
Server --> Embedder
Server --> VectorStore
Loader -->|read| Docs
VectorStore |read/write| Index
Embedder -->|load once| ONNX
style Client fill:#e1f5fe
style Storage fill:#fff3e0
style Models fill:#f3e5f5
style MCP fill:#e8f5e9数据流
flowchart LR
subgraph Index["Indexing"]
direction TB
A[Document] --> B[Load & Extract Text]
B --> C[Detect Boundaries]
C --> D[Chunk ~256 tokens]
D --> E[Generate Embeddings]
E --> F[Save to Disk]
end
subgraph Search["Searching"]
direction TB
G[Query] --> H[Embed Query]
H --> I[Vector Similarity Search]
I --> J[Expand to Boundaries]
J --> K[Return Results]
end
Index -.->|stored in .docindex/| Search许可证
麻省理工学院