Which integrations are available for this server?

Enables GitHub Copilot to search and retrieve information from private knowledge bases.

How do I use Modular RAG MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Modular RAG MCP Server search my knowledge base for RAG best practices" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Modular RAG MCP Server

by XBW-Leo

Overview Schema Source Related Servers Discussions Admin

Python

Local

模块化企业知识检索与 Agent RAG 系统（Modular RAG MCP Server）

可插拔、可观测的模块化 RAG（Retrieval-Augmented Generation）系统。通过 MCP（Model Context Protocol）协议对外暴露标准工具接口，支持 GitHub Copilot、Claude Desktop、Claude Code 等 AI 助手与 Agent 直接调用私有知识库，实现"知识检索 → 精准召回 → 生成回答"的完整闭环。

项目背景

企业知识库场景中的典型痛点：

文档分散：知识散落在 Wiki、PDF、内部系统中，缺少统一的检索入口
语义缺失：传统关键词搜索无法理解近义表达，如"反洗钱"与"AML"
接入困难：AI 应用难以安全、标准地接入私有知识

本项目将 RAG 链路的完整环节——检索（Hybrid Search + Rerank）、多模态视觉处理（Image Captioning）、评估（Ragas + Custom）、生成（LLM Response）——与 MCP（Model Context Protocol） 串接为一个可运行的工程系统，作为 Agent / AI 助手的知识底座。

核心特性

🔌 全链路可插拔架构

LLM / Embedding / Reranker / Splitter / VectorStore / Evaluator 均定义抽象接口，基于工厂模式 + 配置文件一键切换后端（OpenAI / Azure / DeepSeek / Ollama），零代码修改即可适配不同环境。

🔍 混合检索 + 重排

BM25 稀疏检索（内置 jieba 中文分词）解决专有名词精确匹配，Dense Embedding 解决同义词语义匹配，RRF 融合排序后再经 Cross-Encoder / LLM 重排精排，平衡查全率与查准率。

🖼️ 多模态图像处理

采用 Image-to-Text 策略，利用 Vision LLM 自动生成图片描述并缝合进 Chunk，复用纯文本 RAG 链路即可实现"搜文字出图"。

📡 MCP 生态集成

遵循 Model Context Protocol 标准，暴露 query_knowledge_hub / list_collections / get_document_summary 三个工具，可直接接入支持 MCP 协议的 AI 客户端与 Agent，一次开发、多端调用。

📊 全链路可观测

Ingestion 与 Query 两条链路的状态全程白盒追踪，Streamlit Dashboard 提供数据管理与链路可视化，拒绝"凭感觉"调优。

📈 自动化评估

集成 Ragas 评估框架与自定义 Evaluator，支持 Golden Test Set 回归测试，从数据层面度量检索质量（Hit Rate / MRR / Faithfulness 等）。

🧪 三层测试体系

Unit / Integration / E2E 分层测试，覆盖独立模块逻辑、模块间交互与完整链路（MCP Client / Dashboard）。

系统架构

┌──────────────────────────── 数据摄取（Ingestion）────────────────────────────┐
│  PDF/文档 ──▶ markitdown ──▶ Markdown ──▶ Splitter ──▶ Chunk                │
│       └──▶ Vision LLM 图像描述 ──┐      └──▶ Chunk Refiner / Metadata Enricher
│                                  ▼                                          │
│                          Embedding ──▶ ChromaDB (Upsert)                   │
└──────────────────────────────────────────────────────────────────────────────┘

┌───────────────────────────── 查询（Query）─────────────────────────────────┐
│   Query ──▶ Dense Embedding ──┐                                            │
│            ──▶ BM25 (jieba) ──┴──▶ RRF Fusion ──▶ Rerank ──▶ Top-K 结果    │
│                                          (Cross-Encoder / LLM)             │
└──────────────────────────────────────────────────────────────────────────────┘

┌───────────────────────────── 对外暴露（MCP）────────────────────────────────┐
│   MCP Server: query_knowledge_hub / list_collections / get_document_summary │
│   ◀── Copilot / Claude Desktop / Claude Code / Agent 等 MCP Client          │
└──────────────────────────────────────────────────────────────────────────────┘

┌───────────────────────── 管理与观测（Dashboard / Evaluation）───────────────┐
│   Streamlit Dashboard（总览/数据/Ingestion/摄取追踪/查询追踪/评估）          │
│   Ragas + Custom Evaluator（Golden Test Set 回归）                           │
└──────────────────────────────────────────────────────────────────────────────┘

所有核心组件均通过统一的 config/settings.yaml 配置驱动。

技术栈

