# Modular RAG MCP Server

Modular RAG MCP Server 是一个面向私有知识库的模块化 RAG（Retrieval-Augmented Generation，检索增强生成）服务框架。项目支持文档摄取、稠密/稀疏混合检索、可选重排、链路追踪、评估面板，并通过 MCP（Model Context Protocol）协议向外暴露知识库查询能力。

该项目适合作为企业内部知识库、团队文档问答、AI 助手工具接入、RAG 原型验证和检索质量分析的工程基础。

更多架构细节可参考 [系统架构说明](docs/ARCHITECTURE.md)。

## 核心功能

| 模块 | 能力 |
| --- | --- |
| 文档摄取 | 文件完整性检查、PDF 解析、分块、元数据增强、图片描述、向量化和存储 |
| 混合检索 | Dense 向量检索 + BM25 稀疏检索 + RRF 融合排序 |
| 重排 | 支持关闭、Cross-Encoder 重排或 LLM 重排 |
| MCP 服务 | 通过标准 MCP tools 对外提供知识库查询能力 |
| Dashboard | 基于 Streamlit 的系统总览、数据浏览、摄取管理、链路追踪和评估面板 |
| 可观测性 | 记录 Ingestion 和 Query 两条链路的结构化 trace |
| 评估 | 支持自定义指标和 Ragas 评估扩展 |
| 可插拔架构 | LLM、Embedding、Reranker、Splitter、VectorStore、Evaluator 均通过接口和工厂模式组织 |

## 适用场景

- 企业内部知识库：技术文档、产品手册、制度文档、客服资料、研究报告等。
- 团队文档问答：帮助研发、产品、运营或支持团队快速定位内部资料。
- AI 助手接入：通过 MCP 让兼容客户端调用私有知识库查询工具。
- RAG 原型验证：快速验证不同分块、检索、融合、重排和评估策略。
- 检索质量分析：通过 trace、评估集和 Dashboard 检查召回与排序效果。
- 行业知识问答：在法律、医疗、金融、制造、教育等领域接入专有文档。

## 系统架构

```text
文档
  -> Ingestion Pipeline
     -> Loader
     -> Chunker
     -> Transform
     -> Dense + Sparse Encoding
     -> ChromaDB + BM25 Index + Image Index
  -> Query Pipeline
     -> Query Processing
     -> Dense Retrieval
     -> Sparse Retrieval
     -> RRF Fusion
     -> Optional Rerank
     -> Response + Citations
  -> MCP Tools / CLI / Dashboard
```

主要目录：

- `src/ingestion/`：文档摄取流水线、分块、编码和存储协调。
- `src/core/query_engine/`：查询处理、混合检索、融合排序和重排编排。
- `src/mcp_server/`：MCP 服务、协议处理和工具注册。
- `src/observability/`：日志、trace、Dashboard 和评估相关能力。
- `src/libs/`：LLM、Embedding、Loader、Splitter、Reranker、VectorStore 等 provider 抽象和实现。
- `scripts/`：摄取、查询、评估和 Dashboard 启动脚本。

## MCP 工具

当前 MCP Server 注册了以下工具：

- `query_knowledge_hub`：对指定 collection 执行混合检索并返回带引用的结果。
- `list_collections`：列出当前向量库中的 collection，可选返回统计信息。
- `get_document_summary`：根据文档 ID 查询文档标题、摘要、来源、标签和 chunk 数量。

## 环境要求

- Python 3.10+
- 一个可用的 LLM provider，用于生成、元数据增强、图片描述或可选重排
- 一个可用的 Embedding provider，用于稠密向量检索
- ChromaDB，用于本地向量存储

Provider 配置位于 `config/settings.yaml`。

当前代码支持的 provider 类型包括：

- LLM：OpenAI、Azure OpenAI、Ollama、DeepSeek
- Embedding：OpenAI、Azure OpenAI、Ollama
- Vision LLM：OpenAI、Azure OpenAI、Ollama
- Vector Store：ChromaDB
- Rerank：关闭、Cross-Encoder、LLM Reranker

## 安装

```bash
python -m venv .venv
.venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
```

macOS 或 Linux：

```bash
source .venv/bin/activate
```

## 配置

