MCP Raganything

MCP RAGAnything

建筑

                            Clients
                     (REST / MCP / Claude)
                               |
                 +-------------+-------------+
                 |          FastAPI App        |
                 +-------------+-------------+
                               |
               +---------------+---------------+
               |                               |
       Application Layer            MCP Servers (FastMCP)
       +------------------------------+       |
       | api/                         |   +---+--------+  +--+-----------+  +--+-------------+
       |   indexing_routes.py         |   | RAGAnything |  | RAGAnything |  | RAGAnything    |
       |   query_routes.py            |   | Query       |  | Files       |  | Classical      |
       |   file_routes.py             |   |  /rag/mcp   |  |  /files/mcp |  |  /classical/mcp|
       |   health_routes.py           |   +---+--------+  +--+-----------+  +--+-------------+
       |   classical_indexing_routes   |       |               |                 |
       |   classical_query_routes      |       |               |         classical_index_file
       | use_cases/                   |       |               |         classical_index_folder
       |   IndexFileUseCase           |       |               |         classical_query
       |   IndexFolderUseCase         |
       |   QueryUseCase               |
       |   ClassicalIndexFileUseCase   |
       |   ClassicalIndexFolderUseCase |
       |   ClassicalQueryUseCase       |
       |   ListFilesUseCase           |
       |   ListFoldersUseCase         |
       |   ReadFileUseCase            |
       | requests/ responses/         |
       +------------------------------+
                |         |          |
                v         v          v
     Domain Layer (ports)
     +----------------------------------------------------------+
     | RAGEnginePort  StoragePort  BM25EnginePort              |
     | DocumentReaderPort  VectorStorePort  LLMPort            |
     +----------------------------------------------------------+
              |         |          |            |      |
              v         v          v            v      v
     Infrastructure Layer (adapters)
     +----------------------------------------------------------+
      | LightRAGAdapter       MinioAdapter                        |
      | (RAGAnything/         (minio-py)                          |
      |  KreuzbergParser)                                         |
     |                                                            |
     | PostgresBM25Adapter       RRFCombiner                      |
     | (pg_textsearch)            (hybrid+ fusion)                |
     |                                                            |
     | KreuzbergAdapter          LangchainPgvectorAdapter         |
     | (kreuzberg - 91 formats) (langchain-postgres PGVector)    |
     |                                                            |
     | LangchainOpenAIAdapter                                     |
     | (langchain-openai ChatOpenAI)                             |
     +----------------------------------------------------------+
              |         |          |            |      |
              v         v          v            v      v
        PostgreSQL        MinIO       Kreuzberg    OpenAI-compatible
        (pgvector +     (object     (document     (LLM API)
         Apache AGE      storage)    extraction)
         pg_textsearch)

先决条件

• Python 3.13+
• Docker和Docker Compose
• 一 开放路由 API密钥（或任何与OpenAI兼容的提供程序）
• 这 soludev-compose-apps/bricks/ 用于生产部署的堆栈（提供PostgreSQL、MinIO和此服务）

快速开始

生产从共享的组合堆栈运行 soludev-compose-apps/bricks/The docker-compose.yml 此存储库仅用于本地开发。

本地开发

# 1. Install dependencies
uv sync

# 2. Start PostgreSQL and MinIO (docker-compose.yml provides Postgres;
#    MinIO must be available separately or added to the compose file)
docker compose up -d postgres

# 3. Configure environment
cp .env.example .env
# Edit .env: set OPEN_ROUTER_API_KEY and adjust MINIO_HOST / POSTGRES_HOST

# 4. Run the server
uv run python src/main.py

API可在 http://localhost:8000.Swagger用户界面位于 http://localhost:8000/docs.

生产（soludev编写应用程序）

cd soludev-compose-apps/bricks/
docker compose up -d

这将启动所有砖服务，包括 raganything-api, postgres，以及 minio.

API 参考

基础路径： /api/v1

健康

# Health check
curl http://localhost:8000/api/v1/health

答复：

{"message": "RAG Anything API is running"}

索引

两个索引端点都接受JSON正文并在后台运行处理。文件从MinIO下载，而不是直接上传。

索引单个文件

下载由标识的文件 file_name 从配置的MinIO存储桶中，然后将其索引到RAG知识图中 working_dir.

