Markdown语义搜索引擎

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<br/>(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）。

验证

python3 -m py_compile server.py utils.py reindex.py chunking.py
python3 -m build

发布工作流程基于以下内容构建 uv build 并通过PyPI可信发布在GitHub上发布。准备好的CI工作流还在未来的推送之前验证包元数据、文档资产和核心Python语法。

特性

• 语义匹配 --查找概念上相关的内容，而不仅仅是关键字点击
• 多提供商嵌入 --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 用于使用实时进度日志进行大规模索引

📚 文档

工具

运作原理

flowchart LR
    A["📁 Markdown Files"] -->|"walk + filter"| B["🔍 Delta Scan<br/>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

配置

核心

索引

小贴士：默认值适用于大多数Vault。调整 MIN_CHUNK_TOKENS / MIN_FINAL_TOKENS 如果短音符意外掉落。更改需要重新索引(reindex.py --force).

看 嵌入提供者 获取完整身份验证和调优选项。

安全与隐私

• 从环境变量中读取API密钥；永远不要提交带有文字秘密的提供者密钥或主机MCP配置。
• MARKDOWN_WORKSPACE 可以锁定索引和搜索到已批准的根。
• scope_path 当将搜索暴露给多个代理时，应该使用此选项，这样一个项目就不能静默地查询另一个项目的注释。
• 生成的矢量存储和跟踪数据库可以显示文件路径和注释主题；对待 .db/ Milvus作为私人数据导出。
• clear_index 具有破坏性，应保留用于明确的维护，而不是常规搜索。

演出

许可证

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工具的虚拟参数）