Nexus-MCP-CI

Servidor MCP unificado: busca híbrida + grafo de código + memória semântica. 10 ferramentas, <350MB de RAM, totalmente local. Sem chaves de API.

Ver em glama.aiExperimente este MCPPatrocinado

Documentação

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

Busca híbrida + grafo de código + memória semântica em um único servidor MCP local — com menos de 350 MB de RAM.

O Nexus-MCP é um servidor de inteligência de código para o Model Context Protocol. Ele fornece a agentes de IA respostas precisas e eficientes em tokens sobre seu código, sem dependências de nuvem: sem chaves de API, sem egresso de dados, sem assinaturas.

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

O Problema que Ele Resolve

Agentes de IA de codificação são ineficientes em tokens por padrão. Um agente tentando entender verify_credentials() normalmente:

Glob("src/**/*.py") → 120 arquivos retornados, o agente lê os 8 mais prováveis → ~12.000 tokens
Grep("verify_credentials") → 3 correspondências, o agente lê o contexto ao redor → ~4.000 tokens
Read("auth/middleware.py") → arquivo completo de 400 linhas para entender os chamadores → ~3.000 tokens

Total: ~19.000 tokens, 3+ chamadas de ferramenta, sem relações de grafo.

Com o Nexus-MCP:

explain("verify_credentials") → definição do símbolo + todos os chamadores + todos os chamados + métricas de complexidade → ~1.500 tokens, 1 chamada de ferramenta

Ou para descoberta:

search("credential verification flow") → top-10 trechos semanticamente relevantes em todo o código → ~2.000 tokens, 1 chamada de ferramenta

Economia estimada: redução de 30–60% em tokens por sessão de codificação. Os números exatos dependem do tamanho do código e do tipo de tarefa — veja a tabela de benchmarks abaixo.

Servidor MCP relacionado: embecode

Início 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

Em seguida, coloque um CLAUDE.md na raiz do seu projeto:

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

É isso. O Claude indexará seu projeto no primeiro uso e usará as ferramentas do Nexus-MCP automaticamente.

Como Funciona

Pipeline de Indexação (8 etapas)

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)

Reindexação incremental: baseada em mtime — apenas arquivos alterados são reprocessados. A detecção de índice corrompido aciona uma reconstrução completa automática.

Pipeline de Busca

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

Pilha de Tecnologia

Camada	Tecnologia	Justificativa da Decisão
Armazenamento de vetores	LanceDB	mmap com suporte a disco → ~20–50 MB de overhead vs. modelo em memória do ChromaDB. FTS nativo Tantivy significa um único armazenamento para vetores e BM25. (ADR-002)
Embeddings	bge-small-en (padrão) ou ONNX Runtime + jina-code	bge-small-en é leve (384-dim, sem trust_remote_code). jina-code é específico para código (161M parâmetros, 8192 seq len) em ONNX (~50 MB vs. PyTorch ~500 MB). Carregamento/descarregamento preguiçoso mantém a RAM estável após a indexação. (ADR-003)
Mecanismo de grafo	rustworkx PyDiGraph	Com suporte Rust, busca de nó O(1), algoritmos de PageRank + centralidade. Thread-safe com RLock. (ADR-006)
Parser de símbolos	tree-sitter 0.21.3	25+ linguagens, parsing incremental, extração de símbolos em nível de AST com metadados. Paralelo via ThreadPool. (ADR-005)
Parser de grafo	ast-grep	Correspondência estrutural de padrões para arestas de chamada/importação/herança. Execução sequencial para consistência do grafo. (ADR-005)
Chunking	Baseado em símbolos	Um chunk por função/classe. IDs SHA256 determinísticos evitam inserções duplicadas. (ADR-008)
Re-ranker	FlashRank (opcional)	Cross-encoder ONNX de 4 MB, <10 ms em CPU para top-20. Passthrough gracioso se não estiver instalado.
Persistência	SQLite + LanceDB	Grafo em SQLite (recuperação de warm-start), vetores+FTS em LanceDB, mtimes em JSON. Zero configuração.
Framework MCP	FastMCP 2.0	Transporte stdio, registro automático de ferramentas, geração de esquemas.

