# zammad-mcp

MCP server para acessar a API do Zammad `https://chamados.pop-rr.rnp.br`.

## Tools expostas

| Tool | Descrição |
|------|-----------|
| `zammad_ticket_search` | Busca chamados (sintaxe de busca do Zammad) |
| `zammad_ticket_get` | Detalhes de um chamado (com artigos/histórico) |
| `zammad_ticket_create` | Cria um novo chamado |
| `zammad_ticket_update` | Atualiza estado/prioridade/grupo/responsável |
| `zammad_ticket_add_article` | Adiciona nota interna ou resposta a um chamado |
| `zammad_user_search` | Busca usuários (agentes/clientes) |
| `zammad_user_get` | Detalhes de um usuário |
| `zammad_organization_search` | Busca organizações |
| `zammad_group_list` | Lista os grupos (filas) de chamados |

`zammad_ticket_create`/`zammad_ticket_update` aceitam tanto o nome (`group`, `state`,
`priority`) quanto o id (`group_id`, `state_id`, `priority_id`) — o Zammad resolve nomes
nesses campos automaticamente. Em `article.internal`/`internal` (add_article e create), o
default é `true` (nota interna, não visível ao cliente) **independente** de `type` — para
enviar um e-mail ao cliente, informe `internal: false` explicitamente.

## Configuração

| Variável | Descrição | Default |
|----------|-----------|---------|
| `ZAMMAD_URL` | Base URL da instância Zammad (sem `/api/v1`) | — (obrigatório) |
| `ZAMMAD_TOKEN_FILE` | Caminho do arquivo do token | `/run/zammad/token` |
| `ZAMMAD_TOKEN` | Token da API direto por env (a imagem grava no `ZAMMAD_TOKEN_FILE`) | — |
| `MCP_PORT` | Porta do endpoint HTTP (só na imagem Docker) | `8000` |
| `MCP_PATH` | Caminho do endpoint streamable-HTTP (só na imagem) | `/mcp` |
| `NODE_TLS_REJECT_UNAUTHORIZED` | Setar `0` se a instância usar certificado autoassinado (ex.: mkcert) | — |

Forneça o token por **`ZAMMAD_TOKEN_FILE`** (arquivo/secret montado) **ou** por
**`ZAMMAD_TOKEN`** (env) — a imagem materializa o env num arquivo no start. `unset
ZAMMAD_TOKEN` no entrypoint tira o valor do ambiente do processo, mas **não** o esconde de
`docker inspect`/Portainer quando fornecido como env var na stack (é metadado do container,
não do processo) — se isso for uma preocupação, use secret de swarm (`ZAMMAD_TOKEN_FILE`
apontando para um arquivo montado) em vez de env var.

## Build & Run (local, stdio)

```bash
npm install
npm run build
npm test
ZAMMAD_URL=https://sua-instancia.example.com ZAMMAD_TOKEN_FILE=$(pwd)/.token node dist/index.js
```

## Docker (streamable-HTTP via supergateway)

A imagem embute o servidor + `supergateway`, expondo o MCP em `:8000/mcp`.

```bash
docker build -t ghcr.io/marcelofmatos/zammad-mcp:local .
docker run --rm -p 8000:8000 \
  -e ZAMMAD_URL=https://sua-instancia.example.com \
  -e ZAMMAD_TOKEN=xxxxxxxx \
  ghcr.io/marcelofmatos/zammad-mcp:local
# health: curl localhost:8000/health   |   MCP: http://localhost:8000/mcp
```

Imagens publicadas no GHCR pelo workflow **`Release and build`** (dispatch manual;
versiona SemVer via tags e dá push em `ghcr.io/marcelofmatos/zammad-mcp`).

## Deploy no bot Apolo (PoP-RR)

Roda como serviço `zammad-poprr` na stack `mcp-servers-anton` (rede `anton-mcp`), registrado
no `mcp.json` do bot como:

```json
"zammad-poprr": { "type": "http", "url": "http://zammad-poprr:8080/mcp" }
```

Detalhes completos (compose do serviço, envs da stack, passos de deploy) na spec local em
`docs/superpowers/specs/2026-07-26-zammad-mcp-design.md` (não versionada neste repositório).