@comando.one/mcp-server 0.12.5 → 0.14.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 (2) hide show
  1. package/dist/index.js +97 -16
  2. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -384,7 +384,8 @@ var WEBHOOK_EVENT_KEYS = [
384
384
  "repasse.failed",
385
385
  "repasse.reversed",
386
386
  "supplier_payout_request.created",
387
- "supplier_payout_request.approved"
387
+ "supplier_payout_request.approved",
388
+ "plan.limit_near"
388
389
  ];
389
390
  var SCHEMAS = {
390
391
  Error: {
@@ -1785,12 +1786,31 @@ var STEP_UP_ERRORS = {
1785
1786
  ...COMMON_ERRORS,
1786
1787
  "403": errorResponse("Scope insuficiente, ou a empresa exige 2FA para movimentar dinheiro (ver descri\xE7\xE3o)")
1787
1788
  };
1789
+ var LIMITE_DO_PLANO_ERROR = {
1790
+ description: "Limite do plano atingido (franquia do m\xEAs ou de estoque da conta). `code`: limite_do_plano; `limite`: a franquia estourada (ex.: cadastros_mes, cobrancas_mes); `plano`: o plano atual; `plano_url`: onde trocar de plano no app. N\xE3o tente de novo: s\xF3 a troca de plano (ou a virada do m\xEAs, para franquias mensais) libera.",
1791
+ content: {
1792
+ "application/json": {
1793
+ schema: {
1794
+ type: "object",
1795
+ required: ["error", "code"],
1796
+ properties: {
1797
+ error: { type: "string", description: "Frase em pt-BR para mostrar \xE0 pessoa" },
1798
+ code: { type: "string", enum: ["limite_do_plano"] },
1799
+ limite: { type: "string", description: "Franquia estourada (ex.: cadastros_mes, cobrancas_mes)" },
1800
+ plano: { type: "string", description: "C\xF3digo do plano atual da conta (ex.: gratis, essencial)" },
1801
+ mensagem: { type: "string" },
1802
+ plano_url: { type: "string", description: "Caminho no app para trocar de plano" }
1803
+ }
1804
+ }
1805
+ }
1806
+ }
1807
+ };
1788
1808
  var OPENAPI_SPEC = {
1789
1809
  openapi: "3.1.0",
1790
1810
  info: {
1791
1811
  title: "Comando1 API",
1792
1812
  version: "1.1.0",
1793
- description: "API REST p\xFAblica do Comando1 \u2014 ERP SaaS para empresas de servi\xE7o brasileiras.\n\nAutentique com uma API key no header `x-api-key` ou `Authorization: Bearer <key>`.\n\n**Idempot\xEAncia:** envie o header `Idempotency-Key` (string \xFAnica) em requisi\xE7\xF5es POST. Repeti\xE7\xF5es com a mesma chave retornam a resposta original (header `Idempotent-Replayed: true`), evitando cobran\xE7as/pagamentos duplicados em caso de retry.\n\n**Rate limit:** 60 requisi\xE7\xF5es/minuto por chave (429 ao exceder).\n\n**Erros:** toda falha devolve JSON com `error` (texto acion\xE1vel, em portugu\xEAs). `424 Failed Dependency` = a requisi\xE7\xE3o estava correta, mas um terceiro falhou \u2014 o fisco, o banco, o gateway de pagamento; o motivo do terceiro vem em `error`. A API nunca responde 502/504: a borda da Cloudflare substituiria o corpo pela p\xE1gina HTML dela e o motivo se perderia.\n\n**N\xE3o existe ambiente de homologa\xE7\xE3o.** S\xF3 h\xE1 chaves `cmd_live_`, e toda emiss\xE3o de NFS-e \xE9 documento fiscal real. Para ensaiar a integra\xE7\xE3o sem gerar documento, exercite os caminhos que RECUSAM (payload incompleto, fatura inexistente) e confira o XML antes pela tela do sistema.\n\n**Multi-empresa:** chaves podem ter acesso a v\xE1rias empresas. Use `GET /v1/companies` para list\xE1-las e o header `X-Company-Id` para escolher o tenant de cada request (omitido = empresa padr\xE3o da chave).\n\nGere sua chave em **Configura\xE7\xF5es \u2192 API Keys** dentro da plataforma.",
1813
+ description: "API REST p\xFAblica do Comando1 \u2014 ERP SaaS para empresas de servi\xE7o brasileiras.\n\nAutentique com uma API key no header `x-api-key` ou `Authorization: Bearer <key>`.\n\n**Idempot\xEAncia:** envie o header `Idempotency-Key` (string \xFAnica) em requisi\xE7\xF5es POST. Repeti\xE7\xF5es com a mesma chave retornam a resposta original (header `Idempotent-Replayed: true`), evitando cobran\xE7as/pagamentos duplicados em caso de retry. A chave pertence \xE0 credencial que a usou (chave de API, usu\xE1rio ou pessoa que autorizou o token OAuth). Reusar a chave em outra rota devolve **422**. Respostas que n\xE3o s\xE3o 2xx n\xE3o ficam guardadas: repita com a mesma chave.\n\n**Rate limit:** 60 requisi\xE7\xF5es/minuto por chave (429 ao exceder).\n\n**Erros:** toda falha devolve JSON com `error` (texto acion\xE1vel, em portugu\xEAs). `424 Failed Dependency` = a requisi\xE7\xE3o estava correta, mas um terceiro falhou \u2014 o fisco, o banco, o gateway de pagamento; o motivo do terceiro vem em `error`. A API nunca responde 502/504: a borda da Cloudflare substituiria o corpo pela p\xE1gina HTML dela e o motivo se perderia.\n\n**N\xE3o existe ambiente de homologa\xE7\xE3o.** S\xF3 h\xE1 chaves `cmd_live_`, e toda emiss\xE3o de NFS-e \xE9 documento fiscal real. Para ensaiar a integra\xE7\xE3o sem gerar documento, exercite os caminhos que RECUSAM (payload incompleto, fatura inexistente) e confira o XML antes pela tela do sistema.\n\n**Multi-empresa:** chaves podem ter acesso a v\xE1rias empresas. Use `GET /v1/companies` para list\xE1-las e o header `X-Company-Id` para escolher o tenant de cada request (omitido = empresa padr\xE3o da chave).\n\nGere sua chave em **Configura\xE7\xF5es \u2192 API Keys** dentro da plataforma.",
1794
1814
  contact: { email: "contato@comando.one", url: "https://comando.one" },
1795
1815
  license: { name: "Propriet\xE1rio" }
1796
1816
  },
@@ -1838,9 +1858,9 @@ var OPENAPI_SPEC = {
1838
1858
  "/me": {
1839
1859
  get: {
1840
1860
  tags: ["Auth"],
1841
- summary: "Verificar conectividade",
1861
+ summary: "Verificar conectividade, plano e uso da conta",
1842
1862
  operationId: "getMe",
1843
- description: "Retorna os dados da empresa e da chave autenticada. N\xE3o exige scope espec\xEDfico \u2014 qualquer chave v\xE1lida funciona.",
1863
+ description: "Retorna os dados da empresa, da chave autenticada e o `plan`: plano da conta de faturamento e o uso de cada franquia no m\xEAs (a franquia \xE9 da CONTA, somada entre as empresas dela). Consulte antes de criar em lote para n\xE3o esbarrar no 402 `limite_do_plano`. `plan` \xE9 null enquanto o plano n\xE3o puder ser lido. N\xE3o exige scope espec\xEDfico \u2014 qualquer chave v\xE1lida funciona.",
1844
1864
  security: API_KEY_SECURITY,
1845
1865
  responses: {
1846
1866
  "200": {
@@ -1864,14 +1884,63 @@ var OPENAPI_SPEC = {
1864
1884
  properties: {
1865
1885
  name: { type: "string" },
1866
1886
  scopes: { type: "array", items: { type: "string" } },
1867
- last_used_at: { type: ["string", "null"], format: "date-time" }
1887
+ last_used_at: { type: ["string", "null"], format: "date-time" },
1888
+ multi_company: { type: "boolean" },
1889
+ accessible_company_ids: { type: "array", items: { type: "string", format: "uuid" } }
1890
+ }
1891
+ },
1892
+ plan: {
1893
+ type: ["object", "null"],
1894
+ description: "Plano e uso da conta de faturamento. null se o plano n\xE3o puder ser lido.",
1895
+ properties: {
1896
+ code: { type: "string", description: "gratis | essencial | profissional | escala | cortesia" },
1897
+ name: { type: "string", description: "Nome do plano em pt-BR" },
1898
+ status: { type: "string", description: "Status da assinatura (none = sem assinatura paga, Gr\xE1tis)" },
1899
+ billing_cycle: { type: "string", enum: ["monthly", "yearly"] },
1900
+ current_period_end: { type: ["string", "null"], format: "date" },
1901
+ courtesy: { type: "boolean", description: "Plano de cortesia (sem cobran\xE7a, sem prazo)" },
1902
+ transition_until: { type: ["string", "null"], format: "date", description: "Conta em transi\xE7\xE3o da virada dos planos: at\xE9 a v\xE9spera desta data fica sem cobran\xE7a, com as franquias do Escala; nesse dia passa ao Gr\xE1tis (a menos que escolha um plano)" },
1903
+ features: {
1904
+ type: "object",
1905
+ description: "Recursos que o plano inclui. O Gr\xE1tis n\xE3o envia WhatsApp nem conecta banco automaticamente (extrato por OFX/CSV).",
1906
+ properties: {
1907
+ whatsapp: { type: "boolean" },
1908
+ bank_sync: { type: "boolean", description: "Conex\xE3o autom\xE1tica com o banco (extrato sincronizado)" }
1909
+ }
1910
+ },
1911
+ usage: {
1912
+ type: "object",
1913
+ description: "Uma entrada por franquia: empresas, usuarios, cadastros_mes, cobrancas_mes, nfse_mes, contas_bancarias, sync_bancario, storage_gb, ai_tokens_input_mes, ai_tokens_output_mes, email_mes, whatsapp_mes, lembretes_por_cobranca. `_mes` zera na virada do m\xEAs (hor\xE1rio de Bras\xEDlia); as demais s\xE3o estoque.",
1914
+ additionalProperties: {
1915
+ type: "object",
1916
+ properties: {
1917
+ used: { type: ["number", "null"], description: "Usado no m\xEAs (ou estoque atual). null quando n\xE3o se mede (lembretes_por_cobranca)" },
1918
+ limit: { type: ["number", "null"], description: "Limite do plano. null = ilimitado" },
1919
+ unavailable: { type: "boolean", description: "true se esta m\xE9trica n\xE3o p\xF4de ser lida agora" },
1920
+ percent: { type: ["integer", "null"], description: "% do limite j\xE1 usado (null sem limite)" },
1921
+ projected: { type: ["integer", "null"], description: "Franquias _mes: uso projetado at\xE9 o fim do m\xEAs no ritmo atual" },
1922
+ level: { type: ["string", "null"], enum: ["previsao", "oitenta", "esgotada", null], description: "Mesmo n\xEDvel do aviso/webhook plan.limit_near: previsao (no ritmo, acaba antes da virada), oitenta (\u2265 80%), esgotada" }
1923
+ }
1924
+ }
1925
+ },
1926
+ plano_url: { type: "string", description: "Caminho no app para trocar de plano" }
1868
1927
  }
1869
1928
  }
1870
1929
  }
1871
1930
  },
1872
1931
  example: {
1873
1932
  company: { id: "18fc359b-...", name: "Acme Servi\xE7os", trade_name: "Acme", document: "12345678000195" },
1874
- api_key: { name: "Integra\xE7\xE3o ERP", scopes: ["customers:read", "invoices:read"], last_used_at: "2026-06-04T18:17:47+00:00" }
1933
+ api_key: { name: "Integra\xE7\xE3o ERP", scopes: ["customers:read", "invoices:read"], last_used_at: "2026-06-04T18:17:47+00:00", multi_company: false, accessible_company_ids: ["18fc359b-..."] },
1934
+ plan: {
1935
+ code: "essencial",
1936
+ name: "Essencial",
1937
+ status: "active",
1938
+ billing_cycle: "monthly",
1939
+ current_period_end: "2026-12-31",
1940
+ courtesy: false,
1941
+ usage: { cobrancas_mes: { used: 128, limit: 150 }, cadastros_mes: { used: 37, limit: 200 }, empresas: { used: 1, limit: 1 } },
1942
+ plano_url: "/admin/cobranca?aba=plano"
1943
+ }
1875
1944
  }
1876
1945
  }
1877
1946
  }
@@ -1944,6 +2013,7 @@ var OPENAPI_SPEC = {
1944
2013
  content: { "application/json": { schema: { $ref: "#/components/schemas/Customer" } } }
1945
2014
  },
1946
2015
  "400": errorResponse("Par\xE2metros inv\xE1lidos"),
2016
+ "402": LIMITE_DO_PLANO_ERROR,
1947
2017
  ...COMMON_ERRORS
1948
2018
  }
1949
2019
  }
@@ -2392,7 +2462,7 @@ var OPENAPI_SPEC = {
2392
2462
  description: "Cria uma fatura. Se 'items' for enviado, o valor \xE9 calculado a partir deles. O cliente pode ser da empresa **ou compartilhado com ela com a permiss\xE3o 'Faturar'** (o dono marca em Clientes \u2192 Compartilhar; \xE9 diferente de 'Faturas', que trata das faturas do dono). A fatura pertence a quem a lan\xE7a \u2014 financeiro, baixa e NFS-e s\xE3o dessa empresa; s\xF3 o cadastro do cliente \xE9 do dono. Cliente compartilhado sem 'Faturar' devolve 404 \u2014 na API e na tela.",
2393
2463
  security: [{ ApiKeyAuth: ["invoices:create"] }],
2394
2464
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/InvoiceCreate" } } } },
2395
- responses: { "201": { description: "Fatura criada", content: { "application/json": { schema: { $ref: "#/components/schemas/Invoice" } } } }, "400": errorResponse("Dados inv\xE1lidos"), "404": errorResponse("Cliente n\xE3o encontrado"), ...COMMON_ERRORS }
2465
+ responses: { "201": { description: "Fatura criada", content: { "application/json": { schema: { $ref: "#/components/schemas/Invoice" } } } }, "400": errorResponse("Dados inv\xE1lidos"), "404": errorResponse("Cliente n\xE3o encontrado"), "402": LIMITE_DO_PLANO_ERROR, ...COMMON_ERRORS }
2396
2466
  }
2397
2467
  },
2398
2468
  "/invoices/{id}": {
@@ -2462,6 +2532,7 @@ var OPENAPI_SPEC = {
2462
2532
  }
2463
2533
  }
2464
2534
  },