Eficiência de Tokens

Medido contra fluxos de trabalho equivalentes de navegação de arquivos por agentes em um código Python de ~10.000 linhas:

Tarefa	Sem Nexus-MCP	Com Nexus-MCP	Redução
Encontrar código relevante (agente lê 5–10 arquivos)	5.000–15.000 tokens	500–2.000 tokens	70–90%
Entender um símbolo (grep + leitura + rastrear chamadores)	3.000–8.000 tokens, 3–5 chamadas	800–2.000 tokens, 1 chamada	60–75%
Avaliar impacto de mudança (rastreio transitivo manual)	10.000–20.000 tokens	1.000–3.000 tokens	80–85%
Descrições de ferramentas no contexto (2 servidores MCP)	~1.700 tokens (17 ferramentas)	~700 tokens (10 ferramentas)	~60%
Precisão de busca (somente palavras-chave exige novas tentativas)	2–3 buscas × 2.000 tokens	1 busca híbrida × 1.500 tokens	60–75%

Economia típica por sessão: 15.000–40.000 tokens (30–60%) em comparação com agentes de navegação de arquivos.

Três Níveis de Verbosidade

Cada ferramenta respeita um parâmetro verbosity — os agentes solicitam exatamente o nível de detalhe que precisam:

Nível	Orçamento de Tokens	O que Está Incluído
`summary`	~500 tokens	Apenas contagens, pontuações, ponteiros arquivo:linha
`detailed`	~2.000 tokens	Assinaturas, tipos, intervalos de linha, docstrings
`full`	~8.000 tokens	Trechos de código completos, todas as relações, metadados

As 10 Ferramentas

Mudança de quebra na v2.0.0: find_callers / find_callees / impact mescladas em graph, overview / architecture mescladas em map, e remember / recall / forget mescladas em memory — veja CHANGELOG para o mapeamento antigo→novo e ADR-017 para o motivo. Ferramentas menos numerosas e mais ricas roteiam melhor sob o MCP Tool Search do que muitas ferramentas finas.

Descoberta e Indexação

Ferramenta	Use Quando
`index(path)`	Primeira ação em qualquer sessão. Suporta caminhos de múltiplas pastas separados por vírgula. Incremental por padrão, relata progresso enquanto executa e inicia um observador de reindexação automática com debounce (`NEXUS_AUTO_WATCH`) ao terminar.
`status()`	Verifique a saúde do índice: contagem de símbolos, contagem de chunks, uso de memória, disponibilidade do mecanismo e um par `stale` / `staleness_warning` se os arquivos mudaram desde o último índice.
`health()`	Sonda de atividade — tempo de atividade, quais mecanismos estão prontos.
`map(detail)`	Substitui `ls` + navegação manual. `detail="summary"` (arquivos/linguagens/qualidade/módulos principais, era `overview()`), `"architecture"` (camadas/dependências/classes/pontos de entrada/símbolos de hub, era `architecture()`), ou `"full"` para ambos.

Busca

Ferramenta	Use Quando
`search(query, mode, language, type, n)`	Descoberta primária de código. `mode`: `hybrid` (padrão), `vector`, ou `bm25`. Recorre a grep ao vivo se os resultados forem escassos. Retorna um `warning` não nulo se o índice parecer desatualizado (uma reindexação em segundo plano é acionada automaticamente; os resultados ainda retornam imediatamente).

Análise de Grafo

Ferramenta	Use Quando
`find_symbol(name, exact)`	Consulte um símbolo específico. `exact=False` para correspondência difusa.
`graph(symbol, direction, transitive, max_depth)`	`direction="callers"` (quem chama isso, era `find_callers`) ou `"callees"` (o que isso chama, era `find_callees`). `transitive=True` — DEVE ser executado antes de qualquer refatoração (era `impact()`): raio de impacto transitivo completo de mudanças em todo o grafo.
`explain(symbol)`	Substitui `Read` para entender código. Relações de grafo + contexto semântico + métricas de qualidade em uma única chamada.
`analyze(path)`	Qualidade de código: complexidade ciclomática, complexidade cognitiva, code smells, métricas de dependência.

Memória

