mcp-jenkins-pipeline 1.0.0

= Projeto mcp-jenkins-pipeline

Servidor MCP do Jenkins. Expõe como tools MCP as capacidades de consulta e operação no
Jenkins: detecção de build por commit, status, listagem de builds, console, artefatos,
navegação de multibranch (branches) e o input step de promoção.

É consumido por um cliente MCP (ex.: um Kiro Power) via `uvx`. O cliente sobe este servidor
como um processo e conversa com ele pelo protocolo MCP; você não o executa manualmente no
dia a dia (exceto para desenvolver/testar). Distribuído no PyPI como `mcp-jenkins-pipeline`.

== Pré-requisitos

* Python >= 3.10.
* Uma destas opções para rodar/instalar:
** https://docs.astral.sh/uv/getting-started/installation/[uv] (recomendado — resolve o
   ambiente automaticamente), ou
** `venv` + `pip` (vem com o próprio Python: `python -m venv`).

== Instalação (como cliente MCP)

Este servidor é feito para ser iniciado por um cliente MCP (ex.: Kiro). Registre-o no
`mcp.json` do cliente. Forma publicada no PyPI:

[source,json]
----
{
  "mcpServers": {
    "jenkins": {
      "command": "uvx",
      "args": ["mcp-jenkins-pipeline"]
    }
  }
}
----

Para rodar a partir do código local (sem publicar), aponte o `uvx` para o diretório do
projeto:

[source,json]
----
{
  "mcpServers": {
    "jenkins": {
      "command": "uvx",
      "args": ["--from", "/caminho/para/mcp-jenkins-pipeline", "mcp-jenkins-pipeline"]
    }
  }
}
----

Repare que os exemplos acima *não* trazem um bloco `env`: as variáveis de ambiente
(inclusive o `JENKINS_TOKEN`) devem ficar no arquivo `.env`, que o servidor carrega
automaticamente na inicialização. É o caminho recomendado — veja a seção
_Configuração via arquivo `.env`_ abaixo e configure-o antes de usar o servidor.

[WARNING]
====
Evite colocar `JENKINS_TOKEN` (ou qualquer segredo) no bloco `env` do `mcp.json`: esse
arquivo costuma ser versionado, o que exporia o token. Mantenha os segredos no `.env`.
====

Para fixar uma versão específica, use `uvx mcp-jenkins-pipeline==1.0.0`.

== Configuração (variáveis de ambiente)

[cols="<,^,<,<"]
|===
| Variável | Obrigatória | Default | Descrição

| `JENKINS_URL`          | sim | — | URL base do Jenkins
| `JENKINS_USERNAME`     | sim | — | usuário para HTTP Basic
| `JENKINS_TOKEN`        | sim | — | token de API para HTTP Basic
| `JENKINS_JOB_DEFAULT`  | não | — | job padrão (caminho completo) usado quando a tool é chamada sem `job`
| `JENKINS_VERIFY_SSL`   | não | `true`  | verificar certificado TLS
| `JENKINS_TIMEOUT`      | não | `30`    | timeout HTTP (segundos)
| `JENKINS_READ_ONLY`    | não | `false` | se `true`, oculta e desativa as tools de escrita (`write`), deixando só as de leitura
| `JENKINS_MCP_ENV_FILE` | não | — | caminho de um `.env` alternativo (ver abaixo)
|===

A forma recomendada de definir essas variáveis é o arquivo `.env` (veja a seção seguinte),
que mantém o token fora de arquivos versionados. O servidor também lê variáveis já presentes
no ambiente do processo (ex.: um bloco `env` do `mcp.json`), mas *não* coloque segredos como
o `JENKINS_TOKEN` ali — reserve o `mcp.json`, no máximo, para valores não sensíveis.

== Configuração via arquivo `.env` (recomendado)

O servidor carrega, na inicialização, um arquivo `.env` com as variáveis acima. Isso evita
colocar o token no `mcp.json` (que é versionado). *Precedência:* uma variável já definida no
ambiente do processo vence o valor do `.env` — o arquivo só preenche o que falta.

