# RAG-Anything MCP Server

RAG-Anything 的独立 FastMCP 服务器项目。该服务器通过 MCP 暴露文档解析、摄取、查询、多模态查询以及轻量级图谱检查工具。

## 快速开始

在当前目录中运行：

```bash
python3 -m venv .venv
source .venv/bin/activate
python scripts/install.py --dev
raganything-mcp configure
raganything-mcp serve
```

`python scripts/install.py --dev` 会自动检测本机是否有可用 NVIDIA GPU：检测到 GPU 时安装 GPU 版本解析依赖；未检测到 GPU 时安装 CPU 版本解析依赖，避免在无 GPU 机器上下载 CUDA/cuDNN 大包。

如需排错，也可以手动强制安装目标：

```bash
python scripts/install.py --dev --cpu
python scripts/install.py --dev --gpu
```

`raganything-mcp configure` 会创建本地 `.env` 文件。`raganything-mcp serve` 会为你的 MCP 客户端启动 stdio MCP 服务器。

## 模型配置层

这里有两个独立的模型层：

- 你的智能体客户端模型在连接 MCP 的客户端中配置，例如 OpenClaw 或 Claude Code。
- 此 MCP 服务器的 `.env` 会配置 RAG-Anything 内部用于 LLM 调用、嵌入以及视觉/多模态处理的模型。

更改客户端模型不会改变 RAG-Anything 内部的嵌入、解析或视觉设置。请通过此服务器的 `.env` 配置这些设置。

## 配置

运行：

```bash
raganything-mcp configure
```

该向导会写入 `.env` 设置，包括：

- LLM 提供商、基础 URL、模型和 API 密钥
- 嵌入提供商、基础 URL、模型、维度和 API 密钥
- 视觉提供商、基础 URL、模型和 API 密钥
- LightRAG 向量存储和图谱存储后端
- 解析器、解析方法、解析 backend、模型下载策略、解析超时、工作目录、输出目录、多模态处理标志和可选多模态处理超时

LLM、嵌入和视觉提供商可以不同。例如，你可以使用一个提供商进行聊天，另一个提供商生成嵌入，并使用单独的支持视觉的模型进行多模态处理。

## 存储后端

默认存储仍保持 LightRAG 本地文件模式：

```env
LIGHTRAG_VECTOR_STORAGE=NanoVectorDBStorage
LIGHTRAG_GRAPH_STORAGE=NetworkXStorage
```

如需使用 Milvus Lite 保存向量、Neo4j 保存知识图谱，可设置：

```env
LIGHTRAG_VECTOR_STORAGE=MilvusVectorDBStorage
LIGHTRAG_GRAPH_STORAGE=Neo4JStorage

MILVUS_URI=rag_storage/milvus_lite.db
MILVUS_DB_NAME=
MILVUS_INDEX_TYPE=AUTOINDEX
MILVUS_METRIC_TYPE=COSINE

NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_neo4j_password
NEO4J_DATABASE=neo4j
NEO4J_WORKSPACE=raganything
```

`MILVUS_URI` 指向本地 `.db` 文件时使用 Milvus Lite；后续升级到远程 Milvus 或 Zilliz 时，只需替换该 URI 和认证配置。Neo4j 需要本地或远程服务已经运行。

当前 MCP 只显式切换 LightRAG 的向量存储和图谱存储；KV 存储与文档状态存储仍保持默认本地 JSON。`raganything_graph_stats` 和 `raganything_graph_search` 是轻量文件检查工具，主要适用于默认 `NetworkXStorage`；切换到 `Neo4JStorage` 后，应以 RAG 查询和 Neo4j 自身查询作为图谱验证依据。

Embedding 入库阶段会对 chunks、entities 和 relationships 批量生成向量。公网 API 预检成功只说明单次小请求可用，不代表批量并发入库稳定。可以用下面的参数降低压力并放宽超时；后续切换到本地 Ollama embedding 时也复用同一组参数：

```env
EMBEDDING_FUNC_MAX_ASYNC=2
EMBEDDING_BATCH_NUM=4
EMBEDDING_TIMEOUT_SECONDS=180
```

如果仍出现 `Embedding func: Worker execution timeout`，优先把 `EMBEDDING_FUNC_MAX_ASYNC` 降到 `1`；如果服务只是慢而非失败，再逐步增加 `EMBEDDING_TIMEOUT_SECONDS`。本地 Ollama 通常可以按机器能力再调大并发。

`PARSER_TIMEOUT_SECONDS` 默认是 `120`。解析 PDF 或图片时，如果 MinerU 超过该时间仍未完成，服务器会终止 MinerU 进程组并返回超时错误，避免解析任务在后台残留并持续占用资源。`raganything_parse`、`raganything_ingest_file` 和 `raganything_ingest_folder` 也支持传入 `timeout_seconds` 覆盖单次调用超时。

