Kalymos Hoag

Servidor MCP (Model Context Protocol) de leitura do ecossistema Kalymos Global. 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: 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.

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.

Related MCP server: server-ops-mcp

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

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

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

Contexto mais amplo

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