Nexus-MCP-CI

Servidor MCP unificado: búsqueda híbrida + grafo de código + memoria semántica. 10 herramientas, <350MB de RAM, totalmente local. Sin claves API.

Ver en glama.aiPrueba este MCPPatrocinado

Documentación

de en es ja ko ru zh

Nexus-MCP

PyPI version Python 3.10–3.12 License: PolyForm Noncommercial 1.0.0 Glama MCP server

Búsqueda híbrida + grafo de código + memoria semántica en un único servidor MCP local — menos de 350 MB de RAM.

Nexus-MCP es un servidor de inteligencia de código para el Model Context Protocol. Proporciona a los agentes de IA respuestas precisas y eficientes en tokens sobre tu base de código sin dependencias en la nube: sin claves API, sin salida de datos, sin suscripciones.

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

El Problema Que Resuelve

Los agentes de codificación con IA son ineficientes en tokens por defecto. Un agente que intenta entender verify_credentials() normalmente:

Glob("src/**/*.py") → 120 archivos devueltos, el agente lee los 8 más probables → ~12,000 tokens
Grep("verify_credentials") → 3 coincidencias, el agente lee el contexto circundante → ~4,000 tokens
Read("auth/middleware.py") → archivo completo de 400 líneas para entender a los llamadores → ~3,000 tokens

Total: ~19,000 tokens, 3+ llamadas a herramientas, sin relaciones de grafo.

Con Nexus-MCP:

explain("verify_credentials") → definición del símbolo + todos los llamadores + todos los llamados + métricas de complejidad → ~1,500 tokens, 1 llamada a herramienta

O para descubrimiento:

search("credential verification flow") → top-10 de fragmentos semánticamente relevantes en toda la base de código → ~2,000 tokens, 1 llamada a herramienta

Ahorro estimado: reducción del 30–60% de tokens por sesión de codificación. Los números exactos dependen del tamaño de la base de código y del tipo de tarea — consulta la tabla de benchmarks a continuación.

Servidor MCP relacionado: embecode

Inicio rápido (60 segundos)

# 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

Luego coloca un CLAUDE.md en la raíz de tu proyecto:

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

Eso es todo. Claude indexará tu proyecto en el primer uso y usará las herramientas de Nexus-MCP automáticamente.

Cómo Funciona

Pipeline de Indexación (8 pasos)

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)

Reindexación incremental: basada en mtime — solo se reprocesan los archivos modificados. La detección de índice corrupto activa una reconstrucción completa automática.

Pipeline de Búsqueda

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

Stack Tecnológico

Capa	Tecnología	Justificación de la Decisión
Almacén de vectores	LanceDB	respaldado por mmap en disco → ~20–50 MB de sobrecarga vs el modelo en memoria de ChromaDB. El FTS nativo de Tantivy significa un solo almacén para vectores y BM25. (ADR-002)
Embeddings	bge-small-en (predeterminado) o ONNX Runtime + jina-code	bge-small-en es ligero (384-dim, sin trust_remote_code). jina-code es específico para código (161M parámetros, 8192 longitud de secuencia) en ONNX (~50 MB vs ~500 MB de PyTorch). La carga/descarga diferida mantiene la RAM plana después de la indexación. (ADR-003)
Motor de grafo	rustworkx PyDiGraph	Respaldado por Rust, búsqueda de nodos O(1), PageRank + algoritmos de centralidad. Seguro para subprocesos con RLock. (ADR-006)
Parser de símbolos	tree-sitter 0.21.3	25+ lenguajes, parsing incremental, extracción de símbolos a nivel de AST con metadatos. Paralelo vía ThreadPool. (ADR-005)
Parser de grafo	ast-grep	Coincidencia estructural de patrones para aristas de llamada/importación/herencia. Ejecución secuencial para consistencia del grafo. (ADR-005)
Fragmentación	Basada en símbolos	Un fragmento por función/clase. Los IDs SHA256 deterministas previenen inserciones duplicadas. (ADR-008)
Re-clasificador	FlashRank (opcional)	Cross-encoder ONNX de 4 MB, <10 ms en CPU para top-20. Paso directo elegante si no está instalado.
Persistencia	SQLite + LanceDB	Grafo en SQLite (recuperación de arranque en caliente), vectores+FTS en LanceDB, mtimes en JSON. Cero configuración.
Marco MCP	FastMCP 2.0	Transporte stdio, registro automático de herramientas, generación de esquemas.

