Skip to main content

MCP Server RAG (Retrieval-Augmented Generation)

基于 Python 与 FastMCP 构建的工业级检索增强生成 (RAG) 模型上下文协议 (MCP) 服务端

CI Status Release PyPI Python Versions License PRs Welcome


📖 项目简介

mcp-server-rag 是一个专为大语言模型与 AI 智能体(Claude Desktop、Google Antigravity、Cursor、Windsurf、Cline 等)量身打造的开箱即用检索增强生成(RAG)服务端。

项目基于现代 Python 3.10+ 与 FastMCP 框架构建,严格遵循标准化的 Model Context Protocol (MCP) 规范。它彻底告别了传统 RAG 系统的重型捆绑负担,具备单机零中间件开箱即用与企业级分布式水平扩展双模能力:

  • 灵活的存储底座:支持本地内嵌 SQLite + ChromaDB,亦可平滑无缝切换至分布式 Milvus 与企业级关系型数据库(PostgreSQL / MySQL);
  • 全方位检索管线:实现高维向量语义搜索与数据库原生全文检索(FTS5 / GIN tsvector / FULLTEXT)的 RRF 倒数排名融合,并按需接入 FastEmbed ONNX 与云端 HTTP API 双模交叉重排器(Reranker);
  • 多模态与富文档:覆盖 Markdown、代码、结构化数据、在线网页以及 Office/PDF(.docx, .pdf),支持图片原子保护、图像降噪过滤、FastMCP Resource 图片分发与 S3/MinIO 对象存储外链安全归档;
  • 滑动上下文增强:基于双向链表拓扑支持邻近切片窗口扩展(expand_context),精准还原长篇上下文连贯性。

🏛️ 系统架构 (Architecture)

本项目采用分层解耦、双模切换与多源混合检索设计,系统整体运行拓扑如下:

flowchart TD
    subgraph ClientLayer["AI 智能体客户端 (MCP Client)"]
        Client["Claude Desktop / Antigravity / Cursor / Windsurf / CLI"]
    end

    subgraph ProtocolLayer["MCP 通信、安全与资源网关层"]
        Protocol["FastMCP 协议接口 (stdio / SSE)"]
        Guard{"只读守卫门禁\n(MCP_RAG_READ_ONLY)"}
        ResourceGW["FastMCP Resource 图片网关\n(rag://assets/{kb}/{doc}/{filename})"]
    end

    subgraph PipelineLayer["结构感知摄取管线 (Ingestion Pipeline)"]
        Deduper["SHA-256 内容指纹比对\n(幂等去重 / 原子替换)"]
        MDParser["Markdown 标题树保护切片器\n(图片原子块保护)"]
        OfficeParser["Office/PDF 解析器 (.docx/.pdf)\n(图像降噪过滤 / 跨页锚定)"]
        CodeParser["源码语法边界切片器 (.py/.ts/.java/.go)"]
        DataParser["结构化数据切分器 (JSON/CSV/YAML)"]
        URLParser["原生 HTML 视觉降噪与正文清洗"]
    end

    subgraph RetrievalLayer["双路召回与二次重排流水线 (Hybrid Retrieval & Rerank)"]
        DenseSearch["稠密向量语义检索\n(ChromaDB / Milvus)"]
        NativeFTS["数据库原生 FTS 倒排检索\n(SQLite FTS5 / PG tsvector / MySQL FULLTEXT)"]
        RRF["Reciprocal Rank Fusion (RRF k=60)\n排名融合与单调校准"]
        Reranker{"可插拔双模 Reranker\n(MCP_RAG_RERANK_ENABLED)"}
        FastEmbedRerank["FastEmbed ONNX 交叉重排\n(BAAI/bge-reranker-base / CPU)"]
        ApiRerank["云端 HTTP API 重排\n(/v1/rerank: SiliconFlow / Cohere / 百炼)"]
    end

    subgraph StorageLayer["双模存储与资产底座 (Storage Adapters)"]
        MetaStore[("元数据与 FTS 存储\n(SQLite / PostgreSQL / MySQL)")]
        VecStore[("向量存储引擎\n(ChromaDB / Milvus)")]
        AssetStore[("图片资产存储\n(本地磁盘 / S3 / MinIO)")]
    end

    Client <--> Protocol
    Protocol --> Guard
    Guard -->|"写操作/索引工具 (只读时物理隐藏)"| Deduper
    Guard -->|"混合检索/诊断工具"| RetrievalLayer
    Protocol <--> ResourceGW
    ResourceGW <--> AssetStore

    Deduper --> MDParser & OfficeParser & CodeParser & DataParser & URLParser
    MDParser & OfficeParser & CodeParser & DataParser & URLParser --> StorageLayer

    DenseSearch & NativeFTS --> RRF
    RRF --> Reranker
    Reranker -->|"fastembed"| FastEmbedRerank
    Reranker -->|"api"| ApiRerank
    Reranker -->|"disabled"| Client
    FastEmbedRerank & ApiRerank --> Client

