Gnosis MCP 是一个面向 AI 智能体的文档搜索服务器，通过 MCP（Model Context Protocol）协议暴露工具与资源。其核心目标是替代“把文件直接粘贴进上下文”的做法，让 AI 智能体在需要信息时搜索本地已索引的文档，返回经过排序和高亮的摘录片段，从而显著减少每次查询消耗的 token。
主要能力：
- 零配置：默认使用 SQLite，pip 安装后即可运行；可通过 GNOSIS_MCP_DATABASE_URL 自动切换到 PostgreSQL。
- 混合搜索：关键词搜索（BM25）与语义搜索（本地 ONNX 嵌入，无需 API 密钥）结合，使用 RRF 融合，可通过 GNOSIS_MCP_RRF_K 调参。
- 可选交叉编码器重排序：需安装 [reranking] 额外依赖，默认关闭；官方实测捆绑的 MS-MARCO 重排序器会降低开发文档检索效果，建议先在自己的语料上测试。
- 文档摄取：支持 Markdown、.txt、.ipynb、.toml、.csv、.json，可选 .rst、.pdf；支持 Git 提交历史（ingest-git）和网页爬取（通过 sitemap 或链接爬取）。
- 自动链接：frontmatter 中的 relates_to 可创建可导航的文档图。
- Watch 模式：文件变更时自动重新摄取。
- 清理陈旧文档：gnosis-mcp ingest --prune 删除源文件已不存在的分块，--wipe 重置整个索引。
- 内置评测工具：gnosis-mcp eval 一条命令输出 Hit@K / MRR / Precision@K（基于捆绑的固定样本，属于冒烟测试，并非针对用户语料的测量）。
- Token 节省追踪：gnosis-mcp savings 可查看节省情况；gnosis-mcp usage 可查看查询统计、未命中查询、最常被访问的文档等。
使用方式：
- 安装：pip install 后即可使用 SQLite 默认配置。
- 启用语义搜索：添加本地嵌入，无需 API 密钥，首次运行自动下载约 23 MB 量化模型（MongoDB/mdbr-leaf-ir，Apache 2.0）。
- 连接客户端：提供 Claude Code、Claude Desktop、Cursor、Zed、opencode、Windsurf、VS Code、JetBrains、Cline 等 MCP 客户端的复制粘贴 JSON 配置（见 llms-install.md）。可使用 setup 命令自动为客户端安装配置，doctor 命令检查客户端是否真正调用了服务器。
- Docker：提供多架构镜像，约 140 MB，内置本地 ONNX 嵌入与 REST 接口，并附有 docker-compose.yaml。
- 检查：gnosis-mcp check 验证后端启动且所需 schema 存在；关键词搜索依赖 SQLite FTS5。
适用场景：
- 希望 AI 编程助手基于本地开发文档、API 文档、设计决策记录等进行检索，而不是幻觉出 API 签名。
- 需要跨数百个文件快速搜索、减少 token 消耗的团队或个人。
- 需要完全本地化、无云依赖的文档检索方案。
限制与注意事项：
- 捆绑的评测固定样本返回相同数字，不是用户语料的真实测量；需自行用 tests/bench/bench_real_corpus.py 对自有语料评测。
- 重排序器默认关闭，因为实测在开发文档上会显著降低检索质量并增加延迟。
- 语义搜索需要额外安装嵌入模型，首次运行需下载约 23 MB 模型。
- 写入工具（共三个）默认不暴露，需设置 GNOSIS_MCP_WRITABLE=true。
- 访问日志默认开启，可通过 GNOSIS_MCP_ACCESS_LOG=false 关闭。
- 具体性能数字（如 8.7 ms MCP 往返、混合搜索 p50 < 30 ms、Hit@5=0.92 等）来自官方文档所述公开基准，实际效果需在自有语料验证。
暂未提供的信息：具体收费模式、商业支持、SLA 等未在资料中明确说明。