Eficiencia de Tokens

Medido contra flujos de trabajo equivalentes de navegación de archivos por agentes en una base de código Python de ~10,000 líneas:

Tarea	Sin Nexus-MCP	Con Nexus-MCP	Reducción
Encontrar código relevante (el agente lee 5–10 archivos)	5,000–15,000 tokens	500–2,000 tokens	70–90%
Entender un símbolo (grep + lectura + rastreo de llamadores)	3,000–8,000 tokens, 3–5 llamadas	800–2,000 tokens, 1 llamada	60–75%
Evaluar impacto de cambios (rastreo transitivo manual)	10,000–20,000 tokens	1,000–3,000 tokens	80–85%
Descripciones de herramientas en contexto (2 servidores MCP)	~1,700 tokens (17 herramientas)	~700 tokens (10 herramientas)	~60%
Precisión de búsqueda (solo palabras clave requiere reintentos)	2–3 búsquedas × 2,000 tokens	1 búsqueda híbrida × 1,500 tokens	60–75%

Ahorro típico por sesión: 15,000–40,000 tokens (30–60%) comparado con agentes de navegación de archivos.

Tres Niveles de Verbosidad

Cada herramienta respeta un parámetro verbosity — los agentes solicitan exactamente el detalle que necesitan:

Nivel	Presupuesto de Tokens	Qué Incluye
`summary`	~500 tokens	Solo conteos, puntuaciones, punteros archivo:línea
`detailed`	~2,000 tokens	Firmas, tipos, rangos de líneas, docstrings
`full`	~8,000 tokens	Fragmentos de código completos, todas las relaciones, metadatos

Las 10 Herramientas

Cambio disruptivo v2.0.0: find_callers / find_callees / impact fusionadas en graph, overview / architecture fusionadas en map, y remember / recall / forget fusionadas en memory — consulta CHANGELOG para el mapeo antiguo→nuevo y ADR-017 para el porqué. Menos herramientas pero más ricas se enrutan mejor bajo MCP Tool Search que muchas herramientas delgadas.

Descubrimiento e Indexación

Herramienta	Cuándo Usar
`index(path)`	Primera acción en cualquier sesión. Soporta rutas multi-carpeta separadas por comas. Incremental por defecto, reporta progreso mientras se ejecuta, e inicia un observador de reindexación automática con debounce (`NEXUS_AUTO_WATCH`) cuando termina.
`status()`	Verificar salud del índice: conteo de símbolos, conteo de fragmentos, uso de memoria, disponibilidad del motor, y un par `stale` / `staleness_warning` si los archivos cambiaron desde el último índice.
`health()`	Sonda de actividad — tiempo de actividad, qué motores están listos.
`map(detail)`	Reemplaza `ls` + navegación manual. `detail="summary"` (archivos/lenguajes/calidad/módulos principales, era `overview()`), `"architecture"` (capas/dependencias/clases/puntos de entrada/símbolos centrales, era `architecture()`), o `"full"` para ambos.

Búsqueda

Herramienta	Cuándo Usar
`search(query, mode, language, type, n)`	Descubrimiento principal de código. `mode`: `hybrid` (predeterminado), `vector`, o `bm25`. Recurre a grep en vivo si los resultados son escasos. Devuelve un `warning` no nulo si el índice parecía desactualizado (se activa automáticamente una reindexación en segundo plano; los resultados aún se devuelven inmediatamente).

Análisis de Grafo

Herramienta	Cuándo Usar
`find_symbol(name, exact)`	Consultar un símbolo específico. `exact=False` para coincidencia difusa.
`graph(symbol, direction, transitive, max_depth)`	`direction="callers"` (quién llama a esto, era `find_callers`) o `"callees"` (qué llama esto, era `find_callees`). `transitive=True` — DEBE ejecutarse antes de cualquier refactorización (era `impact()`): radio de explosión completo del cambio transitivo a través del grafo.
`explain(symbol)`	Reemplaza `Read` para entender código. Relaciones de grafo + contexto semántico + métricas de calidad en una sola llamada.
`analyze(path)`	Calidad de código: complejidad ciclomática, complejidad cognitiva, olores de código, métricas de dependencias.

Memoria

