Recon

Recon

Dê um cérebro ao seu agente de IA. Indexe seu código em 5 segundos.
_{Um servidor MCP de inteligência de código — 8 ferramentas, 13 linguagens, grafo de conhecimento, zero configuração.}

Resumo · Início Rápido · Recursos · Configuração MCP · Ferramentas · Painel

Resumo

Seu agente de IA é cego à arquitetura. Ele faz buscas, adivinha, e quebra coisas em arquivos que nunca leu.

O Recon resolve isso em uma linha:

npx recon-mcp serve

É isso. Seu agente agora tem um grafo de conhecimento de todo o seu código:

• Pergunte "o que quebra se eu mudar esta função?" — raio de impacto em ms
• "Trace o fluxo de execução a partir desta rota de API" — cadeia de chamadas entre linguagens
• "Encontre código estruturalmente semelhante a X" — busca híbrida FTS5 + vetorial
• "Renomeie com segurança em todo o repositório" — ciente do grafo, sem falsos positivos
• "Desenhe um diagrama de arquitetura" — Mermaid, um comando
• "Encontre código morto e dependências circulares" — regras de qualidade de código
• "Quais testes são afetados?" — análise de impacto em testes

Funciona com Claude Code, Cursor, Windsurf e qualquer cliente MCP. Zero configuração. 13 linguagens. MIT.

Por que o Recon?

Agentes de IA de codificação são cegos à arquitetura. Eles leem um arquivo por vez, buscam identificadores, adivinham pontos de chamada e quebram coisas em lugares que nunca viram.

Você não resolve isso com uma janela de contexto maior. Você precisa de estrutura.

O Recon indexa seu código em um grafo de conhecimento — funções, classes, cadeias de chamadas, imports, comunidades — e o expõe por meio de 8 ferramentas MCP, 3 prompts e 3 recursos que qualquer agente de IA pode consultar.

Um comando, consciência total. Seu agente obtém mapeamento de dependências, análise de raio de impacto, renomeações seguras, rastreamento de fluxo de execução, busca em linguagem natural e análise de qualidade de código — sem ler cada arquivo.

Início Rápido

# Index your project (zero config)
cd /path/to/your/project
npx recon-mcp index

# Start MCP server for AI agents
npx recon-mcp serve

# Or start HTTP REST API + interactive dashboard
npx recon-mcp serve --http
# → http://localhost:3100

Instalação global (opcional):

npm install -g recon-mcp
recon index && recon serve

Requer Node.js ≥ 20. As gramáticas Tree-sitter são empacotadas como dependências npm. A v6 usa armazenamento SQLite (.recon/recon.db) — arquivo único, sem dispersão de JSON.

Recursos

Linguagens Suportadas

Kotlin e Swift exigem gramáticas opcionais: npm install tree-sitter-kotlin tree-sitter-swift A gramática Go (tree-sitter-go) é incluída por padrão.

Busca Aprimorada (Opcional)

Por padrão, o Recon usa busca de texto completo FTS5. Para busca semântica híbrida (encontre código conceitualmente semelhante, não apenas correspondências exatas de nome), instale um pacote opcional:

npm install @huggingface/transformers

O Recon detecta automaticamente e ativa a busca híbrida FTS5 + vetorial com embeddings all-MiniLM-L6-v2. Sem configuração extra ou flags — basta instalar e re-indexar.

Exportação do Grafo

Exporte o grafo de conhecimento como Mermaid (cole em PRs/documentação do GitHub):

# Mermaid flowchart for a package
recon export --package mcp --limit 20

# Ego graph around a symbol
recon export --symbol handleQuery --depth 2

# Filter by node types and edge types
recon export --type Function,Interface --edges CALLS

Também disponível como ferramenta MCP recon_export — agentes podem gerar diagramas diretamente na conversa.

Como Funciona

You add MCP config → Agent starts Recon automatically → Done.

Quando seu agente de IA inicia:

1. O agente lê a configuração MCP → executa npx recon-mcp serve
2. npx baixa o Recon do npm (cacheado após a primeira execução)
3. O Recon auto-indexa o projeto (cwd) → cria .recon/recon.db
4. O observador de arquivos inicia → monitora arquivos de origem para alterações
5. O servidor MCP abre em stdio (stdin/stdout) — sem rede, sem porta
6. O agente vê 8 ferramentas + 3 prompts + 3 recursos
7. O agente recebe instruções integradas → sabe quando usar cada ferramenta
8. Você edita o código → o grafo atualiza cirurgicamente em ~50ms → salvo automaticamente em disco → o agente sempre tem dados atualizados

