jaggernaut007/Nexus-MCP

**Hybrid search + code graph + semantic memory in a single local MCP server — under 350 MB RAM.**
Nexus-MCP is a code intelligence server for the Model Context Protocol. It gives AI agents precise, token-efficient answers about your codebase without cloud dependencies: no API keys, no data egress, no subscriptions.
---
The Problem It Solves
AI coding agents are token-inefficient by default. An agent trying to understand verify_credentials() typically:
1. Glob("src/**/*.py") → 120 files returned, agent reads the most likely 8 → **~12,000 tokens**
2. Grep("verify_credentials") → 3 matches, agent reads surrounding context → **~4,000 tokens**
3. Read("auth/middleware.py") → full 400-line file to understand callers → **~3,000 tokens**
**Total: ~19,000 tokens, 3+ tool calls, no graph relationships.**
With Nexus-MCP:
1. explain("verify_credentials") → symbol definition + related code + quality metrics (callers and callees once call edges are extracted) → **~1,500 tokens, 1 tool call**
Or for discovery:
1. search("credential verification flow") → top-10 semantically relevant chunks across the codebase → **~2,000 tokens, 1 tool call**
**Estimated savings: 30–60% token reduction per coding session.** The exact numbers depend on codebase size and task type — see the benchmarks table below.
---
Quickstart (60 seconds)
Then drop a CLAUDE.md in your project root:
That's it. Claude will index your project on first use and use Nexus-MCP tools automatically.
---
How It Works
Indexing Pipeline (8 steps)
**Incremental reindex:** mtime-based — only changed files are re-processed. Corrupt index detection triggers automatic full rebuild.
Search Pipeline
bash
> pip install "sentence-transformers[onnx]" "optimum[onnxruntime]>=1.19.0"
> bash
Minimal
claude mcp add nexus-mcp-ci -- nexus-mcp-ci
With the code-specific embedding model (requires trust_remote_code)
claude mcp add nexus-mcp-ci -e NEXUS_EMBEDDING_MODEL=jina-code -- nexus-mcp-ci
GPU embeddings
claude mcp add nexus-mcp-ci -e NEXUS_EMBEDDING_DEVICE=cuda -- nexus-mcp-ci
Virtualenv install — pass the full binary path
claude mcp add nexus-mcp-ci -- /path/to/.venv/bin/nexus-mcp-ci
json
{
"mcpServers": {
"nexus-mcp-ci": {
"command": "nexus-mcp-ci",
"args": [],
"env": {
"NEXUS_EMBEDDING_MODEL": "jina-code"
}
}
}
}
json
{
"nexus-mcp-ci": {
"command": "nexus-mcp-ci",
"transport": "stdio"
}
}
markdown
Code Intelligence — nexus-mcp-ci
Every code task in this project MUST follow this workflow:
1. **Session start**: mcp__nexus-mcp__status → if not indexed, mcp__nexus-mcp__index
2. **Before any file read**: mcp__nexus-mcp__search to locate relevant code
3. **To understand a symbol**: mcp__nexus-mcp__explain (not Read)
4. **Before refactoring**: mcp__nexus-mcp__graph with transitive=True to assess blast radius. The current graph has no CALLS edges, so use mcp__nexus-mcp__search to find call sites.
5. **For project orientation**: mcp__nexus-mcp__map with detail="summary" or detail="architecture"
Session start
status() → "indexed: True, 8,412 chunks, 1,203 symbols, 87 MB"
Code discovery
search("JWT token validation", mode="hybrid", limit=10)
→ auth/jwt.py:42 validate_token() score=0.94
→ auth/middleware.py:18 require_auth() score=0.87
→ tests/test_auth.py:91 test_valid_jwt() score=0.81
Deep symbol understanding
explain("validate_token")
→ definition, location, related code
→ callers: [], callees: [] # empty until call edges are extracted (see Known Limitations)
Pre-refactor safety check
graph("validate_token", direction="callers", transitive=True)
→ total_impacted: 0 # no CALLS edges on a real index yet, so this is NOT proof of no callers
Locate call sites with search instead
search("validate_token(", mode="bm25")
→ auth/middleware.py:18 require_auth() ...
→ auth/login.py:57 login_required() ...
python
Index multiple roots in one call — processed sequentially, shared engines