Metadata-Version: 2.5
Name: jenkins-mcp-toolkit
Version: 0.4.0
Summary: Servidor MCP do Jenkins: consulta de builds, detecção por commit, navegação de multibranch e input de promoção.
Author: Pedro Calixto
License-Expression: MPL-2.0
License-File: LICENSE
Keywords: ci,jenkins,mcp,model-context-protocol
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Requires-Dist: fastmcp>=4.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.31
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# jenkins-mcp-toolkit

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 Kiro Power via `uvx`.

## Rodar (desenvolvimento)

A partir da raiz do projeto:

```bash
uvx --from . jenkins-mcp-toolkit
```

Depois de publicado no PyPI, basta:

```bash
uvx jenkins-mcp-toolkit
```

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

| 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`, só as tools de leitura ficam ativas |
| `JENKINS_MCP_ENV_FILE` | não | — | caminho de um `.env` alternativo (ver abaixo) |

As variáveis podem vir do ambiente do processo (ex.: do `env` do `mcp.json`) **ou** de um
arquivo `.env` que o servidor carrega automaticamente (recomendado — mantém o token fora de
arquivos versionados). Veja a seção seguinte.

## 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`** (uniforme nos três sistemas). Para usar outro
caminho, defina `JENKINS_MCP_ENV_FILE` com o caminho desejado.

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

> Regra: 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.

### Setup

A partir do `.env.example` deste diretório:

```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_USERNAME e JENKINS_TOKEN
```

> ⚠️ **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.

## Testes

```bash
.venv/bin/pytest        # ou: uv run pytest
```

## Publicação (PyPI)

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

```bash
uv build                 # gera dist/jenkins_mcp_toolkit-<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:

```bash
uvx jenkins-mcp-toolkit==0.4.0
```

> 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).