2535
+ "402": LIMITE_DO_PLANO_ERROR,
2465
2536
  ...COMMON_ERRORS
2466
2537
  }
2467
2538
  }
@@ -2476,7 +2547,7 @@ var OPENAPI_SPEC = {
2476
2547
  security: [{ ApiKeyAuth: ["invoices:send"] }],
2477
2548
  requestBody: { required: true, content: { "application/json": { schema: { type: "object", properties: {
2478
2549
  enabled: { type: "boolean", default: true, description: "false desliga e volta o canal para manual" },
2479
- channel: { type: "string", enum: ["manual", "email", "whatsapp", "ambos"], default: "email", description: '"ambos" = e-mail E WhatsApp' },
2550
+ channel: { type: "string", enum: ["manual", "email", "whatsapp", "ambos"], default: "email", description: '"ambos" = e-mail E WhatsApp. WhatsApp \xE9 dos planos pagos (Essencial em diante): no Gr\xE1tis a mensagem n\xE3o \xE9 enviada (cancelada com motivo plano_sem_whatsapp) \u2014 confira plan.features.whatsapp em GET /v1/me' },
2480
2551
  days_before: { type: "integer", minimum: 0, maximum: 90, default: 0, description: "dias ANTES do vencimento" }
2481
2552
  } } } } },
2482
2553
  responses: {
@@ -2650,15 +2721,15 @@ var OPENAPI_SPEC = {
2650
2721
  type: "object",
2651
2722
  properties: {
2652
2723
  to: {
2653
- description: "Destinat\xE1rio(s). Aceita string separada por v\xEDrgula ou lista. Omitido, usa o e-mail do cliente.",
2724
+ description: "Destinat\xE1rio(s). Aceita string separada por v\xEDrgula ou lista. Omitido, usa o e-mail do cliente. Precisa ser um e-mail cadastrado do cliente da fatura (cadastro ou contatos, `POST /v1/customers/{id}/contacts`); fora disso, 422.",
2654
2725
  oneOf: [{ type: "string" }, { type: "array", items: { type: "string", format: "email" } }]
2655
2726
  },
2656
2727
  recipient_emails: {
2657
2728
  description: "Apelido de 'to'. Mesmo formato; 'to' tem preced\xEAncia.",
2658
2729
  oneOf: [{ type: "string" }, { type: "array", items: { type: "string", format: "email" } }]
2659
2730
  },
2660
- subject: { type: "string", description: "Assunto. Padr\xE3o: 'Segunda via da fatura <numero>'." },
2661
- body_html: { type: "string", description: "Corpo em HTML. Padr\xE3o: mensagem curta com valor e vencimento." },
2731
+ subject: { type: "string", description: "Assunto. Uma linha, at\xE9 200 caracteres. Padr\xE3o: 'Segunda via da fatura <numero>'." },
2732
+ body_html: { type: "string", description: "Texto da mensagem; tags HTML s\xE3o removidas (links, imagens e formul\xE1rios n\xE3o passam), quebras de linha mantidas. Padr\xE3o: mensagem curta com valor e vencimento." },
2662
2733
  include_attachments: { type: "boolean", default: true, description: "Anexa os arquivos da fatura." }
2663
2734
  }
2664
2735
  }
@@ -2684,7 +2755,16 @@ var OPENAPI_SPEC = {
2684
2755
  }
2685
2756
  }
2686
2757
  },
