Markdown FastRAG MCP
](https://pypi.org/project/markdown-fastrag-mcp/) ](https://pypi.org/project/markdown-fastrag-mcp/)   
一个用于markdown文档的语义搜索引擎。MCP服务器 无阻塞背景索引, 多提供者嵌入 （Gemini、OpenAI、Vertex AI、Voyage），以及 Milvus/Zilliz云 矢量存储——专为 多代理并发访问.
这个项目是 Zackriya解决方案/MCP Markdown RAG，大量扩展用于生产多代理使用。原始项目在Apache 2.0下获得许可。
问 *“微服务的权衡是什么？”* 找到关于服务边界、分布式系统和API设计的笔记，即使它们都没有提到“微服务”
graph LR
A["Claude Code"] --> M["Milvus Standalone
(Docker)"]
B["Codex"] --> M
C["Copilot"] --> M
D["Antigravity"] --> M
M --> V["Shared Document Index"]快速开始
pip install markdown-fastrag-mcp添加到MCP主机配置中：
{
"mcpServers": {
"markdown-rag": {
"command": "uvx",
"args": ["markdown-fastrag-mcp"],
"env": {
"EMBEDDING_PROVIDER": "gemini",
"GEMINI_API_KEY": "${GEMINI_API_KEY}",
"MILVUS_ADDRESS": "http://localhost:19530"
}
}
}
}小贴士：省略 MILVUS_ADDRESS 仅供本地使用（默认为基于SQLite的Milvus Lite）。特性
- 语义匹配 --查找概念上相关的内容，而不仅仅是关键字点击
- 多提供商嵌入 --Gemini、OpenAI、Vertex AI、Voyage或本地模型
- 异步背景索引 --无阻塞
index_documents立即返回job_id；投票get_index_status - 事件循环安全线程 --所有同步I/O都通过以下方式在工作线程中运行
asyncio.to_thread - 智能增量索引 --mtime/size快速路径跳过未更改的文件而不读取它们
- 三向三角扫描 --一次性将文件分类为新建/修改/删除；新文件跳过Milvus删除
- 智能块合并 --下面的小块
MIN_CHUNK_TOKENS与兄弟姐妹合并；注入父标头上下文 - 空块过滤 --仅前体和仅结构块（没有散文的标题/分隔符）在索引时被丢弃，在搜索时被过滤
- 短大块掉落 --下面的最后一块
MIN_FINAL_TOKENS（默认值为150）随每个块的stderr日志记录一起删除 - 和解扫荡 --每次索引运行后，查询所有Milvus路径并删除源文件不再存在于磁盘上的孤立向量
- 搜索已删除 --每个文件的结果限制可防止单个文档主导结果
- 范围搜索和修剪 —
scope_path将结果过滤到子目录；修剪永远不会擦除无关的数据 - 批量嵌入和插入 --并发批处理，重试429次，分块Milvus插入低于gRPC 64MB限制
- Shell重新索引CLI —
reindex.py用于使用实时进度日志进行大规模索引
📚 文档
| 文档 | 描述 |
|---|---|
| 嵌入提供者 | 所有6个提供程序：设置、身份验证、调优、速率限制 |
| Milvus/Zilliz设置 | Lite vs Standalone vs Zilliz Cloud，Docker Compose，故障排除 |
| 索引架构 | 无阻塞流动， to_thread，三向三角洲，和解扫掠 |
| 优化 | 块合并、头注入、批量插入、搜索数据删除 |
工具
| 工具 | 说明 |
|---|---|
index_documents | 启动后台索引作业，返回 job_id 立即 |
get_index_status | 轮询作业状态(running / succeeded / failed) |
search_documents | 具有相关性得分和文件路径的语义搜索 |
clear_index | 重置矢量数据库和跟踪状态 |
运作原理
flowchart LR
A["📁 Markdown Files"] -->|"walk + filter"| B["🔍 Delta Scan
mtime/size"]
B -->|changed| C["✂️ Chunk + Merge"]
B -->|unchanged| SKIP["⏭️ Skip"]
B -->|deleted| PRUNE["🗑️ Prune"]
C --> D["🧠 Embed"]
D -->|"batch insert"| E["💾 Milvus"]
F["🔎 Query"] --> D
D -->|"k×5"| G["📊 Dedup + Top-K"]
style A fill:#2d3748,color:#e2e8f0
style D fill:#553c9a,color:#e9d8fd
style E fill:#2a4365,color:#bee3f8
style G fill:#22543d,color:#c6f6d5
style PRUNE fill:#742a2a,color:#fed7d7配置
核心
| 变量 | 默认值 | 描述 |
|---|---|---|
EMBEDDING_PROVIDER | local | gemini, openai, openai-compatible, vertex, voyage |
EMBEDDING_DIM | 768 | 矢量维度 |
MILVUS_ADDRESS | .db/milvus_markdown.db | Milvus地址或本地文件路径 |
MARKDOWN_WORKSPACE | -- | 锁定工作区根目录 |
索引
| 变量 | 默认值 | 描述 |
|---|---|---|
MARKDOWN_CHUNK_SIZE | 2048 | 令牌块大小 |
MARKDOWN_CHUNK_OVERLAP | 100 | 块之间的令牌重叠 |
MIN_CHUNK_TOKENS | 300 | 小块合并阈值 |
MIN_FINAL_TOKENS | 150 | 将最后的区块降至此令牌计数以下 |
DEDUP_MAX_PER_FILE | 1 | 每个文件的最大结果(0 关 |
EMBEDDING_BATCH_SIZE | 250 | 每个API调用的文本 |
EMBEDDING_CONCURRENT_BATCHES | 4 | 平行批次 |
EMBEDDING_BATCH_DELAY_MS | 0 | 批处理波之间的延迟（ms） |
MILVUS_INSERT_BATCH | 5000 | 每次Milvus插入的行数（gRPC 64MB限制） |
小贴士：默认值适用于大多数Vault。调整MIN_CHUNK_TOKENS/MIN_FINAL_TOKENS如果短音符意外掉落。更改需要重新索引(reindex.py --force). 看 嵌入提供者 获取完整身份验证和调优选项。
演出
| 度量 | 结果 |
|---|---|
| 未更改的文件--哈希计算 | 0 （时间/大小快速路径） |
| 已更改文件--嵌入+插入 | 约3秒 |
| 无更改--完全扫描 | 瞬间 |
| 完全重新索引（1300个文件，23K块） | ~7-8分钟 |
许可证
Apache 2.0——请参阅 许可证 全文。
这个项目是 MCP Markdown RAG 由Zackriya Solutions提供。原始项目在Apache 2.0下获得许可；此分叉保持相同的许可证。
上游的主要新增内容:
- 多提供商嵌入（Gemini、Vertex AI、OpenAI、Voyage）
- Milvus矢量存储取代Qdrant
- 无阻塞背景索引
asyncio.to_thread - 三向增量扫描（新增/修改/删除）
- 智能块合并与父头注入
- 空块过滤（仅前体/仅结构删除）
- 短块删除（最终块低于150个令牌，每个块记录）
- 和解扫荡（Milvus↔磁盘重影矢量清理）
- 范围搜索和修剪、批量嵌入、shell CLI
- VS代码副本MCP兼容性（零所需arg工具的虚拟参数）