Skip to main content
Glama
Ryo-234

Modular RAG MCP Server

by Ryo-234
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

# Modular RAG MCP Server

可扩展、高可观测的模块化 RAG（检索增强生成）MCP Server。

状态：A-H 8 个阶段全部完成(65 个任务,~1010 个测试,~18350 行代码)。

快速开始

1. 安装依赖

git clone <repo>
cd modular-rag-mcp-server
python -m venv .venv
.venv\Scripts\activate   # Windows
# source .venv/bin/activate  # Linux/Mac
pip install -e .

2. 配置 API Key

编辑 config/settings.yaml:

llm:
  provider: minimax
  model: MiniMax-M3
  api_key: "${MINIMAX_API_KEY}"  # 读环境变量

embedding:
  provider: minimax
  model: embo-01
  api_host: https://api.minimax.chat

设置环境变量:

# Windows PowerShell
$env:MINIMAX_API_KEY = "sk-cp-xxxxxxxxxx"

# Linux/Mac
export MINIMAX_API_KEY="sk-cp-xxxxxxxxxx"

3. 摄取文档

# 单个文件
python scripts/ingest.py --path /path/to/doc.pdf

# 整个目录
python scripts/ingest.py --path /docs/

# 指定 collection
python scripts/ingest.py --path /docs/ --collection mydocs

# 强制重新摄取(忽略 SHA256 缓存)
python scripts/ingest.py --path /docs/ --force

4. 查询

# 简单查询
python scripts/query.py --query "什么是深度学习?"

# 指定 Top-K
python scripts/query.py --query "Python 装饰器" --top-k 5

# 限定 collection
python scripts/query.py --query "transformer" --collection mydocs

# 跳过 Reranker(快一点)
python scripts/query.py --query "test" --no-rerank

5. 启动 Dashboard

python scripts/start_dashboard.py
# 访问 http://localhost:8501

Related MCP server: MCP Knowledge Service

架构说明

项目按职责分 4 层:

A. 工程骨架(A1-A3)        — pytest 配置、Settings、目录结构
B. 可插拔层(B1-B16)        — LLM/Embedding/Splitter/VectorStore/Reranker 抽象
C. 摄取管线(C1-C15)       — PDF → Document → Chunks → 向量 → 存储
D. 检索管线(D1-D7)         — Query → D1 解析 → D2/D3 并行 → D4 融合 → D6 重排
E. MCP 工具(E1-E6)         — JSON-RPC server + 3 个工具
F. 观测(F1-F5)             — TraceContext + JSON Lines 日志
G. Dashboard(G1-G6)        — Streamlit 多页面 UI
H. 评估(H1-H5)             — Ragas + golden test set + 阈值门控

核心设计原则:

  • 每层独立可测(mock 隔离)

  • 失败降级(不影响主流程)

  • 关注点分离(数据 vs 渲染)

  • 依赖注入(测试友好)

MCP 配置示例

GitHub Copilot

在 mcp.json 中:

{
  "mcpServers": {
    "modular-rag": {
      "command": "python",
      "args": ["src/mcp_server/server.py"],
      "env": {
        "MINIMAX_API_KEY": "sk-cp-xxxxxxxxxx"
      }
    }
  }
}

Claude Desktop

在 claude_desktop_config.json 中:

{
  "mcpServers": {
    "modular-rag": {
      "command": "python",
      "args": ["src/mcp_server/server.py"],
      "env": {
        "MINIMAX_API_KEY": "sk-cp-xxxxxxxxxx"
      }
    }
  }
}

Dashboard 使用

Dashboard 有 6 个页面:

页面

功能

总览(Overview)

系统配置卡片 + Collection 统计

数据浏览(DataBrowser)

文档列表 + Chunk 详情 + 图片预览

摄取管理(IngestionManager)

上传文件 + 触发摄取 + 删除文档

摄取追踪(IngestionTraces)

F4 trace 历史 + 阶段耗时柱图

查询追踪(QueryTraces)

F3 query trace + dense/sparse/rerank 对比

评估(EvaluationPanel)

H3 跑评估 + 历史对比

运行测试

# 单元测试
pytest -q tests/unit/

# 集成测试
pytest -q tests/integration/

# E2E 测试
pytest -q tests/e2e/

# 全部
pytest -q

# 指定测试
pytest -q tests/unit/test_query_processor.py
pytest -q tests/integration/test_ingestion_pipeline.py

故障排查 FAQ

Q: 启动失败 "ModuleNotFoundError" A: 重新 pip install -e .

Q: API Key 错误 A: 确认环境变量 MINIMAX_API_KEY 已设置,值正确

Q: 摄取无数据 A: 1) 确认 PDF 文件存在;2) 检查 data/documents/ 目录权限

Q: 查询无结果 A: 1) 确认先 ingest.py 摄取数据;2) BM25 索引存在(data/db/bm25/);3) 检查 MINIMAX_API_KEY

Q: Dashboard 启动失败 A: 1) pip install streamlit;2) 检查端口 8501 未占用

Q: 评估结果全 0 A: 1) golden_test_set.json 中的 expected_chunks 跟实际 chunk_id 不匹配;2) 看 data/db/chroma 确认数据存在

License

MIT

Deploy Server
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

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-rag-assistant

    EdwinIN01
    F
    license
    Not graded
    quality
    B
    maintenance
    Provides RAG-based knowledge retrieval and document management as MCP tools, supporting hybrid search, reranking, and retrieval process visualization.
    -

  • MCP RAG Server

    amaralphp
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables document ingestion, semantic search, and retrieval-augmented generation via MCP tools and REST API, using vector embeddings and intelligent chunking.
    MIT