equatorial-mcp

Servidor MCP comunitário e não oficial para consultar e baixar faturas da Equatorial.

Projeto comunitário, não oficial e sem afiliação com a Equatorial Energia.

Licença MIT. Veja LICENSE.

Escopo do v0.1.0

• Suporte somente a Goiás (EQUATORIAL_UF=GO). Outras UFs (por exemplo PA e MA) falham com UF_UNSUPPORTED antes de abrir o navegador.

• Três tools orientadas à intenção: listar_ucs, listar_faturas e baixar_fatura.

• O PDF da segunda via é exposto como Resource MCP (equatorial://faturas/{artifact_id}/pdf); capturas de diagnóstico usam equatorial://diagnosticos/{error_id}/screenshot.

• Operação local e determinística, sem LLM, sem OCR em nuvem, sem mensageria e sem agendamento.

• Uma instância representa uma única conta configurada. Não use como serviço multi-tenant.

• Nenhuma operação de pagamento é executada. O servidor apenas lista unidades consumidoras, lista faturas e baixa a segunda via em PDF com extração local.

Requisitos

• Node.js >=20.

• Chromium compatível via Puppeteer (dependência fixada no lockfile).

Instalação

A partir do tarball publicado:

npm install -g equatorial-mcp
equatorial-mcp

Uso local sem instalar:

npx -y equatorial-mcp

A partir do repositório:

npm ci
npm run build
npm pack --dry-run

Configuração do servidor no cliente

Os arquivos em examples/ configuram o transporte MCP e não contêm segredos: o servidor herda o ambiente privado do processo. Exemplos:

• Claude Code e Cursor usam o formato mcpServers — veja examples/mcp.json (command npx, args ["-y", "equatorial-mcp"], env vazio).

• OpenCode v2 usa o aninhamento mcp.servers com type: "local" e comando em array — veja examples/opencode.jsonc.

Prefira o escopo de usuário/local do cliente (nunca commite credenciais):

• Claude Code: registre o servidor no escopo de usuário e informe as cinco variáveis no armazenamento privado de ambiente do cliente ou no shell que o inicia.

• Cursor: coloque a entrada de examples/mcp.json no seu mcp.json de usuário e defina as variáveis fora do repositório.

• OpenCode: mescle a entrada de examples/opencode.jsonc sob mcp.servers no seu opencode.json de usuário ou do projeto, sem valores secretos.

Instalação da Skill

A Skill canônica é publicada em skills/equatorial-faturas/SKILL.md (dentro do repositório e do tarball NPM). A instalação é por cópia — nenhum postinstall escreve no seu home. Copie o diretório inteiro equatorial-faturas, para que futuras referências e anexos continuem junto do SKILL.md:

• Claude Code (projeto): .claude/skills/equatorial-faturas/SKILL.md

• Claude Code (usuário): ~/.claude/skills/equatorial-faturas/SKILL.md

• OpenCode (projeto): .opencode/skills/equatorial-faturas/SKILL.md

• OpenCode (usuário): ~/.config/opencode/skills/equatorial-faturas/SKILL.md

• Cursor (projeto): .cursor/skills/equatorial-faturas/SKILL.md ou o local compartilhado documentado .agents/skills/equatorial-faturas/SKILL.md

• Cursor (usuário): ~/.cursor/skills/equatorial-faturas/SKILL.md

Exemplo (projeto Claude Code, a partir da raiz do repositório):

mkdir -p .claude/skills
cp -r skills/equatorial-faturas .claude/skills/

Em atualizações, copie novamente por cima para manter a Skill sincronizada com o servidor.

Configuração

O binário não carrega .env automaticamente e não depende de dotenv: .env.example é apenas documentação. Exporte as variáveis no ambiente do processo ou na configuração privada do cliente MCP. Nunca cole CPF, nascimento, cookies ou códigos de pagamento em chamadas de tool.

export EQUATORIAL_UF=GO
export EQUATORIAL_UC='SUA_UC'
export EQUATORIAL_CPF='SEU_CPF'
export EQUATORIAL_NASCIMENTO='DD/MM/AAAA'
export HEADLESS='true'

Variáveis normativas:

Não há aliases: variáveis com outros nomes são ignoradas e segredos não têm flags CLI. EQUATORIAL_CPF exige 11 dígitos com dígitos verificadores válidos; EQUATORIAL_NASCIMENTO exige data real em DD/MM/AAAA; HEADLESS aceita somente true/false. EQUATORIAL_CPF aceita entrada formatada com pontuação (somente os dígitos são validados) e HEADLESS é insensível a maiúsculas/minúsculas com espaços aparados, com vazio/ausente assumindo true.

Transporte

• Padrão: stdio (stdin/stdout exclusivos do protocolo, diagnósticos em stderr).

• Opt-in local: --http serve POST /mcp e GET /healthz (responde {"status":"ok"}) somente em loopback. --host aceita apenas 127.0.0.1, ::1 ou localhost (padrão 127.0.0.1); --port define a porta (padrão 3000). --host e --port exigem --http, e binds não-loopback são recusados porque o v0.1.0 não tem autenticação HTTP multiusuário.

• Flags com aparência de segredo são recusadas: segredos entram somente pelo ambiente do processo.

npx -y equatorial-mcp --http --port 3000

Tools

Chamadas do mesmo perfil são serializadas: faça chamadas em série e não baixe todas as UCs por padrão.

Resultado estruturado e Resources

Toda tool devolve o valor canônico em structuredContent no envelope { "ok", "data", "error" }. Em sucesso, content traz um resumo curto e baixar_fatura acrescenta um bloco resource_link. Em falha de domínio/portal, o resultado usa isError: true e repete o envelope seguro com code, message, retryable, evidence_uri e details (somente campos da allowlist).

Campos extraídos de baixar_fatura (uc, conta_mes, vencimento, total, consumo_kwh, codigo_pix, linha_digitavel, saldos_scee) usam null para “não extraído/não presente” — nunca zero ou string inventada. parse_status resume a extração:

• complete: campos principais obtidos e códigos de pagamento validados (seção SCEE ausente é legítima e usa saldos_scee.status: not_present);

• partial: há texto útil, mas algo está em missing_fields — informe os ausentes e ofereça o PDF, sem inferir valores;

• unreadable: PDF válido sem texto aproveitável — entregue/vincule o PDF e explique a conferência manual.

Regras de leitura: a uc principal é a consumidora (nunca a de injeção/geração SCEE); codigo_pix confiável começa com 000201 com validadores aprovados; linha_digitavel confiável começa com 341, com comprimento e dígitos verificadores aceitos; saldos_scee nulo não é zero.

O PDF nunca entra inline em base64 no JSON/texto inicial: a referência canônica é arquivo.resource_uri (formato equatorial://faturas/{artifact_id}/pdf) mais o bloco resource_link. O resources/read entrega o binário somente quando o host solicita. arquivo.local_path é auxiliar e pode apontar para dentro de um container — trate resource_uri como referência canônica. PIX e linha digitável completos fazem parte do resultado estruturado, mas o resumo textual os omite; repita-os na conversa somente com pedido explícito do usuário.

Estado local

Raiz padrão em sistemas Unix: ~/.equatorial-mcp/ (no Windows, sob o diretório de dados local da aplicação). Conteúdo:

~/.equatorial-mcp/
├── profile-key                 # segredo local aleatório, 0600
├── profiles/<uf>/<profile-id>/ # userDataDir do Chromium (cookies/sessão isolados por perfil)
├── downloads/<uf>/             # PDFs da segunda via, 0600
├── diagnostics/                # PNGs de diagnóstico temporários, 0600
├── manifests/
│   ├── artifacts.json          # IDs opacos -> caminhos/metadados
│   └── invoices.json           # fatura_id -> fingerprint seguro
└── locks/                      # lock interprocesso do perfil

Diretórios usam permissão 0700 e arquivos sensíveis 0600 em POSIX; no Windows a permissão é aplicada como melhor esforço da plataforma (o chmod ali só alterna o atributo de leitura). O profile-id deriva de HMAC-SHA-256 sobre UF + UC de login + CPF normalizado — o CPF nunca aparece em caminhos ou manifestos. Não commite esse diretório.

PDFs ficam sob seu controle e não são apagados silenciosamente. Capturas de diagnóstico expiram: na inicialização, o servidor remove capturas com mais de sete dias e nunca toca nos PDFs nessa limpeza.

Remoção precisa de estado

A remoção nunca é recursiva ampla: pare o servidor, faça backup do que for manter e remova somente o que você identificou.

1. Pare o servidor (SIGINT/SIGTERM fecha navegador e sessão sem corromper perfil ou manifesto).

2. Inspecione localmente os manifestos (manifests/artifacts.json e manifests/invoices.json) para mapear IDs opacos a arquivos — os PDFs físicos chamam-se downloads/<uf>/Fatura_<uc>_<mes>.pdf com a UC exata mais o mês YYYY-MM ou o prefixo de 8 caracteres da fatura_id (sem CPF e sem códigos de pagamento), e os manifestos registam a UC em texto claro ao lado dos IDs opacos (sem CPF/nascimento/pagamento).

3. Para limpar cookies/sessão de um perfil, remova somente o diretório profiles/<uf>/<profile-id> desejado.

4. Para descartar documentos, remova somente os arquivos listados no manifesto que você escolheu, junto dos registros correspondentes. Edite artifacts.json/invoices.json somente com o servidor parado e mantendo JSON/schema válidos — edições malformadas quebram a resolução e exigem restaurar o backup da etapa 1.

5. Nunca apague um caminho amplo de home ou raiz. PDFs não são limpos automaticamente; capturas com mais de sete dias, sim.

Erros

Repetições automáticas são limitadas a uma única repetição controlada por operação e nunca disparam em rajada; CAPTCHA, credencial inválida, WAF e estrutura alterada nunca entram em retry automático.

Container

A imagem OCI é construída a partir da imagem oficial do navegador fixada por versão e digest no Dockerfile (nunca latest), em build multi-stage que compila sem segredos e publica somente dependências de produção, package.json, dist, Skill, exemplos, README, licença e exemplo de ambiente. O processo roda como usuário não-root da imagem, com stdio como transporte padrão e sandbox do navegador preservado.

docker build -t equatorial-mcp:0.1.0 .
docker inspect equatorial-mcp:0.1.0 --format '{{.Config.User}} {{json .Config.Entrypoint}}'

O diretório de estado permanece em /home/pptruser/.equatorial-mcp e deve ser persistido em volume — sem ele, sessão e artefatos se perdem. Segredos entram somente em runtime via arquivo de ambiente do orquestrador; nenhum segredo vai em build. O exemplo examples/docker-compose.yml usa init: true, stdin_open: true, volume nomeado para o caminho de estado, env_file sem valores e a capacidade documentada exigida pela imagem oficial. Quando local_path apontar para dentro do container, monte o volume correspondente ou use a resource_uri, que continua válida na sessão MCP.

Antes de criar qualquer tag de release, estes gates precisam de decisão do mantenedor e não podem ser adivinhados: disponibilidade/autorização do nome no registro público (ou decisão de fallback com escopo), remoto público canônico para metadados de repositório, digest imutável da imagem base do navegador, SHAs imutáveis das actions fixadas, chave pública de assinatura no segredo de ambiente RELEASE_SIGNING_PUBKEY com fingerprint fixado no workflow (2D413C35D5BAF50B95DAA3DE91257A029C418CF8), ordem de publicação (a imagem só publica após o tarball; em falha, repita o job de imagem no mesmo commit e nunca republicar o npm — depreciar, nunca sobrescrever), errata de recursos ainda aberta, confirmação de performance do parser na máquina de release, revisão vigente de termos e autorização, e validação nos três hosts. Nenhuma tag é criada com gate pendente.

Privacidade e base legal

• O tratamento ocorre para atender ao pedido explícito do titular/operador autenticado. Não acesse conta de terceiros, não compartilhe credenciais e não explore endpoints não públicos.

• Revise os termos de uso do portal antes de automatizar: se o portal proibir automação ou exigir consentimento adicional, o adaptador deve falhar de forma explícita e o canal oficial deve ser usado.

• Sem telemetria, sem analytics e sem upload de documentos. O parser trabalha em memória e não persiste texto bruto extraído.

• Logs usam allowlist de campos e mascaram a UC (no máximo os quatro últimos dígitos). CPF, nascimento, cookies, cabeçalhos de autenticação, corpo do PDF, texto integral da fatura e códigos de pagamento completos nunca entram em logs.

• Reporte vulnerabilidades de forma privada conforme SECURITY.md, sem anexar documentos reais, capturas com dados pessoais, cookies, credenciais, endereços ou códigos de pagamento.

O que o software NÃO faz

• Pagamento, confirmação de pagamento, geração de PIX, alteração cadastral ou qualquer operação mutável.

• Envio por WhatsApp, e-mail, SMS ou qualquer canal de disseminação do documento.

• Agendamento, monitoramento de novas contas ou operação como daemon de cobrança.

• Bypass de CAPTCHA/WAF, proxy rotativo ou falsificação de fingerprint.

• API HTTP pública, multi-tenancy ou armazenamento remoto.

• OCR em nuvem, chave de IA ou processamento remoto de PDF.

Compatibilidade de hosts (2026-09-07)

Somente esses três hosts têm exemplos neste repositório; nenhum outro host é declarado suportado. Os formatos evoluem fora deste projeto — cada release revalida os exemplos contra a documentação oficial e as versões instaladas antes de declarar execução confirmada.

Validação de release

• Evals da Skill em evals/ (casos sintéticos + sequências de tools esperadas), verificados pelo contrato npx vitest run tests/contract/skill-evals.test.ts: nenhuma chamada real, nenhum modelo, nenhuma rede.

• Candidato offline antes de qualquer validação manual: npm ci, npm run lint, npm run typecheck, npm run test:coverage, npm run build, npm pack --dry-run --json, probe de performance do parser com RUN_PARSER_PERF=1 npx vitest run tests/unit/fatura-parser.performance.test.ts e build da imagem candidata com docker build --pull=false -t equatorial-mcp:0.1.0-rc ..

• Evidência de produção: nenhuma. O mapa de aliases de produção permanece vazio (a conveniência UC/mês segue baseada em nulos), o parser SCEE segue validado apenas por fixtures sintéticas e nenhuma amostra real foi registrada.

• A tag v0.1.0 está BLOQUEADA até a execução humana autorizada do runbook em evals/README.md (portões de entrada, orçamento de requisições, evidência privada, condições de parada e rollback) e a quitação dos demais portões pré-tag: errata do código de Resource, autorização de nome/escopo no registro, digests de imagem e actions, e revisão de termos e autorização.

Limitações

• Somente Goiás no v0.1.0; PA/MA falham explicitamente com UF_UNSUPPORTED.

• Sem pagamento, sem alteração cadastral, sem envio por WhatsApp ou e-mail.

• Sem bypass de CAPTCHA ou WAF. Em bloqueio, pare e tente manualmente depois.

• PDF escaneado/sem texto continua disponível como Resource, mas os campos voltam null com parse_status: unreadable — sem OCR no MVP.

• Clientes MCP sem bom suporte a Resources ainda recebem local_path quando acessível; nunca base64 inline na resposta inicial.