curl -X POST http://localhost:8000/api/v1/file/index \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "project-alpha/report.pdf",
    "working_dir": "project-alpha"
  }'

答复(202 Accepted):

{"status": "accepted", "message": "File indexing started in background"}

为文件夹建立索引

列出下的所有对象 working_dir 在MinIO中添加前缀，下载它们，然后对整个文件夹进行索引。

curl -X POST http://localhost:8000/api/v1/folder/index \
  -H "Content-Type: application/json" \
  -d '{
    "working_dir": "project-alpha",
    "recursive": true,
    "file_extensions": [".pdf", ".docx", ".txt"]
  }'

答复(202 Accepted):

{"status": "accepted", "message": "Folder indexing started in background"}

支持的文档格式

该服务通过RAGAnything解析器自动检测和处理以下文档格式：

注： 文件格式检测是自动的。无需配置即可指定文档类型。该服务将在索引时处理任何支持的格式。安装时，所有文档和图像格式都支持开箱即用 raganything[all].

文件浏览和读取

直接从MinIO浏览和读取文件，而无需将其编入RAG知识库。由...驱动 克罗伊茨贝格 用于文档文本提取（91种文件格式）。

列出文件

# List all files in the bucket
curl http://localhost:8000/api/v1/files/list

# List files under a specific prefix
curl "http://localhost:8000/api/v1/files/list?prefix=documents/&recursive=true"

答复(200 OK):

[
  {"object_name": "documents/report.pdf", "size": 1024, "last_modified": "2026-01-01 00:00:00+00:00"},
  {"object_name": "documents/notes.txt", "size": 512, "last_modified": "2026-01-02 00:00:00+00:00"}
]

上传文件

将文件直接上传到MinIO存储桶。文件存储在 {prefix}{filename}。此端点确实 不 索引文件--使用 POST /file/index 上传后将端点添加到RAG知识库中。

允许的文件类型： .pdf, .txt, .docx, .xlsx, .pptx, .md, .csv, .png, .jpg, .jpeg, .gif, .webp, .svg, .bmp, .html, .xml, .json, .rtf, .odt, .ods 最大文件大小： 50 MB

curl -X POST http://localhost:8000/api/v1/files/upload \
  -F "file=@report.pdf" \
  -F "prefix=documents/"

答复(201 Created):

{"object_name": "documents/report.pdf", "size": 2048, "message": "File uploaded successfully"}

错误响应：

读取文件

从MinIO下载文件，使用Kreuzberg提取其文本内容，并返回结果。支持91种文件格式，包括PDF、Office文档、图像和HTML。

curl -X POST http://localhost:8000/api/v1/files/read \
  -H "Content-Type: application/json" \
  -d '{"file_path": "documents/report.pdf"}'

答复(200 OK):

{
  "content": "Extracted text from the document...",
  "metadata": {"format_type": "pdf", "mime_type": "application/pdf"},
  "tables": [{"markdown": "| Header | Value |\n|---|---|\n| A | 1 |"}]
}

错误响应：

查询

查询索引知识库。RAG引擎针对给定的 working_dir 在执行查询之前。

curl -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "working_dir": "project-alpha",
    "query": "What are the main findings of the report?",
    "mode": "naive",
    "top_k": 10
  }'

答复(200 OK):

{
  "status": "success",
  "message": "",
  "data": {
    "entities": [],
    "relationships": [],
    "chunks": [
      {
        "reference_id": "...",
        "content": "...",
        "file_path": "...",
        "chunk_id": "..."
      }
    ],
    "references": []
  },
  "metadata": {
    "query_mode": "naive",
    "keywords": null,
    "processing_info": null
  }
}

BM25查询模式

返回按PostgreSQL全文搜索排序的结果，使用 pg_textsearch每个区块均包含一个 score BM25相关性得分的字段。

curl -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "working_dir": "project-alpha",
    "query": "quarterly revenue growth",
    "mode": "bm25",
    "top_k": 10
  }'

答复(200 OK):

{
  "status": "success",
  "message": "",
  "data": {
    "entities": [],
    "relationships": [],
    "chunks": [
      {
        "chunk_id": "abc123",
        "content": "Quarterly revenue grew 12% year-over-year...",
        "file_path": "reports/financials-q4.pdf",
        "score": 3.456,
        "metadata": {}
      }
    ],
    "references": []
  },
  "metadata": {
    "query_mode": "bm25",
    "total_results": 10
  }
}