✨ 核心特性

  • 🪶 单机零中间件自足 (Zero-Middleware Invariant): 坚决不强制引入外部中间件;内建 SQLite 管理元数据与 FTS5 倒排索引,默认内嵌 ChromaDB 持久化向量索引,单机冷启动秒级就绪。
  • ⚡ 本地轻量级 CPU 推理 (FastEmbed ONNX): 默认集成 FastEmbed 运行时与 BAAI/bge-small-zh-v1.5(512 维,~90MB 模型),纯 CPU 毫秒级生成稠密向量,内置镜像加速,无 GPU 依赖。
  • 🌐 多模型向量嵌入生态 (Embedding Providers): 支持通过环境变量无缝切换至 OpenAI、通义千问 (Qwen)、Ollama、DeepSeek 等 OpenAI 兼容嵌入接口;支持 MRL 向量维度动态裁剪、自动网络维度探测与跨模型写入防错熔断。
  • 🔍 原生 FTS + 向量混合检索与 RRF 融合 (Hybrid Search): 拒绝引入庞大的外部 Elasticsearch;利用 SQLite FTS5、PostgreSQL GIN tsvector 或 MySQL FULLTEXT 原生倒排检索,结合标准 RRF(Reciprocal Rank Fusion, $k=60$)算法与单调置信度校准,彻底解决特定代码、专有名词与精确术语漏召回痛点。
  • 🎯 双模可插拔二次重排 (Reranker): 支持通过 MCP_RAG_RERANK_ENABLED=true 按需开启精排;提供基于 FastEmbed ONNX 的纯 CPU 本地交叉编码(默认 BAAI/bge-reranker-base)与兼容云端 /v1/rerank(SiliconFlow、Cohere、百炼)的 HTTP 驱动,对扩大候选初筛池进行交叉注意力重排并按阈值截断。
  • 🖼️ 多模态图片资产网关与 S3/MinIO 共享 (Multimodal & MCP Resources):
    • 原子切片保护:确保 Markdown 与 HTML 图片标签不被切片切断;
    • FastMCP Resource:提供标准化 rag://assets/{kb_name}/{doc_id}/{filename} 协议,供多模态模型按需拉取图像二进制流;
    • 多端共享与安全归档:支持将图片上传至 S3/MinIO 对象存储并自动转写为公网直链;内置严谨的 SSRF 防御沙箱(拦截环回、私有 IP、链路本地、DNS 重绑定与危险重定向),安全归档远程外链。
  • 📑 Office / PDF 富文档智能摄取 (Zero-LangChain): 原生集成 .docx 与 .pdf 解析引擎,支持段落与表格(SDT / AlternateContent)语法边界提取、智能图像降噪过滤(过滤宽高小于 64px 或体积小于 5KB 的装饰噪点图)与跨页图片语义锚定。
  • 🔗 滑动上下文窗口与邻近切片拼接 (Context Window Stitching): 基于双向链表存储拓扑,在检索时支持通过 expand_context(1 ~ 5 步)自动向前、向后扩展并去重缝合邻近切片,有效弥补固定切片截断的上下文裂痕。
  • 🏛️ 企业级双模存储平滑升级:
    • 向量底座:支持从本地内嵌 ChromaDB 无感切换至企业级分布式 Milvus 集群;
    • 元数据库:支持从 SQLite 升级为高并发 PostgreSQL 或 MySQL。
  • 🛡️ 工业级只读安全防灾门禁 (Read-Only Guard): 通过 MCP_RAG_READ_ONLY=true 在 FastMCP 握手层物理隐藏全部写操作工具,提供双层纵深防御,杜绝智能体误操作污染生产数据。

