Jenkins

Um servidor para integração com Jenkins CI/CD para gerenciar e acionar builds.

Documentação

@grec0/mcp-jenkins

Servidor MCP para operar Jenkins a partir de clientes compatíveis com Model Context Protocol, como VS Code, Claude Desktop ou outros agentes. Permite consultar jobs, lançar builds, aguardar que terminem, revisar logs, inspecionar stages de pipelines, gerenciar approvals, consultar artifacts/cobertura e administrar jobs sem entrar na UI do Jenkins.

O Que Você Pode Fazer

Listar jobs, multibranch projects e ramos.
Consultar estado, configuração e último build de um job.
Lançar builds com ou sem parâmetros.
Aguardar de forma bloqueante até que um build termine.
Ver histórico de builds, logs, stages, nós e ações pendentes.
Parar builds com confirmação explícita.
Fazer rebuild/replay se o Jenkins tiver os endpoints/plugins necessários.
Criar, atualizar, habilitar, desabilitar ou excluir jobs usando confirmações de segurança.
Consultar relatórios de cobertura quando o job os publicar.

Quick Start

Requisitos

Node.js 18 ou superior.
URL do Jenkins acessível a partir da máquina onde o cliente MCP é executado.
Usuário do Jenkins com permissões suficientes.
API token ou senha do Jenkins.

Use API tokens quando possível. Não guarde credenciais reais em repositórios nem compartilhe configurações com segredos.

Configuração Recomendada Com 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 fixar uma versão concreta, troque @latest por uma versão publicada:

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

Instalação Global Opcional

npm install -g @grec0/mcp-jenkins

Configuração usando o binário 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"
      }
    }
  }
}

Conceitos Básicos

`fullName`

A maioria das ferramentas novas usa fullName, que é o caminho lógico do job no Jenkins.

Exemplos:

Grec0AI_backend_sb
Grec0AI_backend_sb/main
folder/backend/main

Em um multibranch project, normalmente o primeiro nível é o projeto e o segundo nível é o ramo. Por exemplo, se o Jenkins mostrar:

Grec0AI_backend_sb / main

o fullName geralmente é:

Grec0AI_backend_sb/main

`app` e `branch`

As tools antigas usam app e branch. Continuam disponíveis por compatibilidade, mas para uso novo recomenda-se usar os managers baseados em fullName.

Managers vs Tools Simples

Use jenkins_job_manager para jobs e pipelines.
Use jenkins_build_manager para execuções/builds.
Use jenkins_wait_for_build quando um agente precisar aguardar o Jenkins antes de continuar.
Use jenkins_pipeline_monitor para stages, nós e inputs pendentes.
Use as tools jenkins_get_*, jenkins_start_job e jenkins_stop_job se você já tiver prompts antigos baseados em app e branch.

Fluxos Recomendados

Descobrir Jobs

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

Tool: jenkins_job_manager

Listar Ramos De Um Multibranch Project

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

Tool: jenkins_job_manager

Lançar Um Build E Aguardar Que Termine

Inicie o build.

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

Tool: jenkins_build_manager

Liste builds para identificar o número iniciado.

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

Tool: jenkins_build_manager

Aguarde até que o Jenkins termine.

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

Tool: jenkins_wait_for_build

Somente depois de receber completed: true, revise logs, stages ou execute validações dependentes do build.

Revisar Uma Falha