OpenClaw 等 stdio MCP 客户端处理 PDF 摄取时，应默认使用 `raganything_ingest_file` 的 `wait_for_completion=false`。推荐流程是：

1. 调用 `raganything_ingest_file`。
2. 保存返回的 `job_id`。
3. 向用户报告 `job_id` 和后台提交状态。
4. 停止当前 agent turn，除非用户明确要求等待、监控、入库后查询或验证完成。

这个后台作业由一个分离的单次 worker 进程执行，不依赖 OpenClaw 的单次 agent turn，也不依赖 stdio MCP server 的生命周期。即使客户端请求已经返回、agent turn 已结束，worker 仍会继续跑完摄取和入库流程。`wait_for_completion=true` 主要用于小文件或排错场景；大 PDF 可能会超过 MCP 请求超时，因此不适合把同步等待作为默认路径。

### Agent polling behavior

OpenClaw 等 agent 默认应在后台入库提交后报告 `job_id` 并返回控制权，不要自动轮询。只有当用户明确要求 monitor、wait、ingest and query，或要求检查失败原因时，才调用 `raganything_job_status(job_id)` 继续跟踪任务。用户之后询问状态时，再使用保存的 `job_id` 查询。

不要把大 PDF 走成 `raganything_parse(include_content=true)` 再 `raganything_insert_content_list` 的流程。`parse` 适合调试解析结果；完整入库应直接使用 `raganything_ingest_file`。如果确实已有内容列表要插入，`raganything_insert_content_list` 也默认提交后台任务并返回 `job_id`；只有需要监控、等待或排错时才通过 `raganything_job_status` 查询。

同一工作目录一次只会有一个 ingest worker 运行。若当前任务仍在运行，请先等待它在 `raganything_job_status` 中变成 `succeeded` 或 `failed`，再提交下一次 ingest。

MinerU backend 默认使用 `PARSER_BACKEND=pipeline`，并默认关闭 `MINERU_FORMULA=false` 与 `MINERU_TABLE=false`，避免普通 CPU/虚拟机首次解析时误走 `hybrid`/`vlm` 高精度路径并下载大体积 VLM 模型。需要高精度解析时，可以在 `.env` 中设置 backend，或在单次 MCP 调用中传入 `backend`、`model_source`、`formula`、`table` 覆盖默认值。

MinerU 执行模式通过 `MINERU_EXECUTION_MODE` 控制：

- `local`：默认模式，使用本机 `mineru` CLI。
- `api`：使用 MinerU 官方精准解析 API。只需要配置 `MINERU_API_KEY`；`MINERU_API_BASE_URL` 默认是 `https://mineru.net`。服务会通过官方批量上传接口申请上传 URL、上传本地文件、轮询解析结果并下载 zip，再转换为本地 RAG-Anything 内容列表。

常用 API 模式配置：

```env
MINERU_EXECUTION_MODE=api
MINERU_API_KEY=你的 MinerU API key
MINERU_API_BASE_URL=https://mineru.net
MINERU_API_TIMEOUT_SECONDS=1800
MINERU_API_POLL_INTERVAL_SECONDS=5
JOB_TIMEOUT_SECONDS=3600
TEXT_INGEST_TIMEOUT_SECONDS=1800
MULTIMODAL_TIMEOUT_SECONDS=
```

`raganything_job_status` 会保留任务真实状态和阶段，例如 `status=running`、`stage=ingest` 或 `stage=processing`。如果运行中已经检测到图谱存储文件，会额外返回 `storage_progress.graph_stats`，但不会把任务伪装成已完成。若后台任务超过 `JOB_TIMEOUT_SECONDS` 仍未返回，会标记为 `failed` 并写入 `TimeoutError`。`TEXT_INGEST_TIMEOUT_SECONDS` 是官方 LightRAG/RAG-Anything 插入阶段的慢任务告警阈值，超过后只会在 manifest 中记录 `text_ingest_slow` warning 并继续等待官方入库完成，不会取消 `insert_content_list(process_multimodal=True)`。如果历史 job 因旧的 text ingest timeout 被标成 `resumable_failed`，但本地 `doc_status` 与 chunk 存储已经证明官方入库完成，`raganything_job_status` 会把该 job 收敛为 `succeeded`。`MULTIMODAL_TIMEOUT_SECONDS` 默认为空，表示不单独限制多模态后处理；设置为正整数后，图片/表格/公式等多模态后处理超过该秒数会让本次入库明确失败，避免任务长期停在半完成状态。

