hollerpost-mcp 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +230 -0
- package/dist/client.d.ts +49 -0
- package/dist/client.js +163 -0
- package/dist/format.d.ts +25 -0
- package/dist/format.js +142 -0
- package/dist/prompts.d.ts +15 -0
- package/dist/prompts.js +122 -0
- package/dist/resources.d.ts +13 -0
- package/dist/resources.js +72 -0
- package/dist/server.d.ts +7 -0
- package/dist/server.js +23 -0
- package/dist/stdio.d.ts +2 -0
- package/dist/stdio.js +27 -0
- package/dist/tools.d.ts +25 -0
- package/dist/tools.js +562 -0
- package/dist/version.d.ts +1 -0
- package/dist/version.js +2 -0
- package/package.json +48 -0
package/README.md
ADDED
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
# hollerpost-mcp
|
|
2
|
+
|
|
3
|
+
Bring your own AI to Hollerpost. This is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets an agent you already use (Claude, ChatGPT, Cursor, n8n, anything that speaks MCP) work inside your Hollerpost workspace: set up a sending domain, add contacts who opted in, draft on-brand campaigns, preview and test them, schedule them once you say yes, and report on results. Hollerpost runs no AI of its own here. Your agent does the writing; Hollerpost does the rendering, the compliance footer and the sending.
|
|
4
|
+
|
|
5
|
+
Everything goes through the public API at `https://api.hollerpost.com/api/v1` with your workspace API key, so the same scopes, rate limit (600 requests per minute per key), quotas and first-campaign review apply.
|
|
6
|
+
|
|
7
|
+
- Remote server: `https://mcp.hollerpost.com/mcp` (Streamable HTTP)
|
|
8
|
+
- Local server: `npx -y hollerpost-mcp` (stdio, key in `HOLLERPOST_KEY`)
|
|
9
|
+
|
|
10
|
+
Create a key in the Hollerpost Dashboard under **Settings, Developer API**. Keys look like `hp_live_...`. Treat a key like a password.
|
|
11
|
+
|
|
12
|
+
## Connect
|
|
13
|
+
|
|
14
|
+
### Claude Desktop (local, recommended)
|
|
15
|
+
|
|
16
|
+
Edit `claude_desktop_config.json` (Settings, Developer, Edit Config) and restart Claude Desktop:
|
|
17
|
+
|
|
18
|
+
```json
|
|
19
|
+
{
|
|
20
|
+
"mcpServers": {
|
|
21
|
+
"hollerpost": {
|
|
22
|
+
"command": "npx",
|
|
23
|
+
"args": ["-y", "hollerpost-mcp"],
|
|
24
|
+
"env": { "HOLLERPOST_KEY": "hp_live_your_key_here" }
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Needs Node.js 20 or newer.
|
|
31
|
+
|
|
32
|
+
### Claude.ai and Claude Desktop connectors (remote)
|
|
33
|
+
|
|
34
|
+
Settings, Connectors, Add custom connector. Connectors cannot send a custom header yet, so put the key in the URL:
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
https://mcp.hollerpost.com/mcp?key=hp_live_your_key_here
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
The URL now contains your key: do not share it or paste it anywhere else. Revoke the key in the dashboard if it leaks. (Click-to-connect OAuth is planned; see "Later".)
|
|
41
|
+
|
|
42
|
+
### ChatGPT
|
|
43
|
+
|
|
44
|
+
In ChatGPT settings, open Apps and Connectors, turn on developer mode under Advanced, then create a connector. Use the same URL with `?key=` as above and choose no authentication.
|
|
45
|
+
|
|
46
|
+
### Cursor
|
|
47
|
+
|
|
48
|
+
`~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project). Remote, with the key in a header:
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"mcpServers": {
|
|
53
|
+
"hollerpost": {
|
|
54
|
+
"url": "https://mcp.hollerpost.com/mcp",
|
|
55
|
+
"headers": { "Authorization": "Bearer hp_live_your_key_here" }
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Or local:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"mcpServers": {
|
|
66
|
+
"hollerpost": {
|
|
67
|
+
"command": "npx",
|
|
68
|
+
"args": ["-y", "hollerpost-mcp"],
|
|
69
|
+
"env": { "HOLLERPOST_KEY": "hp_live_your_key_here" }
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
### Claude Code
|
|
76
|
+
|
|
77
|
+
```sh
|
|
78
|
+
claude mcp add --transport http hollerpost https://mcp.hollerpost.com/mcp --header "Authorization: Bearer hp_live_your_key_here"
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Anything else
|
|
82
|
+
|
|
83
|
+
Point any Streamable HTTP MCP client at `https://mcp.hollerpost.com/mcp` with the header `Authorization: Bearer hp_live_...`. If the client cannot set headers, add `?key=hp_live_...` to the URL instead.
|
|
84
|
+
|
|
85
|
+
## First thing to try
|
|
86
|
+
|
|
87
|
+
Pick the `setup_workspace` prompt in your client (or just ask "set up my Hollerpost workspace"). The agent checks your account, adds your sending domain and hands you the DNS records (or adds them itself if you have a DNS tool such as a Cloudflare MCP connected), verifies the domain, saves your brand voice, imports the first contacts you paste with consent confirmed, drafts a welcome campaign and stops before scheduling.
|
|
88
|
+
|
|
89
|
+
## Scopes
|
|
90
|
+
|
|
91
|
+
Each API key carries scopes. Pick only what the tool you connect needs.
|
|
92
|
+
|
|
93
|
+
| Scope | Allows |
|
|
94
|
+
|---|---|
|
|
95
|
+
| `read` | Reading everything: workspace, brand, templates, segments, contacts, campaigns, stats, events, account, domains |
|
|
96
|
+
| `contacts` | Adding contacts (`contacts_add`) |
|
|
97
|
+
| `draft` | Creating and editing drafts, previews, test sends, saving the brand voice |
|
|
98
|
+
| `send` | Scheduling and canceling campaigns, sending transactional email |
|
|
99
|
+
| `webhooks` | Webhook management (not used by this server) |
|
|
100
|
+
| `account` | Account details, sending domains, the billing portal link |
|
|
101
|
+
|
|
102
|
+
New keys get `read`, `contacts`, `draft` and `account` by default.
|
|
103
|
+
|
|
104
|
+
> **About `send`:** it lets a key schedule campaigns to your whole list. Only turn it on for tools you trust. Without it, an agent can do everything up to a ready, tested draft, and you schedule from the dashboard.
|
|
105
|
+
|
|
106
|
+
If a tool needs a scope the key lacks, the tool answers `insufficient_scope`, names the missing scope, and changes nothing. The workspace owner can enable it in Dashboard, Settings, Developer API.
|
|
107
|
+
|
|
108
|
+
## Tools
|
|
109
|
+
|
|
110
|
+
| Tool | Scope | What it does |
|
|
111
|
+
|---|---|---|
|
|
112
|
+
| `workspace_info` | read | Who this key is: workspace, plan, trial, scopes, brand. Start here |
|
|
113
|
+
| `brand_get` | read | Brand settings and writing voice |
|
|
114
|
+
| `brand_set_voice` | draft | Save the brand voice notes (replaces the old text) |
|
|
115
|
+
| `templates_list` | read | Templates and the content blocks each accepts |
|
|
116
|
+
| `segments_list` | read | Tags with subscribed counts, for choosing an audience |
|
|
117
|
+
| `contacts_search` | read | Find contacts by email, status or tag |
|
|
118
|
+
| `contacts_add` | contacts | Add one contact who opted in (`consent: true` required) |
|
|
119
|
+
| `campaign_draft` | draft | Create a draft from a template, content blocks and an audience. Sends nothing |
|
|
120
|
+
| `campaign_update` | draft | Edit a draft |
|
|
121
|
+
| `campaign_preview` | draft | Rendered text, live audience count, quota after sending, warnings |
|
|
122
|
+
| `campaign_send_test` | draft | Test copy to up to 3 workspace users |
|
|
123
|
+
| `campaign_schedule` | send | Schedule a draft (`confirm: true` and `expected_audience_count` required) |
|
|
124
|
+
| `campaign_cancel` | send | Cancel a scheduled campaign before it starts sending |
|
|
125
|
+
| `campaigns_list` | read | List campaigns by status |
|
|
126
|
+
| `campaign_stats` | read | Delivered, opens, clicks, bounces, unsubscribes, top links |
|
|
127
|
+
| `email_send` | send | One transactional email (receipt, reply). `idempotency_key` required |
|
|
128
|
+
| `events_recent` | read | Recent bounces, complaints or deliveries |
|
|
129
|
+
| `account_get` | read | Plan, quota, trial, period end, send packs |
|
|
130
|
+
| `account_update` | account | Workspace name, from name, reply-to, footer address |
|
|
131
|
+
| `domain_add` | account | Add the sending domain; returns the DNS records and a registrar hint |
|
|
132
|
+
| `domain_list` | read | Sending domain status and per-record checks |
|
|
133
|
+
| `domain_verify` | account | Re-check DNS now; expected vs actual for every record |
|
|
134
|
+
| `domain_remove` | account | Remove the sending domain (`confirm: true` required) |
|
|
135
|
+
| `billing_portal_link` | account | A short-lived Stripe portal link for the person to open |
|
|
136
|
+
|
|
137
|
+
Resources (context a client can attach without a tool call): `hollerpost://brand`, `hollerpost://templates`, `hollerpost://quota`, `hollerpost://domains`.
|
|
138
|
+
|
|
139
|
+
Prompts: `setup_workspace`, `write_campaign`, `weekly_report`, `fix_domain`, `clean_list`.
|
|
140
|
+
|
|
141
|
+
## Safety rules
|
|
142
|
+
|
|
143
|
+
These are built into the server and the API, not left to the agent:
|
|
144
|
+
|
|
145
|
+
- **Preview before schedule.** Campaigns are always created as drafts. The `campaign_schedule` description tells the agent to run `campaign_preview`, tell you the audience count and quota use, and wait for your yes.
|
|
146
|
+
- **Audience count check.** `campaign_schedule` must pass the count you were shown. If the live audience differs by more than 5% the API refuses (`audience_changed`) and the agent has to ask again.
|
|
147
|
+
- **Literal confirmations.** `confirm` on `campaign_schedule` and `domain_remove`, and `consent` on `contacts_add`, must be the literal value `true`; the call cannot be formed without them.
|
|
148
|
+
- **First campaign review.** A new workspace's first campaign is held for a one-time human review by the Hollerpost team. `campaign_schedule` then reports `review_pending`, says plainly that nothing was sent, and tells the agent not to retry.
|
|
149
|
+
- **Consent.** Contacts can only be added with `consent: true`, and addresses that unsubscribed, bounced or complained can never be re-added.
|
|
150
|
+
- **No money moves.** No tool changes a plan, buys a send pack or touches a card. `billing_portal_link` hands back a URL for you to open in your browser. This is a permanent rule.
|
|
151
|
+
- **Almost nothing destructive.** There is no contact delete, campaign delete or webhook delete. The only destructive tool is `domain_remove` (needs `confirm: true`, refused while a campaign is scheduled on the domain). `campaign_cancel` is the undo for a scheduled send.
|
|
152
|
+
- **Quota.** A send larger than the remaining monthly quota is refused with `quota_exceeded`, with a link where you can buy a send pack yourself.
|
|
153
|
+
- **Your key stays yours.** The remote server forwards your `Authorization` header to the API on each request and stores nothing. Keys are never echoed in tool output and never logged; anything shaped like a key is redacted from output even if the API were to return it.
|
|
154
|
+
|
|
155
|
+
## Behavior details
|
|
156
|
+
|
|
157
|
+
- A `429` from the API is retried once after `Retry-After` (up to 30 seconds), then reported as `rate_limited`.
|
|
158
|
+
- List results are cut to 50 rows in the text the agent reads; the full API JSON is always in `structuredContent`.
|
|
159
|
+
- Every API error comes back as a tool error (`isError: true`) with a plain sentence naming the API code, for example `Hollerpost API error "insufficient_scope" (HTTP 403)`. Never a stack trace.
|
|
160
|
+
- Every API call sends `User-Agent: hollerpost-mcp/<version> (worker)` or `(stdio)`, so MCP traffic is visible separately in API logs.
|
|
161
|
+
|
|
162
|
+
## Why the remote server is stateless
|
|
163
|
+
|
|
164
|
+
The remote Worker serves Streamable HTTP with the MCP SDK's own `WebStandardStreamableHTTPServerTransport` in stateless mode (no session ids, JSON responses, a fresh server per request). It does not use Cloudflare's `McpAgent`. Reasons, checked against the docs in October 2026:
|
|
165
|
+
|
|
166
|
+
1. `McpAgent` is deprecated in `agents` 0.26. It also needs a Durable Object binding plus migrations, and it pins `@modelcontextprotocol/sdk` to exactly 1.30.0 as a peer.
|
|
167
|
+
2. Cloudflare's replacement, `createMcpHandler` from `agents/mcp`, now only accepts servers built with the split SDK v2 package `@modelcontextprotocol/server`, not `@modelcontextprotocol/sdk`. That would mean two different MCP SDKs for the Worker and the npx package, or moving both to v2.
|
|
168
|
+
3. This server has no per-session state worth keeping. The only thing that identifies a caller is their API key, which arrives on every request and must never be stored. A Durable Object would add cost and a place where a key could end up persisted, for no benefit.
|
|
169
|
+
|
|
170
|
+
The stateless transport is part of `@modelcontextprotocol/sdk` itself, works on Workers with `nodejs_compat`, and accepts every protocol revision the SDK supports. `GET` and `DELETE` on `/mcp` answer 405, which the spec allows for servers without a standalone SSE stream or sessions. If the stack moves to MCP SDK v2 later, `src/server.ts` is the only file that needs to change shape: swap in `createMcpHandler(factory)` and keep the tools as they are.
|
|
171
|
+
|
|
172
|
+
### About `?key=`
|
|
173
|
+
|
|
174
|
+
The plan asks for `?key=` to be accepted only on the initial handshake. In a stateless server there is no session to carry the key from the handshake to later calls without storing it, and clients that cannot set headers repeat the same URL (with the key) on every request anyway. So the Worker accepts `?key=` on any `POST /mcp` that has no `Authorization` header, validates its format, removes it from the URL before the MCP transport sees the request, and never logs it: the Worker's own log line drops it, and Cloudflare invocation logs (which record the full URL) are turned off in `wrangler.jsonc`. The header is still the better choice where a client supports it, because URLs can end up in client-side history and in Cloudflare's live tail.
|
|
175
|
+
|
|
176
|
+
## Development
|
|
177
|
+
|
|
178
|
+
```sh
|
|
179
|
+
npm install
|
|
180
|
+
npm test # vitest: tool mapping, error mapping, 429 retry, truncation, key secrecy, worker, stdio
|
|
181
|
+
npm run typecheck
|
|
182
|
+
npm run build # dist/ for the npx package
|
|
183
|
+
npm run dev # wrangler dev (local Worker on http://localhost:8787/mcp)
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
`wrangler dev` and `wrangler deploy` must be given the config explicitly from this folder (`npx wrangler dev -c wrangler.jsonc`), because the app repo root has its own `.wrangler/deploy/config.json`.
|
|
187
|
+
|
|
188
|
+
Inspect with the MCP Inspector CLI (put the target first, then the flags):
|
|
189
|
+
|
|
190
|
+
```sh
|
|
191
|
+
npm run build
|
|
192
|
+
npx @modelcontextprotocol/inspector@2.9.0 --cli node dist/stdio.js -e HOLLERPOST_KEY=hp_live_dummy --method tools/list --strict
|
|
193
|
+
npx @modelcontextprotocol/inspector@2.9.0 --cli node dist/stdio.js -e HOLLERPOST_KEY=hp_live_dummy --method resources/list
|
|
194
|
+
npx @modelcontextprotocol/inspector@2.9.0 --cli node dist/stdio.js -e HOLLERPOST_KEY=hp_live_dummy --method prompts/list
|
|
195
|
+
npx @modelcontextprotocol/inspector@2.9.0 --cli http://localhost:8787/mcp --header "Authorization: Bearer hp_live_dummy" --method tools/list --strict
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
`HOLLERPOST_API_BASE` overrides the API base URL (stdio env var, or the Worker var in `wrangler.jsonc`) for staging.
|
|
199
|
+
|
|
200
|
+
### End-to-end test
|
|
201
|
+
|
|
202
|
+
`test/e2e.ts` runs the full flow against a real staging workspace: `account_get`, `domain_add`, DNS records added through the Cloudflare API, `domain_verify` until verified, `campaign_draft`, `campaign_preview`, `campaign_send_test`, `campaign_schedule` for ten minutes out, `campaign_cancel`, `domain_remove`, and cleanup of the DNS records. It is not part of `npm test`.
|
|
203
|
+
|
|
204
|
+
```sh
|
|
205
|
+
HOLLERPOST_KEY=hp_live_... \
|
|
206
|
+
HOLLERPOST_TEST_DOMAIN=mcp-e2e.yourzone.com \
|
|
207
|
+
HOLLERPOST_TEST_TO=you@yourworkspace.com \
|
|
208
|
+
CLOUDFLARE_API_TOKEN=... CLOUDFLARE_ZONE_ID=... \
|
|
209
|
+
npm run e2e
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Add `HOLLERPOST_MCP_URL=https://mcp.hollerpost.com/mcp` to go through the deployed Worker, and `HOLLERPOST_NOSEND_KEY=hp_live_...` (a key without `send`) to check the `insufficient_scope` path. See the header of the script for every option.
|
|
213
|
+
|
|
214
|
+
## Layout
|
|
215
|
+
|
|
216
|
+
```
|
|
217
|
+
src/tools.ts the 24 tools: schemas, descriptions, handlers (transport agnostic)
|
|
218
|
+
src/client.ts fetch wrapper: auth passthrough, 429 retry, User-Agent, key redaction
|
|
219
|
+
src/format.ts tool results, 50-row truncation, API error messages
|
|
220
|
+
src/resources.ts hollerpost://brand, templates, quota, domains
|
|
221
|
+
src/prompts.ts setup_workspace, write_campaign, weekly_report, fix_domain, clean_list
|
|
222
|
+
src/server.ts builds the McpServer for either transport
|
|
223
|
+
src/worker.ts Cloudflare Worker: stateless Streamable HTTP at /mcp
|
|
224
|
+
src/stdio.ts npx entry: stdio, HOLLERPOST_KEY
|
|
225
|
+
wrangler.jsonc Worker hollerpost-mcp on mcp.hollerpost.com
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
## Later
|
|
229
|
+
|
|
230
|
+
OAuth 2.1 click-to-connect for Claude.ai and ChatGPT connectors, segment builder tools, SMS tools, automations, and contact delete or unsubscribe tools (each behind a literal `confirm: true`).
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
export type TransportKind = 'worker' | 'stdio';
|
|
2
|
+
export declare const DEFAULT_API_BASE = "https://api.hollerpost.com/api/v1";
|
|
3
|
+
/** Longest Retry-After we are willing to sleep through inside one tool call. */
|
|
4
|
+
export declare const MAX_RETRY_WAIT_MS = 30000;
|
|
5
|
+
export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
|
|
6
|
+
export interface ClientOptions {
|
|
7
|
+
/** Full Authorization header value, e.g. "Bearer hp_live_...". */
|
|
8
|
+
authorization?: string | null;
|
|
9
|
+
transport: TransportKind;
|
|
10
|
+
baseUrl?: string;
|
|
11
|
+
fetch?: FetchLike;
|
|
12
|
+
/** Injected for tests. */
|
|
13
|
+
sleep?: (ms: number) => Promise<void>;
|
|
14
|
+
}
|
|
15
|
+
export interface RequestOptions {
|
|
16
|
+
query?: Record<string, string | number | boolean | undefined | null>;
|
|
17
|
+
body?: unknown;
|
|
18
|
+
headers?: Record<string, string>;
|
|
19
|
+
}
|
|
20
|
+
/** An API failure, already reduced to the API's `{"error": "code", ...}` shape. */
|
|
21
|
+
export declare class ApiError extends Error {
|
|
22
|
+
readonly status: number;
|
|
23
|
+
readonly code: string;
|
|
24
|
+
readonly body: Record<string, unknown>;
|
|
25
|
+
/** True when the error was raised here before any request went out. */
|
|
26
|
+
readonly local: boolean;
|
|
27
|
+
constructor(status: number, code: string, body?: Record<string, unknown>, local?: boolean);
|
|
28
|
+
}
|
|
29
|
+
/** Replace anything that looks like a Hollerpost key with a fixed marker. */
|
|
30
|
+
export declare function redactString(text: string, secrets?: string[]): string;
|
|
31
|
+
/** Deep copy of a JSON value with every string passed through redactString. */
|
|
32
|
+
export declare function redactDeep<T>(value: T, secrets?: string[]): T;
|
|
33
|
+
/** Parse Retry-After (delta seconds or HTTP date) into milliseconds. */
|
|
34
|
+
export declare function parseRetryAfter(header: string | null, now?: number): number | null;
|
|
35
|
+
export declare class HollerpostClient {
|
|
36
|
+
readonly transport: TransportKind;
|
|
37
|
+
private readonly authorization;
|
|
38
|
+
private readonly baseUrl;
|
|
39
|
+
private readonly fetchImpl;
|
|
40
|
+
private readonly sleep;
|
|
41
|
+
constructor(opts: ClientOptions);
|
|
42
|
+
get userAgent(): string;
|
|
43
|
+
/** Strings that must never appear in output: the raw key and the header. */
|
|
44
|
+
get secrets(): string[];
|
|
45
|
+
hasKey(): boolean;
|
|
46
|
+
request<T = unknown>(method: string, path: string, opts?: RequestOptions): Promise<T>;
|
|
47
|
+
private send;
|
|
48
|
+
private parse;
|
|
49
|
+
}
|
package/dist/client.js
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
// Tiny fetch wrapper for the Hollerpost public API.
|
|
2
|
+
//
|
|
3
|
+
// Rules this file enforces for every transport:
|
|
4
|
+
// - The Authorization header is passed through exactly as given (remote) or
|
|
5
|
+
// built from HOLLERPOST_KEY (stdio). It is never logged or echoed.
|
|
6
|
+
// - A 429 is retried once, honoring Retry-After, then surfaced.
|
|
7
|
+
// - Every call carries `User-Agent: hollerpost-mcp/<version> (<transport>)`.
|
|
8
|
+
// - Failures become ApiError with the API's `error` code, never a raw stack.
|
|
9
|
+
import { VERSION } from './version.js';
|
|
10
|
+
export const DEFAULT_API_BASE = 'https://api.hollerpost.com/api/v1';
|
|
11
|
+
/** Longest Retry-After we are willing to sleep through inside one tool call. */
|
|
12
|
+
export const MAX_RETRY_WAIT_MS = 30_000;
|
|
13
|
+
/** An API failure, already reduced to the API's `{"error": "code", ...}` shape. */
|
|
14
|
+
export class ApiError extends Error {
|
|
15
|
+
status;
|
|
16
|
+
code;
|
|
17
|
+
body;
|
|
18
|
+
/** True when the error was raised here before any request went out. */
|
|
19
|
+
local;
|
|
20
|
+
constructor(status, code, body = {}, local = false) {
|
|
21
|
+
super(code);
|
|
22
|
+
this.name = 'ApiError';
|
|
23
|
+
this.status = status;
|
|
24
|
+
this.code = code;
|
|
25
|
+
this.body = body;
|
|
26
|
+
this.local = local;
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
const KEY_PATTERN = /\b(hp|uc)_(live|test)_[A-Za-z0-9_\-]+/g;
|
|
30
|
+
/** Replace anything that looks like a Hollerpost key with a fixed marker. */
|
|
31
|
+
export function redactString(text, secrets = []) {
|
|
32
|
+
let out = text.replace(KEY_PATTERN, '[redacted key]');
|
|
33
|
+
for (const s of secrets) {
|
|
34
|
+
if (s && s.length >= 6)
|
|
35
|
+
out = out.split(s).join('[redacted key]');
|
|
36
|
+
}
|
|
37
|
+
return out;
|
|
38
|
+
}
|
|
39
|
+
/** Deep copy of a JSON value with every string passed through redactString. */
|
|
40
|
+
export function redactDeep(value, secrets = []) {
|
|
41
|
+
if (typeof value === 'string')
|
|
42
|
+
return redactString(value, secrets);
|
|
43
|
+
if (Array.isArray(value))
|
|
44
|
+
return value.map((v) => redactDeep(v, secrets));
|
|
45
|
+
if (value && typeof value === 'object') {
|
|
46
|
+
const out = {};
|
|
47
|
+
for (const [k, v] of Object.entries(value)) {
|
|
48
|
+
out[k] = redactDeep(v, secrets);
|
|
49
|
+
}
|
|
50
|
+
return out;
|
|
51
|
+
}
|
|
52
|
+
return value;
|
|
53
|
+
}
|
|
54
|
+
/** Parse Retry-After (delta seconds or HTTP date) into milliseconds. */
|
|
55
|
+
export function parseRetryAfter(header, now = Date.now()) {
|
|
56
|
+
if (!header)
|
|
57
|
+
return null;
|
|
58
|
+
const trimmed = header.trim();
|
|
59
|
+
if (/^\d+(\.\d+)?$/.test(trimmed))
|
|
60
|
+
return Math.round(parseFloat(trimmed) * 1000);
|
|
61
|
+
const at = Date.parse(trimmed);
|
|
62
|
+
if (Number.isNaN(at))
|
|
63
|
+
return null;
|
|
64
|
+
return Math.max(0, at - now);
|
|
65
|
+
}
|
|
66
|
+
const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
67
|
+
export class HollerpostClient {
|
|
68
|
+
transport;
|
|
69
|
+
authorization;
|
|
70
|
+
baseUrl;
|
|
71
|
+
fetchImpl;
|
|
72
|
+
sleep;
|
|
73
|
+
constructor(opts) {
|
|
74
|
+
this.transport = opts.transport;
|
|
75
|
+
this.authorization = opts.authorization?.trim() || null;
|
|
76
|
+
this.baseUrl = (opts.baseUrl || DEFAULT_API_BASE).replace(/\/+$/, '');
|
|
77
|
+
this.fetchImpl = opts.fetch ?? ((input, init) => fetch(input, init));
|
|
78
|
+
this.sleep = opts.sleep ?? defaultSleep;
|
|
79
|
+
}
|
|
80
|
+
get userAgent() {
|
|
81
|
+
return `hollerpost-mcp/${VERSION} (${this.transport})`;
|
|
82
|
+
}
|
|
83
|
+
/** Strings that must never appear in output: the raw key and the header. */
|
|
84
|
+
get secrets() {
|
|
85
|
+
if (!this.authorization)
|
|
86
|
+
return [];
|
|
87
|
+
const token = this.authorization.replace(/^Bearer\s+/i, '');
|
|
88
|
+
const bare = token.replace(/^(hp|uc)_(live|test)_/, '');
|
|
89
|
+
return [this.authorization, token, ...(bare.length >= 12 ? [bare] : [])];
|
|
90
|
+
}
|
|
91
|
+
hasKey() {
|
|
92
|
+
return !!this.authorization;
|
|
93
|
+
}
|
|
94
|
+
async request(method, path, opts = {}) {
|
|
95
|
+
if (!this.authorization) {
|
|
96
|
+
throw new ApiError(401, 'missing_api_key', {}, true);
|
|
97
|
+
}
|
|
98
|
+
const url = new URL(this.baseUrl + path);
|
|
99
|
+
for (const [k, v] of Object.entries(opts.query ?? {})) {
|
|
100
|
+
if (v !== undefined && v !== null && v !== '')
|
|
101
|
+
url.searchParams.set(k, String(v));
|
|
102
|
+
}
|
|
103
|
+
const headers = {
|
|
104
|
+
Authorization: this.authorization,
|
|
105
|
+
Accept: 'application/json',
|
|
106
|
+
'User-Agent': this.userAgent,
|
|
107
|
+
...(opts.headers ?? {}),
|
|
108
|
+
};
|
|
109
|
+
const init = { method, headers };
|
|
110
|
+
if (opts.body !== undefined) {
|
|
111
|
+
headers['Content-Type'] = 'application/json';
|
|
112
|
+
init.body = JSON.stringify(opts.body);
|
|
113
|
+
}
|
|
114
|
+
let res = await this.send(url.toString(), init);
|
|
115
|
+
if (res.status === 429) {
|
|
116
|
+
const wait = parseRetryAfter(res.headers.get('retry-after')) ?? 1000;
|
|
117
|
+
if (wait <= MAX_RETRY_WAIT_MS) {
|
|
118
|
+
await res.body?.cancel().catch(() => { });
|
|
119
|
+
await this.sleep(wait);
|
|
120
|
+
res = await this.send(url.toString(), init);
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
return this.parse(res);
|
|
124
|
+
}
|
|
125
|
+
async send(url, init) {
|
|
126
|
+
try {
|
|
127
|
+
return await this.fetchImpl(url, init);
|
|
128
|
+
}
|
|
129
|
+
catch {
|
|
130
|
+
// Network failure. Do not surface the underlying error text: it can
|
|
131
|
+
// include the URL and is never useful to the agent.
|
|
132
|
+
throw new ApiError(0, 'network_error', {}, true);
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
async parse(res) {
|
|
136
|
+
const text = await res.text().catch(() => '');
|
|
137
|
+
let json = undefined;
|
|
138
|
+
if (text) {
|
|
139
|
+
try {
|
|
140
|
+
json = JSON.parse(text);
|
|
141
|
+
}
|
|
142
|
+
catch {
|
|
143
|
+
json = undefined;
|
|
144
|
+
}
|
|
145
|
+
}
|
|
146
|
+
if (res.ok) {
|
|
147
|
+
if (json === undefined)
|
|
148
|
+
return {};
|
|
149
|
+
return json;
|
|
150
|
+
}
|
|
151
|
+
const body = json && typeof json === 'object' && !Array.isArray(json) ? json : {};
|
|
152
|
+
let code = typeof body.error === 'string' && body.error ? body.error : `http_${res.status}`;
|
|
153
|
+
if (res.status === 429 && !body.error)
|
|
154
|
+
code = 'rate_limited';
|
|
155
|
+
if (res.status === 429) {
|
|
156
|
+
const ra = parseRetryAfter(res.headers.get('retry-after'));
|
|
157
|
+
if (ra !== null && body.retry_after_seconds === undefined) {
|
|
158
|
+
body.retry_after_seconds = Math.ceil(ra / 1000);
|
|
159
|
+
}
|
|
160
|
+
}
|
|
161
|
+
throw new ApiError(res.status, code, body);
|
|
162
|
+
}
|
|
163
|
+
}
|
package/dist/format.d.ts
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
|
|
2
|
+
import { ApiError } from './client.js';
|
|
3
|
+
export declare const TEXT_ROW_LIMIT = 50;
|
|
4
|
+
export declare const SCOPE_SETTINGS_HINT = "The workspace owner can enable it in the Hollerpost Dashboard under Settings, Developer API (edit the key, or create a new key with that scope).";
|
|
5
|
+
interface TruncationNote {
|
|
6
|
+
path: string;
|
|
7
|
+
shown: number;
|
|
8
|
+
total: number;
|
|
9
|
+
}
|
|
10
|
+
/** Copy `value`, cutting every array longer than `limit` down to `limit`. */
|
|
11
|
+
export declare function truncateLists(value: unknown, limit?: number): {
|
|
12
|
+
view: unknown;
|
|
13
|
+
notes: TruncationNote[];
|
|
14
|
+
};
|
|
15
|
+
/** structuredContent must be a JSON object; wrap anything else. */
|
|
16
|
+
export declare function asObject(data: unknown): Record<string, unknown>;
|
|
17
|
+
export declare function okResult(lead: string, data: unknown, secrets?: string[]): CallToolResult;
|
|
18
|
+
/** Plain-language explanation for each API error code the tools can hit. */
|
|
19
|
+
export declare function describeApiError(err: ApiError): string;
|
|
20
|
+
export declare function errorResult(err: unknown, secrets?: string[]): CallToolResult;
|
|
21
|
+
/** A validation problem the tool catches before calling the API. */
|
|
22
|
+
export declare class InputError extends Error {
|
|
23
|
+
constructor(message: string);
|
|
24
|
+
}
|
|
25
|
+
export {};
|
package/dist/format.js
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
// Turning API results and API errors into MCP tool results.
|
|
2
|
+
//
|
|
3
|
+
// - Text content is short and human readable; any list longer than 50 rows is
|
|
4
|
+
// cut to 50 in the text, while structuredContent keeps the full API JSON.
|
|
5
|
+
// - Errors become `isError: true` with a plain sentence naming the API code.
|
|
6
|
+
// No stack traces, no raw exception text, no keys.
|
|
7
|
+
import { ApiError, redactDeep, redactString } from './client.js';
|
|
8
|
+
export const TEXT_ROW_LIMIT = 50;
|
|
9
|
+
export const SCOPE_SETTINGS_HINT = 'The workspace owner can enable it in the Hollerpost Dashboard under Settings, Developer API (edit the key, or create a new key with that scope).';
|
|
10
|
+
/** Copy `value`, cutting every array longer than `limit` down to `limit`. */
|
|
11
|
+
export function truncateLists(value, limit = TEXT_ROW_LIMIT) {
|
|
12
|
+
const notes = [];
|
|
13
|
+
const walk = (v, path) => {
|
|
14
|
+
if (Array.isArray(v)) {
|
|
15
|
+
const kept = v.length > limit ? v.slice(0, limit) : v;
|
|
16
|
+
if (v.length > limit)
|
|
17
|
+
notes.push({ path: path || '(root)', shown: limit, total: v.length });
|
|
18
|
+
return kept.map((item, i) => walk(item, `${path}[${i}]`));
|
|
19
|
+
}
|
|
20
|
+
if (v && typeof v === 'object') {
|
|
21
|
+
const out = {};
|
|
22
|
+
for (const [k, child] of Object.entries(v)) {
|
|
23
|
+
out[k] = walk(child, path ? `${path}.${k}` : k);
|
|
24
|
+
}
|
|
25
|
+
return out;
|
|
26
|
+
}
|
|
27
|
+
return v;
|
|
28
|
+
};
|
|
29
|
+
return { view: walk(value, ''), notes };
|
|
30
|
+
}
|
|
31
|
+
/** structuredContent must be a JSON object; wrap anything else. */
|
|
32
|
+
export function asObject(data) {
|
|
33
|
+
if (data && typeof data === 'object' && !Array.isArray(data))
|
|
34
|
+
return data;
|
|
35
|
+
if (Array.isArray(data))
|
|
36
|
+
return { data };
|
|
37
|
+
return { value: data ?? null };
|
|
38
|
+
}
|
|
39
|
+
export function okResult(lead, data, secrets = []) {
|
|
40
|
+
const structured = redactDeep(asObject(data), secrets);
|
|
41
|
+
const { view, notes } = truncateLists(structured);
|
|
42
|
+
const lines = [lead.trim()];
|
|
43
|
+
for (const n of notes) {
|
|
44
|
+
const where = n.path === '(root)' || n.path === 'data' ? '' : ` in ${n.path}`;
|
|
45
|
+
lines.push(`Showing the first ${n.shown} of ${n.total} rows${where}. The full list is in structuredContent; narrow the query (filters or a smaller limit) if you need to read it as text.`);
|
|
46
|
+
}
|
|
47
|
+
const text = `${lines.join('\n')}\n\n${JSON.stringify(view, null, 2)}`;
|
|
48
|
+
return {
|
|
49
|
+
content: [{ type: 'text', text: redactString(text, secrets) }],
|
|
50
|
+
structuredContent: structured,
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
function num(v) {
|
|
54
|
+
return typeof v === 'number' ? v.toLocaleString('en-US') : String(v ?? 'unknown');
|
|
55
|
+
}
|
|
56
|
+
/** Plain-language explanation for each API error code the tools can hit. */
|
|
57
|
+
export function describeApiError(err) {
|
|
58
|
+
const b = err.body;
|
|
59
|
+
const head = `Hollerpost API error "${err.code}"${err.status ? ` (HTTP ${err.status})` : ''}.`;
|
|
60
|
+
switch (err.code) {
|
|
61
|
+
case 'missing_api_key':
|
|
62
|
+
if (!err.local) {
|
|
63
|
+
return `${head} The API did not find a usable key in the request. Check that the key is complete (it starts with hp_live_ or uc_live_ and is long) and is sent as "Authorization: Bearer <key>". Keys are created in the Dashboard under Settings, Developer API.`;
|
|
64
|
+
}
|
|
65
|
+
return `${head} No API key was provided. For the remote server send "Authorization: Bearer hp_live_..." (or add ?key= to the connector URL if the client cannot set headers). For the local server set the HOLLERPOST_KEY environment variable. Keys are created in the Dashboard under Settings, Developer API.`;
|
|
66
|
+
case 'invalid_api_key':
|
|
67
|
+
return `${head} The API key is not valid or has been revoked. Ask the workspace owner for a current key from Dashboard, Settings, Developer API.`;
|
|
68
|
+
case 'insufficient_scope': {
|
|
69
|
+
const required = typeof b.required === 'string' ? b.required : 'a scope this key does not have';
|
|
70
|
+
const sendWarning = required === 'send'
|
|
71
|
+
? ' The "send" scope lets a key schedule campaigns to the whole list, so only turn it on for tools the owner trusts.'
|
|
72
|
+
: '';
|
|
73
|
+
return `${head} This API key is missing the "${required}" scope needed for this action. ${SCOPE_SETTINGS_HINT}${sendWarning} Nothing was changed.`;
|
|
74
|
+
}
|
|
75
|
+
case 'rate_limited': {
|
|
76
|
+
const secs = typeof b.retry_after_seconds === 'number' ? ` Try again in about ${b.retry_after_seconds} seconds.` : '';
|
|
77
|
+
return `${head} The key hit its request rate limit and one automatic retry did not clear it.${secs}`;
|
|
78
|
+
}
|
|
79
|
+
case 'review_pending': {
|
|
80
|
+
const id = typeof b.campaign_id === 'string' ? ` Campaign ${b.campaign_id}` : ' The campaign';
|
|
81
|
+
return `${head}${id} was NOT sent. A workspace's first campaign is held for a one-time human review by the Hollerpost team (status "held_for_review"). It goes out after it is approved, and later campaigns schedule normally. Tell the person it is waiting for review. Do not retry, and do not create a duplicate campaign to get around the review.`;
|
|
82
|
+
}
|
|
83
|
+
case 'confirm_required':
|
|
84
|
+
return `${head} Scheduling needs confirm: true. Nothing was scheduled. The preview numbers are in structuredContent: show the person the audience count and quota use, get a clear yes, then call campaign_schedule again with confirm: true and that audience count as expected_audience_count.`;
|
|
85
|
+
case 'audience_changed':
|
|
86
|
+
return `${head} Nothing was scheduled. The audience is now ${num(b.audience_count)} contacts, which differs from the expected_audience_count you sent by more than 5%. Tell the person the new count and ask again before retrying with expected_audience_count ${num(b.audience_count)}.`;
|
|
87
|
+
case 'quota_exceeded': {
|
|
88
|
+
const url = typeof b.send_packs_url === 'string' ? ` The person can buy a send pack in their browser at ${b.send_packs_url}.` : '';
|
|
89
|
+
return `${head} Nothing was scheduled. This send needs ${num(b.needed)} emails but only ${num(b.remaining)} remain this period.${url} You cannot buy packs or change plans through these tools; you can also narrow the audience with campaign_update.`;
|
|
90
|
+
}
|
|
91
|
+
case 'sending_domain_required':
|
|
92
|
+
return `${head} Nothing was sent. This workspace must send from its own verified domain first. Use domain_add to get the DNS records, have them added, then domain_verify until it reports verified.`;
|
|
93
|
+
case 'campaign_locked':
|
|
94
|
+
return `${head} Only draft campaigns can be changed or scheduled this way. This campaign is no longer a draft (it may be scheduled, sending, sent, held for review or canceled). Check it with campaigns_list, or draft a new campaign.`;
|
|
95
|
+
case 'domain_in_use':
|
|
96
|
+
return `${head} The domain was not removed because a scheduled campaign uses it. Cancel that campaign first (campaign_cancel) if the person really wants to remove the domain.`;
|
|
97
|
+
case 'consent_required':
|
|
98
|
+
return `${head} The contact was not added. Only add people who agreed to receive email from this business, and pass consent: true.`;
|
|
99
|
+
case 'recipient_suppressed':
|
|
100
|
+
return `${head} This address unsubscribed, bounced or complained before, so it cannot be added or mailed. That is permanent by design.`;
|
|
101
|
+
case 'trial_import_cap':
|
|
102
|
+
return `${head} The trial contact limit${b.limit !== undefined ? ` of ${num(b.limit)}` : ''} is reached. More contacts can be added after the workspace picks a plan (billing_portal_link gives the person a link).`;
|
|
103
|
+
case 'not_found':
|
|
104
|
+
return `${head} That item does not exist in this workspace. Check the id with the matching list tool.`;
|
|
105
|
+
case 'network_error':
|
|
106
|
+
return `${head} Could not reach api.hollerpost.com. Try again shortly.`;
|
|
107
|
+
case 'tenant_key_required':
|
|
108
|
+
return `${head} This is a platform key. The MCP server needs a workspace key (hp_live_... or uc_live_...).`;
|
|
109
|
+
default: {
|
|
110
|
+
const extra = { ...b };
|
|
111
|
+
delete extra.error;
|
|
112
|
+
const detail = Object.keys(extra).length ? ` Details: ${JSON.stringify(extra)}` : '';
|
|
113
|
+
return `${head}${detail}`;
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
export function errorResult(err, secrets = []) {
|
|
118
|
+
if (err instanceof ApiError) {
|
|
119
|
+
const structured = redactDeep({ ...err.body, error: err.code, status: err.status }, secrets);
|
|
120
|
+
return {
|
|
121
|
+
isError: true,
|
|
122
|
+
content: [{ type: 'text', text: redactString(describeApiError(err), secrets) }],
|
|
123
|
+
structuredContent: structured,
|
|
124
|
+
};
|
|
125
|
+
}
|
|
126
|
+
if (err instanceof InputError) {
|
|
127
|
+
return { isError: true, content: [{ type: 'text', text: redactString(err.message, secrets) }] };
|
|
128
|
+
}
|
|
129
|
+
// Anything else is a bug on our side. Keep it generic: no stack, no message
|
|
130
|
+
// that might carry request details.
|
|
131
|
+
return {
|
|
132
|
+
isError: true,
|
|
133
|
+
content: [{ type: 'text', text: 'Hollerpost MCP internal error. The request may not have completed; check with the matching list tool before retrying.' }],
|
|
134
|
+
};
|
|
135
|
+
}
|
|
136
|
+
/** A validation problem the tool catches before calling the API. */
|
|
137
|
+
export class InputError extends Error {
|
|
138
|
+
constructor(message) {
|
|
139
|
+
super(message);
|
|
140
|
+
this.name = 'InputError';
|
|
141
|
+
}
|
|
142
|
+
}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
3
|
+
import type { GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
|
|
4
|
+
type Args = Record<string, string | undefined>;
|
|
5
|
+
export interface PromptDef {
|
|
6
|
+
name: string;
|
|
7
|
+
title: string;
|
|
8
|
+
description: string;
|
|
9
|
+
args?: z.ZodRawShape;
|
|
10
|
+
build: (args: Args) => string;
|
|
11
|
+
}
|
|
12
|
+
export declare const PROMPTS: PromptDef[];
|
|
13
|
+
export declare function buildPrompt(def: PromptDef, args: Args): GetPromptResult;
|
|
14
|
+
export declare function registerPrompts(server: McpServer): void;
|
|
15
|
+
export {};
|