🛠️ 快速开始

方式一:使用 uvx 免安装一键运行 (推荐首选)

无需预先安装 Python 依赖,直接通过 uvx 即开即用:

uvx ateng-mcp-server-rag

若需包含可选企业级扩展(如 Milvus、Office/PDF、Postgres、MySQL、S3 支持):

# 包含所有可选驱动扩展
uvx "ateng-mcp-server-rag[all]"

# 或仅引入指定驱动扩展(如 office 与 s3)
uvx "ateng-mcp-server-rag[office,s3]"

方式二:使用 Docker 容器运行

# 拉取并运行预构建多架构容器镜像
docker run -i --rm -v $(pwd)/.rag_data:/app/.rag_data ghcr.io/atengk/mcp-server-rag:latest

或使用仓库自带的 docker-compose.yml 后台守护运行:

docker compose up -d

方式三:源码本地开发安装与运行

# 1. 克隆代码仓库
git clone https://github.com/atengk/mcp-server-rag.git
cd mcp-server-rag

# 2. 激活本地 Git 规范提交守护钩子
git config core.hooksPath .githooks

# 3. 基于 uv 快速同步项目全量依赖与开发工具
uv sync --all-extras --dev

# 4. 启动 MCP 服务端
uv run mcp-server-rag

💻 通用 MCP 客户端接入配置 (Client Configuration)

将以下配置片段追加至你的 MCP 宿主配置文件中(如 Claude Desktop 的 claude_desktop_config.json、Antigravity 的 mcp_settings.json 或 Cursor / Windsurf 的 MCP 扩展配置):

1. 标准默认接入配置 (uvx 免安装,纯本地零配置)

💡 提示:在包尚未发布至 PyPI 或需直接运行本地克隆源码时,执行 uvx 可能报错 No solution found;请改用下方「1.1 本地仓库源码直连配置」方式启动。

{
  "mcpServers": {
    "rag": {
      "command": "uvx",
      "args": ["ateng-mcp-server-rag"]
    }
  }
}

1.1 本地仓库源码直连配置 (uv --directory)

先在仓库目录执行一次 uv sync --all-extras 完成依赖安装,再在 MCP 客户端配置中直接指向本地仓库目录:

{
  "mcpServers": {
    "rag": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-rag",
        "run",
        "--no-sync",
        "mcp-server-rag"
      ]
    }
  }
}

2. 开启云端 Embedding + 二次 Reranker 重排模式

{
  "mcpServers": {
    "rag": {
      "command": "uvx",
      "args": ["ateng-mcp-server-rag"],
      "env": {
        "MCP_RAG_EMBEDDING_PROVIDER": "qwen",
        "MCP_RAG_EMBEDDING_MODEL": "text-embedding-v3",
        "MCP_RAG_EMBEDDING_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "MCP_RAG_EMBEDDING_API_KEY": "sk-your-dashscope-api-key",
        "MCP_RAG_RERANK_ENABLED": "true",
        "MCP_RAG_RERANK_PROVIDER": "api",
        "MCP_RAG_RERANK_MODEL": "BAAI/bge-reranker-v2-m3",
        "MCP_RAG_RERANK_BASE_URL": "https://api.siliconflow.cn/v1",
        "MCP_RAG_RERANK_API_KEY": "sk-your-siliconflow-api-key"
      }
    }
  }
}

