@comando.one/mcp-server

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.

Instalação rápida (Claude Desktop)

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "comando": {
      "command": "npx",
      "args": ["-y", "@comando.one/mcp-server"],
      "env": {
        "COMANDO_API_KEY": "cmd_live_...",
        "COMANDO_COMPANY_ID": ""
      }
    }
  }
}

Gere sua chave em Configurações → API Keys no app. Reinicie o Claude Desktop e pronto.

Alternativa: MCP remoto (sem instalar nada)

Além deste pacote stdio, existe um endpoint MCP remoto (streaming) em https://api.comando.one/mcp (transporte MCP Streamable HTTP). Para clientes com conector remoto:

{
  "mcpServers": {
    "comando-remoto": {
      "type": "http",
      "url": "https://api.comando.one/mcp",
      "headers": { "Authorization": "Bearer cmd_live_..." }
    }
  }
}

Ambos expõem o mesmo conjunto de ferramentas (50 curadas + lookups + comando_request = cobertura total da API).

Variáveis de ambiente

| Variável | Obrigatória | Padrão | Descrição | |---|---|---|---| | COMANDO_API_KEY | sim | — | Chave cmd_live_... | | COMANDO_BASE_URL | não | https://api.comando.one/v1 | Base da API | | COMANDO_COMPANY_ID | não | empresa padrão da chave | Empresa default (X-Company-Id) |

Como funciona

• ~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.
• comando_request — escape hatch genérico (method, path, query, body) que cobre 100% dos endpoints restantes.
• lookups — catálogos read-only (centros de custo, condições/métodos de pagamento, naturezas, contas bancárias).
• whoami — identidade, empresas acessíveis e scopes da chave.

Segurança

• Scope-gating: ao iniciar, o servidor chama /me e só expõe as tools cujos scopes a chave possui.
• 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.
• Idempotência automática em POSTs (evita cobrança/pagamento duplicado); aceita idempotency_key explícito.
• Multi-empresa: qualquer tool aceita company_id para sobrescrever a empresa por chamada.

Desenvolvimento

bun install
npm run dev        # roda via tsx (stdio)
npm test           # unit (sem rede) + smoke (live, se COMANDO_API_KEY estiver setado)
npm run build      # bundle self-contained em dist/

Inspecionar com o MCP Inspector

npm run build
COMANDO_API_KEY=cmd_live_... npx @modelcontextprotocol/inspector node dist/index.js

Licença

MIT