模型拉取策略通过 `MODEL_DOWNLOAD_POLICY` 控制：

- `auto`：默认策略。允许高精度 backend 拉取所需模型；当 backend 是 `hybrid*` 或 `vlm*` 时，解析超时会至少扩展到 `MODEL_DOWNLOAD_TIMEOUT_SECONDS`，默认 `1800` 秒，避免首次模型准备被短解析超时误杀。
- `never`：禁止高精度 backend 触发可能的大模型下载；此时请使用 `pipeline` 或先手动准备模型。
- `require-ready`：要求高精度模型已存在于本地缓存，否则在解析前直接报错，适合生产环境避免业务请求中临时下载大模型。

`raganything_parse`、`raganything_ingest_file` 和 `raganything_ingest_folder` 支持 `start_page` 与 `end_page` 限制解析页码。MCP 参数使用用户习惯的 1-based 页码，例如 `start_page=1,end_page=3` 表示只解析第 1 到第 3 页；服务器内部会自动转换为 MinerU 使用的 0-based 页码。不传页码时默认解析整个文件。

## 工具

服务器会注册 13 个 MCP 工具：

- `raganything_status`：报告配置、存储路径、模型摘要以及可选的解析器可用性。
- `raganything_config_info`：返回当前生效的安全配置摘要。
- `raganything_parse`：将一个源文件解析为 RAG-Anything 内容块。
- `raganything_ingest_file`：默认提交文件解析和摄取后台任务，返回 `job_id`；OpenClaw stdio MCP 客户端做 PDF 摄取时应默认使用 `wait_for_completion=false`。传入 `wait_for_completion=true` 时同步等待完成，适合小文件或排错。
- `raganything_ingest_folder`：解析并摄取某个文件夹中的文件。
- `raganything_insert_content_list`：默认提交现有 RAG-Anything 内容列表的后台插入任务，返回 `job_id`；传入 `wait_for_completion=true` 时同步插入，适合小列表或排错。后台模式会拒绝过大的 `content_list` payload，此时应改用原始文件调用 `raganything_ingest_file`。
- `raganything_job_status`：根据 `job_id` 查看后台任务状态、阶段、结果或错误。
- `raganything_list_jobs`：列出最近的后台任务。
- `raganything_query`：查询已摄取的知识库。
- `raganything_query_multimodal`：使用多模态内容进行查询。
- `raganything_graph_stats`：统计图谱存储中的实体、关系、分块和文档数量。
- `raganything_graph_search`：按关键字搜索图谱存储载荷，默认省略向量字段；只有排查底层存储时才传入 `include_vectors=true`。
- `raganything_graph_export`：将图谱存储载荷导出为 JSON，保存到配置的工作目录中。

图谱工具会直接从 `WORKING_DIR` 读取 RAG-Anything 存储文件；它们适用于在不运行完整查询的情况下检查已摄取数据。

`raganything_query` 接受 `response_mode`：

- `answer`：仅返回生成的答案。
- `context`：仅返回检索到的上下文。
- `both`：返回检索到的上下文和生成的答案。

## 可选离线缓存

默认不包含 `model_cache/` 和 `tiktoken_cache/` 等离线缓存目录。如果你的部署需要这些目录，请自行将缓存目录复制到相应位置，并在启动服务器前将相关环境变量指向这些路径。

## 客户端示例

示例客户端配置文件位于 `examples/`：

- `examples/openclaw.json`
- `examples/claude_code.md`

请在连接客户端之前运行 `raganything-mcp configure`，以便服务器拥有可用的模型和存储设置。

## 冒烟测试

首先从你的 MCP 客户端检查服务器配置和连接：

1. 调用 `raganything_status`，并将 `check_parser` 设置为 `false`。
2. 如果模型设置看起来正确，调用 `raganything_config_info`。
3. 可以选择调用 `raganything_status`，并将 `check_parser` 设置为 `true`，以验证解析器可用性。

然后使用一个小型本地文件测试 RAG 路径：

1. 将一份简短文本、Markdown、PDF 或其他受支持的文件放入此项目目录。
2. 使用该文件路径调用 `raganything_ingest_file`，记录返回的 `job_id`。
3. 使用 `raganything_job_status` 轮询该 `job_id`，直到状态变为 `succeeded`；如果状态为 `failed`，查看返回的 `error`。如果还有一个 ingest 任务在跑，先等它结束再提交新的文件。
4. 调用 `raganything_graph_stats`，确认 `chunks`、`entities` 或 `relationships` 已增加。
5. 调用 `raganything_query`，提出一个关于该文件的简单问题。
6. 如有需要，将 `response_mode` 设置为 `context` 或 `both`，以检查检索到的上下文。