Alcance - Desenvolvimento Empresarial

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).
  • Voltar WEBAPI_API_KEY para escopo restrito (5 escopos específicos em vez de global).

[0.2.0] - 2026-05-19

Adicionado

  • Tool `listar_clientes` (read) com filtros opcionais (uf, regime_tributario, cidade) e paginação (pagina, por_pagina até 50). Mapeia GET /api/v1/customers/ da WebApi. Filtros e paginação aplicados client-side no gateway, já que o endpoint upstream não suporta query params. Sétima tool do MVP - antecipada da Fase 1.1, onde estava planejada como customers_listar.
  • Helper markdownTableSemTruncar em src/lib/format.ts - variante de markdownTable sem cap automático de 20 linhas, usada por tools que já fazem paginação client-side controlada. markdownTable original preservado intacto (continua aplicando truncamento em buscar_cliente).
  • Atualização do guia Lovable (docs/install-lovable.md no repo MCP) com prompt real consumindo listar_clientes - substitui referência anterior a tools que ainda não existiam.

Segurança

  • PII via mascararDocumento (auto-detect PF/PJ por length) em todas as colunas de CNPJ da listagem - fix aplicado durante o review (uso direto de mascararCnpj vazaria CPF cru em clientes pessoa física). senha_gov, login_gov, email, telefone e celular continuam fora do schema da tool.
  • Limitação ativo=false rejeitada explicitamente com erro estruturado not_implemented em PT-BR - a WebApi só retorna ativos no endpoint público; documentar a limitação é mais seguro do que filtrar silenciosamente.

Limitações conhecidas

  • Sem cache: cada invocação baixa a base inteira da WebApi (GET /api/v1/customers/). Aceitável para o MVP; cache de 60-300s será avaliado na Fase 2 (Vercel Runtime Cache + invalidation por webhook).
  • Sem rate limiting no gateway. O MCP_BEARER_TOKEN único compartilhado é aceitável enquanto o consumo for restrito a integrações operadas internamente - Fase 2 trará OAuth 2.1 + Vercel Firewall.

[0.1.0] - 2026-05-15

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 repositório mcp-alcancecontabilidade.