Skip to main content
Glama
deenesjakoruzh
jaggernaut007

nexus-mcp-ci

by jaggernaut007
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Nexus-MCP

PyPI version Python 3.10–3.12 License: MIT CI Glama MCP server

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.

pip install nexus-mcp-ci
claude mcp add nexus-mcp-ci -- nexus-mcp-ci

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 + all callers + all callees + complexity metrics → ~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.

Related MCP server: embecode

Quickstart (60 seconds)

# 1. Install
pip install nexus-mcp-ci

# 2. Register with Claude Code
claude mcp add nexus-mcp-ci -- nexus-mcp-ci

# 3. Verify (in any Claude Code session)
# Claude will automatically use nexus-mcp-ci tools when CLAUDE.md instructs it

Then drop a CLAUDE.md in your project root:

## Code Navigation

Use nexus-mcp-ci tools before built-in file tools:
- Start sessions with `mcp__nexus-mcp__status`; run `index` if needed
- `search` before `Read/Grep`
- `explain` instead of reading a file to understand a symbol
- `impact` before any refactor

That's it. Claude will index your project on first use and use Nexus-MCP tools automatically.

How It Works

Indexing Pipeline (8 steps)

Source files
    │
    ├─ Step 1: Discover ──────── walk tree, filter by ext/size/.gitignore
    │
    ├─ Step 2: Parse symbols ─── tree-sitter (parallel ThreadPool)
    │           extracts: functions, classes, methods
    │           captures: name, signature, docstring, line_start/end, language
    │
    ├─ Step 3: Parse graph ────── ast-grep (sequential for consistency)
    │           extracts: call edges, import edges, inheritance edges
    │           output: UniversalGraph(nodes=[], edges=[])
    │
    ├─ Step 4: Transfer graph ── populate rustworkx PyDiGraph
    │           O(1) node lookup by name, Rust-backed traversal
    │
    ├─ Step 5: Chunk ──────────── Symbol → CodeChunk
    │           deterministic IDs: SHA256(file_path + symbol_name + line)
    │           avoids duplicate inserts on incremental reindex
    │
    ├─ Step 6: Embed ──────────── bge-small-en: 384-dim (default) or jina-code: 768-dim via ONNX
    │           lazy-loaded, unloaded after indexing (try/finally)
    │           GPU/MPS auto-detected; falls back to CPU
    │
    ├─ Step 7: Store ──────────── write to LanceDB `chunks` table (12-col PyArrow schema)
    │           rebuild native FTS (Tantivy) index after write
    │
    └─ Step 8: Cleanup ────────── unload model, persist metadata (mtimes for incremental)
                                  save rustworkx graph to SQLite (warm-start recovery)

Incremental reindex: mtime-based — only changed files are re-processed. Corrupt index detection triggers automatic full rebuild.

Search Pipeline

search("how does auth work")
         │
         ├─► vector_engine.search(query, n=30)  ← cosine similarity on 768-dim embeddings
         │                                         "auth" finds "verify_credentials", "token_check"
         │
         ├─► bm25_engine.search(query, n=30)    ← Tantivy FTS on same LanceDB table
         │                                         fast exact-keyword matching
         │
         ├─► graph_engine.boost(query, n=30)    ← structural relevance score
         │                                         hub symbols (high in/out degree) boosted
         │
         └─► fusion.merge(v_results, b_results, g_results)
                  │
                  │  Reciprocal Rank Fusion: score = Σ weight_i / (k + rank_i)
                  │  default weights: vector=0.5, bm25=0.3, graph=0.2
                  │
                  ├─► reranker.rerank(top_20)   ← FlashRank (optional, 4MB ONNX model, <10ms)
                  │
                  └─► token_budget.truncate()   ← summary / detailed / full
                           │
                           └─► Top-N chunks, scored, formatted

Technology Stack

Layer

Technology

Decision Rationale

Vector store

LanceDB

mmap disk-backed → ~20–50 MB overhead vs ChromaDB's in-memory model. Native Tantivy FTS means one store for both vector and BM25. (ADR-002)

