Jenkins管理工具

@grec0/mcp-jenkins

MCP server para operar Jenkins desde clientes compatibles con Model Context Protocol, como VS Code, Claude Desktop u otros agentes. Permite consultar jobs, lanzar builds, esperar a que terminen, revisar logs, inspeccionar stages de pipelines, gestionar approvals, consultar artifacts/cobertura y administrar jobs sin entrar en la UI de Jenkins.

Que Puedes Hacer

• Listar jobs, multibranch projects y ramas.
• Consultar estado, configuracion y ultimo build de un job.
• Lanzar builds con o sin parametros.
• Esperar de forma bloqueante hasta que un build termine.
• Ver historial de builds, logs, stages, nodos y acciones pendientes.
• Detener builds con confirmacion explicita.
• Hacer rebuild/replay si Jenkins tiene los endpoints/plugins necesarios.
• Crear, actualizar, habilitar, deshabilitar o borrar jobs usando confirmaciones de seguridad.
• Consultar reportes de cobertura cuando el job los publique.

Quick Start

Requisitos

• Node.js 18 o superior.
• URL de Jenkins accesible desde la maquina donde corre el cliente MCP.
• Usuario de Jenkins con permisos suficientes.
• API token o password de Jenkins.

Usa API tokens cuando sea posible. No guardes credenciales reales en repositorios ni compartas configuraciones con secretos.

Configuracion Recomendada Con npx

{
  "servers": {
    "jenkins": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "--package", "@grec0/mcp-jenkins@latest", "mcp-jenkins"],
      "env": {
        "JENKINS_URL": "https://tu-jenkins.com/jenkins",
        "JENKINS_USERNAME": "tu-usuario",
        "JENKINS_PASSWORD": "tu-api-token"
      }
    }
  }
}

Para fijar una version concreta, cambia @latest por una version publicada:

"args": ["-y", "--package", "@grec0/mcp-jenkins@0.2.2", "mcp-jenkins"]

Instalacion Global Opcional

npm install -g @grec0/mcp-jenkins

Configuracion usando el binario global:

{
  "servers": {
    "jenkins": {
      "type": "stdio",
      "command": "mcp-jenkins",
      "env": {
        "JENKINS_URL": "https://tu-jenkins.com/jenkins",
        "JENKINS_USERNAME": "tu-usuario",
        "JENKINS_PASSWORD": "tu-api-token"
      }
    }
  }
}

Conceptos Basicos

fullName

La mayoria de herramientas nuevas usan fullName, que es la ruta logica del job en Jenkins.

Ejemplos:

Grec0AI_backend_sb
Grec0AI_backend_sb/main
folder/backend/main

En un multibranch project, normalmente el primer nivel es el proyecto y el segundo nivel es la rama. Por ejemplo, si Jenkins muestra:

Grec0AI_backend_sb / main

el fullName suele ser:

Grec0AI_backend_sb/main

app y branch

Las tools antiguas usan app y branch. Siguen disponibles por compatibilidad, pero para uso nuevo se recomienda usar los managers basados en fullName.

Managers vs Tools Simples

• Usa jenkins_job_manager para jobs y pipelines.
• Usa jenkins_build_manager para ejecuciones/builds.
• Usa jenkins_wait_for_build cuando un agente deba esperar a Jenkins antes de continuar.
• Usa jenkins_pipeline_monitor para stages, nodos e inputs pendientes.
• Usa las tools jenkins_get_*, jenkins_start_job y jenkins_stop_job si ya tienes prompts antiguos basados en app y branch.

Flujos Recomendados

Descubrir Jobs

{
  "action": "list",
  "limit": 20
}

Tool: jenkins_job_manager

Listar Ramas De Un Multibranch Project

{
  "action": "list",
  "folder": "Grec0AI_backend_sb",
  "limit": 20
}

Tool: jenkins_job_manager

Lanzar Un Build Y Esperar A Que Termine

1. Inicia el build.

{
  "action": "start",
  "fullName": "Grec0AI_backend_sb/main"
}

Tool: jenkins_build_manager

2. Lista builds para identificar el numero iniciado.

{
  "action": "list",
  "fullName": "Grec0AI_backend_sb/main",
  "limit": 5
}

Tool: jenkins_build_manager

3. Espera hasta que Jenkins termine.

{
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "pollIntervalSeconds": 10,
  "timeoutSeconds": 1800,
  "includeStages": true
}

Tool: jenkins_wait_for_build

4. Solo despues de recibir completed: true, revisa logs, stages o ejecuta validaciones dependientes del build.

Revisar Un Fallo

{
  "action": "console",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "limit": 8000
}

Tool: jenkins_build_manager

{
  "action": "steps",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298
}

Tool: jenkins_pipeline_monitor

Aprobar O Rechazar Un Input Pendiente

1. Consulta inputs pendientes.

{
  "action": "pending_inputs",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298
}

Tool: jenkins_pipeline_monitor

2. Envia la decision usando la proceedUrl o abortUrl devuelta por Jenkins.

{
  "action": "submit_input",
  "decisionUrl": "https://tu-jenkins.com/jenkins/job/.../proceedEmpty"
}

Tool: jenkins_pipeline_monitor

Tools

jenkins_job_manager

Gestiona jobs y pipelines usando rutas fullName.

Acciones:

Parametros:

Ejemplos:

{
  "action": "list",
  "query": "backend",
  "limit": 20
}

