mcp-despliegue-local

Agente de diagnóstico de solo lectura para servicios Node/Nitro que corren bajo pm2 en un servidor Windows on-premise. Se expone como servidor MCP por HTTP, así que un asistente de IA puede contestar, sin que nadie entre por escritorio remoto:

1. ¿Qué build corre ahí, y desde cuándo?

2. ¿Está vivo?

3. ¿Qué dice el log?

4. ¿Qué configuración tiene cargada?

5. ¿El proceso vivo arrancó con la configuración que hoy está en disco, o con una anterior?

La quinta es la que justifica el proyecto. pm2 conserva el entorno con el que arrancó cada proceso, y pm2 restart no lo recarga y no lo dice. El síntoma es «cambié el archivo y no pasa nada» y cuesta media hora cada vez. El agente compara por huella el archivo en disco contra el entorno del proceso vivo y responde directamente si divergen.

Qué NO es

• No despliega. No construye, no copia, no reinicia, no escribe. Ni una sola ruta de escritura existe en la tabla de enrutado — no está desactivada por bandera, no existe. El despliegue está diseñado por escrito en docs/V1-DESPLIEGUE.md y deliberadamente no implementado.

• No es un monitor. No agrega, no alerta, no guarda serie temporal. Contesta preguntas cuando se las hacen.

• No adivina. No prueba /health ni /healthz a ver si suena. Cada servicio declara cómo se sondea, o declara que no se sondea.

• No exige nada a los servicios vigilados. Ni una línea de código, ni un endpoint de versión, ni una variable nueva. Todo se infiere desde el disco.

Related MCP server: Windows MCP Server

Por qué existe

En un servidor de planta nadie sabe qué versión corre. Los servicios de este tipo declaran version: "0.0.0" en su package.json, no exponen commit ni fecha de build, y no tienen endpoint de versión. Preguntar «¿está actualizado?» no tiene respuesta, y la que se da es un recuerdo.

El agente responde con evidencia etiquetada: cada dato de build viene con su origen y su nivel de confianza, y esa etiqueta nunca sube de tono al resumirse. Una herramienta de diagnóstico que exagera lo que sabe es una que miente. Los límites están escritos, uno a uno, en docs/DIAGNOSTICO.md — es el documento que más importa de este repo.

Arranque en 10 minutos

Requiere Node ≥ 22.19 y pm2 en la máquina vigilada.

git clone <este-repo> C:\agentes\mcp-despliegue-local
cd C:\agentes\mcp-despliegue-local
npm install

1. Descriptor. Copia ejemplos/servicios.ejemplo.mjs a tu repo privado (nunca a este) y describe tus servicios. Empieza por uno solo, con sonda: { tipo: 'ninguna' }. Esquema completo en docs/DESCRIPTORES.md.

2. Entorno. cp env.ejemplo .env y rellena:

   DESPLIEGUE_LOCAL_TOKEN=<32 caracteres o más, generado al azar>
   DESPLIEGUE_LOCAL_DESCRIPTORES=D:\servicios\configuracion\servicios.mjs

   Genera el token con node -p "require('crypto').randomBytes(32).toString('hex')". Con menos de 32 caracteres el agente sale con código 1 y te dice por qué.

3. Arranca bajo pm2.

   pm2 start ecosystem.config.cjs
   pm2 save

4. Verifica sin un modelo delante. /salud no pide token y no devuelve datos:

   curl http://127.0.0.1:7717/salud

   { "ok": true, "contrato": 1, "version": "0.1.0", "arrancadoEn": "2026-09-08T09:12:44.001Z",
     "expuesto": false, "descriptores": { "cargados": 4, "invalidos": 0, "avisos": 1 } }

5. Registra el MCP en el consumidor. No hace falta OAuth ni un puente stdio: el agente es el servidor MCP por Streamable HTTP y .mcp.json admite cabeceras estáticas con expansión de variables de entorno.

   { "mcpServers": { "planta": {
     "type": "http",
     "url": "https://agente.example.com/mcp",
     "headers": { "Authorization": "Bearer ${TOKEN_DESPLIEGUE_LOCAL}" }
   } } }

   Con headers puesto, un 401 se reporta como fallo de conexión y no dispara el flujo OAuth.

El runbook completo — proxy inverso, servicio de arranque, verificación paso a paso — está en docs/INSTALACION.md.

Salida de ejemplo

estado_de_los_servicios es la primera llamada de cualquier diagnóstico y casi siempre la única que hace falta:

4 servicios descritos, 3 en línea.

inventario     en línea    3 d 4 h    build 2026-09-04 (sello.json, confianza alta)
               sonda http /contrato → 200 en 41 ms. Alcance: http.

etiquetas      en línea    3 d 4 h    build 2026-09-04 (nitro.json, confianza media)
               sonda http /api/etiqueta → 400 en 18 ms, esperado. Alcance: proceso:
               contesta, pero esto no prueba que emita etiquetas.

telemetria     en línea      41 min   build 2026-09-08 (mtime de entrada, confianza BAJA —
               probablemente la fecha del copiado, no la del build).
               sonda websocket → 101. Alcance: proceso.
               AVISO: el archivo de configuración en disco no es el que el proceso
               tiene cargado. Divergen: NIVEL_LOG, INTERVALO_MS. Remedio:
               pm2 startOrRestart, no pm2 restart.

pedidos        detenido    —          build 2026-08-27 (nitro.json, confianza media)
               Sin sonda por decisión del descriptor: solo tiene endpoints de negocio
               que exigen base viva, así que un 200 no probaría nada.
               Señales en disco: datos/cola.jsonl, 0 bytes, sin cambios desde hace 6 d.

Nada de eso es JSON crudo por accidente: toda salida de una herramienta MCP es prosa en español ya traducida a una acción.

Las cinco herramientas MCP

Documentación

Estado

v0 implementado. Los dieciséis módulos de src/ están escritos, con 115 tests unitarios y una prueba de aceptación de 41 comprobaciones que corre contra pm2 de verdad y un servicio de juguete.

npm test                      # 115 tests unitarios
npm run utiles:aceptacion     # 41 comprobaciones contra pm2 real (monta y borra su banco)
npm run verificar             # higiene pública con historial + tests. Antes de publicar

La prueba que decide si esto sirve está en utiles/prueba-de-aceptacion.mjs: cambia una variable, hace pm2 restart —el comando equivocado— y comprueba que el agente detecta la divergencia; luego pm2 startOrRestart y comprueba que desaparece.

El despliegue (v1) sigue diseñado por escrito y sin implementar, en docs/V1-DESPLIEGUE.md.

Licencia

MIT. Ver LICENSE.