@comando.one/mcp-server 0.3.0 → 0.3.2

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

@@ -192,6 +192,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" },
@@ -2217,6 +2218,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"],
@@ -3091,6 +3137,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",
@@ -3415,6 +3468,22 @@ function augmentInputSchema(schema, opts) {
   }
   return { ...schema, properties };
 }
+function coerceObjectArg(value) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    return value;
+  }
+  if (typeof value === "string" && value.trim()) {
+    try {
+      const parsed = JSON.parse(value);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed;
+      }
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
 function destructiveBlocked(args) {
   if (args.confirm === true) return null;
   return fail(
@@ -3463,7 +3532,7 @@ function buildCuratedTools(api, heldScopes) {
             if (blocked && args.dry_run !== true) return blocked;
           }
           const path = buildPath(desc, args);
-          const body = desc.hasBody ? args.body : void 0;
+          const body = desc.hasBody ? coerceObjectArg(args.body) : void 0;
           if (args.dry_run === true) {
             return ok({
               dry_run: true,
@@ -3527,15 +3596,16 @@ function buildRequestTool(api) {
         }
         let path = String(args.path ?? "");
         if (!path.startsWith("/")) return fail("path deve come\xE7ar com / (ex.: /customers).");
-        if (args.query && typeof args.query === "object") {
+        const queryArg = coerceObjectArg(args.query);
+        if (queryArg) {
           const u = new URLSearchParams();
-          for (const [k, v] of Object.entries(args.query)) {
+          for (const [k, v] of Object.entries(queryArg)) {
             if (v !== void 0 && v !== null && v !== "") u.set(k, String(v));
           }
           const s = u.toString();
           if (s) path += (path.includes("?") ? "&" : "?") + s;
         }
-        const body = args.body && typeof args.body === "object" ? args.body : void 0;
+        const body = coerceObjectArg(args.body);
         if (args.dry_run === true) {
           return ok({ dry_run: true, method, path, body: body ?? null });
         }

package/package.json

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