2687
- ...COMMON_ERRORS
2758
+ ...COMMON_ERRORS,
2759
+ "402": {
2760
+ ...LIMITE_DO_PLANO_ERROR,
2761
+ description: "Os e-mails inclu\xEDdos no plano acabaram neste m\xEAs e o plano n\xE3o tem excedente (`code`: limite_do_plano), ou faltou saldo para o excedente (`code`: saldo_insuficiente | limite_de_gasto_atingido | carteira_inativa). Nada foi enviado; tentar de novo n\xE3o resolve."
2762
+ },
2763
+ "429": errorResponse(
2764
+ "Rate limit da chave, OU teto di\xE1rio de envios da conta (`code`: teto_diario). No teto, `libera_em`/`retry_at` e o cabe\xE7alho `Retry-After` dizem quando volta (00:00 de Bras\xEDlia) \u2014 n\xE3o \xE9 falta de saldo."
2765
+ ),
2766
+ "409": errorResponse("Mesma segunda via, para os mesmos destinat\xE1rios, enviada h\xE1 menos de 1 minuto"),
2767
+ "422": { description: "Destinat\xE1rio que n\xE3o \xE9 e-mail cadastrado do cliente da fatura (cadastro ou contatos)." }
2688
2768
  }
2689
2769
  }