类别	技术
语言	Python 3.10+
协议	MCP（Model Context Protocol）
文档解析	markitdown（PDF → Markdown）
文本分块	LangChain Text Splitters（递归 / 语义 / 定长）
向量检索	ChromaDB + Embedding（OpenAI / Azure / Ollama）
稀疏检索	BM25（jieba 中文分词）
重排	Cross-Encoder / LLM Rerank（RRF 融合）
LLM	OpenAI / Azure OpenAI / DeepSeek / Ollama
可视化	Streamlit
评估	Ragas + Custom Evaluator
测试	pytest（Unit / Integration / E2E）

快速开始

环境要求

Python >= 3.10
一个 LLM API Key（OpenAI / Azure / DeepSeek / Ollama 任选）

1. 克隆与安装

git clone <repo-url>
cd MODULAR-RAG-MCP-SERVER
pip install -e .

2. 配置

编辑 config/settings.yaml，填写 LLM / Embedding 的 Provider 与 API Key：

llm:
  provider: "openai"   # openai / azure / ollama / deepseek
  model: "gpt-4o"
  api_key: "YOUR_API_KEY"

embedding:
  provider: "openai"
  model: "text-embedding-ada-002"
  api_key: "YOUR_API_KEY"

3. 摄取文档

# 摄取单个 PDF 或整个目录（递归处理所有 PDF）
python scripts/ingest.py --path ./docs --collection my_knowledge

4. 查询

python scripts/query.py --query "什么是混合检索" --collection my_knowledge --top-k 10

--verbose 可查看 Dense / Sparse / Fusion / Rerank 各阶段中间结果。

5. 启动 Dashboard

python scripts/start_dashboard.py --port 8501

浏览器访问 http://localhost:8501。

使用方式

系统提供三种接入方式：

1. MCP Server（推荐，供 Agent / AI 助手调用）

将 MCP Server 注册到任意支持 MCP 协议的客户端：

{
  "mcpServers": {
    "knowledge-hub": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "<项目路径>"
    }
  }
}

配置完成后，Copilot / Claude Desktop / Claude Code 等即可直接调用 query_knowledge_hub 等工具检索知识库。

2. CLI 命令行

适用于脚本化 / 自动化场景：scripts/ingest.py、scripts/query.py、scripts/evaluate.py。

3. Streamlit Dashboard

提供完整的管理界面：系统总览 / 数据浏览 / Ingestion 管理 / 摄取追踪 / 查询追踪 / 评估面板。

配置说明

所有配置集中在 config/settings.yaml：

配置项	说明
`llm`	生成模型 Provider / Model / API Key / 参数
`embedding`	Embedding 模型配置
`vision_llm`	图像描述模型（Image Captioning）
`vector_store`	向量库类型与持久化目录
`retrieval`	Dense / Sparse Top-K、RRF 融合参数
`rerank`	重排开关与模型
`ingestion`	分块大小 / 重叠 / 切分策略
`evaluation`	评估开关与指标
`observability`	日志级别 / 链路追踪

切换 Provider

得益于工厂模式，切换 Provider 只需改配置：

llm:
  provider: "deepseek"          # 切换为 DeepSeek
  model: "deepseek-chat"
  api_key: "..."

新增 Provider 的扩展路径：① 在 src/libs/llm/ 新增 Provider 类 → ② 在工厂注册 → ③ 更新配置。Embedding / Reranker 同理。

模块详解

Ingestion Pipeline

全链路数据摄取：PDF → Markdown → Chunk → Transform → Embedding → Upsert

基于 markitdown 将 PDF 转为 Markdown
支持递归 / 语义 / 定长三种分块策略
Vision LLM 自动为图片生成描述并缝合进 Chunk，实现多模态检索
Chunk Refiner 与 Metadata Enricher 增强块质量与元数据
DocumentManager 幂等管理，避免重复摄取

Hybrid Search

两段式检索架构：

召回：Dense Embedding 语义检索 + BM25 稀疏检索（jieba 中文分词）并行召回
融合：RRF（Reciprocal Rank Fusion）合并两个结果集
精排：可选 Cross-Encoder / LLM 重排，提升 Top-K 精准度

MCP Server

src/mcp_server/ 暴露三个标准 MCP 工具：

工具	功能
`query_knowledge_hub`	语义检索知识库，返回召回结果
`list_collections`	列出所有知识集合
`get_document_summary`	获取指定文档摘要

Dashboard

Streamlit 六页面管理平台：系统总览 / 数据浏览 / Ingestion 管理 / 摄取追踪 / 查询追踪 / 评估面板。

Observability

Ingestion 与 Query 两条链路的关键中间状态全部落盘为结构化日志与 Trace，便于定位检索质量问题。