Ferramenta	Use Quando
`memory(action, ...)`	`action="store"` (era `remember`) para persistir uma decisão/nota entre sessões (tipos: `note`, `decision`, `conversation`, `status`, `preference`, `doc`; TTL: `permanent`, `month`, `week`, `day`, `session`); `"search"` (era `recall`) para recuperação semântica; `"delete"` (era `forget`) para remover por ID, tag ou tipo.

Instalação

Do 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]

Do Código-Fonte

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 suportado. Python 3.13+ ainda não é suportado pela pilha de dependências atual, e o build empacotado Glama/Docker usa Python 3.12 para compatibilidade. Opcional: rg (ripgrep) para cobertura de busca 100% em arquivos não indexados.

O modelo opcional jina-code requer ONNX Runtime. Se você vir erros de ONNX/Optimum:
pip install "sentence-transformers[onnx]" "optimum[onnxruntime]>=1.19.0"
O modelo padrão bge-small-en não precisa de ONNX nem de trust_remote_code.

Configuração do 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 / Qualquer Cliente MCP

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

Padrões de Integração com Agentes

Boilerplate CLAUDE.md (coloque na raiz do projeto)

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

Sequência típica de chamadas de ferramentas do 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)

Indexação de monorepo com múltiplas pastas

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

Configuração

Todas as configurações via variáveis de ambiente NEXUS_:

Variável	Padrão	Descrição
`NEXUS_EMBEDDING_MODEL`	`bge-small-en`	`bge-small-en` (384-dim, leve) ou `jina-code` (768-dim, otimizado para código)
`NEXUS_EMBEDDING_DEVICE`	`auto`	`auto` (CUDA → MPS → CPU), `cuda`, `mps`, `cpu`
`NEXUS_STORAGE_DIR`	`.nexus`	Diretório de armazenamento do índice
`NEXUS_AUTO_WATCH`	`true`	Reindexação automática em mudança de arquivo via observador com debounce, iniciado após `index()`
`NEXUS_STALENESS_CHECK_INTERVAL`	`15`	Segundos entre verificações de desatualização de `status()` / `search()` (limitado, não por chamada)
`NEXUS_MAX_FILE_SIZE_MB`	`10`	Ignorar arquivos maiores que isso
`NEXUS_CHUNK_MAX_CHARS`	`4000`	Máx. de caracteres por chunk de código
`NEXUS_MAX_MEMORY_MB`	`350`	Meta de orçamento de memória
`NEXUS_SEARCH_MODE`	`hybrid`	`hybrid`, `vector`, ou `bm25`
`NEXUS_FUSION_WEIGHT_VECTOR`	`0.5`	Peso da pontuação de vetor no RRF
`NEXUS_FUSION_WEIGHT_BM25`	`0.3`	Peso da pontuação BM25 no RRF
`NEXUS_FUSION_WEIGHT_GRAPH`	`0.2`	Peso da pontuação de grafo no RRF
`NEXUS_PERMISSION_LEVEL`	`full`	`full`, `read`, ou `restricted`
`NEXUS_RATE_LIMIT_ENABLED`	`false`	Ativar limitação de taxa por token-bucket por ferramenta
`NEXUS_AUDIT_ENABLED`	`true`	Logging de auditoria estruturado com IDs de correlação
`NEXUS_TRUST_REMOTE_CODE`	`true`	Necessário para jina-code; defina `false` com bge-small-en
`NEXUS_LOG_LEVEL`	`INFO`	Nível de logging
`NEXUS_LOG_FORMAT`	`text`	`text` ou `json`

Modelos de Embedding

Modelo	Chave	Dims	Seq Máx	Backend	`trust_remote_code`
BGE Small EN v1.5 (padrão)	`bge-small-en`	384	512	PyTorch	Não
Jina Embeddings v2 Code	`jina-code`	768	8.192	ONNX	Sim

Após alterar o modelo, re-indexe. Embeddings de modelos diferentes são incompatíveis.

Comparação

vs. Outros Servidores MCP

