# Kalymos Hoag

Servidor MCP (Model Context Protocol) de leitura do ecossistema [Kalymos Global](https://github.com/GustavoVieiraDeAraujo). Dá a um agente de IA um jeito auditável e com escopo fixo de investigar o estado do servidor — sem precisar de acesso SSH.

Nome em referência ao [Hoag's Object](https://en.wikipedia.org/wiki/Hoag's_Object): uma galáxia-anel quase perfeita, com um núcleo protegido cercado por um anel externo bem definido e um gap limpo entre os dois. A metáfora: o Hoag é o anel — nada toca o núcleo (o servidor real) direto, tudo passa pela camada de ferramentas primeiro.

## Escopo (Fase 1 — só leitura)

Nenhuma ferramenta aqui muda estado do servidor. **Regra permanente do projeto: nenhuma ferramenta de shell/exec genérico existe, nem vai existir.** Toda ferramenta é uma função tipada, com um propósito específico.

| Ferramenta | O que faz |
|---|---|
| `list_containers` | Lista todos os containers do servidor, com status e saúde |
| `get_container_logs` | Últimas linhas de log de um container (via Loki) |
| `get_health_summary` | Resumo geral: alvos monitorados, quais estão fora do ar, quantos alertas disparando |
| `get_recent_alerts` | Alertas disparando agora no Grafana |
| `get_waha_session_status` | Status da sessão do WhatsApp no WAHA |

Uma Fase 2 (ações com allowlist rígida, tipo reiniciar um container específico ou disparar um backup) fica pra depois de validar essa primeira fase em produção.

## Arquitetura

```
Agente de IA ──(Bearer token, via Tailscale + NPM)──► Kalymos Hoag
                                                            │
                              ┌─────────────────────────────┼─────────────────────────────┐
                              ▼                              ▼                              ▼
                    docker-socket-proxy            Loki + Grafana API              WAHA
                    (dedicado, só leitura)          (logs, alertas, saúde)   (status da sessão)
```

Rede isolada própria (`mcp_isolated`) com um `docker-socket-proxy` dedicado, ainda mais restrito que o do Jenkins — nem `POST`, nem `EXEC`, nem `VOLUMES`, só leitura de containers.

## Autenticação

Diferente do resto do stack (que fica atrás do Keycloak via oauth2-proxy — login de browser), o Hoag usa um **Bearer token** simples, porque quem consome é um agente de IA fazendo chamadas máquina-a-máquina, não um humano num browser. Mesmo padrão de chave já usado no resto do ecossistema (`WAHA_API_KEY` etc.).

## Stack

Node.js + TypeScript + Express + `@modelcontextprotocol/server` (v2, transporte Streamable HTTP). Comunicação com Loki/Grafana/WAHA via `fetch` nativo — sem SDK por cima do necessário.

## Testes

```bash
npm test
```

Vitest. Cobre o middleware de autenticação e cada ferramenta (com `fetch` mockado). Roda como estágio próprio (`Testes`) no pipeline, antes do build da imagem final.

## Rodando localmente

```bash
npm install
npm run build

HOAG_BEARER_TOKEN=um-token-qualquer \
GRAFANA_API_TOKEN=token-de-service-account-viewer \
WAHA_URL=http://localhost:3000 \
WAHA_API_KEY=sua-chave \
npm start
```

## Endpoints

| Rota | O que faz |
|---|---|
| `POST /mcp` | Endpoint MCP (Streamable HTTP) — exige `Authorization: Bearer <token>` |
| `GET /health` | Retorna `200` se o serviço está de pé |

## Contexto mais amplo

Faz parte do ecossistema Kalymos Global — ver `contextos/contexto-kalymos-global.md` no repo principal pra arquitetura completa do servidor.