Evaluation

集成 Ragas 与自定义 Evaluator，支持 Golden Test Set 回归测试，覆盖 Hit Rate / MRR / Faithfulness / Relevancy 等指标。

模块实现状态

模块	状态
Ingestion / Hybrid Search / MCP Server / Dashboard / Observability	✅ 已实现
Custom Evaluator	🚧 框架已搭建，待完善
Cross-Encoder Reranker	🚧 框架已搭建，需下载本地模型

测试

# 单元测试（快速，无外部依赖）
pytest tests/unit -m "not llm and not slow"

# 集成测试
pytest tests/integration

# 端到端测试（完整链路，含 MCP Client / Dashboard）
pytest tests/e2e

# 全量测试
pytest

三层测试体系：

Unit：独立模块逻辑（分块、召回、融合、配置加载等）
Integration：模块间交互（Ingestion → VectorStore、Retrieval → Rerank 等）
E2E：完整链路（MCP 协议调用、Dashboard 渲染）

目录结构

├── main.py                     # 主入口（配置加载 + 日志初始化）
├── pyproject.toml              # 项目元数据与依赖
├── config/
│   ├── settings.yaml           # 主配置文件
│   └── prompts/                # Prompt 模板
├── src/
│   ├── core/                   # 配置加载、查询引擎、响应、Trace
│   ├── ingestion/              # 摄取链路（chunking / embedding / storage / transform）
│   ├── libs/                   # 抽象接口与实现（llm / embedding / loader / reranker / splitter / vector_store / evaluator）
│   ├── mcp_server/             # MCP Server 与 Tools
│   └── observability/          # 日志、Trace、Dashboard、Evaluation
├── scripts/
│   ├── ingest.py               # 文档摄取 CLI
│   ├── query.py                # 查询 CLI
│   ├── evaluate.py             # 评估 CLI
│   └── start_dashboard.py      # Dashboard 启动
└── tests/
    ├── unit/
    ├── integration/
    └── e2e/

Roadmap

完善 Custom Evaluator 与 Cross-Encoder Reranker
支持 Word / Markdown / HTML 等更多文档格式（扩展 Loader）
Docker 化部署与 CI/CD 流水线
扩展 Agentic RAG / Graph RAG 形态
支持更多 VectorStore 后端（Qdrant / Pinecone）

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

DocsMint A
io.github.HiAi-gg
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Documentation Access Knowledge & Memory RAG Systems
21171
Ragora A
io.github.mregmi
Search your knowledge bases from any AI assistant using hybrid RAG.
RAG Systems Search Knowledge & Memory
2
WauldoOAuth
com.wauldo
Stateless agentic tools over MCP: concept extraction, long-context, knowledge graph, planning.
Knowledge & Memory Autonomous Agents
2
CustomGPT.ai
ai.customgpt.mcp
The CustomGPT.ai MCP server is a fully managed, RAG-powered endpoint that connects large language models with private knowledge bases and external data sources. It provides tools for retrieval-augmented generation queries (send_message), data ingestion (upload_file), and source listing, enabling AI agents to query private documents like PDFs with high accuracy and real-time citations.
RAG Systems Knowledge & Memory Search
2

Related MCP Servers

Modular RAG MCP Server
RAG Systems Search Knowledge & Memory
Bye-666
F
license
Not graded
quality
B
maintenance
A pluggable, observable modular RAG service framework that exposes tool interfaces via the MCP protocol, enabling AI assistants like Copilot and Claude to directly query knowledge bases.
Updated 2 months ago (2026-07-06 10:38 UTC)
1
-
Modular RAG MCP Server
RAG Systems Search Vector Databases
Lina6795
A
license
Not graded
quality
D
maintenance
A pluggable, observable modular RAG service framework that exposes tool interfaces via the MCP protocol, enabling AI assistants like Copilot and Claude to directly invoke knowledge retrieval and reasoning capabilities.
Updated 3 months ago (2026-06-12 07:39 UTC)
MIT
Modular RAG MCP Server
RAG Systems Search
EdmendZ
A
license
Not graded
quality
C
maintenance
A pluggable, observable modular RAG framework that exposes query knowledge hub, list collections, and get document summary tools via MCP, enabling AI assistants to perform hybrid search and document retrieval with reranking.
Updated 2 months ago (2026-07-17 01:24 UTC)
2
MIT
Modular RAG MCP Server
Holysmiles
F
license
Not graded
quality
B
maintenance
A pluggable, observable modular RAG service framework that exposes tools via MCP protocol for AI assistants, supporting hybrid search, reranking, multi-modal processing, and evaluation.
Updated a month ago (2026-08-14 11:59 UTC)
-