hollerpost-mcp 0.1.1 → 0.2.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 +31 -0
- package/README.md +10 -5
- package/dist/format.js +28 -1
- package/dist/prompts.js +1 -1
- package/dist/server.js +1 -0
- package/dist/tools.js +156 -7
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +3 -2
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.2.0 (2026-10-27)
|
|
4
|
+
|
|
5
|
+
- Surveys: `survey_create` makes a draft survey and `survey_update` edits,
|
|
6
|
+
opens or closes one. `campaign_draft` and `campaign_update` take an
|
|
7
|
+
optional `survey: { survey_id, question_id }` to ask one rating, NPS or
|
|
8
|
+
single-choice question that readers answer with one click
|
|
9
|
+
(`survey: null` removes it). `surveys_list` now returns each question's
|
|
10
|
+
id, options and whether it can go in an email (`one_click`).
|
|
11
|
+
- Clear messages for `survey_not_open`, `monthly_quota_exceeded`,
|
|
12
|
+
`question_not_one_click` and the other survey errors.
|
|
13
|
+
- SMS: `sms_setup_status` reports the toll-free number registration, its
|
|
14
|
+
checklist and how to fix a rejection.
|
|
15
|
+
- Clearer `setup_incomplete` errors: what's missing and how to verify the
|
|
16
|
+
sending domain.
|
|
17
|
+
- Wording follows the Hollerpost Free plan (no trial).
|
|
18
|
+
- 29 tools.
|
|
19
|
+
|
|
20
|
+
## 0.1.2 (2026-10-07)
|
|
21
|
+
|
|
22
|
+
- `campaign_stats` reads the nested stats the API returns.
|
|
23
|
+
|
|
24
|
+
## 0.1.1 (2026-10-07)
|
|
25
|
+
|
|
26
|
+
- README: both key prefixes (`hp_live_` and `uc_live_`).
|
|
27
|
+
|
|
28
|
+
## 0.1.0 (2026-10-04)
|
|
29
|
+
|
|
30
|
+
- First release: 24 tools, 4 resources and 5 prompts, over stdio (`npx
|
|
31
|
+
hollerpost-mcp`) and the remote server at mcp.hollerpost.com.
|
package/README.md
CHANGED
|
@@ -109,15 +109,15 @@ If a tool needs a scope the key lacks, the tool answers `insufficient_scope`, na
|
|
|
109
109
|
|
|
110
110
|
| Tool | Scope | What it does |
|
|
111
111
|
|---|---|---|
|
|
112
|
-
| `workspace_info` | read | Who this key is: workspace, plan,
|
|
112
|
+
| `workspace_info` | read | Who this key is: workspace, plan, scopes, brand. Start here |
|
|
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
116
|
| `segments_list` | read | Tags with subscribed counts, for choosing an audience |
|
|
117
117
|
| `contacts_search` | read | Find contacts by email, status or tag |
|
|
118
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 |
|
|
119
|
+
| `campaign_draft` | draft | Create a draft from a template, content blocks and an audience, optionally with one survey question. Sends nothing |
|
|
120
|
+
| `campaign_update` | draft | Edit a draft, including adding or removing its survey question |
|
|
121
121
|
| `campaign_preview` | draft | Rendered text, live audience count, quota after sending, warnings |
|
|
122
122
|
| `campaign_send_test` | draft | Test copy to up to 3 workspace users |
|
|
123
123
|
| `campaign_schedule` | send | Schedule a draft (`confirm: true` and `expected_audience_count` required) |
|
|
@@ -126,12 +126,17 @@ If a tool needs a scope the key lacks, the tool answers `insufficient_scope`, na
|
|
|
126
126
|
| `campaign_stats` | read | Delivered, opens, clicks, bounces, unsubscribes, top links |
|
|
127
127
|
| `email_send` | send | One transactional email (receipt, reply). `idempotency_key` required |
|
|
128
128
|
| `events_recent` | read | Recent bounces, complaints or deliveries |
|
|
129
|
-
| `account_get` | read | Plan, quota,
|
|
129
|
+
| `account_get` | read | Plan, quota, period end, send packs |
|
|
130
130
|
| `account_update` | account | Workspace name, from name, reply-to, footer address |
|
|
131
131
|
| `domain_add` | account | Add the sending domain; returns the DNS records and a registrar hint |
|
|
132
132
|
| `domain_list` | read | Sending domain status and per-record checks |
|
|
133
133
|
| `domain_verify` | account | Re-check DNS now; expected vs actual for every record |
|
|
134
134
|
| `domain_remove` | account | Remove the sending domain (`confirm: true` required) |
|
|
135
|
+
| `sms_setup_status` | read | Texting setup: toll-free number registration status, checklist, check results and rejection fixes |
|
|
136
|
+
| `surveys_list` | read | Surveys with status, questions (and which can go in an email), response counts and share links |
|
|
137
|
+
| `survey_results` | read | Aggregated answers, averages and NPS for one survey |
|
|
138
|
+
| `survey_create` | draft | Create a draft survey (1 to 30 questions) |
|
|
139
|
+
| `survey_update` | draft | Edit a survey, or open or close it |
|
|
135
140
|
| `billing_portal_link` | account | A short-lived Stripe portal link for the person to open |
|
|
136
141
|
|
|
137
142
|
Resources (context a client can attach without a tool call): `hollerpost://brand`, `hollerpost://templates`, `hollerpost://quota`, `hollerpost://domains`.
|
|
@@ -214,7 +219,7 @@ Add `HOLLERPOST_MCP_URL=https://mcp.hollerpost.com/mcp` to go through the deploy
|
|
|
214
219
|
## Layout
|
|
215
220
|
|
|
216
221
|
```
|
|
217
|
-
src/tools.ts the
|
|
222
|
+
src/tools.ts the 29 tools: schemas, descriptions, handlers (transport agnostic)
|
|
218
223
|
src/client.ts fetch wrapper: auth passthrough, 429 retry, User-Agent, key redaction
|
|
219
224
|
src/format.ts tool results, 50-row truncation, API error messages
|
|
220
225
|
src/resources.ts hollerpost://brand, templates, quota, domains
|
package/dist/format.js
CHANGED
|
@@ -88,6 +88,15 @@ export function describeApiError(err) {
|
|
|
88
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
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
90
|
}
|
|
91
|
+
case 'setup_incomplete': {
|
|
92
|
+
const words = { business_name: 'a business name', physical_address: 'a mailing address', sending_domain: 'a verified sending domain' };
|
|
93
|
+
const missing = Array.isArray(b.missing) ? b.missing.map((m) => words[m] || m) : [];
|
|
94
|
+
const list = missing.length ? missing.join(', ') : 'business name, mailing address and sending domain';
|
|
95
|
+
const domainStep = Array.isArray(b.missing) && b.missing.includes('sending_domain')
|
|
96
|
+
? ' For the domain, domain_add gives the DNS records; once they are added, domain_verify until it reports verified.'
|
|
97
|
+
: '';
|
|
98
|
+
return `${head} Nothing was sent. This workspace can't send until setup is finished. Missing: ${list}. The business name and mailing address are set in the dashboard under Settings.${domainStep} Tell the person what is missing; don't retry until it's done.`;
|
|
99
|
+
}
|
|
91
100
|
case 'sending_domain_required':
|
|
92
101
|
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
102
|
case 'campaign_locked':
|
|
@@ -99,7 +108,25 @@ export function describeApiError(err) {
|
|
|
99
108
|
case 'recipient_suppressed':
|
|
100
109
|
return `${head} This address unsubscribed, bounced or complained before, so it cannot be added or mailed. That is permanent by design.`;
|
|
101
110
|
case 'trial_import_cap':
|
|
102
|
-
return `${head} The
|
|
111
|
+
return `${head} The contact limit for a workspace without a paid plan${b.limit !== undefined ? ` (${num(b.limit)})` : ''} is reached. It lifts after the first campaign is reviewed, or when the workspace picks a paid plan (billing_portal_link gives the person a link).`;
|
|
112
|
+
case 'monthly_quota_exceeded':
|
|
113
|
+
return `${head} Nothing was sent. This month\u2019s emails are used up${b.quota !== undefined ? ` (${num(b.used)} of ${num(b.quota)})` : ''}. New sends wait until the month resets, or the person can add a send pack or move up a plan in the browser (billing_portal_link). You cannot buy anything through these tools.`;
|
|
114
|
+
case 'survey_not_open': {
|
|
115
|
+
const id = typeof b.survey_id === 'string' ? ` ${b.survey_id}` : '';
|
|
116
|
+
return `${head} Nothing was sent. The email asks a question from survey${id}, which is not open. Open it with survey_update (status "open"), or remove the question with campaign_update (survey: null), then try again.`;
|
|
117
|
+
}
|
|
118
|
+
case 'survey_not_found':
|
|
119
|
+
return `${head} That survey does not exist in this workspace. Check the id with surveys_list.`;
|
|
120
|
+
case 'question_not_found':
|
|
121
|
+
return `${head} That question id is not in the survey. Get the question ids from surveys_list.`;
|
|
122
|
+
case 'question_not_one_click':
|
|
123
|
+
return `${head} Only rating, nps and single-choice questions can be answered from inside an email. Pick a question with one_click: true from surveys_list, or link to the survey page instead.`;
|
|
124
|
+
case 'invalid_survey': {
|
|
125
|
+
const errs = Array.isArray(b.errors) ? ` ${b.errors.join(' ')}` : typeof b.reason === 'string' ? ` ${b.reason}` : '';
|
|
126
|
+
return `${head} The survey was not saved.${errs}`;
|
|
127
|
+
}
|
|
128
|
+
case 'surveys_not_enabled':
|
|
129
|
+
return `${head} Surveys are not turned on for this workspace yet. Ask the person to contact support@hollerpost.com.`;
|
|
103
130
|
case 'not_found':
|
|
104
131
|
return `${head} That item does not exist in this workspace. Check the id with the matching list tool.`;
|
|
105
132
|
case 'network_error':
|
package/dist/prompts.js
CHANGED
|
@@ -57,7 +57,7 @@ export const PROMPTS = [
|
|
|
57
57
|
build: (a) => [
|
|
58
58
|
'Set up my Hollerpost workspace with me, one step at a time. Wait for my answer where a step needs one.',
|
|
59
59
|
'',
|
|
60
|
-
'1. Call workspace_info and account_get. Tell me the plan
|
|
60
|
+
'1. Call workspace_info and account_get. Tell me the plan and which scopes this key has. If a scope you need is missing, tell me which and where to enable it.',
|
|
61
61
|
a.domain
|
|
62
62
|
? `2. Call domain_add for ${a.domain}.`
|
|
63
63
|
: '2. Ask which domain I want to send from (a subdomain like mail.mybusiness.com is a good choice), then call domain_add.',
|
package/dist/server.js
CHANGED
|
@@ -11,6 +11,7 @@ export const SERVER_INSTRUCTIONS = [
|
|
|
11
11
|
'Start with workspace_info to learn the plan, the key scopes and the brand voice.',
|
|
12
12
|
'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.',
|
|
13
13
|
'A workspace first campaign is held for a one-time human review (review_pending): it is not sent yet, do not retry.',
|
|
14
|
+
'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.',
|
|
14
15
|
'Only add contacts who agreed to receive email. No tool can change billing; billing_portal_link gives the person a link.',
|
|
15
16
|
].join(' ');
|
|
16
17
|
export function createServer(client, options = {}) {
|
package/dist/tools.js
CHANGED
|
@@ -52,6 +52,45 @@ const audienceSchema = z
|
|
|
52
52
|
])
|
|
53
53
|
.describe('Who gets it: {"tags": ["vip"]} for tagged contacts, or {"all": true} for every subscribed contact.');
|
|
54
54
|
const campaignStatus = z.enum(['draft', 'scheduled', 'sending', 'sent', 'held_for_review', 'canceled']);
|
|
55
|
+
const surveyId = z.string().min(1).describe('Survey id, as returned by survey_create or surveys_list.');
|
|
56
|
+
const surveyRef = z
|
|
57
|
+
.object({
|
|
58
|
+
survey_id: surveyId,
|
|
59
|
+
question_id: z
|
|
60
|
+
.string()
|
|
61
|
+
.min(1)
|
|
62
|
+
.describe('Id of one question in that survey. Only rating, nps and single-choice questions (one_click: true) can be answered from an email.'),
|
|
63
|
+
})
|
|
64
|
+
.describe('Ask one survey question in the email; readers answer with one click. The survey must be open (survey_update with status "open") before the campaign can be test-sent or scheduled.');
|
|
65
|
+
const questionSchema = z.object({
|
|
66
|
+
id: z
|
|
67
|
+
.string()
|
|
68
|
+
.regex(/^[A-Za-z0-9_-]{1,40}$/)
|
|
69
|
+
.optional()
|
|
70
|
+
.describe('Keep a question\u2019s existing id when editing so earlier answers stay matched. Leave out for new questions.'),
|
|
71
|
+
type: z
|
|
72
|
+
.enum(['rating', 'nps', 'single', 'multi', 'text', 'long_text'])
|
|
73
|
+
.describe('rating (1 to 5 stars, or up to 10), nps (0 to 10 recommend score), single (pick one), multi (pick any), text (one line), long_text (paragraph). Only rating, nps and single can be answered from inside an email.'),
|
|
74
|
+
prompt: z.string().min(1).max(300).describe('The question as the reader sees it.'),
|
|
75
|
+
required: z.boolean().optional().describe('Defaults to true.'),
|
|
76
|
+
scale: z
|
|
77
|
+
.object({
|
|
78
|
+
max: z.number().int().min(3).max(10).optional().describe('Top of a rating scale (default 5). Ignored for nps.'),
|
|
79
|
+
labels: z.array(z.string().max(40)).max(2).optional().describe('Up to two end labels, for example ["Poor", "Great"].'),
|
|
80
|
+
})
|
|
81
|
+
.optional(),
|
|
82
|
+
options: z
|
|
83
|
+
.array(z.object({
|
|
84
|
+
key: z.string().regex(/^[a-z0-9_-]{1,40}$/).optional().describe('Short stable key, for example "yes". Made up when left out.'),
|
|
85
|
+
label: z.string().min(1).max(120).describe('What the reader sees.'),
|
|
86
|
+
tags: z.array(z.string().min(1).max(60)).max(5).optional().describe('Tags added to a contact who picks this option.'),
|
|
87
|
+
}))
|
|
88
|
+
.min(2)
|
|
89
|
+
.max(20)
|
|
90
|
+
.optional()
|
|
91
|
+
.describe('Choices for single and multi questions (2 to 20).'),
|
|
92
|
+
});
|
|
93
|
+
const surveyStatus = z.enum(['draft', 'open', 'closed']);
|
|
55
94
|
// ---------------------------------------------------------------------------
|
|
56
95
|
// Result helpers
|
|
57
96
|
function rows(data) {
|
|
@@ -101,13 +140,13 @@ function verifyLines(domain) {
|
|
|
101
140
|
.join('\n');
|
|
102
141
|
}
|
|
103
142
|
// ---------------------------------------------------------------------------
|
|
104
|
-
// The
|
|
143
|
+
// The 27 tools
|
|
105
144
|
export const TOOLS = [
|
|
106
145
|
defineTool({
|
|
107
146
|
name: 'workspace_info',
|
|
108
147
|
title: 'Workspace info',
|
|
109
148
|
scope: 'read',
|
|
110
|
-
description: 'Start here. Returns who this key belongs to: workspace name, plan,
|
|
149
|
+
description: 'Start here. Returns who this key belongs to: workspace name, plan, 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
150
|
input: {},
|
|
112
151
|
annotations: READ,
|
|
113
152
|
run: async (api) => {
|
|
@@ -228,7 +267,7 @@ export const TOOLS = [
|
|
|
228
267
|
name: 'campaign_draft',
|
|
229
268
|
title: 'Draft campaign',
|
|
230
269
|
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.',
|
|
270
|
+
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. Optionally ask one survey question (survey) that readers answer with one click. Returns the id, audience_count and a preview_url to share with the person. Next step: campaign_preview, then campaign_send_test.',
|
|
232
271
|
input: {
|
|
233
272
|
name: z.string().min(1).max(200).describe('Internal campaign name (recipients do not see it).'),
|
|
234
273
|
template_id: z.string().min(1).describe('Template id from templates_list.'),
|
|
@@ -236,6 +275,7 @@ export const TOOLS = [
|
|
|
236
275
|
preheader: z.string().max(200).optional().describe('Preview text shown after the subject in most inboxes.'),
|
|
237
276
|
blocks: blocksSchema,
|
|
238
277
|
audience: audienceSchema,
|
|
278
|
+
survey: surveyRef.optional(),
|
|
239
279
|
},
|
|
240
280
|
annotations: WRITE_SAFE,
|
|
241
281
|
run: async (api, args) => {
|
|
@@ -248,6 +288,8 @@ export const TOOLS = [
|
|
|
248
288
|
};
|
|
249
289
|
if (args.preheader !== undefined)
|
|
250
290
|
body.preheader = args.preheader;
|
|
291
|
+
if (args.survey !== undefined)
|
|
292
|
+
body.survey = args.survey;
|
|
251
293
|
const data = await api.request('POST', '/campaigns', { body });
|
|
252
294
|
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
295
|
return { lead, data };
|
|
@@ -257,7 +299,7 @@ export const TOOLS = [
|
|
|
257
299
|
name: 'campaign_update',
|
|
258
300
|
title: 'Update draft',
|
|
259
301
|
scope: 'draft',
|
|
260
|
-
description: 'Edits a campaign while it is still a draft: any of name, template, subject, preheader, blocks or
|
|
302
|
+
description: 'Edits a campaign while it is still a draft: any of name, template, subject, preheader, blocks, audience or the survey question. Fields you leave out stay as they are; blocks you pass replace the whole blocks object; survey null removes the question. Uses no quota and sends nothing. Refused with campaign_locked once the campaign is scheduled or sent. Run campaign_preview again after editing.',
|
|
261
303
|
input: {
|
|
262
304
|
id: campaignId,
|
|
263
305
|
name: z.string().min(1).max(200).optional().describe('New internal name.'),
|
|
@@ -266,12 +308,13 @@ export const TOOLS = [
|
|
|
266
308
|
preheader: z.string().max(200).optional().describe('New preview text.'),
|
|
267
309
|
blocks: blocksSchema.optional(),
|
|
268
310
|
audience: audienceSchema.optional(),
|
|
311
|
+
survey: surveyRef.nullable().optional().describe('Set the survey question, or null to remove it.'),
|
|
269
312
|
},
|
|
270
313
|
annotations: WRITE_IDEMPOTENT,
|
|
271
314
|
run: async (api, { id, ...rest }) => {
|
|
272
315
|
const body = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined));
|
|
273
316
|
if (!Object.keys(body).length) {
|
|
274
|
-
throw new InputError('Nothing to update: pass at least one of name, template_id, subject, preheader, blocks or
|
|
317
|
+
throw new InputError('Nothing to update: pass at least one of name, template_id, subject, preheader, blocks, audience or survey.');
|
|
275
318
|
}
|
|
276
319
|
const data = await api.request('PATCH', `/campaigns/${seg(id)}`, { body });
|
|
277
320
|
return { lead: `Draft ${id} updated. Run campaign_preview again before testing or scheduling.`, data };
|
|
@@ -371,7 +414,9 @@ export const TOOLS = [
|
|
|
371
414
|
annotations: READ,
|
|
372
415
|
run: async (api, { id }) => {
|
|
373
416
|
const data = await api.request('GET', `/campaigns/${seg(id)}/stats`);
|
|
374
|
-
|
|
417
|
+
// The API nests the numbers under `stats`.
|
|
418
|
+
const st = get(data, 'stats') ?? data;
|
|
419
|
+
const lead = `Stats for ${id}: sent ${get(st, 'sent') ?? 0}, delivered ${get(st, 'delivered') ?? 0}, opened ${get(st, 'opened') ?? 0}, clicked ${get(st, 'clicked') ?? 0}, bounced ${get(st, 'bounced') ?? 0}, unsubscribed ${get(st, 'unsubscribed') ?? 0}.`;
|
|
375
420
|
return { lead, data };
|
|
376
421
|
},
|
|
377
422
|
}),
|
|
@@ -426,7 +471,7 @@ export const TOOLS = [
|
|
|
426
471
|
name: 'account_get',
|
|
427
472
|
title: 'Account and quota',
|
|
428
473
|
scope: 'read',
|
|
429
|
-
description: 'Returns the plan, billing period end, email and SMS quota used and limit,
|
|
474
|
+
description: 'Returns the plan, billing period end, email and SMS quota used and limit, 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
475
|
input: {},
|
|
431
476
|
annotations: READ,
|
|
432
477
|
run: async (api) => {
|
|
@@ -526,6 +571,110 @@ export const TOOLS = [
|
|
|
526
571
|
return { lead: `Domain ${domain} removed.`, data };
|
|
527
572
|
},
|
|
528
573
|
}),
|
|
574
|
+
defineTool({
|
|
575
|
+
name: 'sms_setup_status',
|
|
576
|
+
title: 'Text messaging setup',
|
|
577
|
+
scope: 'read',
|
|
578
|
+
description: 'Returns where this workspace stands on texting: the status of its own toll-free number registration (none, draft, submitted, in_review, rejected or verified), the number, when it was submitted, the checklist the business must meet, the latest website check results, and, after a rejection, a plain explanation with fix steps. Free and read only. Carriers only deliver marketing texts from a toll-free number verified under the business itself, which takes 1 to 2 weeks and sometimes up to a month: never promise a date. Use it to walk the person through the checklist item by item (privacy policy sentence, optional standalone opt-in, sample messages starting with the brand and ending "Reply STOP to opt out"). The form itself is filled and submitted in the dashboard at setup_url; text campaigns cannot be scheduled until status is verified.',
|
|
579
|
+
input: {},
|
|
580
|
+
annotations: READ,
|
|
581
|
+
run: async (api) => {
|
|
582
|
+
const data = await api.request('GET', '/sms/registration');
|
|
583
|
+
const status = get(data, 'status') ?? 'unknown';
|
|
584
|
+
const label = get(get(data, 'status_copy'), 'label');
|
|
585
|
+
const number = get(data, 'phone_number');
|
|
586
|
+
const submitted = get(data, 'submitted_at');
|
|
587
|
+
const parts = [`Text messaging: ${label ?? status} (${status}).`];
|
|
588
|
+
if (number)
|
|
589
|
+
parts.push(`Number ${number}.`);
|
|
590
|
+
if (submitted)
|
|
591
|
+
parts.push(`Submitted ${submitted}.`);
|
|
592
|
+
const explainer = get(get(data, 'rejection'), 'explainer');
|
|
593
|
+
const meaning = get(explainer, 'meaning');
|
|
594
|
+
if (status === 'rejected' && meaning)
|
|
595
|
+
parts.push(`What the carrier means: ${meaning}`);
|
|
596
|
+
const eligibility = get(data, 'eligibility');
|
|
597
|
+
if (get(eligibility, 'eligible') === false && get(eligibility, 'reason'))
|
|
598
|
+
parts.push(`Not available yet: ${get(eligibility, 'reason')}.`);
|
|
599
|
+
parts.push(`Set up or fix it at ${get(data, 'setup_url') ?? 'the dashboard settings'}.`);
|
|
600
|
+
return { lead: parts.join(' '), data };
|
|
601
|
+
},
|
|
602
|
+
}),
|
|
603
|
+
defineTool({
|
|
604
|
+
name: 'surveys_list',
|
|
605
|
+
title: 'List surveys',
|
|
606
|
+
scope: 'read',
|
|
607
|
+
description: 'Lists the workspace’s surveys with status (draft, open or closed), response count, questions (with ids and whether each can be answered from an email) and, when open, the public link to share. Free and read only. Use survey_results for the answers.',
|
|
608
|
+
input: {},
|
|
609
|
+
annotations: READ,
|
|
610
|
+
run: async (api) => {
|
|
611
|
+
const data = await api.request('GET', '/surveys');
|
|
612
|
+
const list = rows(data);
|
|
613
|
+
const lead = list.length
|
|
614
|
+
? list.map((s) => `${get(s, 'name')} (${get(s, 'status')}, ${get(s, 'responses')} responses)`).join('; ')
|
|
615
|
+
: 'No surveys yet. Create one with survey_create, or in the Hollerpost dashboard under Surveys.';
|
|
616
|
+
return { lead, data };
|
|
617
|
+
},
|
|
618
|
+
}),
|
|
619
|
+
defineTool({
|
|
620
|
+
name: 'survey_results',
|
|
621
|
+
title: 'Survey results',
|
|
622
|
+
scope: 'read',
|
|
623
|
+
description: 'Returns aggregated results for one survey: response and completion counts, and per question the answer counts, average rating, NPS (promoters minus detractors) and the latest written answers. No contact identities. Free and read only. Summarize trends in plain words; do not over-read small samples.',
|
|
624
|
+
input: { survey_id: z.string().min(1).describe('Survey id from surveys_list.') },
|
|
625
|
+
annotations: READ,
|
|
626
|
+
run: async (api, { survey_id }) => {
|
|
627
|
+
const data = await api.request('GET', `/surveys/${seg(survey_id)}/results`);
|
|
628
|
+
return { lead: `${get(data, 'name') ?? 'Survey'}: ${get(data, 'total') ?? 0} responses, ${get(data, 'complete') ?? 0} complete.`, data };
|
|
629
|
+
},
|
|
630
|
+
}),
|
|
631
|
+
defineTool({
|
|
632
|
+
name: 'survey_create',
|
|
633
|
+
title: 'Create survey',
|
|
634
|
+
scope: 'draft',
|
|
635
|
+
description: 'Creates a survey as a DRAFT: its page is not public and no email can ask its questions until it is opened with survey_update. Give it a name and 1 to 30 questions. Returns the survey with each question id; one_click questions (rating, nps, single) can go in an email with campaign_draft. Sends nothing and uses no quota.',
|
|
636
|
+
input: {
|
|
637
|
+
name: z.string().min(1).max(120).describe('Survey name, also used as the page title unless title is set.'),
|
|
638
|
+
title: z.string().max(200).optional().describe('Heading on the survey page.'),
|
|
639
|
+
intro: z.string().max(1000).optional().describe('Short intro under the heading.'),
|
|
640
|
+
questions: z.array(questionSchema).min(1).max(30),
|
|
641
|
+
thank_you_message: z.string().max(1000).optional().describe('Shown after someone answers.'),
|
|
642
|
+
},
|
|
643
|
+
annotations: WRITE_SAFE,
|
|
644
|
+
run: async (api, args) => {
|
|
645
|
+
const body = Object.fromEntries(Object.entries(args).filter(([, v]) => v !== undefined));
|
|
646
|
+
const data = await api.request('POST', '/surveys', { body });
|
|
647
|
+
const questions = rows({ data: get(data, 'questions') });
|
|
648
|
+
const lead = `Survey ${get(data, 'id') ?? ''} created as a draft with ${questions.length} question${questions.length === 1 ? '' : 's'}. Open it with survey_update (status "open") before an email asks one of its questions.`;
|
|
649
|
+
return { lead, data };
|
|
650
|
+
},
|
|
651
|
+
}),
|
|
652
|
+
defineTool({
|
|
653
|
+
name: 'survey_update',
|
|
654
|
+
title: 'Update survey',
|
|
655
|
+
scope: 'draft',
|
|
656
|
+
description: 'Edits a survey, or opens or closes it with status. Opening makes the survey page public and lets campaigns that ask its questions be test-sent and scheduled; closing stops new answers. Questions you pass replace the whole list; keep each existing question id so earlier answers stay matched. Fields you leave out stay as they are. Sends nothing.',
|
|
657
|
+
input: {
|
|
658
|
+
survey_id: surveyId,
|
|
659
|
+
status: surveyStatus.optional().describe('"open" to start taking answers, "closed" to stop, "draft" to take it offline.'),
|
|
660
|
+
name: z.string().min(1).max(120).optional(),
|
|
661
|
+
title: z.string().max(200).optional(),
|
|
662
|
+
intro: z.string().max(1000).optional(),
|
|
663
|
+
questions: z.array(questionSchema).min(1).max(30).optional(),
|
|
664
|
+
thank_you_message: z.string().max(1000).optional(),
|
|
665
|
+
},
|
|
666
|
+
annotations: WRITE_IDEMPOTENT,
|
|
667
|
+
run: async (api, { survey_id, ...rest }) => {
|
|
668
|
+
const body = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined));
|
|
669
|
+
if (!Object.keys(body).length) {
|
|
670
|
+
throw new InputError('Nothing to update: pass status or at least one of name, title, intro, questions or thank_you_message.');
|
|
671
|
+
}
|
|
672
|
+
const data = await api.request('PATCH', `/surveys/${seg(survey_id)}`, { body });
|
|
673
|
+
const url = get(data, 'url');
|
|
674
|
+
const lead = `Survey ${survey_id} is ${get(data, 'status') ?? 'updated'}.${url ? ` Public link: ${url}` : ''}`;
|
|
675
|
+
return { lead, data };
|
|
676
|
+
},
|
|
677
|
+
}),
|
|
529
678
|
defineTool({
|
|
530
679
|
name: 'billing_portal_link',
|
|
531
680
|
title: 'Billing portal link',
|
package/dist/version.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const VERSION = "0.
|
|
1
|
+
export declare const VERSION = "0.2.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.2.0';
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "hollerpost-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.2.0",
|
|
4
4
|
"description": "MCP server for Hollerpost: let your own AI agent draft, preview, schedule and report on email campaigns in your Hollerpost workspace.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -10,7 +10,8 @@
|
|
|
10
10
|
"main": "dist/server.js",
|
|
11
11
|
"files": [
|
|
12
12
|
"dist",
|
|
13
|
-
"README.md"
|
|
13
|
+
"README.md",
|
|
14
|
+
"CHANGELOG.md"
|
|
14
15
|
],
|
|
15
16
|
"engines": {
|
|
16
17
|
"node": ">=20"
|