Recon

Recon

Dale a tu agente de IA un cerebro. Indexa tu código en 5 segundos.
_{Un servidor MCP de inteligencia de código: 8 herramientas, 13 lenguajes, grafo de conocimiento, cero configuración.}

Resumen · Inicio rápido · Características · Configuración MCP · Herramientas · Panel

Resumen

Tu agente de IA es ciego a la arquitectura. Busca con grep, adivina, y rompe cosas en archivos que nunca leyó.

Recon lo soluciona con una línea:

npx recon-mcp serve

Eso es todo. Tu agente ahora tiene un grafo de conocimiento de todo tu código:

• Pregunta "¿qué se rompe si cambio esta función?" — radio de impacto en ms
• "Traza el flujo de ejecución desde esta ruta de API" — cadena de llamadas entre lenguajes
• "Encuentra código estructuralmente similar a X" — búsqueda híbrida FTS5 + vectorial
• "Renombra esto de forma segura en todo el repositorio" — consciente del grafo, sin falsos positivos
• "Dibújame un diagrama de arquitectura" — Mermaid, un comando
• "Encuentra código muerto y dependencias circulares" — reglas de calidad de código
• "¿Qué pruebas se ven afectadas?" — análisis de impacto en pruebas

Funciona con Claude Code, Cursor, Windsurf y cualquier cliente MCP. Cero configuración. 13 lenguajes. MIT.

¿Por qué Recon?

Los agentes de IA de codificación son ciegos a la arquitectura. Leen un archivo a la vez, buscan identificadores con grep, adivinan en los puntos de llamada y rompen cosas en lugares que nunca vieron.

No puedes solucionar esto con una ventana de contexto más grande. Necesitas estructura.

Recon indexa tu código en un grafo de conocimiento — funciones, clases, cadenas de llamadas, importaciones, comunidades — y lo expone a través de 8 herramientas MCP, 3 prompts y 3 recursos que cualquier agente de IA puede consultar.

Un comando, conciencia total. Tu agente obtiene mapeo de dependencias, análisis de radio de impacto, renombrados seguros, trazado de flujo de ejecución, búsqueda en lenguaje natural y análisis de calidad de código — sin leer cada archivo.

Inicio 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

Instalación global (opcional):

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

Requiere Node.js ≥ 20. Las gramáticas de Tree-sitter se incluyen como dependencias npm. v6 usa almacenamiento SQLite (.recon/recon.db) — un solo archivo, sin dispersión de JSON.

Características

Lenguajes compatibles

Kotlin y Swift requieren gramáticas opcionales: npm install tree-sitter-kotlin tree-sitter-swift La gramática de Go (tree-sitter-go) se incluye por defecto.

Búsqueda mejorada (opcional)

Por defecto, Recon usa búsqueda de texto completo FTS5. Para búsqueda semántica híbrida (encuentra código conceptualmente similar, no solo coincidencias de nombre exactas), instala un paquete opcional:

npm install @huggingface/transformers

Recon lo detecta automáticamente y habilita la búsqueda híbrida FTS5 + vectorial con embeddings de all-MiniLM-L6-v2. Sin configuración adicional ni banderas — solo instala y re-indexa.

Exportación del grafo

Exporta el grafo de conocimiento como Mermaid (pégalo en PRs/documentación de 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

También disponible como herramienta MCP recon_export — los agentes pueden generar diagramas directamente en la conversación.

Cómo funciona

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

Cuando tu agente de IA inicia:

1. El agente lee la configuración MCP → ejecuta npx recon-mcp serve
2. npx descarga Recon desde npm (en caché después de la primera ejecución)
3. Recon auto-indexa el proyecto (cwd) → crea .recon/recon.db
4. El observador de archivos inicia → monitorea archivos fuente para cambios
5. El servidor MCP se abre en stdio (stdin/stdout) — sin red, sin puerto
6. El agente ve 8 herramientas + 3 prompts + 3 recursos
7. El agente recibe instrucciones integradas → sabe cuándo usar cada herramienta
8. Editas código → el grafo se actualiza quirúrgicamente en ~50ms → se auto-guarda en disco → el agente siempre tiene datos frescos

Cero configuración. Cero comandos. Totalmente automático.

Integración MCP

Proyecto único

Agrega a la configuración MCP de tu 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 le dice a Recon qué proyecto indexar. Escanea el código desde este directorio y crea .recon/ allí.

Múltiples proyectos

Indexa y observa múltiples proyectos desde un solo servidor Recon usando --projects:

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

Esto crea un grafo fusionado — ambos proyectos se indexan, observan y consultan desde un solo servidor MCP. Usa el parámetro repo en cualquier herramienta para filtrar por proyecto.

Alternativamente, ejecuta servidores separados por proyecto:

{
  "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"
    }
  }
}

Luego filtra por repositorio en las consultas: recon_find({query: "Auth", repo: "backend"}).

Auto-indexación

recon serve maneja la indexación automáticamente:

Instrucciones integradas: Recon inyecta automáticamente instrucciones del servidor MCP en el prompt del sistema del agente. El agente usará proactivamente recon_impact antes de editar, recon_explain para exploración y recon_rename para renombrados seguros — sin necesidad de prompts manuales.

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-indexación: serve verifica si el índice está actualizado con el commit actual de Git. Si está desactualizado, re-indexa automáticamente antes de iniciar. Usa --no-index para omitir.