=== Onde fica o `.env`

Por padrão, em *`~/.mcp/jenkins/.env`*. Para usar outro caminho, defina
`JENKINS_MCP_ENV_FILE` com o caminho desejado.

[cols="<,<"]
|===
| Sistema | Caminho padrão do `.env`

| Linux / WSL (Ubuntu) | `~/.mcp/jenkins/.env`
| Windows nativo       | `C:\Users\<você>\.mcp\jenkins\.env`
|===

[NOTE]
====
O `.env` vai no `~/.mcp/jenkins/` do *ambiente onde o Kiro/servidor roda*. Se o seu
Kiro roda dentro do WSL, use o `~` do WSL; se roda no Windows nativo, use o do Windows.
====

=== Criando o `.env`

A partir do `.env.example` deste diretório (comandos para Linux / WSL):

[source,bash]
----
mkdir -p ~/.mcp/jenkins
cp .env.example ~/.mcp/jenkins/.env
chmod 600 ~/.mcp/jenkins/.env     # contém o token: restrinja a leitura
$EDITOR ~/.mcp/jenkins/.env       # preencha JENKINS_URL, JENKINS_USERNAME e JENKINS_TOKEN
----

[NOTE]
====
No *Windows nativo* (sem WSL), os comandos acima não se aplicam: crie manualmente o
arquivo em `%USERPROFILE%\.mcp\jenkins\.env` (copiando o `.env.example`) e edite-o no seu
editor, preenchendo `JENKINS_URL`, `JENKINS_USERNAME` e `JENKINS_TOKEN`.
====

[WARNING]
====
*Nunca* versione o `.env` real (ele tem o token). O `.gitignore` já ignora `.env`;
apenas o `.env.example` (sem segredo) é versionado.
====

== Tools

As tools são marcadas com tags `read` (consulta) e `write` (ação). Em modo read-only
(`JENKINS_READ_ONLY=true`), as tools `write` ficam desabilitadas (não aparecem na listagem
e não executam).

A maioria das tools aceita o parâmetro opcional `job` (caminho completo do job); quando
omitido, usa-se o `JENKINS_JOB_DEFAULT`. A `jenkins_listar_branches` usa o parâmetro
`multibranch` da mesma forma, mas o valor deve apontar para um multibranch pipeline.

[cols="<,^,<"]
|===
| Tool | Tag | Descrição

| `jenkins_ping`                      | `read`  | Verifica se o servidor MCP está no ar (responde `pong`).
| `jenkins_listar_branches`           | `read`  | Lista as branches de um multibranch pipeline (nome, status e último build).
| `jenkins_listar_builds_recentes`    | `read`  | Lista os builds mais recentes de um job (número, status, url).
| `jenkins_encontrar_build_por_commit`| `read`  | Localiza o build cujo changeset contém o commit informado.
| `jenkins_ultimo_build`              | `read`  | Retorna as informações do último build de um job.
| `jenkins_status_build`              | `read`  | Consulta o status atual de um build específico.
| `jenkins_listar_estagios_build`     | `read`  | Lista os stages (estágios) da pipeline de um build.
| `jenkins_obter_input_pendente`      | `read`  | Consulta o input step de promoção pendente de um build.
| `jenkins_listar_artefatos_build`    | `read`  | Lista os artefatos arquivados em um build (no próprio Jenkins).
| `jenkins_console_output`            | `read`  | Lê o console output de um build (com filtro, offset e limite opcionais).
| `jenkins_responder_input_promocao`  | `write` | Responde o input de promoção selecionando artefatos (equivale a "Publicar!").
| `jenkins_abortar_input_promocao`    | `write` | Aborta o input de promoção pendente de um build (equivale a "Abort").
|===

== Rodar (desenvolvimento)

Há dois caminhos: `uv` (mais rápido) ou um `venv` explícito.

