# Modular RAG MCP Server

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

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

---

## 快速开始

### 1. 安装依赖

```bash
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`:

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

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

设置环境变量:

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

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

### 3. 摄取文档

```bash
# 单个文件
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. 查询

```bash
# 简单查询
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

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

---

## 架构说明

项目按职责分 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` 中:

```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` 中:

```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 跑评估 + 历史对比 |

---

## 运行测试

```bash
# 单元测试
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