混合+查询模式

并行运行BM25和向量搜索，然后使用交互秩融合（RRF）合并结果。每个区块包括 bm25_rank, vector_rank，以及 combined_score 领域。

curl -X POST http://localhost:8000/api/v1/query \
  -H "Content-Type: application/json" \
  -d '{
    "working_dir": "project-alpha",
    "query": "quarterly revenue growth",
    "mode": "hybrid+",
    "top_k": 10
  }'

答复(200 OK):

{
  "status": "success",
  "message": "",
  "data": {
    "entities": [],
    "relationships": [],
    "chunks": [
      {
        "chunk_id": "abc123",
        "content": "Quarterly revenue grew 12% year-over-year...",
        "file_path": "reports/financials-q4.pdf",
        "score": 0.0328,
        "bm25_rank": 1,
        "vector_rank": 3,
        "combined_score": 0.0328,
        "metadata": {}
      }
    ],
    "references": []
  },
  "metadata": {
    "query_mode": "hybrid+",
    "total_results": 10,
    "rrf_k": 60
  }
}

这 combined_score 是以下各项的总和 bm25_score 和 vector_score，每个计算如下 1 / (k + rank)。结果按以下方式排序 combined_score 下降。出现在两个结果集中的块的综合得分将高于仅出现在一个中的块。

______________________________________________________________________

经典RAG管道

基于图的LightRAG旁边的第二个检索路径。经典RAG使用一个简单的块→ 嵌入→ 使用两种质量增强技术检索流： 多查询生成 和 法学硕士作为裁判相关性评分。它将块存储在专用的PGVector表中（每个表一个 working_dir)并且不构建知识图。

运作原理

1. 索引 --从MinIO下载一个文件，通过Kreuzberg提取文本（使用分块），每个块都嵌入并存储在PGVector表中。
2. 查询 --LLM生成用户查询的N个备选短语（多查询），对每个变体进行相似性搜索，结果由 chunk_id，然后法学硕士评委以0-10的评分标准对每个块的相关性进行评分。低于相关性阈值的块被丢弃；其余的按分数排序返回。

经典索引

两个经典的索引端点都接受JSON正文并在后台运行处理。

索引单个文件（经典）

从MinIO下载文件，使用Kreuzberg分块提取文本，并将分块嵌入到范围为的PGVector表中 working_dir.

curl -X POST http://localhost:8000/api/v1/classical/file/index \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "project-alpha/report.pdf",
    "working_dir": "project-alpha",
    "chunk_size": 1000,
    "chunk_overlap": 200
  }'

答复(202 Accepted):

{"status": "accepted", "message": "File indexing started in background"}

索引文件夹（经典）

列出下的所有对象 working_dir 在MinIO中添加前缀，下载它们，并将每个文件索引到PGVector表中。

curl -X POST http://localhost:8000/api/v1/classical/folder/index \
  -H "Content-Type: application/json" \
  -d '{
    "working_dir": "project-alpha",
    "recursive": true,
    "file_extensions": [".pdf", ".docx", ".txt"],
    "chunk_size": 1000,
    "chunk_overlap": 200
  }'

答复(202 Accepted):

{"status": "accepted", "message": "Folder indexing started in background"}

经典查询

查询经典的RAG管道。支持两种模式： 向量 （默认）和 混合 （通过互易秩融合的BM25+向量）。

矢量模式（默认）

LLM生成查询变体，对每个变体运行向量相似性搜索，对结果进行重复数据消除，然后用LLM判断对其进行评分和过滤。

curl -X POST http://localhost:8000/api/v1/classical/query \
  -H "Content-Type: application/json" \
  -d '{
    "working_dir": "project-alpha",
    "query": "What are the main findings of the report?",
    "top_k": 10,
    "num_variations": 3,
    "relevance_threshold": 5.0,
    "mode": "vector"
  }'

混合模式

并行运行BM25全文搜索和多查询向量搜索，使用交互排名融合（RRF）合并结果，然后用LLM判断进行评分。块包括 bm25_score, vector_score，以及 combined_score 领域。

