Markdown RAG MCP Server

🧠 OmniDocs RAG

面向人工智能代理的通用高性能RAG知识库

索引本地文件、网站、GitHub repos、npm/PyPI包，然后使用混合AI检索进行搜索。通过您的IDE聊天。

特性 • 建筑 • 快速启动 • 工具 • 常见问题解答

______________________________________________________________________

✨ 特性

🔍 搜索管道

• 混合搜索 --ChromaDB向量+BM25关键字评分通过互易秩融合（RRF，k=60）融合
• 交叉编码器重新排序 — BAAI/bge-reranker-v2-m3 重新筛选手术精度最高的候选者
• 查询扩展 --RU→混合语言文档的EN同义词扩展（例如“создать”）→ “新建帖子”）
• 结果重复数据删除 --删除接近重复的块（>80%相似性阈值）

📁 通用来源摄入

• 40+文件格式 — .md, .py, .js, .ts, .json, .yaml, .html, .csv，以及更多
• 二进制文档 --PDF、DOCX、XLSX、PPTX、Jupyter笔记本（可选软件包）
• 网站 --带有边界控制、robots.txt、sitemap.xml的完全异步BFS爬虫
• GitHub 仓库 -API直接植树
• npm/PyPI包 --元数据+README提取
• ZIP存档 --自动提取和索引
• JS渲染网站 --Docusaurus、GitBook、VitePress的可选编剧支持

⚡ 演出

• GPU加速 --自动检测CUDA（RTX 3080=约11倍加速）
• 增量索引 --MD5文件哈希，仅重新索引更改的文件
• 代码感知分块 --通过AST按类/函数分割Python文件，通过正则表达式按JS/TS分割Python文件
• 头部感知组块 --Markdown拆分为 ##/### 两句话重叠
• BM25持久性 --通过pickle缓存在服务器重启后幸存下来

🛠️ 管理

• 多收藏 --每个项目都有单独的知识库
• 自动分类 --YAML前体→ H1航向→ 文件名回退
• 文件监视器 --文件系统更改时自动重新索引（看门狗，2s去抖动）
• 管理工具 --列表、删除、删除、重新索引——全部通过聊天完成
• 100%本地免费 -没有API密钥，没有Docker，没有月费

______________________________________________________________________

🏗️ 建筑

