@comando.one/mcp-server 0.11.1 → 0.12.0

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 +62 -31
  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 },
@@ -950,6 +951,7 @@ var SCHEMAS = {
950
951
  method: { type: "string", enum: ["pix", "boleto", "checkout", "credit_card"], description: "Canal de pagamento" },
951
952
  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
953
  invoice_id: { type: "string", format: "uuid", description: "Fatura existente (opcional)" },
954
+ 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
955
  customer_id: { type: "string", format: "uuid", description: "Obrigat\xF3rio se invoice_id omitido" },
954
956
  amount: { type: "number", description: "Obrigat\xF3rio se invoice_id omitido" },
955
957
  due_date: { type: "string", format: "date", description: "Obrigat\xF3rio se invoice_id omitido" },
@@ -1227,6 +1229,19 @@ var SCHEMAS = {
1227
1229
  account_type: { type: ["string", "null"] },
1228
1230
  is_primary: { type: "boolean" },
1229
1231
  active: { type: "boolean" },
1232
+ opening_balance: { type: ["number", "null"], description: "Saldo de fechamento conhecido no dia opening_balance_date. \xC2ncora do saldo calculado." },
1233
+ opening_balance_date: { type: ["string", "null"], format: "date", description: "Data do saldo informado em opening_balance." },
1234
+ saldo_calculado: {
1235
+ type: ["object", "null"],
1236
+ 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).",
1237
+ properties: {
1238
+ saldo: { type: "number" },
1239
+ base: { type: "number" },
1240
+ base_date: { type: "string", format: "date" },
1241
+ qtd_lancamentos: { type: "integer" },
1242
+ ultimo_lancamento: { type: ["string", "null"], format: "date" }
1243
+ }
1244
+ },
1230
1245
  created_at: { type: "string", format: "date-time" },
1231
1246
  updated_at: { type: "string", format: "date-time" }
1232
1247
  }
@@ -1710,6 +1725,11 @@ var COMMON_ERRORS = {
1710
1725
  "429": errorResponse("Rate limit excedido (60 req/min por padr\xE3o)"),
1711
1726
  "500": errorResponse("Erro interno")
1712
1727
  };
