CLI, MCP y skill para agentes
@chaski-ec/cli ofrece tres formas de trabajar con Chaski, y las tres usan la misma API:
- CLI: para probar desde la terminal o en CI.
- Servidor MCP: para que un agente (Claude Code, Cursor, Codex…) consulte y emita en pruebas.
- Skill: le enseña al agente a integrar Chaski correctamente.
Darle Chaski a tu agente
Sección titulada «Darle Chaski a tu agente»npx @chaski-ec/cli skill install # deja la skill en .claude/skills/chaski/claude mcp add chaski --env CHASKI_API_KEY=sk_test_… -- npx -y @chaski-ec/cli mcp{ "mcpServers": { "chaski": { "command": "npx", "args": ["-y", "@chaski-ec/cli", "mcp"], "env": { "CHASKI_API_KEY": "sk_test_…" } } }}Para la skill, npx @chaski-ec/cli skill la imprime. Cópiala donde tu agente lea sus instrucciones (por ejemplo, AGENTS.md).
Después pídele algo como «integra Chaski para facturar cada pedido pagado». Con la skill, el agente usa el SDK y la idempotencia y verifica bien los webhooks. Con el MCP, puede emitir una factura de prueba, ver la respuesta del SRI y probar tu handler de webhooks.
| Herramienta MCP | Qué hace |
|---|---|
chaski_account |
Ambiente, consumo y emisores con sus puntos de emisión. |
chaski_example_invoice |
Un body de factura válido para tu cuenta. No emite nada. |
chaski_create_invoice |
Emite una factura. Con wait: true espera la respuesta del SRI. |
chaski_get_document |
Estado y sri_messages de cualquier comprobante. |
chaski_trigger_webhook |
Envía un evento firmado a tu handler local. |
chaski_webhook_endpoints |
Endpoints registrados y, con un id, sus últimas entregas. |
chaski_test_webhook_endpoint |
Chaski manda un evento de prueba a un endpoint registrado. |
Desde la terminal
Sección titulada «Desde la terminal»npx @chaski-ec/cli login # pega tu key sk_test_ y Ctrl-Dnpx @chaski-ec/cli whoami # emisores y puntos de emisiónnpx @chaski-ec/cli init # agrega las variables a tu .envnpx @chaski-ec/cli invoices create --example --wait # factura de prueba hasta authorizednpx @chaski-ec/cli documents get inv_… --waitnpx @chaski-ec/cli webhooks trigger invoice.authorized --to http://localhost:3000/webhooks/chaskinpx @chaski-ec/cli webhooks list # endpoints registradosnpx @chaski-ec/cli webhooks get we_… # un endpoint y sus últimas entregasnpx @chaski-ec/cli webhooks test we_… # evento de prueba desde ChaskiSi lo instalas con npm install -g @chaski-ec/cli, el comando queda como chaski.
La salida es JSON. Los errores salen en stderr con la misma forma que los de la API ({ "error": { "code", "message" } }) y código de salida 1, así que puedes usarlo en scripts y en CI.
Probar webhooks en local
Sección titulada «Probar webhooks en local»webhooks trigger envía a tu servidor un evento con los mismos headers que manda Chaski (Chaski-Signature y Chaski-Event-Id), firmado con tu secreto (--secret o CHASKI_WEBHOOK_SECRET). Así compruebas tu handler sin exponer tu máquina a internet. Con --document inv_…, el evento lleva un comprobante real como data; sin esa opción, lleva datos de ejemplo.
Cuando el endpoint ya está registrado y tu servidor es público, webhooks test we_… hace que Chaski mismo le mande un evento de prueba firmado con el secreto real (por defecto, del primer tipo al que está suscrito; otro con --event). Los datos traen sample: true: tu handler debe responder 2xx e ignorarlos. webhooks get we_… muestra las últimas entregas y qué respondió tu servidor en cada una.
