conflaro-mcp 0.0.0-stage → 1.8.1

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# conflaro-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Servidor [MCP](https://modelcontextprotocol.io) da Conflaro (ex-`@conttrole/mcp`) — expõe a API
+pública de emissão fiscal (NF-e, NFC-e, NFS-e) como ferramentas para agentes de
+IA (Claude Desktop, Cursor, Claude Code).
+
+Roda **localmente** (stdio) — não precisa hospedar nada. Autentica com a sua
+chave de API e fala com `https://api.conflaro.com` por HTTPS.
+
+## Uso
+
+```json
+{
+  "mcpServers": {
+    "conflaro": {
+      "command": "npx",
+      "args": ["-y", "conflaro-mcp"],
+      "env": { "CONFLARO_API_KEY": "ck_live_xxxxxxxx" }
+    }
+  }
+}
+```
+
+| Variável | Obrigatória | Default |
+| --- | --- | --- |
+| `CONFLARO_API_KEY` | sim | — (`ck_live_...` da empresa, ou `ok_live_...` do escritório no modo contador) |
+| `CONFLARO_API_URL` | não | `https://api.conflaro.com` |
+
+`CONTTROLE_API_KEY`/`CONTTROLE_API_URL` continuam aceitas (nome antigo do pacote).
+
+## Desenvolvimento
+
+```bash
+pnpm install
+pnpm build      # compila para dist/
+pnpm dev        # roda do fonte (tsx)
+```
+
+Ferramentas (as MESMAS do servidor remoto — ver o guard em
+`__tests__/services/mcp-superficie-unica.test.ts`):
+
+- **Empresa**: `get_company`
+- **Documentos fiscais**: `list_fiscal_documents`, `get_fiscal_document`,
+  `create_fiscal_document`, `emit_fiscal_document`, `cancel_fiscal_document`,
+  `correct_fiscal_document`, `get_fiscal_document_xml`
+- **GNRE** (guias de DIFAL/FCP/ICMS-ST para outra UF): `get_fiscal_document_gnre`,
+  `generate_fiscal_document_gnre`, `refresh_fiscal_document_gnre`,
+  `list_gnre_guides` — `documents:read`/`documents:write`; gerar e listar exigem
+  o módulo **GNRE** contratado
+- **Produtos**: `list_products`, `get_product`, `create_product`,
+  `update_product`
+- **Financeiro (AP/AR)**: `list_finance_titles`, `get_finance_title`,
+  `get_finance_summary`, `create_finance_title`, `settle_finance_installment`,
+  `list_overdue_receivables`, `top_delinquent_clients`, `cashflow_projection`
+  — exigem o escopo `finance:read`/`finance:write` na chave e o módulo
+  **Financeiro** contratado
+- **Notas recebidas (DF-e)**: `list_received_documents`,
+  `get_received_document`, `get_received_document_xml`,
+  `manifest_received_document`, `sync_received_documents`,
+  `get_received_documents_distribution`, `get_received_documents_export_link`
+  (o mês inteiro num ZIP, entregue como link de 15 min) — exigem `received-documents:read`
+  (e `:write` para manifestar); com a chave do escritório, informe `companyId`
+- **Simples Nacional**: `get_simples_estimate` — a estimativa do DAS do mês,
+  com a memória de cálculo; exige `simples:read`. Com `companyId` (chave do
+  escritório), de uma empresa da carteira; `simulate_simples_ibscbs_regime` (IBS/CBS
+  dentro × fora do DAS a partir de 2027), `get_simples_das_forecast` (previsão
+  do mês e da faixa seguinte) e `get_product_tax_in_price` (imposto no preço e
+  preço mínimo)
+- **Notas suspeitas**: `list_suspicious_received_documents` — NF-e recebidas
+  de fornecedor novo com valor ou mercadoria fora do padrão (exige
+  `received-documents:read`)
+- **Modo contador** (chave do escritório `ok_`): `get_accounting_office`,
+  `list_portfolio_companies`, `list_portfolio_das_estimates`, `list_closing_eligible_companies`,
+  `request_fiscal_closings`, `list_fiscal_closings`,
+  `get_fiscal_closing_download`
+- **Regras e webhooks**: `list_tax_rules`, `list_webhooks`, `create_webhook`
+
+Documentação completa: https://docs.conttrole.io/mcp
+
+## Publicação no registro oficial do MCP
+
+O `server.json` desta pasta descreve o servidor para o
+[registro oficial](https://registry.modelcontextprotocol.io) com as duas formas
+de uso: este pacote (stdio) e o servidor remoto (`https://mcp.conttrole.io/mcp`,
+OAuth). O nome é `io.conttrole/mcp`, e o namespace `io.conttrole` é provado
+por um registro TXT no DNS de `conttrole.io`.
+
+**Quem publica é o CI** (`.github/workflows/mcp-publish.yml`): basta subir a
+versão e commitar na main. Ele publica no npm e depois no registro, e pula o
+que já estiver lá — então rodar de novo depois de uma falha completa o que
+faltou, sem erro de versão duplicada.
+
+🔴 **A versão mora em TRÊS lugares** que precisam bater: o `version` do
+`package.json` e os dois `version` do `server.json`. O guard
+`apps/web/__tests__/services/mcp-registro-versao.test.ts` e o próprio workflow
+recusam quando divergem. O servidor lê a dele do `package.json`.
+
+O npm publica por **Trusted Publisher** (OIDC): o vínculo é com
+`saas-nfe/conttrole` + `mcp-publish.yml`, configurado nas Settings do pacote no
+npmjs.com. Renomear o workflow quebra a publicação.
+🔴 Pacote novo não aceita Trusted Publisher antes de existir: a 1ª versão do
+`conflaro-mcp` sai pelo secret `NPM_TOKEN`, que depois é apagado (ver o
+cabeçalho do `mcp-publish.yml`). O único secret é
+`MCP_REGISTRY_PRIVATE_KEY` (a chave Ed25519 do namespace, em hex); o par
+público dela é o TXT na raiz de `conttrole.io`, e trocar a chave exige trocar
+o TXT junto.
+
+Publicação à mão, só se o CI estiver fora (o `mcp-publisher` é o binário das
+releases de `modelcontextprotocol/registry`, **não** o pacote npm homônimo,
+que é um servidor MCP e fica parado esperando no stdin):
+
+```bash
+pnpm --filter conflaro-mcp publish
+mcp-publisher login dns --domain conttrole.io \
+  --private-key "$(openssl pkey -in ~/.config/conttrole/mcp-key.pem -noout -text | grep -A3 'priv:' | tail -n +2 | tr -d ' :\n')"
+mcp-publisher publish   # de dentro de apps/mcp
+```
+
+Conferência: `curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.conttrole"`.

package/dist/index.js

@@ -0,0 +1,847 @@
+#!/usr/bin/env node
+/**
+ * Servidor MCP da Conflaro — expõe a API pública de emissão fiscal como
+ * ferramentas para agentes de IA (Claude Desktop, Cursor, etc.).
+ *
+ * Configuração via variáveis de ambiente:
+ *   - CONFLARO_API_KEY  (obrigatório)  Chave de API da empresa (ck_live_...) ou,
+ *                                        no modo contador, do escritório (ok_live_...)
+ *   - CONFLARO_API_URL  (opcional)     Default: https://api.conflaro.com
+ *
+ * 🔴 `CONTTROLE_API_KEY`/`CONTTROLE_API_URL` continuam aceitas: o pacote era
+ * `@conttrole/mcp`, e quem migrar para `conflaro-mcp` só trocando o nome no
+ * `args` do Claude Desktop não pode ficar sem servidor por causa do `env`.
+ *
+ * Autenticação na API: header `Authorization: Bearer <chave>`.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createRequire } from "node:module";
+import { z } from "zod";
+const API_URL = (process.env.CONFLARO_API_URL ??
+    process.env.CONTTROLE_API_URL ??
+    "https://api.conflaro.com").replace(/\/$/, "");
+const API_KEY = process.env.CONFLARO_API_KEY ?? process.env.CONTTROLE_API_KEY ?? "";
+if (!API_KEY) {
+    console.error("[conflaro-mcp] CONFLARO_API_KEY não definida. " +
+        "Gere uma chave em /dashboard/api-keys e configure no ambiente.");
+    process.exit(1);
+}
+/** Chama a API pública. Retorna o corpo (JSON) ou texto (XML). Lança em erro. */
+async function api(method, path, opts = {}) {
+    const url = new URL(`${API_URL}${path}`);
+    for (const [k, v] of Object.entries(opts.query ?? {})) {
+        if (v !== undefined && v !== null && v !== "")
+            url.searchParams.set(k, String(v));
+    }
+    const res = await fetch(url, {
+        method,
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            // Identifica o canal: a API exige o módulo `mcp` do plano.
+            "X-Api-Client": "mcp",
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        },
+        body: opts.body != null ? JSON.stringify(opts.body) : undefined,
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`HTTP ${res.status} ${path}: ${text || res.statusText}`);
+    }
+    const ct = res.headers.get("content-type") ?? "";
+    return ct.includes("application/json") && text ? JSON.parse(text) : text;
+}
+/** Embrulha um handler: serializa o resultado e formata erros como isError. */
+function tool(fn) {
+    return async (args) => {
+        try {
+            const result = await fn(args);
+            const text = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            return {
+                content: [
+                    { type: "text", text: err instanceof Error ? err.message : String(err) },
+                ],
+                isError: true,
+            };
+        }
+    };
+}
+// A versão vem do package.json (que o npm sempre empacota, um nível acima de
+// dist/ e de src/): fixa no código, ela ficou em "1.0.0" até a 1.4.0.
+const { version } = createRequire(import.meta.url)("../package.json");
+const server = new McpServer({ name: "conflaro", version });
+// ── Empresa ────────────────────────────────────────────────────────────────
+server.tool("get_company", "Mostra os dados da empresa dona da chave de API configurada (razão social, CNPJ, IE/IM, regime tributário, endereço).", {}, tool(() => api("GET", "/v1/company")));
+// ── Documentos fiscais ─────────────────────────────────────────────────────
+server.tool("list_fiscal_documents", "Lista os documentos fiscais (NF-e/NFC-e/NFS-e) da empresa, com paginação e filtros por status e tipo.", {
+    page: z.number().int().positive().optional().describe("Página (default 1)"),
+    pageSize: z.number().int().positive().max(100).optional().describe("Itens por página (default 20, máx 100)"),
+    status: z.string().optional().describe("Filtra por status (ex.: AUTHORIZED, DRAFT, REJECTED)"),
+    type: z.string().optional().describe("Filtra por tipo (NFE, NFCE, NFSE)"),
+}, tool((a) => api("GET", "/v1/fiscal-documents", { query: a })));
+server.tool("get_fiscal_document", "Detalha um documento fiscal pelo id (status, número, chave de acesso, itens, etc.).", { id: z.string().describe("ID do documento fiscal") }, tool((a) => api("GET", `/v1/fiscal-documents/${a.id}`)));
+/**
+ * 🔴 Estes shapes são um RECORTE da API pública, não um espelho dela.
+ *
+ * O schema de uma tool de MCP viaja para o modelo em TODA conversa, então
+ * enumerar os 39 campos de documento e os 57 de item que a API aceita custaria
+ * contexto permanente em troca de campos que quase ninguém usa. Por outro lado,
+ * campo que não está no schema é campo que o modelo não sabe que existe.
+ *
+ * O corte: enumerado com descrição o que se usa para emitir uma nota de
+ * verdade; o resto entra por `.passthrough()` (nos objetos) e por `extra` (no
+ * topo, onde o SDK monta o `z.object` e não dá para abrir). Quem valida é a
+ * API — um 422 dela volta como texto de erro com o motivo. É o mesmo idioma do
+ * `productNfeConfigShape` do servidor HTTP.
+ *
+ * 🔴 Este arquivo é a CÓPIA publicada no npm: `conflaro-mcp` só pode
+ * depender de `zod` e do SDK, então os enums que o servidor HTTP lê do
+ * Prisma (forma de pagamento, bandeira) aqui são `string` com os valores na
+ * descrição — a API recusa o inválido com 422. O que NÃO pode divergir é a
+ * lista de CAMPOS: campo ausente é descartado em silêncio, e a nota sai sem
+ * ele. Guard: `__tests__/services/mcp-superficie-unica.test.ts`.
+ */
+const paymentShape = z
+    .object({
+    method: z
+        .string()
+        .describe("Forma de pagamento: MONEY, CHECK, CREDIT_CARD, DEBIT_CARD, STORE_CREDIT, " +
+        "FOOD_VOUCHER, MEAL_VOUCHER, GIFT_VOUCHER, FUEL_VOUCHER, BANK_SLIP, " +
+        "BANK_DEPOSIT, PIX, WIRE_TRANSFER, LOYALTY, NO_PAYMENT, DEFERRED_PAYMENT, " +
+        "OTHERS. Valor fora da tabela é recusado pela API com 422."),
+    value: z.number().describe("Valor pago nesta forma (R$)"),
+    description: z
+        .string()
+        .nullish()
+        .describe("Descrição da forma. OBRIGATÓRIA quando method=OTHERS."),
+    cardFlag: z.string().nullish().describe("Bandeira do cartão (VISA, MASTERCARD, ELO…)"),
+    cardCNPJ: z.string().nullish().describe("CNPJ da credenciadora do cartão"),
+    cardAuthorization: z.string().nullish().describe("Código de autorização"),
+    pixKey: z.string().nullish(),
+    pixTxId: z.string().nullish(),
+    paidAt: z
+        .string()
+        .nullish()
+        .describe("<dPag> — data em que o pagamento OCORREU (AAAA-MM-DD), que pode não ser a da emissão."),
+})
+    .passthrough();
+const duplicateShape = z.object({
+    number: z.string().nullish().describe("Número da parcela. Vazio = 001, 002…"),
+    dueDate: z.string().describe("Vencimento, AAAA-MM-DD (data pura, sem hora)"),
+    value: z.number().positive().describe("Valor da parcela (R$)"),
+});
+const transportShape = z
+    .object({
+    freightType: z
+        .string()
+        .nullish()
+        .describe("<modFrete>. SENDER=por conta do emitente · RECIPIENT=do destinatário · " +
+        "THIRD_PARTY=de terceiros · NO_FREIGHT=sem transporte."),
+    freightValue: z
+        .number()
+        .nonnegative()
+        .nullish()
+        .describe("Valor do frete da NOTA (R$). É rateado entre os itens e ENTRA NO " +
+        "TOTAL da nota — o vNF soma frete, seguro e outras despesas e abate " +
+        "o desconto."),
+    carrierId: z.string().nullish().describe("ID da transportadora cadastrada"),
+    vehiclePlate: z.string().nullish(),
+    volumeQuantity: z.number().nullish(),
+    volumeSpecies: z.string().nullish(),
+    volumeGrossWeight: z.number().nullish(),
+    volumeNetWeight: z.number().nullish(),
+})
+    .passthrough();
+const placeShape = z
+    .object({
+    kind: z.enum(["PICKUP", "DELIVERY"]).describe("PICKUP=<retirada> · DELIVERY=<entrega>"),
+    street: z.string().describe("Logradouro"),
+    number: z.string().describe("Número"),
+    neighborhood: z.string().describe("Bairro"),
+    cityCode: z.string().nullish().describe("Código IBGE do município"),
+    cityName: z.string().nullish(),
+    state: z.string().describe("UF"),
+    zipCode: z.string().nullish(),
+    cnpj: z.string().nullish(),
+    cpf: z.string().nullish(),
+})
+    .passthrough()
+    .describe("🔴 Endereço INCOMPLETO não emite o grupo: logradouro, número, bairro, " +
+    "município e UF são obrigatórios dentro dele.");
+const referenceShape = z
+    .object({
+    kind: z
+        .enum(["NFE", "NF", "NFP", "CTE", "ECF"])
+        .describe("Tipo do documento referenciado. NFE=por chave · NF=nota em papel " +
+        "(modelo 1/1A) · NFP=produtor rural · CTE · ECF=cupom fiscal."),
+    accessKey: z.string().nullish().describe("Chave de 44 dígitos (kind NFE/CTE)"),
+})
+    .passthrough()
+    .describe("UM tipo por item — o leiaute declara um xs:choice.");
+const inlineClientShape = z
+    .object({
+    name: z.string().describe("Razão social ou nome"),
+    document: z.string().nullish().describe("CNPJ ou CPF (só dígitos ou com máscara)"),
+    email: z.string().nullish(),
+    zipCode: z.string().nullish(),
+    street: z.string().nullish(),
+    number: z.string().nullish(),
+    neighborhood: z.string().nullish(),
+    city: z.string().nullish(),
+    state: z.string().nullish(),
+})
+    .passthrough();
+const itemShape = z.object({
+    code: z.string().describe("Código/SKU do item"),
+    description: z.string().describe("Descrição do item"),
+    quantity: z.number().positive().describe("Quantidade"),
+    unitValue: z.number().nonnegative().describe("Valor unitário"),
+    ncm: z.string().optional().describe("NCM 8 dígitos (NF-e). Sem valor, herda da empresa."),
+    cfop: z.string().optional().describe("CFOP (NF-e/NFC-e)"),
+    unit: z.string().optional().describe("Unidade comercial. Default: UN."),
+    serviceCode: z.string().optional().describe("Código de serviço municipal (NFS-e)"),
+    nationalServiceCode: z.string().optional().describe("Código de serviço nacional (NFS-e)"),
+    taxRuleId: z.string().optional().describe("ID de regra tributária a aplicar no item"),
+    productId: z
+        .string()
+        .optional()
+        .describe("ID de um produto desta empresa (list_products). Liga o item ao cadastro: a tributação própria do produto e o CEST dele passam a valer, e NCM/CFOP ausentes vêm do produto."),
+    cest: z
+        .string()
+        .optional()
+        .describe("CEST do item (7 dígitos). Vazio = o do produto. Exigido quando o ICMS tem ST."),
+    nbsCode: z
+        .string()
+        .nullish()
+        .describe("Código NBS (<cNBS>, 9 dígitos). Sem valor, herda do produto e depois da empresa."),
+    // ACESSÓRIOS do item. 🔴 Entram no TOTAL da nota: o vNF soma frete, seguro e
+    // outras despesas e abate o desconto, e a SEFAZ confere (rejeição 610).
+    freightValue: z
+        .number()
+        .nonnegative()
+        .nullish()
+        .describe("<vFrete> do PRÓPRIO item (R$). Soma-se ao rateio do frete da nota. Entra no total e na base do ICMS/ST."),
+    insuranceValue: z
+        .number()
+        .nonnegative()
+        .nullish()
+        .describe("<vSeg> do item (R$). Entra no total da nota."),
+    otherValue: z
+        .number()
+        .nonnegative()
+        .nullish()
+        .describe("<vOutro> — outras despesas acessórias do item (R$). Entra no total da nota."),
+    discountValue: z
+        .number()
+        .nonnegative()
+        .nullish()
+        .describe("<vDesc> do PRÓPRIO item (R$). Soma-se ao rateio do desconto da nota e é abatido do total."),
+    // Impostos — opcionais. Ausentes, vêm da hierarquia (produto → regra → template).
+    icmsOrigin: z.string().nullish().describe("Origem da mercadoria (0 a 8)"),
+    icmsSituation: z.string().nullish().describe("CST/CSOSN do ICMS"),
+    icmsRate: z.number().nullish().describe("Alíquota do ICMS (%)"),
+    pisSituation: z.string().nullish().describe("CST do PIS"),
+    pisRate: z.number().nullish().describe("Alíquota do PIS (%)"),
+    cofinsSituation: z.string().nullish().describe("CST da COFINS"),
+    cofinsRate: z.number().nullish().describe("Alíquota da COFINS (%)"),
+    ipiSituation: z.string().nullish().describe("CST do IPI"),
+    ipiRate: z.number().nullish().describe("Alíquota do IPI (%)"),
+    // Parâmetros do ICMS no ITEM — a nota prevalece sobre produto e regra.
+    icmsRedBc: z.number().nullish().describe("Redução da base do ICMS (%) — CST 20/70"),
+    icmsStModBc: z
+        .enum(["4", "6"])
+        .nullish()
+        .describe("Modalidade da base do ICMS-ST (4 = MVA, 6 = valor da operação)"),
+    icmsStMva: z.number().nullish().describe("MVA do ICMS-ST (%)"),
+    icmsStRedBc: z.number().nullish().describe("Redução da base do ICMS-ST (%)"),
+    icmsStRate: z.number().nullish().describe("Alíquota do ICMS-ST no destino (%)"),
+    icmsSnCreditRate: z
+        .number()
+        .nullish()
+        .describe("Alíquota de crédito do Simples (pCredSN, %) — CSOSN 101/201"),
+    // DESONERAÇÃO e DIFERIMENTO. 🔴 `icmsDesonValue` e `icmsDesonReason` saem
+    // JUNTOS no XML, e o motivo aceito DEPENDE DO CST.
+    icmsDesonValue: z
+        .number()
+        .nonnegative()
+        .nullish()
+        .describe("Valor do ICMS desonerado (vICMSDeson, R$) — CST 20/30/40/41/50/70/90. Omitido, é calculado pela alíquota."),
+    icmsDesonReason: z
+        .string()
+        .nullish()
+        .describe("Motivo da desoneração (motDesICMS). 🔴 A tabela muda POR CST: 3/9/10/11/12 no 20; " +
+        "6/7/9 no 30; 1/3/4/5/6/7/8/9/10/11/16/90 no 40, 41 e 50; 3/9/12 no 70 e no 90. " +
+        "Motivo fora da tabela do CST é recusado com 422."),
+    icmsDesonDeduct: z
+        .boolean()
+        .nullish()
+        .describe("indDeduzDeson — quando verdadeiro, o valor desonerado ABATE o total da nota. Ausente = falso."),
+    icmsDeferralRate: z
+        .number()
+        .nullish()
+        .describe("Percentual de diferimento (pDif, %) — CST 51. 100 é o caso comum e resulta em " +
+        "vICMS 0,00, que é DIFERENTE de isenção: o imposto existe e será recolhido adiante."),
+    // <rastro> (B13) e pedido de compra do ITEM (B4).
+    batches: z
+        .array(z.object({
+        batch: z.string().describe("<nLote> — até 20 caracteres"),
+        quantity: z.number().positive().describe("<qLote>"),
+        producedAt: z.string().describe("<dFab> — AAAA-MM-DD, sem hora"),
+        expiresAt: z.string().describe("<dVal> — AAAA-MM-DD"),
+        aggregationCode: z.string().nullish().describe("<cAgreg>"),
+    }))
+        .max(500)
+        .nullish()
+        .describe("Lotes deste item. Um item pode ter VÁRIOS — a soma dos `quantity` é a " +
+        "quantidade do item. 🔴 Tudo ou nada: lote sem algum dos quatro campos " +
+        "obrigatórios é descartado na emissão."),
+    purchaseOrder: z
+        .string()
+        .nullish()
+        .describe("<xPed> — pedido de compra DESTE item (até 15 caracteres; o excedente é truncado)."),
+    purchaseOrderItem: z
+        .string()
+        .nullish()
+        .describe("<nItemPed> — a linha do pedido (até 6 dígitos). Fora do formato é DESCARTADO."),
+}).passthrough();
+server.tool("create_fiscal_document", "Cria um documento fiscal (rascunho). Use emit=true para já enfileirar a emissão. Impostos são resolvidos pela regra tributária quando não informados.", {
+    type: z.enum(["NFE", "NFCE", "NFSE"]).describe("Tipo do documento"),
+    clientId: z
+        .string()
+        .optional()
+        .describe("ID de um cliente já cadastrado nesta empresa. Informe `clientId` OU `client`."),
+    client: inlineClientShape
+        .nullish()
+        .describe("Cliente inline — cria ou reusa o cliente junto da nota (reusa quando " +
+        "o `document` casa). Alternativa ao `clientId`."),
+    items: z.array(itemShape).min(1).describe("Itens do documento"),
+    operationNature: z.string().optional().describe("Natureza da operação"),
+    taxRuleId: z.string().optional().describe("Regra tributária para os itens sem regra própria"),
+    templateId: z
+        .string()
+        .nullish()
+        .describe("Template fiscal a aplicar (list via GET /v1/fiscal-templates). " +
+        "Preenche só os campos que você NÃO enviou."),
+    additionalInfo: z.string().optional(),
+    externalId: z.string().optional().describe("ID externo da venda (dedup/rastreio)"),
+    issueDateTime: z.string().optional().describe("Data de emissão ISO 8601. Default: agora."),
+    emit: z.boolean().optional().describe("Quando true, já dispara a emissão (assíncrona)."),
+    // ── Cobrança e total ────────────────────────────────────────────────
+    payments: z
+        .array(paymentShape)
+        .nullish()
+        .describe("Formas de pagamento (<pag>). A soma precisa fechar com o total da nota."),
+    duplicates: z
+        .array(duplicateShape)
+        .nullish()
+        .describe("Parcelas da cobrança (<cobr>). Presença indica venda a prazo. 🔴 A SOMA " +
+        "PRECISA FECHAR EXATAMENTE com o total da nota — que inclui frete, seguro " +
+        "e outras despesas e abate o desconto, NÃO é só o total dos itens. " +
+        "Diferença de um centavo é recusada com 400. Omita em venda à vista."),
+    transport: transportShape
+        .nullish()
+        .describe("Grupo X (<transp>) da NF-e — transportadora, veículo e volumes; é onde vai " +
+        "o valor do frete. Omita em venda sem transporte. NFS-e não tem esse grupo."),
+    discountValue: z
+        .number()
+        .nonnegative()
+        .nullish()
+        .describe("Desconto INCONDICIONAL da nota. É rateado entre os itens e ABATE A BASE do " +
+        "imposto — não é só um abatimento do total. Desconto condicional (por " +
+        "antecipação) não entra aqui."),
+    buyerPresence: z
+        .enum(["0", "1", "2", "3", "4", "5", "9"])
+        .nullish()
+        .describe("<indPres>. 0=não se aplica · 1=presencial · 2=internet · 3=teleatendimento · " +
+        "4=entrega a domicílio · 5=presencial fora do estabelecimento · 9=outros. " +
+        "Omita para automático. A NFC-e só aceita 1, 4 e 5."),
+    // ── Finalidade e documentos referenciados (B1) ───────────────────────
+    fiscalPurpose: z
+        .enum(["COMPLEMENTAR", "AJUSTE"])
+        .nullish()
+        .describe("COMPLEMENTAR = finNFe 2, para corrigir valor ou imposto declarado A MENOS " +
+        "(carrega só a DIFERENÇA). AJUSTE = finNFe 3. 🔴 Exclusiva com " +
+        "`isDevolution`: a nota tem UMA finalidade. As duas EXIGEM o documento " +
+        "referenciado."),
+    isDevolution: z
+        .boolean()
+        .nullish()
+        .describe("Nota de DEVOLUÇÃO (finNFe=4). Entrada ou saída sai da faixa do CFOP dos " +
+        "itens, não daqui. Com `referencedAccessKey`, o IPI devolvido é lido do XML " +
+        "original."),
+    referencedAccessKey: z
+        .string()
+        .nullish()
+        .describe("Chave de 44 dígitos da NF-e original ajustada ou devolvida — vira <refNFe>."),
+    references: z
+        .array(referenceShape)
+        .max(999)
+        .nullish()
+        .describe("Documentos referenciados (<NFref>), até 999. Cobre nota em papel, produtor " +
+        "rural, CT-e e cupom fiscal além da NF-e por chave."),
+    // ── Entrega/retirada e pedido de compra (B3/B4) ──────────────────────
+    places: z
+        .array(placeShape)
+        .max(2)
+        .nullish()
+        .describe("Local de RETIRADA e de ENTREGA, quando diferentes do remetente e do " +
+        "destinatário — e-commerce com entrega em outro endereço, dropshipping, " +
+        "venda à ordem. Um de cada `kind`."),
+    purchaseNote: z.string().nullish().describe("<xNEmp> — nota de EMPENHO (exigida por órgão público)."),
+    purchaseOrderRef: z
+        .string()
+        .nullish()
+        .describe("<xPed> do grupo <compra> — pedido da NOTA INTEIRA. 🔴 Não é o `purchaseOrder` do ITEM."),
+    purchaseContract: z.string().nullish().describe("<xCont> — número do contrato de compra."),
+    // ── NFS-e ────────────────────────────────────────────────────────────
+    competence: z
+        .string()
+        .nullish()
+        .describe("NFS-e: competência do serviço (<dCompet>), AAAA-MM ou AAAA-MM-DD. Ausente = " +
+        "data de emissão. Serve a quem fatura no mês seguinte ao serviço."),
+    serviceMunicipalityCode: z
+        .string()
+        .nullish()
+        .describe("NFS-e: código IBGE do município onde o serviço foi PRESTADO, quando difere do " +
+        "que a Regra Fiscal resolveria. 🔴 Obra, evento ou serviço na sede do cliente " +
+        "ficavam no município da empresa, e o ISS vai para a prefeitura errada."),
+    serviceDeductionValue: z
+        .number()
+        .nonnegative()
+        .nullish()
+        .describe("NFS-e: dedução da base em VALOR (<vDR>). 🔴 VENCE o percentual da Regra " +
+        "Fiscal — agência de viagem e construção civil deduzem repasse e material, " +
+        "que mudam a cada nota."),
+    serviceFinalUse: z
+        .boolean()
+        .nullish()
+        .describe("NFS-e: <indFinal> — uso ou consumo PESSOAL de sócio ou administrador (art. 57 " +
+        "da LC 214/2025). 🔴 NÃO é o consumidor final da NF-e e não se deriva do " +
+        "cliente. Ausente = não."),
+    issExigibility: z
+        .enum(["1", "2", "3", "4", "5", "6", "7"])
+        .nullish()
+        .describe("NFS-e: exigibilidade do ISS. 1=exigível · 2=não incidência · 3=isenção · " +
+        "4=exportação · 5=imunidade · 6=suspensa por decisão judicial · 7=suspensa " +
+        "por processo administrativo. 6 e 7 exigem `issSuspensionProcess`."),
+    issSuspensionProcess: z
+        .string()
+        .nullish()
+        .describe("Número do processo da suspensão. Obrigatório com issExigibility 6 ou 7."),
+    construction: z
+        .object({
+        registration: z.string().nullish().describe("Inscrição imobiliária (IPTU). NÃO identifica a obra."),
+        code: z.string().nullish().describe("Código CNO/CEI da obra (<cObra>)"),
+        cib: z.string().nullish().describe("Código CIB (<cCIB>), 8 caracteres. Só no Padrão Nacional."),
+        art: z.string().nullish().describe("Número da ART/RRT"),
+    })
+        .passthrough()
+        .nullish()
+        .describe("NFS-e de construção civil (LC 7.02 e 7.05) — é o município DA OBRA que cobra o " +
+        "ISS. 🔴 A identificação é um xs:choice: `code`, `cib` ou o endereço, UM " +
+        "deles. A inscrição imobiliária sozinha não serve."),
+    substitutedDocumentId: z
+        .string()
+        .nullish()
+        .describe("NFS-e: id da nota que esta SUBSTITUI. 🔴 A substituição é UMA operação, não " +
+        "'cancela e emite' — quem cancela a antiga é a Sefin, depois de esta ser " +
+        "autorizada."),
+    substitutionReason: z
+        .string()
+        .nullish()
+        .describe("Justificativa da substituição (TSCodJustSubst): 01 desenquadramento do " +
+        "Simples · 02 enquadramento · 03 inclusão retroativa de imunidade · 04 " +
+        "exclusão retroativa · 05 rejeição pelo tomador · 99 outros. Vazio = 99. " +
+        "🔴 NÃO é a tabela do cancelamento comum (1/2/9)."),
+    substitutionNote: z.string().nullish().describe("Texto do motivo da substituição (<xMotivo>)."),
+    extra: z
+        .record(z.unknown())
+        .nullish()
+        .describe("Campos da API pública não listados acima, passados como estão. É por aqui que " +
+        "entram os grupos raros: ajustes de IBS/CBS no item (rtcCst, rtcCClassTrib, " +
+        "rtcAjusteIbs…), ICMS-ST retido anteriormente (icmsStRetBase e família), " +
+        "notas de crédito/débito da RTC (rtcCreditType, rtcDebitType), <comExt> da " +
+        "NFS-e e o intermediador (intermediaryDocument, intermediarySellerId). " +
+        "Referência: GET /v1/openapi.json."),
+}, tool((a) => {
+    // `extra` é a válvula de escape do recorte: o schema do SDK é um
+    // `z.object` fechado, então campo não declarado seria DESCARTADO em
+    // silêncio — o pior desfecho, porque a nota sai sem ele e nada avisa.
+    // O declarado vence o `extra` quando os dois trazem a mesma chave.
+    const { extra, ...campos } = a;
+    const declarados = Object.fromEntries(Object.entries(campos).filter(([, v]) => v !== undefined));
+    return api("POST", "/v1/fiscal-documents", {
+        body: { ...(extra ?? {}), ...declarados },
+    });
+}));
+server.tool("emit_fiscal_document", "Dispara a emissão (assíncrona) de um documento fiscal já criado. Acompanhe o status com get_fiscal_document.", { id: z.string().describe("ID do documento fiscal") }, tool((a) => api("POST", `/v1/fiscal-documents/${a.id}/emit`)));
+server.tool("cancel_fiscal_document", "Cancela um documento fiscal AUTORIZADO, com justificativa.", {
+    id: z.string().describe("ID do documento fiscal"),
+    reason: z.string().min(15).describe("Justificativa do cancelamento (mín. 15 caracteres)"),
+}, tool((a) => api("POST", `/v1/fiscal-documents/${a.id}/cancel`, { body: { reason: a.reason } })));
+server.tool("correct_fiscal_document", "Emite uma Carta de Correção (CC-e) para um documento fiscal autorizado.", {
+    id: z.string().describe("ID do documento fiscal"),
+    text: z.string().min(15).describe("Texto da correção (mín. 15 caracteres)"),
+}, tool((a) => api("POST", `/v1/fiscal-documents/${a.id}/correction`, { body: { text: a.text } })));
+server.tool("get_fiscal_document_xml", "Baixa o XML autorizado de um documento fiscal (retorna o XML como texto).", { id: z.string().describe("ID do documento fiscal") }, tool((a) => api("GET", `/v1/fiscal-documents/${a.id}/xml`)));
+// ── GNRE por operação (docs/plans/gnre.md §8) ──
+server.tool("get_fiscal_document_gnre", "GNRE da nota (guia de recolhimento do DIFAL, FCP e ICMS-ST devidos a OUTRA UF): o que a NF-e autorizada exige (`assessment`, pelo XML), as guias geradas (status, valor, vencimento, `digitableLine` para pagar) e a cota do mês. `noGuideReason` explica quando NÃO há guia devida. Valores em string decimal.", { id: z.string().describe("ID do documento fiscal (NF-e)") }, tool((a) => api("GET", `/v1/fiscal-documents/${encodeURIComponent(String(a.id))}/gnre`)));
+server.tool("generate_fiscal_document_gnre", "Gera (ou regera) as guias GNRE da nota no Portal GNRE — fala com o fisco, consome a cota do plano e cria obrigação de pagamento: confirme com o usuário antes. Idempotente (guia emitida não é refeita). O resultado sai em ≥ 30 s: depois consulte get_fiscal_document_gnre (ou refresh_fiscal_document_gnre). `blocked` = falta dado que só a pessoa resolve; o motivo fica na guia. Exige o módulo GNRE (403 `feature_not_enabled`).", { id: z.string().describe("ID do documento fiscal (NF-e autorizada)") }, tool((a) => api("POST", `/v1/fiscal-documents/${encodeURIComponent(String(a.id))}/gnre`)));
+server.tool("refresh_fiscal_document_gnre", "Consulta AGORA no Portal GNRE o resultado das guias enviadas da nota (emitidas ganham linha digitável; rejeitadas, o motivo). `processing: true` = o portal ainda processa; tente de novo em alguns segundos.", { id: z.string().describe("ID do documento fiscal (NF-e)") }, tool((a) => api("POST", `/v1/fiscal-documents/${encodeURIComponent(String(a.id))}/gnre/refresh`)));
+server.tool("list_gnre_guides", "Lista as guias GNRE da empresa (mais recentes primeiro), com filtro por status, UF favorecida e ambiente (padrão PRODUCTION). Sem o módulo GNRE a resposta é 403 `feature_not_enabled` — não conclua que não há guias.", {
+    page: z.number().int().positive().optional(),
+    pageSize: z.number().int().positive().max(100).optional(),
+    // `string` (não enum): o publicado não lê o Prisma — valor inválido volta 400 da API.
+    status: z.string().optional().describe("PENDING | SENT | ISSUED | REJECTED | BLOCKED | QUOTA_EXCEEDED | CANCELED"),
+    uf: z.string().optional().describe("UF favorecida (sigla, ex.: SP)"),
+    environment: z.string().optional().describe("PRODUCTION (padrão) | HOMOLOGATION | ALL"),
+}, tool((a) => api("GET", "/v1/gnre", { query: a })));
+/**
+ * Configuração de NF-e do produto, com a TRIBUTAÇÃO PRÓPRIA. Os campos
+ * principais estão descritos para o modelo; `passthrough` deixa passar o resto
+ * (unidades, código de barras…) — quem valida é a API, e um 422 dela volta como
+ * texto de erro com o motivo.
+ */
+const productNfeConfigShape = z
+    .object({
+    internalCfop: z
+        .string()
+        .nullish()
+        .describe("CFOP dentro do estado (5xxx). Os interestaduais omitidos são sugeridos a partir dele (5102 → 6102 / 6108)."),
+    interstateContributor: z.string().nullish().describe("CFOP interestadual p/ contribuinte (6xxx)"),
+    interstateNonContributor: z.string().nullish().describe("CFOP interestadual p/ não contribuinte (6xxx)"),
+    internationalCfop: z.string().nullish().describe("CFOP de exportação (7xxx)"),
+    ncm: z.string().nullish().describe("NCM (8 dígitos)"),
+    cest: z.string().nullish().describe("CEST (7 dígitos) — obrigatório com ICMS-ST"),
+    taxRuleId: z.string().nullish().describe("Regra Fiscal de NF-e do produto (list_tax_rules)"),
+    icmsCst: z
+        .string()
+        .nullish()
+        .describe("CST (Regime Normal) ou CSOSN (Simples/MEI) — precisa ser da tabela do regime da empresa"),
+    icmsRate: z.number().nullish().describe("Alíquota do ICMS (%)"),
+    icmsRedBc: z.number().nullish().describe("Redução da base (%) — CST 20/70"),
+    icmsStModBc: z.enum(["4", "6"]).nullish().describe("Base do ICMS-ST: 4 = MVA, 6 = valor da operação"),
+    icmsStMva: z.number().nullish().describe("MVA do ICMS-ST (%) — modalidade 4"),
+    icmsStRedBc: z.number().nullish().describe("Redução da base do ICMS-ST (%)"),
+    icmsStRate: z.number().nullish().describe("Alíquota do ICMS-ST no destino (%)"),
+    icmsSnCreditRate: z.number().nullish().describe("Crédito do Simples (pCredSN, %) — CSOSN 101/201"),
+    // Desoneração e diferimento do PRÓPRIO produto — o padrão dele, que o item
+    // sobrescreve. Enumerados (e não deixados no passthrough) porque o motivo
+    // da desoneração depende do CST, e um valor plausível no CST errado reprova
+    // o schema com uma mensagem que não diz qual campo está fora.
+    icmsDesonValue: z
+        .number()
+        .nonnegative()
+        .nullish()
+        .describe("Valor do ICMS desonerado (vICMSDeson, R$) — CST 20/30/40/41/50/70/90. Omitido, é calculado pela alíquota."),
+    icmsDesonReason: z
+        .string()
+        .nullish()
+        .describe("Motivo da desoneração (motDesICMS). 🔴 A tabela muda POR CST: 3/9/10/11/12 no 20; " +
+        "6/7/9 no 30; 1/3/4/5/6/7/8/9/10/11/16/90 no 40, 41 e 50; 3/9/12 no 70 e no 90. " +
+        "Motivo fora da tabela do CST é recusado com 422."),
+    icmsDesonDeduct: z
+        .boolean()
+        .nullish()
+        .describe("indDeduzDeson — quando verdadeiro, o valor desonerado ABATE o total da nota. Ausente = falso."),
+    icmsDeferralRate: z
+        .number()
+        .nullish()
+        .describe("Percentual de diferimento (pDif, %) — CST 51. 100 é o caso comum e resulta em " +
+        "vICMS 0,00, que é DIFERENTE de isenção: o imposto existe e será recolhido adiante."),
+    icmsCBenef: z
+        .string()
+        .nullish()
+        .describe("Código de benefício fiscal da UF (cBenef, ex.: RS052001) — acompanha o icmsCst do " +
+        "produto. Sem ele, vários estados rejeitam (930) CST com benefício (20, 40, 41, 51, 90…)."),
+    pisCst: z.string().nullish(),
+    pisRate: z.number().nullish(),
+    cofinsCst: z.string().nullish(),
+    cofinsRate: z.number().nullish(),
+    ipiCst: z.string().nullish(),
+    ipiRate: z.number().nullish(),
+})
+    .passthrough()
+    .describe("Config. de NF-e do produto. Na nota, cada imposto vem do item → da tributação própria do produto → da regra fiscal → do template. Campo em branco cai na regra.");
+const productNfseConfigShape = z
+    .object({
+    serviceDescription: z.string().optional().describe("Discriminação do serviço"),
+    serviceListItem: z.string().nullish().describe("Item da LC 116 (ex.: 01.05)"),
+    municipalServiceCode: z.string().nullish(),
+    taxRuleId: z.string().nullish().describe("Regra Fiscal de NFS-e"),
+    issRate: z.number().nullish().describe("Alíquota do ISS (%). Vazio = a da empresa."),
+})
+    .passthrough()
+    .describe("Config. de NFS-e do produto");
+// ── Regras tributárias ─────────────────────────────────────────────────────
+server.tool("list_tax_rules", "Lista as regras tributárias da empresa (use o id em taxRuleId ao criar documentos).", {}, tool(() => api("GET", "/v1/tax-rules")));
+// ── Produtos ───────────────────────────────────────────────────────────────
+server.tool("list_products", "Lista os produtos da empresa, com a tributação própria de cada um. Use o id em items[].productId ao criar documentos.", {
+    page: z.number().int().positive().optional(),
+    pageSize: z.number().int().positive().max(100).optional(),
+    search: z.string().optional().describe("Busca por nome ou código"),
+}, tool((a) => api("GET", "/v1/products", { query: a })));
+server.tool("get_product", "Detalha um produto pelo id (configuração de NF-e com a tributação própria, e de NFS-e).", { id: z.string().describe("ID do produto") }, tool((a) => api("GET", `/v1/products/${encodeURIComponent(String(a.id))}`)));
+server.tool("create_product", "Cadastra um produto, opcionalmente com a tributação própria em nfeConfig. Campo de imposto preenchido no produto vale em toda venda dele; em branco, vale a regra fiscal.", {
+    name: z.string().describe("Nome do produto"),
+    code: z.string().describe("Código/SKU — único na empresa"),
+    salePrice: z.number().positive().describe("Preço de venda"),
+    profile: z.enum(["PRODUTOR", "AFILIADO", "COPRODUTOR"]).optional().describe("Default: PRODUTOR"),
+    emissionModel: z.enum(["NFE", "NFSE", "SPLIT"]).optional().describe("Default: NFE"),
+    nfeConfig: productNfeConfigShape.optional(),
+    nfseConfig: productNfseConfigShape.optional(),
+}, tool((a) => api("POST", "/v1/products", { body: a })));
+server.tool("update_product", "Atualiza um produto. Só os campos enviados mudam (null limpa); na tributação, o enviado é mesclado com o gravado — mandar só pisCst não apaga o CSOSN.", {
+    id: z.string().describe("ID do produto"),
+    name: z.string().optional(),
+    code: z.string().optional(),
+    salePrice: z.number().positive().optional(),
+    profile: z.enum(["PRODUTOR", "AFILIADO", "COPRODUTOR"]).optional(),
+    emissionModel: z.enum(["NFE", "NFSE", "SPLIT"]).optional(),
+    nfeConfig: productNfeConfigShape.optional(),
+    nfseConfig: productNfseConfigShape.optional(),
+}, tool(({ id, ...body }) => api("PATCH", `/v1/products/${encodeURIComponent(String(id))}`, { body })));
+// ── Financeiro (AP/AR) ─────────────────────────────────────────────────────
+//
+// As MESMAS leituras que o chat do sistema executa, aqui pela API pública. A
+// regra vive num lugar só (`finance/titles/`) — se cada caminho calculasse "o
+// que está vencido", o assistente do site e o do ChatGPT dariam números
+// diferentes para a mesma empresa.
+//
+// Quem pode: a chave precisa carregar `finance:read`/`finance:write`
+// LITERALMENTE (não vale "chave sem escopo = tudo") e a empresa precisa ter o
+// módulo. As duas condições são checadas na API — aqui só encaminhamos, e um
+// 403 dela vira texto de erro para o modelo.
+server.tool("list_overdue_receivables", "Contas a receber VENCIDAS, da mais antiga para a mais nova (ordem de cobrança). `total` soma todas as vencidas mesmo quando a lista vem truncada.", { limite: z.number().int().positive().max(100).optional().describe("Máx. de contas listadas. Default: 20.") }, tool((a) => api("GET", "/v1/finance/receivables/overdue", { query: a })));
+server.tool("top_delinquent_clients", "Quem mais deve, agrupado por cliente, com o maior atraso de cada um. Use para priorizar cobrança.", { limite: z.number().int().positive().max(100).optional() }, tool((a) => api("GET", "/v1/finance/receivables/delinquent-clients", { query: a })));
+server.tool("cashflow_projection", "Projeção de caixa por vencimento. NÃO inclui saldo bancário, e o que já venceu vem separado — nunca some `vencidoNaoRecebido` ao `resultadoPrevisto`: isso assumiria que o inadimplente vai pagar.", { dias: z.number().int().positive().max(365).optional().describe("Horizonte em dias. Default: 30.") }, tool((a) => api("GET", "/v1/finance/cashflow-projection", { query: a })));
+server.tool("list_finance_titles", "Lista as PARCELAS de contas a receber ou a pagar. A parcela é a unidade que vence e que recebe baixa. Use `derivedStatus` (não `status`) para saber se atrasou.", {
+    kind: z.enum(["RECEIVABLE", "PAYABLE"]).describe("RECEIVABLE = a receber; PAYABLE = a pagar"),
+    due: z
+        .enum([
+        "VENCIDAS",
+        "VENCE_HOJE",
+        "PROXIMOS_7",
+        "EM_ABERTO",
+        "TODAS",
+        "A_CONFIRMAR",
+        "D1A30",
+        "D31A60",
+        "D61A90",
+        "D91MAIS",
+    ])
+        .optional()
+        .describe("Recorte. A_CONFIRMAR = fila sem vencimento informado."),
+    search: z.string().optional().describe("Busca por descrição ou contraparte"),
+    includeSettled: z.boolean().optional().describe("Inclui as já quitadas"),
+    page: z.number().int().positive().optional(),
+    pageSize: z.number().int().positive().max(100).optional(),
+}, tool((a) => api("GET", "/v1/finance/titles", { query: a })));
+server.tool("get_finance_summary", "Totais em aberto e aging (faixas de atraso) de um lado. As faixas somam `totalAberto − aConfirmar`, não o total.", { kind: z.enum(["RECEIVABLE", "PAYABLE"]) }, tool((a) => api("GET", "/v1/finance/summary", { query: a })));
+server.tool("get_finance_title", "Ficha completa de um título: parcelas e histórico de baixas, incluindo as ESTORNADAS (`reversedAt` preenchido, e fora de toda soma).", { id: z.string().describe("ID do título") }, tool((a) => api("GET", `/v1/finance/titles/${encodeURIComponent(String(a.id))}`)));
+server.tool("create_finance_title", "Lança uma conta a receber ou a pagar. Conta à vista é 1 parcela. Use `schedule` quando já souber os vencimentos — ele vence `installments`/`totalAmount`.", {
+    kind: z.enum(["RECEIVABLE", "PAYABLE"]),
+    description: z.string().describe("Descrição da conta"),
+    totalAmount: z.string().describe('Valor total em string decimal ("1234.56")'),
+    dueDate: z.string().describe("Vencimento da 1ª parcela (YYYY-MM-DD)"),
+    counterpartyName: z.string().optional().describe("Cliente (receber) ou fornecedor (pagar)"),
+    counterpartyDocument: z.string().optional().describe("CPF/CNPJ da contraparte"),
+    installments: z.number().int().positive().max(360).optional(),
+    interval: z.enum(["MONTHLY", "WEEKLY"]).optional(),
+    categoryId: z.string().optional(),
+    clientId: z.string().optional(),
+}, tool((a) => api("POST", "/v1/finance/titles", { body: a })));
+server.tool("settle_finance_installment", "Registra uma baixa na PARCELA (não no título). `amount` é o PRINCIPAL, o que abate a conta — juros e multa vão nos campos próprios e não abatem saldo. Valor menor que o saldo é baixa parcial, caminho normal.", {
+    installmentId: z.string().describe("ID da PARCELA (vem de list_finance_titles)"),
+    amount: z.string().describe('Principal em string decimal ("500.00")'),
+    date: z.string().describe("Data da baixa (YYYY-MM-DD)"),
+    interestAmount: z.string().optional().describe("Juros — por fora do principal"),
+    fineAmount: z.string().optional().describe("Multa — por fora do principal"),
+    discountAmount: z.string().optional(),
+}, tool((a) => api("POST", `/v1/finance/installments/${encodeURIComponent(String(a.installmentId))}/settlements`, {
+    body: {
+        amount: a.amount,
+        date: a.date,
+        interestAmount: a.interestAmount,
+        fineAmount: a.fineAmount,
+        discountAmount: a.discountAmount,
+    },
+})));
+// ── Notas recebidas (DF-e) e modo contador ─────────────────────────────────
+//
+// Notas RECEBIDAS são as que os fornecedores emitem contra o CNPJ da empresa
+// (Distribuição DF-e da SEFAZ e NFS-e do Padrão Nacional). As mesmas rotas
+// servem os dois tipos de chave, e é o `companyId` que escolhe:
+//   - sem `companyId` → a empresa da chave (chave `ck_`/token OAuth, escopo
+//     `received-documents:*`);
+//   - com `companyId` → uma empresa da CARTEIRA do escritório (chave do
+//     escritório `ok_`, modo contador). A API recusa empresa sem vínculo ativo.
+// As ferramentas de fechamento e carteira exigem a chave do escritório; com a
+// chave de uma empresa a API responde 401 `office_key_required`, dizendo isso.
+const RD_COMPANY = z
+    .string()
+    .optional()
+    .describe("SÓ no modo contador (chave do escritório `ok_`): a empresa da carteira. Omita com a chave de uma empresa.");
+function receivedBase(companyId) {
+    return companyId
+        ? `/v1/accounting/companies/${encodeURIComponent(String(companyId))}/received-documents`
+        : "/v1/received-documents";
+}
+server.tool("list_received_documents", "Lista as notas RECEBIDAS (emitidas contra o CNPJ pelos fornecedores), NSU mais novo primeiro. `pending=true` = só as NF-e que ainda precisam de manifestação. `schemaType` RES_NFE é só o resumo: manifeste CIENCIA para liberar o XML completo.", {
+    companyId: RD_COMPANY,
+    pending: z.boolean().optional().describe("Só a fila de manifestação"),
+    model: z.enum(["NFE", "NFSE"]).optional(),
+    manifestation: z
+        .enum(["NONE", "CIENCIA", "CONFIRMADA", "DESCONHECIDA", "NAO_REALIZADA"])
+        .optional(),
+    search: z.string().optional().describe("Trecho da chave, do CNPJ ou do nome do emitente"),
+    issuerCnpj: z.string().optional().describe("CNPJ do fornecedor"),
+    emittedFrom: z.string().optional().describe("Emitidas a partir de (AAAA-MM-DD, BRT)"),
+    emittedTo: z.string().optional().describe("Emitidas até (AAAA-MM-DD, BRT)"),
+    page: z.number().int().positive().optional(),
+    pageSize: z.number().int().positive().max(100).optional(),
+}, tool((a) => {
+    const { companyId, ...query } = a;
+    return api("GET", receivedBase(companyId), { query });
+}));
+server.tool("get_received_document", "Detalha uma nota recebida: emitente, valor, situação, manifestação e se a DANFE já pode ser gerada (`pdf.available`, com o motivo quando não).", {
+    id: z.string().describe("ID da nota recebida"),
+    companyId: RD_COMPANY,
+}, tool((a) => api("GET", `${receivedBase(a.companyId)}/${encodeURIComponent(String(a.id))}`)));
+server.tool("get_received_document_xml", "Baixa o XML da nota recebida (o resumo enquanto não houver Ciência; a nota completa depois).", {
+    id: z.string().describe("ID da nota recebida"),
+    companyId: RD_COMPANY,
+}, tool((a) => api("GET", `${receivedBase(a.companyId)}/${encodeURIComponent(String(a.id))}/xml`)));
+server.tool("manifest_received_document", "Manifesta a nota recebida perante a SEFAZ, EM NOME DA EMPRESA — é ato jurídico e NÃO TEM DESFAZER. Confirme com o usuário antes de DESCONHECIDA ou NAO_REALIZADA (recusam a nota e cancelam a conta a pagar dela). CIENCIA libera o XML completo. NAO_REALIZADA exige `justification` com 15+ caracteres. Só NF-e.", {
+    id: z.string().describe("ID da nota recebida"),
+    type: z.enum(["CIENCIA", "CONFIRMADA", "DESCONHECIDA", "NAO_REALIZADA"]),
+    justification: z.string().optional().describe("Obrigatória em NAO_REALIZADA (15+ caracteres)"),
+    companyId: RD_COMPANY,
+}, tool((a) => api("POST", `${receivedBase(a.companyId)}/${encodeURIComponent(String(a.id))}/manifestation`, { body: { type: a.type, justification: a.justification } })));
+server.tool("sync_received_documents", "Busca agora, na SEFAZ, as notas recebidas novas (a busca já roda sozinha a cada hora). Assíncrono. Depois de uma consulta sem novidades a SEFAZ exige 1h de espera: a resposta 429 `sefaz_wait` traz quando tentar de novo — não repita antes.", {
+    companyId: RD_COMPANY,
+}, tool((a) => api("POST", `${receivedBase(a.companyId)}/sync`)));
+server.tool("get_received_documents_distribution", "Estado da busca de notas recebidas: último NSU, último retorno da SEFAZ, se há certificado e quando a próxima sincronização manual é permitida (`nextSyncAllowedAt`).", {
+    companyId: RD_COMPANY,
+}, tool((a) => api("GET", `${receivedBase(a.companyId)}/distribution`)));
+server.tool("get_received_documents_export_link", "Download em LOTE: todas as notas recebidas de um MÊS num ZIP (XMLs em notas/ e eventos/). Devolve um LINK (`url`) — entregue-o ao usuário como link clicável para ele baixar no navegador; NÃO tente abrir nem ler o ZIP. O link vale 15 minutos. Sem `companyId`: a empresa da chave. MODO CONTADOR (chave do escritório): `companyId` = uma empresa da carteira; `portfolio: true` (ou `companyIds`) = várias empresas num ZIP só, uma pasta por empresa. `pendingSummaries` > 0 = NF-e que só têm o resumo: manifeste CIENCIA para a nota completa entrar no pacote. Mês sem nada volta 404 `no_documents`.", {
+    year: z.number().int().describe("Ano (ex.: 2026)"),
+    month: z.number().int().min(1).max(12).describe("Mês, 1–12 (mês de EMISSÃO, horário de Brasília)"),
+    companyId: RD_COMPANY,
+    portfolio: z
+        .boolean()
+        .optional()
+        .describe("SÓ no modo contador: true = a carteira inteira (até 200 empresas) num ZIP só"),
+    companyIds: z
+        .array(z.string())
+        .optional()
+        .describe("SÓ no modo contador: estas empresas da carteira num ZIP só (uma pasta cada)"),
+    notes: z.boolean().optional().describe("NF-e completas e NFS-e (padrão: sim)"),
+    events: z.boolean().optional().describe("Eventos: cancelamentos, CC-e, manifestações (padrão: sim)"),
+    summaries: z
+        .boolean()
+        .optional()
+        .describe("Resumos das NF-e ainda não manifestadas (padrão: não)"),
+}, tool((a) => {
+    const body = {
+        year: a.year,
+        month: a.month,
+        notes: a.notes,
+        events: a.events,
+        summaries: a.summaries,
+    };
+    if (a.portfolio || (Array.isArray(a.companyIds) && a.companyIds.length > 0)) {
+        return api("POST", "/v1/accounting/received-documents/export/link", {
+            body: { ...body, companyIds: a.companyIds },
+        });
+    }
+    return api("POST", `${receivedBase(a.companyId)}/export/link`, { body });
+}));
+server.tool("get_accounting_office", "MODO CONTADOR (chave do escritório `ok_`): o escritório, quantas empresas estão na carteira e os escopos da chave.", {}, tool(() => api("GET", "/v1/accounting/office")));
+server.tool("get_simples_estimate", "Estimativa do DAS do Simples Nacional na competência (AAAA-MM; padrão o mês corrente), pelas notas autorizadas em produção. É ESTIMATIVA: com `status: incomplete` o `das` vem null e `pendencies` diz o que falta (receita de meses anteriores ao sistema, anexo dos serviços, folha) — nunca invente o valor. `two_scenarios` = fator R sem folha: o DAS fica entre o Anexo III e o V. Escopo `simples:read`.", {
+    companyId: RD_COMPANY,
+    competence: z.string().optional().describe("Competência AAAA-MM"),
+}, tool((a) => {
+    const { companyId, ...query } = a;
+    const path = companyId
+        ? `/v1/accounting/companies/${encodeURIComponent(String(companyId))}/simples/estimate`
+        : "/v1/simples/estimate";
+    return api("GET", path, { query });
+}));
+server.tool("list_portfolio_das_estimates", "MODO CONTADOR: o DAS estimado de cada empresa da carteira na competência (AAAA-MM; padrão o mês corrente). `status: incomplete` = faltam dados naquela empresa (detalhe com get_simples_estimate + companyId); `error` = a conta falhou só nela.", {
+    competence: z.string().optional().describe("Competência AAAA-MM"),
+}, tool((a) => api("GET", "/v1/accounting/simples/estimates", { query: a })));
+server.tool("simulate_simples_ibscbs_regime", "Simula, para empresa do Simples Nacional, recolher o IBS/CBS DENTRO do DAS × FORA dele (regime regular, opção semestral a partir de 2027: em setembro para jan–jun e em março para jul–dez). Devolve o imposto da empresa nos dois casos (`inside.das` × `outside.total`), o crédito que os clientes com CNPJ recuperam (`clientsCredit`), a `reading` e as `premises`. É ESTIMATIVA para conversar com o contador, nunca recomendação fiscal. `cbs_not_published` = a CBS do ano não saiu: só mande `cbs` se a PESSOA informar a alíquota a simular — nunca chute, e diga que o resultado usa a premissa dela. Cobre 2027 e 2028. Escopo `simples:read`.", {
+    companyId: RD_COMPANY,
+    year: z.number().int().optional().describe("2027 ou 2028. Padrão: o ano seguinte"),
+    cbs: z.number().optional().describe("CBS a simular (%), SÓ quando informada pela pessoa"),
+}, tool((a) => {
+    const { companyId, ...query } = a;
+    const path = companyId
+        ? `/v1/accounting/companies/${encodeURIComponent(String(companyId))}/simples/regime-ibscbs`
+        : "/v1/simples/regime-ibscbs";
+    return api("GET", path, { query });
+}));
+server.tool("get_simples_das_forecast", "Previsão do DAS do MÊS CORRENTE se o mês seguir no ritmo dos dias já decorridos, e a RBT12 e a faixa do mês seguinte (`nextMonth.warnings`: muda_de_faixa | sublimite | teto — avise ANTES de acontecer). `fewDays: true` = poucos dias, projeção instável: diga isso. Escopo `simples:read`.", {
+    companyId: RD_COMPANY,
+}, tool((a) => {
+    const path = a.companyId
+        ? `/v1/accounting/companies/${encodeURIComponent(String(a.companyId))}/simples/forecast`
+        : "/v1/simples/forecast";
+    return api("GET", path);
+}));
+server.tool("get_product_tax_in_price", "Quanto do preço de um produto é imposto (empresa do Simples): alíquota efetiva do DAS do anexo do produto, imposto no preço, margem e o PREÇO MÍNIMO para a margem desejada. Valores em string decimal (\"40.00\"). `minimumPrice: null` = imposto + despesas + margem passam de 100%. Nada é gravado. Escopo `simples:read`.", {
+    productId: z.string().describe("Id do produto (list_products)"),
+    cost: z.string().describe("Custo unitário, decimal em string"),
+    price: z.string().optional().describe("Preço a avaliar. Padrão: o preço de venda cadastrado"),
+    expensesRate: z.number().optional().describe("Outras despesas, % do preço (cartão, comissão)"),
+    marginRate: z.number().optional().describe("Margem desejada, % do preço"),
+}, tool((a) => api("GET", "/v1/simples/pricing", { query: a })));
+server.tool("list_suspicious_received_documents", "NF-e recebidas (últimos 60 dias, ainda sem decisão) de fornecedor que NUNCA emitiu para a empresa e com valor ou mercadoria fora do padrão — pode ser nota fria contra o CNPJ. Apresente como algo a CONFERIR, nunca como acusação. Se a pessoa disser que a compra não aconteceu, a saída é manifestar Desconhecimento da operação (manifest_received_document, `210220`) — só com a confirmação dela. Escopo `received-documents:read`.", {
+    companyId: RD_COMPANY,
+}, tool((a) => {
+    const path = a.companyId
+        ? `/v1/accounting/companies/${encodeURIComponent(String(a.companyId))}/received-documents/suspicious`
+        : "/v1/received-documents/suspicious";
+    return api("GET", path);
+}));
+server.tool("list_portfolio_companies", "MODO CONTADOR: as empresas-cliente com vínculo ATIVO com o escritório. O `id` de cada uma é o `companyId` das outras ferramentas.", {
+    search: z.string().optional().describe("Trecho do nome ou do CNPJ"),
+    page: z.number().int().positive().optional(),
+    pageSize: z.number().int().positive().max(100).optional(),
+}, tool((a) => api("GET", "/v1/accounting/companies", { query: a })));
+server.tool("list_closing_eligible_companies", "MODO CONTADOR: empresas da carteira com nota de PRODUÇÃO autorizada ou cancelada no mês (BRT) — as que o fechamento vai processar. Mês é 1–12.", {
+    year: z.number().int().describe("Ano (ex.: 2026)"),
+    month: z.number().int().min(1).max(12).describe("Mês, 1–12"),
+}, tool((a) => api("GET", "/v1/accounting/closings/eligible", { query: a })));
+server.tool("request_fiscal_closings", "MODO CONTADOR: pede o fechamento fiscal do mês — um ZIP por empresa com XML e/ou DANFE. Assíncrono: acompanhe com list_fiscal_closings. Sem `companyIds` vale para a carteira inteira (até 200). Empresa sem nota no mês, com fechamento em andamento ou fora da carteira volta em `skipped`, com o motivo.", {
+    year: z.number().int(),
+    month: z.number().int().min(1).max(12).describe("Mês, 1–12"),
+    companyIds: z.array(z.string()).optional().describe("Omitido = carteira inteira"),
+    includeXml: z.boolean().optional().describe("Default true"),
+    includePdf: z.boolean().optional().describe("Default true"),
+}, tool((a) => api("POST", "/v1/accounting/closings", { body: a })));
+server.tool("list_fiscal_closings", "MODO CONTADOR: os fechamentos fiscais da carteira e a situação de cada um (PENDING, PROCESSING, COMPLETED, FAILED).", {
+    companyId: z.string().optional(),
+    year: z.number().int().optional(),
+    month: z.number().int().min(1).max(12).optional().describe("1–12"),
+    status: z.enum(["PENDING", "PROCESSING", "COMPLETED", "FAILED"]).optional(),
+    page: z.number().int().positive().optional(),
+    pageSize: z.number().int().positive().max(100).optional(),
+}, tool((a) => api("GET", "/v1/accounting/closings", { query: a })));
+server.tool("get_fiscal_closing_download", "MODO CONTADOR: link para baixar o ZIP de um fechamento COMPLETED (válido por 1 hora). Antes de terminar, a resposta diz a situação atual.", {
+    id: z.string().describe("ID do fechamento (closingId)"),
+}, tool((a) => api("GET", `/v1/accounting/closings/${encodeURIComponent(String(a.id))}/download`)));
+// ── Webhooks ───────────────────────────────────────────────────────────────
+server.tool("list_webhooks", "Lista os endpoints de webhook da empresa.", {}, tool(() => api("GET", "/v1/webhooks")));
+server.tool("create_webhook", "Cria um endpoint de webhook que recebe eventos assinados (document.authorized/rejected/cancelled/inutilized). O segredo de assinatura é retornado apenas uma vez.", {
+    url: z.string().url().describe("URL HTTPS que recebe os eventos"),
+    events: z.array(z.string()).optional().describe("Eventos assinados. Omitido/vazio = todos."),
+}, tool((a) => api("POST", "/v1/webhooks", { body: a })));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("[conflaro-mcp] pronto (stdio).");

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "conflaro-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.8.1",
+  "description": "Servidor MCP da Conflaro — emissão fiscal (NF-e, NFC-e, NFS-e) por IA",
+  "mcpName": "io.conttrole/mcp",
+  "type": "module",
+  "bin": {
+    "conflaro-mcp": "dist/index.js",
+    "conttrole-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}