curl -X POST http://localhost:8000/api/v1/classical/query \
  -H "Content-Type: application/json" \
  -d '{
    "working_dir": "project-alpha",
    "query": "What are the main findings of the report?",
    "mode": "hybrid"
  }'

答复(200 OK):

{
  "status": "success",
  "message": "",
  "queries": [
    "What are the main findings of the report?",
    "What key results does the report present?",
    "Summarize the primary conclusions from the report"
  ],
  "chunks": [
    {
      "chunk_id": "a1b2c3d4-...",
      "content": "The primary finding indicates that...",
      "file_path": "project-alpha/report.pdf",
      "relevance_score": 8.5,
      "metadata": {"chunk_index": 0},
      "bm25_score": 0.0164,
      "vector_score": 0.0164,
      "combined_score": 0.0328
    }
  ],
  "mode": "hybrid"
}

如果BM25不可用(BM25_ENABLED=false 或者缺少pg_textsearch扩展），混合模式将回退到向量模式并记录警告。

LightRAG与经典RAG

______________________________________________________________________

MCP服务器

该服务公开 三台MCP服务器，全部使用流式HTTP传输：

RAGAnythingQuery-- /rag/mcp

用于搜索索引知识库的以查询为中心的工具。

工具： query_knowledge_base

工具： query_knowledge_base_multimodal

RAGAnythingFiles-- /files/mcp

文件浏览工具，用于列出和读取MinIO存储中的文件。

工具： list_files

工具： read_file

从MinIO下载文件，使用Kreuzberg提取其文本内容，并返回提取的文本以及元数据和任何检测到的表。

RAGAnythings经典-- /classical/mcp

用于在没有知识图的情况下进行索引和查询的经典RAG工具。

工具： classical_index_file

工具： classical_index_folder

工具： classical_query

运输

所有MCP服务器都使用 可流式传输HTTP 运输独家。将MCP客户端连接到装载路径：

http://localhost:8000/rag/mcp          # RAGAnythingQuery
http://localhost:8000/files/mcp        # RAGAnythingFiles
http://localhost:8000/classical/mcp    # RAGAnythingClassical

配置

所有配置都是通过环境变量进行的，通过Pydantic Settings加载。看 .env.example 以获取完整的参考。

应用程序(AppConfig)

数据库(DatabaseConfig)

LLMLLMConfig)

抹布(RAGConfig)

BM25(BM25Config)

当 BM25_ENABLED 是 false 或者pg_textsearch扩展不可用， hybrid+ 模式回退到 naive （仅矢量）和 bm25 模式返回错误。

经典RAG(ClassicalRAGConfig)

经典的RAG适配器共享相同的 OPEN_ROUTER_API_KEY, OPEN_ROUTER_API_URL/BASE_URL, CHAT_MODEL, EMBEDDING_MODEL，以及 EMBEDDING_DIM LLM配置中的设置。如果初始化失败（例如缺少API密钥），则经典端点返回 503 Service Unavailable 存在描述性错误。

MinIO(MinioConfig)

查询模式

发展

uv sync                          # Install all dependencies (including dev)
uv run python src/main.py        # Run the server locally
uv run pytest                    # Run tests with coverage
uv run ruff check src/           # Lint
uv run ruff format src/          # Format
uv run mypy src/                 # Type checking

Docker（本地）

docker compose up -d             # Start Postgres + API
docker compose logs -f raganything-api   # Follow API logs
docker compose down -v           # Stop and remove volumes

数据库迁移

Alembic迁移在启动时通过以下方式自动运行 db_lifespan 上下文管理器 main.py。在中跟踪迁移状态 raganything_alembic_version 表，与 composable-agents Alembic表避免冲突。

初始迁移(001_add_bm25_support)创建 chunks 桌子与a tsvector 用于全文搜索的列、GIN和BM25索引以及自动更新触发器。

生产要求

PostgreSQL服务器必须具有 pg_textsearch 扩展已安装并加载。在生产中，这需要：

1. Dockerfile.db 构建一个自定义的PostgreSQL镜像，用于编译 pg_textsearch 来源（连同 pgvector 和 Apache AGE).

1. docker-compose.yml 必须配置 shared_preload_libraries=pg_textsearch 为了 bricks-db 服务。本地开发人员 docker-compose.yml 默认情况下，此存储库中包含此内容。