Configuración

Crea un .recon.json en la raíz de tu proyecto para persistir configuraciones:

// .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
  }
}

Prioridad: Las banderas CLI siempre anulan .recon.json, que anula los valores predeterminados.

Con un archivo de configuración, tu configuración MCP se mantiene mínima:

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

No más arrays largos de args — toda la configuración vive en .recon.json.

Referencia de herramientas

Las 8 herramientas aceptan un parámetro opcional repo para filtrar entre múltiples repositorios.

recon_map

Vista general de arquitectura: paquetes, stack tecnológico, puntos de entrada, salud.

recon_map(repo?: string)

recon_find

Búsqueda inteligente: nombre exacto, comodín (*Handler) o lenguaje natural.

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

recon_explain

Contexto completo de 360°: llamadores, llamados, flujos, enlaces entre lenguajes, pruebas.

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

recon_impact

Análisis de radio de impacto con pruebas afectadas.

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

Niveles de riesgo: LOW (0-2 d1) · MEDIUM (3-9) · HIGH (10-19) · CRITICAL (20+ o entre aplicaciones)

recon_changes

Diff de Git a símbolos afectados, evaluación de riesgo y pruebas afectadas.

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

recon_rename

Renombrado seguro consciente del grafo entre archivos. Simulación por defecto.

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

recon_export

Genera diagrama Mermaid.

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

recon_rules

Calidad de código: código muerto, dependencias circulares, exportaciones sin usar, archivos grandes, huérfanos.

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

Recursos MCP

Datos estructurados mediante URIs recon:// — los agentes los LEEN sin hacer una llamada de herramienta.

Prompts MCP

Tres flujos de trabajo guiados que instruyen a los agentes de IA paso a paso usando las herramientas de Recon:

Cada prompt devuelve un mensaje estructurado con instrucciones paso a paso. El agente recibe el mensaje y ejecuta autónomamente cada paso usando las herramientas de Recon.

Panel

Inicia el servidor HTTP para acceder al panel interactivo de inteligencia de código:

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

Características:

• Pestaña de Grafo — Grafo de conocimiento dirigido por fuerza con nodos coloreados por tipo, alternancia de color de comunidad y clic para inspeccionar
• Pestaña de Procesos — Visor de flujo de ejecución con cadenas de llamadas, conteos de ramas y etiquetas de comunidad
• Pestaña de Impacto — Análisis interactivo de radio de impacto con niveles de riesgo y niveles de confianza
• Búsqueda en vivo — Menú desplegable de búsqueda con debounce (200ms) con navegación por teclado (↑↓ Enter Esc)
• Leyenda del grafo — Mapeo de tipo de nodo → forma/color
• Barra lateral de paquetes — Filtra el grafo por paquete con conteos de símbolos

Soporte multi-repositorio

Indexa y consulta múltiples repositorios desde un único directorio .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 las herramientas aceptan un parámetro opcional repo. Los índices por repositorio se almacenan en .recon/recon.db.

Búsqueda

Búsqueda de texto completo FTS5

FTS5 reemplaza al BM25 personalizado, con tokenización camelCase/snake_case integrada en SQLite.

• Tokenizador divide camelCase, PascalCase, snake_case, límites de dígitos (base64Decode → ["base", "64", "decode"])
• Refuerzo de nombres — los nombres de símbolos pesan 3 veces más que las rutas de archivo
• Ranking — función de ranking FTS5 con puntuación de relevancia
• Respaldo — coincidencia de subcadenas cuando FTS5 no devuelve resultados

Búsqueda semántica híbrida

Habilítala con recon index --embeddings, luego usa recon_find({query: "...", semantic: true}).

• Modelo: Xenova/all-MiniLM-L6-v2 (embeddings de 384 dimensiones vía @huggingface/transformers)
• Fusión: Fusión de Ranking Recíproco (RRF) — score = 1/(k + rank), k=60
• Almacenamiento: Persistido en recon.db

Arquitectura

├── 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

Flujo de datos

  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 defecto para clientes de navegador.

Seguridad: El servidor HTTP se vincula a localhost (127.0.0.1) por defecto. Usa --host 0.0.0.0 para exponerlo en la red.

Esquema del grafo

Propiedades de nodos

Tipos de relaciones

Pruebas

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

541 pruebas en 22 suites de pruebas:

Detección de comunidades

Después de la indexación, Recon detecta automáticamente comunidades de código usando el Algoritmo de Propagación de Etiquetas (LPA):

• Cada función/clase/struct recibe una etiqueta community según sus conexiones
• Las comunidades se nombran según el paquete más común en cada clúster
• recon_explain muestra la pertenencia a comunidades
• recon_impact lista las comunidades afectadas para conciencia entre módulos

Re-indexación en vivo

Recon observa los archivos fuente y actualiza el grafo de conocimiento en tiempo real:

Indexación incremental

Los archivos se procesan con SHA-256. En recon index, solo se re-analizan los archivos modificados:

• TypeScript: granularidad por archivo vía Compiler API
• Tree-sitter: granularidad por archivo para los 13 lenguajes
• Auto-detección: serve compara hashes de commits de Git para detectar índices obsoletos
• Fuerza una re-indexación completa con --force

Licencia

MIT