2690
2770
  },
@@ -3240,6 +3320,7 @@ var OPENAPI_SPEC = {
3240
3320
  responses: {
3241
3321
  "201": { description: "Fornecedor criado", content: { "application/json": { schema: { $ref: "#/components/schemas/Supplier" } } } },
3242
3322
  "400": errorResponse("Dados inv\xE1lidos"),
3323
+ "402": LIMITE_DO_PLANO_ERROR,
3243
3324
  ...COMMON_ERRORS
3244
3325
  }
3245
3326
  }
@@ -3403,7 +3484,7 @@ var OPENAPI_SPEC = {
3403
3484
  operationId: "createPurchaseInvoice",
3404
3485
  security: [{ ApiKeyAuth: ["purchase_invoices:create"] }],
3405
3486
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/PurchaseInvoiceCreate" } } } },
3406
- responses: { "201": { description: "Conta a pagar criada", content: { "application/json": { schema: { $ref: "#/components/schemas/PurchaseInvoice" } } } }, "400": errorResponse("Dados inv\xE1lidos"), "404": errorResponse("Fornecedor n\xE3o encontrado"), ...COMMON_ERRORS }
3487
+ responses: { "201": { description: "Conta a pagar criada", content: { "application/json": { schema: { $ref: "#/components/schemas/PurchaseInvoice" } } } }, "400": errorResponse("Dados inv\xE1lidos"), "404": errorResponse("Fornecedor n\xE3o encontrado"), "402": LIMITE_DO_PLANO_ERROR, ...COMMON_ERRORS }
3407
3488
  }