flowchart TD
    Q(["🔍 User Query"])

    Q --> QE
    subgraph EXPAND["📝 Stage 0 — Query Expansion"]
        QE["RU→EN Synonyms
(up to 3 variations)"]
    end

    QE --> VS
    QE --> BM

    subgraph HYBRID["⚡ Stage 1 — Hybrid Retrieval"]
        VS["🧠 Vector Search
(ChromaDB + bge-m3)"]
        BM["📝 Keyword Search
(BM25 Okapi)"]
    end

    VS --> RRF
    BM --> RRF

    subgraph FUSION["🔀 Stage 2 — Fusion"]
        RRF["Reciprocal Rank Fusion
(k=60)"]
    end

    RRF --> CE

    subgraph RERANK["🎯 Stage 3 — Reranking"]
        CE["Cross-Encoder
bge-reranker-v2-m3"]
    end

    CE --> DD

    subgraph DEDUP["🧹 Stage 4 — Dedup"]
        DD["Remove >80%
similar results"]
    end

    DD --> OUT

    subgraph OUTPUT["📋 Stage 5 — Result"]
        OUT["Top-N Documents
with Breadcrumbs"]
    end

    style Q fill:#6366f1,color:#fff,stroke:#4338ca
    style EXPAND fill:#0f172a,color:#e2e8f0,stroke:#334155
    style HYBRID fill:#0f172a,color:#e2e8f0,stroke:#334155
    style FUSION fill:#0f172a,color:#e2e8f0,stroke:#334155
    style RERANK fill:#0f172a,color:#e2e8f0,stroke:#334155
    style DEDUP fill:#0f172a,color:#e2e8f0,stroke:#334155
    style OUTPUT fill:#0f172a,color:#e2e8f0,stroke:#334155
    style QE fill:#581c87,color:#e9d5ff,stroke:#9333ea
    style VS fill:#1e40af,color:#bfdbfe,stroke:#3b82f6
    style BM fill:#065f46,color:#a7f3d0,stroke:#10b981
    style RRF fill:#7c3aed,color:#ede9fe,stroke:#8b5cf6
    style CE fill:#b45309,color:#fef3c7,stroke:#f59e0b
    style DD fill:#0e7490,color:#cffafe,stroke:#06b6d4
    style OUT fill:#1e3a5f,color:#bae6fd,stroke:#38bdf8

运作原理

1. 查询扩展 --使用RU生成最多3个查询变体→EN编程同义词
2. 混合检索 --语义搜索(bge-m3，8192个令牌）和精确关键字（BM25）同时使用
3. Reciprocal Rank Fusion：RRF（相互排名融合） --数学上结合了两个引擎的排名
4. 交叉编码器重新排序 — bge-reranker-v2-m3 深入计算顶级候选人的相关性
5. 去重 --删除几乎相同的结果
6. 结构化输出 --返回的结果带有面包屑（例如。， README.md > Quickstart > Installation)

______________________________________________________________________

🚀 快速启动

1.先决条件

• Python 3.10+（在3.13上测试）
• git

2.安装

git clone https://github.com/ElvinBayramov/OmniDocs-RAG.git
cd OmniDocs-RAG
python install.py

安装程序下载AI模型（bge-m3+bge reranker约2.2GB），安装依赖项，并自动配置IDE。

⚠️ 启用GPU加速（对速度至关重要）： 默认情况下， pip 可以在Windows上安装仅CPU版本的PyTorch。要解锁您的NVIDIA GPU，请运行： ``bash pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124 --upgrade --force-reinstall ``

3.配置（如果手动）

添加到IDE的MCP配置中(mcp_config.json):

{
  "mcpServers": {
    "markdown-rag": {
      "command": "python",
      "args": ["C:\\path\\to\\OmniDocs-RAG\\server.py"],
      "env": {
        "RAG_DOCS_PATH": "C:\\path\\to\\your\\docs",
        "RAG_DEVICE": "cuda"
      }
    }
  }
}

4.使用

只需与您的AI助手交谈：

> Index my project docs
> Search: how does authentication work?
> Index the FastAPI documentation from https://fastapi.tiangolo.com
> Add the langchain repo: github://langchain-ai/langchain/docs

AI自动调用MCP工具——没有UI，没有按钮，只是聊天。

______________________________________________________________________

🛠️ MCP工具

index_url() --通用来源摄入

# Websites (async BFS crawler)
index_url("https://docs.python.org/3/library/asyncio.html")

# GitHub repositories
index_url("github://tiangolo/fastapi/docs")

# npm packages
index_url("npm://axios@1.6")

# PyPI packages
index_url("pypi://fastapi")

# ZIP archives
index_url("file:///path/to/docs.zip")

______________________________________________________________________

⚙️ 配置

通过环境变量进行的所有设置：

______________________________________________________________________

📁 支持格式

文本（无额外deps）： .md .txt .rst .log .html .htm

代码（用markdown包装）： .py .js .ts .jsx .tsx .css .java .go .rs .c .cpp .rb .php .swift .kt .lua .sh

配置： .json .yaml .yml .toml .xml .csv .ini .cfg

二进制（可选包）：

______________________________________________________________________

🏷️ 自动分类

每个文件都会自动获得一个类别（不需要手动标记）：

______________________________________________________________________

❓ 常见问题解答

Q： 这会把我的数据发送到任何地方吗？ A： 不，100%本地。模特从HuggingFace下载一次，然后一切都离线运行。没有API密钥，没有云。

Q： 我需要GPU吗？ A： 没有，但它有帮助。CPU在搜索时工作良好（~200ms）。GPU（CUDA）将索引速度提高了约11倍。集 RAG_DEVICE=cuda.

Q： 如何更新索引？ A： 服务器使用增量索引——只有更改的文件才会被重新索引。只需拨打电话 index_documents() 再次，或使用以下命令启用文件监视器 RAG_WATCH_PATH.

Q： 为什么第一次搜索很慢？ A： 交叉编码器（~1.1GB）在第一次查询时延迟加载。所有后续搜索都是即时的。

Q： 它支持我的语言吗？ A： 是的。 bge-m3 支持100多种语言，包括英语、俄语、中文、日语、西班牙语等。跨语言搜索也适用（俄语查询，英语查找结果）。

Q： 我可以为每个项目设置单独的知识库吗？ A： 是的。使用 collection 参数： index_documents(path, collection="my-project")那么 search_docs(query, collection="my-project").

______________________________________________________________________

📄 许可证

根据 Apache许可证2.0。参见 许可证 了解详情。