# 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).

## 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

## 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
