Changelog

Todas as mudanças relevantes deste projeto são documentadas aqui.

O formato segue Keep a Changelog e o projeto adota Semantic Versioning.

[Não lançado]

Planejado (Fase 1.1)

• Tool obter_cliente(cliente_id, full=true) com unmask + log de auditoria por bearer (ADR-0004).
• Helpers mascararClienteResponse (agregador) e mais finos por domínio.
• Busca fuzzy por razão social em buscar_cliente (depende de endpoint na WebApi).
• Auto-resolve do contato em criar_lembrete (GET cliente → extrai telefone).
• Tool customers_listar paginada.
• Voltar WEBAPI_API_KEY para escopo restrito (5 escopos específicos em vez de global).

Planejado (Fase 2)

• OAuth 2.1 + DCR (Clerk/WorkOS) para habilitar ChatGPT e revogação granular.
• Rate limiting por cliente IA e por tool.
• Auditoria estruturada de chamadas write em storage externo.

[0.1.0] - 2026-05-15

Adicionado

• Scaffold inicial Next.js 16 + TypeScript estrito + mcp-handler@^1.1.0.
• 6 tools MVP (5 do plano original + obter_cliente antecipado da Fase 1.1):
  • buscar_cliente(termo) — busca por CNPJ (texto retorna mensagem Fase 1.1).
  • obter_cliente(cliente_id) — ficha completa com PII mascarada; nunca expõe credenciais gov.
  • listar_certidoes(cliente_id?, status?, paginação) — CND/FGTS/etc com filtros.
  • listar_lembretes(cliente_id ou usuario_id, apenas_pendentes) — lembretes WhatsApp.
  • criar_lembrete(...) — dry-run by default, exige confirmar=true para criar de fato.
  • consultar_status_task(task_id) — status de tasks Celery.
• 3 resources estáticos: glossario://contabil, status://certidoes, bancos://suportados.
• 1 prompt: /diagnostico-cliente.
• Autenticação Bearer estática via MCP_BEARER_TOKEN com timingSafeEqual (ADR-0003).
• Cliente HTTP tipado para a WebApiAlcance com WEBAPI_API_KEY e timeout configurável.
• Mascaramento de PII por padrão (ADR-0004): mascararCnpj, mascararCpf, mascararDocumento (auto-detect CPF/CNPJ por length), mascararCelular (tolera prefixo 55 do WhatsApp Business), mascararEmail.
• Helpers de formatação: markdownTable (com truncamento), formatarDataBR, formatarMoeda, truncar.
• Erros estruturados em PT-BR (toMcpError): tradução de WebApiError, parser de detail: array do FastAPI 422, dicas contextuais por status code.
• Configuração de deploy: Vercel Fluid Compute região gru1 (ADR-0002), maxDuration: 300s, auto-deploy de main desabilitado (git.deploymentEnabled.main: false) — promoção exige vercel deploy --prod manual.
• Governança: LICENSE proprietária bilíngue (com cláusula anti-treino de LLM), SECURITY.md (canais + SLAs), CODE_OF_CONDUCT.md (Contributor Covenant 2.1), CODEOWNERS (security em auth.ts/format.ts/webapi-client.ts), .editorconfig, .github/{workflows/ci.yml, dependabot.yml, ISSUE_TEMPLATE/*, pull_request_template.md}.
• Arquitetura formal: docs/ARCHITECTURE.md (C4 Contexto + Container em Mermaid, sequence diagram, boundaries, camadas), 4 ADRs retroativos (docs/adr/0001–0004), template ADR.
• Docker dev/CI (não-produção): Dockerfile multi-stage (node:22-alpine, USER non-root, output standalone, ARG para dummies em vez de ENV), .dockerignore, docker-compose.yml validado.
• Plano de QA executável em docs/QA-PLAN-fase-1.md (32 casos funcionais + 20 critérios de aceite).
• Runbook de setup Vercel em docs/VERCEL-SETUP.md (CLI install → login → link → env add → deploy preview/prod + troubleshooting).

Smoke test em produção (2026-05-15)

• Bearer: 401 em request sem header, 401 em bearer inválido, 200 em bearer válido com WWW-Authenticate: Bearer realm="mcp-alcance".
• Handshake MCP initialize retornou protocolVersion: 2024-11-05 + capabilities tools/resources/prompts com listChanged: true.
• obter_cliente(20) validado com cliente real: razão social/nome fantasia/endereço visíveis; CPF, telefone, celular e e-mail mascarados (***.***.691-XX, (73) ****-5606, t****k@yahoo.com.br).
• listar_certidoes(status=todos) retornou tabela populada de certidões reais com id_cliente, tipo, status, data_validade.

Lições aprendidas (referência: docs/adr/)

• O pacote @vercel/mcp-adapter foi renomeado para mcp-handler upstream — versões > 1.0.0 só existem no nome novo (ADR-0001).
• FastAPI 422 (RequestValidationError) retorna detail: [{loc, msg, type}, ...] (array, não string). Parser de erro do gateway precisa cobrir ambos os formatos.
• Ordenamento de declaração de rotas no FastAPI importa: rota dinâmica (/{customer_id}) antes da estática (/cnpj/) faz a estática ser inacessível sem slash final na chamada.
• A WebApiAlcance usa envelope {status, message, data} em todas as respostas (mesmo erros de negócio retornam HTTP 200) — gateway desempacota resp.data antes de processar.

Fonte: content/changelogs/mcp.md · Snapshot sincronizado a partir do repositorio mcp-alcancecontabilidade.