Alcance Docs

Arquitetura

Visão pública da arquitetura do MCP Alcance Contabilidade — um gateway HTTPS que traduz o protocolo MCP (Model Context Protocol) em chamadas autenticadas contra a WebApiAlcance.

Decisões arquiteturais detalhadas (ADRs) ficam no repositório privado da Alcance. Solicite acesso via ti@alcancecontabilidade.com.br.

1. Propósito

Em uma frase: dar a um LLM acesso seguro e auditável aos dados contábeis da Alcance, sem que o LLM jamais conheça a API real ou suas credenciais.

O gateway é o ponto único onde:

  1. Autenticamos o cliente IA.
  2. Validamos input (Zod).
  3. Mascaramos PII por padrão.
  4. Logamos invocações.
  5. Traduzimos para a WebApi com API Key dedicada e escopo restrito.

2. Diagrama de contexto (C4 — Nível 1)

   ┌──────────────────┐         ┌─────────────────────────────┐
   │ Operador humano  │  ────▶  │ Cliente IA                  │
   │ contador/gestor  │   PT-BR │ Claude / Cursor / Lovable / │
   └──────────────────┘         │ ChatGPT*                    │
                                └──────────────┬──────────────┘
                                               │ MCP Streamable HTTP
                                               ▼
                                ┌─────────────────────────────┐
                                │ MCP Alcance                 │
                                │ gateway MCP HTTPS (Vercel)  │
                                └──────────────┬──────────────┘
                                               │ HTTPS + API Key
                                               ▼
                                ┌─────────────────────────────┐
                                │ WebApiAlcance               │
                                │ FastAPI on-premise          │
                                └──────────────┬──────────────┘
                                               │
                          ┌────────────────────┼──────────────────────┐
                          ▼                                           ▼
                   ┌──────────────┐                            ┌──────────────┐
                   │ PostgreSQL   │                            │ Celery       │
                   │ contabilidade│                            │ workers async│
                   └──────────────┘                            └──────────────┘

* ChatGPT depende de OAuth 2.1 (Fase 2).

3. Padrões inegociáveis

  1. PT-BR em tudo que toca o LLM — descrições de tools, mensagens de erro, hints. O LLM consome essas strings.
  2. Annotations corretas — readOnlyHint: true em reads; destructiveHint: true em writes. O Claude Desktop mostra escudo amarelo nos destrutivos.
  3. Dry-run by default em writes — todo write tem confirmar: z.boolean().default(false). Sem true, retorna apenas preview.
  4. PII mascarada by default em respostas READ. Desmascarar exige tool específica.
  5. cliente_id: int é o identificador canônico. CNPJ entra apenas em buscar_cliente(termo), que devolve o id.
  6. Tarefas Celery são assíncronas — retornamos task_id; o cliente IA usa consultar_status_task para acompanhar.
  7. Truncamento — listas com mais de 50 itens cortam em 20 com footer; mais de 500 bloqueia com erro estruturado.
  8. Sem DELETE / sem admin — nenhum endpoint destrutivo de gestão (purge queue, manage users, manage api keys).

4. Boundaries — o que o MCP faz vs delega

ResponsabilidadeMCP gatewayWebApiAlcanceCliente IA
Autenticar cliente IA (Bearer Fase 1)simnãoapresenta token
Autorização por escopo de API Keyconsomesimnão
Validação de input (Zod)simrevalidavia JSON Schema
Mascaramento de PII em respostassimnão (retorna dados crus)não
Conversão JSON → tabela markdownsimnãonão
Erro estruturado em PT-BRsimpassa erro upstreamrenderiza
Persistência / lógica de negócionãosimnão
Disparo de tarefas Celerychama endpointsimnão
Acompanhamento de taskssim (consultar_status_task)sim (endpoint)delega
Auditoria de invocaçõessim (logs Vercel)sim (logs HTTP)não

5. Camadas de código

mcp-alcancecontabilidade/
├── app/api/[transport]/route.ts   Entry point HTTP. Bearer auth + mcp-handler.
├── src/
│   ├── tools/                     1 arquivo por tool. Zod + annotations + registro.
│   │   ├── index.ts               registerTools(server) — chama os registers individuais.
│   │   ├── buscar-cliente.ts
│   │   ├── obter-cliente.ts
│   │   ├── listar-certidoes.ts
│   │   ├── listar-lembretes.ts
│   │   ├── criar-lembrete.ts
│   │   └── consultar-status-task.ts
│   ├── resources/                 Dados de leitura passiva (glossário, enums).
│   ├── prompts/                   Slash-commands expostos ao cliente IA.
│   └── lib/
│       ├── auth.ts                Verificação Bearer (timingSafeEqual).
│       ├── config.ts              Validação Zod das envs.
│       ├── webapi-client.ts       fetch tipado para a WebApi.
│       ├── format.ts              Máscaras PII + tabelas markdown + moeda BR.
│       └── errors.ts              toMcpError() — PT-BR + códigos.
├── docs/                          Documentação humana.
├── vercel.json                    Região gru1, função, headers.
└── next.config.ts                 standalone + MDX + reactStrictMode.

6. Estratégia de evolução

FaseStatusDisparadorSaída
1 — MVPem produçãoscaffold completo6 tools em produção, smoke test Claude Desktop OK
2 — OAuth + Expansãoplanejada2 semanas estáveis em produçãoOAuth 2.1, 15+ tools, dashboard de uso
3 — RAGbacklogdemanda explícita + orçamentoBusca semântica sobre legislação/manuais

7. Decisões arquiteturais (ADRs)

ADRs individuais (uso de mcp-handler, escolha da região gru1, Bearer estático na Fase 1, mascaramento de PII por padrão) ficam no repositório privado da Alcance. Solicite acesso via ti@alcancecontabilidade.com.br.

8. Referências públicas