Zero configuração. Zero comandos. Totalmente automático.

Integração MCP

Projeto Único

Adicione à configuração MCP do seu agente de IA:

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/your/project"
    }
  }
}

cwd diz ao Recon qual projeto indexar. Ele escaneia o código deste diretório e cria .recon/ lá.

Múltiplos Projetos

Indexe e monitore vários projetos a partir de um único servidor Recon usando --projects:

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-mcp", "serve", "--projects", "/path/to/frontend"],
      "cwd": "/path/to/backend"
    }
  }
}

Isso cria um grafo mesclado — ambos os projetos são indexados, monitorados e consultáveis a partir de um único servidor MCP. Use o parâmetro repo em qualquer ferramenta para filtrar por projeto.

Alternativamente, execute servidores separados por projeto:

{
  "mcpServers": {
    "recon-backend": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/backend"
    },
    "recon-frontend": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/frontend"
    }
  }
}

### Multi-Repo (Merged Graph)

For cross-project queries (e.g., tracing API calls from frontend to backend), use multi-repo mode:

```bash
# Index each project with a name
cd /path/to/backend  && npx recon-mcp index --repo backend
cd /path/to/frontend && npx recon-mcp index --repo frontend

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/backend"
    }
  }
}

Depois filtre por repositório nas consultas: recon_find({query: "Auth", repo: "backend"}).

Auto-Indexação

recon serve lida com a indexação automaticamente:

Instruções Integradas: O Recon injeta automaticamente instruções do servidor MCP no prompt do sistema do agente. O agente usará proativamente recon_impact antes de editar, recon_explain para exploração e recon_rename para renomeações seguras — sem necessidade de prompts manuais.

Comandos CLI

recon index                        # Index codebase (incremental)
recon index --force                # Force full re-index
recon index --repo my-backend      # Index as named repo (multi-repo)
recon index --embeddings           # Include vector embeddings for semantic search

recon serve                        # Start MCP server on stdio (auto-indexes + live watcher)
recon serve --projects ../frontend # Watch additional project directories
recon serve --http                 # Start HTTP REST API + dashboard on :3100
recon serve --http --port 8080     # Custom port
recon serve --no-index             # Skip auto-indexing and file watcher
recon serve --no-watch             # Auto-index but disable file watcher
recon serve --repo my-backend      # Serve specific repo only

recon export                       # Export graph as Mermaid flowchart (Mermaid only)
recon export --symbol handleQuery  # Ego graph around a symbol

recon status                       # Show index stats
recon status --repo my-backend     # Status for specific repo
recon clean                        # Delete index

Auto-indexação: serve verifica se o índice está atualizado com o commit Git atual. Se estiver desatualizado, re-indexa automaticamente antes de iniciar. Use --no-index para pular.

Configuração

Crie um .recon.json na raiz do seu projeto para persistir configurações:

// .recon.json
{
  "projects": ["../frontend"],   // Additional dirs to index + watch
  "embeddings": false,           // Enable vector embeddings
  "watch": true,                 // Enable live file watcher
  "watchDebounce": 1500,         // Debounce interval (ms)
  "ignore": ["generated/"],      // Extra paths to ignore
  "crossLanguage": true,         // Enable cross-language API matching
  "testPatterns": ["**/*.test.*", "**/*.spec.*"],  // Test file patterns
  "rules": {                     // Code quality rule config
    "deadCode": true,
    "circularDeps": true,
    "unusedExports": true
  }
}

Prioridade: Flags CLI sempre sobrescrevem .recon.json, que sobrescreve os padrões.

Com um arquivo de configuração, sua configuração MCP permanece mínima:

{
  "mcpServers": {
    "recon": {
      "command": "npx",
      "args": ["recon-mcp", "serve"],
      "cwd": "/path/to/project"
    }
  }
}

Sem mais arrays longos de args — toda a configuração vive em .recon.json.

Referência de Ferramentas

Todas as 8 ferramentas aceitam um parâmetro opcional repo para filtragem multi-repositório.

recon_map

Visão geral da arquitetura: pacotes, stack tecnológico, pontos de entrada, saúde.

recon_map(repo?: string)

recon_find

Busca inteligente: nome exato, curinga (*Handler) ou linguagem natural.

recon_find(query: string, type?: string, language?: string, package?: string, limit?: number)

recon_explain

Contexto completo de 360°: chamadores, chamados, fluxos, links entre linguagens, testes.

recon_explain(name: string, file?: string, depth?: number, include_source?: boolean)

recon_impact

Análise de raio de impacto com testes afetados.

recon_impact(target: string, direction?: "upstream" | "downstream", maxDepth?: number, file?: string)

Níveis de risco: LOW (0-2 d1) · MEDIUM (3-9) · HIGH (10-19) · CRITICAL (20+ ou entre aplicações)

recon_changes

Diff Git para símbolos afetados, avaliação de risco e testes afetados.

recon_changes(scope?: "unstaged" | "staged" | "all" | "branch", base?: string, include_diagram?: boolean)

recon_rename

Renomeação segura ciente do grafo entre arquivos. Simulação por padrão.

recon_rename(symbol: string, new_name: string, file?: string, dry_run?: boolean)

recon_export

Gera diagrama Mermaid.

recon_export(target?: string, scope?: string, depth?: number, direction?: string, limit?: number)

recon_rules

Qualidade de código: código morto, dependências circulares, exports não utilizados, arquivos grandes, órfãos.

recon_rules(rule?: string, package?: string, language?: string)

Recursos MCP

Dados estruturados via URIs recon:// — agentes LEEM estes sem fazer uma chamada de ferramenta.

Prompts MCP

Três fluxos guiados que instruem agentes de IA passo a passo usando as ferramentas do Recon:

Cada prompt retorna uma mensagem estruturada com instruções passo a passo. O agente recebe a mensagem e executa autonomamente cada etapa usando as ferramentas do Recon.

Painel

Inicie o servidor HTTP para acessar o painel interativo de inteligência de código:

recon serve --http  # → http://localhost:3100

Recursos:

• Aba Grafo — Grafo de conhecimento dirigido por força com nós coloridos por tipo, alternância de coloração por comunidade e clique para inspecionar
• Aba Processos — Visualizador de fluxo de execução com cadeias de chamadas, contagens de ramificações e tags de comunidade
• Aba Impacto — Análise interativa de raio de impacto com níveis de risco e camadas de confiança
• Busca ao Vivo — Menu suspenso de busca com debounce (200ms) com navegação por teclado (↑↓ Enter Esc)
• Legenda do Grafo — Mapeamento tipo de nó → forma/cor
• Barra Lateral de Pacotes — Filtre o grafo por pacote com contagens de símbolos

Suporte Multi-Repositório

Indexe e consulte vários repositórios a partir de um único diretório .recon/:

cd /path/to/backend && recon index --repo backend
cd /path/to/frontend && recon index --repo frontend

recon serve                  # Serve all repos (merged graph)
recon serve --repo backend   # Serve single repo

Todas as ferramentas aceitam um parâmetro opcional repo. Os índices por repositório são armazenados em .recon/recon.db.

Busca

Busca de Texto Completo FTS5

O FTS5 substitui o BM25 personalizado, com tokenização camelCase/snake_case integrada ao SQLite.

• Tokenizer divide camelCase, PascalCase, snake_case, limites de dígitos (base64Decode → ["base", "64", "decode"])
• Boost de nome — nomes de símbolos com peso 3x maior que caminhos de arquivo
• Classificação — função de classificação FTS5 com pontuação de relevância
• Fallback — correspondência por substring quando o FTS5 não retorna nada

Busca Semântica Híbrida

Ative com recon index --embeddings e depois use recon_find({query: "...", semantic: true}).

• Modelo: Xenova/all-MiniLM-L6-v2 (embeddings de 384 dimensões via @huggingface/transformers)
• Fusão: Reciprocal Rank Fusion (RRF) — score = 1/(k + rank), k=60
• Armazenamento: Persistido em recon.db

Arquitetura

├── src/
│   ├── analyzers/
│   │   ├── ts-analyzer.ts        # TypeScript/React extraction (Compiler API)
│   │   ├── cross-language.ts     # Go route ↔ TS API call matching
│   │   ├── framework-detection.ts # 20+ framework entry point detection
│   │   └── tree-sitter/          # Multi-language tree-sitter analyzer
│   ├── graph/
│   │   ├── graph.ts              # KnowledgeGraph — in-memory Map + adjacency + version
│   │   ├── community.ts          # Label propagation community detection
│   │   └── process.ts            # Execution flow detection (BFS)
│   ├── watcher/
│   │   └── watcher.ts            # Live file watcher — surgical graph updates
│   ├── mcp/
│   │   ├── server.ts             # MCP server (stdio transport)
│   │   ├── tools.ts              # 8 tool definitions (JSON Schema)
│   │   ├── handlers.ts           # Tool dispatch + query logic
│   │   ├── prompts.ts            # 3 MCP prompt templates
│   │   ├── hints.ts              # Next-step hints for agent guidance
│   │   ├── instructions.ts       # AI agent instructions (system prompt)
│   │   ├── augmentation.ts       # Compact context injection
│   │   ├── staleness.ts          # Index freshness check
│   │   ├── rename.ts             # Graph-aware multi-file rename
│   │   └── resources.ts          # MCP Resources (recon:// URIs)
│   ├── search/
│   │   ├── fts5.ts               # FTS5 full-text search
│   │   ├── hybrid-search.ts      # FTS5 + vector RRF fusion
│   │   └── vector-store.ts       # In-memory cosine similarity
│   ├── server/
│   │   └── http.ts               # Express HTTP REST API + dashboard
│   ├── dashboard/                # Interactive web dashboard
│   │   ├── index.html
│   │   ├── style.css
│   │   └── app.js
│   └── cli/
│       ├── index.ts              # Commander CLI
│       └── commands.ts           # index, serve, status, clean

Fluxo de Dados

  TS Compiler API → components ─┐
  tree-sitter → 13 languages   ├─→ KnowledgeGraph ─→ .recon/recon.db (SQLite)
  router.go → API routes       ─┤   (in-memory)       single database:
  label propagation → clusters ─┤   + FTS5 Index       - nodes, relationships
  BFS → execution flows        ─┘   + Communities      - search index (FTS5)
                                     + Embeddings       - embeddings
                                     + Processes        - metadata
                                          │
                                  ┌───────┤
                          File Watcher (chokidar)
                          surgical update ~50ms/file
                                          │
                                ┌─────────┴──────────┐
                           MCP Server (stdio)   HTTP REST API
                         ┌───┴────┐────┐        (:3100 + Dashboard)
                      8 Tools  3 Prompts  3 Resources
                         │        │      recon://symbol/{name}
                   ┌─────┼────┐   │      recon://file/{path}
                   │     │    │   │      recon://stats
                Claude  Cursor …   │
                 Code  Antigravity │
                                  │
                          pre_commit
                          architecture
                          onboard

API REST HTTP

recon serve --http              # Listen on :3100
recon serve --http --port 8080  # Custom port

# Search for a symbol
curl -X POST http://localhost:3100/api/tools/recon_find \
  -H 'Content-Type: application/json' \
  -d '{"query": "AuthMiddleware"}'

# Read a resource
curl 'http://localhost:3100/api/resources/read?uri=recon://symbol/AuthMiddleware'

CORS habilitado por padrão para clientes de navegador.

Segurança: O servidor HTTP vincula-se a localhost (127.0.0.1) por padrão. Use --host 0.0.0.0 para expor na rede.

Esquema do Grafo

Propriedades dos Nós

Tipos de Relacionamento

Testes

npm test           # Run all tests
npx vitest --watch # Watch mode

541 testes em 22 suítes de teste:

Detecção de Comunidades

Após a indexação, o Recon detecta automaticamente comunidades de código usando o Algoritmo de Propagação de Rótulos (LPA):

• Cada função/classe/struct recebe um rótulo community com base em suas conexões
• As comunidades recebem o nome do pacote mais comum em cada cluster
• recon_explain mostra a associação à comunidade
• recon_impact lista as comunidades afetadas para conscientização entre módulos

Reindexação em Tempo Real

O Recon monitora arquivos de origem e atualiza o grafo de conhecimento em tempo real:

Indexação Incremental

Os arquivos são hashados com SHA-256. Em recon index, apenas os arquivos alterados são reanalisados:

• TypeScript: granularidade por arquivo via Compiler API
• Tree-sitter: granularidade por arquivo para todas as 13 linguagens
• Detecção automática: serve compara hashes de commits Git para detectar índices desatualizados
• Force a reindexação completa com --force

Licença

MIT