Herramienta	Cuándo Usar
`memory(action, ...)`	`action="store"` (era `remember`) para persistir una decisión/nota entre sesiones (tipos: `note`, `decision`, `conversation`, `status`, `preference`, `doc`; TTL: `permanent`, `month`, `week`, `day`, `session`); `"search"` (era `recall`) para recuperación semántica; `"delete"` (era `forget`) para eliminar por ID, etiqueta o tipo.

Instalación

Desde PyPI (recomendado)

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]

Desde el Código Fuente

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 soportado. Python 3.13+ aún no es soportado por el stack de dependencias actual, y la compilación empaquetada de Glama/Docker usa Python 3.12 para compatibilidad. Opcional: rg (ripgrep) para cobertura de búsqueda 100% como respaldo en archivos no indexados.

El modelo opcional jina-code requiere ONNX Runtime. Si ves errores de ONNX/Optimum:
pip install "sentence-transformers[onnx]" "optimum[onnxruntime]>=1.19.0"
El modelo predeterminado bge-small-en no necesita ni ONNX ni trust_remote_code.

Configuración del Cliente MCP

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 / Cualquier Cliente MCP

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

Patrones de Integración con Agentes

Plantilla CLAUDE.md (colocar en la raíz del proyecto)

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

Secuencia típica de llamadas a herramientas del agente

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

Indexación de monorepo multi-carpeta

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

Configuración

Todos los ajustes mediante variables de entorno NEXUS_:

Variable	Predeterminado	Descripción
`NEXUS_EMBEDDING_MODEL`	`bge-small-en`	`bge-small-en` (384-dim, ligero) o `jina-code` (768-dim, optimizado para código)
`NEXUS_EMBEDDING_DEVICE`	`auto`	`auto` (CUDA → MPS → CPU), `cuda`, `mps`, `cpu`
`NEXUS_STORAGE_DIR`	`.nexus`	Directorio de almacenamiento del índice
`NEXUS_AUTO_WATCH`	`true`	Reindexación automática al cambiar archivos mediante un observador con debounce, iniciado después de `index()`
`NEXUS_STALENESS_CHECK_INTERVAL`	`15`	Segundos entre verificaciones de desactualización de `status()` / `search()` (limitado, no por llamada)
`NEXUS_MAX_FILE_SIZE_MB`	`10`	Omitir archivos más grandes que esto
`NEXUS_CHUNK_MAX_CHARS`	`4000`	Máximo de caracteres por fragmento de código
`NEXUS_MAX_MEMORY_MB`	`350`	Objetivo de presupuesto de memoria
`NEXUS_SEARCH_MODE`	`hybrid`	`hybrid`, `vector`, o `bm25`
`NEXUS_FUSION_WEIGHT_VECTOR`	`0.5`	Peso de puntuación de vectores en RRF
`NEXUS_FUSION_WEIGHT_BM25`	`0.3`	Peso de puntuación BM25 en RRF
`NEXUS_FUSION_WEIGHT_GRAPH`	`0.2`	Peso de puntuación de grafo en RRF
`NEXUS_PERMISSION_LEVEL`	`full`	`full`, `read`, o `restricted`
`NEXUS_RATE_LIMIT_ENABLED`	`false`	Habilitar limitación de velocidad por token-bucket por herramienta
`NEXUS_AUDIT_ENABLED`	`true`	Registro de auditoría estructurado con IDs de correlación
`NEXUS_TRUST_REMOTE_CODE`	`true`	Requerido para jina-code; establece `false` con bge-small-en
`NEXUS_LOG_LEVEL`	`INFO`	Nivel de registro
`NEXUS_LOG_FORMAT`	`text`	`text` o `json`

Modelos de Embeddings

Modelo	Clave	Dims	Máx. Secuencia	Backend	`trust_remote_code`
BGE Small EN v1.5 (predeterminado)	`bge-small-en`	384	512	PyTorch	No
Jina Embeddings v2 Code	`jina-code`	768	8,192	ONNX	Sí

Después de cambiar el modelo, re-indexa. Los embeddings de diferentes modelos son incompatibles.

Comparación

vs. Otros Servidores MCP

