# Nexus-MCP

> Unified, local-first MCP server combining hybrid search (vector + BM25), a static code graph with call edges, and persistent semantic memory in a single process. Designed for AI coding agents via the Model Context Protocol. About 90MB RAM idle and 460MB with the embedding model loaded, no API keys, no cloud dependencies. Source-available under PolyForm Noncommercial 1.0.0.

Nexus-MCP gives AI agents precise, token-efficient code understanding. It indexes codebases into three engines (vector embeddings, BM25 keyword index, rustworkx code graph) and fuses the vector and BM25 results via Reciprocal Rank Fusion. In live benchmarks (v2.1.0, Claude Sonnet, 12 questions per project, 3 runs each) agents with Nexus-MCP used 55 to 35 turns on a private 460-file project (cost -22%) and 93 to 71 turns on django (cost -3%, inside the run-to-run noise), with the same accuracy. See docs/EVALS.md. Supports 25+ programming languages via dual parsing (tree-sitter + ast-grep).

## Evaluate on your repo

- First step for anyone who has not decided: `uvx nexus-mcp-ci eval` in the project folder. Free, offline, no LLM calls; compares Nexus-MCP with Grep and Read on about 30 questions made from the code and prints Strong fit, Likely fit or Weak fit.
- `uvx nexus-mcp-ci eval --example` runs it on the Nexus-MCP source (59 files: 1,234 against 5,385 median tokens to reach the right file). A public `https://` repo URL also works: pallets/click (91 files) gave Strong fit, 1,301 against 24,774 (95% fewer); Chromium base/ (3,638 files) gave Strong fit, 950 against 17,998 (95% fewer).
- `nexus-mcp-ci eval --agent claude[:model]` (or `codex[:model]`, experimental): paid A/B with the user's own CLI login; shows the cost first. `--preset efficient` names the cheapest model and setup at the same accuracy.
- `nexus-mcp-ci eval share <id>`: posts numbers only (no code, no paths) after a yes. No telemetry.
- [Evaluate guide](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/EVALUATE.md) and [benchmarks page](https://jaggernaut007.github.io/nexus-mcp/benchmarks.html)

## Privacy and data

- The server makes no network calls. Downloads: the package, and the embedding model once (`NEXUS_OFFLINE=1` after that).
- Stored: index, memories and graph in `<project>/.nexus/`; model in `~/.cache/huggingface/`; eval results in `~/.nexus-mcp/evals/`.
- `nexus-mcp-ci data where` lists every location; `nexus-mcp-ci data clear --all --yes` removes them. [Privacy guide](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/PRIVACY.md)

## Core Tools (8 MCP tools)

- [index](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Index one or more folders — parallel parsing, incremental reindex on changed files, 8-step pipeline. Starts a file watcher for auto-reindex.
- [status](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Index stats, memory usage, and a staleness warning when files changed since the last index.
- [search](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Hybrid code search — vector semantic + BM25 keyword, fused via RRF, with the definitions of exact names first. Live-grep fallback.
- [find_symbol](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Look up one or more symbols by name — whole code (an outline for a long class), location, callers and callees. Exact or fuzzy matching.
- [graph](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Callers or callees of a symbol; `transitive=True` for change-impact analysis. Replaces find_callers, find_callees and impact. Call edges are static and name-based, so results are a lower bound.
- [analyze](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Code complexity, dependencies, smells, and quality metrics.
- [map](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Project overview (`detail="summary"`), architecture (`"architecture"`), or both (`"full"`). Replaces overview and architecture.
- [memory](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): `action="store"`/`"search"`/`"delete"` — persist and retrieve project context with tags. Replaces remember, recall and forget.

## Install

- PyPI: `pip install nexus-mcp-ci` (or `pip install nexus-mcp-ci[gpu]` for all extras)
- From source: `git clone https://github.com/jaggernaut007/Nexus-MCP && cd Nexus-MCP && ./setup.sh`
- Add to Claude Code: `claude mcp add nexus-mcp -- nexus-mcp-ci`

## Getting Started

- [Website](https://jaggernaut007.github.io/nexus-mcp/): Overview, install tabs for each MCP client, and FAQ
- [PyPI](https://pypi.org/project/nexus-mcp-ci/) and [Glama](https://glama.ai/mcp/servers/jaggernaut007/Nexus-MCP): Package and MCP directory listings

- [README](https://github.com/jaggernaut007/Nexus-MCP/blob/main/README.md): Overview, install, quick start, tool reference, configuration
- [Installation Guide](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/INSTALLATION.md): Prerequisites, setup script, manual install, MCP client integration
- [Usage Guide](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Tool reference, configuration, best practices

## Architecture & Design

- [Architecture](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/ARCHITECTURE.md): System design, data flow, engine composition, memory budget
- [Developer Guide](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/DEVELOPER_GUIDE.md): Contributing, testing, adding tools/engines
- [ADRs](https://github.com/jaggernaut007/Nexus-MCP/tree/main/docs/adr): 19 Architecture Decision Records

## Key Technical Details

- **Search pipeline**: query -> [vector, BM25] -> source files before test files -> RRF fusion (weights 0.5/0.3) -> definitions of exact names first -> live-grep fallback when results are few
- **Storage**: LanceDB (vectors + FTS, mmap disk-backed), SQLite (graph persistence), no ChromaDB
- **Embedding**: bge-small-en-v1.5 default (384d); jina-code is deprecated
- **Graph**: rustworkx PyDiGraph — containment, import and static call edges; caller/callee and impact traversal
- **Parsing**: tree-sitter (symbol extraction for embeddings) + ast-grep (containment and import structure for the graph)
- **Memory**: LanceDB-backed semantic memory with tag filtering, stored with the project index
- **Small results**: `search` gives the whole code of its top 3 results and the signature of the rest; `find_symbol` gives the code of each name (6,000 characters at most for one); `graph` names callers by file. An agent pays for each call with one more read of the whole conversation, so the tools aim at fewer calls, not only smaller results

<!-- results:start -->
## Benchmarks

Source of truth: https://jaggernaut007.github.io/nexus-mcp/benchmarks.json (updated 2026-10-28, version 2.1.0). Method: Claude Code, Claude Sonnet, headless (claude -p), 3 runs per question.

- Private Python project (460 files): cost $0.571 with Grep and Read, $0.446 with Nexus-MCP (-22%); turns 55 to 35; correct 36 and 35 of 36.
- Django (3000 files): cost $0.894 with Grep and Read, $0.863 with Nexus-MCP (-3%); turns 93 to 71; correct 34 and 36 of 36.
- Quick tier (`nexus-mcp-ci eval`, no LLM), Chromium base/ (3638 files): Strong fit; median tokens to the right file 17998 (Grep and Read) and 950 (Nexus-MCP); right file first 40% and 70%.
- Quick tier (`nexus-mcp-ci eval`, no LLM), pallets/click (91 files): Strong fit; median tokens to the right file 24774 (Grep and Read) and 1301 (Nexus-MCP); right file first 27% and 97%.
- Quick tier (`nexus-mcp-ci eval`, no LLM), Nexus-MCP source (59 files): Likely fit; median tokens to the right file 5385 (Grep and Read) and 1234 (Nexus-MCP); right file first 70% and 93%.
- The same code can vary by about 20% in cost with 3 runs per question (measured 2026-10-28).
<!-- results:end -->

## Optional

- [Research Notes](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/RESEARCH.md): Deep dives on LanceDB, ONNX, rustworkx, embedding models
- [Self-Test Demo](https://github.com/jaggernaut007/Nexus-MCP/blob/main/self_test/README.md): End-to-end demo exercising the 8 tools and the Python API
