MCP-DOC-MID: Servidor MCP para OpenAPI y Generación de Integraciones

Servidor de grado empresarial para el ecosistema Model Context Protocol (MCP) en Node.js (ES Modules), especializado en aprender, dereferenciar ($ref) y permitir que un LLM consulte especificaciones OpenAPI/Swagger y genere integraciones de código listas para producción.

Utiliza @apidevtools/swagger-parser para resolver en memoria todos los apuntadores y esquemas de componentes al iniciar el servidor, y expone un catálogo de 8 herramientas MCP diseñadas para búsqueda, inspección, validación y generación de clientes HTTP en múltiples lenguajes (TypeScript, Python, JavaScript, cURL, C#).

📚 Documentación Detallada

Para guías especializadas y diagramas completos, consulta:

• 🏛️ Guía de Arquitectura del Sistema (docs/ARCHITECTURE.md): Diagramas de flujo, Session Binding, observabilidad, persistencia atómica y Circuit Breaker.

• 🛠️ Referencia de Herramientas MCP (docs/TOOLS_REFERENCE.md): Detalle exhaustivo de parámetros, esquemas JSON y ejemplos de respuesta de cada herramienta.

• 📂 Guía de Archivos Swagger / OpenAPI (docs/SWAGGER_GUIDE.md): Instrucciones para añadir, validar y organizar especificaciones .yml y .json.

• 📋 Especificación Estructural Doters API Internal (docs/MIDDLEWARE_API_SPEC.md): Análisis de los 110 endpoints, 221 DTOs, envoltorios de respuesta y 25 dominios de middleware-api.json.

Related MCP server: mcp-swagger

🏛️ Características Principales

1. Lectura y Dereference Automático (swaggers/):

   • Escaneo recursivo de archivos .yml, .yaml y .json.

   • Resolución completa de referencias $ref en componentes, parámetros y modelos.

2. Generación de Integraciones de Código para LLM:

   • generate_integration_code: Genera snippets y clientes fuertemente tipados para cualquier endpoint.

   • Soporte para TypeScript (fetch/axios), JavaScript, Python (httpx/requests), cURL y C#.

3. Validación y Extracción de Seguridad:

   • validate_payload: Comprobación previa de que un payload JSON cumpla con tipos y campos requeridos.

   • get_security_schemes: Extracción de esquemas de autenticación (Bearer tokens, API keys, OAuth2).

4. Transporte Dual:

   • STDIO: Integración estándar con Claude Desktop, Antigravity, Cursor y extensiones MCP.

   • SSE / HTTP: Servidor Express con /sse, /messages, /metrics, /health y /dashboard.

5. Observabilidad y Seguridad:

   • Logs dirigidos exclusivamente a process.stderr con Pino.

   • Métricas Prometheus (prom-client) en /metrics.

   • Session Binding y protección contra Session Hijacking en /messages.

🛣️ El Flujo de Integración en 3 Pasos (Zero-Code)

Para que la integración de nuevas APIs sea 100% escalable, sin fricción y sin tocar una sola línea de código, el servidor implementa Autodescubrimiento y Carga por Convención:

flowchart LR
    A["1. Copiar Archivo\n(swaggers/mi-api.json o .yml)"] --> B["2. Auto-Discovery & Caching\n(Hash SHA-256 + Dereference)"]
    B --> C["3. Auto-Diagnóstico\n(npm run self-test)"]
    C --> D["✅ Disponible en las 8 Tools MCP\n(search_docs, get_endpoint_doc, etc.)"]

1️⃣ Paso 1: Colocar el Archivo en swaggers/

Simplemente guarda tu archivo .json, .yml o .yaml en el directorio swaggers/.

📁 Estructura Escalable Recomendada (Por Dominios o Microservicios):

El escáner es recursivo, por lo que puedes organizar tus archivos en subcarpetas temáticas a medida que crezca el número de APIs:

swaggers/
├── middleware-api.json                # API Core Middleware
├── partners/
│   ├── avasa-car-rental.json          # Swagger de Avasa
│   └── iamsa-bus.json                 # Swagger de IAMSA
├── payments/
│   └── openpay-gateway.yml            # OpenAPI de Pasarelas de Pago
└── flights/
    └── viva-booking.yaml              # OpenAPI de Reservaciones Viva

2️⃣ Paso 2: Verificar la Integridad con npm run self-test

No necesitas levantar clientes MCP ni reiniciar servidores a ciegas. Ejecuta en terminal:

npm run self-test

¿Qué hace este comando en < 15 ms?

1. Detecta el nuevo archivo y calcula su hash SHA-256.

2. Resuelve y dereferencia automáticamente todos los apuntadores $ref.

3. Sanitiza referencias rotas o ausentes para que el servidor nunca colapse.

4. Genera el snapshot de alto rendimiento en .cache/swaggers/.

5. Muestra el resumen en tiempo real:

{
  "status": "healthy",
  "checks": {
    "swaggers": {
      "status": "pass",
      "specsCount": 4,
      "endpointsCount": 285,
      "schemasCount": 412
    }
  }
}

3️⃣ Paso 3: Listo para Consultar por los Agentes y LLMs

De forma inmediata, las 8 herramientas MCP aprenden los nuevos endpoints y esquemas sin configuración adicional:

• Búsqueda global: search_docs({ query: "renta autos" }) buscará en todos los swaggers a la vez.

• Búsqueda filtrada: search_docs({ query: "renta", specId: "avasa-car-rental" }) consulta exclusivamente esa API.

• Generación de código: generate_integration_code({ path: "/v1/cars/book", language: "typescript" }) generará el cliente tipado.

• Validación de payloads: validate_payload({ schemaName: "CarBookingDto", payload: { ... } }) validará contra el nuevo modelo.

🏆 Buenas Prácticas para Garantizar Máxima Calidad en el LLM

Para que los modelos de lenguaje generen el mejor código y respuestas precisas al leer tus nuevos swaggers:

1. Declarar la URL Base (servers):

   servers:
     - url: https://api.vivaaerobus.com/v1
       description: Ambiente de Producción

2. Incluir Ejemplos en los Schemas (example / examples): Los ejemplos permiten a la herramienta generate_integration_code y al LLM crear payloads de prueba realistas automáticamente.

3. Usar Etiquetas Claras (tags): Agrupar por tags (ej. [ "CarRental", "Payments", "Security" ]) permite a los agentes filtrar colecciones de endpoints rápidamente con search_docs({ tag: "Payments" }).

4. Declarar la Seguridad (components.securitySchemes): Especificar si usa bearerFormat: JWT, ApiKey o OAuth2 para que la herramienta get_security_schemes exponga las cabeceras requeridas.

🛠️ Herramientas MCP Disponibles

⚙️ Variables de Entorno (.env)

🚀 Inicio Rápido

# 1. Instalar dependencias
npm install

# 2. Autodiagnóstico en runtime (<5ms)
npm run self-test

# 3. Iniciar en modo STDIO (predeterminado)
npm start

# 4. Iniciar en modo SSE / HTTP (servidor web)
TRANSPORT_MODE=sse PORT=3000 npm start

🧪 Pruebas Automatizadas y Benchmarks

El proyecto cuenta con una suite integral de pruebas con 116 tests pasando (100%) y una cobertura superior al 93% en sentencias:

# 1. Ejecutar suite completa de pruebas unitarias y de integración
npm test

# 2. Reporte de cobertura detallado con Vitest y V8 (>93% Stmts)
npm run test:coverage

# 3. Pruebas de carga de alta concurrencia (100 agentes concurrentes)
npm run test:load

# 4. Benchmark de latencia y throughput (<5ms)
npm run benchmark

# 5. Pipeline de integración continua (CI)
npm run test:ci

🐳 Despliegue con Docker

# Construir imagen Docker multi-stage
docker build -t mcp-doc-mid:latest .

# Ejecutar contenedor en modo SSE
docker run -p 3000:3000 -e TRANSPORT_MODE=sse mcp-doc-mid:latest