1. Alembic移民 001_add_bm25_support 将失败，如果 pg_textsearch 不可用。确保数据库映像是从以下内容构建的 Dockerfile.db 并且共享库被预加载。

项目结构

src/
  main.py                           -- FastAPI app, triple MCP mounts, entry point
  config.py                         -- Pydantic Settings config classes
  dependencies.py                   -- Dependency injection wiring
  domain/
    entities/
      indexing_result.py             -- FileIndexingResult, FolderIndexingResult
    ports/
      rag_engine.py                  -- RAGEnginePort (abstract)
      storage_port.py                -- StoragePort (abstract) + FileInfo
      bm25_engine.py                 -- BM25EnginePort (abstract)
      document_reader_port.py        -- DocumentReaderPort (abstract) + DocumentContent
      vector_store_port.py          -- VectorStorePort (abstract) + SearchResult
      llm_port.py                   -- LLMPort (abstract)
  application/
    api/
      health_routes.py               -- GET /health
      indexing_routes.py              -- POST /file/index, /folder/index
      query_routes.py                 -- POST /query
      file_routes.py                  -- GET /files/list, GET /files/folders, POST /files/read
      classical_indexing_routes.py   -- POST /classical/file/index, /classical/folder/index
      classical_query_routes.py      -- POST /classical/query
      mcp_query_tools.py              -- MCP tools: query_knowledge_base, query_knowledge_base_multimodal
      mcp_file_tools.py               -- MCP tools: list_files, read_file
      mcp_classical_tools.py          -- MCP tools: classical_index_file, classical_index_folder, classical_query
    requests/
      indexing_request.py            -- IndexFileRequest, IndexFolderRequest
      classical_indexing_request.py  -- ClassicalIndexFileRequest, ClassicalIndexFolderRequest
      classical_query_request.py     -- ClassicalQueryRequest
      query_request.py                -- QueryRequest, MultimodalQueryRequest
      file_request.py                 -- ListFilesRequest, ReadFileRequest
    responses/
      query_response.py              -- QueryResponse, QueryDataResponse
      classical_query_response.py    -- ClassicalQueryResponse, ClassicalChunkResponse
      file_response.py                -- FileInfoResponse, FileContentResponse
    use_cases/
      index_file_use_case.py         -- Downloads from MinIO, indexes single file (LightRAG)
      index_folder_use_case.py       -- Downloads from MinIO, indexes folder (LightRAG)
      query_use_case.py              -- Query with bm25/hybrid+ support
      classical_index_file_use_case.py  -- Classical: download → Kreuzberg chunk → PGVector
      classical_index_folder_use_case.py -- Classical: folder batch index
      classical_query_use_case.py    -- Classical: multi-query + LLM judge + hybrid BM25
      _classical_helpers.py          -- validate_path, build_documents_from_extraction
      list_files_use_case.py          -- Lists files with metadata from MinIO
      list_folders_use_case.py        -- Lists folder prefixes from MinIO
      read_file_use_case.py           -- Reads file from MinIO, extracts content via Kreuzberg
      upload_file_use_case.py          -- Uploads file to MinIO storage
  infrastructure/
    rag/
      lightrag_adapter.py            -- LightRAGAdapter (RAGAnything/LightRAG)
      kreuzberg_raganything_parser.py -- KreuzbergRAGAnythingParser (kreuzberg, custom parser for RAGAnything)
    storage/
      minio_adapter.py               -- MinioAdapter (minio-py client)
    document_reader/
      kreuzberg_adapter.py            -- KreuzbergAdapter (kreuzberg, 91 formats)
    bm25/
      pg_textsearch_adapter.py        -- PostgresBM25Adapter (pg_textsearch, LightRAG tables)
      classical_bm25_adapter.py        -- ClassicalBM25Adapter (pg_textsearch, classical_rag_* tables)
    hybrid/
      rrf_combiner.py                 -- RRFCombiner (Reciprocal Rank Fusion)
    vector_store/
      langchain_pgvector_adapter.py -- LangchainPgvectorAdapter (langchain-postgres PGVectorStore)
    llm/
      langchain_openai_adapter.py    -- LangchainOpenAIAdapter (langchain-openai ChatOpenAI)
  alembic/
    env.py                            -- Alembic migration environment (async)
    versions/
      001_add_bm25_support.py          -- BM25 table, indexes, triggers

许可证

麻省理工学院