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/dist/tools.js
ADDED
|
@@ -0,0 +1,562 @@
|
|
|
1
|
+
// All Hollerpost MCP tools: definitions plus handlers. Transport agnostic.
|
|
2
|
+
//
|
|
3
|
+
// Each tool is a thin call to the public API at api.hollerpost.com. The API
|
|
4
|
+
// enforces scopes, quotas, consent and the first-campaign review; this file
|
|
5
|
+
// adds schemas, careful descriptions and readable results on top.
|
|
6
|
+
//
|
|
7
|
+
// Safety rules baked in here (plan 4.4):
|
|
8
|
+
// - No destructive tools except domain_remove, which needs confirm: true.
|
|
9
|
+
// - No tool moves money. billing_portal_link only hands back a URL.
|
|
10
|
+
// - consent and confirm fields are z.literal(true): the call cannot even be
|
|
11
|
+
// formed without them.
|
|
12
|
+
import { z } from 'zod';
|
|
13
|
+
import { ApiError } from './client.js';
|
|
14
|
+
import { errorResult, InputError, okResult } from './format.js';
|
|
15
|
+
function defineTool(def) {
|
|
16
|
+
return def;
|
|
17
|
+
}
|
|
18
|
+
const seg = (v) => encodeURIComponent(v);
|
|
19
|
+
const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
|
|
20
|
+
const WRITE_SAFE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
|
|
21
|
+
const WRITE_IDEMPOTENT = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
|
|
22
|
+
const SENDS_MAIL = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
|
|
23
|
+
// ---------------------------------------------------------------------------
|
|
24
|
+
// Shared schema pieces
|
|
25
|
+
const campaignId = z.string().min(1).describe('Campaign id, as returned by campaign_draft or campaigns_list.');
|
|
26
|
+
const domainName = z
|
|
27
|
+
.string()
|
|
28
|
+
.min(3)
|
|
29
|
+
.max(253)
|
|
30
|
+
.regex(/^(?!-)[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/, 'Must be a bare domain such as mail.example.com (no scheme, no path).')
|
|
31
|
+
.describe('A sending domain or subdomain, for example mail.example.com. No https://, no path.');
|
|
32
|
+
const blocksSchema = z
|
|
33
|
+
.object({
|
|
34
|
+
heading: z.string().optional().describe('Main heading of the email.'),
|
|
35
|
+
body_md: z.string().optional().describe('Body copy in Markdown. Hollerpost renders it inside the brand template.'),
|
|
36
|
+
cta_text: z.string().optional().describe('Button label, for example "Book a visit".'),
|
|
37
|
+
cta_url: z.string().optional().describe('Button link (https URL).'),
|
|
38
|
+
image_url: z.string().optional().describe('Optional hero image (https URL).'),
|
|
39
|
+
image_alt: z.string().optional().describe('Alt text for the hero image. Required whenever image_url is set.'),
|
|
40
|
+
})
|
|
41
|
+
// Templates may add more text blocks later; accept them as strings.
|
|
42
|
+
.catchall(z.string())
|
|
43
|
+
.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.');
|
|
44
|
+
const audienceSchema = z
|
|
45
|
+
.union([
|
|
46
|
+
z.object({
|
|
47
|
+
tags: z.array(z.string().min(1)).min(1).describe('Send to subscribed contacts with ANY of these tags. Get tags from segments_list.'),
|
|
48
|
+
}),
|
|
49
|
+
z.object({
|
|
50
|
+
all: z.literal(true).describe('Send to every subscribed contact in the workspace.'),
|
|
51
|
+
}),
|
|
52
|
+
])
|
|
53
|
+
.describe('Who gets it: {"tags": ["vip"]} for tagged contacts, or {"all": true} for every subscribed contact.');
|
|
54
|
+
const campaignStatus = z.enum(['draft', 'scheduled', 'sending', 'sent', 'held_for_review', 'canceled']);
|
|
55
|
+
// ---------------------------------------------------------------------------
|
|
56
|
+
// Result helpers
|
|
57
|
+
function rows(data) {
|
|
58
|
+
if (Array.isArray(data))
|
|
59
|
+
return data;
|
|
60
|
+
if (data && typeof data === 'object' && Array.isArray(data.data)) {
|
|
61
|
+
return data.data;
|
|
62
|
+
}
|
|
63
|
+
return [];
|
|
64
|
+
}
|
|
65
|
+
function total(data) {
|
|
66
|
+
const t = data && typeof data === 'object' ? data.total : undefined;
|
|
67
|
+
return typeof t === 'number' ? t : null;
|
|
68
|
+
}
|
|
69
|
+
function countLead(noun, data) {
|
|
70
|
+
const n = rows(data).length;
|
|
71
|
+
const t = total(data);
|
|
72
|
+
if (t !== null && t > n)
|
|
73
|
+
return `${n} ${noun} returned (${t} match in total).`;
|
|
74
|
+
return `${n} ${noun} returned.`;
|
|
75
|
+
}
|
|
76
|
+
function get(obj, key) {
|
|
77
|
+
return obj && typeof obj === 'object' ? obj[key] : undefined;
|
|
78
|
+
}
|
|
79
|
+
function recordTable(domain) {
|
|
80
|
+
const records = get(domain, 'records') ?? [];
|
|
81
|
+
if (!records.length)
|
|
82
|
+
return '';
|
|
83
|
+
const lines = ['| Purpose | Type | Host | Value | TTL | Found |', '|---|---|---|---|---|---|'];
|
|
84
|
+
for (const r of records) {
|
|
85
|
+
const value = r.priority !== undefined ? `${r.priority} ${r.value ?? ''}` : (r.value ?? '');
|
|
86
|
+
lines.push(`| ${r.purpose ?? ''} | ${r.type ?? ''} | ${r.host ?? ''} | ${value} | ${r.ttl ?? ''} | ${r.found ? 'yes' : 'no'} |`);
|
|
87
|
+
}
|
|
88
|
+
return lines.join('\n');
|
|
89
|
+
}
|
|
90
|
+
function verifyLines(domain) {
|
|
91
|
+
const records = get(domain, 'records') ?? [];
|
|
92
|
+
return records
|
|
93
|
+
.map((r) => {
|
|
94
|
+
const label = `${r.purpose ?? r.type ?? 'record'} ${r.type ?? ''} ${r.host ?? ''}`.replace(/\s+/g, ' ').trim();
|
|
95
|
+
if (r.found)
|
|
96
|
+
return `- OK: ${label}`;
|
|
97
|
+
const expected = r.expected ?? r.value ?? '(see records)';
|
|
98
|
+
const actual = Array.isArray(r.actual) ? r.actual.join(', ') : r.actual;
|
|
99
|
+
return `- WRONG OR MISSING: ${label}. Expected "${expected}", found ${actual ? `"${actual}"` : 'nothing'}.`;
|
|
100
|
+
})
|
|
101
|
+
.join('\n');
|
|
102
|
+
}
|
|
103
|
+
// ---------------------------------------------------------------------------
|
|
104
|
+
// The 24 tools
|
|
105
|
+
export const TOOLS = [
|
|
106
|
+
defineTool({
|
|
107
|
+
name: 'workspace_info',
|
|
108
|
+
title: 'Workspace info',
|
|
109
|
+
scope: 'read',
|
|
110
|
+
description: 'Start here. Returns who this key belongs to: workspace name, plan, trial status, emails left, the scopes this key has, and the brand (voice, colors, from name, sending domain). Free and read only; uses no quota. Call it at the start of a conversation so you know which tools this key may use and how to write on-brand.',
|
|
111
|
+
input: {},
|
|
112
|
+
annotations: READ,
|
|
113
|
+
run: async (api) => {
|
|
114
|
+
const [me, brand] = await Promise.allSettled([api.request('GET', '/me'), api.request('GET', '/brand')]);
|
|
115
|
+
if (me.status === 'rejected')
|
|
116
|
+
throw me.reason;
|
|
117
|
+
const meData = (me.value ?? {});
|
|
118
|
+
const merged = { ...meData };
|
|
119
|
+
merged.brand = brand.status === 'fulfilled' ? brand.value : null;
|
|
120
|
+
if (brand.status === 'rejected' && brand.reason instanceof ApiError) {
|
|
121
|
+
merged.brand_error = brand.reason.code;
|
|
122
|
+
}
|
|
123
|
+
const scopes = Array.isArray(meData.scopes) ? meData.scopes.join(', ') : 'unknown';
|
|
124
|
+
const lead = `Workspace "${meData.workspace_name ?? 'unknown'}" on plan ${meData.plan ?? 'unknown'}. This key's scopes: ${scopes}.`;
|
|
125
|
+
return { lead, data: merged };
|
|
126
|
+
},
|
|
127
|
+
}),
|
|
128
|
+
defineTool({
|
|
129
|
+
name: 'brand_get',
|
|
130
|
+
title: 'Get brand',
|
|
131
|
+
scope: 'read',
|
|
132
|
+
description: 'Returns the brand settings: workspace and from name, reply-to, logo, colors, footer address, the saved writing voice and the sending domain status. Free and read only. Read this before writing any campaign copy and follow the voice exactly.',
|
|
133
|
+
input: {},
|
|
134
|
+
annotations: READ,
|
|
135
|
+
run: async (api) => {
|
|
136
|
+
const data = await api.request('GET', '/brand');
|
|
137
|
+
return { lead: `Brand for "${get(data, 'workspace_name') ?? 'this workspace'}".`, data };
|
|
138
|
+
},
|
|
139
|
+
}),
|
|
140
|
+
defineTool({
|
|
141
|
+
name: 'brand_set_voice',
|
|
142
|
+
title: 'Save brand voice',
|
|
143
|
+
scope: 'draft',
|
|
144
|
+
description: 'Saves the brand voice notes (how this business writes: tone, words to use or avoid). Replaces the previous voice text entirely, so read brand_get first and include anything worth keeping. Uses no quota and sends nothing. Reversible by saving the old text again. Only save what the person dictated or approved.',
|
|
145
|
+
input: {
|
|
146
|
+
voice: z.string().min(1).max(4000).describe('The full voice notes to save, in plain sentences. Replaces the current text.'),
|
|
147
|
+
},
|
|
148
|
+
annotations: WRITE_IDEMPOTENT,
|
|
149
|
+
run: async (api, { voice }) => {
|
|
150
|
+
const data = await api.request('PATCH', '/brand', { body: { voice } });
|
|
151
|
+
return { lead: 'Brand voice saved.', data };
|
|
152
|
+
},
|
|
153
|
+
}),
|
|
154
|
+
defineTool({
|
|
155
|
+
name: 'templates_list',
|
|
156
|
+
title: 'List templates',
|
|
157
|
+
scope: 'read',
|
|
158
|
+
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.',
|
|
159
|
+
input: {},
|
|
160
|
+
annotations: READ,
|
|
161
|
+
run: async (api) => {
|
|
162
|
+
const data = await api.request('GET', '/templates');
|
|
163
|
+
return { lead: countLead('templates', data), data };
|
|
164
|
+
},
|
|
165
|
+
}),
|
|
166
|
+
defineTool({
|
|
167
|
+
name: 'segments_list',
|
|
168
|
+
title: 'List segments',
|
|
169
|
+
scope: 'read',
|
|
170
|
+
description: 'Lists contact tags with the number of subscribed contacts on each. Free and read only. Use it to choose a campaign audience by tag and to tell the person roughly how many people a send reaches.',
|
|
171
|
+
input: {},
|
|
172
|
+
annotations: READ,
|
|
173
|
+
run: async (api) => {
|
|
174
|
+
const data = await api.request('GET', '/segments');
|
|
175
|
+
return { lead: countLead('tags', data), data };
|
|
176
|
+
},
|
|
177
|
+
}),
|
|
178
|
+
defineTool({
|
|
179
|
+
name: 'contacts_search',
|
|
180
|
+
title: 'Search contacts',
|
|
181
|
+
scope: 'read',
|
|
182
|
+
description: 'Finds contacts by exact email, status or tag, newest first. Free and read only. Status "subscribed" means active; "unsubscribed" covers suppressed addresses. Returns at most `limit` rows (default 50, max 200).',
|
|
183
|
+
input: {
|
|
184
|
+
email: z.string().optional().describe('Exact email address to look up.'),
|
|
185
|
+
status: z
|
|
186
|
+
.enum(['subscribed', 'unsubscribed', 'active', 'pending', 'suppressed'])
|
|
187
|
+
.optional()
|
|
188
|
+
.describe('Filter by status. subscribed = active, unsubscribed = suppressed.'),
|
|
189
|
+
tag: z.string().optional().describe('Only contacts that carry this tag.'),
|
|
190
|
+
limit: z.number().int().min(1).max(200).optional().describe('How many rows to return (1 to 200, default 50).'),
|
|
191
|
+
},
|
|
192
|
+
annotations: READ,
|
|
193
|
+
run: async (api, args) => {
|
|
194
|
+
const data = await api.request('GET', '/contacts', {
|
|
195
|
+
query: { email: args.email, status: args.status, tag: args.tag, limit: args.limit },
|
|
196
|
+
});
|
|
197
|
+
return { lead: countLead('contacts', data), data };
|
|
198
|
+
},
|
|
199
|
+
}),
|
|
200
|
+
defineTool({
|
|
201
|
+
name: 'contacts_add',
|
|
202
|
+
title: 'Add contact',
|
|
203
|
+
scope: 'contacts',
|
|
204
|
+
description: 'Adds one contact, or merges tags into an existing one. Uses no send quota. ONLY add a person who agreed to receive marketing email from this business (for example they signed up, or the person you are helping confirms they opted in). If you are not sure, ask first. Addresses that unsubscribed, bounced or complained cannot be re-added. Not reversible through these tools (there is no delete tool), so check the email is right.',
|
|
205
|
+
input: {
|
|
206
|
+
email: z.email().describe('The contact email address.'),
|
|
207
|
+
first_name: z.string().max(80).optional().describe('First name, used for personalization.'),
|
|
208
|
+
last_name: z.string().max(80).optional().describe('Last name.'),
|
|
209
|
+
tags: z.array(z.string().min(1).max(60)).max(25).optional().describe('Tags to add, for example ["vip"]. Merged with existing tags.'),
|
|
210
|
+
consent: z
|
|
211
|
+
.literal(true)
|
|
212
|
+
.describe('Must be true. Confirms this person agreed to receive marketing email from this business. Never set it on a guess.'),
|
|
213
|
+
},
|
|
214
|
+
annotations: WRITE_IDEMPOTENT,
|
|
215
|
+
run: async (api, args) => {
|
|
216
|
+
const body = { email: args.email, consent: true };
|
|
217
|
+
if (args.first_name !== undefined)
|
|
218
|
+
body.first_name = args.first_name;
|
|
219
|
+
if (args.last_name !== undefined)
|
|
220
|
+
body.last_name = args.last_name;
|
|
221
|
+
if (args.tags !== undefined)
|
|
222
|
+
body.tags = args.tags;
|
|
223
|
+
const data = await api.request('POST', '/contacts', { body });
|
|
224
|
+
return { lead: `Contact ${args.email} saved.`, data };
|
|
225
|
+
},
|
|
226
|
+
}),
|
|
227
|
+
defineTool({
|
|
228
|
+
name: 'campaign_draft',
|
|
229
|
+
title: 'Draft campaign',
|
|
230
|
+
scope: 'draft',
|
|
231
|
+
description: 'Creates a campaign as a DRAFT. Nothing is sent and no quota is used. Before calling: read brand_get for the voice, pick a template from templates_list, and pick the audience from segments_list. You fill the content blocks; Hollerpost renders the email with the brand header, footer and unsubscribe link. Returns the id, audience_count and a preview_url to share with the person. Next step: campaign_preview, then campaign_send_test.',
|
|
232
|
+
input: {
|
|
233
|
+
name: z.string().min(1).max(200).describe('Internal campaign name (recipients do not see it).'),
|
|
234
|
+
template_id: z.string().min(1).describe('Template id from templates_list.'),
|
|
235
|
+
subject: z.string().min(1).max(200).describe('Email subject line.'),
|
|
236
|
+
preheader: z.string().max(200).optional().describe('Preview text shown after the subject in most inboxes.'),
|
|
237
|
+
blocks: blocksSchema,
|
|
238
|
+
audience: audienceSchema,
|
|
239
|
+
},
|
|
240
|
+
annotations: WRITE_SAFE,
|
|
241
|
+
run: async (api, args) => {
|
|
242
|
+
const body = {
|
|
243
|
+
name: args.name,
|
|
244
|
+
template_id: args.template_id,
|
|
245
|
+
subject: args.subject,
|
|
246
|
+
blocks: args.blocks,
|
|
247
|
+
audience: args.audience,
|
|
248
|
+
};
|
|
249
|
+
if (args.preheader !== undefined)
|
|
250
|
+
body.preheader = args.preheader;
|
|
251
|
+
const data = await api.request('POST', '/campaigns', { body });
|
|
252
|
+
const lead = `Draft ${get(data, 'id') ?? ''} created for ${get(data, 'audience_count') ?? 'an unknown number of'} contacts. Nothing has been sent. Preview: ${get(data, 'preview_url') ?? 'n/a'}. Next: campaign_preview, then campaign_send_test.`;
|
|
253
|
+
return { lead, data };
|
|
254
|
+
},
|
|
255
|
+
}),
|
|
256
|
+
defineTool({
|
|
257
|
+
name: 'campaign_update',
|
|
258
|
+
title: 'Update draft',
|
|
259
|
+
scope: 'draft',
|
|
260
|
+
description: 'Edits a campaign while it is still a draft: any of name, template, subject, preheader, blocks or audience. Fields you leave out stay as they are; blocks you pass replace the whole blocks object. Uses no quota and sends nothing. Refused with campaign_locked once the campaign is scheduled or sent. Run campaign_preview again after editing.',
|
|
261
|
+
input: {
|
|
262
|
+
id: campaignId,
|
|
263
|
+
name: z.string().min(1).max(200).optional().describe('New internal name.'),
|
|
264
|
+
template_id: z.string().min(1).optional().describe('New template id from templates_list.'),
|
|
265
|
+
subject: z.string().min(1).max(200).optional().describe('New subject line.'),
|
|
266
|
+
preheader: z.string().max(200).optional().describe('New preview text.'),
|
|
267
|
+
blocks: blocksSchema.optional(),
|
|
268
|
+
audience: audienceSchema.optional(),
|
|
269
|
+
},
|
|
270
|
+
annotations: WRITE_IDEMPOTENT,
|
|
271
|
+
run: async (api, { id, ...rest }) => {
|
|
272
|
+
const body = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined));
|
|
273
|
+
if (!Object.keys(body).length) {
|
|
274
|
+
throw new InputError('Nothing to update: pass at least one of name, template_id, subject, preheader, blocks or audience.');
|
|
275
|
+
}
|
|
276
|
+
const data = await api.request('PATCH', `/campaigns/${seg(id)}`, { body });
|
|
277
|
+
return { lead: `Draft ${id} updated. Run campaign_preview again before testing or scheduling.`, data };
|
|
278
|
+
},
|
|
279
|
+
}),
|
|
280
|
+
defineTool({
|
|
281
|
+
name: 'campaign_preview',
|
|
282
|
+
title: 'Preview campaign',
|
|
283
|
+
scope: 'draft',
|
|
284
|
+
description: 'Renders a draft and returns the text version, the live audience_count, quota_after_send and warnings (empty subject, missing button, over quota, first campaign pending review). Free, read only, sends nothing. Always call this before campaign_schedule and tell the person the audience count, the quota it will use and every warning.',
|
|
285
|
+
input: { id: campaignId },
|
|
286
|
+
annotations: READ,
|
|
287
|
+
run: async (api, { id }) => {
|
|
288
|
+
const data = await api.request('POST', `/campaigns/${seg(id)}/preview`, { body: {} });
|
|
289
|
+
const warnings = get(data, 'warnings');
|
|
290
|
+
const w = Array.isArray(warnings) && warnings.length ? ` Warnings: ${warnings.map(String).join('; ')}.` : ' No warnings.';
|
|
291
|
+
const lead = `Preview of ${id}: audience ${get(data, 'audience_count') ?? 'unknown'} contacts, quota left after sending ${get(data, 'quota_after_send') ?? 'unknown'}.${w}`;
|
|
292
|
+
return { lead, data };
|
|
293
|
+
},
|
|
294
|
+
}),
|
|
295
|
+
defineTool({
|
|
296
|
+
name: 'campaign_send_test',
|
|
297
|
+
title: 'Send test email',
|
|
298
|
+
scope: 'draft',
|
|
299
|
+
description: 'Sends a test copy of a draft to up to 3 addresses. The addresses must belong to users of this workspace; other addresses are refused. Uses quota only for the test emails actually sent, does not touch the audience, and does not change the draft. Offer this after campaign_preview so the person can check it in their own inbox.',
|
|
300
|
+
input: {
|
|
301
|
+
id: campaignId,
|
|
302
|
+
to: z.array(z.email()).min(1).max(3).describe('1 to 3 addresses of people who use this workspace.'),
|
|
303
|
+
},
|
|
304
|
+
annotations: { ...WRITE_SAFE, openWorldHint: true },
|
|
305
|
+
run: async (api, { id, to }) => {
|
|
306
|
+
const data = await api.request('POST', `/campaigns/${seg(id)}/test`, { body: { to } });
|
|
307
|
+
return { lead: `Test of ${id} sent to ${to.join(', ')}.`, data };
|
|
308
|
+
},
|
|
309
|
+
}),
|
|
310
|
+
defineTool({
|
|
311
|
+
name: 'campaign_schedule',
|
|
312
|
+
title: 'Schedule campaign',
|
|
313
|
+
scope: 'send',
|
|
314
|
+
description: 'Schedules a drafted campaign to send to its audience. This is not reversible once sending starts, and it uses one email of quota per recipient. Call campaign_preview first, tell the person the audience count and the quota it uses, and only call this after they say yes. Pass the audience count you showed them as expected_audience_count; if the list changed meaningfully the call is refused. A workspace\'s first campaign is held for a one-time human review instead of sending (review_pending); say so plainly and do not retry. Before send_at, campaign_cancel can still stop it.',
|
|
315
|
+
input: {
|
|
316
|
+
id: campaignId,
|
|
317
|
+
send_at: z
|
|
318
|
+
.union([z.literal('now'), z.iso.datetime({ offset: true })])
|
|
319
|
+
.describe('"now", or an ISO 8601 time with timezone such as 2026-10-05T09:00:00-07:00.'),
|
|
320
|
+
expected_audience_count: z
|
|
321
|
+
.number()
|
|
322
|
+
.int()
|
|
323
|
+
.min(0)
|
|
324
|
+
.describe('The audience count you showed the person from campaign_preview.'),
|
|
325
|
+
confirm: z
|
|
326
|
+
.literal(true)
|
|
327
|
+
.describe('Must be true, and only after the person explicitly approved this send and its audience count.'),
|
|
328
|
+
},
|
|
329
|
+
annotations: SENDS_MAIL,
|
|
330
|
+
run: async (api, { id, send_at, expected_audience_count }) => {
|
|
331
|
+
const data = await api.request('POST', `/campaigns/${seg(id)}/schedule`, {
|
|
332
|
+
body: { send_at, confirm: true, expected_audience_count },
|
|
333
|
+
});
|
|
334
|
+
const lead = `Campaign ${id} is ${get(data, 'status') ?? 'scheduled'} for ${get(data, 'send_at') ?? send_at} to ${get(data, 'audience_count') ?? expected_audience_count} contacts. campaign_cancel can stop it until sending starts.`;
|
|
335
|
+
return { lead, data };
|
|
336
|
+
},
|
|
337
|
+
}),
|
|
338
|
+
defineTool({
|
|
339
|
+
name: 'campaign_cancel',
|
|
340
|
+
title: 'Cancel scheduled campaign',
|
|
341
|
+
scope: 'send',
|
|
342
|
+
description: 'Cancels a scheduled campaign before it starts sending. Only works while the status is scheduled; once sending has started it cannot be stopped. Uses no quota. Confirm with the person which campaign they mean (campaigns_list with status scheduled) before calling.',
|
|
343
|
+
input: { id: campaignId },
|
|
344
|
+
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
|
|
345
|
+
run: async (api, { id }) => {
|
|
346
|
+
const data = await api.request('POST', `/campaigns/${seg(id)}/cancel`, { body: {} });
|
|
347
|
+
return { lead: `Campaign ${id} canceled. Nothing more will be sent for it.`, data };
|
|
348
|
+
},
|
|
349
|
+
}),
|
|
350
|
+
defineTool({
|
|
351
|
+
name: 'campaigns_list',
|
|
352
|
+
title: 'List campaigns',
|
|
353
|
+
scope: 'read',
|
|
354
|
+
description: 'Lists campaigns, newest first, optionally filtered by status (draft, scheduled, sending, sent, held_for_review, canceled). Free and read only.',
|
|
355
|
+
input: {
|
|
356
|
+
status: campaignStatus.optional().describe('Only campaigns with this status.'),
|
|
357
|
+
limit: z.number().int().min(1).max(100).optional().describe('How many to return (1 to 100).'),
|
|
358
|
+
},
|
|
359
|
+
annotations: READ,
|
|
360
|
+
run: async (api, args) => {
|
|
361
|
+
const data = await api.request('GET', '/campaigns', { query: { status: args.status, limit: args.limit } });
|
|
362
|
+
return { lead: countLead('campaigns', data), data };
|
|
363
|
+
},
|
|
364
|
+
}),
|
|
365
|
+
defineTool({
|
|
366
|
+
name: 'campaign_stats',
|
|
367
|
+
title: 'Campaign stats',
|
|
368
|
+
scope: 'read',
|
|
369
|
+
description: 'Returns delivery and engagement numbers for a campaign: sent, delivered, bounced, complained, opened, clicked, unsubscribed and top links. Free and read only.',
|
|
370
|
+
input: { id: campaignId },
|
|
371
|
+
annotations: READ,
|
|
372
|
+
run: async (api, { id }) => {
|
|
373
|
+
const data = await api.request('GET', `/campaigns/${seg(id)}/stats`);
|
|
374
|
+
const lead = `Stats for ${id}: sent ${get(data, 'sent') ?? 0}, delivered ${get(data, 'delivered') ?? 0}, opened ${get(data, 'opened') ?? 0}, clicked ${get(data, 'clicked') ?? 0}, bounced ${get(data, 'bounced') ?? 0}, unsubscribed ${get(data, 'unsubscribed') ?? 0}.`;
|
|
375
|
+
return { lead, data };
|
|
376
|
+
},
|
|
377
|
+
}),
|
|
378
|
+
defineTool({
|
|
379
|
+
name: 'email_send',
|
|
380
|
+
title: 'Send transactional email',
|
|
381
|
+
scope: 'send',
|
|
382
|
+
description: 'Sends ONE transactional email (a receipt, a reply, a booking confirmation) to one address right away. Not reversible, and it uses one email of quota. Never use it for marketing or to mail a list: campaigns are for that. Show the person the recipient, subject and body and get a yes before calling. idempotency_key is required: reuse the same key if you retry so the email is not sent twice. Pass html, text, or both.',
|
|
383
|
+
input: {
|
|
384
|
+
to: z.email().describe('Recipient address.'),
|
|
385
|
+
subject: z.string().min(1).max(300).describe('Subject line.'),
|
|
386
|
+
html: z.string().optional().describe('HTML body. Hollerpost adds the brand header.'),
|
|
387
|
+
text: z.string().optional().describe('Plain text body.'),
|
|
388
|
+
reply_to: z.email().optional().describe('Reply-to address, if different from the workspace default.'),
|
|
389
|
+
idempotency_key: z
|
|
390
|
+
.string()
|
|
391
|
+
.min(8)
|
|
392
|
+
.max(200)
|
|
393
|
+
.describe('A unique key for this email, for example "receipt-1042". Reusing it returns the first result instead of sending again.'),
|
|
394
|
+
},
|
|
395
|
+
annotations: SENDS_MAIL,
|
|
396
|
+
run: async (api, args) => {
|
|
397
|
+
if (!args.html && !args.text)
|
|
398
|
+
throw new InputError('Pass html, text, or both. Nothing was sent.');
|
|
399
|
+
const body = { to: args.to, subject: args.subject };
|
|
400
|
+
if (args.html !== undefined)
|
|
401
|
+
body.html = args.html;
|
|
402
|
+
if (args.text !== undefined)
|
|
403
|
+
body.text = args.text;
|
|
404
|
+
if (args.reply_to !== undefined)
|
|
405
|
+
body.replyTo = args.reply_to;
|
|
406
|
+
const data = await api.request('POST', '/emails', { body, headers: { 'Idempotency-Key': args.idempotency_key } });
|
|
407
|
+
return { lead: `Email to ${args.to} accepted for sending.`, data };
|
|
408
|
+
},
|
|
409
|
+
}),
|
|
410
|
+
defineTool({
|
|
411
|
+
name: 'events_recent',
|
|
412
|
+
title: 'Recent delivery events',
|
|
413
|
+
scope: 'read',
|
|
414
|
+
description: 'Lists recent delivery events of one type across campaigns and transactional mail: email.bounced (default), email.complained or email.delivered. Free and read only. Useful for list hygiene and deliverability questions.',
|
|
415
|
+
input: {
|
|
416
|
+
type: z.enum(['email.bounced', 'email.complained', 'email.delivered']).optional().describe('Event type (default email.bounced).'),
|
|
417
|
+
limit: z.number().int().min(1).max(100).optional().describe('How many events (1 to 100, default 25).'),
|
|
418
|
+
},
|
|
419
|
+
annotations: READ,
|
|
420
|
+
run: async (api, args) => {
|
|
421
|
+
const data = await api.request('GET', '/events', { query: { type: args.type, limit: args.limit } });
|
|
422
|
+
return { lead: countLead(`${args.type ?? 'email.bounced'} events`, data), data };
|
|
423
|
+
},
|
|
424
|
+
}),
|
|
425
|
+
defineTool({
|
|
426
|
+
name: 'account_get',
|
|
427
|
+
title: 'Account and quota',
|
|
428
|
+
scope: 'read',
|
|
429
|
+
description: 'Returns the plan, billing period end, email and SMS quota used and limit, trial status and the send packs available. Free and read only. Check it before a large send. Plan changes and purchases are never done through tools: use billing_portal_link to give the person a link.',
|
|
430
|
+
input: {},
|
|
431
|
+
annotations: READ,
|
|
432
|
+
run: async (api) => {
|
|
433
|
+
const data = await api.request('GET', '/account');
|
|
434
|
+
const email = get(get(data, 'quota'), 'email');
|
|
435
|
+
const used = get(email, 'used');
|
|
436
|
+
const limit = get(email, 'limit');
|
|
437
|
+
const lead = `Plan ${get(data, 'plan') ?? 'unknown'}. Emails used ${used ?? '?'} of ${limit ?? '?'} this period, which ends ${get(data, 'billing_period_ends') ?? 'unknown'}.`;
|
|
438
|
+
return { lead, data };
|
|
439
|
+
},
|
|
440
|
+
}),
|
|
441
|
+
defineTool({
|
|
442
|
+
name: 'account_update',
|
|
443
|
+
title: 'Update account details',
|
|
444
|
+
scope: 'account',
|
|
445
|
+
description: 'Updates the workspace name, from name, reply-to address or the physical footer address (required by law in marketing email). Uses no quota. Reversible by setting the old value again. Billing can never be changed here. Confirm the new values with the person first.',
|
|
446
|
+
input: {
|
|
447
|
+
workspace_name: z.string().min(1).max(120).optional().describe('Workspace or business name.'),
|
|
448
|
+
from_name: z.string().min(1).max(120).optional().describe('Name recipients see in the From field.'),
|
|
449
|
+
reply_to: z.email().optional().describe('Where replies go.'),
|
|
450
|
+
footer_address: z.string().min(5).max(300).optional().describe('Physical mailing address printed in every campaign footer.'),
|
|
451
|
+
},
|
|
452
|
+
annotations: WRITE_IDEMPOTENT,
|
|
453
|
+
run: async (api, args) => {
|
|
454
|
+
const body = {};
|
|
455
|
+
if (args.workspace_name !== undefined)
|
|
456
|
+
body.workspace_name = args.workspace_name;
|
|
457
|
+
if (args.from_name !== undefined)
|
|
458
|
+
body.from_name = args.from_name;
|
|
459
|
+
if (args.reply_to !== undefined)
|
|
460
|
+
body.reply_to = args.reply_to;
|
|
461
|
+
if (args.footer_address !== undefined)
|
|
462
|
+
body.footer = { address: args.footer_address };
|
|
463
|
+
if (!Object.keys(body).length) {
|
|
464
|
+
throw new InputError('Nothing to update: pass at least one of workspace_name, from_name, reply_to or footer_address.');
|
|
465
|
+
}
|
|
466
|
+
const data = await api.request('PATCH', '/account', { body });
|
|
467
|
+
return { lead: 'Account details updated.', data };
|
|
468
|
+
},
|
|
469
|
+
}),
|
|
470
|
+
defineTool({
|
|
471
|
+
name: 'domain_add',
|
|
472
|
+
title: 'Add sending domain',
|
|
473
|
+
scope: 'account',
|
|
474
|
+
description: 'Adds a sending domain (one per workspace) and returns the exact DNS records to create, plus registrar_hint (cloudflare, godaddy, namecheap, route53, vercel or unknown). Uses no quota. Safe to call again: an existing domain returns its current records. If you have a DNS provider tool for that registrar connected, offer to add the records yourself; otherwise show them as a table and point the person to their DNS settings or the Hollerpost dashboard. Then call domain_verify.',
|
|
475
|
+
input: { domain: domainName },
|
|
476
|
+
annotations: WRITE_IDEMPOTENT,
|
|
477
|
+
run: async (api, { domain }) => {
|
|
478
|
+
const data = await api.request('POST', '/domains', { body: { domain } });
|
|
479
|
+
const table = recordTable(data);
|
|
480
|
+
const lead = `Domain ${get(data, 'domain') ?? domain} is ${get(data, 'status') ?? 'pending'} (registrar hint: ${get(data, 'registrar_hint') ?? 'unknown'}). Add these DNS records, then run domain_verify:${table ? `\n\n${table}` : ''}`;
|
|
481
|
+
return { lead, data };
|
|
482
|
+
},
|
|
483
|
+
}),
|
|
484
|
+
defineTool({
|
|
485
|
+
name: 'domain_list',
|
|
486
|
+
title: 'List sending domains',
|
|
487
|
+
scope: 'read',
|
|
488
|
+
description: 'Lists the sending domain and its status (pending, verified or failed) with each DNS record and whether it was found. Free and read only. Check this before drafting: a workspace that must send from its own domain cannot schedule until it is verified.',
|
|
489
|
+
input: {},
|
|
490
|
+
annotations: READ,
|
|
491
|
+
run: async (api) => {
|
|
492
|
+
const data = await api.request('GET', '/domains');
|
|
493
|
+
const list = rows(data);
|
|
494
|
+
const summary = list.length
|
|
495
|
+
? list.map((d) => `${get(d, 'domain')} is ${get(d, 'status')}`).join('; ')
|
|
496
|
+
: 'No sending domain yet. Use domain_add.';
|
|
497
|
+
return { lead: summary, data };
|
|
498
|
+
},
|
|
499
|
+
}),
|
|
500
|
+
defineTool({
|
|
501
|
+
name: 'domain_verify',
|
|
502
|
+
title: 'Verify sending domain',
|
|
503
|
+
scope: 'account',
|
|
504
|
+
description: 'Re-checks the DNS records for a sending domain now and returns, per record, whether it was found plus expected vs actual values. Uses no quota, changes nothing, safe to repeat. DNS changes can take minutes to a few hours to show up; if records are missing right after adding them, wait a bit and try again. Explain any wrong record in plain words.',
|
|
505
|
+
input: { domain: domainName },
|
|
506
|
+
annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
|
|
507
|
+
run: async (api, { domain }) => {
|
|
508
|
+
const data = await api.request('POST', `/domains/${seg(domain)}/verify`, { body: {} });
|
|
509
|
+
const lines = verifyLines(data);
|
|
510
|
+
const lead = `Domain ${get(data, 'domain') ?? domain} is ${get(data, 'status') ?? 'unknown'}.${lines ? `\n${lines}` : ''}`;
|
|
511
|
+
return { lead, data };
|
|
512
|
+
},
|
|
513
|
+
}),
|
|
514
|
+
defineTool({
|
|
515
|
+
name: 'domain_remove',
|
|
516
|
+
title: 'Remove sending domain',
|
|
517
|
+
scope: 'account',
|
|
518
|
+
description: 'Removes the sending domain from this workspace. Destructive: campaigns cannot be scheduled from it afterwards, and adding it back gives new DNS records to set up again. Refused with domain_in_use while a campaign is scheduled on it. Uses no quota. Only call when the person explicitly asked to remove this exact domain.',
|
|
519
|
+
input: {
|
|
520
|
+
domain: domainName,
|
|
521
|
+
confirm: z.literal(true).describe('Must be true, and only after the person explicitly asked to remove this domain.'),
|
|
522
|
+
},
|
|
523
|
+
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
|
|
524
|
+
run: async (api, { domain }) => {
|
|
525
|
+
const data = await api.request('DELETE', `/domains/${seg(domain)}`);
|
|
526
|
+
return { lead: `Domain ${domain} removed.`, data };
|
|
527
|
+
},
|
|
528
|
+
}),
|
|
529
|
+
defineTool({
|
|
530
|
+
name: 'billing_portal_link',
|
|
531
|
+
title: 'Billing portal link',
|
|
532
|
+
scope: 'account',
|
|
533
|
+
description: 'Returns a short-lived link to the Stripe billing portal for the person to open in their browser, where they can change plan, update a card or buy send packs. This is the only billing tool: you never change plans or buy anything yourself. Free; changes nothing. The link expires, so get a fresh one when needed and do not store it.',
|
|
534
|
+
input: {},
|
|
535
|
+
annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: false },
|
|
536
|
+
run: async (api) => {
|
|
537
|
+
const data = await api.request('GET', '/billing/portal');
|
|
538
|
+
return { lead: `Billing portal link for the person to open: ${get(data, 'url') ?? 'unavailable'}`, data };
|
|
539
|
+
},
|
|
540
|
+
}),
|
|
541
|
+
];
|
|
542
|
+
export const TOOL_NAMES = TOOLS.map((t) => t.name);
|
|
543
|
+
/** Run one tool and turn its outcome (or failure) into an MCP result. */
|
|
544
|
+
export async function runTool(def, api, args) {
|
|
545
|
+
try {
|
|
546
|
+
const outcome = await def.run(api, (args ?? {}));
|
|
547
|
+
return okResult(outcome.lead, outcome.data, api.secrets);
|
|
548
|
+
}
|
|
549
|
+
catch (err) {
|
|
550
|
+
return errorResult(err, api.secrets);
|
|
551
|
+
}
|
|
552
|
+
}
|
|
553
|
+
export function registerTools(server, api) {
|
|
554
|
+
for (const def of TOOLS) {
|
|
555
|
+
server.registerTool(def.name, {
|
|
556
|
+
title: def.title,
|
|
557
|
+
description: `${def.description} Requires API key scope: ${def.scope}.`,
|
|
558
|
+
inputSchema: z.object(def.input),
|
|
559
|
+
annotations: { title: def.title, ...def.annotations },
|
|
560
|
+
}, async (args) => runTool(def, api, args));
|
|
561
|
+
}
|
|
562
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export declare const VERSION = "0.1.0";
|
package/dist/version.js
ADDED
package/package.json
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "hollerpost-mcp",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "MCP server for Hollerpost: let your own AI agent draft, preview, schedule and report on email campaigns in your Hollerpost workspace.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"bin": {
|
|
8
|
+
"hollerpost-mcp": "dist/stdio.js"
|
|
9
|
+
},
|
|
10
|
+
"main": "dist/server.js",
|
|
11
|
+
"files": [
|
|
12
|
+
"dist",
|
|
13
|
+
"README.md"
|
|
14
|
+
],
|
|
15
|
+
"engines": {
|
|
16
|
+
"node": ">=20"
|
|
17
|
+
},
|
|
18
|
+
"keywords": [
|
|
19
|
+
"mcp",
|
|
20
|
+
"model-context-protocol",
|
|
21
|
+
"hollerpost",
|
|
22
|
+
"email",
|
|
23
|
+
"newsletter"
|
|
24
|
+
],
|
|
25
|
+
"homepage": "https://hollerpost.com/docs/mcp/",
|
|
26
|
+
"scripts": {
|
|
27
|
+
"build": "tsc -p tsconfig.build.json && chmod +x dist/stdio.js",
|
|
28
|
+
"typecheck": "tsc --noEmit -p tsconfig.json",
|
|
29
|
+
"test": "vitest run",
|
|
30
|
+
"dev": "wrangler dev",
|
|
31
|
+
"start:stdio": "node dist/stdio.js",
|
|
32
|
+
"inspect:stdio": "npm run build && npx @modelcontextprotocol/inspector@2.9.0 --cli -e HOLLERPOST_KEY=hp_live_dummy --method tools/list --strict node dist/stdio.js",
|
|
33
|
+
"e2e": "tsx test/e2e.ts",
|
|
34
|
+
"prepublishOnly": "npm run typecheck && npm test && npm run build"
|
|
35
|
+
},
|
|
36
|
+
"dependencies": {
|
|
37
|
+
"@modelcontextprotocol/sdk": "1.32.0",
|
|
38
|
+
"zod": "4.6.5"
|
|
39
|
+
},
|
|
40
|
+
"devDependencies": {
|
|
41
|
+
"@cfworker/json-schema": "4.1.1",
|
|
42
|
+
"@types/node": "26.6.4",
|
|
43
|
+
"tsx": "4.23.15",
|
|
44
|
+
"typescript": "6.0.3",
|
|
45
|
+
"vitest": "5.0.3",
|
|
46
|
+
"wrangler": "4.147.0"
|
|
47
|
+
}
|
|
48
|
+
}
|