Característica	Nexus-MCP	Sourcegraph MCP	Greptile MCP	GitHub MCP	tree-sitter MCP
Totalmente local / privado	✅	❌ requiere infraestructura	❌ nube	❌ nube	✅
Búsqueda semántica (vectores)	✅	❌ solo palabras clave	✅ basada en LLM	❌	❌
Búsqueda por palabras clave (BM25)	✅	✅	—	✅	❌
Fusión híbrida (RRF)	✅	❌	❌	❌	❌
Grafo de código (llamada/importación)	✅ rustworkx	✅ SCIP	❌	❌	❌
Re-clasificación	✅ FlashRank	❌	—	❌	❌
Memoria semántica (persistente)	✅ 6 tipos	❌	❌	❌	❌
Análisis de impacto de cambios	✅	parcial	❌	❌	❌
Respuestas con presupuesto de tokens	✅ 3 niveles	❌	❌	❌	❌
Lenguajes	25+	30+	muchos	muchos	muchos
Costo	Licencia de pago	$$$	$40/mes	$10–39/mes	Gratis
Claves API requeridas	No	Sí	Sí	Sí	No

vs. Herramientas de IA para Código

Capacidad	Nexus-MCP	Cursor	Copilot @workspace	Cody	Continue.dev	Aider
Independiente del IDE	✅	❌	❌	❌	❌	✅
Nativo MCP	✅	parcial	❌	❌	✅ cliente	❌
Totalmente local	✅	parcial	❌	parcial	✅	✅
Búsqueda híbrida	✅	desconocido	desconocido	por palabras clave	sí	❌
Grafo de código	✅	desconocido	desconocido	✅ SCIP	básico	❌
Memoria semántica	✅ persistente	❌	❌	❌	❌	❌
Salida con presupuesto de tokens	✅	—	—	—	—	—
Código abierto	❌ todos los derechos reservados	❌	❌	parcial	✅	✅
Costo	Licencia de pago	$20–40/mes	$10–39/mes	$0–49/mes	Gratis	Gratis

Desarrollo

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

Estructura del Proyecto

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

Añadir una Nueva Herramienta

Añade la función de manejo a server.py decorada con @mcp.tool()
Añade validación en línea (ayudantes de _validate_* en server.py) para cualquier entrada nueva
Añade la categoría de permiso a security/permissions.py
Escribe pruebas en tests/
Actualiza self_test/demo_mcp.py para ejercitar la herramienta

Añadir un Nuevo Lenguaje

Añade la entrada a parsing/language_registry.py con la gramática de tree-sitter
Añade patrones estructurales a parsing/astgrep_parser.py para la extracción de llamadas/importaciones
Añade fixtures de prueba en tests/fixtures/

Autocomprobación

Verifica que tu instalación ejercita las 10 herramientas de extremo a extremo:

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

Salida esperada: las 10 herramientas ejercitadas con aprobado/fallo por herramienta y un resumen.

Limitaciones Conocidas

Análisis secuencial del grafo: ast-grep se ejecuta secuencialmente (no en paralelo) para mantener consistente el grafo de llamadas. Este es el principal cuello de botella de indexación en bases de código grandes.
bge-small-en usa PyTorch: El modelo ligero usa PyTorch en lugar de ONNX, por lo que no se beneficia de la misma huella de ~50 MB que jina-code.
Sin actualizaciones incrementales del grafo: El grafo se reconstruye por completo en la reindexación incremental (solo vector/BM25 son incrementales a nivel de fragmento).
Sin transporte SSE: Solo se admite actualmente el transporte stdio.
Cobertura de lenguajes: 25+ lenguajes, pero la extracción de relaciones estructurales (llamantes/llamados) es más precisa para Python, TypeScript, JavaScript, Go y Rust. Otros lenguajes pueden tener aristas de grafo parciales.
Grafo de llamadas estático solamente: find_callers / find_callees / impact se construyen a partir del análisis estático, no del rastreo en tiempo de ejecución — el despacho dinámico, el monkey-patching y las llamadas realizadas a través de callbacks/cierres/reflexión no aparecerán como aristas. Trata impact como un límite inferior del radio de explosión en código altamente dinámico.
La reindexación automática tiene un retraso de detección: con el observador de archivos habilitado (por defecto), los cambios se detectan después de un breve debounce, y status() / search() ejecutan una verificación de obsolescencia limitada como respaldo — no es una garantía instantánea de frescura por llamada.

Registros de Decisiones de Arquitectura

Las decisiones clave están documentadas en docs/adr/:

