@comando.one/mcp-server 0.11.1 → 0.12.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +12 -7
  2. package/dist/index.js +122 -40
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @comando.one/mcp-server
2
2
 
3
- Servidor **MCP (Model Context Protocol)** para a API pública do **Comando1**. Conecte o Claude (Desktop, Code ou qualquer cliente MCP) ao seu ERP e **opere tudo por linguagem natural**: clientes, propostas, contratos, faturas, cobranças Pix/boleto, NFS-e, contas a pagar, financeiro e webhooks.
3
+ Servidor **MCP (Model Context Protocol)** para a API pública do **Comando1**. Conecte o Claude (Desktop, Code ou qualquer cliente MCP) ao seu ERP e **opere tudo por linguagem natural**: clientes, propostas, contratos e reajustes, faturas e baixas, cobranças Pix/boleto, NFS-e, contas a pagar, pagamentos a fornecedor e split, financeiro e conciliação, caixa de entrada, DDA, recorrências, insumos, lembretes, notificações, relatórios e webhooks.
4
4
 
5
5
  ## Instalação rápida (Claude Desktop)
6
6
 
@@ -25,7 +25,11 @@ Gere sua chave em **Configurações → API Keys** no app. Reinicie o Claude Des
25
25
 
26
26
  ## Alternativa: MCP remoto (sem instalar nada)
27
27
 
28
- Além deste pacote stdio, existe um **endpoint MCP remoto (streaming)** em `https://api.comando.one/mcp` (transporte MCP Streamable HTTP). Para clientes com conector remoto:
28
+ Além deste pacote stdio, existe um **endpoint MCP remoto (streaming)** em `https://api.comando.one/mcp` (transporte MCP Streamable HTTP).
29
+
30
+ **Com OAuth (recomendado):** no Claude (Desktop ou web), ChatGPT e outros clientes com conector remoto, basta colar a URL `https://api.comando.one/mcp` — o cliente abre o navegador, você entra no Comando1, escolhe a empresa e autoriza. Não há chave para copiar.
31
+
32
+ **Com chave de API**, para clientes que aceitam cabeçalho fixo:
29
33
 
30
34
  ```json
31
35
  {
@@ -39,7 +43,7 @@ Além deste pacote stdio, existe um **endpoint MCP remoto (streaming)** em `http
39
43
  }
40
44
  ```
41
45
 
42
- Ambos expõem o **mesmo conjunto de ferramentas** (131 curadas + `lookups` + `comando_request` = cobertura total da API).
46
+ Ambos expõem as mesmas ferramentas: **169 tools curadas** (uma por operação da API) + `lookups` + `comando_request`. Só o stdio tem `whoami`.
43
47
 
44
48
  ## Variáveis de ambiente
45
49
 
@@ -51,8 +55,8 @@ Ambos expõem o **mesmo conjunto de ferramentas** (131 curadas + `lookups` + `co
51
55
 
52
56
  ## Como funciona
53
57
 
54
- - **136 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`, `invoices_settle_charge` (dá baixa numa parcela — registra o recebimento), etc.
55
- - **`comando_request`** — escape hatch genérico (`method`, `path`, `query`, `body`) que cobre 100% dos endpoints restantes.
58
+ - **169 tools curadas** (geradas a partir do OpenAPI canônico, zero drift) — uma por operação da API, por exemplo `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`, `invoices_settle_charge` (dá baixa numa parcela — registra o recebimento), etc.
59
+ - **`comando_request`** — escape hatch genérico (`method`, `path`, `query`, `body`) para qualquer rota; as destrutivas continuam exigindo `confirm`.
56
60
  - **`lookups`** — catálogos read-only (centros de custo, condições/métodos de pagamento, naturezas, contas bancárias).
57
61
  - **`whoami`** — identidade, empresas acessíveis e scopes da chave.
58
62
  - **Nomes em português** — cada tool viaja com `title` (e `annotations.title`) vindo do
@@ -62,8 +66,9 @@ Ambos expõem o **mesmo conjunto de ferramentas** (131 curadas + `lookups` + `co
62
66
 
63
67
  ### Segurança
64
68
 
65
- - **Scope-gating**: ao iniciar, o servidor chama `/me` e **só expõe as tools cujos scopes a chave possui**.
66
- - **Ações destrutivas** (`*_delete`, `*_cancel`, `charges_refund`, `payouts_create`) exigem `confirm: true` para executar e aceitam `dry_run: true` para pré-visualizar a requisição sem enviá-la.
69
+ - **Scope-gating**: ao iniciar, o servidor chama `/me` e **só expõe as tools cujos scopes a chave possui**. Quando a operação aceita mais de um scope (ex.: `cost_centers_list` com `expenses:read` **ou** `finance:read`), basta um deles.
70
+ - **Ações destrutivas** — exclusões e cancelamentos, estornos (`charges_refund`, `invoices_reverse_payment`, `split_reverse`), pagamentos (`payouts_create`), reajustes (`contracts_readjustments_apply`/`_revert`), `reconciliation_unmatch` e afins; a descrição da tool começa com `[DESTRUTIVA]` — exigem `confirm: true` para executar e aceitam `dry_run: true` para pré-visualizar a requisição sem enviá-la.
71
+ - **2FA de pagamento**: se a empresa exige 2FA para movimentar dinheiro, pagamentos, estornos e liberação de repasse feitos só com chave de API são recusados (403) — a verificação é humana.
67
72
  - **Idempotência** automática em POSTs (evita cobrança/pagamento duplicado); aceita `idempotency_key` explícito.
68
73
  - **Multi-empresa**: qualquer tool aceita `company_id` para sobrescrever a empresa por chamada.
69
74
 
