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)](file:///c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/docs/ARCHITECTURE.md): Diagramas de flujo, Session Binding, observabilidad, persistencia atómica y Circuit Breaker.
• 🛠️ [Referencia de Herramientas MCP (docs/TOOLS_REFERENCE.md)](file:///c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/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)](file:///c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/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)](file:///c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/docs/MIDDLEWARE_API_SPEC.md): Análisis de los 110 endpoints, 221 DTOs, envoltorios de respuesta y 25 dominios de middleware-api.json.

---

🏛️ 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/](file:///c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/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

[!TIP] Identificador Automático (specId):
El sistema genera el specId automáticamente a partir del nombre base del archivo:

• avasa-car-rental.json $\rightarrow$ specId: "avasa-car-rental"
• openpay-gateway.yml $\rightarrow$ specId: "openpay-gateway"

---

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

Herramienta	Descripción	Parámetros Principales
[list_specs](file:///c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/docs/TOOLS_REFERENCE.md#1-list_specs)	Lista todas las APIs cargadas con sus versiones, servidores y conteo de rutas.	Ninguno
[search_docs](file:///c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/docs/TOOLS_REFERENCE.md#2-search_docs)	Busca endpoints, modelos y descripciones por palabras clave.	query (req), specId (opt), tag (opt), limit (opt)
[get_endpoint_doc](file:///c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/docs/TOOLS_REFERENCE.md#3-get_endpoint_doc)	Obtiene la especificación completa y dereferenciada de un endpoint.	path (req), method (opt, default: GET), specId (opt)
[get_schema_doc](file:///c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/docs/TOOLS_REFERENCE.md#4-get_schema_doc)	Obtiene el modelo de datos / schema dereferenciado.	schemaName (req), specId (opt)
[generate_integration_code](file:///c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/docs/TOOLS_REFERENCE.md#5-generate_integration_code)	Genera código de cliente listo para producción (TS, Python, JS, cURL, C#).	path (req), method (opt), language (opt), clientType (opt)
[get_security_schemes](file:///c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/docs/TOOLS_REFERENCE.md#6-get_security_schemes)	Obtiene esquemas de autenticación y cabeceras requeridas.	specId (opt)
[validate_payload](file:///c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/docs/TOOLS_REFERENCE.md#7-validate_payload)	Valida un payload JSON contra el schema de un endpoint antes de invocarlo.	schemaName (req), payload (req), specId (opt)
[query_api_knowledge](file:///c:/Users/Manuel/Documents/vivaaerobus/Doters/MCP/mcp-docu-mid/docs/TOOLS_REFERENCE.md#8-query_api_knowledge)	Sintetiza respuestas a preguntas de negocio o arquitectura sobre las APIs.	query (req), specId (opt)

---

⚙️ Variables de Entorno (.env)

Variable	Descripción	Valor por Defecto
TRANSPORT_MODE	Modo de transporte (stdio, sse, http)	stdio
PORT	Puerto de escucha para modo SSE/HTTP	3000
LOG_LEVEL	Nivel de logs (debug, info, warn, error)	info
MCP_API_KEY	Llave secreta para autenticación de API	default-mcp-secret-key
ENABLE_AUTH	Habilitar/deshabilitar autenticación (true/false)	true
ALLOWED_ORIGINS	Orígenes permitidos para CORS	*
DASHBOARD_USER	Usuario para acceso al Dashboard web	admin
DASHBOARD_PASSWORD	Contraseña para acceso al Dashboard web	admin
RATE_LIMIT_WINDOW_MS	Ventana de tiempo para Rate Limit en ms	900000 (15 min)
RATE_LIMIT_MAX	Máximo de peticiones por ventana	1000
STATS_STORAGE_ENABLED	Persistencia de estadísticas en disco	true
STATS_STORAGE_PATH	Ruta del archivo de persistencia	data/stats.json
SWAGGERS_DIR	Carpeta de especificaciones OpenAPI	swaggers

---

🚀 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