Embeddings

bge-small-en (default) or ONNX Runtime + jina-code

bge-small-en is lightweight (384-dim, no trust_remote_code). jina-code is code-specific (161M params, 8192 seq len) on ONNX (~50 MB vs PyTorch ~500 MB). Lazy-load/unload keeps RAM flat after indexing. (ADR-003)

Graph engine

rustworkx PyDiGraph

Rust-backed, O(1) node lookup, PageRank + centrality algorithms. Thread-safe with RLock. (ADR-006)

Symbol parser

tree-sitter 0.21.3

25+ languages, incremental parsing, AST-level symbol extraction with metadata. Parallel via ThreadPool. (ADR-005)

Graph parser

ast-grep

Structural pattern matching for call/import/inheritance edges. Sequential run for graph consistency. (ADR-005)

Chunking

Symbol-based

One chunk per function/class. Deterministic SHA256 IDs prevent duplicate inserts. (ADR-008)

Re-ranker

FlashRank (optional)

4 MB ONNX cross-encoder, <10 ms on CPU for top-20. Graceful passthrough if not installed.

Persistence

SQLite + LanceDB

Graph in SQLite (warm-start recovery), vectors+FTS in LanceDB, mtimes in JSON. Zero-config.

MCP framework

FastMCP 2.0

Stdio transport, automatic tool registration, schema generation.

Token Efficiency

Measured against equivalent agentic file-browsing workflows on a ~10,000-line Python codebase:

Task

Without Nexus-MCP

With Nexus-MCP

Reduction

Find relevant code (agent reads 5–10 files)

5,000–15,000 tokens

500–2,000 tokens

70–90%

Understand a symbol (grep + read + trace callers)

3,000–8,000 tokens, 3–5 calls

800–2,000 tokens, 1 call

60–75%

Assess change impact (manual transitive trace)

10,000–20,000 tokens

1,000–3,000 tokens

80–85%

Tool descriptions in context (2 MCP servers)

~1,700 tokens (17 tools)

~700 tokens (10 tools)

~60%

Search precision (keyword-only needs retries)

2–3 searches × 2,000 tokens

1 hybrid search × 1,500 tokens

60–75%

Typical session savings: 15,000–40,000 tokens (30–60%) compared to file-browsing agents.

Three Verbosity Levels

Every tool respects a verbosity parameter — agents request exactly the detail they need:

Level

Token Budget

What's Included

summary

~500 tokens

Counts, scores, file:line pointers only

detailed

~2,000 tokens

Signatures, types, line ranges, docstrings

full

~8,000 tokens

Full code snippets, all relationships, metadata

The 10 Tools

v2.0.0 breaking change: find_callers/find_callees/impact merged into graph, overview/architecture merged into map, and remember/recall/forget merged into memory — see CHANGELOG for the old→new mapping and ADR-017 for why. Fewer, richer tools route better under MCP Tool Search than many thin ones.

Discovery & Indexing

Tool

Use When

index(path)

First action in any session. Supports comma-separated multi-folder paths. Incremental by default, reports progress as it runs, and starts a debounced auto-reindex watcher (NEXUS_AUTO_WATCH) when it finishes.

status()

Check index health: symbol count, chunk count, memory usage, engine availability, and a stale/staleness_warning pair if files changed since the last index.

health()

Liveness probe — uptime, which engines are ready.

map(detail)

Replaces ls + manual browsing. detail="summary" (files/languages/quality/top-modules, was overview()), "architecture" (layers/dependencies/classes/entry points/hub symbols, was architecture()), or "full" for both.

Search

Tool

Use When

search(query, mode, language, type, n)

Primary code discovery. mode: hybrid (default), vector, or bm25. Falls back to live grep if results are sparse. Returns a non-null warning if the index looked stale (a background reindex is triggered automatically; results still return immediately).

Graph Analysis

Tool

Use When

find_symbol(name, exact)

Look up a specific symbol. exact=False for fuzzy matching.