编辑 `config/settings.yaml`，配置实际使用的模型和存储参数。

至少需要关注：

- `llm.provider`
- `llm.model`
- `llm.api_key` 或 provider 对应 endpoint 配置
- `embedding.provider`
- `embedding.model`
- `embedding.api_key` 或 provider 对应 endpoint 配置
- `vector_store.persist_directory`
- `vector_store.collection_name`

默认运行数据目录：

- `data/db/chroma`：ChromaDB 持久化目录
- `data/db/bm25`：BM25 稀疏索引
- `data/db/ingestion_history.db`：摄取历史与文件完整性记录
- `data/db/image_index.db`：图片索引
- `data/images`：提取出的图片资源

这些运行时目录默认不会提交到 git。

## 使用方式

### 摄取文档

摄取单个 PDF：

```bash
python scripts/ingest.py --path documents/report.pdf --collection default
```

摄取目录下的所有 PDF：

```bash
python scripts/ingest.py --path documents/ --collection default
```

强制重新处理已摄取文件：

```bash
python scripts/ingest.py --path documents/report.pdf --collection default --force
```

### 查询知识库

```bash
python scripts/query.py --query "Azure OpenAI 如何配置？" --collection default
```

查看 dense、sparse、fusion、rerank 等中间结果：

```bash
python scripts/query.py --query "RRF 融合策略是什么？" --collection default --verbose
```

关闭重排：

```bash
python scripts/query.py --query "RRF 融合策略是什么？" --collection default --no-rerank
```

### 启动 Dashboard

```bash
python scripts/start_dashboard.py
```

指定 host 和 port：

```bash
python scripts/start_dashboard.py --host localhost --port 8502
```

### 启动 MCP Server

```bash
python -m src.mcp_server.server
```

服务使用 stdio transport。接入 MCP 兼容客户端时，将客户端命令指向该 Python 模块即可。

示例命令结构：

```json
{
  "command": "python",
  "args": ["-m", "src.mcp_server.server"]
}
```

## 项目结构

```text
config/
  settings.yaml                 主配置文件
  prompts/                      Transform 和 Rerank 使用的提示词模板
scripts/
  ingest.py                     文档摄取命令行入口
  query.py                      查询命令行入口
  evaluate.py                   评估命令行入口
  start_dashboard.py            Dashboard 启动入口
src/
  core/                         共享类型、配置、trace、查询引擎、响应构建
  ingestion/                    摄取流水线和文档生命周期管理
  libs/                         provider 抽象和适配器
  mcp_server/                   MCP server 和 tools
  observability/                日志、trace、Dashboard、评估
tests/
  unit/                         单元测试
  integration/                  集成测试
  e2e/                          端到端测试
  fixtures/                     测试数据和样例文档
```

## 测试

运行单元测试：

```bash
pytest tests/unit -v
```

运行全部测试：

```bash
pytest
```

部分 integration/e2e 测试依赖真实 provider 凭证或本地服务。只运行快速测试时可使用 pytest markers：

```bash
pytest -m "unit and not llm"
```

## 扩展方式

项目通过接口和工厂模式组织 provider。新增或替换组件时，建议保持配置驱动的方式：

- 新增 LLM provider：`src/libs/llm/`
- 新增 Embedding provider：`src/libs/embedding/`
- 新增 Vector Store：`src/libs/vector_store/`
- 新增 Splitter：`src/libs/splitter/`
- 新增 Reranker：`src/libs/reranker/`
- 新增 Evaluator：`src/libs/evaluator/` 或 `src/observability/evaluation/`

新增组件时应完成：

1. 实现对应 base interface。
2. 在 factory 中注册 provider。
3. 在 `config/settings.yaml` 中补充配置项。
4. 添加单元测试和必要的集成测试。
5. 更新 README 或 DEV_SPEC 中的配置说明。

## 运行说明

- MCP stdio server 的 stdout 只用于协议消息，日志应写入 stderr。
- 摄取默认通过 SHA256 做幂等跳过，避免重复处理未变化文件。
- 查询和摄取 trace 以 JSONL 形式写入本地文件。
- 当前版本实际实现的向量库后端是 ChromaDB。
- API Key、运行数据、日志和索引文件不应提交到仓库。

## License

MIT