Recurso	Nexus-MCP	Sourcegraph MCP	Greptile MCP	GitHub MCP	tree-sitter MCP
Totalmente local / privado	✅	❌ infra necessária	❌ nuvem	❌ nuvem	✅
Busca semântica (vetor)	✅	❌ somente palavras-chave	✅ baseada em LLM	❌	❌
Busca por palavras-chave (BM25)	✅	✅	—	✅	❌
Fusão híbrida (RRF)	✅	❌	❌	❌	❌
Grafo de código (chamada/importação)	✅ rustworkx	✅ SCIP	❌	❌	❌
Re-ranking	✅ FlashRank	❌	—	❌	❌
Memória semântica (persistente)	✅ 6 tipos	❌	❌	❌	❌
Análise de impacto de mudança	✅	parcial	❌	❌	❌
Respostas com orçamento de tokens	✅ 3 níveis	❌	❌	❌	❌
Linguagens	25+	30+	muitas	muitas	muitas
Custo	Licença paga	$$$	$40/mês	$10–39/mês	Grátis
Chaves de API necessárias	Não	Sim	Sim	Sim	Não

vs. Ferramentas de IA para Código

Capacidade	Nexus-MCP	Cursor	Copilot @workspace	Cody	Continue.dev	Aider
Independente de IDE	✅	❌	❌	❌	❌	✅
Nativo MCP	✅	parcial	❌	❌	✅ cliente	❌
Totalmente local	✅	parcial	❌	parcial	✅	✅
Busca híbrida	✅	desconhecido	desconhecido	palavra-chave	sim	❌
Grafo de código	✅	desconhecido	desconhecido	✅ SCIP	básico	❌
Memória semântica	✅ persistente	❌	❌	❌	❌	❌
Saída com orçamento de tokens	✅	—	—	—	—	—
Código aberto	❌ todos os direitos reservados	❌	❌	parcial	✅	✅
Custo	Licença paga	$20–40/mês	$10–39/mês	$0–49/mês	Gratuito	Gratuito

Desenvolvimento

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

Estrutura do Projeto

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

Adicionando uma Nova Ferramenta

Adicione a função de manipulador em server.py decorada com @mcp.tool()
Adicione validação inline (auxiliares _validate_* em server.py) para qualquer nova entrada
Adicione a categoria de permissão em security/permissions.py
Escreva testes em tests/
Atualize self_test/demo_mcp.py para exercitar a ferramenta

Adicionando um Novo Idioma

Adicione a entrada em parsing/language_registry.py com a gramática tree-sitter
Adicione padrões estruturais em parsing/astgrep_parser.py para extração de chamadas/importações
Adicione fixtures de teste em tests/fixtures/

Autoteste

Verifique se sua instalação exercita todas as 10 ferramentas de ponta a ponta:

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

Saída esperada: todas as 10 ferramentas exercitadas com aprovação/reprovação por ferramenta e um resumo.

Limitações Conhecidas

Análise sequencial de grafos: ast-grep é executado sequencialmente (não em paralelo) para manter o grafo de chamadas consistente. Este é o principal gargalo de indexação em bases de código grandes.
bge-small-en usa PyTorch: O modelo leve usa PyTorch em vez de ONNX, portanto não se beneficia da mesma pegada de ~50 MB que o jina-code.
Sem atualizações incrementais de grafo: O grafo é reconstruído por completo na reindexação incremental (apenas vetor/BM25 são incrementais no nível de chunk).
Sem transporte SSE: Apenas o transporte stdio é suportado atualmente.
Cobertura de idiomas: 25+ idiomas, mas a extração de relacionamentos estruturais (chamadores/callees) é mais precisa para Python, TypeScript, JavaScript, Go e Rust. Outros idiomas podem ter arestas de grafo parciais.
Grafo de chamadas estático apenas: find_callers / find_callees / impact são construídos a partir de análise estática, não de rastreamento em tempo de execução — despacho dinâmico, monkey-patching e chamadas feitas por meio de callbacks/closures/reflexão não aparecerão como arestas. Trate impact como um limite inferior do raio de explosão em código altamente dinâmico.
A reindexação automática tem atraso de detecção: com o observador de arquivos habilitado (padrão), as edições são capturadas após um debounce curto, e status() / search() executam uma verificação de obsolescência limitada como rede de segurança — não uma garantia instantânea de frescor por chamada.