graph(symbol, direction, transitive, max_depth)

direction="callers" (who calls this, was find_callers) or "callees" (what this calls, was find_callees). transitive=True — MUST run before any refactor (was impact()): full transitive change blast radius across the graph.

explain(symbol)

Replaces Read for understanding code. Graph relationships + semantic context + quality metrics in one call.

analyze(path)

Code quality: cyclomatic complexity, cognitive complexity, code smells, dependency metrics.

Memory

Tool

Use When

memory(action, ...)

action="store" (was remember) to persist a decision/note across sessions (types: note, decision, conversation, status, preference, doc; TTL: permanent, month, week, day, session); "search" (was recall) for semantic retrieval; "delete" (was forget) to remove by ID, tag, or type.

Install

From PyPI (recommended)

pip install nexus-mcp-ci

# GPU (CUDA) support — adds ONNX CUDA execution provider
pip install nexus-mcp-ci[gpu]

# FlashRank reranker — adds ~4MB cross-encoder for better search quality
pip install nexus-mcp-ci[reranker]

# Both
pip install nexus-mcp-ci[gpu,reranker]

From Source

git clone https://github.com/jaggernaut007/Nexus-MCP.git
cd Nexus-MCP
./setup.sh           # creates venv, installs, verifies
# or
pip install -e ".[dev]"

Python 3.10–3.12 supported. Python 3.13+ is not yet supported by the current dependency stack, and the packaged Glama/Docker build uses Python 3.12 for compatibility. Optional: rg (ripgrep) for 100% search coverage fallback on unindexed files.

The optional jina-code model requires ONNX Runtime. If you see ONNX/Optimum errors:

pip install "sentence-transformers[onnx]" "optimum[onnxruntime]>=1.19.0"

The default bge-small-en model needs neither ONNX nor trust_remote_code.

MCP Client Setup

Claude Code

# 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

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "nexus-mcp-ci": {
      "command": "nexus-mcp-ci",
      "args": [],
      "env": {
        "NEXUS_EMBEDDING_MODEL": "jina-code"
      }
    }
  }
}

Cursor / Windsurf / Cline / Any MCP Client

{
  "nexus-mcp-ci": {
    "command": "nexus-mcp-ci",
    "transport": "stdio"
  }
}

Agent Integration Patterns

CLAUDE.md boilerplate (drop into project root)

## 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__impact` to assess blast radius
5. **For project orientation**: `mcp__nexus-mcp__overview` or `mcp__nexus-mcp__architecture`

Typical agent tool-call sequence

# Session start
status()               → "indexed: True, 8,412 chunks, 1,203 symbols, 87 MB"

