@comando.one/mcp-server 0.12.5 → 0.13.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 +82 -14
  2. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -1785,12 +1785,31 @@ var STEP_UP_ERRORS = {
1785
1785
  ...COMMON_ERRORS,
1786
1786
  "403": errorResponse("Scope insuficiente, ou a empresa exige 2FA para movimentar dinheiro (ver descri\xE7\xE3o)")
1787
1787
  };
1788
+ var LIMITE_DO_PLANO_ERROR = {
1789
+ 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.",
1790
+ content: {
1791
+ "application/json": {
1792
+ schema: {
1793
+ type: "object",
1794
+ required: ["error", "code"],
1795
+ properties: {
1796
+ error: { type: "string", description: "Frase em pt-BR para mostrar \xE0 pessoa" },
1797
+ code: { type: "string", enum: ["limite_do_plano"] },
1798
+ limite: { type: "string", description: "Franquia estourada (ex.: cadastros_mes, cobrancas_mes)" },
1799
+ plano: { type: "string", description: "C\xF3digo do plano atual da conta (ex.: gratis, essencial)" },
1800
+ mensagem: { type: "string" },
1801
+ plano_url: { type: "string", description: "Caminho no app para trocar de plano" }
1802
+ }
1803
+ }
1804
+ }
1805
+ }
1806
+ };
1788
1807
  var OPENAPI_SPEC = {
1789
1808
  openapi: "3.1.0",
1790
1809
  info: {
1791
1810
  title: "Comando1 API",
1792
1811
  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.",
1812
+ 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
1813
  contact: { email: "contato@comando.one", url: "https://comando.one" },
1795
1814
  license: { name: "Propriet\xE1rio" }
1796
1815
  },
@@ -1838,9 +1857,9 @@ var OPENAPI_SPEC = {
1838
1857
  "/me": {
1839
1858
  get: {
1840
1859
  tags: ["Auth"],
1841
- summary: "Verificar conectividade",
1860
+ summary: "Verificar conectividade, plano e uso da conta",
1842
1861
  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.",
1862
+ 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
1863
  security: API_KEY_SECURITY,
1845
1864
  responses: {
1846
1865
  "200": {
@@ -1864,14 +1883,51 @@ var OPENAPI_SPEC = {
1864
1883
  properties: {
1865
1884
  name: { type: "string" },
1866
1885
  scopes: { type: "array", items: { type: "string" } },
1867
- last_used_at: { type: ["string", "null"], format: "date-time" }
1886
+ last_used_at: { type: ["string", "null"], format: "date-time" },
1887
+ multi_company: { type: "boolean" },
1888
+ accessible_company_ids: { type: "array", items: { type: "string", format: "uuid" } }
1889
+ }
1890
+ },
1891
+ plan: {
1892
+ type: ["object", "null"],
1893
+ description: "Plano e uso da conta de faturamento. null se o plano n\xE3o puder ser lido.",
1894
+ properties: {
1895
+ code: { type: "string", description: "gratis | essencial | profissional | escala | cortesia" },
1896
+ name: { type: "string", description: "Nome do plano em pt-BR" },
1897
+ status: { type: "string", description: "Status da assinatura (none = sem assinatura paga, Gr\xE1tis)" },
1898
+ billing_cycle: { type: "string", enum: ["monthly", "yearly"] },
1899
+ current_period_end: { type: ["string", "null"], format: "date" },
1900
+ courtesy: { type: "boolean", description: "Plano de cortesia (sem cobran\xE7a)" },
1901
+ usage: {
1902
+ type: "object",
1903
+ 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.",
1904
+ additionalProperties: {
1905
+ type: "object",
1906
+ properties: {
1907
+ used: { type: ["number", "null"], description: "Usado no m\xEAs (ou estoque atual). null quando n\xE3o se mede (lembretes_por_cobranca)" },
1908
+ limit: { type: ["number", "null"], description: "Limite do plano. null = ilimitado" },
1909
+ unavailable: { type: "boolean", description: "true se esta m\xE9trica n\xE3o p\xF4de ser lida agora" }
1910
+ }
1911
+ }
1912
+ },
1913
+ plano_url: { type: "string", description: "Caminho no app para trocar de plano" }
1868
1914
  }
1869
1915
  }
1870
1916
  }
1871
1917
  },
1872
1918
  example: {
1873
1919
  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" }
1920
+ 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-..."] },
1921
+ plan: {
1922
+ code: "essencial",
1923
+ name: "Essencial",
1924
+ status: "active",
1925
+ billing_cycle: "monthly",
1926
+ current_period_end: "2026-12-31",
1927
+ courtesy: false,
1928
+ usage: { cobrancas_mes: { used: 128, limit: 150 }, cadastros_mes: { used: 37, limit: 200 }, empresas: { used: 1, limit: 1 } },
1929
+ plano_url: "/admin/cobranca?aba=plano"
1930
+ }
1875
1931
  }
1876
1932
  }
1877
1933
  }
@@ -1944,6 +2000,7 @@ var OPENAPI_SPEC = {
1944
2000
  content: { "application/json": { schema: { $ref: "#/components/schemas/Customer" } } }
1945
2001
  },
1946
2002
  "400": errorResponse("Par\xE2metros inv\xE1lidos"),
2003
+ "402": LIMITE_DO_PLANO_ERROR,
1947
2004
  ...COMMON_ERRORS
1948
2005
  }
1949
2006
  }