1728
+ 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.";
1729
+ var STEP_UP_ERRORS = {
1730
+ ...COMMON_ERRORS,
1731
+ "403": errorResponse("Scope insuficiente, ou a empresa exige 2FA para movimentar dinheiro (ver descri\xE7\xE3o)")
1732
+ };
1713
1733
  var OPENAPI_SPEC = {
1714
1734
  openapi: "3.1.0",
1715
1735
  info: {
@@ -1840,7 +1860,8 @@ var OPENAPI_SPEC = {
1840
1860
  parameters: [
1841
1861
  ...PAGINATION_PARAMS,
1842
1862
  { 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" }
1863
+ { name: "status", in: "query", schema: { type: "string" }, description: "Filtrar por status" },
1864
+ { name: "type", in: "query", schema: { type: "string", enum: ["fisica", "juridica", "estrangeira"] }, description: "Filtrar por tipo de pessoa" }
1844
1865
  ],
1845
1866
  responses: {
1846
1867
  "200": paginatedResponse("#/components/schemas/Customer"),
@@ -2684,7 +2705,7 @@ var OPENAPI_SPEC = {
2684
2705
  summary: "Listar naturezas financeiras",
2685
2706
  operationId: "listFinancialNatures",
2686
2707
  description: "IDs usados em POST /v1/finance/movements (nature_id).",
2687
- security: [{ ApiKeyAuth: ["finance:read", "finance:write"] }],
2708
+ security: [{ ApiKeyAuth: ["finance:read"] }, { ApiKeyAuth: ["finance:write"] }],
2688
2709
  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
2710
  responses: { "200": paginatedResponse("#/components/schemas/FinancialNature"), ...COMMON_ERRORS }
2690
2711
  }
@@ -2695,7 +2716,7 @@ var OPENAPI_SPEC = {
2695
2716
  summary: "Listar centros de custo",
2696
2717
  operationId: "listCostCenters",
2697
2718
  description: "IDs usados em despesas (category_id).",
2698
- security: [{ ApiKeyAuth: ["expenses:read", "expenses:write", "finance:read"] }],
2719
+ security: [{ ApiKeyAuth: ["expenses:read"] }, { ApiKeyAuth: ["expenses:write"] }, { ApiKeyAuth: ["finance:read"] }],
2699
2720
  parameters: [...PAGINATION_PARAMS, { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } }],
2700
2721
  responses: { "200": paginatedResponse("#/components/schemas/CostCenter"), ...COMMON_ERRORS }
2701
2722
  },
@@ -2761,7 +2782,9 @@ var OPENAPI_SPEC = {
2761
2782
  body: { type: "string" },
2762
2783
  template_key: { type: "string", description: "Obrigat\xF3rio para kind=digest." },
2763
2784
  remind_in_minutes: { type: "integer", description: "Atalho RELATIVO: minutos a partir de agora (servidor calcula). Ex.: 'daqui 30min' \u2192 30. Preferir para lembretes relativos." },
2785
+ remind_in_hours: { type: "number", description: "Atalho RELATIVO em horas (somado a remind_in_minutes, se vier junto)." },
2764
2786
  remind_at: { type: "string", description: "Atalho ABSOLUTO: instante ISO (use 'Z' para UTC). Vira recurrence once + start_date + run_time no fuso." },
2787
+ due_date: { type: "string", format: "date", description: "Atalho S\xD3-DATA (YYYY-MM-DD): lembrete pontual nesse dia." },
2765
2788
  params: { type: "object" },
2766
2789
  audience: { type: "array", items: { type: "string", enum: ["admin", "operador", "visualizador"] } },
2767
2790
  channels: { type: "object", properties: { in_app: { type: "boolean" }, email: { type: "boolean" }, push: { type: "boolean" } } },
@@ -2784,6 +2807,8 @@ var OPENAPI_SPEC = {
2784
2807
  operationId: "updateReminder",
2785
2808
  security: [{ ApiKeyAuth: ["reminders:update"] }],
2786
2809
  requestBody: { required: true, content: { "application/json": { schema: { type: "object", properties: {
2810
+ kind: { type: "string", enum: ["manual", "digest"] },
2811
+ template_key: { type: "string" },
2787
2812
  title: { type: "string" },
2788
2813
  body: { type: "string" },
2789
2814
  params: { type: "object" },
@@ -2813,7 +2838,7 @@ var OPENAPI_SPEC = {
2813
2838
  tags: ["Cat\xE1logos"],
2814
2839
  summary: "Listar condi\xE7\xF5es de pagamento",
2815
2840
  operationId: "listPaymentConditions",
2816
- security: [{ ApiKeyAuth: ["invoices:read", "contracts:read"] }],
2841
+ security: [{ ApiKeyAuth: ["invoices:read"] }, { ApiKeyAuth: ["contracts:read"] }, { ApiKeyAuth: ["invoices:create"] }, { ApiKeyAuth: ["contracts:write"] }],
2817
2842
  parameters: [...PAGINATION_PARAMS, { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } }],
2818
2843
  responses: { "200": paginatedResponse("#/components/schemas/PaymentCondition"), ...COMMON_ERRORS }
2819
2844
  }
@@ -2823,7 +2848,7 @@ var OPENAPI_SPEC = {
2823
2848
  tags: ["Cat\xE1logos"],
2824
2849
  summary: "Listar unidades de servi\xE7o",
2825
2850
  operationId: "listServiceUnits",
2826
- security: [{ ApiKeyAuth: ["services:read", "services:write"] }],
2851
+ security: [{ ApiKeyAuth: ["services:read"] }, { ApiKeyAuth: ["services:write"] }],
2827
2852
  parameters: [...PAGINATION_PARAMS],
2828
2853
  responses: { "200": paginatedResponse("#/components/schemas/ServiceUnit"), ...COMMON_ERRORS }
2829
2854
  }
@@ -2915,6 +2940,7 @@ var OPENAPI_SPEC = {
2915
2940
  }
2916
2941
  } } }
2917
2942
  },
2943
+ "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
2944
  "404": { description: "Documento n\xE3o encontrado" }
2919
2945
  }
2920
2946
  }
@@ -2997,7 +3023,7 @@ var OPENAPI_SPEC = {
2997
3023
  tags: ["Relat\xF3rios"],
2998
3024
  summary: "Aging de inadimpl\xEAncia com a\xE7\xF5es sugeridas",
2999
3025
  operationId: "reportAgingActions",
3000
- security: [{ ApiKeyAuth: ["invoices:read", "finance:read"] }],
3026
+ security: [{ ApiKeyAuth: ["invoices:read"] }, { ApiKeyAuth: ["finance:read"] }],
3001
3027
  parameters: [
3002
3028
  { name: "limit", in: "query", schema: { type: "integer", minimum: 1, maximum: 40, default: 12 } },
3003
3029
  { name: "min_overdue_days", in: "query", schema: { type: "integer", minimum: 1, maximum: 365, default: 1 } },
@@ -3075,7 +3101,7 @@ var OPENAPI_SPEC = {
3075
3101
  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
3102
  security: [{ ApiKeyAuth: ["nfse:emitir"] }],
3077
3103
  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 }
3104
+ 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
3105
  }
3080
3106
  },
3081
3107
  "/nfse/{id}/cancel": {
@@ -3368,7 +3394,7 @@ var OPENAPI_SPEC = {
3368
3394
  tags: ["Cobran\xE7as"],
3369
3395
  summary: "Criar cobran\xE7a (Pix, boleto, checkout ou cart\xE3o)",
3370
3396
  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).",
3397
+ 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
3398
  security: [{ ApiKeyAuth: ["charges:create"] }],
3373
3399
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/ChargeCreate" } } } },
3374
3400
  responses: {
@@ -3403,14 +3429,14 @@ var OPENAPI_SPEC = {
3403
3429
  tags: ["Cobran\xE7as"],
3404
3430
  summary: "Estornar cobran\xE7a (devolu\xE7\xE3o Pix)",
3405
3431
  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.",
3432
+ 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
3433
  security: [{ ApiKeyAuth: ["charges:refund"] }],
3408
3434
  responses: {
3409
3435
  "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
3436
  "404": errorResponse("Cobran\xE7a n\xE3o encontrada"),
3411
3437
  "409": errorResponse("Cobran\xE7a n\xE3o est\xE1 paga ou j\xE1 estornada"),
3412
3438
  "422": errorResponse("M\xE9todo n\xE3o suportado (apenas Pix) ou endToEndId indispon\xEDvel"),
3413
- ...COMMON_ERRORS
3439
+ ...STEP_UP_ERRORS
3414
3440
  }
3415
3441
  }
3416
3442
  },
@@ -4000,7 +4026,7 @@ var OPENAPI_SPEC = {
4000
4026
  tags: ["Pagamentos a Fornecedor"],
4001
4027
  summary: "Pagar ou agendar pagamento (Pix/boleto)",
4002
4028
  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.",
4029
+ 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
4030
  security: [{ ApiKeyAuth: ["payouts:create"] }],
4005
4031
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/PayoutCreate" } } } },
4006
4032
  responses: {
@@ -4009,7 +4035,7 @@ var OPENAPI_SPEC = {
4009
4035
  "404": errorResponse("Conta banc\xE1ria, parcela ou fornecedor n\xE3o encontrado"),
4010
4036
  "422": errorResponse("Integra\xE7\xE3o n\xE3o configurada ou provider amb\xEDguo"),
4011
4037
  "424": errorResponse("Erro retornado pelo banco"),
4012
- ...COMMON_ERRORS
4038
+ ...STEP_UP_ERRORS
4013
4039
  }
4014
4040
  }
4015
4041
  },
@@ -4029,9 +4055,9 @@ var OPENAPI_SPEC = {
4029
4055
  tags: ["Pagamentos a Fornecedor"],
4030
4056
  summary: "Cancelar pagamento agendado",
4031
4057
  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).",
4058
+ 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
4059
  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 }
4060
+ 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
4061
  }
4036
4062
  },
4037
4063
  "/payouts/{id}/sync": {
@@ -4126,9 +4152,9 @@ var OPENAPI_SPEC = {
4126
4152
  tags: ["Split de Pagamentos"],
4127
4153
  summary: "Estornar execu\xE7\xE3o de split",
4128
4154
  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).",
4155
+ 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
4156
  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 }
4157
+ 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
4158
  }
4133
4159
  },