ADR	Decisión
ADR-001	Fusionar dos servidores MCP en uno
ADR-002	LanceDB sobre ChromaDB
ADR-003	ONNX Runtime sobre PyTorch para embeddings
ADR-004	bge-small-en como modelo de embedding por defecto
ADR-005	Analizador dual: tree-sitter + ast-grep
ADR-006	rustworkx para algoritmos de grafo
ADR-007	Esquema PyArrow de 12 columnas para LanceDB
ADR-008	Fragmentación basada en símbolos con IDs deterministas
ADR-009	Pipeline de indexación de 8 pasos
ADR-010	API de herramientas de grafo: serialización, manejo de ambigüedad
ADR-011	Apagado elegante, recuperación de corrupción, registro JSON
ADR-012	Categorías de permiso READ/MUTATE/WRITE
~~ADR-013~~	Esquemas de E/S Pydantic v2 — reemplazado por ADR-016 (nunca conectado, eliminado)
ADR-014	Limitación de velocidad con token-bucket (desactivada por defecto)
ADR-015	Observación automática + detección de obsolescencia limitada
ADR-016	Eliminación de esquemas Pydantic no utilizados (reemplaza a ADR-013)
ADR-017	Consolidación de herramientas 15→10, categorías de permiso conscientes de la acción

Documentación

Guía de Instalación — Requisitos previos, configuración específica del cliente, solución de problemas
Arquitectura — Flujo de datos, diseño de componentes, análisis del presupuesto de memoria
Guía de Uso — Referencia completa de herramientas con ejemplos
Guía del Desarrollador — Contribuciones, añadir herramientas/motores/lenguajes
Notas de Investigación — Evaluaciones de bibliotecas y análisis técnicos en profundidad

Agradecimientos

Nexus-MCP consolida dos proyectos anteriores de código abierto:

CodeGrok MCP por rdondeti (Ravitez Dondeti, MIT) — Contribuyó con el pipeline de extracción de símbolos, el servicio de embeddings, el indexador paralelo, los modelos de datos centrales y el sistema de recuperación de memoria.
code-graph-mcp por entrepeneur4lyf — Contribuyó con el analizador estructural ast-grep, el motor de grafo rustworkx, el análisis de complejidad y la extracción de relaciones.

Los archivos fuente conservan la atribución "Ported from" en sus docstrings de módulo. Consulta ADR-001 para conocer la justificación de la consolidación.

Licencia

Licencia No Comercial PolyForm 1.0.0. Libre de usar, copiar, modificar y distribuir para cualquier propósito no comercial. El uso comercial requiere una licencia separada — contacta a Shreyas Jagannath para consultar.

Las versiones publicadas antes de 2.0.1 (0.1.0, 0.1.1, 2.0.0) permanecen disponibles bajo sus términos MIT originales para quienes las obtuvieron bajo esa licencia.

Herramientas Disponibles

10 herramientas

analyze AnalyzeA

Úsala para revisión de código o evaluación de calidad — preferida sobre leer archivos manualmente para evaluar la complejidad, ya que calcula la complejidad ciclomática/cognitiva, el análisis de dependencias, los olores de código (funciones largas/complejas, clases grandes, código muerto) y una puntuación general de calidad en una sola llamada. Solo lectura; requiere un índice (ver index). Opcionalmente, limita el alcance a un subdirectorio o archivo mediante path para mantener los resultados enfocados y rápidos en bases de código grandes — omítelo para analizar toda la base de código indexada.

ParámetrosEsquema JSON

Nombre	Requerido	Descripción	Predeterminado
path	No	Ruta relativa opcional para filtrar el análisis (subdirectorio o archivo)

Esquema de Salida

ParámetrosEsquema JSON

Nombre	Requerido	Descripción
Sin parámetros de salida

TDQS

A4.5/5.0

Comportamiento4/5

Concisión5/5

Completitud5/5

Parámetros4/5

Propósito5/5

Pautas de uso4/5

explain ExplainA

Úsala para incorporarte a un símbolo desconocido — combina sus relaciones de grafo de llamadas, código relacionado encontrado mediante búsqueda semántica y métricas de calidad en una sola llamada, por lo que Read a menudo es innecesaria. Usa verbosity='summary' para una vista rápida, 'full' cuando necesites todo.

ParámetrosEsquema JSON

Nombre	Requerido	Descripción	Predeterminado
verbosity	No	Nivel de detalle de salida: 'summary', 'detailed' o 'full'	detailed
symbol_name	Sí	Nombre del símbolo a explicar

Esquema de Salida

ParámetrosEsquema JSON