{
  "action": "get",
  "fullName": "Grec0AI_backend_sb/main"
}

{
  "action": "get_config",
  "fullName": "Grec0AI_backend_sb/main"
}

{
  "action": "update_config",
  "fullName": "sandbox/test-pipeline",
  "configXml": "<flow-definition>...</flow-definition>",
  "confirmName": "sandbox/test-pipeline"
}

{
  "action": "delete",
  "fullName": "sandbox/test-pipeline",
  "confirmName": "sandbox/test-pipeline"
}

jenkins_build_manager

Gestiona ejecuciones de Jenkins.

Acciones:

Parametros:

Ejemplos:

{
  "action": "list",
  "fullName": "Grec0AI_backend_sb/main",
  "limit": 10
}

{
  "action": "start",
  "fullName": "Grec0AI_backend_sb/main",
  "parameters": {
    "DEPLOY_ENV": "dev"
  }
}

{
  "action": "wait",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "pollIntervalSeconds": 10,
  "timeoutSeconds": 1800,
  "includeStages": true
}

{
  "action": "console",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "limit": 12000
}

{
  "action": "stop",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "confirmBuild": 298
}

jenkins_wait_for_build

Tool dedicada para agentes que necesitan bloquear el flujo hasta que Jenkins termine un build. La llamada responde cuando el build finaliza, cuando se alcanza el timeout o cuando Jenkins entra en una pausa manual (input) que requiere aprobación.

Parametros:

Ejemplo:

{
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "pollIntervalSeconds": 10,
  "timeoutSeconds": 1800,
  "includeStages": true
}

Respuesta esperada:

{
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298,
  "completed": true,
  "timedOut": false,
  "waitedSeconds": 120,
  "pollCount": 13,
  "result": "SUCCESS",
  "build": { "number": 298 },
  "stages": []
}

Si Jenkins queda pausado esperando aprobación manual, la tool devuelve waitingForInput: true, el objeto pendingInput con proceedUrl/abortUrl y un nextStep con la llamada exacta a jenkins_submit_input_action.

Si timedOut es true, el build seguía corriendo cuando se alcanzó el timeout.

jenkins_pipeline_monitor

Inspecciona detalles especificos de pipelines.

Acciones:

Ejemplos:

{
  "action": "steps",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 296
}

{
  "action": "node",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 296,
  "nodeId": "20"
}

{
  "action": "pending_inputs",
  "fullName": "Grec0AI_backend_sb/main",
  "buildNumber": 298
}

{
  "action": "submit_input",
  "decisionUrl": "https://tu-jenkins.com/jenkins/job/.../proceedEmpty"
}

Tools Simples Y Compatibilidad

Estas tools siguen disponibles para prompts antiguos o flujos simples basados en app y branch.

Ejemplo legacy:

{
  "app": "mi-app",
  "branch": "main"
}

Operaciones Protegidas

Algunas acciones pueden cambiar o destruir configuracion en Jenkins. El MCP exige confirmacion explicita.

Recomendacion: prueba primero create_pipeline, update_config y delete en un job temporal.

Requisitos De Jenkins

Funcionalidad disponible con Jenkins core:

• Listar jobs.
• Consultar job/build.
• Iniciar builds.
• Detener builds.
• Leer logs.
• Leer y actualizar config.xml si el usuario tiene permisos.
• Listar artifacts archivados.

Plugins recomendados para funcionalidad completa:

Consulta JENKINS_REQUIREMENTS.md para detalle de plugins, endpoints y errores comunes.

Respuestas Y Limites

• Las tools devuelven JSON serializado como contenido de texto MCP.
• console puede limitar logs con limit para evitar respuestas enormes.
• artifacts devuelve metadata y URLs; no descarga binarios por defecto.
• coverage depende mucho de como el job publique sus reportes.
• jenkins_wait_for_build mantiene la llamada abierta hasta fin de build, timeout o pausa manual con input pendiente; ajusta timeoutSeconds para builds largos.

Troubleshooting

ERR_MODULE_NOT_FOUND con zod-to-json-schema

Si ves un error parecido a:

Cannot find module '.../zod-to-json-schema/dist/esm/parsers/record.js'

usa una version reciente del paquete y preferiblemente arranca con --package:

"args": ["-y", "--package", "@grec0/mcp-jenkins@latest", "mcp-jenkins"]

Si npx quedo con una instalacion temporal contaminada, borra la carpeta _npx que aparece en el stacktrace o limpia el cache de npm.

401 O 403

Revisa JENKINS_USERNAME, JENKINS_PASSWORD, API token y permisos del usuario en Jenkins.

404 En /wfapi/describe

El job puede no ser Pipeline o puede faltar el plugin pipeline-rest-api.

No Encuentro El fullName

Primero lista jobs desde el root:

{
  "action": "list",
  "limit": 50
}

Despues lista dentro del multibranch project:

{
  "action": "list",
  "folder": "nombre-del-proyecto",
  "limit": 50
}

jenkins_wait_for_build Agota Timeout

El build seguía corriendo. Sube timeoutSeconds, revisa logs con console o consulta el build con jenkins_build_manager get. Si la respuesta incluye waitingForInput: true, aprueba o aborta con jenkins_submit_input_action usando la decisionUrl devuelta.

Desarrollo Local

Esta seccion es solo para quienes quieran modificar el paquete.

npm install
npm run build
npm test
npm run prerelease

No publiques una version nueva sin ejecutar npm run prerelease.

Licencia

MIT