qhook 0.5.0

Lightweight webhook gateway and workflow engine with queue, retry, and signature verification.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

# qhook MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that wraps qhook's REST API, allowing AI assistants to interact with your qhook webhook gateway.

## Prerequisites

- Node.js 18+ (uses built-in `fetch`)
- A running qhook instance

## Installation

```bash
cd mcp-server
npm install
npm run build
```

## Configuration

| Environment Variable | Description | Default |
|---|---|---|
| `QHOOK_URL` | qhook server URL | `http://localhost:8888` |
| `QHOOK_API_TOKEN` | API auth token (if `api.auth_token` is configured) | _(none)_ |

## Usage

### Claude Code

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "qhook": {
      "command": "node",
      "args": ["mcp-server/dist/index.js"],
      "env": {
        "QHOOK_URL": "http://localhost:8888"
      }
    }
  }
}
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "qhook": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "QHOOK_URL": "http://localhost:8888",
        "QHOOK_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

## Available Tools

| Tool | Description | qhook API |
|---|---|---|
| `health_check` | Check server health and queue depth | `GET /health` |
| `send_event` | Send an event to a configured source | `POST /events/{source}/{event_type}` |
| `get_event` | Get event details with jobs and workflow runs | `GET /api/events/{event_id}` |
| `get_job` | Get job details with delivery attempts | `GET /api/jobs/{job_id}` |
| `list_events` | List events with optional filters | `GET /api/events` |
| `list_jobs` | List jobs with optional filters | `GET /api/jobs` |
| `retry_job` | Retry a failed job (CLI only, not available via REST) | _N/A_ |

### Tool Details

#### `health_check`
No inputs required. Returns server status and current queue depth.

#### `send_event`
- `source` (required) — Source name as defined in qhook config (must be `type: event`)
- `event_type` (required) — Event type identifier (e.g., `order.created`)
- `payload` (required) — JSON object to send as the event body

#### `get_event`
- `event_id` (required) — Event ID (ULID)

#### `get_job`
- `job_id` (required) — Job ID (ULID)
- `include_attempts` (optional, default: `true`) — Include delivery attempt history

#### `list_events`
- `source` (optional) — Filter by source name
- `event_type` (optional) — Filter by event type
- `since` (optional) — Filter events created after this timestamp (ISO 8601)
- `until` (optional) — Filter events created before this timestamp
- `limit` (optional) — Max results (default: 50, max: 1000)

#### `list_jobs`
- `status` (optional) — Filter by status (available, running, completed, dead)
- `handler` (optional) — Filter by handler name
- `limit` (optional) — Max results (default: 50, max: 1000)

#### `retry_job`
- `job_id` (required) — Job ID (ULID) to retry

> **Note:** Retry is a CLI-only feature. This tool will return instructions to use the CLI: `qhook jobs retry <job_id>`.