Nombre	Requerido	Descripción
Sin parámetros de salida

TDQS

A4.4/5.0

Comportamiento4/5

Concisión5/5

Completitud4/5

Parámetros4/5

Propósito5/5

Pautas de uso4/5

find_symbol Find SymbolA

Úsala para buscar una función/clase/símbolo específico por nombre — preferida sobre Grep ya que devuelve la definición más sus relaciones de grafo de llamadas en una sola llamada. Establece exact=False para coincidencia difusa de subcadenas cuando no estés seguro del nombre exacto.

ParámetrosEsquema JSON

Nombre	Requerido	Descripción	Predeterminado
name	Sí	Nombre del símbolo (p. ej. 'create_server', 'TokenBudget')
exact	No	True para coincidencia exacta, False para subcadena difusa

Esquema de Salida

ParámetrosEsquema JSON

Nombre	Requerido	Descripción
Sin parámetros de salida

TDQS

A4.2/5.0

Comportamiento3/5

Concisión5/5

Completitud4/5

Parámetros4/5

Propósito5/5

Pautas de uso4/5

graph GraphA

Úsala para rastrear quién llama a una función (direction='callers'), qué llama ella (direction='callees'), o — con transitive=True — el radio de explosión transitivo completo de cambiarla. DEBES usar transitive=True antes de refactorizar o editar un símbolo ampliamente compartido; grep no puede mostrar el impacto transitivo.

ParámetrosEsquema JSON

Nombre	Requerido	Descripción	Predeterminado
direction	No	'callers' (quién llama a esto) o 'callees' (qué llama esto)	callers
max_depth	No	Profundidad máxima de recorrido cuando transitive=True (predeterminado 10)
transitive	No	True = cierre transitivo completo para análisis de impacto de cambios (DEBES usarlo antes de refactorizar un símbolo compartido). Solo válido con direction='callers'.
symbol_name	Sí	Nombre de la función/símbolo a rastrear

Esquema de Salida

ParámetrosEsquema JSON

Nombre	Requerido	Descripción
Sin parámetros de salida

TDQS

A4.7/5.0

Comportamiento4/5

Concisión5/5

Completitud5/5

Parámetros4/5

Propósito5/5

Pautas de uso5/5

health HealthA

Úsala solo para sondas de actividad/disponibilidad (tiempo de actividad, qué motores están activos) — no para verificar si el índice está fresco o completo; usa status para eso.

ParámetrosEsquema JSON

Nombre	Requerido	Descripción	Predeterminado
Sin parámetros

Esquema de Salida

ParámetrosEsquema JSON

Nombre	Requerido	Descripción
Sin parámetros de salida

TDQS

A4.7/5.0

Comportamiento4/5

Concisión5/5

Completitud5/5

Parámetros4/5

Propósito5/5

Pautas de uso5/5

index IndexA

Úsala primero en cualquier base de código nueva o modificada, antes que cualquier otra herramienta — todo excepto status / health requiere un índice. Admite rutas separadas por comas para indexación de múltiples carpetas/monorepo (procesadas secuencialmente para mantener baja la RAM). Incremental por defecto una vez que existe un índice, e informa el progreso en vivo en lugar de bloquear silenciosamente. Después de que esto se complete, un observador de archivos mantiene el índice fresco automáticamente (NEXUS_AUTO_WATCH) — volver a ejecutar index manualmente rara vez es necesario.

ParámetrosEsquema JSON

Nombre	Requerido	Descripción	Predeterminado
path	Sí	Ruta absoluta al directorio de la base de código (o rutas separadas por comas)
paths	No	Rutas adicionales separadas por comas para indexar

Esquema de Salida

ParámetrosEsquema JSON

Nombre	Requerido	Descripción
Sin parámetros de salida

TDQS

A4.7/5.0

Comportamiento5/5

Concisión5/5

Completitud5/5

Parámetros3/5

Propósito5/5

Pautas de uso5/5

map MapA

PREFERIDA sobre Glob/ls/navegación manual para comprender el proyecto. Usa 'summary' para una orientación rápida del proyecto, 'architecture' para la estructura de diseño/dependencias, 'full' para ambas en una sola llamada.

ParámetrosEsquema JSON

Nombre	Requerido	Descripción	Predeterminado
detail	No	'summary' (archivos/lenguajes/calidad/módulos principales), 'architecture' (capas/dependencias/clases/puntos de entrada/símbolos centrales) o 'full' (ambos)	summary

