@comando.one/mcp-server 0.1.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 +66 -0
- package/dist/index.js +2901 -0
- package/package.json +44 -0
package/README.md
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# @comando/mcp-server
|
|
2
|
+
|
|
3
|
+
Servidor **MCP (Model Context Protocol)** para a API pública do **Comando.One**. 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
|
+
|
|
5
|
+
## Instalação rápida (Claude Desktop)
|
|
6
|
+
|
|
7
|
+
Adicione ao seu `claude_desktop_config.json`:
|
|
8
|
+
|
|
9
|
+
```json
|
|
10
|
+
{
|
|
11
|
+
"mcpServers": {
|
|
12
|
+
"comando": {
|
|
13
|
+
"command": "npx",
|
|
14
|
+
"args": ["-y", "@comando/mcp-server"],
|
|
15
|
+
"env": {
|
|
16
|
+
"COMANDO_API_KEY": "cmd_live_...",
|
|
17
|
+
"COMANDO_COMPANY_ID": ""
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Gere sua chave em **Configurações → API Keys** no app. Reinicie o Claude Desktop e pronto.
|
|
25
|
+
|
|
26
|
+
## Variáveis de ambiente
|
|
27
|
+
|
|
28
|
+
| Variável | Obrigatória | Padrão | Descrição |
|
|
29
|
+
|---|---|---|---|
|
|
30
|
+
| `COMANDO_API_KEY` | sim | — | Chave `cmd_live_...` |
|
|
31
|
+
| `COMANDO_BASE_URL` | não | `https://api.comando.one/v1` | Base da API |
|
|
32
|
+
| `COMANDO_COMPANY_ID` | não | empresa padrão da chave | Empresa default (`X-Company-Id`) |
|
|
33
|
+
|
|
34
|
+
## Como funciona
|
|
35
|
+
|
|
36
|
+
- **~50 tools curadas** (gerados a partir do OpenAPI canônico, zero drift) cobrindo as operações de maior valor — `customers_list`, `invoices_create`, `charges_create`, `nfse_emit`, `payouts_create`, etc.
|
|
37
|
+
- **`comando_request`** — escape hatch genérico (`method`, `path`, `query`, `body`) que cobre 100% dos endpoints restantes.
|
|
38
|
+
- **`lookups`** — catálogos read-only (centros de custo, condições/métodos de pagamento, naturezas, contas bancárias).
|
|
39
|
+
- **`whoami`** — identidade, empresas acessíveis e scopes da chave.
|
|
40
|
+
|
|
41
|
+
### Segurança
|
|
42
|
+
|
|
43
|
+
- **Scope-gating**: ao iniciar, o servidor chama `/me` e **só expõe as tools cujos scopes a chave possui**.
|
|
44
|
+
- **Ações destrutivas** (`*_delete`, `*_cancel`, `charges_refund`, `payouts_create`) exigem `confirm: true` para executar e aceitam `dry_run: true` para pré-visualizar a requisição sem enviá-la.
|
|
45
|
+
- **Idempotência** automática em POSTs (evita cobrança/pagamento duplicado); aceita `idempotency_key` explícito.
|
|
46
|
+
- **Multi-empresa**: qualquer tool aceita `company_id` para sobrescrever a empresa por chamada.
|
|
47
|
+
|
|
48
|
+
## Desenvolvimento
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
bun install
|
|
52
|
+
npm run dev # roda via tsx (stdio)
|
|
53
|
+
npm test # unit (sem rede) + smoke (live, se COMANDO_API_KEY estiver setado)
|
|
54
|
+
npm run build # bundle self-contained em dist/
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### Inspecionar com o MCP Inspector
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npm run build
|
|
61
|
+
COMANDO_API_KEY=cmd_live_... npx @modelcontextprotocol/inspector node dist/index.js
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Licença
|
|
65
|
+
|
|
66
|
+
MIT
|