shelf-smoke

npx add-mcp 'https://shelf.kymac.co/mcp'

shelf-smoke

Prueba de humo de URL comprable por máquinas para otros bots de IA. Host en vivo https://shelf.kymac.co. Única entrada anunciada: este archivo (GET /llms.txt). No comiences en OpenAPI, MCP o /.

Ruta solo para bots: este archivo → obtener clave → cotización → prueba de humo gratuita. Sin humanos en el bucle. El pago prepagado solo ocurre después de gastar el crédito gratuito.

GET /health es público. Reporta billing (test | live | gated) y runner_ready (Playwright/Chromium puede lanzarse, no solo proceso activo). La sonda falla de forma cerrada cuando runner_ready es falso. Stripe en vivo permanece restringido (unlock-live); los hosts actuales reportan test cuando hay secretos TEST presentes, de lo contrario gated. Emite una clave de llamante en POST /keys (ssm_… se muestra una vez). La primera emisión otorga 1 crédito gratuito (credit.grant razón=first_key). Prefiere Authorization: Bearer ssm_… en rutas restringidas. X-API-Key: ssm_… es un alias para el mismo secreto. La clave id es el caller_id estable para eventos de Ledger.

Secuencia de instalación (sin humanos en el bucle):

1. GET /llms.txt (este archivo — única entrada anunciada)
2. POST /keys — el secreto ssm_… se devuelve una vez; id es caller_id. La primera emisión otorga 1 crédito gratuito.
3. Autentica con Authorization: Bearer ssm_… (X-API-Key es solo un alias)
4. GET /credits/quote?op=smoke — cost, balance, would_succeed sin débito
5. POST /smoke contra la URL dorada https://example.com/
6. GET /credits/packs y luego checkout/confirmar solo después de agotar la prueba gratuita
7. GET /credits/balance y GET /credits/events — verdad de medición del Ledger

Prueba dorada

URL conocida como válida: https://example.com/

Cada POST /smoke HTTP 200 incluye credits_burned y credits_remaining.

Éxito (HTTP 200; compara ok; consume 1 crédito):

{"ok":true,"url":"https://example.com/","viewports":[{"name":"desktop","width":1280,"url":"https://example.com/","ok":true,"status":200},{"name":"phone","width":390,"url":"https://example.com/","ok":true,"status":200}],"credits_burned":1,"credits_remaining":0}

Fallo (HTTP 200, ok:false; ejecutor terminado — las pruebas fallidas no debitan). Ejemplo cuando una URL devuelve HTTP 404:

{"ok":false,"url":"https://example.com/missing","viewports":[{"name":"desktop","width":1280,"url":"https://example.com/missing","ok":false,"status":404,"error":"HTTP 404"},{"name":"phone","width":390,"url":"https://example.com/missing","ok":false,"status":404,"error":"HTTP 404"}],"credits_burned":0,"credits_remaining":1}

HTTP 200 siempre significa que el ejecutor terminó — lee ok para el veredicto.

Formas de fallo

Cada cuerpo de fallo HTTP tiene code, message, retryable y error (alias de message). Sin 500 de texto plano.

401 en rutas restringidas (WWW-Authenticate: Bearer en ambas):

• faltante: {"code":"missing_api_key","message":"missing API key","retryable":false,"error":"missing API key"}
• inválido: {"code":"invalid_api_key","message":"invalid API key","retryable":false,"error":"invalid API key"}

402 cuando la prueba se ejecutaría sin suficientes créditos:

• {"code":"insufficient_credits","message":"insufficient credits","retryable":false,"error":"insufficient credits","caller_id":"k_…","balance":0,"required":1}

400 solicitud inválida: {"code":"invalid_request","message":"…","retryable":false,"error":"…"}

404 ruta desconocida: {"code":"not_found","message":"not found","retryable":false,"error":"not found"}

500 no manejado: {"code":"internal_error","message":"…","retryable":true,"error":"…"}

504 tiempo de espera agotado: {"code":"timeout","message":"smoke timed out","retryable":true,"error":"smoke timed out"}

503 Stripe TEST faltante: {"code":"stripe_not_configured","message":"stripe test mode not configured","retryable":true,"error":"stripe test mode not configured"}

Eventos de Ledger (solo anexar, este caller_id):

• credit.grant — caller_id, credits_added, reason (first_key), ts
• credit.purchase — caller_id, pack_id, credits_added, amount_cents, currency, stripe_payment_intent_id (TEST), ts
• credit.debit — caller_id, credits_burned, reason (smoke_success), request_id, ts
• credit.balance_snapshot (opcional) — caller_id, balance, ts (o deriva de eventos)

Solo Stripe TEST (STRIPE_SECRET_KEY=sk_test_…). Las claves en vivo fallan de forma cerrada (unlock-live).

MCP Streamable HTTP es POST /mcp (no una entrada de instalación). Descubrimiento de transporte para máquinas: GET /.well-known/mcp.json. Fragmento de cliente para copiar y pegar: GET /mcp.json (este archivo es el único puntero anunciado al fragmento; no es una entrada de instalación). Herramientas: issue_key, verify_key, quote_credits, list_credit_packs, checkout_credits, confirm_credits, credit_balance, credit_events, smoke, más health opcional. smoke devuelve los mismos campos de crédito y JSON de fallo que HTTP. Las herramientas restringidas prefieren Authorization: Bearer o env SHELF_SMOKE_API_KEY; X-API-Key es un alias. Stdio: npx tsx src/mcp-stdio.ts con SHELF_SMOKE_API_KEY.