hookshelf-mcp

コーディングエージェントに実際のWebhookエンドポイントを提供します。 MCPサーバーは、Claude Code、Cursor、および任意のMCPクライアントがWebhookを受信し、到着した正確なバイト列を検査し、7つのプロバイダー向けに正しく署名されたテストイベントを送信し、任意の配信をリプレイできるようにします — バックエンドはローカルの hookshelf インスタンスなので、ペイロードがあなたのマシンから出ることはありません。

問題

エージェントに「StripeのWebhookを統合して」と頼むと、エージェントはハンドラーを盲目的に書きます。配信を受信できないため、Stripeが実際に何を送信するのかを見ることができず、実際のバイト列に対する署名検証をチェックできず、修正が機能したかどうかを確認できません。通常の解決策 — 公開トンネルとプロバイダーダッシュボードの操作 — は、まさにエージェントができない部分です。

このサーバーを使えば、エージェントは自分でループを閉じます:

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

ハンドラーを書く → 署名付きイベントを送信 → 届いた内容を読む → 修正 → リプレイ。サードパーティのサービスも、トンネルも、ダッシュボードも不要です。

Related MCP server: hookray-mcp

ツール

Twilioは検証専用です。ボディではなく公開リクエストURLに署名するため、実際のプロバイダーだけが有効な署名を生成できます。

セットアップ

2つの構成要素: hookshelf(配信を保持)とこのサーバー(エージェントに手を与える)。

# 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(または 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とClaude Desktopは、MCP設定で同じ command/args/env ブロックを使用します。HOOKSHELF_URL のデフォルトは http://127.0.0.1:3000 です。

まだnpmには公開されていません — 公開されれば npx hookshelf-mcp は動作します。このREADMEは、公開された時点でそのように記載します(それ以前には記載しません)。

知っておくべき注意点

• 署名は、webhook-kitが検証に使用するのと同じ仕様から生成され、すべての署名はwebhook-kitの実際の検証器でラウンドトリップテストされています — 生成と検証が乖離するのは、テストが壊れた場合だけです。

• シークレットはメモリ内にのみ保持されます。 hookshelfはシークレットを書き込み専用で保存するため、send_test_event は現在のセッションで作成されたエンドポイントに対してのみ機能します。それ以外の場合は、サーバーは推測せずにその旨を伝えます。

• 拒否された配信も保存されます。 これはhookshelfの特徴的な動作です。捨ててしまったリクエストはデバッグできません。ツールはどちらの場合でも配信IDを返すため、エージェントは何が失敗したかを正確に検査できます。

• タイムスタンプ付きスキームは、ミリ秒ではなくunix秒で署名します — ミリ秒のタイムスタンプは「有効な」署名を生成しますが、鮮度チェックに失敗します。これは、このパッケージが存在する目的であるバグの一種です。

• hookshelfには認証がありません。ループバックにバインドしたままにしてください(composeファイルはすでにそうなっています)。

開発

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

ユニットテストは、実際のMCPクライアントを介してインメモリトランスポート上でサーバーを駆動し、応答が実際のハンドラーからコピーされたフェイクのhookshelfに対して実行します — そしてe2e実行では、そのコピーを実際の動作と照合します。すでに1つの乖離を検出しています。フェイクはキャプチャ専用エンドポイントで配信を重複排除していましたが、実際のhookshelfは転送時のみ重複排除します(そうでなければ保護すべきダウンストリームが存在しないため)。

ライセンス

MIT — LICENSE を参照してください。