Modular RAG MCP Server

一个可插拔、可观测的模块化 RAG（检索增强生成）服务框架，通过 MCP（Model Context Protocol）协议对外暴露工具接口，支持 Copilot / Claude 等 AI 助手直接调用

📖 目录

• 项目概述
• 快速开始
  • 项目架构可视化

🏗️ 项目概述

这个项目是什么

本项目将 RAG 最常见的核心环节——检索（Hybrid Search + Rerank）、多模态视觉处理（Image Captioning）、RAG 评估（Ragas + Custom）、生成（LLM Response）——以及当下热门的应用协议 MCP（Model Context Protocol） 串联为一个完整的、可运行的工程项目。

项目的一大亮点是极易适配到你自己的业务中。得益于全链路可插拔架构，你可以快速将它结合到自己已有的项目里，无论你的背景和需求如何，都能找到适合自己的使用方式。具体的使用策略会在后文 谁适合用这个项目 & 怎么用 中详细展开。

不只是项目，更是一整套思路

比这个项目本身更有价值的，是它背后蕴含的一整套工程化思路：

• 如何编写 DEV_SPEC（开发规格文档）来驱动开发
• 如何用 Skill 基于 Spec 自动完成代码编写
• 如何用 Skill 进行自动化测试、打包、环境配置
• 如何基于可插拔架构进行扩展（比如扩展到 Agent）

学会了思路，你可以自己做全新的项目和扩展。以上每一步的具体做法、设计思路，在笔记中都有对应的视频讲解，建议配合观看。

核心能力一览

技术亮点

🔌 全链路可插拔架构：LLM / Embedding / Reranker / Splitter / VectorStore / Evaluator 每一个核心环节均定义了抽象接口，支持"乐高积木式"替换，通过配置文件一键切换后端，零代码修改。

🔍 混合检索 + 重排：BM25 稀疏检索解决专有名词精确匹配 + Dense Embedding 解决同义词语义匹配，RRF 融合后可选 Cross-Encoder / LLM Rerank 精排，平衡查全率与查准率。

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

📡 MCP 生态集成：遵循 Model Context Protocol 标准，可直接对接 GitHub Copilot、Claude Desktop 等 MCP Client，零前端开发，一次开发处处可用。

📊 可视化管理 + 自动化评估：Streamlit Dashboard 提供完整的数据管理与链路追踪能力，集成 Ragas 等评估框架，建立基于数据的迭代反馈回路。

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

🤖 Skill 驱动全流程：内置 auto-coder（自动编码）、qa-tester（自动测试）、package（清理打包）、setup（一键配置）等 Agent Skill，覆盖从代码编写到测试、打包、部署的完整开发生命周期。每个 Skill 的使用方法和设计思路在笔记的项目部分均有讲解视频，可参考学习。

📖 详细架构设计、模块说明和任务排期请参阅 DEV_SPEC.md

🚀 快速开始

1. 克隆项目

git clone <repo-url>
cd Modular-RAG-MCP-Server

2. 一键配置（Setup Skill）

本项目提供了 Setup Skill 一键完成所有环境配置，包括：Provider 选择 → API Key 配置 → 依赖安装 → 配置文件生成 → Dashboard 启动。

在 VS Code 中打开项目，通过 Copilot / Claude 对话框输入：

setup

Agent 会自动引导你完成全部配置流程。

3. 手动配置与环境搭建

如果你不想使用 Setup Skill，也可以手动完成所有步骤：

3.1 安装依赖

pip install -e .
pip install -e ".[dev]"  # 包含测试依赖

3.2 配置 settings.yaml

编辑 config/settings.yaml，关键字段说明：

llm:                           # LLM 生成模型配置
  provider: "openai"           # openai / azure / ollama / gemini / qwen / deepseek
  model: "gpt-4o"
  api_key: "sk-xxx"           # 支持环境变量 ${VAR_NAME}

embedding:                     # Embedding 模型配置
  provider: "openai"           # openai / azure / ollama / qwen / local
  model: "text-embedding-3-small"
  dimensions: 1536

vector_store:                  # 向量存储
  provider: "chroma"
  persist_directory: "./data/db/chroma"
  collection_name: "knowledge_hub"

retrieval:                     # 检索参数
  dense_top_k: 20
  sparse_top_k: 20
  fusion_top_k: 10
  rrf_k: 60

rerank:                        # 重排序
  enabled: true
  provider: "llm"              # llm / cross_encoder / none
  top_k: 5

evaluation:                    # 评估
  enabled: false
  provider: "custom"           # custom / ragas
  metrics: ["hit_rate", "mrr"]

observability:                 # 可观测性
  log_level: "INFO"
  trace_enabled: true
  trace_file: "./logs/traces.jsonl"

ingestion:                     # 数据摄取
  chunk_size: 1000
  chunk_overlap: 200
  splitter: "recursive"
  batch_size: 100

4. MCP 配置示例

将 MCP Server 接入 AI 工具，只需在对应工具的配置文件中添加本项目：

GitHub Copilot (VS Code)

在你的项目根目录创建 .vscode/mcp.json：

{
  "servers": {
    "modular-rag": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}/src"
      }
    }
  }
}

Claude Desktop

编辑 claude_desktop_config.json（通常在 %APPDATA%\Claude\ 或 ~/Library/Application Support/Claude/）：

{
  "mcpServers": {
    "modular-rag": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "D:/MODULAR-RAG-MCP-SERVER",
      "env": {
        "PYTHONPATH": "D:/MODULAR-RAG-MCP-SERVER/src"
      }
    }
  }
}

配置后重启对应工具，即可在对话中调用 query_knowledge_hub、list_collections、get_document_summary 三个 MCP Tool。

5. Dashboard 使用指南

启动命令

# 方式一：使用启动脚本
python scripts/start_dashboard.py

# 方式二：直接启动
PYTHONPATH=src streamlit run src/observability/dashboard/app.py

默认访问 http://localhost:8501。

六大页面功能

6. 项目架构可视化

项目内置一个交互式代码可视化工具，基于 Cytoscape.js + Mermaid，可在浏览器中直观查看模块间的依赖关系与数据流。

快速启动

cd code-viz
npm install    # 首次使用需要安装依赖
npm start      # 启动可视化服务（默认 http://localhost:3456）

需要 Node.js 18+。首次启动时 prestart 脚本会自动同步前端库文件。

使用方式

1. 启动后在浏览器打开 http://localhost:3456
2. 可视化面板会展示项目全部模块的依赖拓扑图（core / libs / ingestion / mcp_server 等）
3. 支持节点点击、缩放、搜索高亮，可实时查看各模块间的调用关系
4. 修改源码后页面会通过 SSE 热刷新，无需手动刷新浏览器

生成静态报告

cd code-viz
python parser/extract.py    # 解析源码，生成 public/metadata.json

生成的 metadata.json 是所有模块关系的数据源，供前端渲染使用。

跨项目复用

该工具是独立的 Node.js 项目，可直接复制 code-viz/ 目录到其他 Python 项目使用，只需修改 server.js 中的 ROOT 路径指向新的项目根目录即可。

7. 运行测试

# 单元测试（281 个）
pytest tests/unit/ -q

# 集成测试（需要 ChromaDB + 本地依赖）
pytest tests/integration/ -q

# E2E 测试（全链路）
pytest tests/e2e/ -q

# 全部测试
pytest tests/ -q

# 跳过 LLM 依赖的测试
pytest tests/ -q -m "not slow"