{"$schema":"https://wellknown.network/schemas/agent-record-v1.json","schemaVersion":"1","id":"ag_amxra7sy5b2c","handle":"mcp-rag","url":"https://wellknown.network/agents/mcp-rag","links":{"self":"https://wellknown.network/agents/mcp-rag/record.json","html":"https://wellknown.network/agents/mcp-rag","markdown":"https://wellknown.network/agents/mcp-rag/record.md","api":"https://wellknown.network/api/v1/agents/mcp-rag","status":"https://wellknown.network/api/v1/agents/mcp-rag/status","claim":"https://wellknown.network/agents/mcp-rag/claim","claimApi":"https://wellknown.network/api/v1/claims","claimDescriptor":"https://wellknown.network/agents/mcp-rag/claim.json","badge":"https://wellknown.network/agents/mcp-rag/badge.svg","openapi":"https://wellknown.network/openapi.json","history":"https://wellknown.network/api/v1/agents/mcp-rag/history","tools":"https://wellknown.network/api/v1/agents/mcp-rag/tools"},"ard":{"identifier":"urn:air::server:mcp-rag","type":"application/mcp-server-card+json"},"kind":"mcp_server","declared":{"name":"mcp-rag","summary":"基于mcp的rag服务","description":"# MCP-RAG\n\n面向 AI 客户端的服务优先 RAG 服务。\n\n当前主形态是：\n- FastAPI HTTP 服务\n- Streamable HTTP MCP 端点\n- 基于 Chroma 的多集合检索\n- HTTP / MCP 共用运行时、鉴权、限流、配额、观测与租户上下文\n\n## 当前状态\n\n这版已经完成：\n- 正式 `RequestContext` / `TenantContext`\n- HTTP / MCP 统一生成标准化上下文\n- service 层统一消费标准化 context\n- 配置文件热更新\n- 首次运行没有配置文件也不会报错，并会在启动时写入默认配置\n- request-level retrieval cache\n- provider 级预算、熔断、fallback\n- `/health`、`/ready`、`/metrics`\n- 更细的 runtime readiness / dependency health\n- Streamable HTTP MCP smoke test\n- Chroma-backed 端到端测试\n\n当前仍然不是“生产平台级完成态”，还缺：\n- 分布式限流、缓存、provider budget 状态共享\n- 更正式的身份体系，例如 OIDC / workspace 级鉴权\n- 更完整的 tracing / log correlation / metrics export\n- collection 生命周期治理、后台任务和资源回收策略\n\n## 架构\n\n当前主链路：\n\n```text\nHTTP / MCP\n  -> app_factory.py\n  -> context.py\n  -> service_facade.py\n  -> services/\n       - runtime.py\n       - indexing_service.py\n       - retrieval_service.py\n       - chat_service.py\n  -> core/indexing/\n  -> retrieval/\n```\n\n关键模块：\n- `src/mcp_rag/main.py`: 服务启动入口\n- `src/mcp_rag/cli.py`: CLI 启服与初始化\n- `src/mcp_rag/http_server.py`: HTTP API 与 Streamable HTTP MCP 挂载\n- `src/mcp_rag/mcp_server.py`: MCP 工具定义与 `rag_ask`\n- `src/mcp_rag/app_factory.py`: HTTP / MCP 共享运行时装配\n- `src/mcp_rag/shell_factory.py`: 向后兼容导出\n- `src/mcp_rag/context.py`: `RequestContext` / `TenantContext`\n- `src/mcp_rag/services/runtime.py`: provider、cache、readiness、热更新\n- `src/mcp_rag/services/retrieval_cache.py`: request-level retrieval cache\n\n## 主要能力\n\n- 文档上传、切分、入库\n- 向量检索 + 轻量关键词检索融合\n- `search` / `chat` / MCP `rag_ask`\n- `collection + user_id + agent_id` 的 tenant 隔离\n- API key 鉴权\n- 进程内 rate limit\n- 上传 / 索引配额\n- request-level retrieval cache\n- provider-side budget、熔断、fallback\n- readiness / health / metrics\n\n## 环境要求\n\n- Python `>= 3.13`\n- `uv`\n\n## 安装\n\n发布版用户可以直接安装 CLI：\n\n```bash\nuv tool install mcp-rag\n```\n\n安装完成后可以直接运行：\n\n```bash\nmcp-rag serve\n```\n\n如果你是在本仓库里开发：\n\n```bash\nuv sync\n```\n\n如果需要本地 embedding：\n\n```bash\nuv sync --extra local-embeddings\n```\n\n这里有一个边界要明确：\n- 使用 `uv tool install mcp-rag` 的安装用户不需要 Node.js，也不需要 `pnpm`\n- `pnpm` 只用于维护前端时的开发构建，不是服务运…","publisher":null,"homepage":null,"repository":null,"version":"0.6.2","license":null,"protocols":["mcp"],"tags":["mcp"],"pricing":null,"endpoints":[{"url":"pypi:mcp-rag","type":"package_pypi","auth":null,"probeable":false}],"skills":null,"tools":null,"extra":null,"attribution":{"kind":"pypi","name":"pypi","summary":"pypi","version":"pypi","description":"pypi"}},"derived":{"capabilities":[{"slug":"data.vector-search","name":"Vector Search","confidence":1,"provenance":"derived"},{"slug":"dev.terminal","name":"Terminal & Shell","confidence":0.745,"provenance":"derived"}],"categories":["data","dev"],"language":"en"},"observed":{"status":"unknown","statusReason":"Distributed as a package to run locally; no network endpoint to check.","lastOkAt":null,"lastProbedAt":null,"statusComputedAt":null,"reliability30d":null,"latestObservations":[],"tools":null,"package":{"name":"mcp-rag","registry":"pypi","observedAt":"2026-10-28T12:23:07.231Z","publishedAt":"2026-03-27T08:39:19.743080Z","latestVersion":"0.6.2"},"toolSurface":null,"endpointFacts":[]},"verification":{"claimed":false,"claimedAt":null,"proofs":[]},"provenance":{"sources":[{"source":"pypi","key":"mcp-rag","url":"https://pypi.org/project/mcp-rag/","firstSeenAt":"2026-09-10T03:19:05.732Z","fetchedAt":"2026-10-28T12:22:25.978Z","normalizedAt":"2026-10-28T12:22:25.978Z"}]},"firstSeenAt":"2026-09-10T03:19:05.732Z","updatedAt":"2026-10-28T12:23:07.231Z"}