3. 企业级全栈模式 (PostgreSQL + Milvus + S3 图片网关)

{
  "mcpServers": {
    "rag": {
      "command": "uvx",
      "args": ["ateng-mcp-server-rag[all]"],
      "env": {
        "MCP_RAG_VECTOR_STORE": "milvus",
        "MCP_RAG_MILVUS_URI": "http://10.0.0.10:19530",
        "MCP_RAG_MILVUS_TOKEN": "YOUR_MILVUS_TOKEN",
        "MCP_RAG_METADATA_STORE": "postgresql",
        "MCP_RAG_DATABASE_URL": "postgresql://rag_user:YOUR_DB_PASSWORD@10.0.0.11:5432/rag_metadata",
        "MCP_RAG_STORAGE_TYPE": "s3",
        "MCP_RAG_S3_BUCKET": "team-rag-assets",
        "MCP_RAG_S3_ENDPOINT": "https://minio.corp.internal:9000",
        "MCP_RAG_S3_ACCESS_KEY": "YOUR_S3_ACCESS_KEY",
        "MCP_RAG_S3_SECRET_KEY": "YOUR_S3_SECRET_KEY",
        "MCP_RAG_ARCHIVE_REMOTE_IMAGES": "true"
      }
    }
  }
}

⚠️ 企业级中间件前置准备与避坑提示:

  • PostgreSQL / MySQL 预建库:需预先创建目标数据库(如 rag_metadata),表结构与索引由服务端在首次连接时自动初始化。
  • DSN 特殊字符处理:MCP_RAG_DATABASE_URL 已支持自动转义用户名与密码中的 @、:、#、? 等特殊字符;若连接串较复杂,推荐改用 MCP_RAG_DB_HOST / MCP_RAG_DB_PORT / MCP_RAG_DB_USER / MCP_RAG_DB_PASSWORD / MCP_RAG_DB_NAME 拆分环境变量。
  • S3 / MinIO 预建桶要求:MCP_RAG_STORAGE_TYPE=s3 默认要求预先手动创建 MCP_RAG_S3_BUCKET 存储桶;若需在桶不存在时由服务端自动创建,请显式设置 MCP_RAG_S3_AUTO_CREATE_BUCKET=true,并可通过 rag_doctor 验证存储桶连通性。
  • Milvus 按维度隔离集合:默认按 {MCP_RAG_MILVUS_COLLECTION_PREFIX}_d{dimension}(如 mcp_rag_chunks_d512、mcp_rag_chunks_d1024)自动分集合,避免多维度模型切换建库冲突,并自动平滑兼容历史单集合 mcp_rag_chunks;如需固定单个集合名,可配置 MCP_RAG_MILVUS_COLLECTION。

4. 只读安全模式 (生产查阅与防误删场景)

在握手层物理隐藏所有建库、索引与清理工具,仅开放检索与问答探针:

{
  "mcpServers": {
    "rag": {
      "command": "uvx",
      "args": ["ateng-mcp-server-rag"],
      "env": {
        "MCP_RAG_READ_ONLY": "true"
      }
    }
  }
}

🧰 FastMCP 工具与资源契约规范 (Tools & Resources)

一、 FastMCP 核心工具矩阵 (14 Tools)

1. 知识库生命周期管理 (Knowledge Base Lifecycle)

工具名称 读写属性 参数与类型 核心功能说明
rag_create_kb 写操作 name: str
description: str = ""
owner: str = "default"
visibility: str = "public"
创建新的知识库逻辑命名空间并在底层向量库与元数据库初始化(含维度一致性校验)。
rag_list_kbs 只读 (无入参) 枚举所有知识库,包含各自的文档总数、切片统计、创建与更新时间。
rag_clear_kb 写操作 name: str 原子清空指定知识库下的所有文档、切片与关联图片资产,保留基础配置。
rag_delete_kb 写操作 name: str 物理销毁指定知识库及其关联的全部元数据、倒排索引、向量数据与物理资产。

