@comando.one/mcp-server 0.3.1 → 0.4.0

package/README.md

@@ -51,7 +51,7 @@ Ambos expõem o **mesmo conjunto de ferramentas** (50 curadas + `lookups` + `com
 
 ## Como funciona
 
-- **126 tools curadas** (gerados a partir do OpenAPI canônico, zero drift) cobrindo as operações de maior valor — `customers_list`, `invoices_create`/`invoices_delete`, `charges_create`, `nfse_emit`, `payouts_create`, `contracts_pause`/`contracts_resume`, `service_categories_create`, `reports_aging_actions`/`reports_cashflow_forecast`, `audit_timeline`, `cost_centers_create`, etc.
+- **127 tools curadas** (gerados a partir do OpenAPI canônico, zero drift) cobrindo as operações de maior valor — `customers_list`, `invoices_create`/`invoices_delete`, `charges_create`, `nfse_emit`, `payouts_create`, `contracts_pause`/`contracts_resume`, `service_categories_create`, `reports_aging_actions`/`reports_cashflow_forecast`, `audit_timeline`, `documents_analyze` (lê boleto/guia/NF anexada e extrai valor, vencimento e emitente), `cost_centers_create`, etc.
 - **`comando_request`** — escape hatch genérico (`method`, `path`, `query`, `body`) que cobre 100% dos endpoints restantes.
 - **`lookups`** — catálogos read-only (centros de custo, condições/métodos de pagamento, naturezas, contas bancárias).
 - **`whoami`** — identidade, empresas acessíveis e scopes da chave.

package/dist/index.js

@@ -172,6 +172,7 @@ var MANIFEST = [
   { operationId: "getPurchaseInvoice", tool: "purchase_invoices_get" },
   { operationId: "createPurchaseInvoice", tool: "purchase_invoices_create", write: true },
   { operationId: "cancelPurchaseInvoice", tool: "purchase_invoices_cancel", write: true, destructive: true },
+  { operationId: "deletePurchaseInvoice", tool: "purchase_invoices_delete", write: true, destructive: true },
   // ----- Despesas & Serviços -----
   { operationId: "listExpenses", tool: "expenses_list" },
   { operationId: "createExpense", tool: "expenses_create", write: true },
@@ -192,6 +193,7 @@ var MANIFEST = [
   { operationId: "reverseSplitExecution", tool: "split_reverse", write: true, destructive: true },
   { operationId: "releaseSplitItem", tool: "split_release_item", write: true },
   // Auditoria
+  { operationId: "analyzeDocument", tool: "documents_analyze", write: true },
   { operationId: "getAuditTimeline", tool: "audit_timeline" },
   // Categorias de serviço
   { operationId: "listServiceCategories", tool: "service_categories_list" },
@@ -833,10 +835,32 @@ var SCHEMAS = {
             description: { type: "string" },
             amount: { type: "number" },
             due_date: { type: "string", format: "date" },
-            payment_status: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"], default: "pendente" }
+            payment_status: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"], default: "pendente" },
+            boleto_barcode: { type: "string", description: "Linha digit\xE1vel / c\xF3digo de barras do boleto (s\xF3 d\xEDgitos)." },
+            pix_key: { type: "string" },
+            pix_copia_e_cola: { type: "string" }
           }
         }
       },
+      items: {
+        type: "array",
+        description: "Itens da fatura. Se omitido, o valor de 'amount' vira um item \xFAnico \u2014 a fatura n\xE3o pode ficar sem item (o formul\xE1rio do app n\xE3o salva assim).",
+        items: {
+          type: "object",
+          required: ["name"],
+          properties: {
+            name: { type: "string" },
+            description: { type: "string" },
+            unit: { type: "string", default: "un" },
+            quantity: { type: "number", default: 1 },
+            unit_price: { type: "number" },
+            subtotal: { type: "number", description: "Calculado de quantity \xD7 unit_price quando omitido." }
+          }
+        }
+      },
+      title: { type: "string", description: "Descri\xE7\xE3o da fatura; vira o nome do item quando 'items' n\xE3o \xE9 informado." },
+      digitable_line: { type: "string", description: "Atalho: grava o boleto na parcela \xFAnica criada por 'due_date'." },
+      pix_key: { type: "string", description: "Atalho: grava a chave Pix na parcela \xFAnica." },
       notes: { type: "string" }
     }
   },
@@ -2217,6 +2241,51 @@ var OPENAPI_SPEC = {
         responses: { "200": paginatedResponse("#/components/schemas/ServiceUnit"), ...COMMON_ERRORS }
       }
     },
+    "/documents/analyze": {
+      post: {
+        tags: ["Documentos"],
+        summary: "Analisar documento anexado",
+        operationId: "analyzeDocument",
+        description: "L\xEA um anexo da empresa (PDF, imagem ou texto) e extrai os campos financeiros: tipo do documento, valor, vencimento, n\xFAmero, emitente, linha digit\xE1vel do boleto e chave Pix. Usa o texto do arquivo e, quando ele n\xE3o basta (PDF escaneado), a leitura visual do modelo.",
+        security: [{ ApiKeyAuth: ["documents:read"] }],
+        requestBody: {
+          required: true,
+          content: { "application/json": { schema: {
+            type: "object",
+            properties: {
+              attachment_id: { type: "string", format: "uuid", description: "UUID do anexo em entity_attachments." },
+              file_name: { type: "string", description: "Alternativa ao id: parte do nome do arquivo." }
+            }
+          } } }
+        },
+        responses: {
+          "200": {
+            description: "Campos extra\xEDdos do documento",
+            content: { "application/json": { schema: {
+              type: "object",
+              properties: {
+                attachment_id: { type: "string", format: "uuid" },
+                file_name: { type: "string" },
+                kind: { type: "string", description: "boleto | arrecadacao | nfe | nfse | fatura | recibo | desconhecido" },
+                direction: { type: "string", description: "pagar | receber | indefinido" },
+                amount: { type: "number", nullable: true },
+                due_date: { type: "string", format: "date", nullable: true },
+                document_number: { type: "string", nullable: true },
+                barcode: { type: "string", nullable: true },
+                digitable_line: { type: "string", nullable: true },
+                pix_key: { type: "string", nullable: true },
+                counterparty_name: { type: "string", nullable: true },
+                counterparty_document: { type: "string", nullable: true },
+                is_own_company_document: { type: "boolean", description: "O documento encontrado \xE9 o da pr\xF3pria empresa (contribuinte/pagador)." },
+                missing: { type: "array", items: { type: "string" }, description: "Campos essenciais que n\xE3o foi poss\xEDvel extrair." },
+                extracted: { type: "boolean" }
+              }
+            } } }
+          },
+          "404": { description: "Documento n\xE3o encontrado" }
+        }
+      }
+    },
     "/audit/timeline": {
       get: {
         tags: ["Auditoria"],
@@ -2597,6 +2666,14 @@ var OPENAPI_SPEC = {
         operationId: "getPurchaseInvoice",
         security: [{ ApiKeyAuth: ["purchase_invoices:read"] }],
         responses: { "200": { description: "Conta a pagar", content: { "application/json": { schema: { $ref: "#/components/schemas/PurchaseInvoice" } } } }, "404": errorResponse("Conta a pagar n\xE3o encontrada"), ...COMMON_ERRORS }
+      },
+      delete: {
+        tags: ["Contas a Pagar"],
+        summary: "Excluir conta a pagar",
+        operationId: "deletePurchaseInvoice",
+        description: "Exclus\xE3o definitiva. Recusa (409) contas com pagamento registrado ou parcela paga \u2014 nesses casos use o cancelamento, que preserva o hist\xF3rico.",
+        security: [{ ApiKeyAuth: ["purchase_invoices:delete"] }],
+        responses: { "204": { description: "Exclu\xEDda" }, "404": errorResponse("Conta a pagar n\xE3o encontrada"), "409": errorResponse("H\xE1 pagamento registrado ou registros vinculados que impedem a exclus\xE3o"), ...COMMON_ERRORS }
       }
     },
     "/purchase-invoices/{id}/cancel": {
@@ -3091,6 +3168,13 @@ var OPENAPI_SPEC = {
 
 // ../../src/lib/apiScopes.ts
 var API_MODULES = [
+  {
+    key: "documents",
+    label: "Documentos",
+    permissions: [
+      { key: "read", label: "Analisar documentos", description: "Ler anexos (boleto, guia, NF) e extrair valor, vencimento e emitente" }
+    ]
+  },
   {
     key: "customers",
     label: "Clientes",
@@ -3180,7 +3264,8 @@ var API_MODULES = [
     permissions: [
       { key: "read", label: "Listar e visualizar", description: "Consultar contas a pagar" },
       { key: "create", label: "Criar", description: "Lan\xE7ar contas a pagar" },
-      { key: "cancel", label: "Cancelar", description: "Cancelar contas a pagar" }
+      { key: "cancel", label: "Cancelar", description: "Cancelar contas a pagar" },
+      { key: "delete", label: "Excluir", description: "Excluir contas a pagar definitivamente" }
     ]
   },
   {
@@ -3305,7 +3390,9 @@ function describeOperation(operationId) {
     const d = declaredByName.get(name);
     properties[name] = {
       ...d?.schema ?? { type: "string" },
-      description: d?.description ?? `Identificador (${name}).`
+      description: d?.description ?? // Sem dizer que é UUID, o planner manda o identificador humano que tem em mãos
+      // (o número da nota) e a chamada morre. Observado em 2026-08-24.
+      `UUID do registro (${name}). Obtenha em uma listagem ou consulta \u2014 N\xC3O \xE9 n\xFAmero, c\xF3digo ou nome.`
     };
     required.push(name);
   }
@@ -3346,6 +3433,7 @@ function describeOperation(operationId) {
     scopes: extractScopes(operation),
     inputSchema,
     summary: operation.summary,
+    description: operation.description,
     description: operation.description
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comando.one/mcp-server",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Servidor MCP (Model Context Protocol) para a API pública do Comando.One — opere seu ERP por linguagem natural.",
   "type": "module",
   "license": "MIT",