@comando.one/mcp-server 0.6.0 → 0.8.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 +3 -3
- package/dist/index.js +71 -4
- package/package.json +2 -2
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 **
|
|
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.
|
|
4
4
|
|
|
5
5
|
## Instalação rápida (Claude Desktop)
|
|
6
6
|
|
|
@@ -51,13 +51,13 @@ Ambos expõem o **mesmo conjunto de ferramentas** (131 curadas + `lookups` + `co
|
|
|
51
51
|
|
|
52
52
|
## Como funciona
|
|
53
53
|
|
|
54
|
-
- **
|
|
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
55
|
- **`comando_request`** — escape hatch genérico (`method`, `path`, `query`, `body`) que cobre 100% dos endpoints restantes.
|
|
56
56
|
- **`lookups`** — catálogos read-only (centros de custo, condições/métodos de pagamento, naturezas, contas bancárias).
|
|
57
57
|
- **`whoami`** — identidade, empresas acessíveis e scopes da chave.
|
|
58
58
|
- **Nomes em português** — cada tool viaja com `title` (e `annotations.title`) vindo do
|
|
59
59
|
`summary` da OpenAPI, então o cliente mostra "Listar clientes" em vez de "Customers list".
|
|
60
|
-
O servidor também se identifica com `title` ("
|
|
60
|
+
O servidor também se identifica com `title` ("Comando1"), `description`, `websiteUrl` e
|
|
61
61
|
`icons` (SEP-973). Clientes que ainda não leem esses campos caem no nome técnico sem quebrar.
|
|
62
62
|
|
|
63
63
|
### Segurança
|
package/dist/index.js
CHANGED
|
@@ -147,6 +147,8 @@ var MANIFEST = [
|
|
|
147
147
|
{ operationId: "setInvoiceAutoSend", tool: "invoices_set_auto_send", write: true },
|
|
148
148
|
{ operationId: "listInvoiceCharges", tool: "invoices_list_charges" },
|
|
149
149
|
{ operationId: "settleInvoiceCharge", tool: "invoices_settle_charge", write: true },
|
|
150
|
+
{ operationId: "listChargePayments", tool: "invoices_list_charge_payments" },
|
|
151
|
+
{ operationId: "reverseChargePayment", tool: "invoices_reverse_payment", write: true, destructive: true },
|
|
150
152
|
{ operationId: "generateContractInvoices", tool: "contracts_generate_invoices", write: true },
|
|
151
153
|
// ----- Cobranças -----
|
|
152
154
|
{ operationId: "listCharges", tool: "charges_list" },
|
|
@@ -1431,9 +1433,9 @@ var COMMON_ERRORS = {
|
|
|
1431
1433
|
var OPENAPI_SPEC = {
|
|
1432
1434
|
openapi: "3.1.0",
|
|
1433
1435
|
info: {
|
|
1434
|
-
title: "
|
|
1436
|
+
title: "Comando1 API",
|
|
1435
1437
|
version: "1.1.0",
|
|
1436
|
-
description: "API REST p\xFAblica do
|
|
1438
|
+
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**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.",
|
|
1437
1439
|
contact: { email: "contato@comando.one", url: "https://comando.one" },
|
|
1438
1440
|
license: { name: "Propriet\xE1rio" }
|
|
1439
1441
|
},
|
|
@@ -2162,6 +2164,71 @@ var OPENAPI_SPEC = {
|
|
|
2162
2164
|
}
|
|
2163
2165
|
}
|
|
2164
2166
|
},
|
|
2167
|
+
"/invoices/{id}/charges/{charge_id}/payments": {
|
|
2168
|
+
parameters: [
|
|
2169
|
+
{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } },
|
|
2170
|
+
{ name: "charge_id", in: "path", required: true, schema: { type: "string", format: "uuid" } }
|
|
2171
|
+
],
|
|
2172
|
+
get: {
|
|
2173
|
+
tags: ["Faturas"],
|
|
2174
|
+
summary: "Listar as baixas de uma parcela",
|
|
2175
|
+
operationId: "listChargePayments",
|
|
2176
|
+
description: "Os recebimentos j\xE1 registrados na parcela. `reconciled: true` avisa que aquele pagamento est\xE1 conciliado com o extrato \u2014 o estorno dele ser\xE1 recusado at\xE9 a concilia\xE7\xE3o ser desfeita.",
|
|
2177
|
+
security: [{ ApiKeyAuth: ["invoices:read"] }],
|
|
2178
|
+
responses: { "200": { description: "Baixas da parcela", content: { "application/json": { schema: { type: "object", properties: {
|
|
2179
|
+
invoice_id: { type: "string" },
|
|
2180
|
+
charge_id: { type: "string" },
|
|
2181
|
+
charge_amount: { type: "number" },
|
|
2182
|
+
charge_payment_status: { type: "string" },
|
|
2183
|
+
paid_amount: { type: "number" },
|
|
2184
|
+
remaining_amount: { type: "number" },
|
|
2185
|
+
total: { type: "integer" },
|
|
2186
|
+
payments: { type: "array", items: { type: "object", properties: {
|
|
2187
|
+
payment_id: { type: "string" },
|
|
2188
|
+
allocation_id: { type: "string" },
|
|
2189
|
+
amount: { type: "number" },
|
|
2190
|
+
payment_date: { type: "string", format: "date" },
|
|
2191
|
+
payment_total: { type: "number" },
|
|
2192
|
+
notes: { type: "string" },
|
|
2193
|
+
reconciled: { type: "boolean", description: "conciliado com o extrato \u2014 n\xE3o pode ser estornado por aqui" }
|
|
2194
|
+
} } }
|
|
2195
|
+
} } } } }, "404": errorResponse("Fatura ou parcela n\xE3o encontrada"), ...COMMON_ERRORS }
|
|
2196
|
+
}
|
|
2197
|
+
},
|
|
2198
|
+
"/invoices/{id}/charges/{charge_id}/payments/{payment_id}": {
|
|
2199
|
+
parameters: [
|
|
2200
|
+
{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } },
|
|
2201
|
+
{ name: "charge_id", in: "path", required: true, schema: { type: "string", format: "uuid" } },
|
|
2202
|
+
{ name: "payment_id", in: "path", required: true, schema: { type: "string", format: "uuid" } }
|
|
2203
|
+
],
|
|
2204
|
+
delete: {
|
|
2205
|
+
tags: ["Faturas"],
|
|
2206
|
+
summary: "Estornar uma baixa",
|
|
2207
|
+
operationId: "reverseChargePayment",
|
|
2208
|
+
description: "Desfaz um recebimento registrado na parcela. A parcela e a fatura voltam a `pendente`/`vencido`/`parcial` pelo pr\xF3prio banco. O pagamento \xE9 apagado quando existia s\xF3 para esta baixa; cobrindo outras faturas, perde apenas esta aloca\xE7\xE3o e tem o valor reduzido. RECUSA (409) se o pagamento estiver conciliado com o extrato ou se a parcela tiver gerado repasse (split) j\xE1 liberado ou pago \u2014 nos dois casos a resposta diz o que desfazer antes.",
|
|
2209
|
+
security: [{ ApiKeyAuth: ["invoices:settle"] }],
|
|
2210
|
+
responses: {
|
|
2211
|
+
"200": { description: "Baixa estornada", content: { "application/json": { schema: { type: "object", properties: {
|
|
2212
|
+
reversed_payment_id: { type: "string" },
|
|
2213
|
+
reversed_amount: { type: "number" },
|
|
2214
|
+
payment_deleted: { type: "boolean", description: "false = o pagamento cobria outras faturas e foi s\xF3 reduzido" },
|
|
2215
|
+
invoice_id: { type: "string" },
|
|
2216
|
+
invoice_number: { type: "string" },
|
|
2217
|
+
invoice_payment_status: { type: "string" },
|
|
2218
|
+
charge: { type: "object", properties: {
|
|
2219
|
+
id: { type: "string" },
|
|
2220
|
+
amount: { type: "number" },
|
|
2221
|
+
paid_amount: { type: "number" },
|
|
2222
|
+
remaining_amount: { type: "number" },
|
|
2223
|
+
payment_status: { type: "string" }
|
|
2224
|
+
} }
|
|
2225
|
+
} } } } },
|
|
2226
|
+
"404": errorResponse("Fatura, parcela ou baixa n\xE3o encontrada"),
|
|
2227
|
+
"409": errorResponse("Pagamento conciliado com o extrato, ou repasse (split) liberado/pago"),
|
|
2228
|
+
...COMMON_ERRORS
|
|
2229
|
+
}
|
|
2230
|
+
}
|
|
2231
|
+
},
|
|
2165
2232
|
"/invoices/{id}/send": {
|
|
2166
2233
|
parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
|
|
2167
2234
|
post: {
|
|
@@ -3892,7 +3959,7 @@ function buildRequestTool(api) {
|
|
|
3892
3959
|
return {
|
|
3893
3960
|
name: "comando_request",
|
|
3894
3961
|
title: "Chamada livre \xE0 API",
|
|
3895
|
-
description: "Chamada gen\xE9rica \xE0 API do
|
|
3962
|
+
description: "Chamada gen\xE9rica \xE0 API do Comando1 (cobre qualquer endpoint /v1/*). Use quando n\xE3o houver uma tool espec\xEDfica. Ex.: method=GET, path=/webhooks/deliveries. Os scopes da chave s\xE3o validados pelo servidor.",
|
|
3896
3963
|
inputSchema: {
|
|
3897
3964
|
type: "object",
|
|
3898
3965
|
required: ["method", "path"],
|
|
@@ -4022,7 +4089,7 @@ function buildWhoamiTool(api) {
|
|
|
4022
4089
|
|
|
4023
4090
|
// src/branding.ts
|
|
4024
4091
|
var MCP_SERVER_NAME = "comando-one";
|
|
4025
|
-
var MCP_SERVER_TITLE = "
|
|
4092
|
+
var MCP_SERVER_TITLE = "Comando1";
|
|
4026
4093
|
var MCP_SERVER_VERSION = "0.5.0";
|
|
4027
4094
|
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.";
|
|
4028
4095
|
var MCP_SERVER_WEBSITE = "https://comando.one";
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@comando.one/mcp-server",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Servidor MCP (Model Context Protocol) para a API pública do
|
|
3
|
+
"version": "0.8.0",
|
|
4
|
+
"description": "Servidor MCP (Model Context Protocol) para a API pública do Comando1 — opere seu ERP por linguagem natural.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"bin": {
|