shelf-smoke

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

shelf-smoke

Smoke de URL comprável por máquina para outros bots de IA. Host ativo https://shelf.kymac.co. Única entrada divulgada: este arquivo (GET /llms.txt). Não comece pela OpenAPI, MCP ou /.

Caminho somente para bots: este arquivo → obter chave → cotação → teste gratuito de smoke. Sem humano no meio do ciclo. Checkout pré-pago somente após o crédito gratuito ser gasto.

GET /health é público. Ele reporta billing (test | live | gated) e runner_ready (Playwright/Chromium consegue iniciar — não apenas processo ativo). A sondagem falha de forma fechada quando runner_ready é falso. Stripe ativo permanece bloqueado (unlock-live); hosts atuais reportam test quando segredos TEST estão presentes, caso contrário gated. Emita uma chave de chamador em POST /keys (ssm_… mostrado uma única vez). A primeira emissão concede 1 crédito gratuito (credit.grant reason=first_key). Prefira Authorization: Bearer ssm_… em rotas bloqueadas. X-API-Key: ssm_… é um alias para o mesmo segredo. A chave id é o caller_id estável para eventos de Ledger.

Sequência de instalação (sem humano no meio do ciclo):

1. GET /llms.txt (este arquivo — única entrada divulgada)
2. POST /keys — segredo ssm_… retornado uma única vez; id é caller_id. A primeira emissão concede 1 crédito gratuito.
3. Autentique com Authorization: Bearer ssm_… (X-API-Key é apenas um alias)
4. GET /credits/quote?op=smoke — cost, balance, would_succeed sem débito
5. POST /smoke contra a URL dourada https://example.com/
6. GET /credits/packs e então checkout/confirmação somente após o teste gratuito ser esgotado
7. GET /credits/balance e GET /credits/events — verdade de medição do Ledger

Prova dourada

URL conhecida como boa: https://example.com/

Todo POST /smoke HTTP 200 inclui credits_burned e credits_remaining.

Aprovado (HTTP 200; compare ok; queima 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}

Falha (HTTP 200, ok:false; executor finalizado — smokes com falha não debitam). Exemplo quando uma URL retorna 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 sempre significa que o executor finalizou — leia ok para o veredito.

Formatos de falha

Todo corpo de falha HTTP tem code, message, retryable e error (alias de message). Sem 500s de texto puro.

401 em rotas bloqueadas (WWW-Authenticate: Bearer em ambos):

• ausente: {"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 quando o smoke seria executado sem créditos suficientes:

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

400 solicitação inválida: {"code":"invalid_request","message":"…","retryable":false,"error":"…"}

404 rota desconhecida: {"code":"not_found","message":"not found","retryable":false,"error":"not found"}

500 não tratado: {"code":"internal_error","message":"…","retryable":true,"error":"…"}

504 tempo esgotado: {"code":"timeout","message":"smoke timed out","retryable":true,"error":"smoke timed out"}

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

Eventos de Ledger (somente anexação, 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 (ou derive dos eventos)

Stripe TEST somente (STRIPE_SECRET_KEY=sk_test_…). Chaves ativas falham de forma fechada (unlock-live).

MCP Streamable HTTP é POST /mcp (não é uma entrada de instalação). Descoberta de transporte para máquinas: GET /.well-known/mcp.json. Trecho de cliente copiar-e-colar: GET /mcp.json (este arquivo é o único ponteiro divulgado para o trecho; não é uma entrada de instalação). Ferramentas: issue_key, verify_key, quote_credits, list_credit_packs, checkout_credits, confirm_credits, credit_balance, credit_events, smoke, além do opcional health. smoke retorna os mesmos campos de crédito e JSON de falha que HTTP. Ferramentas bloqueadas preferem Authorization: Bearer ou env SHELF_SMOKE_API_KEY; X-API-Key é um alias. Stdio: npx tsx src/mcp-stdio.ts com SHELF_SMOKE_API_KEY.