@@ -2392,7 +2449,7 @@ var OPENAPI_SPEC = {
2392
2449
  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
2450
  security: [{ ApiKeyAuth: ["invoices:create"] }],
2394
2451
  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 }
2452
+ 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
2453
  }
2397
2454
  },
2398
2455
  "/invoices/{id}": {
@@ -2462,6 +2519,7 @@ var OPENAPI_SPEC = {
2462
2519
  }
2463
2520
  }
2464
2521
  },
2522
+ "402": LIMITE_DO_PLANO_ERROR,
2465
2523
  ...COMMON_ERRORS
2466
2524
  }
2467
2525
  }
@@ -2650,15 +2708,15 @@ var OPENAPI_SPEC = {
2650
2708
  type: "object",
2651
2709
  properties: {
2652
2710
  to: {
2653
- description: "Destinat\xE1rio(s). Aceita string separada por v\xEDrgula ou lista. Omitido, usa o e-mail do cliente.",
2711
+ 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
2712
  oneOf: [{ type: "string" }, { type: "array", items: { type: "string", format: "email" } }]
2655
2713
  },
2656
2714
  recipient_emails: {
2657
2715
  description: "Apelido de 'to'. Mesmo formato; 'to' tem preced\xEAncia.",
2658
2716
  oneOf: [{ type: "string" }, { type: "array", items: { type: "string", format: "email" } }]
2659
2717
  },
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." },
2718
+ subject: { type: "string", description: "Assunto. Uma linha, at\xE9 200 caracteres. Padr\xE3o: 'Segunda via da fatura <numero>'." },
2719
+ 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
2720
  include_attachments: { type: "boolean", default: true, description: "Anexa os arquivos da fatura." }
2663
2721
  }
2664
2722
  }
@@ -2684,7 +2742,16 @@ var OPENAPI_SPEC = {
2684
2742
  }
2685
2743
  }
2686
2744
  },
2687
- ...COMMON_ERRORS
2745
+ ...COMMON_ERRORS,
2746
+ "402": {
2747
+ ...LIMITE_DO_PLANO_ERROR,
2748
+ 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."
2749
+ },
2750
+ "429": errorResponse(
2751
+ "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."
2752
+ ),
2753
+ "409": errorResponse("Mesma segunda via, para os mesmos destinat\xE1rios, enviada h\xE1 menos de 1 minuto"),
2754
+ "422": { description: "Destinat\xE1rio que n\xE3o \xE9 e-mail cadastrado do cliente da fatura (cadastro ou contatos)." }
2688
2755
  }
2689
2756
  }
2690
2757
  },
@@ -3240,6 +3307,7 @@ var OPENAPI_SPEC = {
3240
3307
  responses: {
3241
3308
  "201": { description: "Fornecedor criado", content: { "application/json": { schema: { $ref: "#/components/schemas/Supplier" } } } },
3242
3309
  "400": errorResponse("Dados inv\xE1lidos"),
3310
+ "402": LIMITE_DO_PLANO_ERROR,
3243
3311
  ...COMMON_ERRORS
3244
3312
  }
3245
3313
  }
@@ -3403,7 +3471,7 @@ var OPENAPI_SPEC = {
3403
3471
  operationId: "createPurchaseInvoice",
3404
3472
  security: [{ ApiKeyAuth: ["purchase_invoices:create"] }],
3405
3473
  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 }
3474
+ 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
3475
  }
3408
3476
  },
3409
3477
  "/purchase-invoices/{id}": {
@@ -3510,8 +3578,8 @@ var OPENAPI_SPEC = {
3510
3578
  tags: ["Cobran\xE7as"],
3511
3579
  summary: "Confirmar pagamento (Pix est\xE1tico/offline)",
3512
3580
  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"] }],
3581
+ 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.",
3582
+ security: [{ ApiKeyAuth: ["invoices:settle"] }],
3515
3583
  responses: {
3516
3584
  "200": { description: "Cobran\xE7a confirmada (paga)", content: { "application/json": { schema: { $ref: "#/components/schemas/Charge" } } } },
3517
3585
  "404": errorResponse("Cobran\xE7a n\xE3o encontrada"),
@@ -4960,7 +5028,7 @@ function buildWhoamiTool(api) {
4960
5028
  // src/branding.ts
4961
5029
  var MCP_SERVER_NAME = "comando-one";
4962
5030
  var MCP_SERVER_TITLE = "Comando1";
4963
- var MCP_SERVER_VERSION = "0.12.5";
5031
+ var MCP_SERVER_VERSION = "0.13.0";
4964
5032
  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
5033
  var MCP_SERVER_WEBSITE = "https://comando.one";
4966
5034
  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.13.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",