2. 多源数据摄取与细粒度管理 (Ingestion & Document Management)

工具名称 读写属性 参数与类型 核心功能说明
rag_index_text 写操作 kb_name: str
text: str
title: str
metadata: dict = None
archive_remote_images: bool | None = None
extract_images: bool = True
对纯文本内容进行语法切片、向量嵌入与入库;支持基于内容指纹幂等去重与图片资产控制。
rag_index_file 写操作 kb_name: str
file_path: str
metadata: dict = None
archive_remote_images: bool | None = None
extract_images: bool = True
background: bool = False
自动识别格式(Markdown、源码、数据、Office、PDF),支持跳过图片加速摄取、进度汇报与后台异步任务模式。
rag_index_directory 写操作 kb_name: str
dir_path: str
glob_pattern: str = "**/*"
max_files: int = 200
recursive: bool = True
archive_remote_images: bool | None = None
extract_images: bool = True
background: bool = False
批量扫描并摄取本地目录文档;内置忽略列表、max_files 防超时截断及 background=True 异步后台任务支持。
rag_index_url 写操作 kb_name: str
url: str
metadata: dict = None
archive_remote_images: bool | None = None
extract_images: bool = True
抓取网页并清洗 HTML 视觉噪点,提取正文、处理相对外链图片并完成向量化。
rag_get_task_status 查询 (读写模式可用) task_id: str 查询由 rag_index_file(..., background=True) 或 rag_index_directory(..., background=True) 返回的后台任务执行进度、状态与最终结果。
rag_delete_document 写操作 kb_name: str
doc_id: str
按文档 ID 精确级联删除单个文档、所有切片以及登记的物理图片资产。

3. 混合检索与上下文增强 (Hybrid Search & Context Augmentation)

工具名称 读写属性 参数与类型 核心功能说明
rag_search 只读 kb_name: str | list[str]
query: str
top_k: int = 5
threshold: float = 0.0
keyword: str = None
metadata_filter: dict = None
expand_context: int = 0
跨库向量检索与原生 FTS 倒排 RRF 融合混合检索:
1. 支持单库名、知识库名称列表或 "*" 跨全库联合检索;
2. 支持相似度阈值截断(0.0 ~ 1.0);
3. 精准关键词必须包含过滤与元数据标量过滤;
4. 支持 Reranker 二次交叉重排打分;
5. 支持 expand_context 邻近上下文滑动扩展;
6. 返回结果包含 images 结构化图片元数据。
rag_query_with_context 只读 kb_name: str | list[str]
query: str
top_k: int = 5
threshold: float = 0.0
keyword: str = None
metadata_filter: dict = None
expand_context: int = 0
检索相关切片,并自动格式化组装为包含来源标题、知识库归属、评分打分与 Markdown 引用块的增强提示词,供大模型直接回答问题。

4. 运维诊断与健康监测 (Operations & Diagnostics)

工具名称 读写属性 参数与类型 核心功能说明
rag_doctor 只读 (无入参) 全维系统健康自检:检查 SQLite/PG/MySQL 连通性、向量库连通性与 Milvus 集合维度一致性、S3 存储桶可用性、磁盘占用、模型维度、Reranker 状态与只读状态。
health_check 只读 (无入参) 检查 RAG MCP 服务的在线状态、服务标识与版本号。

二、 FastMCP 标准资源网关 (MCP Resources)

服务端动态注册并暴露符合 MCP 规范的标准图片资源模板:

rag://assets/{kb_name}/{doc_id}/{filename}
  • 协议能力:多模态大模型在检索切片中获取图片地址后,可直接通过 MCP read_resource 协议读取对应图片的精确二进制流(BlobResourceContents)与 MIME 类型(image/png, image/jpeg 等);
  • 只读兼容:在 MCP_RAG_READ_ONLY=true 模式下,写工具虽被物理隐藏,但 Resource 网关保持正常开放,保障智能体多模态图文查阅畅通无阻。