Esquema de Salida

ParámetrosEsquema JSON

Nombre	Requerido	Descripción
Sin parámetros de salida

TDQS

A4.1/5.0

Comportamiento3/5

Concisión5/5

Completitud4/5

Parámetros4/5

Propósito4/5

Pautas de uso5/5

memory MemoryA

Persiste y recupera el contexto del proyecto entre sesiones. Usa action='store' para guardar una decisión/nota, action='search' para encontrar memorias por similitud semántica, action='delete' para limpiar por ID, etiquetas o tipo.

ParámetrosEsquema JSON

Nombre	Requerido	Descripción	Predeterminado
ttl	No	Tiempo de vida para action='store': 'permanent', 'month', 'week', 'day', 'session'	permanent
tags	No	Etiquetas separadas por comas (todas las acciones)
limit	No	Máximo de resultados (action='search', predeterminado 5)
query	No	Consulta de búsqueda en lenguaje natural (action='search')
action	Sí	'store' (antes remember), 'search' (antes recall), o 'delete' (antes forget)
content	No	Contenido de memoria a almacenar (action='store')
project	No	Nombre del proyecto para el alcance (action='store')	default
memory_id	No	ID de memoria específico a eliminar (action='delete')
memory_type	No	Tipo/filtro, p. ej. 'note', 'decision' (store: tipo; search/delete: filtro)

Esquema de Salida

ParámetrosEsquema JSON

Nombre	Requerido	Descripción
Sin parámetros de salida

TDQS

A4.2/5.0

Comportamiento4/5

Concisión5/5

Completitud4/5

Parámetros3/5

Propósito5/5

Pautas de uso4/5

search SearchA

Úsalo para cualquier pregunta de código tipo "dónde está/cómo funciona/encuentra" — preferido sobre Grep/Glob, y generalmente respondible desde el code_snippet devuelto sin una lectura de seguimiento. Vuelve automáticamente a grep en vivo cuando los resultados híbridos son escasos. Devuelve un warning no nulo si el índice parecía desactualizado (se activa un reindexado en segundo plano; los resultados aún se devuelven de inmediato).

ParámetrosEsquema JSON

Nombre	Requerido	Descripción	Predeterminado
mode	No	Modo de búsqueda: 'hybrid', 'vector', o 'bm25'	hybrid
limit	No	Máximo de resultados (predeterminado 10, máximo 100)
query	Sí	Consulta en lenguaje natural o código (p. ej. 'retry logic')
rerank	No	Reordenamiento FlashRank (predeterminado True)
language	No	Filtrar por idioma (p. ej. 'python')
live_grep	No	Forzar respaldo de grep en vivo (rg/grep)
symbol_type	No	Filtrar por tipo (p. ej. 'function', 'class')

Esquema de Salida

ParámetrosEsquema JSON

Nombre	Requerido	Descripción
Sin parámetros de salida

TDQS

A4.2/5.0

Comportamiento4/5

Concisión5/5

Completitud4/5

Parámetros3/5

Propósito5/5

Pautas de uso4/5

status StatusA

Úsalo al inicio de una sesión, o cuando no estés seguro de si los resultados de búsqueda podrían estar desactualizados. Informa si una base de código está indexada, tamaño del índice/disponibilidad del motor, uso de memoria, y un par stale/staleness_warning si los archivos cambiaron desde el último índice (se activa automáticamente un reindexado en segundo plano).

ParámetrosEsquema JSON

Nombre	Requerido	Descripción
Sin parámetros

Esquema de Salida

ParámetrosEsquema JSON

Nombre	Requerido	Descripción
Sin parámetros de salida

TDQS

A4.5/5.0

Comportamiento4/5

Concisión5/5

Completitud5/5

Parámetros4/5

Propósito5/5

Pautas de uso4/5

Registro de Cambios del Esquema de Herramientas

Adiciones, eliminaciones y cambios de esquema recientes de herramientas observados durante inspecciones MCP exitosas.

3 actualizaciones de herramientas 18 sep 2026
7 actualizaciones de herramientas v1.0.4 23 jul 2026

TDQS

A4.4/5.0

Puntuado en 10 herramientas

Desambiguación5/5

Consistencia de nombres4/5

Cantidad de herramientas5/5

Completitud4/5

Mantenimiento

ActividadMantenido

Capacidad de respuestaSin respuesta