mcp-rag

# MCP-RAG 面向 AI 客户端的服务优先 RAG 服务。 当前主形态是： - FastAPI HTTP 服务 - Streamable HTTP MCP 端点 - 基于 Chroma 的多集合检索 - HTTP / MCP 共用运行时、鉴权、限流、配额、观测与租户上下文 ## 当前状态 这版已经完成： - 正式 `RequestContext` / `TenantContext` - HTTP / MCP 统一生成标准化上下文 - service 层统一消费标准化 context - 配置文件热更新 - 首次运行没有配置文件也不会报错，并会在启动时写入默认配置 - request-level retrieval cache - provider 级预算、熔断、fallback - `/health`、`/ready`、`/metrics` - 更细的 runtime readiness / dependency health - Streamable HTTP MCP smoke test - Chroma-backed 端到端测试 当前仍然不是“生产平台级完成态”，还缺： - 分布式限流、缓存、provider budget 状态共享 - 更正式的身份体系，例如 OIDC / workspace 级鉴权 - 更完整的 tracing / log correlation / metrics export - collection 生命周期治理、后台任务和资源回收策略 ## 架构 当前主链路： ```text HTTP / MCP -> app_factory.py -> context.py -> service_facade.py -> services/ - runtime.py - indexing_service.py - retrieval_service.py - chat_service.py -> core/indexing/ -> retrieval/ ``` 关键模块： - `src/mcp_rag/main.py`: 服务启动入口 - `src/mcp_rag/cli.py`: CLI 启服与初始化 - `src/mcp_rag/http_server.py`: HTTP API 与 Streamable HTTP MCP 挂载 - `src/mcp_rag/mcp_server.py`: MCP 工具定义与 `rag_ask` - `src/mcp_rag/app_factory.py`: HTTP / MCP 共享运行时装配 - `src/mcp_rag/shell_factory.py`: 向后兼容导出 - `src/mcp_rag/context.py`: `RequestContext` / `TenantContext` - `src/mcp_rag/services/runtime.py`: provider、cache、readiness、热更新 - `src/mcp_rag/services/retrieval_cache.py`: request-level retrieval cache ## 主要能力 - 文档上传、切分、入库 - 向量检索 + 轻量关键词检索融合 - `search` / `chat` / MCP `rag_ask` - `collection + user_id + agent_id` 的 tenant 隔离 - API key 鉴权 - 进程内 rate limit - 上传 / 索引配额 - request-level retrieval cache - provider-side budget、熔断、fallback - readiness / health / metrics ## 环境要求 - Python `>= 3.13` - `uv` ## 安装 发布版用户可以直接安装 CLI： ```bash uv tool install mcp-rag ``` 安装完成后可以直接运行： ```bash mcp-rag serve ``` 如果你是在本仓库里开发： ```bash uv sync ``` 如果需要本地 embedding： ```bash uv sync --extra local-embeddings ``` 这里有一个边界要明确： - 使用 `uv tool install mcp-rag` 的安装用户不需要 Node.js，也不需要 `pnpm` - `pnpm` 只用于维护前端时的开发构建，不是服务运…