package/dist/index.js CHANGED
@@ -278,7 +278,8 @@ var MANIFEST = [
278
278
  { operationId: "listFinancialNatures", tool: "finance_list_natures" },
279
279
  { operationId: "deleteFinancialMovement", tool: "finance_delete_movement", write: true, destructive: true },
280
280
  // Módulos operacionais que tinham tela e nenhuma exposição (COBERTURA.md item 1).
281
- // Somente leitura — escrever em conciliação/cartão/DDA mexe em dinheiro e entra depois.
281
+ // As escritas destes módulos (status da caixa, conciliar/desfazer, triagem do DDA, insumos,
282
+ // notificação lida) vêm primeiro; a leitura, em seguida.
282
283
  { operationId: "updateInboxMessageStatus", tool: "inbox_messages_update_status", write: true },
283
284
  { operationId: "resolveStatementEntry", tool: "reconciliation_resolve", write: true },
284
285
  { operationId: "deleteReconciliationMatch", tool: "reconciliation_unmatch", write: true, destructive: true },
@@ -560,6 +561,37 @@ var SCHEMAS = {
560
561
  notes: { type: "string" }
561
562
  }
562
563
  },
564
+ // Schemas de ATUALIZAÇÃO: o PATCH reusava o de criação, que carrega `required` — o MCP
565
+ // derivava a tool de update exigindo `customer_id` em toda edição — e não dizia o que cada
566
+ // campo faz depois que o registro existe (trocar cliente, reagendar, anexar).
567
+ ProposalUpdate: {
568
+ type: "object",
569
+ description: "S\xF3 os campos enviados mudam. Ao menos um \xE9 obrigat\xF3rio.",
570
+ properties: {
571
+ customer_id: { type: "string", format: "uuid", description: "Troca o cliente da proposta. Precisa ser cliente desta empresa (404 se n\xE3o for)." },
572
+ status: { type: "string", enum: ["rascunho", "enviada", "aceita", "recusada", "cancelada"] },
573
+ total_amount: { type: "number" },
574
+ valid_until: { type: ["string", "null"], format: "date" },
575
+ notes: { type: ["string", "null"] }
576
+ }
577
+ },
578
+ ContractUpdate: {
579
+ type: "object",
580
+ description: "S\xF3 os campos enviados mudam. Ao menos um \xE9 obrigat\xF3rio. Itens e se\xE7\xF5es do contrato n\xE3o s\xE3o edit\xE1veis por esta rota.",
581
+ properties: {
582
+ customer_id: { type: "string", format: "uuid", description: "Troca o cliente do contrato. Precisa ser cliente desta empresa (404). Recusado com 409 se o contrato tem autoriza\xE7\xE3o de d\xE9bito recorrente ativa (cart\xE3o salvo ou Pix Autom\xE1tico) \u2014 ela \xE9 do pagador atual; revogue-a antes. Faturas j\xE1 geradas continuam no cliente antigo." },
583
+ title: { type: ["string", "null"] },
584
+ status: { type: "string", enum: ["ativo", "suspenso", "cancelado", "finalizado"] },
585
+ frequency: { type: "string", enum: ["semanal", "quinzenal", "mensal", "bimestral", "trimestral", "semestral", "anual"] },
586
+ start_date: { type: "string", format: "date" },
587
+ end_date: { type: ["string", "null"], format: "date" },
588
+ due_days: { type: "integer" },
589
+ amount: { type: "number" },
590
+ payment_method_id: { type: ["string", "null"], format: "uuid" },
591
+ next_generation_date: { type: "string", format: "date", description: "Reagenda a pr\xF3xima gera\xE7\xE3o de fatura (rodada di\xE1ria das 03:00). S\xF3 hoje (fuso de Bras\xEDlia) em diante: data no passado \xE9 400, porque o gerador emitiria de uma vez uma fatura por ciclo atrasado. Para gerar um ciclo agora use POST /contracts/{id}/generate-invoices." },
592
+ notes: { type: ["string", "null"] }
593
+ }
594
+ },
563
595
  ContractReadjustment: {
564
596
  type: "object",
565
597
  description: "Reajuste aplicado a um contrato (specs/reajustes/).",
@@ -832,6 +864,27 @@ var SCHEMAS = {
832
864
  }
833
865
  }
834
866
  },