Registros de Decisões de Arquitetura

Decisões-chave estão documentadas em docs/adr/:

ADR	Decisão
ADR-001	Mesclar dois servidores MCP em um
ADR-002	LanceDB em vez de ChromaDB
ADR-003	ONNX Runtime em vez de PyTorch para embeddings
ADR-004	bge-small-en como modelo de embedding padrão
ADR-005	Analisador duplo: tree-sitter + ast-grep
ADR-006	rustworkx para algoritmos de grafo
ADR-007	Esquema PyArrow de 12 colunas para LanceDB
ADR-008	Chunking baseado em símbolos com IDs determinísticos
ADR-009	Pipeline de indexação em 8 etapas
ADR-010	API de ferramentas de grafo: serialização, tratamento de ambiguidade
ADR-011	Desligamento gracioso, recuperação de corrupção, registro JSON
ADR-012	Categorias de permissão READ/MUTATE/WRITE
~~ADR-013~~	Esquemas de I/O Pydantic v2 — substituído por ADR-016 (nunca conectado, excluído)
ADR-014	Limitação de taxa com token bucket (desativado por padrão)
ADR-015	Observação automática + detecção de obsolescência limitada
ADR-016	Remoção de esquemas Pydantic não utilizados (substitui ADR-013)
ADR-017	Consolidação de ferramentas 15→10, categorias de permissão sensíveis à ação

Documentação

Guia de Instalação — Pré-requisitos, configuração específica do cliente, solução de problemas
Arquitetura — Fluxo de dados, design de componentes, análise de orçamento de memória
Guia de Uso — Referência completa de ferramentas com exemplos
Guia do Desenvolvedor — Contribuição, adição de ferramentas/mecanismos/idiomas
Notas de Pesquisa — Avaliações de bibliotecas e mergulhos profundos em tecnologia

Agradecimentos

Nexus-MCP consolida dois projetos anteriores de código aberto:

CodeGrok MCP por rdondeti (Ravitez Dondeti, MIT) — Contribuiu com o pipeline de extração de símbolos, serviço de embeddings, indexador paralelo, modelos de dados principais e sistema de recuperação de memória.
code-graph-mcp por entrepeneur4lyf — Contribuiu com o analisador estrutural ast-grep, mecanismo de grafo rustworkx, análise de complexidade e extração de relacionamentos.

Os arquivos-fonte mantêm a atribuição "Ported from" em seus docstrings de módulo. Consulte ADR-001 para a justificativa da consolidação.

Licença

Licença PolyForm Noncommercial 1.0.0. Livre para usar, copiar, modificar e distribuir para qualquer finalidade não comercial. Uso comercial requer uma licença separada — entre em contato com Shreyas Jagannath para consultar.

Versões publicadas antes de 2.0.1 (0.1.0, 0.1.1, 2.0.0) permanecem disponíveis sob seus termos MIT originais para qualquer pessoa que as obteve sob essa licença.

Ferramentas Disponíveis

10 ferramentas

analyze AnalyzeA

Use para revisão de código ou avaliação de qualidade — preferível a ler arquivos manualmente para avaliar complexidade, pois calcula complexidade ciclomática/cognitiva, análise de dependências, code smells (funções longas/complexas, classes grandes, código morto) e uma pontuação geral de qualidade em uma única chamada. Somente leitura; requer um índice (consulte index). Opcionalmente, escopo para um subdiretório ou arquivo via path para manter os resultados focados e rápidos em bases de código grandes — omita para analisar toda a base de código indexada.

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição	Padrão
path	Não	Caminho relativo opcional para filtrar a análise (subdiretório ou arquivo)

Esquema de Saída

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição
Sem parâmetros de saída

TDQS

A4.5/5.0

Comportamento4/5

Concisão5/5

Completude5/5

Parâmetros4/5

Propósito5/5

Diretrizes de Uso4/5

explain ExplainA

Use para integração com um símbolo desconhecido — combina suas relações de grafo de chamadas, código relacionado encontrado via busca semântica e métricas de qualidade em uma única chamada, então Read geralmente é desnecessário. Use verbosity='summary' para uma visão rápida, 'full' quando precisar de tudo.

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição	Padrão
verbosity	Não	Nível de detalhe da saída: 'summary', 'detailed' ou 'full'	detailed
symbol_name	Sim	Nome do símbolo a explicar