{
  "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

Aprovar Ou Rejeitar Um Input Pendente

Consulte inputs pendentes.

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

Tool: jenkins_pipeline_monitor

Envie a decisão usando a proceedUrl ou abortUrl devolvida pelo Jenkins.

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

Tool: jenkins_pipeline_monitor

Tools

`jenkins_job_manager`

Gerencia jobs e pipelines usando caminhos fullName.

Ações:

Ação	Descrição
`list`	Lista jobs do root ou de um folder/multibranch project.
`get`	Obtém detalhe de um job.
`get_config`	Devolve o `config.xml` de um job.
`create_pipeline`	Cria um job/pipeline a partir de XML.
`update_config`	Atualiza `config.xml`; requer `confirmName`.
`delete`	Exclui um job; requer `confirmName`.
`enable`	Habilita um job; requer `confirmName`.
`disable`	Desabilita um job; requer `confirmName`.
`get_branches`	Lista ramos usando o fluxo legacy baseado em `app`.

Parâmetros:

Parâmetro	Uso
`action`	Ação a executar.
`fullName`	Caminho do job, por exemplo `folder/job/main`.
`folder`	Folder ou multibranch project a partir do qual listar.
`query`	Filtro por texto para `list`.
`limit`	Máximo de resultados para `list`.
`configXml`	XML completo para criar ou atualizar jobs.
`confirmName`	Confirmação exata para ações protegidas.
`app`	Nome de aplicação para `get_branches`.

Exemplos:

{
  "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`

Gerencia execuções do Jenkins.

Ações:

Ação	Descrição
`list`	Lista builds recentes de um job.
`get`	Obtém detalhe de um build.
`start`	Inicia um build, opcionalmente com parâmetros.
`wait`	Aguarda até que um build termine ou atinja timeout.
`stop`	Para um build; requer `confirmBuild`.
`rebuild`	Solicita reconstrução se o Jenkins expuser o endpoint.
`replay`	Solicita replay se o Jenkins expuser o endpoint.
`console`	Devolve logs de console.
`artifacts`	Lista artifacts arquivados com URLs.

Parâmetros:

Parâmetro	Uso
`action`	Ação a executar.
`fullName`	Caminho do job.
`buildNumber`	Número de build para ações sobre uma execução.
`parameters`	Parâmetros para `buildWithParameters`.
`pollIntervalSeconds`	Intervalo entre consultas para `wait`.
`timeoutSeconds`	Tempo máximo de espera para `wait`.
`includeStages`	Inclui stages ao terminar o build.
`limit`	Quantidade de builds ou caracteres de log.
`start`	Offset para logs progressivos.
`confirmBuild`	Confirmação exata para `stop`.

Exemplos:

{
  "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 precisam bloquear o fluxo até que o Jenkins termine um build. A chamada responde quando o build finaliza, quando o timeout é atingido ou quando o Jenkins entra em uma pausa manual (input) que requer aprovação.

Parâmetros:

Parâmetro	Default	Descrição
`fullName`	Obrigatório	Caminho do job.
`buildNumber`	Obrigatório	Número de build a aguardar.
`pollIntervalSeconds`	`10`	Segundos entre consultas. Mínimo efetivo: 2. Máximo efetivo: 120.
`timeoutSeconds`	`1800`	Timeout total. Máximo efetivo: 86400.
`includeStages`	`true`	Inclui stages ao terminar se o job expuser Pipeline REST API.

Exemplo:

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

Resposta esperada:

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

Se o Jenkins ficar pausado aguardando aprovação manual, a tool devolve waitingForInput: true, o objeto pendingInput com proceedUrl/abortUrl e um nextStep com a chamada exata a jenkins_submit_input_action.

Se timedOut for true, o build ainda estava rodando quando o timeout foi atingido.

`jenkins_pipeline_monitor`

Inspeciona detalhes específicos de pipelines.

Ações:

Ação	Descrição
`steps`	Devolve stages do build.
`node`	Devolve detalhe de um nó/stage por `nodeId`.
`pending_inputs`	Devolve input actions pendentes.
`submit_input`	Envia uma decisão usando `decisionUrl`.

Exemplos:

{
  "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 E Compatibilidade

Estas tools continuam disponíveis para prompts antigos ou fluxos simples baseados em app e branch.

Tool	Uso
`jenkins_get_job_status`	Estado de um job por `app` e `branch`.
`jenkins_start_job`	Inicia um job com um ramo.
`jenkins_stop_job`	Para um build por `app`, `branch` e `buildNumber`.
`jenkins_get_build_steps`	Stages de um build.
`jenkins_get_node_status`	Estado de um nó de pipeline.
`jenkins_get_pending_actions`	Input actions pendentes.
`jenkins_submit_input_action`	Envia approval/reject usando uma URL do Jenkins.
`jenkins_get_coverage_report`	Resumo de cobertura.
`jenkins_get_coverage_lines`	Cobertura de um arquivo.
`jenkins_get_coverage_paths`	Paths com cobertura disponível.
`jenkins_get_git_branches`	Ramos Git disponíveis para um job legacy.

Exemplo legacy:

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

Operações Protegidas

Algumas ações podem alterar ou destruir configuração no Jenkins. O MCP exige confirmação explícita.

Ação	Confirmação
`jenkins_job_manager.update_config`	`confirmName` deve ser igual a `fullName`.
`jenkins_job_manager.delete`	`confirmName` deve ser igual a `fullName`.
`jenkins_job_manager.enable`	`confirmName` deve ser igual a `fullName`.
`jenkins_job_manager.disable`	`confirmName` deve ser igual a `fullName`.
`jenkins_build_manager.stop`	`confirmBuild` deve ser igual a `buildNumber`.

Recomendação: teste primeiro create_pipeline, update_config e delete em um job temporário.

Requisitos Do Jenkins

Funcionalidade disponível com Jenkins core:

Listar jobs.
Consultar job/build.
Iniciar builds.
Parar builds.
Ler logs.
Ler e atualizar config.xml se o usuário tiver permissões.
Listar artifacts arquivados.

Plugins recomendados para funcionalidade completa:

Plugin	Para Que Serve
`pipeline-rest-api`	Stages, nós e input actions de pipelines.
`git-parameter`	Listagem de ramos em tools legacy.
`jacoco`	Cobertura backend Java.
Cobertura frontend/Istanbul	Cobertura frontend se o job publicar o ZIP esperado.

Consulte JENKINS_REQUIREMENTS.md para detalhes de plugins, endpoints e erros comuns.

Respostas E Limites

As tools devolvem JSON serializado como conteúdo de texto MCP.
console pode limitar logs com limit para evitar respostas enormes.
artifacts devolve metadata e URLs; não baixa binários por padrão.
coverage depende muito de como o job publica seus relatórios.
jenkins_wait_for_build mantém a chamada aberta até fim de build, timeout ou pausa manual com input pendente; ajuste timeoutSeconds para builds longos.

Troubleshooting

`ERR_MODULE_NOT_FOUND` com `zod-to-json-schema`

Se você vir um erro parecido com:

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

use uma versão recente do pacote e preferencialmente inicie com --package:

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

Se npx ficou com uma instalação temporária contaminada, exclua a pasta _npx que aparece no stacktrace ou limpe o cache do npm.

`401` O `403`

Revise JENKINS_USERNAME, JENKINS_PASSWORD, API token e permissões do usuário no Jenkins.

`404` Em `/wfapi/describe`

O job pode não ser Pipeline ou pode faltar o plugin pipeline-rest-api.

Não Encontro O `fullName`

Primeiro liste jobs a partir do root:

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

Depois liste dentro do multibranch project:

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

`jenkins_wait_for_build` Esgota Timeout

O build ainda estava rodando. Aumente timeoutSeconds, revise logs com console ou consulte o build com jenkins_build_manager get. Se a resposta incluir waitingForInput: true, aprove ou aborte com jenkins_submit_input_action usando a decisionUrl devolvida.

Desenvolvimento Local

Esta seção é apenas para quem quiser modificar o pacote.

npm install
npm run build
npm test
npm run prerelease

Não publique uma versão nova sem executar npm run prerelease.

Licença

MIT

Jenkins

Documentação

@grec0/mcp-jenkins

O Que Você Pode Fazer

Quick Start

Requisitos

Configuração Recomendada Com npx

Instalação Global Opcional

Conceitos Básicos

fullName

app e branch

Managers vs Tools Simples

Fluxos Recomendados

Descobrir Jobs

Listar Ramos De Um Multibranch Project

Lançar Um Build E Aguardar Que Termine

Revisar Uma Falha

Aprovar Ou Rejeitar Um Input Pendente

Tools

jenkins_job_manager

jenkins_build_manager

jenkins_wait_for_build

jenkins_pipeline_monitor

Tools Simples E Compatibilidade

Operações Protegidas

Requisitos Do Jenkins

Respostas E Limites

Troubleshooting

ERR_MODULE_NOT_FOUND com zod-to-json-schema

401 O 403

404 Em /wfapi/describe

Não Encontro O fullName

jenkins_wait_for_build Esgota Timeout

Desenvolvimento Local

Licença

`fullName`

`app` e `branch`

`jenkins_job_manager`

`jenkins_build_manager`

`jenkins_wait_for_build`

`jenkins_pipeline_monitor`

`ERR_MODULE_NOT_FOUND` com `zod-to-json-schema`

`401` O `403`

`404` Em `/wfapi/describe`

Não Encontro O `fullName`

`jenkins_wait_for_build` Esgota Timeout