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 を取得し（それ以外の場合は実行中のサーバーが初回使用時に取得します。後述の「配布」を参照）、neutrinos-docs を ユーザースコープ（このプロジェクトだけでなく、すべてのプロジェクト）で Claude Code に登録し、Claude Desktop の claude_desktop_config.json にエントリをマージします（macOS/Linux/Windows のパスに対応。このファイルには他の MCP サーバーが既に含まれていることが一般的なため、上書きではなく小さな Python スクリプトでマージします）。これは Cowork もカバーします — Claude Desktop アプリのエージェントワークタブは別のアプリではなく、独自の設定を持ちません。Desktop 自身の SDK レイヤーが、その設定に登録されたサーバーを Cowork のサンドボックス化された VM に自動的にブリッジします。一方、Cowork セッション内で直接追加されたサーバーは接続できません（VM はホストから分離されているため）。これが、登録先が Desktop の設定ファイルに特化している理由です。パッケージのインストールまでの間に何かが失敗した場合、実行によって作成されたすべてのものが終了前に削除されます — 失敗した試行が次の試行を妨げる残骸を残すことは決してありません。DB の取得またはいずれかの登録ステップでの失敗は削除されません。DB をまだ取得していない、または手動登録が必要な正常なローカルインストールは「失敗」ではないからです。その後、Claude Code / Claude Desktop を再起動してください — セッションが既に実行中に登録されたサーバーは、クライアントが再接続するまで認識されません。

プリビルドのリリース DB を使用せずにソースからビルドする場合:

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 マシンでは、2 つの別々の要因が単純な pip install -e . セットアップをブロックする可能性があり、それぞれ異なる回避策が必要です:

• pip.exe 自体が実行を拒否される（Access is denied）— 裸の pip install の代わりに python.exe -m pip install -e . を使用してください。ブロックされるのはその特定のラッパー実行可能ファイルであり、インタプリタは影響を受けません。

• インストールが成功した後でも、pip が neutrinos-mcp、neutrinos-cli、neutrinos-build 用に生成する .exe ランチャー（.venv\Scripts\ 内）は、実際に実行すると *同じ* Access is denied エラーになる可能性があります — このプロジェクト自身の開発マシンで確認済みです。pip.exe をブロックするポリシーは、どうやら pip.exe を名前で特にブロックしているのではなく、新しく生成されたコンソールスクリプトランチャー全般をブロックしているようです。修正方法はどちらの場合も同じです: .exe を決して呼び出さず、常にインタプリタ経由で実行する — neutrinos-cli ... の代わりに python.exe -m neutrinos_mcp.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 は、4 つの取り込みステージを毎日ライブサイトに対して実行し、data/neutrinos.db を GitHub リリースアセットとして公開します（raw/ は実行間でキャッシュされるため、これは実際には毎日の完全な再クロールではなく増分です — ワークフローのコメントを参照）。install.sh はリポジトリをクローンし、gh release download を使用して最新のリリース DB を取得します。gh が利用できない場合、neutrinos_mcp.server._check_for_db_updates_once がサーバー起動時に初回取得を行います。このチェックはプロセスごとに 1 回、バックグラウンドスレッドで実行され、リクエストパス上では決して実行されません。この区別が重要である理由については、その 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 ラムダ、再ランカー切り詰め/スレッド化、陳腐化ウィンドウ、トークン予算。モデルの重みは名前で固定され、サーバー起動時にビルドマニフェストに対して検証されます（AD-12）: 異なる埋め込みモデルで構築されたインデックスを提供すると、黙って品質の低下した結果を返すのではなく、明確に失敗します。

これは何ではないか

一般的なウェブ検索やコード実行のサーフェスではなく、LLM 抽出エンティティグラフでもなく、ライターでもありません — サーバーは安定した引用（ref トークン）付きの証拠を返します。返信の作成は呼び出し側エージェントの仕事です。計画 §1.4 を参照してください。