Analizador de bases de código de servidor MCP

Un servidor MCP (Model Context Protocol) de nivel de producción que analiza bases de código TypeScript, detecta problemas de salud del código, obtiene incidentes del sistema y genera planes de remediación accionables. Admite transporte dual (STDIO para desarrollo local, SSE para despliegue en la nube). Construido con ts-morph, Express y validación Zod.

🚀 Características

Tres herramientas principales:

1. analyze_codebase_health — Escanea repositorios TypeScript en busca de:

   • Archivos grandes (candidatos potenciales a refactorización)

   • Falta de tipos de función explícitos (tipado débil)

   • Dependencias circulares (problemas arquitectónicos)

   • Utiliza ts-morph para el análisis a nivel de AST

2. fetch_system_incidents — Devuelve datos de incidentes estructurados:

   • Datos de incidentes simulados (perfectos para pruebas/demos)

   • Retrasos y modos de fallo configurables

   • Respuestas JSON amigables para LLM

3. generate_remediation_plan — Crea planes de corrección accionables:

   • Análisis de causa raíz a partir de seguimientos de pila (stack traces)

   • Pasos de remediación detallados

   • Sugerencias de código y mejores prácticas

   • Evaluación del nivel de riesgo

Todas las herramientas devuelven sobres de éxito/error estructurados diseñados para el consumo por parte de LLMs.

Descripción general de la arquitectura

flowchart LR
    Client[McpClient] --> Runtime[RuntimeSelector]
    Runtime -->|stdio| Stdio[StdioTransportAdapter]
    Runtime -->|sse| Sse[SseTransportAdapter]
    Stdio --> Server[McpServer]
    Sse --> Server
    Server --> Registry[ToolRegistry]
    Registry --> ToolA[analyze_codebase_health]
    Registry --> ToolB[fetch_system_incidents]
    Registry --> ToolC[generate_remediation_plan]

Ejecución local (STDIO)

1. Instalar dependencias:

   • npm install

2. Iniciar servidor:

   • npm run dev:stdio

3. El servidor se inicia a través de stdin/stdout y está listo para clientes MCP locales.

Ejecución con SSE (Express)

1. Configurar entorno:

   • TRANSPORT=sse

   • opcional: AUTH_TOKEN=tu-token-secreto

2. Iniciar servidor:

   • npm run dev:sse

3. Endpoints:

   • GET /events para el flujo SSE

   • POST /messages?sessionId=... para mensajes JSON-RPC de MCP

Conectar desde Cursor

Para uso local, registra Nexus-Core como un servidor MCP stdio:

• comando: node

• argumentos: dist/index.js (después de compilar) o tsx src/index.ts (desarrollo)

• entorno: TRANSPORT=stdio

Para uso alojado, configura tu cliente MCP para usar el endpoint SSE:

• URL de flujo: https://<host>/events

• URL de mensajes: https://<host>/messages?sessionId=<session-id>

• añade Authorization: Bearer <AUTH_TOKEN> si la autenticación por token está habilitada.

Ejemplos de prompts

• "Analiza mi repositorio"

• "Obtén incidentes"

• "Corrige este error"

Variables de entorno

Consulta .env.example para ver todos los ajustes admitidos. Controles importantes:

• TRANSPORT: stdio o sse

• TOOL_TIMEOUT_MS: tiempo de espera máximo para cada llamada a herramienta

• TS_MORPH_MAX_FILES, TS_MORPH_MAX_DEPTH: límites de seguridad para el análisis

• INCIDENT_API_TIMEOUT_MS, INCIDENT_API_RETRIES: controles de dependencias externas

• SSE_HEARTBEAT_MS, SSE_SESSION_TTL_MS: ciclo de vida de la sesión SSE

Despliegue en producción

Docker

• Construir imagen: docker build -t nexus-core .

• Ejecutar contenedor:

  • docker run -e TRANSPORT=sse -e PORT=8080 -p 8080:8080 nexus-core

Cloud Run

Usa deploy.sh:

PROJECT_ID=<gcp-project> REGION=<region> SERVICE=nexus-core ./deploy.sh

Este script:

1. Construye la imagen del contenedor

2. Envía a GCR

3. Despliega en Cloud Run

Fiabilidad y modelo de errores

• Todas las solicitudes de herramientas se validan con Zod.

• Ninguna ejecución de herramienta devuelve excepciones no controladas.

• Los errores utilizan un sobre estándar con:

  • code

  • message

  • retryable

  • suggestedAction

  • meta (requestId, toolName, tiempo)