hookshelf-mcp

Дайте вашему кодирующему агенту настоящую вебхук-точку. MCP-сервер, который позволяет Claude Code, Cursor и любому MCP-клиенту получать вебхуки, просматривать точные байты, которые пришли, отправлять корректно подписанные тестовые события для 7 провайдеров и воспроизводить любую доставку — на основе локального экземпляра hookshelf, так что полезные данные никогда не покидают вашу машину.

Проблема

Попросите агента «интегрировать вебхуки Stripe» — и он напишет обработчик вслепую. Он не может получить доставку, поэтому не видит, что 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 запроса, а не тело, поэтому только реальный провайдер может создать действительную подпись.

Настройка

Две части: 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 принимают тот же блок command/args/env в своих настройках MCP. HOOKSHELF_URL по умолчанию — http://127.0.0.1:3000.

Пока не на npm — npx hookshelf-mcp заработает, когда будет опубликован; этот README сообщит об этом, когда это произойдёт, а не раньше.

Полезные заметки

• Подписи генерируются из тех же спецификаций, которые webhook-kit проверяет, и каждая из них проходит сквозное тестирование через реальный верификатор webhook-kit — генерация и проверка могут разойтись только в том случае, если тесты сломаются.

• Секреты хранятся только в памяти. hookshelf хранит секреты только для записи, поэтому send_test_event работает для конечных точек, созданных в текущем сеансе; для всего остального сервер говорит об этом, а не угадывает.

• Отклонённая доставка всё равно сохраняется. Это определяющее поведение hookshelf: вы не можете отладить запрос, который выбросили. Инструмент возвращает идентификатор доставки в любом случае, и агент может проверить, что именно не удалось.

• Схемы с метками времени подписывают в Unix-секундах, а не в миллисекундах — метка времени в миллисекундах создаёт «действительную» подпись, которая не проходит проверку свежести, а это та ошибка, для выявления которой и существует этот пакет.

• На hookshelf нет аутентификации: держите его привязанным к loopback (его 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-прогон проверяет копии на реальности. Это уже поймало одно расхождение: фейк дедуплицировал доставки на конечных точках только для захвата, а реальный hookshelf дедуплицирует только при пересылке (иначе нечего защищать ниже по потоку).

Лицензия

MIT — см. LICENSE.