867
+ ExpenseUpdate: {
868
+ type: "object",
869
+ description: "S\xF3 os campos enviados mudam. Ao menos um \xE9 obrigat\xF3rio (`attachment_ids` sozinho vale).",
870
+ properties: {
871
+ supplier_id: { type: "string", format: "uuid", description: "Troca o fornecedor. Precisa ser fornecedor desta empresa (404 se n\xE3o for)." },
872
+ description: { type: "string" },
873
+ amount: { type: "number" },
874
+ expense_date: { type: "string", format: "date" },
875
+ payment_date: { type: ["string", "null"], format: "date" },
876
+ category_id: { type: ["string", "null"], format: "uuid" },
877
+ status: { type: "string", enum: ["pendente", "pago", "cancelado"] },
878
+ bank_account_id: { type: ["string", "null"], format: "uuid" },
879
+ payment_method_id: { type: ["string", "null"], format: "uuid" },
880
+ notes: { type: ["string", "null"] },
881
+ attachment_ids: {
882
+ type: "array",
883
+ items: { type: "string", format: "uuid" },
884
+ description: "ACRESCENTA anexos j\xE1 enviados \xE0 despesa (n\xE3o substitui os atuais). Anexo que a despesa j\xE1 tem \xE9 ignorado, ent\xE3o repetir a chamada n\xE3o duplica. Id inexistente nesta empresa \u2192 404, sem gravar nada."
885
+ }
886
+ }
887
+ },
835
888
  PurchaseInvoice: {
836
889
  type: "object",
837
890
  properties: {
@@ -950,6 +1003,7 @@ var SCHEMAS = {
950
1003
  method: { type: "string", enum: ["pix", "boleto", "checkout", "credit_card"], description: "Canal de pagamento" },
951
1004
  provider: { type: "string", enum: ["inter", "c6bank", "pix_offline", "pagarme", "cora"], description: "Opcional. Desambigua quando a empresa tem mais de um provedor no mesmo canal (ex.: Pix Inter x Pix Pagar.me x Pix Cora). Se omitido, usa o provedor ativo do canal." },
952
1005
  invoice_id: { type: "string", format: "uuid", description: "Fatura existente (opcional)" },
1006
+ charge_id: { type: "string", format: "uuid", description: "PARCELA da fatura a cobrar (invoice_charges.id \u2014 veja GET /v1/invoices/{id}/charges). S\xF3 vale com invoice_id. Quando informado, a cobran\xE7a sai com o VALOR e o VENCIMENTO da parcela e fica amarrada a ela, que \xE9 o que d\xE1 baixa certa quando o dinheiro entra. Omitido, a cobran\xE7a \xE9 no n\xEDvel da fatura (valor cheio) \u2014 numa fatura parcelada isso normalmente n\xE3o \xE9 o que se quer." },
953
1007
  customer_id: { type: "string", format: "uuid", description: "Obrigat\xF3rio se invoice_id omitido" },
954
1008
  amount: { type: "number", description: "Obrigat\xF3rio se invoice_id omitido" },
955
1009
  due_date: { type: "string", format: "date", description: "Obrigat\xF3rio se invoice_id omitido" },
@@ -972,7 +1026,7 @@ var SCHEMAS = {
972
1026
  type: "object",
973
1027
  required: ["url"],
974
1028
  properties: {
975
- name: { type: "string", description: "R\xF3tulo opcional" },
1029
+ name: { type: ["string", "null"], description: "R\xF3tulo opcional. No PUT /webhooks/payments, omitido preserva o r\xF3tulo atual; null apaga." },
976
1030
  url: { type: "string", format: "uri", description: "Deve come\xE7ar com https://" },
977
1031
  events: { type: "array", items: { type: "string", enum: WEBHOOK_EVENT_KEYS }, description: "Eventos assinados (default: charge.paid, charge.cancelled, charge.expired)" },
978
1032
  active: { type: "boolean", default: true }
@@ -1227,6 +1281,19 @@ var SCHEMAS = {
1227
1281
  account_type: { type: ["string", "null"] },
1228
1282
  is_primary: { type: "boolean" },
1229
1283
  active: { type: "boolean" },
1284
+ opening_balance: { type: ["number", "null"], description: "Saldo de fechamento conhecido no dia opening_balance_date. \xC2ncora do saldo calculado." },
1285
+ opening_balance_date: { type: ["string", "null"], format: "date", description: "Data do saldo informado em opening_balance." },
1286
+ saldo_calculado: {
1287
+ type: ["object", "null"],
1288
+ description: "S\xF3 no detalhe (GET /v1/bank-accounts/{id}). Saldo da \xE2ncora somado ao extrato importado a partir do dia seguinte. \xC9 nulo quando a conta n\xE3o tem \xE2ncora \u2014 sem ela n\xE3o existe saldo, e a API n\xE3o devolve um n\xFAmero que seria mentira. Serve aos bancos que n\xE3o publicam saldo (o C6 n\xE3o exp\xF5e saldo em nenhuma das suas APIs).",
1289
+ properties: {
1290
+ saldo: { type: "number" },
1291
+ base: { type: "number" },
1292
+ base_date: { type: "string", format: "date" },
1293
+ qtd_lancamentos: { type: "integer" },
1294
+ ultimo_lancamento: { type: ["string", "null"], format: "date" }
1295
+ }
1296
+ },
1230
1297
  created_at: { type: "string", format: "date-time" },
1231
1298
  updated_at: { type: "string", format: "date-time" }
1232
1299
  }
@@ -1265,8 +1332,7 @@ var SCHEMAS = {
1265
1332
  pix_key_type: { type: "string", enum: ["cpf", "cnpj", "email", "phone", "random"] },
1266
1333
  pix_copia_e_cola: { type: "string", description: "QR Pix copia e cola (EMV)" },
1267
1334
  boleto_barcode: { type: "string" },
1268
- scheduled_for: { type: "string", format: "date", description: "Data de agendamento (YYYY-MM-DD); omitir paga \xE0 vista" },
1269
- description: { type: "string" }
1335
+ scheduled_for: { type: "string", format: "date", description: "Data de agendamento (YYYY-MM-DD); omitir paga \xE0 vista" }
1270
1336
  }
1271
1337
  },
1272
1338
  SplitRuleRecipient: {
@@ -1710,6 +1776,11 @@ var COMMON_ERRORS = {
1710
1776
  "429": errorResponse("Rate limit excedido (60 req/min por padr\xE3o)"),
1711
1777
  "500": errorResponse("Erro interno")
1712
1778
  };
1779
+ var STEP_UP_NOTE = " 2FA: se a empresa exige verifica\xE7\xE3o em duas etapas para movimentar dinheiro (Configura\xE7\xF5es \u2192 Seguran\xE7a), uma chave de API sem usu\xE1rio recebe 403; pelo chat ou por OAuth \xE9 preciso enviar o cabe\xE7alho X-Payment-Step-Up-Grant, emitido pela verifica\xE7\xE3o 2FA no app.";
1780
+ var STEP_UP_ERRORS = {
1781
+ ...COMMON_ERRORS,
1782
+ "403": errorResponse("Scope insuficiente, ou a empresa exige 2FA para movimentar dinheiro (ver descri\xE7\xE3o)")
1783
+ };
1713
1784
  var OPENAPI_SPEC = {
1714
1785
  openapi: "3.1.0",
1715
1786
  info: {
@@ -1840,7 +1911,8 @@ var OPENAPI_SPEC = {
1840
1911
  parameters: [
1841
1912
  ...PAGINATION_PARAMS,
1842
1913
  { name: "search", in: "query", schema: { type: "string" }, description: "Busca por nome, e-mail ou documento" },
1843
- { name: "status", in: "query", schema: { type: "string" }, description: "Filtrar por status" }
1914
+ { name: "status", in: "query", schema: { type: "string" }, description: "Filtrar por status" },
1915
+ { name: "type", in: "query", schema: { type: "string", enum: ["fisica", "juridica", "estrangeira"] }, description: "Filtrar por tipo de pessoa" }
1844
1916
  ],
1845
1917
  responses: {
1846
1918
  "200": paginatedResponse("#/components/schemas/Customer"),
@@ -2095,8 +2167,8 @@ var OPENAPI_SPEC = {
2095
2167
  summary: "Atualizar proposta",
2096
2168
  operationId: "updateProposal",
2097
2169
  security: [{ ApiKeyAuth: ["proposals:write"] }],
2098
- requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ProposalCreate" } } } },
2099
- responses: { "200": { description: "Proposta atualizada", content: { "application/json": { schema: { $ref: "#/components/schemas/Proposal" } } } }, "404": errorResponse("Proposta n\xE3o encontrada"), ...COMMON_ERRORS }
2170
+ requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ProposalUpdate" } } } },
2171
+ responses: { "200": { description: "Proposta atualizada", content: { "application/json": { schema: { $ref: "#/components/schemas/Proposal" } } } }, "400": errorResponse("Dados inv\xE1lidos ou nenhum campo para atualizar"), "404": errorResponse("Proposta ou cliente n\xE3o encontrado"), ...COMMON_ERRORS }
2100
2172
  },
2101
2173
  delete: {
2102
2174
  tags: ["Propostas"],
@@ -2165,8 +2237,8 @@ var OPENAPI_SPEC = {
2165
2237
  summary: "Atualizar contrato",
2166
2238
  operationId: "updateContract",
2167
2239
  security: [{ ApiKeyAuth: ["contracts:write"] }],
2168
- requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ContractCreate" } } } },
2169
- responses: { "200": { description: "Contrato atualizado", content: { "application/json": { schema: { $ref: "#/components/schemas/Contract" } } } }, "404": errorResponse("Contrato n\xE3o encontrado"), ...COMMON_ERRORS }
2240
+ requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ContractUpdate" } } } },
2241
+ responses: { "200": { description: "Contrato atualizado", content: { "application/json": { schema: { $ref: "#/components/schemas/Contract" } } } }, "400": errorResponse("Dados inv\xE1lidos ou nenhum campo para atualizar"), "404": errorResponse("Contrato ou cliente n\xE3o encontrado"), "409": errorResponse("Troca de cliente com autoriza\xE7\xE3o de d\xE9bito recorrente ativa"), ...COMMON_ERRORS }
2170
2242
  },
2171
2243
  delete: {
2172
2244
  tags: ["Contratos"],
@@ -2684,7 +2756,7 @@ var OPENAPI_SPEC = {
2684
2756
  summary: "Listar naturezas financeiras",
2685
2757
  operationId: "listFinancialNatures",
2686
2758
  description: "IDs usados em POST /v1/finance/movements (nature_id).",
2687
- security: [{ ApiKeyAuth: ["finance:read", "finance:write"] }],
2759
+ security: [{ ApiKeyAuth: ["finance:read"] }, { ApiKeyAuth: ["finance:write"] }],
2688
2760
  parameters: [...PAGINATION_PARAMS, { name: "is_active", in: "query", schema: { type: "string", enum: ["true", "false"] } }, { name: "direction", in: "query", schema: { type: "string", enum: ["credit", "debit", "both"] } }],
2689
2761
  responses: { "200": paginatedResponse("#/components/schemas/FinancialNature"), ...COMMON_ERRORS }
2690
2762
  }
@@ -2695,7 +2767,7 @@ var OPENAPI_SPEC = {
2695
2767
  summary: "Listar centros de custo",
2696
2768
  operationId: "listCostCenters",
2697
2769
  description: "IDs usados em despesas (category_id).",
2698
- security: [{ ApiKeyAuth: ["expenses:read", "expenses:write", "finance:read"] }],
2770
+ security: [{ ApiKeyAuth: ["expenses:read"] }, { ApiKeyAuth: ["expenses:write"] }, { ApiKeyAuth: ["finance:read"] }],
2699
2771
  parameters: [...PAGINATION_PARAMS, { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } }],
2700
2772
  responses: { "200": paginatedResponse("#/components/schemas/CostCenter"), ...COMMON_ERRORS }
2701
2773
  },
@@ -2761,7 +2833,9 @@ var OPENAPI_SPEC = {
2761
2833
  body: { type: "string" },
2762
2834
  template_key: { type: "string", description: "Obrigat\xF3rio para kind=digest." },
2763
2835
  remind_in_minutes: { type: "integer", description: "Atalho RELATIVO: minutos a partir de agora (servidor calcula). Ex.: 'daqui 30min' \u2192 30. Preferir para lembretes relativos." },
2836
+ remind_in_hours: { type: "number", description: "Atalho RELATIVO em horas (somado a remind_in_minutes, se vier junto)." },
2764
2837
  remind_at: { type: "string", description: "Atalho ABSOLUTO: instante ISO (use 'Z' para UTC). Vira recurrence once + start_date + run_time no fuso." },
2838
+ due_date: { type: "string", format: "date", description: "Atalho S\xD3-DATA (YYYY-MM-DD): lembrete pontual nesse dia." },
2765
2839
  params: { type: "object" },
2766
2840
  audience: { type: "array", items: { type: "string", enum: ["admin", "operador", "visualizador"] } },
2767
2841
  channels: { type: "object", properties: { in_app: { type: "boolean" }, email: { type: "boolean" }, push: { type: "boolean" } } },
@@ -2784,6 +2858,8 @@ var OPENAPI_SPEC = {
2784
2858
  operationId: "updateReminder",
2785
2859
  security: [{ ApiKeyAuth: ["reminders:update"] }],
2786
2860
  requestBody: { required: true, content: { "application/json": { schema: { type: "object", properties: {
2861
+ kind: { type: "string", enum: ["manual", "digest"] },
2862
+ template_key: { type: "string" },
2787
2863
  title: { type: "string" },
2788
2864
  body: { type: "string" },
2789
2865
  params: { type: "object" },
@@ -2813,7 +2889,7 @@ var OPENAPI_SPEC = {
2813
2889
  tags: ["Cat\xE1logos"],
2814
2890
  summary: "Listar condi\xE7\xF5es de pagamento",
2815
2891
  operationId: "listPaymentConditions",
2816
- security: [{ ApiKeyAuth: ["invoices:read", "contracts:read"] }],
2892
+ security: [{ ApiKeyAuth: ["invoices:read"] }, { ApiKeyAuth: ["contracts:read"] }, { ApiKeyAuth: ["invoices:create"] }, { ApiKeyAuth: ["contracts:write"] }],
2817
2893
  parameters: [...PAGINATION_PARAMS, { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } }],
2818
2894
  responses: { "200": paginatedResponse("#/components/schemas/PaymentCondition"), ...COMMON_ERRORS }
2819
2895
  }
@@ -2823,7 +2899,7 @@ var OPENAPI_SPEC = {
2823
2899
  tags: ["Cat\xE1logos"],
2824
2900
  summary: "Listar unidades de servi\xE7o",
2825
2901
  operationId: "listServiceUnits",
2826
- security: [{ ApiKeyAuth: ["services:read", "services:write"] }],
2902
+ security: [{ ApiKeyAuth: ["services:read"] }, { ApiKeyAuth: ["services:write"] }],
2827
2903
  parameters: [...PAGINATION_PARAMS],
2828
2904
  responses: { "200": paginatedResponse("#/components/schemas/ServiceUnit"), ...COMMON_ERRORS }
2829
2905
  }
@@ -2915,6 +2991,7 @@ var OPENAPI_SPEC = {
2915
2991
  }
2916
2992
  } } }
2917
2993
  },
2994
+ "402": { description: "Saldo insuficiente para a leitura visual por IA (o texto do arquivo n\xE3o bastou). `code`: saldo_insuficiente | limite_de_gasto_atingido | carteira_inativa" },
2918
2995
  "404": { description: "Documento n\xE3o encontrado" }
2919
2996
  }
2920
2997
  }
@@ -2997,7 +3074,7 @@ var OPENAPI_SPEC = {
2997
3074
  tags: ["Relat\xF3rios"],
2998
3075
  summary: "Aging de inadimpl\xEAncia com a\xE7\xF5es sugeridas",
2999
3076
  operationId: "reportAgingActions",
3000
- security: [{ ApiKeyAuth: ["invoices:read", "finance:read"] }],
3077
+ security: [{ ApiKeyAuth: ["invoices:read"] }, { ApiKeyAuth: ["finance:read"] }],
3001
3078
  parameters: [
3002
3079
  { name: "limit", in: "query", schema: { type: "integer", minimum: 1, maximum: 40, default: 12 } },
3003
3080
  { name: "min_overdue_days", in: "query", schema: { type: "integer", minimum: 1, maximum: 365, default: 1 } },
@@ -3075,7 +3152,7 @@ var OPENAPI_SPEC = {
3075
3152
  description: "Emite uma NFS-e a partir de uma fatura. O m\xE9todo (certificado/portal) vem da configura\xE7\xE3o da empresa. Pode levar alguns segundos.\n\n**Os itens da fatura N\xC3O precisam de `service_id`** \u2014 item avulso emite normalmente; a classifica\xE7\xE3o fiscal (cTribNac, cNBS, al\xEDquotas) vem da configura\xE7\xE3o fiscal da empresa e do CNAE padr\xE3o, n\xE3o do item.\n\nC\xF3digos: **201** = autorizada ou em transmiss\xE3o \u2014 o `id` devolvido \xE9 o mesmo `{id}` de `/v1/nfse/{id}`, `/files`, `/sync` e `/cancel`. **422 com `status: 'rejeitada'`** = o fisco REJEITOU (motivo em `message`) \u2014 n\xE3o existe nota, n\xE3o afirme ao usu\xE1rio que foi emitida. **422 sem `status`** = a EMPRESA n\xE3o est\xE1 configurada para emitir. **409** = esta fatura j\xE1 tem nota (o `error` traz o id da existente). **424** = o provedor fiscal falhou; o motivo dele vem em `error`.\n\nRetentativa \xE9 segura: mande o header `Idempotency-Key` (a mesma resposta volta, com `Idempotent-Replayed: true`), e mesmo sem ele o 409 impede uma segunda nota para a mesma fatura.",
3076
3153
  security: [{ ApiKeyAuth: ["nfse:emitir"] }],
3077
3154
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/NfseEmit" } } } },
3078
- responses: { "201": { description: "Emiss\xE3o solicitada", content: { "application/json": { schema: { type: "object", properties: { id: { type: ["string", "null"], description: "Id da NFS-e \u2014 use em /v1/nfse/{id}, /files, /sync e /cancel. Mesmo valor de history_id." }, invoice_id: { type: "string" }, status: { type: "string", description: "autorizada | transmitindo | rejeitada" }, numero_nfse: { type: ["string", "null"] }, chave_acesso: { type: ["string", "null"] }, history_id: { type: ["string", "null"], description: "Alias de `id`, mantido por compatibilidade." }, message: { type: ["string", "null"] } } } } } }, "400": errorResponse("invoice_id ausente"), "404": errorResponse("Fatura n\xE3o encontrada"), "409": errorResponse("A fatura j\xE1 tem NFS-e autorizada ou em transmiss\xE3o \u2014 o `error` traz o id da existente"), "422": errorResponse('Rejeitada pelo fisco (corpo traz `status: "rejeitada"` e `message`) OU empresa sem NFS-e configurada (corpo traz s\xF3 `error`)'), "424": errorResponse("O provedor de NFS-e falhou \u2014 o motivo dele vem em `error`"), ...COMMON_ERRORS }
3155
+ responses: { "201": { description: "Emiss\xE3o solicitada", content: { "application/json": { schema: { type: "object", properties: { id: { type: ["string", "null"], description: "Id da NFS-e \u2014 use em /v1/nfse/{id}, /files, /sync e /cancel. Mesmo valor de history_id." }, invoice_id: { type: "string" }, status: { type: "string", description: "autorizada | transmitindo | rejeitada" }, numero_nfse: { type: ["string", "null"] }, chave_acesso: { type: ["string", "null"] }, history_id: { type: ["string", "null"], description: "Alias de `id`, mantido por compatibilidade." }, message: { type: ["string", "null"] } } } } } }, "400": errorResponse("invoice_id ausente"), "404": errorResponse("Fatura n\xE3o encontrada"), "409": errorResponse("A fatura j\xE1 tem NFS-e autorizada ou em transmiss\xE3o \u2014 o `error` traz o id da existente"), "402": errorResponse("Saldo insuficiente na carteira pr\xE9-paga (ou limite de gasto atingido) \u2014 nada foi transmitido. `code`: saldo_insuficiente | limite_de_gasto_atingido | carteira_inativa; recarregue em Cobran\xE7a da plataforma"), "422": errorResponse('Rejeitada pelo fisco (corpo traz `status: "rejeitada"` e `message`) OU empresa sem NFS-e configurada (corpo traz s\xF3 `error`)'), "424": errorResponse("O provedor de NFS-e falhou \u2014 o motivo dele vem em `error`"), ...COMMON_ERRORS }
3079
3156
  }
3080
3157
  },
3081
3158
  "/nfse/{id}/cancel": {
@@ -3273,8 +3350,8 @@ var OPENAPI_SPEC = {
3273
3350
  summary: "Atualizar despesa",
3274
3351
  operationId: "updateExpense",
3275
3352
  security: [{ ApiKeyAuth: ["expenses:write"] }],
3276
- requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ExpenseCreate" } } } },
3277
- responses: { "200": { description: "Despesa atualizada", content: { "application/json": { schema: { $ref: "#/components/schemas/Expense" } } } }, "404": errorResponse("Despesa n\xE3o encontrada"), ...COMMON_ERRORS }
3353
+ requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ExpenseUpdate" } } } },
3354
+ responses: { "200": { description: "Despesa atualizada", content: { "application/json": { schema: { $ref: "#/components/schemas/Expense" } } } }, "400": errorResponse("Dados inv\xE1lidos ou nenhum campo para atualizar"), "404": errorResponse("Despesa, fornecedor ou anexo n\xE3o encontrado"), ...COMMON_ERRORS }
3278
3355
  },
3279
3356
  delete: {
3280
3357
  tags: ["Despesas"],
@@ -3368,7 +3445,7 @@ var OPENAPI_SPEC = {
3368
3445
  tags: ["Cobran\xE7as"],
3369
3446
  summary: "Criar cobran\xE7a (Pix, boleto, checkout ou cart\xE3o)",
3370
3447
  operationId: "createCharge",
3371
- description: "Gera uma cobran\xE7a no provider ativo da empresa (Inter, C6 Bank, Pix Offline ou Pagar.me). Forne\xE7a invoice_id ou customer_id+amount+due_date. Com Pagar.me, method=pix retorna o copia-e-cola e method=credit_card retorna 'checkout.url' (link da p\xE1gina de pagamento pr\xF3pria).",
3448
+ description: "Gera uma cobran\xE7a no provider ativo da empresa (Inter, C6 Bank, Pix Offline, Cora ou Pagar.me). Forne\xE7a invoice_id ou customer_id+amount+due_date. Com Pagar.me, method=pix retorna o copia-e-cola e method=credit_card retorna 'checkout.url' (link da p\xE1gina de pagamento pr\xF3pria).\n\nNuma fatura PARCELADA, informe `charge_id`: sem ele a cobran\xE7a sai no valor cheio da fatura e n\xE3o fica amarrada a nenhuma parcela \u2014 ent\xE3o a baixa n\xE3o fecha a parcela certa. Use GET /v1/invoices/{id}/charges para descobrir o charge_id.",
3372
3449
  security: [{ ApiKeyAuth: ["charges:create"] }],
3373
3450
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ChargeCreate" } } } },
3374
3451
  responses: {
@@ -3403,14 +3480,14 @@ var OPENAPI_SPEC = {
3403
3480
  tags: ["Cobran\xE7as"],
3404
3481
  summary: "Estornar cobran\xE7a (devolu\xE7\xE3o Pix)",
3405
3482
  operationId: "refundCharge",
3406
- description: "Estorna (devolve) uma cobran\xE7a Pix paga. Dispon\xEDvel apenas para Pix \u2014 boleto e checkout retornam 422. Requer que o endToEndId do pagamento tenha sido capturado.",
3483
+ description: "Estorna (devolve) uma cobran\xE7a Pix paga. Dispon\xEDvel apenas para Pix \u2014 boleto e checkout retornam 422. Requer que o endToEndId do pagamento tenha sido capturado." + STEP_UP_NOTE,
3407
3484
  security: [{ ApiKeyAuth: ["charges:refund"] }],
3408
3485
  responses: {
3409
3486
  "200": { description: "Devolu\xE7\xE3o solicitada", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, status: { type: "string" }, provider: { type: "string" }, amount: { type: "number" }, message: { type: "string" } } } } } },
3410
3487
  "404": errorResponse("Cobran\xE7a n\xE3o encontrada"),
3411
3488
  "409": errorResponse("Cobran\xE7a n\xE3o est\xE1 paga ou j\xE1 estornada"),
3412
3489
  "422": errorResponse("M\xE9todo n\xE3o suportado (apenas Pix) ou endToEndId indispon\xEDvel"),
3413
- ...COMMON_ERRORS
3490
+ ...STEP_UP_ERRORS
3414
3491
  }
3415
3492
  }
3416
3493
  },
@@ -4000,7 +4077,7 @@ var OPENAPI_SPEC = {
4000
4077
  tags: ["Pagamentos a Fornecedor"],
4001
4078
  summary: "Pagar ou agendar pagamento (Pix/boleto)",
4002
4079
  operationId: "createPayout",
4003
- description: "Executa ou agenda um pagamento a fornecedor no provider ativo (Inter/C6). Informe o alvo via purchase_invoice_charge_id, supplier_payment_method_id, pix_key/pix_copia_e_cola ou boleto_barcode.",
4080
+ description: "Executa ou agenda um pagamento a fornecedor no provider ativo (Inter/C6). Informe o alvo via purchase_invoice_charge_id, supplier_payment_method_id, pix_key/pix_copia_e_cola ou boleto_barcode." + STEP_UP_NOTE,
4004
4081
  security: [{ ApiKeyAuth: ["payouts:create"] }],
4005
4082
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/PayoutCreate" } } } },
4006
4083
  responses: {
@@ -4009,7 +4086,7 @@ var OPENAPI_SPEC = {
4009
4086
  "404": errorResponse("Conta banc\xE1ria, parcela ou fornecedor n\xE3o encontrado"),
4010
4087
  "422": errorResponse("Integra\xE7\xE3o n\xE3o configurada ou provider amb\xEDguo"),
4011
4088
  "424": errorResponse("Erro retornado pelo banco"),
4012
- ...COMMON_ERRORS
4089
+ ...STEP_UP_ERRORS
4013
4090
  }
4014
4091
  }
4015
4092
  },
@@ -4029,9 +4106,9 @@ var OPENAPI_SPEC = {
4029
4106
  tags: ["Pagamentos a Fornecedor"],
4030
4107
  summary: "Cancelar pagamento agendado",
4031
4108
  operationId: "cancelPayout",
4032
- description: "Cancela um pagamento agendado. Pix agendado no Inter n\xE3o \xE9 cancel\xE1vel pela API (retorna 422 \u2014 cancele no Internet Banking).",
4109
+ description: "Cancela um pagamento agendado. Pix agendado no Inter n\xE3o \xE9 cancel\xE1vel pela API (retorna 422 \u2014 cancele no Internet Banking)." + STEP_UP_NOTE,
4033
4110
  security: [{ ApiKeyAuth: ["payouts:cancel"] }],
4034
- responses: { "200": { description: "Cancelado", content: { "application/json": { schema: { $ref: "#/components/schemas/Payout" } } } }, "404": errorResponse("Pagamento n\xE3o encontrado"), "409": errorResponse("N\xE3o pode ser cancelado no estado atual"), "422": errorResponse("Pix Inter \u2014 cancele no Internet Banking"), ...COMMON_ERRORS }
4111
+ responses: { "200": { description: "Cancelado", content: { "application/json": { schema: { $ref: "#/components/schemas/Payout" } } } }, "404": errorResponse("Pagamento n\xE3o encontrado"), "409": errorResponse("N\xE3o pode ser cancelado no estado atual"), "422": errorResponse("Pix Inter \u2014 cancele no Internet Banking"), ...STEP_UP_ERRORS }
4035
4112
  }
4036
4113
  },
4037
4114
  "/payouts/{id}/sync": {
@@ -4126,9 +4203,9 @@ var OPENAPI_SPEC = {
4126
4203
  tags: ["Split de Pagamentos"],
4127
4204
  summary: "Estornar execu\xE7\xE3o de split",
4128
4205
  operationId: "reverseSplitExecution",
4129
- description: "Marca a execu\xE7\xE3o e suas fatias como 'reversed'. Para cada fatia de fornecedor j\xE1 paga, registra um ajuste de recupera\xE7\xE3o (o fornecedor deve devolver o valor).",
4206
+ description: "Marca a execu\xE7\xE3o e suas fatias como 'reversed'. Para cada fatia de fornecedor j\xE1 paga, registra um ajuste de recupera\xE7\xE3o (o fornecedor deve devolver o valor)." + STEP_UP_NOTE,
4130
4207
  security: [{ ApiKeyAuth: ["split:update"] }],
4131
- responses: { "200": { description: "Estornada", content: { "application/json": { schema: { type: "object", properties: { execution_id: { type: "string" }, status: { type: "string" }, adjustments_created: { type: "integer" }, recover_amount_cents: { type: "integer" } } } } } }, "404": errorResponse("Execu\xE7\xE3o n\xE3o encontrada"), "409": errorResponse("J\xE1 estornada"), ...COMMON_ERRORS }
4208
+ responses: { "200": { description: "Estornada", content: { "application/json": { schema: { type: "object", properties: { execution_id: { type: "string" }, status: { type: "string" }, adjustments_created: { type: "integer" }, recover_amount_cents: { type: "integer" } } } } } }, "404": errorResponse("Execu\xE7\xE3o n\xE3o encontrada"), "409": errorResponse("J\xE1 estornada"), ...STEP_UP_ERRORS }
4132
4209
  }
4133
4210
  },
4134
4211
  "/split-items/{id}/release": {
@@ -4137,9 +4214,9 @@ var OPENAPI_SPEC = {
4137
4214
  tags: ["Split de Pagamentos"],
4138
4215
  summary: "Liberar fatia manualmente",
4139
4216
  operationId: "releaseSplitItem",
4140
- description: "Libera uma fatia (pending/awaiting_nota/failed \u2192 released), apta a virar payout.",
4217
+ description: "Libera uma fatia (pending/awaiting_nota/failed \u2192 released), apta a virar payout." + STEP_UP_NOTE,
4141
4218
  security: [{ ApiKeyAuth: ["split:update"] }],
4142
- responses: { "200": { description: "Liberada", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, status: { type: "string" } } } } } }, "404": errorResponse("Fatia n\xE3o encontrada"), ...COMMON_ERRORS }
4219
+ responses: { "200": { description: "Liberada", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, status: { type: "string" } } } } } }, "404": errorResponse("Fatia n\xE3o encontrada"), ...STEP_UP_ERRORS }
4143
4220
  }
4144
4221
  },
4145
4222
  // -----------------------------------------------------------------------
@@ -4210,7 +4287,7 @@ var OPENAPI_SPEC = {
4210
4287
  summary: "Listar m\xE9todos de pagamento a fornecedor (AP)",
4211
4288
  operationId: "listPaymentMethodsAp",
4212
4289
  description: "Formas de pagamento usadas em payouts (contas a pagar).",
4213
- security: [{ ApiKeyAuth: ["payouts:read"] }],
4290
+ security: [{ ApiKeyAuth: ["payouts:read"] }, { ApiKeyAuth: ["payouts:create"] }],
4214
4291
  parameters: [
4215
4292
  ...PAGINATION_PARAMS,
4216
4293
  { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } },
@@ -4475,12 +4552,17 @@ function resolveRef(ref) {
4475
4552
  if (!schema) throw new Error(`Schema n\xE3o encontrado em components: ${name}`);
4476
4553
  return schema;
4477
4554
  }
4478
- function extractScopes(operation) {
4555
+ function extractScopeAlternatives(operation) {
4479
4556
  const sec = operation.security;
4480
- if (!Array.isArray(sec) || sec.length === 0) return [];
4481
- const first = sec[0];
4482
- const scopes = first?.ApiKeyAuth;
4483
- return Array.isArray(scopes) ? scopes.filter(Boolean) : [];
4557
+ if (!Array.isArray(sec)) return [];
4558
+ return sec.map((alt) => Array.isArray(alt?.ApiKeyAuth) ? alt.ApiKeyAuth.filter(Boolean) : []).filter((alt) => alt.length > 0);
4559
+ }
4560
+ function temScopesPara(desc, held) {
4561
+ if (desc.scopeAlternatives.length === 0) return true;
4562
+ return desc.scopeAlternatives.some((alt) => alt.every((s) => held.has(s)));
4563
+ }
4564
+ function descreverScopes(desc) {
4565
+ return desc.scopeAlternatives.map((alt) => alt.join(" + ")).join(" ou ");
4484
4566
  }
4485
4567
  function describeOperation(operationId) {
4486
4568
  const idx = indexByOperationId();
@@ -4544,7 +4626,8 @@ function describeOperation(operationId) {
4544
4626
  pathParams,
4545
4627
  queryParams,
4546
4628
  hasBody,
4547
- scopes: extractScopes(operation),
4629
+ scopes: [...new Set(extractScopeAlternatives(operation).flat())],
4630
+ scopeAlternatives: extractScopeAlternatives(operation),
4548
4631
  inputSchema,
4549
4632
  summary: operation.summary,
4550
4633
  description: operation.description
@@ -4657,16 +4740,15 @@ function buildCuratedTools(api, heldScopes) {
4657
4740
  `);
4658
4741
  continue;
4659
4742
  }
4660
- const missing = desc.scopes.filter((s) => !heldScopes.has(s));
4661
- if (missing.length > 0) {
4662
- skipped.push({ tool: entry.tool, missingScopes: missing });
4743
+ if (!temScopesPara(desc, heldScopes)) {
4744
+ skipped.push({ tool: entry.tool, missingScopes: desc.scopes.filter((s) => !heldScopes.has(s)) });
4663
4745
  continue;
4664
4746
  }
4665
4747
  const inputSchema = augmentInputSchema(desc.inputSchema, {
4666
4748
  write: entry.write,
4667
4749
  destructive: entry.destructive
4668
4750
  });
4669
- const scopeNote = desc.scopes.length ? ` Scopes: ${desc.scopes.join(", ")}.` : "";
4751
+ const scopeNote = desc.scopes.length ? ` Scopes: ${descreverScopes(desc)}.` : "";
4670
4752
  const prefix = entry.destructive ? "[DESTRUTIVA] " : "";
4671
4753
  const description = `${prefix}${desc.summary ?? entry.operationId}.${scopeNote}`;
4672
4754
  tools.push({
@@ -4865,7 +4947,7 @@ function buildWhoamiTool(api) {
4865
4947
  // src/branding.ts
4866
4948
  var MCP_SERVER_NAME = "comando-one";
4867
4949
  var MCP_SERVER_TITLE = "Comando1";
4868
- var MCP_SERVER_VERSION = "0.5.0";
4950
+ var MCP_SERVER_VERSION = "0.12.1";
4869
4951
  var MCP_SERVER_DESCRIPTION = "ERP das empresas de servi\xE7o brasileiras: clientes, propostas, contratos, faturas, cobran\xE7as Pix e boleto, NFS-e, contas a pagar e financeiro.";
4870
4952
  var MCP_SERVER_WEBSITE = "https://comando.one";
4871
4953
  var MCP_SERVER_ICONS = [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@comando.one/mcp-server",
3
- "version": "0.11.1",
3
+ "version": "0.12.1",
4
4
  "description": "Servidor MCP (Model Context Protocol) para a API pública do Comando1 — opere seu ERP por linguagem natural.",
5
5
  "author": "Orbital Tecnologia e Desenvolvimento LTDA <contato@comando.one> (https://orbitaldev.com.br)",
6
6
  "homepage": "https://comando.one",