Esquema de Saída

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição
Sem parâmetros de saída

TDQS

A4.4/5.0

Comportamento4/5

Concisão5/5

Completude4/5

Parâmetros4/5

Propósito5/5

Diretrizes de Uso4/5

find_symbol Find SymbolA

Use para consultar uma função/classe/símbolo específico pelo nome — preferível ao Grep, pois retorna a definição mais suas relações de grafo de chamadas em uma única chamada. Defina exact=False para correspondência difusa de substring quando não tiver certeza do nome exato.

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição	Padrão
name	Sim	Nome do símbolo (ex.: 'create_server', 'TokenBudget')
exact	Não	True para correspondência exata, False para substring difusa

Esquema de Saída

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição
Sem parâmetros de saída

TDQS

A4.2/5.0

Comportamento3/5

Concisão5/5

Completude4/5

Parâmetros4/5

Propósito5/5

Diretrizes de Uso4/5

graph GraphA

Use para rastrear quem chama uma função (direction='callers'), o que ela chama (direction='callees') ou — com transitive=True — o raio de explosão transitivo completo de alterá-la. DEVE usar transitive=True antes de refatorar ou editar um símbolo amplamente compartilhado; grep não pode mostrar impacto transitivo.

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição	Padrão
direction	Não	'callers' (quem chama isso) ou 'callees' (o que isso chama)	callers
max_depth	Não	Profundidade máxima de travessia quando transitive=True (padrão 10)
transitive	Não	True = fechamento transitivo completo para análise de impacto de mudança (DEVE usar antes de refatorar um símbolo compartilhado). Válido apenas com direction='callers'.
symbol_name	Sim	Nome da função/símbolo a rastrear

Esquema de Saída

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição
Sem parâmetros de saída

TDQS

A4.7/5.0

Comportamento4/5

Concisão5/5

Completude5/5

Parâmetros4/5

Propósito5/5

Diretrizes de Uso5/5

health HealthA

Use apenas para sondas de liveness/readiness (tempo de atividade, quais mecanismos estão ativos) — não para verificar se o índice está atualizado ou completo; use status para isso.

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição	Padrão
Sem parâmetros

Esquema de Saída

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição
Sem parâmetros de saída

TDQS

A4.7/5.0

Comportamento4/5

Concisão5/5

Completude5/5

Parâmetros4/5

Propósito5/5

Diretrizes de Uso5/5

index IndexA

Use primeiro em qualquer base de código nova ou alterada, antes de qualquer outra ferramenta — tudo exceto status / health requer um índice. Suporta caminhos separados por vírgula para indexação de múltiplas pastas/monorepo (processados sequencialmente para manter a RAM baixa). Incremental por padrão uma vez que um índice existe, e relata progresso ao vivo em vez de bloquear silenciosamente. Após a conclusão, um observador de arquivos mantém o índice atualizado automaticamente (NEXUS_AUTO_WATCH) — executar index manualmente raramente é necessário.

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição	Padrão
path	Sim	Caminho absoluto para o diretório da base de código (ou caminhos separados por vírgula)
paths	Não	Caminhos adicionais separados por vírgula para indexar

Esquema de Saída

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição
Sem parâmetros de saída

TDQS

A4.7/5.0

Comportamento5/5

Concisão5/5

Completude5/5

Parâmetros3/5

Propósito5/5

Diretrizes de Uso5/5

map MapA

PREFERIDO em vez de Glob/ls/navegação manual para entendimento do projeto. Use 'summary' para uma orientação rápida do projeto, 'architecture' para estrutura de design/dependências, 'full' para ambos em uma única chamada.

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição	Padrão
detail	Não	'summary' (arquivos/idiomas/qualidade/módulos principais), 'architecture' (camadas/dependências/classes/pontos de entrada/símbolos hub) ou 'full' (ambos)	summary

Esquema de Saída

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição
Sem parâmetros de saída

TDQS

