Skip to main content
Glama
wuwux666

Modular RAG MCP Server

by wuwux666
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Modular RAG MCP Server

可插拔、可观测的模块化 RAG 系统。三种接入方式：Web 界面、REST API、MCP 协议——改一行 YAML 即可切换 LLM / Embedding / VectorStore 后端。

快速开始

1. 安装

git clone https://github.com/wuwux666/RAG-MCP-SERVER.git && cd MODULAR-RAG-MCP-SERVER
pip install -e ".[dev]"

2. 配置

编辑 config/settings.yaml，最少配 LLM + Embedding：

llm:
  provider: "deepseek"
  model: "deepseek-v4-pro"
  api_key: "sk-xxx"

embedding:
  provider: "openai"
  model: "text-embedding-v3"
  api_key: "sk-xxx"
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"

3. 摄入文档

python scripts/ingest.py --file data/documents/your_doc.pdf --collection default

4. 启动服务

# Web 界面 + API（推荐）
uvicorn src.api.server:app --reload --port 8000
cd frontend && npm install && npm run dev       # 浏览器打开 localhost:5173

# 或 MCP Server（供 AI Agent 调用）
python -m src.mcp_server.server

Related MCP server: Librarian

三种接入方式

方式

入口

适用场景

🌸 Web 界面

localhost:5173

人在浏览器中搜索、管理文档、查看追踪

🔗 REST API