=== Com uv

A partir da raiz do projeto:

[source,bash]
----
uvx --from . mcp-jenkins-pipeline
----

Depois de publicado no PyPI, basta:

[source,bash]
----
uvx mcp-jenkins-pipeline
----

=== Com venv + pip

[source,bash]
----
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e .
mcp-jenkins-pipeline
----

== Testes

Com venv (caminho completo de setup):

[source,bash]
----
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                             # ou: .venv/bin/pytest
----

Alternativa com uv (resolve o ambiente automaticamente):

[source,bash]
----
uv run pytest
----

== Publicação (PyPI)

O pacote é distribuído no PyPI como `mcp-jenkins-pipeline` (licença MPL-2.0).

[source,bash]
----
uv build                 # gera dist/mcp_jenkins_pipeline-<versão>-*.whl e .tar.gz
uv publish               # publica no PyPI (requer credenciais; passo manual)
----

Depois de publicado, os consumidores usam a versão pinada:

[source,bash]
----
uvx mcp-jenkins-pipeline==1.0.0
----

[NOTE]
====
O `uv publish` é um passo *manual* do mantenedor — exige credenciais do PyPI e é
irreversível (o PyPI não permite reusar o par nome+versão depois de publicado).
====

== Builds

[cols="^1,^1,<1"]
|===
| Branch | Versão | Status
| https://scm.prevnet/padroes-dev/mcp-jenkins-pipeline/tree/desenvolvimento[desenvolvimento]
| 1.0.0
| image:https://www-ci.prevnet/job/DATAPREV/job/dipb_padroes-dev-mcp-jenkins-pipeline/job/desenvolvimento/badge/icon[Build Status, link=https://www-ci.prevnet/job/DATAPREV/job/dipb_padroes-dev-mcp-jenkins-pipeline/job/desenvolvimento/]

| https://scm.prevnet/padroes-dev/mcp-jenkins-pipeline/tree/entrega[entrega]
| 1.0.0
| image:https://www-ci.prevnet/job/DATAPREV/job/dipb_padroes-dev-mcp-jenkins-pipeline/job/entrega/badge/icon[Build Status, link=https://www-ci.prevnet/job/DATAPREV/job/dipb_padroes-dev-mcp-jenkins-pipeline/job/entrega/]

| https://scm.prevnet/padroes-dev/mcp-jenkins-pipeline/tree/incidente[incidente]
| 1.0.0
| image:https://www-ci.prevnet/job/DATAPREV/job/dipb_padroes-dev-mcp-jenkins-pipeline/job/incidente/badge/icon[Build Status, link=https://www-ci.prevnet/job/DATAPREV/job/dipb_padroes-dev-mcp-jenkins-pipeline/job/incidente/]

| https://scm.prevnet/padroes-dev/mcp-jenkins-pipeline/tree/master[master]
| 1.0.0
| image:https://www-ci.prevnet/job/DATAPREV/job/dipb_padroes-dev-mcp-jenkins-pipeline/job/master/badge/icon[Build Status, link=https://www-ci.prevnet/job/DATAPREV/job/dipb_padroes-dev-mcp-jenkins-pipeline/job/master/]
|===

== Documentação de apoio
* http://www-hub.prevnet/gui-entrega-continua/gui-entrega-continua.html[Guia de Integração e Entrega contínua]
* https://www-ci.prevnet/job/DATAPREV/job/dipb_padroes-dev-mcp-jenkins-pipeline[Pipeline]
* http://www-bin.prevnet[Nexus]
* http://www-qa.prevnet[SonarQube Releases]
* http://www-dqa.prevnet[SonarQube Checkin]
* https://chat.dataprev.gov.br/channel/dtp-ic-ec[Dúvidas sobre Jenkins e Sonar]
* https://chat.dataprev.gov.br/channel/dtp-git[Dúvidas sobre GIT]
* https://asciidoctor.org/docs/#write-with-asciidoctor[Documentação Asciidoc]