3408
3489
  },
3409
3490
  "/purchase-invoices/{id}": {
@@ -3510,8 +3591,8 @@ var OPENAPI_SPEC = {
3510
3591
  tags: ["Cobran\xE7as"],
3511
3592
  summary: "Confirmar pagamento (Pix est\xE1tico/offline)",
3512
3593
  operationId: "confirmCharge",
3513
- description: "Marca manualmente uma cobran\xE7a Pix est\xE1tico (provider 'pix_offline') como paga e dispara o webhook charge.paid. Para Inter/C6 a baixa vem do banco (n\xE3o use este endpoint).",
3514
- security: [{ ApiKeyAuth: ["charges:create"] }],
3594
+ description: "Marca manualmente uma cobran\xE7a Pix est\xE1tico (provider 'pix_offline') como paga e dispara o webhook charge.paid. Para Inter/C6 a baixa vem do banco (n\xE3o use este endpoint). \xC9 uma baixa: exige o mesmo scope de POST /invoices/{id}/charges/{charge_id}/pay.",
3595
+ security: [{ ApiKeyAuth: ["invoices:settle"] }],
3515
3596
  responses: {
3516
3597
  "200": { description: "Cobran\xE7a confirmada (paga)", content: { "application/json": { schema: { $ref: "#/components/schemas/Charge" } } } },
3517
3598
  "404": errorResponse("Cobran\xE7a n\xE3o encontrada"),
@@ -4960,7 +5041,7 @@ function buildWhoamiTool(api) {
4960
5041
  // src/branding.ts
4961
5042
  var MCP_SERVER_NAME = "comando-one";
4962
5043
  var MCP_SERVER_TITLE = "Comando1";
4963
- var MCP_SERVER_VERSION = "0.12.5";
5044
+ var MCP_SERVER_VERSION = "0.14.0";
4964
5045
  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.";
4965
5046
  var MCP_SERVER_WEBSITE = "https://comando.one";
4966
5047
  var MCP_SERVER_ICONS = [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@comando.one/mcp-server",
3
- "version": "0.12.5",
3
+ "version": "0.14.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",