hollerpost-mcp 0.3.0 → 0.5.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/CHANGELOG.md +33 -0
- package/README.md +4 -1
- package/dist/client.js +12 -1
- package/dist/format.js +4 -0
- package/dist/prompts.js +1 -1
- package/dist/server.js +1 -0
- package/dist/tools.js +89 -4
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,38 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.5.0 (2026-11-09)
|
|
4
|
+
|
|
5
|
+
Pictures from the person's own device.
|
|
6
|
+
|
|
7
|
+
- `email_image_upload_link` (scope `draft`): a one-time Hollerpost page
|
|
8
|
+
(30 minutes, up to 10 pictures) where the person uploads pictures an
|
|
9
|
+
agent can't pass as a URL or base64, such as one dropped into a chat.
|
|
10
|
+
- `email_images_list` (scope `read`): the workspace's stored images, newest
|
|
11
|
+
first, to reuse instead of uploading again; with `link_id`, just the
|
|
12
|
+
pictures uploaded through that link.
|
|
13
|
+
|
|
14
|
+
## 0.4.0 (2026-11-08)
|
|
15
|
+
|
|
16
|
+
More than one picture per email.
|
|
17
|
+
|
|
18
|
+
- `email_image_upload` (scope `draft`): stores an image on Hollerpost from a
|
|
19
|
+
public https URL or base64 data (JPEG, PNG, WebP, GIF, up to 5 MB) and
|
|
20
|
+
returns its URL. Emails link to images, they are never attached. Images
|
|
21
|
+
are shrunk to at most 1200px wide and saved as JPEG (PNG when
|
|
22
|
+
transparent); GIFs up to 2 MB. Limits: 100 uploads per API key per 24
|
|
23
|
+
hours, 500 per workspace per 30 days (`image_limit_reached`, not retried).
|
|
24
|
+
- `campaign_draft` / `campaign_update` blocks:
|
|
25
|
+
- `body_md` takes image lines: `` or, clickable,
|
|
26
|
+
`[](https://link)`, each on a line by itself.
|
|
27
|
+
Images inside a sentence are refused (`image_on_its_own_line`), and alt
|
|
28
|
+
text is required.
|
|
29
|
+
- `sections`: up to 8 parts after the body, each with its own sub-heading,
|
|
30
|
+
image (`image_position` top, left or right), copy and button.
|
|
31
|
+
- Up to 20 images per email. The plain template stays copy only.
|
|
32
|
+
- Brand colors that are hard to read (neon yellow, lime) no longer give
|
|
33
|
+
white button labels or yellow links: Hollerpost picks a readable label and
|
|
34
|
+
darkens the link color. Colors chosen for one email are kept.
|
|
35
|
+
|
|
3
36
|
## 0.3.0 (2026-11-04)
|
|
4
37
|
|
|
5
38
|
New tools for Your page, calendar events and social posts. Not yet on npm or
|
package/README.md
CHANGED
|
@@ -113,10 +113,13 @@ If a tool needs a scope the key lacks, the tool answers `insufficient_scope`, na
|
|
|
113
113
|
| `brand_get` | read | Brand settings and writing voice |
|
|
114
114
|
| `brand_set_voice` | draft | Save the brand voice notes (replaces the old text) |
|
|
115
115
|
| `templates_list` | read | Templates and the content blocks each accepts |
|
|
116
|
+
| `email_image_upload` | draft | Store an image (from a URL or the file) for use in an email; returns its URL |
|
|
117
|
+
| `email_image_upload_link` | draft | A one-time page where the person uploads pictures from their device |
|
|
118
|
+
| `email_images_list` | read | Stored images, newest first, or the ones from an upload link |
|
|
116
119
|
| `segments_list` | read | Tags with subscribed counts, for choosing an audience |
|
|
117
120
|
| `contacts_search` | read | Find contacts by email, status or tag |
|
|
118
121
|
| `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, optionally with one survey question. Sends nothing |
|
|
122
|
+
| `campaign_draft` | draft | Create a draft from a template, content blocks (image lines in `body_md`, `sections` for several products) and an audience, optionally with one survey question. Sends nothing |
|
|
120
123
|
| `campaign_update` | draft | Edit a draft, including adding or removing its survey question |
|
|
121
124
|
| `campaign_preview` | draft | Rendered text, live audience count, quota after sending, warnings |
|
|
122
125
|
| `campaign_send_test` | draft | Test copy to up to 3 workspace users |
|
package/dist/client.js
CHANGED
|
@@ -70,6 +70,16 @@ export function redactDeep(value, secrets = []) {
|
|
|
70
70
|
}
|
|
71
71
|
return value;
|
|
72
72
|
}
|
|
73
|
+
/** True when a 429 is a usage limit rather than the per-minute rate limit. */
|
|
74
|
+
async function isUsageLimit(res) {
|
|
75
|
+
try {
|
|
76
|
+
const body = (await res.clone().json());
|
|
77
|
+
return body?.error === 'image_limit_reached';
|
|
78
|
+
}
|
|
79
|
+
catch {
|
|
80
|
+
return false;
|
|
81
|
+
}
|
|
82
|
+
}
|
|
73
83
|
/** Parse Retry-After (delta seconds or HTTP date) into milliseconds. */
|
|
74
84
|
export function parseRetryAfter(header, now = Date.now()) {
|
|
75
85
|
if (!header)
|
|
@@ -149,7 +159,8 @@ export class HollerpostClient {
|
|
|
149
159
|
init.body = JSON.stringify(opts.body);
|
|
150
160
|
}
|
|
151
161
|
let res = await this.send(url.toString(), init);
|
|
152
|
-
|
|
162
|
+
// A usage limit (image uploads) won't clear in a second: don't retry it.
|
|
163
|
+
if (res.status === 429 && !(await isUsageLimit(res))) {
|
|
153
164
|
const wait = parseRetryAfter(res.headers.get('retry-after')) ?? 1000;
|
|
154
165
|
if (wait <= MAX_RETRY_WAIT_MS) {
|
|
155
166
|
await res.body?.cancel().catch(() => { });
|
package/dist/format.js
CHANGED
|
@@ -82,6 +82,10 @@ export function describeApiError(err) {
|
|
|
82
82
|
const secs = typeof b.retry_after_seconds === 'number' ? ` Try again in about ${b.retry_after_seconds} seconds.` : '';
|
|
83
83
|
return `${head} The key hit its request rate limit and one automatic retry did not clear it.${secs}`;
|
|
84
84
|
}
|
|
85
|
+
case 'image_limit_reached': {
|
|
86
|
+
const msg = typeof b.message === 'string' ? ` ${b.message}` : '';
|
|
87
|
+
return `${head}${msg} Nothing was stored. Do not retry now. Reuse the url of an image you already uploaded, or tell the person the limit was reached.`;
|
|
88
|
+
}
|
|
85
89
|
case 'review_pending': {
|
|
86
90
|
const id = typeof b.campaign_id === 'string' ? ` Campaign ${b.campaign_id}` : ' The campaign';
|
|
87
91
|
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.`;
|
package/dist/prompts.js
CHANGED
|
@@ -22,7 +22,7 @@ export const PROMPTS = [
|
|
|
22
22
|
'',
|
|
23
23
|
'Steps:',
|
|
24
24
|
'1. Call brand_get and follow the voice exactly.',
|
|
25
|
-
'2. Call templates_list and pick the template that fits; fill only the blocks its blocks_schema accepts.',
|
|
25
|
+
'2. Call templates_list and pick the template that fits; fill only the blocks its blocks_schema accepts. For pictures, store each with email_image_upload and use the returned URL; for several products or stories use sections.',
|
|
26
26
|
'3. Call campaign_draft. Show me the subject, preheader and copy, plus the preview_url.',
|
|
27
27
|
'4. Call campaign_preview and tell me the audience count, the quota it uses and every warning.',
|
|
28
28
|
'5. Offer campaign_send_test to my address and send it if I agree.',
|
package/dist/server.js
CHANGED
|
@@ -12,6 +12,7 @@ export const SERVER_INSTRUCTIONS = [
|
|
|
12
12
|
'Start with workspace_info to learn the plan, the key scopes and the brand voice.',
|
|
13
13
|
'Campaigns are created as drafts. Before campaign_schedule always run campaign_preview, tell the person the audience count and quota use, and wait for a yes.',
|
|
14
14
|
'A workspace first campaign is held for a one-time human review (review_pending): it is not sent yet, do not retry.',
|
|
15
|
+
'Pictures: store each one with email_image_upload (from a public URL or the file itself), then use the URL as image_url, a section image or an image line in body_md. Several products or stories go in blocks.sections, one per item.',
|
|
15
16
|
'Surveys: survey_create makes a draft survey; campaign_draft can ask one of its rating, nps or single-choice questions in the email; open the survey with survey_update before testing or scheduling; read answers with survey_results.',
|
|
16
17
|
'Only add contacts who agreed to receive email. No tool can change billing; billing_portal_link gives the person a link.',
|
|
17
18
|
'Social posts (beta, only when this key has social scopes): the person connects an account by opening the link from social_channel_connect, never by giving you a password. Draft, run social_post_preview, show the person each network\'s text, and only after their yes call social_post_schedule with that preview_revision and confirm: true.',
|
package/dist/tools.js
CHANGED
|
@@ -49,18 +49,39 @@ const domainName = z
|
|
|
49
49
|
.max(253)
|
|
50
50
|
.regex(/^(?!-)[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/, 'Must be a bare domain such as mail.example.com (no scheme, no path).')
|
|
51
51
|
.describe('A sending domain or subdomain, for example mail.example.com. No https://, no path.');
|
|
52
|
+
const https = z.string().regex(/^https:\/\//, 'Must start with https://');
|
|
53
|
+
const sectionSchema = z
|
|
54
|
+
.object({
|
|
55
|
+
heading: z.string().max(140).optional().describe('Sub-heading for this section.'),
|
|
56
|
+
body_md: z.string().max(3000).optional().describe('Copy for this section. Same Markdown as body_md, image lines allowed.'),
|
|
57
|
+
image_url: https.max(2000).optional().describe('Section image (https URL). Use email_image_upload first to host it on Hollerpost.'),
|
|
58
|
+
image_alt: z.string().max(140).optional().describe('What the image shows. Required when image_url is set.'),
|
|
59
|
+
image_link: https.max(2000).optional().describe('Where a click on the image goes. Defaults to cta_url.'),
|
|
60
|
+
image_position: z.enum(['top', 'left', 'right']).optional().describe('top (default): image above the copy. left or right: image beside the copy on wide screens, stacked on phones.'),
|
|
61
|
+
cta_text: z.string().max(40).optional().describe('Button label for this section.'),
|
|
62
|
+
cta_url: https.max(2000).optional().describe('Button link for this section.'),
|
|
63
|
+
})
|
|
64
|
+
.strict();
|
|
52
65
|
const blocksSchema = z
|
|
53
66
|
.object({
|
|
54
67
|
heading: z.string().optional().describe('Main heading of the email.'),
|
|
55
|
-
body_md: z
|
|
68
|
+
body_md: z
|
|
69
|
+
.string()
|
|
70
|
+
.optional()
|
|
71
|
+
.describe('Body copy in Markdown: blank line between paragraphs, "- " lists, **bold**, *italic*, [text](https://...). To add a picture, put it on a line by itself:  or, clickable, [](https://link). Images inside a sentence are refused.'),
|
|
56
72
|
cta_text: z.string().optional().describe('Button label, for example "Book a visit".'),
|
|
57
73
|
cta_url: z.string().optional().describe('Button link (https URL).'),
|
|
58
|
-
image_url: z.string().optional().describe('Optional hero image (https URL).'),
|
|
74
|
+
image_url: z.string().optional().describe('Optional hero image at the top (https URL). For more pictures use image lines in body_md or sections.'),
|
|
59
75
|
image_alt: z.string().optional().describe('Alt text for the hero image. Required whenever image_url is set.'),
|
|
76
|
+
sections: z
|
|
77
|
+
.array(sectionSchema)
|
|
78
|
+
.max(8)
|
|
79
|
+
.optional()
|
|
80
|
+
.describe('Optional: up to 8 sections after body_md, each with its own sub-heading, image, copy and button, divided by a line. Use for a promotion with several products or a newsletter with several stories. Each needs at least a heading, body_md or image_url. Up to 20 images per email in total.'),
|
|
60
81
|
})
|
|
61
82
|
// Templates may add more text blocks later; accept them as strings.
|
|
62
83
|
.catchall(z.string())
|
|
63
|
-
.describe('Content blocks for the template. Check templates_list for the blocks_schema of the template you pick. Never send raw HTML: Hollerpost renders the blocks with the brand header, footer, unsubscribe link and address.');
|
|
84
|
+
.describe('Content blocks for the template. Check templates_list for the blocks_schema of the template you pick. Never send raw HTML: Hollerpost renders the blocks with the brand header, footer, unsubscribe link and address. The plain template takes no images.');
|
|
64
85
|
const audienceSchema = z
|
|
65
86
|
.union([
|
|
66
87
|
z.object({
|
|
@@ -283,7 +304,7 @@ export const TOOLS = [
|
|
|
283
304
|
name: 'templates_list',
|
|
284
305
|
title: 'List templates',
|
|
285
306
|
scope: 'read',
|
|
286
|
-
description: 'Lists the email templates and, for each, the blocks_schema (JSON Schema for heading, body_md, cta_text, cta_url, image_url, image_alt). Free and read only. Pick a template here before campaign_draft and fill only the blocks its schema accepts.',
|
|
307
|
+
description: 'Lists the email templates and, for each, the blocks_schema (JSON Schema for heading, body_md, cta_text, cta_url, image_url, image_alt and sections). Free and read only. Pick a template here before campaign_draft and fill only the blocks its schema accepts.',
|
|
287
308
|
input: {},
|
|
288
309
|
annotations: READ,
|
|
289
310
|
run: async (api) => {
|
|
@@ -291,6 +312,67 @@ export const TOOLS = [
|
|
|
291
312
|
return { lead: countLead('templates', data), data };
|
|
292
313
|
},
|
|
293
314
|
}),
|
|
315
|
+
defineTool({
|
|
316
|
+
name: 'email_image_upload',
|
|
317
|
+
title: 'Add an email image',
|
|
318
|
+
scope: 'draft',
|
|
319
|
+
description: 'Stores an image on Hollerpost for use in an email and returns its https URL. Pass url (a public https image, for example from the business website) or data_base64 (the file itself). For a picture the person has on their device or dropped into the chat, use email_image_upload_link instead. JPEG, PNG, WebP or GIF, up to 5 MB (GIFs up to 2 MB). Hollerpost shrinks it to at most 1200px wide and saves it as JPEG, or PNG when it has transparency, so the returned type can differ from the upload. Emails link to the image rather than attaching it, so it adds nothing to the message size. Limits: 100 uploads per API key per 24 hours and 500 per workspace per 30 days, so upload each picture once and reuse its url. Use the returned url in image_url, a section image_url, or an image line in body_md: . Sends nothing.',
|
|
320
|
+
input: {
|
|
321
|
+
url: https.max(2000).optional().describe('Public https URL of the image to copy.'),
|
|
322
|
+
data_base64: z.string().max(7_000_000).optional().describe('The image file, base64 encoded (a data: URL prefix is fine).'),
|
|
323
|
+
filename: z.string().max(200).optional().describe('A file name, for example "junior-cues-banner.png".'),
|
|
324
|
+
},
|
|
325
|
+
annotations: WRITE_SAFE,
|
|
326
|
+
run: async (api, args) => {
|
|
327
|
+
if (!args.url === !args.data_base64)
|
|
328
|
+
throw new InputError('Pass exactly one of url or data_base64.');
|
|
329
|
+
const body = Object.fromEntries(Object.entries(args).filter(([, v]) => v !== undefined));
|
|
330
|
+
const data = await api.request('POST', '/media', { body });
|
|
331
|
+
return { lead: `Image stored: ${get(data, 'url') ?? 'n/a'}. Use it in image_url, a section, or an image line in body_md.`, data };
|
|
332
|
+
},
|
|
333
|
+
}),
|
|
334
|
+
defineTool({
|
|
335
|
+
name: 'email_image_upload_link',
|
|
336
|
+
title: 'Get a link to upload pictures',
|
|
337
|
+
scope: 'draft',
|
|
338
|
+
description: 'Makes a one-time Hollerpost page where the person can upload pictures from their own device (up to 10, JPEG, PNG, WebP or GIF, 5 MB each). Use it when the person has a picture you cannot pass as a public URL or base64, for example one they dropped into this chat. Give them upload_url, wait until they say they are done, then call email_images_list with the link_id to get each picture\'s URL. The link works once and expires after 30 minutes. Sends nothing.',
|
|
339
|
+
input: {},
|
|
340
|
+
annotations: WRITE_SAFE,
|
|
341
|
+
run: async (api) => {
|
|
342
|
+
const data = await api.request('POST', '/media/upload-link', { body: {} });
|
|
343
|
+
return {
|
|
344
|
+
lead: `Ask the person to open ${get(data, 'upload_url') ?? 'the link'} and upload their pictures (it works once, for 30 minutes). When they say they are done, call email_images_list with link_id ${get(data, 'link_id') ?? ''}.`,
|
|
345
|
+
data,
|
|
346
|
+
};
|
|
347
|
+
},
|
|
348
|
+
}),
|
|
349
|
+
defineTool({
|
|
350
|
+
name: 'email_images_list',
|
|
351
|
+
title: 'List email images',
|
|
352
|
+
scope: 'read',
|
|
353
|
+
description: 'Lists images already stored on Hollerpost for this workspace, newest first, with their URLs, so you can reuse one instead of uploading it again. Pass link_id (from email_image_upload_link) to get just the pictures uploaded through that link, and whether the person has used it yet. Free and read only.',
|
|
354
|
+
input: {
|
|
355
|
+
link_id: z.string().uuid().optional().describe('The link_id from email_image_upload_link.'),
|
|
356
|
+
limit: z.number().int().min(1).max(50).optional().describe('How many recent images (default 20).'),
|
|
357
|
+
},
|
|
358
|
+
annotations: READ,
|
|
359
|
+
run: async (api, args) => {
|
|
360
|
+
if (args.link_id) {
|
|
361
|
+
const data = await api.request('GET', `/media/upload-link/${encodeURIComponent(args.link_id)}`);
|
|
362
|
+
const status = get(data, 'status');
|
|
363
|
+
const images = get(data, 'images') ?? [];
|
|
364
|
+
const lead = status === 'used'
|
|
365
|
+
? `${images.length} picture(s) uploaded. Use each url in image_url, a section, or an image line in body_md.`
|
|
366
|
+
: status === 'open'
|
|
367
|
+
? 'Nothing uploaded yet. Ask the person to finish uploading on the page, then check again.'
|
|
368
|
+
: `This link is ${status}. Make a new one with email_image_upload_link if they still need to upload.`;
|
|
369
|
+
return { lead, data };
|
|
370
|
+
}
|
|
371
|
+
const query = args.limit ? `?limit=${args.limit}` : '';
|
|
372
|
+
const data = await api.request('GET', `/media${query}`);
|
|
373
|
+
return { lead: countLead('images', data), data };
|
|
374
|
+
},
|
|
375
|
+
}),
|
|
294
376
|
defineTool({
|
|
295
377
|
name: 'segments_list',
|
|
296
378
|
title: 'List segments',
|
|
@@ -1056,6 +1138,9 @@ export const CORE_TOOL_NAMES = [
|
|
|
1056
1138
|
'brand_get',
|
|
1057
1139
|
'brand_set_voice',
|
|
1058
1140
|
'templates_list',
|
|
1141
|
+
'email_image_upload',
|
|
1142
|
+
'email_image_upload_link',
|
|
1143
|
+
'email_images_list',
|
|
1059
1144
|
'segments_list',
|
|
1060
1145
|
'contacts_search',
|
|
1061
1146
|
'contacts_add',
|
package/dist/version.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const VERSION = "0.
|
|
1
|
+
export declare const VERSION = "0.5.0";
|
package/dist/version.js
CHANGED
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
// Kept in sync with package.json "version" (a test checks it).
|
|
2
|
-
export const VERSION = '0.
|
|
2
|
+
export const VERSION = '0.5.0';
|
package/package.json
CHANGED