@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.
- package/dist/index.js +82 -14
- 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
|
|
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: "
|
|
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: ["
|
|
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.
|
|
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.
|
|
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",
|