hookshelf-mcp

Dale a tu agente de codificación un endpoint de webhook real. Un servidor MCP que permite a Claude Code, Cursor y a cualquier cliente MCP recibir webhooks, inspeccionar los bytes exactos que llegan, enviar eventos de prueba correctamente firmados para 7 proveedores y reproducir cualquier entrega — respaldado por una instancia local de hookshelf, de modo que los payloads nunca salen de tu máquina.

El problema

Pídele a un agente que «integra los webhooks de Stripe» y escribirá el manejador a ciegas. No puede recibir una entrega, así que no puede ver lo que Stripe envía realmente, no puede comprobar su verificación de firmas contra bytes reales ni descubrir si su corrección ha funcionado. La respuesta habitual — un túnel público y clics en el panel del proveedor — es exactamente lo que un agente no puede hacer.

Con este servidor, el agente cierra el bucle por sí mismo:

agent: create_endpoint(name: "stripe-dev", provider: "stripe", secret: "whsec_...")
  →  http://127.0.0.1:3000/in/f4080sjvz3v6tfd5

agent: send_test_event(endpoint_id: "f4080...")        # signed like the real thing
  →  { received: true, delivery: "a698af65..." }

agent: get_delivery(delivery_id: "a698af65...")
  →  headers as received, exact body, verification: "ok"

agent: send_test_event(endpoint_id: "f4080...", tamper: true)
  →  { error: "invalid_signature", delivery: "eb7c9d8e..." }   # failure path, also stored

Escribir el manejador → enviar el evento firmado → leer lo que llegó → corrigir → reproducir. Sin servicios de terceros, sin túnel, sin panel.

Related MCP server: hookray-mcp

Herramientas

Twilio es solo de verificación: firma la URL pública de la petición en lugar del cuerpo, por lo que únicamente el proveedor real puede generar una firma válida.

Configuración

Dos piezas: hookshelf (guarda las entregas) y este servidor (que hace las veces de manos del agente).

# 1. hookshelf
git clone https://github.com/vinkurov/hookshelf.git && cd hookshelf
docker compose up -d        # dashboard on http://127.0.0.1:3000

# 2. this server
git clone https://github.com/vinkurov/hookshelf-mcp.git && cd hookshelf-mcp
npm install && npm run build

Claude Code — .mcp.json en tu proyecto (o claude mcp add):

{
  "mcpServers": {
    "hookshelf": {
      "command": "node",
      "args": ["/path/to/hookshelf-mcp/dist/main.js"],
      "env": { "HOOKSHELF_URL": "http://127.0.0.1:3000" }
    }
  }
}

Cursor y Claude Desktop aceptan el mismo bloque command/args/env en sus ajustes de MCP. HOOKSHELF_URL usa por defecto http://127.0.0.1:3000.

Todavía no está en npm: npx hookshelf-mcp funcionará cuando se publique; este README lo dirá cuando ocurra, y no antes.

Notas que conviene saber

• Las firmas se generan a partir de las mismas especificaciones con las que verifica webhook-kit, y todas se prueban de ida y vuelta con el verificador real de webhook-kit; la generación y la verificación solo pueden divorciar si se rompen las pruebas.

• Los secretos solo viven en memoria. hookshelf guarda los secretos en modo de solo escritura, así que send_test_event funciona para endpoints creados en la sesión actual; en cualquier otro caso, el servidor lo dice en lugar de suponer.

• Una entrega rechazada se guarda igualmente. Ese es el comportamiento que define a hookshelf: no puedes dep urar una petición que has tirado. La herramienta devuelve el id de la entrega de todos modos, y el agente puede inspeccionar exactamente lo que falló.

• Los esquemas con marca temporal firma con segundos Unix, no milisegundos: una marca temporal en milisegundos produce una firma «válida» que falla la comprobación de frescura, que es el tipo de fallo que este paquete existe para cazar.

• Sin autenticación en hookshelf: mantenlo vinculado al loopback (su archivo compose ya lo hace).

Desarrollo

npm test              # 37 tests: every signature round-trips through webhook-kit's verifier
npm run test:e2e      # 11 checks against a real hookshelf instance
npm run lint && npm run typecheck

En las pruebas unitarias se conduce el servidor a través de un cliente MCP real sobre un transporte en memoria, contra un hookshelf falso cuyas respuestas se han copiado de los manejadores reales; la ejecución e2e comprueba después esas copias contra la realidad. Ya ha detectado una migración: el falso deduplicaba el entregue en endpoints de solo captura, mientras que el hookshelf real solo deduplica cuando hay reenvío (no habría nada aguas abajo que proteger en caso contrario).

Licencia

MIT — ver LICENSE.