# Nexus-MCP

> Unified, local-first MCP server combining hybrid search (vector + BM25 + graph), structural code graph analysis, and persistent semantic memory in a single process. Designed for AI coding agents via the Model Context Protocol. <350MB RAM, no API keys, no cloud dependencies. MIT licensed.

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 results via Reciprocal Rank Fusion with FlashRank re-ranking. Agents get exactly the code they need in 500-2000 tokens instead of reading entire files (5000-15000 tokens). Supports 25+ programming languages via dual parsing (tree-sitter + ast-grep).

## Core Tools (15 MCP tools)

- [search](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Hybrid code search — vector semantic + BM25 keyword + graph structural, fused via RRF, re-ranked with FlashRank. Supports language/type filters, path scoping, three verbosity levels (summary/detailed/full).
- [index](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Index a codebase — parallel parsing, incremental reindex on changed files, 8-step pipeline.
- [find_symbol](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Look up a symbol by name — definition, location, relationships. Exact or fuzzy matching.
- [find_callers](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Find all direct callers of a function — essential before refactoring.
- [find_callees](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Find all functions called by a given function — trace execution flow.
- [explain](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Combined graph + vector + analysis explanation of a symbol — one call replaces 3-5 tool calls.
- [impact](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Transitive change impact analysis — "what breaks if I change X?"
- [analyze](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Code complexity, dependencies, smells, and quality metrics.
- [overview](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): High-level project overview — files, languages, symbols, quality.
- [architecture](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Architectural analysis — layers, dependencies, entry points, hubs.
- [remember](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Store semantic memory with tags and TTL — persists context across sessions.
- [recall](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Search memories by semantic similarity.
- [forget](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Delete memories by ID, tags, or type.
- [status](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Server status, indexing stats, memory usage.
- [health](https://github.com/jaggernaut007/Nexus-MCP/blob/main/docs/USAGE_GUIDE.md): Readiness/liveness probe.

## Install

- PyPI: `pip install nexus-mcp-ci` (or `pip install nexus-mcp-ci[gpu,reranker]` 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-ci -- nexus-mcp-ci`

## Getting Started

- [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): 14 Architecture Decision Records

## Key Technical Details

- **Search pipeline**: query -> [vector, BM25, graph] parallel -> RRF fusion (weights 0.5/0.3/0.2) -> FlashRank re-rank -> token budget truncation
- **Storage**: LanceDB (vectors + FTS, mmap disk-backed), SQLite (graph persistence), no ChromaDB
- **Embedding**: ONNX Runtime with bge-small-en-v1.5 default (~50MB), optional CodeRankEmbed (~500MB)
- **Graph**: rustworkx PyDiGraph — callers, callees, imports, inheritance, centrality, impact analysis
- **Parsing**: tree-sitter (symbol extraction for embeddings) + ast-grep (structural relationships for graph)
- **Memory**: LanceDB-backed semantic memory with 6 types, TTL expiration, tag filtering
- **Token budgets**: summary ~500tok, detailed ~2000tok, full ~8000tok — agents request only what they need

## 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 all 15 tools