# Code discovery
search("JWT token validation", mode="hybrid", n=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, docstring, params, complexity
  → callers: [require_auth, login_required, api_key_check]
  → callees: [decode_jwt, check_expiry, verify_signature]
  → quality: complexity=6, smells=[], maintainability=A

# Pre-refactor safety check
impact("validate_token")
  → direct callers: 3 symbols
  → transitive impact: 12 symbols across 4 files
  → high-risk: auth/middleware.py (5 dependents)

Multi-folder monorepo indexing

# Index multiple roots in one call — processed sequentially, shared engines
index(path="packages/api/src,packages/shared/src,packages/cli/src")

# Or use the paths parameter for additional roots
index(path="packages/api/src", paths="packages/shared/src,packages/cli/src")

Configuration

All settings via NEXUS_ environment variables:

Variable

Default

Description

NEXUS_EMBEDDING_MODEL

bge-small-en

bge-small-en (384-dim, lightweight) or jina-code (768-dim, code-optimized)

NEXUS_EMBEDDING_DEVICE

auto

auto (CUDA → MPS → CPU), cuda, mps, cpu

NEXUS_STORAGE_DIR

.nexus

Index storage directory

NEXUS_AUTO_WATCH

true

Auto-reindex on file change via a debounced watcher, started after index()

NEXUS_STALENESS_CHECK_INTERVAL

15

Seconds between status()/search() staleness checks (throttled, not per-call)

NEXUS_MAX_FILE_SIZE_MB

10

Skip files larger than this

NEXUS_CHUNK_MAX_CHARS

4000

Max chars per code chunk

NEXUS_MAX_MEMORY_MB

350

Memory budget target

NEXUS_SEARCH_MODE

hybrid

hybrid, vector, or bm25

NEXUS_FUSION_WEIGHT_VECTOR

0.5

Vector score weight in RRF

NEXUS_FUSION_WEIGHT_BM25

0.3

BM25 score weight in RRF

NEXUS_FUSION_WEIGHT_GRAPH

0.2

Graph score weight in RRF

NEXUS_PERMISSION_LEVEL

full

full, read, or restricted

NEXUS_RATE_LIMIT_ENABLED

false

Enable per-tool token-bucket rate limiting

NEXUS_AUDIT_ENABLED

true

Structured audit logging with correlation IDs

NEXUS_TRUST_REMOTE_CODE

true

Required for jina-code; set false with bge-small-en

NEXUS_LOG_LEVEL

INFO

Logging level

NEXUS_LOG_FORMAT

text

text or json

Embedding Models

Model

Key

Dims

Max Seq

Backend

trust_remote_code

BGE Small EN v1.5 (default)

bge-small-en

384

512

PyTorch

No

Jina Embeddings v2 Code

jina-code

768

8,192

ONNX

Yes

After changing model, re-index. Embeddings from different models are incompatible.

Comparison

vs. Other MCP Servers

Feature

Nexus-MCP

Sourcegraph MCP

Greptile MCP

GitHub MCP

tree-sitter MCP

Fully local / private

✅

❌ infra required

❌ cloud

❌ cloud

✅

Semantic (vector) search

✅

❌ keyword only

✅ LLM-based

❌

❌

Keyword (BM25) search

✅

✅

—

✅

❌

Hybrid fusion (RRF)

✅

❌

❌

❌

❌

Code graph (call/import)

✅ rustworkx

✅ SCIP

❌

❌

❌

Re-ranking

✅ FlashRank

❌

—

❌

❌

Semantic memory (persistent)

✅ 6 types

❌

❌

❌

❌

Change impact analysis

✅

partial

❌

❌

❌

Token-budgeted responses

✅ 3 levels

❌

❌

❌

❌

Languages

25+

30+

many

many

many

Cost

Free

$$$

$40/mo

$10–39/mo

Free

API keys required

No

Yes

Yes

Yes

No

vs. AI Code Tools

Capability

Nexus-MCP

Cursor

Copilot @workspace

Cody

Continue.dev

Aider

IDE-agnostic

✅

❌

❌

❌

❌

✅

MCP-native

✅

partial

❌

❌

✅ client

❌

Fully local

✅

partial

❌

partial

✅

✅

Hybrid search

✅

unknown

unknown

keyword

yes

❌

Code graph

✅

unknown

unknown

✅ SCIP

basic

❌

Semantic memory

✅ persistent

❌

❌

❌

❌

❌

Token-budgeted output

✅

—

—

—

—

—

Open source

✅ MIT

❌

❌

partial

✅

✅

Cost

Free

$20–40/mo

$10–39/mo

$0–49/mo

Free

Free

Development

git clone https://github.com/jaggernaut007/Nexus-MCP.git
cd Nexus-MCP
pip install -e ".[dev]"

pytest -v                    # 441 tests
pytest -m "not slow"         # skip performance benchmarks
pytest tests/test_search.py  # single module
ruff check .                 # lint

Project Structure

src/nexus_mcp/
├── server.py              # FastMCP entrypoint — 10 tools, input validation, graceful shutdown
├── config.py              # Settings (NEXUS_ env prefix)
├── state.py               # Global singleton SessionState
├── core/
│   ├── models.py          # Symbol, ParsedFile, CodebaseIndex, Memory
│   ├── graph_models.py    # UniversalNode, Relationship
│   ├── interfaces.py      # IParser, IEngine protocols
│   └── exceptions.py      # NexusException hierarchy
├── parsing/
│   ├── treesitter_parser.py   # Symbol extraction (parallel)
│   ├── astgrep_parser.py      # Structural graph extraction (sequential)
│   ├── language_registry.py   # 25+ language definitions
│   └── file_watcher.py        # Debounced watchdog for live reindex
├── engines/
│   ├── vector_engine.py   # LanceDB cosine similarity search
│   ├── bm25_engine.py     # LanceDB native FTS (Tantivy)
│   ├── graph_engine.py    # rustworkx PyDiGraph with RLock
│   ├── fusion.py          # Reciprocal Rank Fusion
│   └── reranker.py        # FlashRank (optional, graceful degradation)
├── indexing/
│   ├── pipeline.py        # 8-step indexing pipeline
│   ├── embedding_service.py   # ONNX Runtime, GPU/MPS auto-detect
│   ├── parallel_indexer.py    # ThreadPool over files
│   └── chunker.py         # Symbol → CodeChunk with deterministic IDs
├── memory/
│   └── memory_store.py    # LanceDB-backed memory, TTL, 6 types
├── analysis/
│   └── code_analyzer.py   # Cyclomatic/cognitive complexity, smells
├── security/
│   ├── permissions.py     # READ/MUTATE/WRITE tool categories
│   └── rate_limiter.py    # Token-bucket, per-tool, thread-safe
└── middleware/
    └── audit.py           # Structured audit logs, correlation IDs, field redaction

Adding a New Tool

  1. Add the handler function to server.py decorated with @mcp.tool()

  2. Add inline validation (_validate_* helpers in server.py) for any new input

  3. Add permission category to security/permissions.py

  4. Write tests in tests/

  5. Update self_test/demo_mcp.py to exercise the tool

Adding a New Language

  1. Add entry to parsing/language_registry.py with the tree-sitter grammar

  2. Add structural patterns to parsing/astgrep_parser.py for call/import extraction

  3. Add test fixtures in tests/fixtures/

Self-Test

Verify your installation exercises all 10 tools end-to-end:

python self_test/demo_mcp.py                   # built-in sample project
python self_test/demo_mcp.py /path/to/project  # your own codebase

Expected output: all 10 tools exercised with pass/fail per tool and a summary.

Known Limitations

  • Sequential graph parsing: ast-grep runs sequentially (not parallel) to keep the call graph consistent. This is the main indexing bottleneck on large codebases.

  • bge-small-en uses PyTorch: The lightweight model uses PyTorch instead of ONNX, so it doesn't benefit from the same ~50 MB footprint as jina-code.

  • No incremental graph updates: Graph is rebuilt in full on incremental reindex (only vector/BM25 are incremental at the chunk level).

  • No SSE transport: Only stdio transport is currently supported.

  • Language coverage: 25+ languages, but structural relationship extraction (callers/callees) is most accurate for Python, TypeScript, JavaScript, Go, and Rust. Other languages may have partial graph edges.

  • Static call graph only: find_callers/find_callees/impact are built from static parsing, not runtime tracing — dynamic dispatch, monkey-patching, and calls made through callbacks/closures/reflection won't show up as edges. Treat impact as a lower bound on blast radius in highly dynamic code.

  • Auto-reindex has a detection lag: with the file watcher enabled (default), edits are picked up after a short debounce, and status()/search() run a throttled staleness check as a backstop — not an instant, per-call guarantee of freshness.

Architecture Decision Records

Key decisions are documented in docs/adr/:

ADR

Decision

ADR-001

Merge two MCP servers into one

ADR-002

LanceDB over ChromaDB

ADR-003

ONNX Runtime over PyTorch for embeddings

ADR-004

bge-small-en as default embedding model

ADR-005

Dual parser: tree-sitter + ast-grep

ADR-006

rustworkx for graph algorithms

ADR-007

12-column PyArrow schema for LanceDB

ADR-008

Symbol-based chunking with deterministic IDs

ADR-009

8-step indexing pipeline

ADR-010

Graph tools API: serialization, ambiguity handling

ADR-011

Graceful shutdown, corruption recovery, JSON logging

ADR-012

READ/MUTATE/WRITE permission categories

ADR-013

Pydantic v2 I/O schemas — superseded by ADR-016 (never wired in, deleted)

ADR-014

Token-bucket rate limiting (off by default)

ADR-015

Auto-watch + throttled staleness detection

ADR-016

Removal of unused Pydantic schemas (supersedes ADR-013)

ADR-017

Tool consolidation 15→10, action-aware permission categories

Documentation

Acknowledgments

Nexus-MCP consolidates two earlier open-source projects:

  • CodeGrok MCP by rdondeti (Ravitez Dondeti, MIT) — Contributed the symbol extraction pipeline, embedding service, parallel indexer, core data models, and memory retrieval system.

  • code-graph-mcp by entrepeneur4lyf — Contributed the ast-grep structural parser, rustworkx graph engine, complexity analysis, and relationship extraction.

Source files retain "Ported from" attribution in their module docstrings. See ADR-001 for the consolidation rationale.

License

MIT — see LICENSE for details.

Available Tools

7 tools
analyzeB

Use for code review or quality assessment — cyclomatic/cognitive complexity, dependency analysis, code smells (long/complex functions, large classes, dead code), and an overall quality score. Optionally scope to a subdirectory or file via path.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoOptional relative path to filter analysis (subdirectory or file)

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must disclose behavioral traits. While it lists what the tool analyzes, it does not mention that the tool is read-only and has no side effects, nor does it cover rate limits or performance impacts. The description is incomplete in this regard.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with two sentences, front-loading the purpose. The first sentence is somewhat long but efficient, and the second sentence adds the optional parameter. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists (not shown), the description covers the main analysis aspects adequately. It mentions the key components (complexity, dependencies, code smells, quality score) and the optional scope. However, it could improve by hinting at output format or interpretation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for the single parameter `path`, and the description merely echoes the schema's meaning. No additional semantics or usage details are added beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is for code review and quality assessment, listing specific analyses (complexity, dependencies, code smells, quality score). It distinguishes from siblings by its focus on code analysis, but does not explicitly differentiate from sibling tools like 'health' or 'explain'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like 'health' or 'explain'. The description only mentions optional scoping via `path`, but lacks context on prerequisites, limitations, or when to avoid using it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

explainA

Use for onboarding to an unfamiliar symbol — combines its call-graph relationships, related code found via semantic search, and quality metrics in one call, so Read is often unnecessary. Use verbosity='summary' for a quick look, 'full' when you need everything.

ParametersJSON Schema
NameRequiredDescriptionDefault
verbosityNoOutput detail level: 'summary', 'detailed', or 'full'detailed
symbol_nameYesName of the symbol to explain

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes what the tool combines (call-graph, semantic search, quality metrics) and implies it is a read operation. With no annotations provided, the description carries the full burden and does an adequate job, though it does not discuss performance or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, highly efficient, front-loading the purpose and usage. Every word earns its place with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the existence of an output schema, the description adequately covers behavior, usage, and parameter guidance. It does not explicitly differentiate from siblings like 'analyze' or 'map', but the purpose is clear enough that an agent can decide appropriately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining verbosity usage ('summary' and 'full'), but slightly mismatches the schema's default 'detailed' and misses 'detailed' in the example, causing minor confusion.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it explains an unfamiliar symbol by combining call-graph, semantic search, and quality metrics. However, it does not explicitly differentiate from listed sibling tools like 'analyze' or 'map'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('onboarding to an unfamiliar symbol') and mentions an alternative action ('so Read is often unnecessary'). Also provides guidance on verbosity levels with concrete examples.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_symbolA

Use to look up a specific function/class/symbol by name — preferred over Grep since it returns the definition plus its call-graph relationships in one call. Set exact=False for fuzzy substring matching when unsure of the exact name.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesSymbol name (e.g. 'create_server', 'TokenBudget')
exactNoTrue for exact match, False for fuzzy substring

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It reveals that the tool returns definition and call-graph relationships, but does not mention if it has side effects, rate limits, or authorization needs. It implicitly suggests read-only behavior but doesn't state it clearly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loads the purpose, and includes a key usage tip. Every sentence is necessary and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema, the description need not detail return format. It covers the core operation and key parameter variation. Sibling context shows this is a lookup tool among analysis tools, and the description adequately differentiates.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with both parameters well-described. The description adds a note about using exact=False for fuzzy matching, which complements the schema but adds limited extra semantic value beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'look up' and the resource 'specific function/class/symbol by name'. It distinguishes from Grep by mentioning it returns definition plus call-graph relationships, making it clear what the tool does uniquely.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says 'preferred over Grep' and provides guidance on setting exact=False for fuzzy matching. However, it does not explicitly state when not to use this tool or how it compares to siblings like analyze or explain.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

healthA

Use for liveness/readiness probes only (uptime, which engines are up) — not for checking whether the index is fresh or complete; use status for that.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It transparently indicates the tool is read-only and limited to uptime/engine status. However, it could mention behavior like response format or potential latency, but for a simple health probe it is sufficient. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with a dash for contrast, conveying all necessary information without waste. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, output schema exists), the description fully covers its purpose, scope, and usage context. It even references an alternative tool, making it complete for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the schema coverage is 100%. According to guidelines, baseline is 4 for 0 params. The description adds no parameter information because none is needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is for liveness/readiness probes (uptime, which engines are up) and explicitly differentiates from checking index freshness/completeness, which is handled by a sibling tool named `status`. This provides a specific verb+resource+scope and distinguishes from alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (liveness/readiness probes) and when not to use (checking index freshness or completeness), and directly suggests an alternative tool (`status`). This is exemplary guidance for an AI agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

