@comando.one/mcp-server 0.5.1 → 0.7.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 (3) hide show
  1. package/README.md +1 -1
  2. package/dist/index.js +178 -7
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -51,7 +51,7 @@ Ambos expõem o **mesmo conjunto de ferramentas** (131 curadas + `lookups` + `co
51
51
 
52
52
  ## Como funciona
53
53
 
54
- - **131 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`, etc.
54
+ - **134 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.
package/dist/index.js CHANGED
@@ -144,6 +144,11 @@ var MANIFEST = [
144
144
  { operationId: "createInvoice", tool: "invoices_create", write: true },
145
145
  { operationId: "cancelInvoice", tool: "invoices_cancel", write: true, destructive: true },
146
146
  { operationId: "sendInvoiceSecondCopy", tool: "invoices_send", write: true },
147
+ { operationId: "setInvoiceAutoSend", tool: "invoices_set_auto_send", write: true },
148
+ { operationId: "listInvoiceCharges", tool: "invoices_list_charges" },
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 },
147
152
  { operationId: "generateContractInvoices", tool: "contracts_generate_invoices", write: true },
148
153
  // ----- Cobranças -----
149
154
  { operationId: "listCharges", tool: "charges_list" },
@@ -1154,13 +1159,13 @@ var SCHEMAS = {
1154
1159
  },
1155
1160
  InvoiceCreate: {
1156
1161
  type: "object",
1157
- required: ["customer_id"],
1162
+ required: ["customer_id", "due_date"],
1158
1163
  properties: {
1159
1164
  customer_id: { type: "string", format: "uuid" },
1160
1165
  title: { type: "string" },
1161
1166
  amount: { type: "number", description: "Ignorado se 'items' for enviado (calculado dos itens)" },
1162
1167
  status: { type: "string", enum: ["rascunho", "enviada", "aceita", "ativa"], default: "rascunho" },
1163
- due_date: { type: "string", format: "date" },
1168
+ due_date: { type: "string", format: "date", description: "Obrigat\xF3rio. A fatura nasce com uma parcela 1/1 neste vencimento \u2014 sem parcela ningu\xE9m cobra (o dispatch seleciona por parcela). O envio autom\xE1tico nasce desligado; para ligar use PATCH /v1/invoices/{id}/auto-send." },
1164
1169
  items: {
1165
1170
  type: "array",
1166
1171
  items: {
@@ -1224,7 +1229,7 @@ var SCHEMAS = {
1224
1229
  type: "object",
1225
1230
  required: ["motivo", "justificativa"],
1226
1231
  properties: {
1227
- motivo: { type: "integer", enum: [1, 2, 3, 4, 9], description: "1=n\xE3o realizada, 2=duplica\xE7\xE3o, 3=erro de emiss\xE3o, 4=servi\xE7o n\xE3o prestado, 9=outros" },
1232
+ motivo: { type: "integer", enum: [1, 2, 3, 4, 9], description: "1=erro na emiss\xE3o, 2=servi\xE7o n\xE3o prestado, 3=duplicidade de emiss\xE3o, 4=decis\xE3o judicial, 9=outros. Use o c\xF3digo pelo R\xD3TULO, n\xE3o pela ordem." },
1228
1233
  justificativa: { type: "string", minLength: 15, maxLength: 255 }
1229
1234
  }
1230
1235
  },
@@ -1827,7 +1832,7 @@ var OPENAPI_SPEC = {
1827
1832
  tags: ["Propostas"],
1828
1833
  summary: "Enviar proposta",
1829
1834
  operationId: "sendProposal",
1830
- description: "Marca a proposta como enviada.",
1835
+ description: "Apenas MUDA O STATUS da proposta para 'enviada'. N\xC3O dispara e-mail \u2014 n\xE3o existe envio de proposta por e-mail no sistema (conferido: email_schedules s\xF3 tem invoice e charge). Depois de chamar, n\xE3o afirme ao usu\xE1rio que a proposta foi enviada ao cliente.",
1831
1836
  security: [{ ApiKeyAuth: ["proposals:send"] }],
1832
1837
  responses: { "200": { description: "Proposta enviada", content: { "application/json": { schema: { $ref: "#/components/schemas/Proposal" } } } }, "404": errorResponse("Proposta n\xE3o encontrada"), "409": errorResponse("Proposta cancelada"), ...COMMON_ERRORS }
1833
1838
  }
@@ -2060,6 +2065,170 @@ var OPENAPI_SPEC = {
2060
2065
  }
2061
2066
  }
2062
2067
  },
2068
+ "/invoices/{id}/auto-send": {
2069
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
2070
+ patch: {
2071
+ tags: ["Faturas"],
2072
+ summary: "Programar a cobran\xE7a autom\xE1tica",
2073
+ operationId: "setInvoiceAutoSend",
2074
+ description: "Liga ou desliga o envio AUTOM\xC1TICO da cobran\xE7a nas parcelas em aberto da fatura. Sem isso a cobran\xE7a nunca sai sozinha: o disparo di\xE1rio s\xF3 envia com `auto_send_enabled` ligado na parcela, e a fatura criada por API nasce desligada. `days_before` = quantos dias ANTES do vencimento disparar (0 = no dia). Desligar devolve o canal para `manual`.",
2075
+ security: [{ ApiKeyAuth: ["invoices:send"] }],
2076
+ requestBody: { required: true, content: { "application/json": { schema: { type: "object", properties: {
2077
+ enabled: { type: "boolean", default: true, description: "false desliga e volta o canal para manual" },
2078
+ channel: { type: "string", enum: ["manual", "email", "whatsapp", "ambos"], default: "email", description: '"ambos" = e-mail E WhatsApp' },
2079
+ days_before: { type: "integer", minimum: 0, maximum: 90, default: 0, description: "dias ANTES do vencimento" }
2080
+ } } } } },
2081
+ responses: {
2082
+ "200": { description: "Programa\xE7\xE3o aplicada", content: { "application/json": { schema: { type: "object", properties: {
2083
+ invoice_id: { type: "string" },
2084
+ auto_send_enabled: { type: "boolean" },
2085
+ send_channel: { type: "string" },
2086
+ send_days_before: { type: "integer" },
2087
+ parcelas_afetadas: { type: "integer" }
2088
+ } } } } },
2089
+ "400": errorResponse("channel ou days_before inv\xE1lidos"),
2090
+ "404": errorResponse("Fatura n\xE3o encontrada"),
2091
+ "409": errorResponse("Fatura sem parcela em aberto"),
2092
+ ...COMMON_ERRORS
2093
+ }
2094
+ }
2095
+ },
2096
+ "/invoices/{id}/charges": {
2097
+ parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
2098
+ get: {
2099
+ tags: ["Faturas"],
2100
+ summary: "Listar as parcelas da fatura",
2101
+ operationId: "listInvoiceCharges",
2102
+ description: "As PARCELAS (invoice_charges) da fatura, com quanto j\xE1 foi pago e quanto falta em cada uma. N\xE3o confunda com `/v1/charges`, que \xE9 a cobran\xE7a do GATEWAY (Pix/boleto emitido no banco): a parcela \xE9 o que manda no vencimento e no status de pagamento da fatura. Use esta rota para descobrir o `charge_id` antes de dar baixa.",
2103
+ security: [{ ApiKeyAuth: ["invoices:read"] }],
2104
+ responses: { "200": { description: "Parcelas da fatura", content: { "application/json": { schema: { type: "object", properties: {
2105
+ invoice_id: { type: "string" },
2106
+ invoice_number: { type: "string" },
2107
+ invoice_status: { type: "string" },
2108
+ invoice_payment_status: { type: "string" },
2109
+ total: { type: "integer" },
2110
+ charges: { type: "array", items: { type: "object", properties: {
2111
+ id: { type: "string" },
2112
+ sequence: { type: "integer" },
2113
+ description: { type: "string" },
2114
+ amount: { type: "number" },
2115
+ due_date: { type: "string", format: "date" },
2116
+ payment_status: { type: "string", enum: ["pendente", "parcial", "pago", "vencido"] },
2117
+ paid_amount: { type: "number", description: "soma j\xE1 baixada nesta parcela" },
2118
+ remaining_amount: { type: "number", description: "saldo a receber" },
2119
+ auto_send_enabled: { type: "boolean" },
2120
+ send_channel: { type: "string" }
2121
+ } } }
2122
+ } } } } }, "404": errorResponse("Fatura n\xE3o encontrada"), ...COMMON_ERRORS }
2123
+ }
2124
+ },
2125
+ "/invoices/{id}/charges/{charge_id}/pay": {
2126
+ parameters: [
2127
+ { name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } },
2128
+ { name: "charge_id", in: "path", required: true, schema: { type: "string", format: "uuid" }, description: "id da PARCELA (veja GET /v1/invoices/{id}/charges)" }
2129
+ ],
2130
+ post: {
2131
+ tags: ["Faturas"],
2132
+ summary: "Dar baixa em uma parcela",
2133
+ operationId: "settleInvoiceCharge",
2134
+ description: "Registra o recebimento de uma parcela: cria o pagamento e o aloca \xE0 parcela. A parcela e a fatura passam a `pago` (ou `parcial`) pelo pr\xF3prio banco. Sem `amount`, quita o saldo restante; sem `payment_date`, usa hoje (America/Sao_Paulo). Baixa PARCIAL \xE9 permitida; acima do saldo, n\xE3o. Campo de corpo que a rota n\xE3o conhece devolve 400 em vez de ser ignorado.",
2135
+ security: [{ ApiKeyAuth: ["invoices:settle"] }],
2136
+ requestBody: { required: false, content: { "application/json": { schema: { type: "object", properties: {
2137
+ amount: { type: "number", description: "Valor recebido. Omitido, quita o saldo restante da parcela." },
2138
+ payment_date: { type: "string", format: "date", description: "Data do recebimento (YYYY-MM-DD). Padr\xE3o: hoje." },
2139
+ receipt_method_id: { type: "string", format: "uuid", description: "Forma de RECEBIMENTO (GET /v1/payment-methods). Aceita tamb\xE9m o nome `payment_method_id`." },
2140
+ bank_account_id: { type: "string", format: "uuid", description: "Conta que recebeu (GET /v1/bank-accounts)." },
2141
+ notes: { type: "string", description: "Observa\xE7\xE3o livre do pagamento." }
2142
+ } } } } },
2143
+ responses: {
2144
+ "201": { description: "Baixa registrada", content: { "application/json": { schema: { type: "object", properties: {
2145
+ payment_id: { type: "string" },
2146
+ invoice_id: { type: "string" },
2147
+ invoice_number: { type: "string" },
2148
+ invoice_payment_status: { type: "string" },
2149
+ amount: { type: "number" },
2150
+ payment_date: { type: "string", format: "date" },
2151
+ charge: { type: "object", properties: {
2152
+ id: { type: "string" },
2153
+ sequence: { type: "integer" },
2154
+ amount: { type: "number" },
2155
+ paid_amount: { type: "number" },
2156
+ remaining_amount: { type: "number" },
2157
+ payment_status: { type: "string" }
2158
+ } }
2159
+ } } } } },
2160
+ "400": errorResponse("amount, payment_date ou campo de corpo inv\xE1lido"),
2161
+ "404": errorResponse("Fatura ou parcela n\xE3o encontrada"),
2162
+ "409": errorResponse("Fatura cancelada, parcela j\xE1 quitada ou valor acima do saldo"),
2163
+ ...COMMON_ERRORS
2164
+ }
2165
+ }
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
+ },
2063
2232
  "/invoices/{id}/send": {
2064
2233
  parameters: [{ name: "id", in: "path", required: true, schema: { type: "string", format: "uuid" } }],
2065
2234
  post: {
@@ -2545,6 +2714,7 @@ var OPENAPI_SPEC = {
2545
2714
  tags: ["Relat\xF3rios"],
2546
2715
  summary: "Previs\xE3o de fluxo de caixa",
2547
2716
  operationId: "reportCashflowForecast",
2717
+ description: "Projeta o caixa dia a dia pelas parcelas em aberto. `total_inflow`/`total_outflow` e a `timeline` usam o **saldo devedor** de cada parcela (valor menos o que j\xE1 foi baixado) \u2014 \xE9 o que de fato entra e sai; `total_inflow_full`/`total_outflow_full` trazem o valor cheio. Parcela de fatura/compra **cancelada ou em rascunho** n\xE3o entra: o t\xEDtulo foi desfeito ou ainda n\xE3o foi emitido.",
2548
2718
  security: [{ ApiKeyAuth: ["finance:read"] }],
2549
2719
  parameters: [
2550
2720
  { name: "horizon_days", in: "query", schema: { type: "integer", minimum: 1, maximum: 120, default: 30 } },
@@ -2552,7 +2722,7 @@ var OPENAPI_SPEC = {
2552
2722
  { name: "include_receivables", in: "query", schema: { type: "boolean", default: true } },
2553
2723
  { name: "include_payables", in: "query", schema: { type: "boolean", default: true } }
2554
2724
  ],
2555
- responses: { "200": { description: "Proje\xE7\xE3o di\xE1ria de caixa (timeline)", content: { "application/json": { schema: { type: "object" } } } }, ...COMMON_ERRORS }
2725
+ responses: { "200": { description: "Proje\xE7\xE3o di\xE1ria de caixa (timeline). Cada linha de `receivables_preview`/`payables_preview` traz `amount` (cheio), `paid_amount` e `outstanding_amount` (o que falta).", content: { "application/json": { schema: { type: "object" } } } }, ...COMMON_ERRORS }
2556
2726
  }
2557
2727
  },
2558
2728
  // -----------------------------------------------------------------------
@@ -2578,7 +2748,7 @@ var OPENAPI_SPEC = {
2578
2748
  tags: ["NFS-e"],
2579
2749
  summary: "Emitir NFS-e",
2580
2750
  operationId: "emitNfse",
2581
- 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.",
2751
+ 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. **201** = autorizada ou em transmiss\xE3o; **422** = o fisco REJEITOU (o motivo vem em `message`) \u2014 nesse caso n\xE3o existe nota, n\xE3o afirme ao usu\xE1rio que foi emitida.",
2582
2752
  security: [{ ApiKeyAuth: ["nfse:emitir"] }],
2583
2753
  requestBody: { required: true, content: { "application/json": { schema: { $ref: "#/components/schemas/NfseEmit" } } } },
2584
2754
  responses: { "201": { description: "Emiss\xE3o solicitada", content: { "application/json": { schema: { type: "object", properties: { invoice_id: { type: "string" }, status: { type: "string" }, numero_nfse: { type: ["string", "null"] }, chave_acesso: { type: ["string", "null"] }, history_id: { type: ["string", "null"] } } } } } }, "400": errorResponse("invoice_id ausente"), "404": errorResponse("Fatura n\xE3o encontrada"), "422": errorResponse("NFS-e n\xE3o configurada"), "502": errorResponse("Erro do provedor de NFS-e"), ...COMMON_ERRORS }
@@ -2625,7 +2795,7 @@ var OPENAPI_SPEC = {
2625
2795
  tags: ["NFS-e"],
2626
2796
  summary: "URLs assinadas do XML e DANFSE",
2627
2797
  operationId: "getNfseFiles",
2628
- description: "Retorna URLs tempor\xE1rias (30 min) para download do XML e do PDF (DANFSE). Gera o PDF sob demanda se a nota estiver autorizada/cancelada.",
2798
+ description: "Retorna URLs tempor\xE1rias (30 min). `xml_signed_url` = XML autorizado. `danfse_signed_url` = DANFSe em PDF (gerada sob demanda a partir do XML se ainda n\xE3o existir). `danfse_html_signed_url` = HTML OFICIAL publicado pelo ADN, quando dispon\xEDvel \u2014 \xE9 outro documento, n\xE3o uma vers\xE3o pior do PDF. `danfse_formato` diz o que veio em `danfse_signed_url` (pdf|html).",
2629
2799
  security: [{ ApiKeyAuth: ["nfse:read"] }],
2630
2800
  responses: { "200": { description: "URLs assinadas", content: { "application/json": { schema: { type: "object", properties: { id: { type: "string" }, invoice_id: { type: "string" }, status: { type: "string" }, xml_signed_url: { type: ["string", "null"] }, danfse_signed_url: { type: ["string", "null"] }, signed_url_ttl_seconds: { type: "integer" } } } } } }, "404": errorResponse("NFS-e n\xE3o encontrada"), ...COMMON_ERRORS }
2631
2801
  }
@@ -3369,6 +3539,7 @@ var API_MODULES = [
3369
3539
  { key: "create", label: "Criar cobran\xE7a", description: "Gerar boletos, Pix e cobran\xE7as" },
3370
3540
  { key: "cancel", label: "Cancelar cobran\xE7a", description: "Cancelar cobran\xE7as em aberto" },
3371
3541
  { key: "send", label: "Enviar ao cliente", description: "Enviar segunda via da fatura por e-mail ao cliente" },
3542
+ { key: "settle", label: "Dar baixa", description: "Registrar o recebimento de uma parcela (baixa total ou parcial)" },
3372
3543
  { key: "delete", label: "Excluir fatura", description: "Excluir faturas permanentemente (itens e cobran\xE7as vinculadas)" }
3373
3544
  ]
3374
3545
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@comando.one/mcp-server",
3
- "version": "0.5.1",
3
+ "version": "0.7.0",
4
4
  "description": "Servidor MCP (Model Context Protocol) para a API pública do Comando.One — opere seu ERP por linguagem natural.",
5
5
  "type": "module",
6
6
  "license": "MIT",