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 경로 처리, 작은 Python 스크립트로 병합하며 덮어쓰지 않습니다. 이 파일에는 일반적으로 다른 MCP 서버가 이미 있기 때문입니다). 이것은 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 머신에서는 두 가지 별개의 문제가 일반적인 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은 매일 라이브 사이트에 대해 네 가지 수집 단계를 실행하고 data/neutrinos.db를 GitHub 릴리스 자산으로 게시합니다(raw/는 실행 간에 캐시되므로 실제로 매일 전체 재크롤이 아니라 증분입니다 — 워크플로의 주석 참조). install.sh는 저장소를 복제하고 gh release download를 통해 최신 릴리스 DB를 가져옵니다. 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를 참조하세요.