indexA

Use first on any new or changed codebase, before any other tool — everything except status/health requires an index. Supports comma-separated paths for multi-folder/monorepo indexing (processed sequentially to keep RAM low). Incremental by default once an index exists, and reports live progress instead of blocking silently. After this completes, a file watcher keeps the index fresh automatically (NEXUS_AUTO_WATCH) — re-running index manually is rarely needed.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesAbsolute path to the codebase directory (or comma-separated paths)
pathsNoAdditional comma-separated paths to index

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses incremental default behavior, live progress reporting, sequential processing for low RAM, and automatic file watching. It could mention error handling or idempotency, but the provided details are good.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four sentences with no wasted words. The first sentence front-loads the primary purpose. Each sentence provides essential information about usage, behavior, and automation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema (not shown), the description covers key aspects: order of use, multi-path support, progress, incremental nature, and auto-watch. It could mention error scenarios or that the tool is non-destructive, but overall it is sufficient for a setup tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline 3. The description adds behavioral context: paths are processed sequentially to keep RAM low. It also reinforces the comma-separated usage. This adds meaningful value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool indexes a codebase and is the first step before using other tools, explicitly distinguishing from status/health. It also mentions supporting comma-separated paths, incremental indexing, and auto-watch.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states 'Use first on any new or changed codebase, before any other tool' and notes that re-running is rarely needed. However, it does not provide exclusions or when not to use, but the context with sibling tools is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

