neutrinos-mcp

一个针对 Neutrinos 文档语料库（53 篇出版物、3,117 个主题、7,810 个索引块）的检索 MCP 服务器。混合 BM25 + 稠密检索、RRF 融合、交叉编码器重排序、跨版本近似重复折叠，以及条件链接图扩展——旨在回答“对于用户实际使用的版本，这是否成立”，而朴素的语义搜索文档方案在此语料库上超过一半的情况下会出错。完整的设计原理（架构决策、数据模型、评估方法）请参阅 implementation_plan.md。

快速开始

neutrinos-mcp 是一个公开仓库，因此克隆、获取发布版本或运行以下任一单行命令均无需认证——只需 git，以及（可选）用于更快拉取预构建数据库的 gh（见下文“分发”部分；如果没有 gh，服务器会在首次使用时自动获取，只是不在安装期间）。

macOS/Linux——一行命令：

curl -fsSL https://raw.githubusercontent.com/jitin-neutrinos/neutrinos-mcp/master/install.sh | bash

Windows（PowerShell）——一行命令：

iex (irm https://raw.githubusercontent.com/jitin-neutrinos/neutrinos-mcp/master/install.ps1)

每个命令都会获取安装脚本本身（而非整个仓库）并直接运行——本 README 的早期版本让单行命令先自行 git clone，然后从其中调用脚本，这重复了脚本自身的克隆步骤，并且在机器上存在因之前中断运行而残留的过期 ~/.neutrinos-mcp 时，会在脚本有机会检测并清理该残留之前，在外部克隆阶段失败（git clone 对非空目标目录会直接拒绝运行）。仅获取脚本并让其自行管理目标目录，可以完全避免这类错误。

每个脚本：检查该位置是否已存在安装且确实完整（.install_complete 标记仅在先前成功运行结束时写入）——如果是，则就地更新（git pull）；如果目录存在但未标记为完整（中断运行的残留，正是上述错误的原因），则先删除再全新克隆。然后创建 venv，安装包（python -m pip install -e .——绝不使用裸 pip/pip.exe，因为该可执行文件在某些锁定严格的企业机器上会被执行策略专门阻止，而 python.exe 本身仍被允许），如果安装了 gh，则通过 gh release download 从最新的 GitHub 发布版本获取最新的预构建 data/neutrinos.db（否则运行中的服务器会在首次使用时获取——见下文“分发”部分），在用户范围（每个项目，而不仅仅是当前项目）向 Claude Code 注册 neutrinos-docs，并将一个条目合并到 Claude Desktop 的 claude_desktop_config.json 中（macOS/Linux/Windows 路径均已处理；使用一个小型 Python 脚本合并，而非覆盖，因为该文件通常已包含其他 MCP 服务器）。这也涵盖 Cowork——Claude Desktop 应用中的代理工作标签并非独立应用，也没有自己的配置；Desktop 自身的 SDK 层会自动将注册在其配置中的服务器桥接到 Cowork 的沙箱虚拟机中。相比之下，直接在 Cowork 会话内添加的服务器根本无法连接（虚拟机与主机隔离），因此注册目标特意是 Desktop 的配置文件。如果直到包安装为止的任何步骤失败，运行所创建的所有内容都会在退出前被移除——失败的尝试绝不会留下残留来破坏下一次运行；数据库获取或任一注册步骤的失败则不会，因为一个已正常本地安装但尚未获取数据库，或仍需手动注册的安装并不算“失败”。之后请重启 Claude Code / Claude Desktop——在会话已运行时注册的服务器，要等到客户端重新连接时才会被拾取。

若要从源码构建而非使用预构建的发布数据库：

pip install -e ".[dev]"

# Build the index (four stages, run in order; full run crawls
# documentation.neutrinos.com and takes ~25 min)
python -m neutrinos_mcp.ingest.crawl      # stage 1 -> raw/*.html (delta by default; --full to re-fetch everything)
python -m neutrinos_mcp.ingest.extract    # stage 2 -> data/topics.jsonl
python -m neutrinos_mcp.ingest.chunk      # stage 3 -> data/chunks.jsonl
python -m neutrinos_mcp.ingest.index      # stage 4 -> data/neutrinos.db

# Query it
neutrinos-cli search "how do I bind a widget to a data model"
neutrinos-cli search "accessing data models" --product Studio --version 9
neutrinos-cli fetch studio-guide-9/data-binding --json
neutrinos-cli products

# Run the MCP server
neutrinos-mcp

在锁定严格的 Windows 机器上，有两件不同的事情可能阻止普通的 pip install -e . 设置，且需要不同的解决方法：

• pip.exe 本身被拒绝运行（Access is denied）——请使用 python.exe -m pip install -e . 而非裸 pip install。阻止的是该特定包装可执行文件；解释器不受影响。

• 即使安装成功，pip 为 neutrinos-mcp、neutrinos-cli 和 neutrinos-build 生成的 .exe 启动器（位于 .venv\Scripts\）在实际运行时也可能遇到*完全相同*的 Access is denied——已在本项目自己的开发机器上确认。阻止 pip.exe 的策略显然也普遍阻止新生成的控制台脚本启动器，而不仅仅是针对 pip.exe 的名称。两种情况的修复方法相同：绝不调用 .exe，始终通过解释器——使用 python.exe -m neutrinos_mcp.cli ... 而非 neutrinos-cli ...，对于服务器：

  claude mcp add neutrinos-docs --scope user `
    -- "<repo>\.venv\Scripts\python.exe" -m neutrinos_mcp.server

  无论 pip install -e . 是否成功，这都有效——config.py 会针对源码检出目录解析每个路径，而非 site-packages，因此如果安装步骤完全失败，请在上面的命令中添加 -e PYTHONPATH="<repo>\src"，其行为将完全相同。install.ps1 已经这样做了（见下文），因此这仅在手动注册时才重要。

Related MCP server: knowledge-server

分发与自动更新

.github/workflows/build-db.yml 每天对实时站点运行四个摄取阶段，并将 data/neutrinos.db 作为 GitHub 发布资产发布（raw/ 在运行之间缓存，因此这实际上是增量更新，而非每天完全重新爬取——请参阅工作流的注释）。install.sh 克隆仓库并通过 gh release download 拉取最新的发布数据库；如果 gh 不可用，neutrinos_mcp.server._check_for_db_updates_once 会在服务器首次启动时获取。该检查每个进程运行一次，在后台线程中，且绝不在请求路径上——请参阅其 docstring 了解该区别为何重要（其同步版本曾因慢速企业网络而拆毁了一个活动的 MCP 连接）。

布局

.github/workflows/build-db.yml   daily ingest + GitHub release publish (see Distribution above)
install.sh       macOS/Linux installer: clone, venv, pip install -e ., fetch release DB, register
config/          settings.toml (runtime config), publications.yaml (product/version registry)
src/neutrinos_mcp/
  ingest/        crawl -> extract -> chunk -> embed -> build (data/neutrinos.db)
  retrieval/     the ranking pipeline: scope -> BM25/dense -> RRF -> rerank -> collapse -> MMR -> expand
  tools/         MCP tool JSON schemas + handlers (the contract; see plan §8.5)
  kb.py          the query API — server.py and cli.py both call this and nothing else touches SQL
  server.py      FastMCP entry point
  cli.py         terminal adapter over the same contract
eval/            golden-set generation, harness, ablation ladder, two-run regression report
tests/           schema contract tests, corpus-integrity tests (skip without a built index), unit tests
data/            neutrinos.db (built artifact), chroma_db (optional mirror), census.json

测试

pytest                                    # unit + schema tests; integrity tests skip without an index
python -m eval.harness --tag baseline     # full-stack retrieval quality on the golden set
python -m eval.ablate                     # §10.4 rung-by-rung ablation
python -m eval.report before.json after.json --gate   # regression gate, exits 1 on a real regression

配置

所有可调项都位于 config/settings.toml 中，而非代码中——检索候选数量、RRF 常数、MMR lambda、重排序器截断/线程数、过期窗口、令牌预算。模型权重按名称固定，并在服务器启动时根据构建清单进行验证（AD-12）：使用不同嵌入模型构建的索引提供服务时，会大声失败，而非返回静默降级的结果。

这不是什么

不是通用的网络搜索或代码执行表面，不是 LLM 提取的实体图，不是写作者——服务器返回带有稳定引用的证据（ref 令牌）；组织回复是调用代理的工作。请参阅计划 §1.4。