@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.
- package/README.md +12 -7
- package/dist/index.js +62 -31
- 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).
|
|
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
|
|
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
|
-
- **
|
|
55
|
-
- **`comando_request`** — escape hatch genérico (`method`, `path`, `query`, `body`)
|
|
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** (
|
|
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
|
-
//
|
|
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
|
-
...
|
|
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
|
-
...
|
|
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"), ...
|
|
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"), ...
|
|
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"), ...
|
|
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
|
|
4504
|
+
function extractScopeAlternatives(operation) {
|
|
4479
4505
|
const sec = operation.security;
|
|
4480
|
-
if (!Array.isArray(sec)
|
|
4481
|
-
|
|
4482
|
-
|
|
4483
|
-
|
|
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:
|
|
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
|
-
|
|
4661
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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",
|