mapA

PREFERRED over Glob/ls/manual browsing for project understanding. Use 'summary' for a quick project orientation, 'architecture' for design/dependency structure, 'full' for both in one call.

ParametersJSON Schema
NameRequiredDescriptionDefault
detailNo'summary' (files/languages/quality/top-modules), 'architecture' (layers/dependencies/classes/entry points/hub symbols), or 'full' (both)summary

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose any behavioral traits such as side effects, auth requirements, or rate limits. It only states the tool's purpose without addressing safety or non-obvious behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences. The first sentence immediately establishes the tool's recommendation, and the second provides clear instructions on the parameter values. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has only one parameter and an output schema exists, the description covers the essential purpose and usage. It could be more complete by mentioning that the output is structural, but the output schema likely fills this gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage, fully describing the 'detail' parameter. The description adds usage context but does not introduce new semantic information beyond the schema, placing it at the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool is for 'project understanding' and contrasts with alternatives like Glob/ls/manual browsing. It specifies three modes (summary, architecture, full) with distinct purposes, making the tool's functionality unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly recommends when to use this tool over siblings and provides clear guidance on choosing detail levels. However, it does not explicitly mention when not to use it or compare with all sibling tools like 'health' or 'analyze'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

memoryA

Persist and retrieve project context across sessions. Use action='store' to save a decision/note, action='search' to find memories by semantic similarity, action='delete' to clean up by ID, tags, or type.

