@webhooks-cc/mcp 0.3.1 → 1.0.1

package/README.md

@@ -1,15 +1,20 @@
 # @webhooks-cc/mcp
 
-MCP server for [webhooks.cc](https://webhooks.cc). Connects AI coding agents to webhook endpoints — create, inspect, test, and replay webhooks through natural language.
+MCP server for [webhooks.cc](https://webhooks.cc). It gives coding agents direct access to webhook testing workflows: create endpoints, send signed test webhooks, inspect captures, compare attempts, verify signatures, and read recent webhook context through MCP resources.
 
-Works with Claude Code, Cursor, VS Code, Codex, Windsurf, and Claude Desktop.
+It works with Claude Code, Cursor, VS Code, Codex, Windsurf, and Claude Desktop.
 
 ## Install
 
+The server reads `WHK_API_KEY` from the environment. It also supports:
+
+- `WHK_BASE_URL` for a custom API base URL
+- `WHK_WEBHOOK_URL` for a custom receiver base URL
+
 ### One-click
 
-- **Cursor**: [Add to Cursor](https://cursor.com/en/install-mcp?name=webhooks-cc&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB3ZWJob29rcy1jYy9tY3AiXSwiZW52Ijp7IldIS19BUElfS0VZIjoid2hjY18uLi4ifX0=) (paste your API key after install)
-- **VS Code**: [Add to VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=webhooks-cc&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40webhooks-cc%2Fmcp%22%5D%2C%22env%22%3A%7B%22WHK_API_KEY%22%3A%22%24%7Binput%3Awhk_api_key%7D%22%7D%7D&inputs=%5B%7B%22id%22%3A%22whk_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22webhooks.cc%20API%20key%20%28get%20yours%20at%20webhooks.cc%2Faccount%29%22%2C%22password%22%3Atrue%7D%5D) (prompts for your key)
+- **Cursor**: [Add to Cursor](https://cursor.com/en/install-mcp?name=webhooks-cc&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB3ZWJob29rcy1jYy9tY3AiXSwiZW52Ijp7IldIS19BUElfS0VZIjoid2hjY18uLi4ifX0=)
+- **VS Code**: [Add to VS Code](https://insiders.vscode.dev/redirect/mcp/install?name=webhooks-cc&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40webhooks-cc%2Fmcp%22%5D%2C%22env%22%3A%7B%22WHK_API_KEY%22%3A%22%24%7Binput%3Awhk_api_key%7D%22%7D%7D&inputs=%5B%7B%22id%22%3A%22whk_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22webhooks.cc%20API%20key%20%28get%20yours%20at%20webhooks.cc%2Faccount%29%22%2C%22password%22%3Atrue%7D%5D)
 
 ### CLI
 
@@ -17,15 +22,15 @@ Works with Claude Code, Cursor, VS Code, Codex, Windsurf, and Claude Desktop.
 # Claude Code
 claude mcp add -s user --transport stdio webhooks-cc -e WHK_API_KEY=whcc_... -- npx -y @webhooks-cc/mcp
 
+# OpenAI Codex
+codex mcp add webhooks-cc -e WHK_API_KEY=whcc_... -- npx -y @webhooks-cc/mcp
+
 # Cursor
 npx @webhooks-cc/mcp setup cursor --api-key whcc_...
 
 # VS Code
 npx @webhooks-cc/mcp setup vscode --api-key whcc_...
 
-# OpenAI Codex
-codex mcp add webhooks-cc -e WHK_API_KEY=whcc_... -- npx -y @webhooks-cc/mcp
-
 # Windsurf
 npx @webhooks-cc/mcp setup windsurf --api-key whcc_...
 
@@ -33,9 +38,7 @@ npx @webhooks-cc/mcp setup windsurf --api-key whcc_...
 npx @webhooks-cc/mcp setup claude-desktop --api-key whcc_...
 ```
 
-### Manual JSON config
-
-For any tool that reads an MCP config file:
+### Manual config
 
 ```json
 {
@@ -53,47 +56,132 @@ For any tool that reads an MCP config file:
 
 Get your API key at [webhooks.cc/account](https://webhooks.cc/account).
 
-## Tools
+## What it exposes
 
-The MCP server exposes 11 tools:
+The server exposes `25` tools, `3` prompts, and `3` resource surfaces.
 
-| Tool               | Description                               |
-| ------------------ | ----------------------------------------- |
-| `create_endpoint`  | Create a new webhook endpoint             |
-| `list_endpoints`   | List all your endpoints                   |
-| `get_endpoint`     | Get details for an endpoint by slug       |
-| `update_endpoint`  | Update an endpoint name or mock response  |
-| `delete_endpoint`  | Delete an endpoint and its requests       |
-| `list_requests`    | List captured requests for an endpoint    |
-| `get_request`      | Get full details of a captured request    |
-| `send_webhook`     | Send a test webhook to an endpoint        |
-| `wait_for_request` | Wait for an incoming request (polling)    |
-| `replay_request`   | Replay a captured request to a target URL |
-| `describe`         | Describe all available SDK operations     |
+### Endpoint tools
 
-## Example conversation
+- `create_endpoint`
+- `list_endpoints`
+- `get_endpoint`
+- `update_endpoint`
+- `delete_endpoint`
+- `create_endpoints`
+- `delete_endpoints`
+
+### Request tools
+
+- `list_requests`
+- `search_requests`
+- `count_requests`
+- `get_request`
+- `wait_for_request`
+- `wait_for_requests`
+- `replay_request`
+- `compare_requests`
+- `extract_from_request`
+- `verify_signature`
+- `clear_requests`
+
+### Send and test tools
+
+- `send_webhook`
+- `send_to`
+- `preview_webhook`
+- `test_webhook_flow`
+
+### Discovery and account tools
+
+- `list_provider_templates`
+- `get_usage`
+- `describe`
+
+## Prompts
+
+The server exposes MCP prompts for common workflows:
+
+- `debug_webhook_delivery`
+- `setup_provider_testing`
+- `compare_webhook_attempts`
+
+These prompts do not execute anything on their own. They give the client a structured starting point for multi-step agent work.
+
+## Resources
 
+The server exposes MCP resources for recent webhook context:
+
+- `webhooks://endpoints`
+- `webhooks://endpoint/{slug}/recent`
+- `webhooks://request/{id}`
+
+These are useful when the client supports resource browsing or prompt/resource attachment.
+
+## Provider support
+
+Provider template and signing support includes:
+
+- `stripe`
+- `github`
+- `shopify`
+- `twilio`
+- `slack`
+- `paddle`
+- `linear`
+- `standard-webhooks`
+
+Signature verification also supports:
+
+- `discord`
+
+Use `list_provider_templates` to inspect templates, default events, signature headers, and signing requirements from the agent.
+
+## Example workflows
+
+Typical agent flows:
+
+- Create an ephemeral endpoint, send a provider-signed webhook, and wait for capture
+- Search retained requests across endpoints with full-text filters
+- Compare two webhook attempts and extract only the JSON fields you care about
+- Verify a captured signature against a known secret
+- Run `test_webhook_flow` to create, send, capture, verify, replay, and clean up in one tool call
+
+## Programmatic use
+
+The package also exports `createServer()`, `registerTools()`, `registerPrompts()`, and `registerResources()` if you want to embed the server yourself.
+
+```ts
+import { createServer } from "@webhooks-cc/mcp";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+const server = createServer({
+  apiKey: process.env.WHK_API_KEY!,
+  baseUrl: process.env.WHK_BASE_URL,
+  webhookUrl: process.env.WHK_WEBHOOK_URL,
+});
+
+await server.connect(new StdioServerTransport());
 ```
-You: "Create a webhook endpoint for testing Stripe"
-Agent: Created endpoint "stripe-test" at https://go.webhooks.cc/w/abc123
 
-You: "Set it to return 201 with {"received": true}"
-Agent: Updated mock response for stripe-test
+## Example conversation
+
+```text
+You: Create an ephemeral endpoint for GitHub webhook testing.
+
+Agent: Created endpoint https://go.webhooks.cc/w/abc123 and marked it ephemeral.
+
+You: Preview the signed request for a push event before sending it.
 
-You: "Send a test POST with a checkout.session.completed event"
-Agent: Sent POST to stripe-test with event payload
+Agent: Here is the exact method, headers, and JSON body that would be sent.
 
-You: "Show me what was captured"
-Agent: 1 request captured:
-  POST /w/abc123 — {"event": "checkout.session.completed", ...}
+You: Send it, wait for two requests, and compare them.
 
-You: "Replay that to my local server"
-Agent: Replayed to http://localhost:3000/webhooks — got 200 OK
+Agent: Sent the webhook, captured two requests, and here are the header and body differences.
 ```
 
 ## Documentation
 
-Full setup guide with interactive API key filling: [webhooks.cc/docs/mcp](https://webhooks.cc/docs/mcp)
+Full docs: [webhooks.cc/docs/mcp](https://webhooks.cc/docs/mcp)
 
 ## License