localhost:8000/api/*

外部应用/脚本通过 HTTP 调用

🤖 MCP Server

stdio JSON-RPC

Claude Desktop / Copilot 等 AI Agent 直接调用

三种方式共享同一套检索核心，互不冲突，可同时运行。

REST API 端点

POST /api/query           传统混合检索（快）
POST /api/agentic-query   ReAct 智能路由（复杂多跳问题）
GET  /api/collections     集合列表
POST /api/documents/upload  文档上传
GET  /api/documents          文档列表
DELETE /api/documents/{id}   删除文档
GET  /api/traces/query       查询追踪
GET  /api/traces/ingestion   摄取追踪

MCP Tools

Tool

功能

query_knowledge_hub

混合检索（Dense + Sparse + RRF + Rerank），支持 agentic 参数自动路由

list_collections

列出 ChromaDB 集合及统计

get_document_summary

文档元数据与内容预览

架构

┌─────────────────────────────────────────────────┐
│  Vue3 前端 (Sakura 🌸)         :5173            │
│  Chat · 文档管理 · 追踪 · 评估                    │
└──────────────────┬──────────────────────────────┘
                   │ HTTP
┌──────────────────┴──────────────────────────────┐
│  FastAPI REST API              :8000            │
│  /api/query · /api/agentic-query · /api/docs    │
└──────────────────┬──────────────────────────────┘
                   │ 复用
┌──────────────────┴──────────────────────────────┐
│  src/core/  +  src/agentic/                     │
│  HybridSearch · ReAct Loop · Ingestion Pipeline │
└──────────────────┬──────────────────────────────┘
                   │
┌──────────────────┴──────────────────────────────┐
│  MCP Server (stdio)                             │
│  query_knowledge_hub · list_collections · ...   │
└─────────────────────────────────────────────────┘
         ▲
         │ MCP 协议
    ┌────┴────┐
    │ Claude  │  (外部 AI Agent)
    └─────────┘

检索链路：Query → QueryProcessor(jieba) → Dense + Sparse 并行 → RRF Fusion → Rerank(可选) → Response + Citations

摄入链路：PDF → Load(MarkItDown) → Split(Recursive) → Transform(LLM Refine/Enrich/Caption) → Dual Encode → Store(ChromaDB + BM25)

Agentic 智能路由：统一入口 query_knowledge_hub，LLM 自动判断问题复杂度——简单问题走传统混合检索，复杂多跳问题触发 ReAct 循环（分解→搜索→评估→改写→综合）。

核心特性

特性

说明

🔌 全链路可插拔

LLM / Embedding / VectorStore / Reranker 等 6 大组件工厂模式 + YAML 驱动，改配置零代码切换

🔀 混合检索

Dense（语义向量）+ Sparse（BM25 关键词）+ RRF 融合 + Cross-Encoder / LLM 精排，每层独立 fallback

🤖 Agentic RAG

ReAct 推理循环，自主分解问题、调用多工具、迭代检索，支持复杂多跳对比/因果/广度类问题

🖼️ 多模态

PDF 图片 → Vision LLM 生成描述 → 缝合进文本检索链路，"搜文出图"无需独立图片索引

📊 白盒可观测

Ingestion 5 阶段 + Query 5 阶段全链路 Trace JSONL，Streamlit Dashboard 逐阶段展开

✅ 自动化评估

Ragas LLM-as-Judge + Custom 指标 + Golden Test Set 回归测试

🧪 工程化

TDD 开发，1200+ 测试（Unit / Integration / E2E），零外部数据库依赖

项目结构

MODULAR-RAG-MCP-SERVER/
├── config/settings.yaml          # 全局配置
├── scripts/                      # CLI 工具
│   ├── query.py, ingest.py       # 命令行查询/摄入
│   └── agentic_query.py          # ReAct Agent CLI
├── frontend/                     # Vue3 前端 (Sakura UI)
│   └── src/views/                # Chat, Documents, Traces, Evaluation
├── src/
│   ├── api/                      # FastAPI REST Server (新增)
│   │   ├── server.py             # 入口 :8000
│   │   ├── schemas.py            # Pydantic 模型
│   │   └── routers/              # query, collections, docs, traces
│   ├── agentic/                  # Agentic RAG 模块 (新增)
│   │   ├── react_loop.py         # ReAct 循环状态机
│   │   ├── mcp_client.py         # MCP 子进程客户端
│   │   └── ...                   # parser, tracker, registry, prompts
│   ├── core/                     # 核心层：类型 · 配置 · 检索引擎 · 响应
│   ├── libs/                     # 可插拔后端：LLM · Embedding · VectorStore · Reranker · ...
│   ├── ingestion/                # 摄入管道：Load → Split → Transform → Encode → Store
│   ├── mcp_server/               # MCP Server (stdio)
│   └── observability/            # Dashboard · 评估 · Trace
└── tests/                        # Unit / Integration / E2E

技术栈

Python · FastAPI · Vue3 · Vite · TypeScript · MCP Protocol · ChromaDB · BM25 · jieba · LangChain · DeepSeek · OpenAI · Streamlit · Ragas · pytest · SQLite

CLI 速览

# 传统检索
python scripts/query.py --query "Azure OpenAI 怎么配置？" --top-k 5

# Agentic 多跳推理
python scripts/agentic_query.py --query "对比项目A和项目B的技术选型差异" --verbose

# 摄入文档
python scripts/ingest.py --file data/documents/report.pdf --collection default

# 启动 Dashboard
streamlit run src/observability/dashboard/app.py

# 启动 MCP Server
python -m src.mcp_server.server

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

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MinerU Document Explorer by opendatalab

    MinerU Document Explorerofficial

    opendatalab
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to search, deep-read, and build knowledge bases from Markdown, PDF, DOCX, and PPTX documents via MCP tools for retrieval, document navigation, and ingestion.
    16 npm
    633
    MIT

  • Librarian

    arcadeai-labs
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides AI agents with persistent knowledge storage, enabling them to store, search, and retrieve text, documents, and files using semantic and keyword search via MCP tools.
    32
    Apache 2.0

  • rag-retriever-mcp

    code-lawyer
    F
    license
    A
    quality
    D
    maintenance
    A local-first document retrieval engine that mounts as an MCP tool for agents to index files, search for relevant passages, and let the agent's own LLM answer.
    4
    -

  • mcp-rag-bridge

    zyay
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to query and manage a document knowledge base via MCP, with RAG-powered search and grounded answers with citations.
    MIT