A4.1/5.0

Comportamento3/5

Concisão5/5

Completude4/5

Parâmetros4/5

Propósito4/5

Diretrizes de Uso5/5

memory MemoryA

Persista e recupere contexto do projeto entre sessões. Use action='store' para salvar uma decisão/nota, action='search' para encontrar memórias por similaridade semântica, action='delete' para limpar por ID, tags ou tipo.

ParâmetrosEsquema JSON

Nome	Obrigatório	Descrição	Padrão
ttl	Não	Tempo de vida para action='store': 'permanent', 'month', 'week', 'day', 'session'	permanent
tags	Não	Tags separadas por vírgula (todas as ações)
limit	Não	Máximo de resultados (action='search', padrão 5)
query	Não	Consulta de busca em linguagem natural (action='search')
action	Sim	'store' (era remember), 'search' (era recall) ou 'delete' (era forget)
content	Não	Conteúdo de memória a armazenar (action='store')
project	Não	Nome do projeto para escopo (action='store')	default
memory_id	Não	ID específico de memória a excluir (action='delete')
memory_type	Não	Tipo/filtro, ex.: 'note', 'decision' (store: tipo; search/delete: filtro)

Esquema de Saída

ParâmetrosJSON Schema

Nome	Obrigatório	Descrição
Sem parâmetros de saída

TDQS

A4.2/5.0

Comportamento4/5

Concisão5/5

Completude4/5

Parâmetros3/5

Propósito5/5

Diretrizes de Uso4/5

search SearchA

Use para qualquer pergunta de código do tipo "onde está/como funciona/encontre" — preferível em relação a Grep/Glob, e geralmente respondível a partir do code_snippet retornado sem um Read de acompanhamento. Faz fallback automaticamente para grep ao vivo quando os resultados híbridos são escassos. Retorna um warning não nulo se o índice parecer desatualizado (um reindex em segundo plano é acionado; os resultados ainda retornam imediatamente).

ParâmetrosJSON Schema

Nome	Obrigatório	Descrição	Padrão
mode	Não	Modo de busca: 'hybrid', 'vector' ou 'bm25'	hybrid
limit	Não	Máximo de resultados (padrão 10, máximo 100)
query	Sim	Consulta em linguagem natural ou código (ex.: 'retry logic')
rerank	Não	Reordenação FlashRank (padrão True)
language	Não	Filtrar por linguagem (ex.: 'python')
live_grep	Não	Forçar fallback de grep ao vivo (rg/grep)
symbol_type	Não	Filtrar por tipo (ex.: 'function', 'class')

Esquema de Saída

ParâmetrosJSON Schema

Nome	Obrigatório	Descrição
Sem parâmetros de saída

TDQS

A4.2/5.0

Comportamento4/5

Concisão5/5

Completude4/5

Parâmetros3/5

Propósito5/5

Diretrizes de Uso4/5

status StatusA

Use no início de uma sessão, ou quando não tiver certeza se os resultados da busca podem estar desatualizados. Informa se um codebase está indexado, tamanho do índice/disponibilidade do mecanismo, uso de memória e um par stale/staleness_warning se arquivos mudaram desde o último índice (um reindex em segundo plano é acionado automaticamente).

ParâmetrosJSON Schema

Nome	Obrigatório	Descrição
Sem parâmetros

Esquema de Saída

ParâmetrosJSON Schema

Nome	Obrigatório	Descrição
Sem parâmetros de saída

TDQS

A4.5/5.0

Comportamento4/5

Concisão5/5

Completude5/5

Parâmetros4/5

Propósito5/5

Diretrizes de Uso4/5

Changelog do Esquema de Ferramentas

Adições, remoções e alterações de esquema recentes de ferramentas observadas durante inspeções MCP bem-sucedidas.

3 atualizações de ferramentas em 18 de setembro de 2026
7 atualizações de ferramentas v1.0.4 em 23 de julho de 2026

TDQS

A4.4/5.0

Pontuado em 10 ferramentas

Desambiguação5/5

Consistência de Nomenclatura4/5

Contagem de Ferramentas5/5

Completude4/5

Manutenção

AtividadeMantido

ResponsividadeSem resposta