neutrinos-mcp

Сервер MCP для поиска по корпусу документации Neutrinos (53 публикации, 3 117 тем, 7 810 индексированных фрагментов). Гибридный 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); если директория существует, но не помечена как завершённая (остатки от прерванного запуска, именно то, что вызвало ошибку выше), она удаляется перед свежим клонированием. Затем он создаёт виртуальное окружение, устанавливает пакет (python -m pip install -e . — никогда не используйте голый pip/pip.exe, поскольку именно этот исполняемый файл блокируется политикой выполнения на некоторых защищённых корпоративных машинах, тогда как python.exe по-прежнему разрешён), загружает последнюю предварительно собранную data/neutrinos.db из самого нового релиза GitHub через gh release download, если установлен gh (в противном случае работающий сервер загружает её при первом использовании — см. раздел «Распространение» ниже), регистрирует neutrinos-docs в Claude Code на уровне пользователя (для всех проектов, а не только этого) и добавляет запись в claude_desktop_config.json Claude Desktop (пути для macOS/Linux/Windows обрабатываются; объединяется с помощью небольшого Python-скрипта, а не перезаписывается, поскольку в этом файле обычно уже есть другие MCP-серверы). Это также распространяется на Cowork — вкладка агентной работы в приложении Claude Desktop не является отдельным приложением и не имеет собственной конфигурации; собственный SDK-слой Desktop автоматически мостит серверы, зарегистрированные в его конфигурации, в изолированную виртуальную машину 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. Блокировка касается именно этого исполняемого файла-обёртки; интерпретатор не затрагивается.

• Даже после успешной установки запускаемые файлы .exe, которые pip генерирует для neutrinos-mcp, neutrinos-cli и neutrinos-build (в .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/ кэшируется между запусками, так что это фактически инкрементально, а не полный повторный обход каждый день — см. комментарии в workflow). 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, усечение/потоки реранкера, окна устаревания, бюджет токенов. Веса моделей закреплены по имени и проверяются по манифесту сборки при запуске сервера (AD-12): обслуживание индекса, построенного с другой моделью эмбеддингов, завершается с ошибкой, а не возвращает молча ухудшенные результаты.

Чем это не является

Не является универсальным веб-поиском или поверхностью для выполнения кода, не является графом сущностей, извлечённым LLM, и не писателем — сервер возвращает доказательства со стабильными цитатами (токены ref); составление ответа — задача вызывающего агента. См. план §1.4.