ParametersJSON Schema
NameRequiredDescriptionDefault
ttlNoTime-to-live for action='store': 'permanent', 'month', 'week', 'day', 'session'permanent
tagsNoComma-separated tags (all actions)
limitNoMax results (action='search', default 5)
queryNoNatural language search query (action='search')
actionYes'store' (was remember), 'search' (was recall), or 'delete' (was forget)
contentNoMemory content to store (action='store')
projectNoProject name for scoping (action='store')default
memory_idNoSpecific memory ID to delete (action='delete')
memory_typeNoType/filter, e.g. 'note', 'decision' (store: type; search/delete: filter)

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses persistence across sessions, semantic search, and deletion by various criteria. However, it lacks details on side effects (e.g., permanent deletion, rate limits, auth requirements) or behavior in edge cases, which would be helpful for a tool with multiple actions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: two sentences, no filler. The first sentence gives the overall purpose, and the second efficiently covers all three actions with their key parameters. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 9 parameters and 3 actions, the description effectively covers the primary use cases. An output schema exists (though not shown) so missing details about return values are acceptable. It could mention pagination or all-memories retrieval, but overall it is reasonably complete for a memory tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, providing baseline 3. The description adds value by grouping parameters by action context (e.g., specifying which params apply to store, search, delete), making it easier for an agent to understand which fields are relevant for each action. This goes beyond the raw schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Persist and retrieve project context across sessions.' It then enumerates three distinct actions (store, search, delete) with specific verbs and resources, making the scope unambiguous and distinguishable from sibling tools which appear unrelated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance for each action: 'Use action='store' to save a decision/note, action='search' to find memories by semantic similarity, action='delete' to clean up by ID, tags, or type.' While it does not mention when not to use the tool or alternative tools, the sibling tools are sufficiently different so no confusion arises.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 7 tool updatesv1.0.4
    • First observedanalyze
    • First observedexplain
    • First observedfind_symbol
    • First observedhealth
    • First observedindex
    • First observedmap
    • First observedmemory
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.9/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: health checks, indexing, symbol lookup, code analysis, explanation, project mapping, and memory. No overlap or ambiguity between tools.

Naming Consistency3/5

Tool names mix verb forms (analyze, explain, map) and noun forms (health, memory). 'find_symbol' uses verb_noun while others are single words, showing inconsistency in naming conventions.

Tool Count5/5

7 tools is well-scoped for a code intelligence server, covering indexing, search, analysis, mapping, and context persistence without being overwhelming or insufficient.

Completeness4/5

The tool set covers core workflows like indexing, search, analysis, and mapping. A direct file reading tool is missing, but it is architecturally replaced by explain and map, making the gap minor.

Maintenance

ActivityActive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • codesteer-atlas

    LuisCarlosLopes
    A
    license
    A
    quality
    A
    maintenance
    Local MCP server for semantic code search using Tree-sitter AST parsing, local embeddings, and hybrid search; enables indexing and querying codebases entirely offline.
    5
    MIT

  • cba

    davidgeorgehope
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for semantic code search and explanation. Allows AI agents to search, ask questions, and manage memory about a codebase with local embeddings and LLM integration.
    -

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jaggernaut007/Nexus-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server