💡 典型 Agent 交互工作流示范

# 1. 摄取本地设计文档(含本地相对图片)
Agent 调用 -> rag_index_file(kb_name="project_docs", file_path="./docs/architecture.docx")
返回结果: {"success": true, "status": "indexed", "chunk_count": 12, "images_count": 2}

# 2. 混合检索(带滑动邻近切片扩展)
Agent 调用 -> rag_search(kb_name="project_docs", query="图片资产网关与高可用架构", top_k=1, expand_context=1)
返回命中切片:
{
  "chunk_id": "doc_1_5",
  "text": "...前序切片内容...\n[当前切片] 团队图片网关采用 FastMCP Resource 协议暴露资产...\n...后序切片内容...",
  "score": 0.9520,
  "metadata": {
    "retrieval_channels": ["vector", "fts"],
    "rrf_score": 0.032787,
    "rerank_score": 0.9520,
    "rerank_model": "BAAI/bge-reranker-base",
    "images": [
      {
        "filename": "arch_diagram.png",
        "resource_uri": "rag://assets/project_docs/doc_1/arch_diagram.png",
        "mime_type": "image/png",
        "alt": "高可用架构拓扑图"
      }
    ]
  }
}

⚙️ 环境变量配置契约 (Configuration Contract)

本项目所有配置项统一遵循 MCP_RAG_ 命名空间前缀,具备严格的类型校验与异常非法输入安全回退:

