hookshelf-mcp

코딩 에이전트에 실제 웹훅 엔드포인트를 제공하세요. Claude Code, Cursor 및 모든 MCP 클라이언트가 웹훅을 수신하고, 도착한 정확한 바이트를 검사하고, 7개 제공업체에 대해 올바르게 서명된 테스트 이벤트를 전송하고, 모든 전달을 재생할 수 있게 해주는 MCP 서버입니다. 로컬 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은 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를 반환하며 에이전트는 정확히 무엇이 실패했는지 검사할 수 있습니다.

• 타임스탬프 체계는 밀리초가 아닌 유닉스 초로 서명합니다. 밀리초 타임스탬프는 신선도 검사를 실패하는 "유효한" 서명을 생성하는데, 이는 이 패키지가 잡아내기 위해 존재하는 종류의 버그입니다.

• 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 실행은 복사본을 실제와 대조합니다. 이미 한 가지 드리프트를 잡아냈습니다. 가짜는 캡처 전용 엔드포인트에서 전달을 중복 제거했지만, 실제 hookshelf는 전달할 때만 중복 제거합니다(그렇지 않으면 보호할 다운스트림이 없음).

라이선스

MIT — LICENSE 참조.