4134
4160
  "/split-items/{id}/release": {
@@ -4137,9 +4163,9 @@ var OPENAPI_SPEC = {
4137
4163
  tags: ["Split de Pagamentos"],
4138
4164
  summary: "Liberar fatia manualmente",
4139
4165
  operationId: "releaseSplitItem",
4140
- description: "Libera uma fatia (pending/awaiting_nota/failed \u2192 released), apta a virar payout.",
4166
+ description: "Libera uma fatia (pending/awaiting_nota/failed \u2192 released), apta a virar payout." + STEP_UP_NOTE,
4141
4167
  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 }
4168
+ 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
4169
  }
4144
4170
  },
4145
4171
  // -----------------------------------------------------------------------
@@ -4210,7 +4236,7 @@ var OPENAPI_SPEC = {
4210
4236
  summary: "Listar m\xE9todos de pagamento a fornecedor (AP)",
4211
4237
  operationId: "listPaymentMethodsAp",
4212
4238
  description: "Formas de pagamento usadas em payouts (contas a pagar).",
4213
- security: [{ ApiKeyAuth: ["payouts:read"] }],
4239
+ security: [{ ApiKeyAuth: ["payouts:read"] }, { ApiKeyAuth: ["payouts:create"] }],
4214
4240
  parameters: [
4215
4241
  ...PAGINATION_PARAMS,
4216
4242
  { name: "active", in: "query", schema: { type: "string", enum: ["true", "false"] } },
@@ -4475,12 +4501,17 @@ function resolveRef(ref) {
4475
4501
  if (!schema) throw new Error(`Schema n\xE3o encontrado em components: ${name}`);
4476
4502
  return schema;
4477
4503
  }
4478
- function extractScopes(operation) {
4504
+ function extractScopeAlternatives(operation) {
4479
4505
  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) : [];
4506
+ if (!Array.isArray(sec)) return [];
4507
+ return sec.map((alt) => Array.isArray(alt?.ApiKeyAuth) ? alt.ApiKeyAuth.filter(Boolean) : []).filter((alt) => alt.length > 0);
4508
+ }
4509
+ function temScopesPara(desc, held) {
4510
+ if (desc.scopeAlternatives.length === 0) return true;
4511
+ return desc.scopeAlternatives.some((alt) => alt.every((s) => held.has(s)));
4512
+ }
4513
+ function descreverScopes(desc) {
4514
+ return desc.scopeAlternatives.map((alt) => alt.join(" + ")).join(" ou ");
4484
4515
  }
4485
4516
  function describeOperation(operationId) {
4486
4517
  const idx = indexByOperationId();
@@ -4544,7 +4575,8 @@ function describeOperation(operationId) {
4544
4575
  pathParams,
4545
4576
  queryParams,
4546
4577
  hasBody,
4547
- scopes: extractScopes(operation),
4578
+ scopes: [...new Set(extractScopeAlternatives(operation).flat())],
4579
+ scopeAlternatives: extractScopeAlternatives(operation),
4548
4580
  inputSchema,
4549
4581
  summary: operation.summary,
4550
4582
  description: operation.description
@@ -4657,16 +4689,15 @@ function buildCuratedTools(api, heldScopes) {
4657
4689
  `);
4658
4690
  continue;
4659
4691
  }
4660
- const missing = desc.scopes.filter((s) => !heldScopes.has(s));
4661
- if (missing.length > 0) {
4662
- skipped.push({ tool: entry.tool, missingScopes: missing });
4692
+ if (!temScopesPara(desc, heldScopes)) {
4693
+ skipped.push({ tool: entry.tool, missingScopes: desc.scopes.filter((s) => !heldScopes.has(s)) });
4663
4694
  continue;
4664
4695
  }
4665
4696
  const inputSchema = augmentInputSchema(desc.inputSchema, {
4666
4697
  write: entry.write,
4667
4698
  destructive: entry.destructive
4668
4699
  });
4669
- const scopeNote = desc.scopes.length ? ` Scopes: ${desc.scopes.join(", ")}.` : "";
4700
+ const scopeNote = desc.scopes.length ? ` Scopes: ${descreverScopes(desc)}.` : "";
4670
4701
  const prefix = entry.destructive ? "[DESTRUTIVA] " : "";
4671
4702
  const description = `${prefix}${desc.summary ?? entry.operationId}.${scopeNote}`;
4672
4703
  tools.push({
@@ -4865,7 +4896,7 @@ function buildWhoamiTool(api) {
4865
4896
  // src/branding.ts
4866
4897
  var MCP_SERVER_NAME = "comando-one";
4867
4898
  var MCP_SERVER_TITLE = "Comando1";
4868
- var MCP_SERVER_VERSION = "0.5.0";
4899
+ var MCP_SERVER_VERSION = "0.12.0";
4869
4900
  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
4901
  var MCP_SERVER_WEBSITE = "https://comando.one";
4871
4902
  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.0",
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",