环境变量名 数据类型 默认缺省值 功能说明与容错机制
MCP_RAG_DATA_DIR Path .rag_data 本地持久化数据根目录(存放 SQLite metadata.db、Chroma 索引与本地图片资产)。
MCP_RAG_READ_ONLY bool false 只读安全守卫:设为 true/1/yes/on 时,在 MCP 握手层物理隐藏全部写操作工具。
MCP_RAG_CHUNK_SIZE int 600 默认切片长度(字符数),若传入非法非数字字符串自动安全回退为 600。
MCP_RAG_CHUNK_OVERLAP int 80 切片重叠窗口长度(字符数),若传入负数或非法格式自动安全回退为 80。
MCP_RAG_MAX_FILES_BATCH int 200 单次目录批量扫描摄取文件上限,防止超大目录导致 MCP 调用超时。
向量存储配置
MCP_RAG_VECTOR_STORE string chromadb 向量存储引擎类型,支持 chromadb(默认本地)与 milvus(远程分布式集群)。
MCP_RAG_MILVUS_URI string http://localhost:19530 外部 Milvus 集群接入服务地址(仅在 VECTOR_STORE=milvus 时生效)。
MCP_RAG_MILVUS_TOKEN string "" 外部 Milvus 集群认证鉴权 Token 或 username:password。
MCP_RAG_MILVUS_COLLECTION string "" 显式固定 Milvus 物理集合名(如 mcp_rag_chunks);留空时默认启用按维度自动分集合隔离策略。
MCP_RAG_MILVUS_COLLECTION_PREFIX string mcp_rag_chunks 按维度隔离时的 Milvus 集合前缀(生成 {prefix}_d{dimension} 集合,如 mcp_rag_chunks_d512)。
元数据存储配置
MCP_RAG_METADATA_STORE string sqlite 元数据与原生 FTS 存储驱动,支持 sqlite、postgresql、mysql。
MCP_RAG_DATABASE_URL string "" 关系型数据库连接 DSN(如 postgresql://user:pass@host:5432/db);支持密码特殊字符自动编码,优先级高于拆分变量。
MCP_RAG_DB_HOST string "" 数据库主机名/IP(拆分配置项)。
MCP_RAG_DB_PORT int None 数据库端口(缺省自动适配各数据库默认端口)。
MCP_RAG_DB_USER string "" 数据库认证用户名。
MCP_RAG_DB_PASSWORD string "" 数据库认证密码(自动执行 URL 编码)。
MCP_RAG_DB_NAME string "" 目标数据库名。
向量嵌入配置
MCP_RAG_EMBEDDING_PROVIDER string fastembed 嵌入引擎类型,支持 fastembed、openai、qwen、ollama、deepseek、siliconflow、openai-compatible。
MCP_RAG_EMBEDDING_MODEL string BAAI/bge-small-zh-v1.5 嵌入模型标识,各 Provider 具备专属默认推荐模型。
MCP_RAG_EMBEDDING_BASE_URL string "" 外部 Embedding 服务基准 URL(Ollama / Qwen / OpenAI 等各具备预设默认值)。
MCP_RAG_EMBEDDING_API_KEY string "" 外部 Embedding 服务鉴权 API Key(Bearer 鉴权)。
MCP_RAG_EMBEDDING_DIMENSION int None 显式指定向量维度(支持 OpenAI / Qwen 等 MRL 维度裁剪;缺省时自动发起探针探测)。
MCP_RAG_EMBEDDING_TIMEOUT_SECONDS int 30 外部嵌入服务单次 HTTP 请求超时秒数(已接入 OpenAI 兼容驱动,下限 min_val=1)。
MCP_RAG_EMBEDDING_BATCH_SIZE int 32 切片向量化单批请求最大条数,超长文档自动按此分片并发进度汇报(下限 min_val=1)。
二次重排 (Reranker) 配置
MCP_RAG_RERANK_ENABLED bool false 二次重排全局开关;设为 false 时完全跳过 Reranker,零额外计算开销与零模型加载。
MCP_RAG_RERANK_PROVIDER string fastembed 重排驱动模式,支持 fastembed(本地 CPU ONNX)与 api(云端 HTTP API)。
MCP_RAG_RERANK_MODEL string BAAI/bge-reranker-base 重排模型名称标识(云端如 BAAI/bge-reranker-v2-m3)。
MCP_RAG_RERANK_BASE_URL string "" 云端重排服务基准 URL(如 https://api.siliconflow.cn/v1,自动适配 /v1/rerank)。
MCP_RAG_RERANK_API_KEY string "" 云端重排服务鉴权 API Key。
MCP_RAG_RERANK_TIMEOUT_SECONDS int 30 云端重排 HTTP 请求超时秒数。
图片资产与对象存储配置
MCP_RAG_STORAGE_TYPE string local 图片资产存储类型,支持 local(本地磁盘)与 s3(AWS S3 / MinIO)。
MCP_RAG_S3_BUCKET string "" S3 存储桶名称(storage_type=s3 时必填,默认需预先创建)。
MCP_RAG_S3_ENDPOINT string "" S3 兼容服务端点(MinIO 如 https://minio.example.com:9000)。
MCP_RAG_S3_REGION string us-east-1 S3 存储区域。
MCP_RAG_S3_ACCESS_KEY string "" S3 Access Key ID。
MCP_RAG_S3_SECRET_KEY string "" S3 Secret Access Key。
MCP_RAG_S3_PREFIX string assets S3 对象存储根前缀目录。
MCP_RAG_S3_PUBLIC_BASE_URL string "" S3 资产对外公共 HTTPS 直链基准域名(配置后切片内图片自动转写为此直链)。
MCP_RAG_S3_TIMEOUT_SECONDS int 30 S3 连接与传输超时秒数。
MCP_RAG_S3_AUTO_CREATE_BUCKET bool false S3 桶不存在时是否由客户端尝试自动创建(默认 false,要求运维预建桶)。
MCP_RAG_ARCHIVE_REMOTE_IMAGES bool false 远程图片外链自动归档开关(设为 true 时通过 SSRF 防御沙箱抓取外链并归档至存储桶)。
MCP_RAG_REMOTE_IMAGE_TIMEOUT_SECONDS int 8 抓取外链图片单次 HTTP 超时秒数(默认 8,下限 min_val=1)。
MCP_RAG_REMOTE_IMAGE_MAX_BYTES int 10485760 (10MB) 抓取或提取图片最大允许字节大小(下限 min_val=1024)。
MCP_RAG_REMOTE_IMAGE_CONCURRENCY int 4 并发抓取远程外链图片的线程池最大并发数(下限 min_val=1)。
MCP_RAG_REMOTE_IMAGE_SKIP_DOMAINS string (CSV) img.shields.io,badgen.net,forthebadge.com 跳过归档的远程图片域名清单(逗号分隔,显式设为空串可清空默认跳过列表)。
MCP_RAG_REMOTE_IMAGE_SKIP_EXTENSIONS string (CSV) .svg 跳过归档的远程图片后缀清单(逗号分隔,显式设为空串可清空默认跳过列表)。

📁 支持的文件格式与切片策略

文件大类 包含后缀扩展名 专用切片策略与边界保护
Markdown 文档 .md, .markdown 原生感知 # 到 ###### 标题树结构,完整保护代码块与 ![alt](url) 图片原子块。
Office & PDF 文档 .docx, .pdf 提取段落、表格与样式结构;内置图片降噪过滤(剔除噪点小图),维持上下文图文锚定。
编程源码 .py, .ts, .tsx, .js, .jsx, .java, .go, .rs, .sql, .c, .cpp, .cs, .sh 按 Class、Def、Function 及语句块自然边界切分,保留上下文可读性。
结构化数据 .json, .csv, .yaml, .yml, .toml 保留完整键值对象与行数据元组,避免字段跨切片错位断裂。
普通文本 .txt, .log, .rst 基于段落双换行符与标点符号自适应递归分块。
在线网页 http:// 或 https:// 页面 过滤 <script>、<style>、导航与页脚等视觉噪点,提取正文并安全解析相对图片。

🧪 本地研发与自动化门禁验证

项目秉持严格的质量标准,要求本地验证 100% 通过后方可交付:

# 1. 静态代码风格与 Lint 检查 (0 警告)
uv run ruff check .

# 2. 代码自动排版格式校验 (100% 格式合规)
uv run ruff format --check .

# 3. 严格类型检查 (Python 3.10+ Strict Mypy)
uv run mypy src/mcp_server_rag

# 4. 全量端到端测试套件执行 (100% 全绿通过)
uv run pytest -v

📄 开源许可与社区参与

本项目遵循 Apache-2.0 许可证。

欢迎提交 Issue 提出建议或发起 Pull Request!

Metadata

Release files for ateng-mcp-server-rag 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ateng-mcp-server-rag 1.0.0
File Size Uploaded Provenance Actions
ateng_mcp_server_rag-1.0.0.tar.gz 658.3 kB Without provenance Details for ateng_mcp_server_rag-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ateng-mcp-server-rag 1.0.0
File Interpreter ABI Platform Actions
ateng_mcp_server_rag-1.0.0-py3-none-any.whl Python 3 none any Details for ateng_mcp_server_rag-1.0.0-py3-none-any.whl

Total release size: 800.3 kB

Release files / ateng_mcp_server_rag-1.0.0.tar.gz

Download URL ateng_mcp_server_rag-1.0.0.tar.gz
Size 658.3 kB
Tags Source
SHA-256 checksum
How to use checksums
4e80862fa47486456032a970c6e0515d5886f3966348b72ff6d3260c02ac714f
BLAKE2b-256 checksum
How to use checksums
c997bcf3e4cb610c4bad94a9a945a544b0396fc08e0c987c13f9088909cf8ca7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / ateng_mcp_server_rag-1.0.0-py3-none-any.whl

Download URL ateng_mcp_server_rag-1.0.0-py3-none-any.whl
Size 142.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
22b46d25982beec8f66b48cc1b096cc126c655f530fb5db02798ca8f2ec85f8f
BLAKE2b-256 checksum
How to use checksums
e23b4d08775335f8d56ed2134fd2e873ef64480a97c78dc72c9d7073cc342d84
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for ateng-mcp-server-rag 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page