hookshelf-mcp

Geben Sie Ihrem Coding-Agenten einen echten Webhook-Endpoint. Ein MCP-Server, der es Claude Code, Cursor und jedem MCP-Client ermöglicht, Webhooks zu empfangen, die exakt eingegangenen Bytes zu prüfen, korrekt signierte Testereignisse für 7 Anbieter zu senden und jede Zustellung erneut abzuspielen – unterstützt durch eine lokale hookshelf-Instanz, sodass Payloads Ihren Rechner nie verlassen.

Das Problem

Bitten Sie einen Agenten, „Stripe-Webhooks zu integrieren", und er schreibt den Handler blind. Er kann keine Zustellung empfangen, also kann er nicht sehen, was Stripe tatsächlich sendet, kann seine Signaturprüfung nicht gegen echte Bytes testen und kann nicht herausfinden, ob sein Fix funktioniert. Die übliche Antwort – ein öffentlicher Tunnel und das Herumklicken im Provider-Dashboard – ist genau der Teil, den ein Agent nicht erledigen kann.

Mit diesem Server schließt der Agent die Schleife selbst:

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

Handler schreiben → signiertes Ereignis senden → lesen, was angekommen ist → beheben → erneut abspielen. Kein Drittanbieterdienst, kein Tunnel, kein Dashboard.

Related MCP server: hookray-mcp

Werkzeuge

Twilio ist nur zur Verifizierung: Es signiert die öffentliche Anfrage-URL und nicht den Body, sodass nur der echte Anbieter eine gültige Signatur erzeugen kann.

Einrichtung

Zwei Teile: hookshelf (hält die Zustellungen) und dieser Server (gibt dem Agenten die Hände).

# 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 in Ihrem Projekt (oder 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 und Claude Desktop verwenden denselben command/args/env-Block in ihren MCP-Einstellungen. HOOKSHELF_URL ist standardmäßig http://127.0.0.1:3000.

Noch nicht auf npm – npx hookshelf-mcp wird funktionieren, sobald es veröffentlicht ist; dieses README wird es dann sagen, nicht vorher.

Wissenswerte Hinweise

• Signaturen werden aus denselben Spezifikationen erzeugt, gegen die webhook-kit prüft, und jede wird mit dem tatsächlichen Verifizierer von webhook-kit hin- und zurückgetestet – Erzeugung und Prüfung können nur abweichen, wenn die Tests brechen.

• Geheimnisse werden nur im Speicher gehalten. hookshelf speichert Geheimnisse nur schreibend, sodass send_test_event für Endpoints funktioniert, die in der aktuellen Sitzung erstellt wurden; für alles andere sagt der Server dies, anstatt zu raten.

• Eine abgelehnte Zustellung wird trotzdem gespeichert. Das ist das definierende Verhalten von hookshelf: Sie können keine Anfrage debuggen, die Sie verworfen haben. Das Werkzeug gibt in beiden Fällen die Zustellungs-ID zurück, und der Agent kann genau prüfen, was fehlgeschlagen ist.

• Zeitstempelbasierte Schemata signieren mit Unix-Sekunden, nicht Millisekunden – ein Millisekunden-Zeitstempel erzeugt eine „gültige" Signatur, die die Frischeprüfung nicht besteht, was die Art von Fehler ist, die dieses Paket aufdecken soll.

• Keine Authentifizierung auf hookshelf: Binden Sie es an Loopback (seine Compose-Datei tut dies bereits).

Entwicklung

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

Die Unit-Tests treiben den Server über einen echten MCP-Client über einen In-Memory-Transport mit einem Fake-hookshelf, dessen Antworten von den echten Handlern kopiert wurden – und der E2E-Lauf prüft die Kopien dann gegen die Realität. Es hat bereits eine Abweichung aufgedeckt: Das Fake hat Zustellungen bei reinen Erfassungs-Endpoints dedupliziert, das echte hookshelf dedupliziert nur beim Weiterleiten (es gibt sonst nichts stromabwärts zu schützen).

Lizenz

MIT – siehe LICENSE.