hollerpost-mcp 0.5.0 → 0.7.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 CHANGED
@@ -1,5 +1,59 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.7.0 (2026-11-13)
4
+
5
+ Launchpad through the existing Your page API and scopes, plus the new page looks.
6
+
7
+ - `page_update` theme: `linkStyle` (`button` default, `outline`, `pill`,
8
+ `todo`, `checklist`, `microchip`, `clouds`, `ticket`), `accentColor`,
9
+ `backgroundStyle` (`solid`, `gradient`, `glow`, `dots`, `grid`, `lined`,
10
+ `stripes`, `checker`, `sunburst`), `headingFont`, `layout` (`centered`,
11
+ `left`, `card`) and the larger body font list. The theme replaces the saved
12
+ one, so send every field to keep; the API checks contrast.
13
+
14
+ - `campaign_draft` and `campaign_update` accept an exclusive
15
+ `{ "signup_form_id": "<UUID>" }` audience, discovered in `segments_list`
16
+ `audiences`. It selects confirmed, active, unsuppressed subscribers at
17
+ queue time; drafts never snapshot contact IDs.
18
+ - `launchpad_get` names `confirmed_signups`, `emailable_subscribers` and
19
+ `awaiting_confirmation` in its human-readable output.
20
+ - Waitlist audience requires the L-25 worker and
21
+ `20261111170000_signup_form_campaign_audience.sql`.
22
+ - `launchpad_get` (`read`): the Launchpad card, including confirmed, this
23
+ week, pending, queued, confirmation allowance, list size versus plan emails,
24
+ share URL and mode. Uses the new `GET /api/v1/launchpad` adapter.
25
+ - `launchpad_update` (`draft`): save waitlist copy, count visibility, launch
26
+ note, primary link and waitlist/standard mode. Uses `PATCH /api/v1/page`
27
+ with `X-Hollerpost-Save: draft`; preserves the previous public snapshot
28
+ without publishing changes or taking the page down.
29
+ - `launchpad_go_live` (`draft`): after the person approves the launch note
30
+ and primary link, requires literal `confirm: true` and sends the publish
31
+ confirmation header. Reports `pending_review`, `moderation_status` and
32
+ `owner_reason` plainly, including when an older page remains public.
33
+ - `page_update` also accepts the existing waitlist fields. The API requires
34
+ publish confirmation for `mode: live` as well as `published: true`.
35
+ - Read/write/publication annotations are included in tool listings; server
36
+ instructions retain the person's approval for anything public and explain
37
+ automatic checks/review holds. Field validation errors name the field and
38
+ message; rate limits tell the agent to wait; review holds are not retried.
39
+
40
+ ## 0.6.0 (2026-11-11)
41
+
42
+ Texting setup with an agent, not just status.
43
+
44
+ - `sms_registration_update` (scope `account`): fill or fix the toll-free
45
+ registration form while it's a draft or after a rejection. Business facts
46
+ come from the person; the agent may draft the use case, opt-in description
47
+ and sample messages for approval. The registration number (EIN, or SSN for
48
+ a sole proprietor) can't be set through an agent: it's entered in the
49
+ dashboard.
50
+ - `sms_website_check` (scope `account`): the carrier checks on the form and
51
+ a live look at the website, privacy policy and terms, listed as fixes.
52
+ - `sms_numbers` (scope `account`): toll-free numbers to pick from.
53
+ - `sms_registration_submit` (scope `account`): submit after the person's
54
+ yes (`confirm: true`); the first time it buys the chosen number. Every
55
+ check runs again first, and nothing is sent or bought if one fails.
56
+
3
57
  ## 0.5.0 (2026-11-09)
4
58
 
5
59
  Pictures from the person's own device.
package/README.md CHANGED
@@ -136,13 +136,20 @@ If a tool needs a scope the key lacks, the tool answers `insufficient_scope`, na
136
136
  | `domain_verify` | account | Re-check DNS now; expected vs actual for every record |
137
137
  | `domain_remove` | account | Remove the sending domain (`confirm: true` required) |
138
138
  | `sms_setup_status` | read | Texting setup: toll-free number registration status, checklist, check results and rejection fixes |
139
+ | `sms_registration_update` | account | Fill or fix the texting registration form (draft or rejected only). The registration number is entered in the dashboard only |
140
+ | `sms_website_check` | account | Run the carrier checks on the form and the business's website, privacy policy and terms |
141
+ | `sms_numbers` | account | Toll-free numbers available for the first registration |
142
+ | `sms_registration_submit` | account | Submit (or resubmit after a rejection) after the person says yes; needs `confirm: true`. The first time it also buys the chosen number |
139
143
  | `surveys_list` | read | Surveys with status, questions (and which can go in an email), response counts and share links |
140
144
  | `survey_results` | read | Aggregated answers, averages and NPS for one survey |
141
145
  | `survey_create` | draft | Create a draft survey (1 to 30 questions) |
142
146
  | `survey_update` | draft | Edit a survey, or open or close it |
143
147
  | `billing_portal_link` | account | A short-lived Stripe portal link for the person to open |
144
148
  | `page_get` | read | Read Your page, links, calendar events and plan settings |
145
- | `page_update` | draft | Save page fields via `updates`; publishing changes the public page immediately and needs `confirm_publish: true` after the person approves |
149
+ | `page_update` | draft | Save page fields via `updates`, including waitlist fields; publication needs `confirm_publish: true` after the person approves and may be held for review |
150
+ | `launchpad_get` | read | Read confirmed/this-week/pending/queued counts, confirmation allowance, list size vs plan emails, share URL and mode |
151
+ | `launchpad_update` | draft | Save waitlist headline/pitch, count visibility, launch note, primary link and waitlist/standard mode as a draft; does not publish |
152
+ | `launchpad_go_live` | draft | Request live mode and publication after the person approves the launch note and primary link (`confirm: true`); reports review holds plainly |
146
153
  | `page_link_add` | draft | Add a HTTPS link via `link` (max 30) |
147
154
  | `page_link_update` | draft | Update a link by `id` and `updates` |
148
155
  | `page_link_remove` | draft | Permanently remove a link (`confirm: true`) |
@@ -161,6 +168,49 @@ when no page exists. Claim a handle in the dashboard before publishing.
161
168
  Arrays in page updates replace the existing arrays. The two removal/cancel
162
169
  tools have `destructiveHint: true`; page/event reads have `readOnlyHint: true`.
163
170
 
171
+ Launchpad is a mode of Your page at the same handle, using the same signup
172
+ pipeline. `launchpad_get` uses `GET /api/v1/launchpad`, with the same response
173
+ as the dashboard card, and the existing tenant-key, `read` scope and
174
+ `mcp_enabled` rollout gates. The card has its own 60 reads/minute per workspace
175
+ per Worker isolate limit in addition to the API-key rate limit; a 429 preserves
176
+ `Retry-After` and tells the agent to wait.
177
+
178
+ Waitlist fields already use `PATCH /api/v1/page` (`draft` scope):
179
+ `waitlist_headline` (120 characters), `waitlist_pitch` (2,000), `show_count`
180
+ (boolean), `launch_note` (500), `primary_link_id` (workspace link UUID or null),
181
+ and `mode` (`standard`, `waitlist`, `live`). API validation trims text and checks
182
+ the merged saved page; live mode needs an enabled, safe HTTPS primary link.
183
+ `page_update` accepts these fields in `updates`.
184
+
185
+ `page_update` also accepts `theme.linkStyle`, the look of the page's links:
186
+ `button` (default, solid buttons), `outline`, `pill`, `todo` (to-do list rows
187
+ with an empty box), `checklist` (rows with a ticked box), `microchip`
188
+ (cyberpunk chips), `clouds` or `ticket`. Every style uses the theme colors, and
189
+ the main link and signup button stay solid. Social links show as icons.
190
+
191
+ `launchpad_update` sends `X-Hollerpost-Save: draft` and cannot set live mode.
192
+ That opt-in draft-save header skips publication checks and preserves any
193
+ previous approved public snapshot; it also refuses a `published` field. A
194
+ normal PATCH without that header retains the existing behavior of checking
195
+ and publishing edits to an already-public page. Draft saves do not take it down.
196
+ To publish a waitlist draft after approval, use `page_update` with
197
+ `updates: {published: true}` and `confirm_publish: true`.
198
+
199
+ Before `launchpad_go_live`, use `page_get`, show the person the saved launch
200
+ note and selected primary link's label and URL, and wait for a clear yes.
201
+ The tool then sends `{mode: "live", published: true}` with
202
+ `X-Hollerpost-Confirm: publish`. The API requires that header for
203
+ `published: true` or `mode: "live"`; `page_update` uses `confirm_publish: true`.
204
+ HTTP 200 means saved, not necessarily live: a held response includes
205
+ `pending_review`, `moderation_status` and `owner_reason`. Tell the person the
206
+ changes are held and why; an older approved page can remain public. Never
207
+ retry or bypass a review hold. A 422 names the offending field and message.
208
+
209
+ Launchpad annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`,
210
+ `openWorldHint`, in that order) are `true/false/true/false` for `launchpad_get`,
211
+ `false/false/true/false` for `launchpad_update`, and `false/true/false/true` for
212
+ `launchpad_go_live`.
213
+
164
214
  Resources (context a client can attach without a tool call): `hollerpost://brand`, `hollerpost://templates`, `hollerpost://quota`, `hollerpost://domains`.
165
215
 
166
216
  Prompts: `setup_workspace`, `write_campaign`, `weekly_report`, `fix_domain`, `clean_list`.
@@ -173,6 +223,7 @@ These are built into the server and the API, not left to the agent:
173
223
  - **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.
174
224
  - **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.
175
225
  - **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.
226
+ - **Launchpad approval and checks.** Going live requires the person's approval and literal `confirm: true`. Automatic checks can hold publication for review; the tool reports the held state and owner reason without claiming the launch is live.
176
227
  - **Consent.** Contacts can only be added with `consent: true`, and addresses that unsubscribed, bounced or complained can never be re-added.
177
228
  - **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.
178
229
  - **Almost nothing destructive.** There is no contact delete, campaign delete or webhook delete. `domain_remove`, `page_link_remove` and `event_cancel` require `confirm: true`; domain removal is refused while a campaign is scheduled on the domain. `campaign_cancel` is the undo for a scheduled send.
package/dist/format.d.ts CHANGED
@@ -26,6 +26,12 @@ export interface OkOptions {
26
26
  }
27
27
  export declare function okResult(lead: string, data: unknown, secrets?: string[], opts?: OkOptions): CallToolResult;
28
28
  /** Plain-language explanation for each API error code the tools can hit. */
29
+ /**
30
+ * The problems in a texting-setup check result ({ errors: {field: msg},
31
+ * items: [{ key, level, message }] }), form errors first, then failed
32
+ * website items. Warnings are left out.
33
+ */
34
+ export declare function smsCheckProblems(checks: unknown): string[];
29
35
  export declare function describeApiError(err: ApiError): string;
30
36
  export declare function errorResult(err: unknown, secrets?: string[]): CallToolResult;
31
37
  /** A validation problem the tool catches before calling the API. */
package/dist/format.js CHANGED
@@ -60,9 +60,35 @@ function num(v) {
60
60
  return typeof v === 'number' ? v.toLocaleString('en-US') : String(v ?? 'unknown');
61
61
  }
62
62
  /** Plain-language explanation for each API error code the tools can hit. */
63
+ /**
64
+ * The problems in a texting-setup check result ({ errors: {field: msg},
65
+ * items: [{ key, level, message }] }), form errors first, then failed
66
+ * website items. Warnings are left out.
67
+ */
68
+ export function smsCheckProblems(checks) {
69
+ const c = (checks && typeof checks === 'object' ? checks : {});
70
+ const out = [];
71
+ if (c.errors && typeof c.errors === 'object') {
72
+ for (const [field, msg] of Object.entries(c.errors)) {
73
+ // Agents can't set these; the person enters them in the dashboard.
74
+ const where = field === 'registration_number' || field === 'registration_type' ? ' (the person enters this in the Hollerpost dashboard, not you)' : '';
75
+ out.push(`${field}: ${String(msg)}${where}`);
76
+ }
77
+ }
78
+ if (Array.isArray(c.items)) {
79
+ for (const item of c.items) {
80
+ if (item && item.level === 'fail')
81
+ out.push(String(item.message ?? item.key ?? ''));
82
+ }
83
+ }
84
+ return out;
85
+ }
63
86
  export function describeApiError(err) {
64
87
  const b = err.body;
65
88
  const head = `Hollerpost API error "${err.code}"${err.status ? ` (HTTP ${err.status})` : ''}.`;
89
+ if (err.status === 422 && typeof b.field === 'string') {
90
+ return `${head} ${b.field}: ${typeof b.message === 'string' ? b.message : err.code}`;
91
+ }
66
92
  switch (err.code) {
67
93
  case 'missing_api_key':
68
94
  if (!err.local) {
@@ -80,13 +106,17 @@ export function describeApiError(err) {
80
106
  }
81
107
  case 'rate_limited': {
82
108
  const secs = typeof b.retry_after_seconds === 'number' ? ` Try again in about ${b.retry_after_seconds} seconds.` : '';
83
- return `${head} The key hit its request rate limit and one automatic retry did not clear it.${secs}`;
109
+ return `${head} The request rate limit was reached. Wait before trying again.${secs}`;
84
110
  }
85
111
  case 'image_limit_reached': {
86
112
  const msg = typeof b.message === 'string' ? ` ${b.message}` : '';
87
113
  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
114
  }
115
+ case 'pending_review':
89
116
  case 'review_pending': {
117
+ if (typeof b.owner_reason === 'string' || typeof b.moderation_status === 'string') {
118
+ return `${head} The page changes are held for review; this launch is not live.${typeof b.owner_reason === 'string' ? ` ${b.owner_reason}` : ''} Do not retry or bypass the hold.`;
119
+ }
90
120
  const id = typeof b.campaign_id === 'string' ? ` Campaign ${b.campaign_id}` : ' The campaign';
91
121
  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.`;
92
122
  }
@@ -175,6 +205,24 @@ export function describeApiError(err) {
175
205
  return `${head} Only drafts can be changed or scheduled${typeof b.status === 'string' ? `; this post is ${b.status}` : ''}. Cancel it first to edit it.`;
176
206
  case 'beyond_scheduling_horizon':
177
207
  return `${head} That time is further ahead than this plan can schedule${b.limit_days ? ` (${num(b.limit_days)} days)` : ''}.`;
208
+ case 'field_dashboard_only':
209
+ return `${head} The business registration number (EIN, or SSN for a sole proprietor) is entered in the Hollerpost dashboard only, never through an agent. Ask the person to add it under Settings, Text messaging. Nothing was saved.`;
210
+ case 'confirmation_required':
211
+ return `${head} Nothing was submitted. Show the person what will be sent (sms_setup_status), get a clear yes, then call again with confirm: true.`;
212
+ case 'registration_locked':
213
+ return `${head} The carriers are reviewing this registration${typeof b.status === 'string' ? ` (status ${b.status})` : ''}, so it can't be changed or resubmitted now. One review at a time; the person gets an email when it changes.`;
214
+ case 'sms_not_eligible':
215
+ return `${head} This workspace can't register a number${typeof b.reason === 'string' ? ` (${b.reason})` : ''}. Texting needs a paid plan with the texts, calls or AI receptionist add-on; see billing_portal_link.`;
216
+ case 'checks_failed': {
217
+ const problems = smsCheckProblems(b.checks);
218
+ return `${head} Nothing was submitted and no number was bought: the checks found problems the carriers would reject.${problems.length ? `\n${problems.map((p) => `- ${p}`).join('\n')}` : ''}\nHelp the person fix these (sms_registration_update for the form, their own website for website items), run sms_website_check, then ask again before submitting.`;
219
+ }
220
+ case 'phone_number_required':
221
+ return `${head} The first submission needs a toll-free number. Call sms_numbers, let the person pick one, then submit with phone_number.`;
222
+ case 'number_taken':
223
+ return `${head} Someone else just took that number. Call sms_numbers and let the person pick another.`;
224
+ case 'resubmit_not_allowed':
225
+ return `${head} This rejection is handled with the carrier directly by the Hollerpost team. Don't resubmit; the person will get an email.`;
178
226
  case 'not_available_yet':
179
227
  return `${head} That part of Hollerpost Social comes in a later beta release.`;
180
228
  default: {
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
+ 'Launchpad pages publish after automatic checks and may be held for review; show the person the launch note and primary link and wait for their approval before going live. Anything that goes public needs the person\'s approval.',
15
16
  '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.',
16
17
  '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.',
17
18
  'Only add contacts who agreed to receive email. No tool can change billing; billing_portal_link gives the person a link.',
package/dist/tools.js CHANGED
@@ -11,7 +11,7 @@
11
11
  // formed without them.
12
12
  import { z } from 'zod';
13
13
  import { ApiError } from './client.js';
14
- import { errorResult, InputError, okResult } from './format.js';
14
+ import { errorResult, InputError, okResult, smsCheckProblems } from './format.js';
15
15
  export const DEFAULT_ASSUMED_SCOPES = ['read', 'contacts', 'draft', 'send', 'webhooks', 'account'];
16
16
  export const ALL_SCOPES = [
17
17
  'read',
@@ -84,18 +84,19 @@ const blocksSchema = z
84
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.');
85
85
  const audienceSchema = z
86
86
  .union([
87
+ z.object({ signup_form_id: z.string().uuid().describe('Form UUID from segments_list audiences or page_get. Only confirmed, active, unsuppressed email subscribers from this form, resolved when sending.') }).strict(),
87
88
  z.object({
88
89
  // The API's preview count and schedule both use an overlap match for
89
90
  // API/MCP callers (worker/routes/api-v1.js apiAudienceCount and the
90
91
  // tagsAny option of queueCampaignHandler): a contact with any one of the
91
92
  // listed tags is included. The dashboard keeps its ALL-of match.
92
93
  tags: z.array(z.string().min(1)).min(1).describe('Send to subscribed contacts that have ANY of these tags (one tag is the usual case). Get tags from segments_list.'),
93
- }),
94
+ }).strict(),
94
95
  z.object({
95
96
  all: z.literal(true).describe('Send to every subscribed contact in the workspace.'),
96
- }),
97
+ }).strict(),
97
98
  ])
98
- .describe('Who gets it: {"tags": ["vip"]} for tagged contacts, or {"all": true} for every subscribed contact.');
99
+ .describe('Who gets it: {"tags": ["vip"]} for tagged contacts, or {"all": true} for every subscribed contact, or {"signup_form_id": "<UUID>"} for a waitlist.');
99
100
  const campaignStatus = z.enum(['draft', 'scheduled', 'sending', 'sent', 'held_for_review', 'canceled']);
100
101
  const surveyId = z.string().uuid().describe('Survey id (a UUID), as returned by survey_create or surveys_list.');
101
102
  const surveyRef = z
@@ -209,7 +210,14 @@ function verifyLines(domain) {
209
210
  .join('\n');
210
211
  }
211
212
  // ---------------------------------------------------------------------------
212
- // The 29 tools
213
+ // Tool schemas and definitions
214
+ const launchpadFields = {
215
+ waitlist_headline: z.string().max(120).optional(),
216
+ waitlist_pitch: z.string().max(2000).optional(),
217
+ show_count: z.boolean().optional(),
218
+ launch_note: z.string().max(500).optional(),
219
+ primary_link_id: z.string().uuid().nullable().optional().describe('An enabled, safe HTTPS page link in this workspace. Required for live mode; null clears it.'),
220
+ };
213
221
  const pageLinkSchema = z.object({
214
222
  label: z.string().min(1).max(80), url: z.string().max(2048),
215
223
  thumbnail_url: z.union([z.string().max(2048), z.null()]).optional(), starts_at: z.union([z.string().max(2048), z.null()]).optional(),
@@ -222,19 +230,68 @@ const pageEventSchema = z.object({
222
230
  online_url: z.union([z.string().max(2048), z.null()]).optional(), ticket_url: z.union([z.string().max(2048), z.null()]).optional(), image_url: z.union([z.string().max(2048), z.null()]).optional(),
223
231
  status: z.enum(['draft', 'published', 'canceled']).optional(), show_on_page: z.boolean().optional(),
224
232
  });
233
+ // Your page fonts (L-43). Must match PAGE_FONTS and HEADING_FONTS in the API's
234
+ // src/lib/page/validation.js (worker/page-themes.test.mjs checks).
235
+ const PAGE_BODY_FONTS = ['Nunito Sans', 'Nunito', 'sans-serif', 'serif', 'monospace', 'Arial', 'Georgia', 'Lora', 'Outfit', 'Manrope', 'Bricolage Grotesque', 'Space Mono'];
236
+ const PAGE_HEADING_FONTS = ['body', 'Fraunces', 'Instrument Serif', 'Lora', 'Outfit', 'Manrope', 'Bricolage Grotesque', 'Nunito', 'Nunito Sans', 'Unbounded', 'Caveat', 'Pacifico', 'Space Mono'];
225
237
  const pageUpdateSchema = z.object({
238
+ ...launchpadFields, mode: z.enum(['standard', 'waitlist', 'live']).optional(),
226
239
  title: z.string().max(120).optional(), tagline: z.string().max(240).optional(), avatar_url: z.union([z.string().max(2048), z.null()]).optional(),
227
- theme: z.object({ brandColor: z.string().optional(), backgroundColor: z.string().optional(), textColor: z.string().optional(), buttonTextColor: z.string().optional(), fontFamily: z.string().optional(), buttonRadius: z.number().int().min(0).max(40).optional() }).optional(),
240
+ theme: z.object({ brandColor: z.string().optional(), backgroundColor: z.string().optional(), textColor: z.string().optional(), buttonTextColor: z.string().optional(), fontFamily: z.enum(PAGE_BODY_FONTS).optional().describe('Body text font.'), buttonRadius: z.number().int().min(0).max(40).optional(), linkStyle: z.enum(['button', 'outline', 'pill', 'todo', 'checklist', 'microchip', 'clouds', 'ticket']).optional().describe('How the page links look. button: solid buttons (default). outline: outlined buttons. pill: round pills with an arrow. todo: to-do list rows with an empty box. checklist: rows with a ticked box. microchip: cyberpunk chips with notched corners. clouds: puffy cloud shapes. ticket: admission tickets with notched sides. Colors come from the theme; the main link and signup button stay solid.'), accentColor: z.string().regex(/^#[0-9a-fA-F]{6}$/).optional().describe('Six-digit hex accent for background patterns and details.'), backgroundStyle: z.enum(['solid', 'gradient', 'glow', 'dots', 'grid', 'lined', 'stripes', 'checker', 'sunburst']).optional().describe('Background behind the page. Text keeps 4.5:1 contrast against the pattern too (the API checks).'), headingFont: z.enum(PAGE_HEADING_FONTS).optional().describe('Headline font. body means the same as fontFamily.'), layout: z.enum(['centered', 'left', 'card']).optional().describe('centered, left aligned, or the page on a card over the background.') }).describe('The whole look. Send every field you want to keep: the theme replaces the saved one. A theme without accentColor, backgroundStyle, headingFont and layout keeps the classic look.').optional(),
228
241
  show_badge: z.boolean().optional(), signup_form_id: z.string().uuid().nullable().optional(),
229
242
  socials: z.array(z.object({ network: z.enum(['instagram', 'tiktok', 'facebook', 'youtube', 'x', 'threads', 'bluesky', 'linkedin', 'pinterest', 'snapchat', 'twitch', 'discord', 'whatsapp', 'spotify', 'website']), url: z.string() })).max(15).optional(),
230
243
  info: z.object({ website: z.union([z.string().max(2048), z.null()]).optional(), phone: z.string().optional(), email: z.string().optional(), address_mode: z.enum(['none', 'city', 'full']).optional(), hours: z.string().optional() }).optional(),
231
244
  show_events: z.boolean().optional(), published: z.boolean().optional(),
232
245
  });
233
246
  const PAGE_DESTRUCTIVE = { ...WRITE_IDEMPOTENT, destructiveHint: true };
247
+ function launchpadPublicationLead(data) {
248
+ const status = get(data, 'moderation_status');
249
+ if (get(data, 'pending_review') === true || status === 'pending_review' || status === 'review_pending' || status === 'rejected' || status === 'unpublished') {
250
+ const reason = get(data, 'owner_reason') || get(data, 'moderation_reason');
251
+ return `Launchpad changes are saved and held${status === 'rejected' ? ' after review' : ' for review'}; this launch is not live.${reason ? ` ${reason}` : ''} An older approved page may still be public. Do not retry or bypass the hold.`;
252
+ }
253
+ return get(data, 'published') === true && status === 'published'
254
+ ? 'Launchpad is live: the automatic publication checks passed.'
255
+ : 'Launchpad changes saved; publication is not confirmed. Check page_get before saying the launch is live.';
256
+ }
234
257
  export const TOOLS = [
258
+ defineTool({
259
+ name: 'launchpad_get', title: 'Get Launchpad', scope: 'read',
260
+ description: 'Read the Launchpad card: confirmed_signups, emailable_subscribers, awaiting_confirmation, confirmed this week and queued confirmations, confirmation allowance, list size versus plan emails, share URL and page mode. Launchpad is a mode of Your page.',
261
+ input: {}, annotations: READ, untrusted: true,
262
+ run: async (api) => {
263
+ const data = await api.request('GET', '/launchpad');
264
+ return { lead: `Launchpad: confirmed_signups=${get(data, 'confirmed_signups') ?? 'unavailable'}, emailable_subscribers=${get(data, 'emailable_subscribers') ?? 'unavailable'}, awaiting_confirmation=${get(data, 'awaiting_confirmation') ?? 'unavailable'}.`, data };
265
+ },
266
+ }),
267
+ defineTool({
268
+ name: 'launchpad_update', title: 'Update Launchpad draft', scope: 'draft',
269
+ description: 'Save Launchpad headline, pitch, count visibility, launch note, primary link or mode (waitlist or standard). Omitted fields stay unchanged. Saves a draft only, including when an older approved page is public. Does not publish. Use page_get to read the saved launch note and primary link before asking the person to go live.',
270
+ input: { ...launchpadFields, mode: z.enum(['waitlist', 'standard']).optional() },
271
+ annotations: WRITE_IDEMPOTENT, untrusted: true,
272
+ run: async (api, args) => {
273
+ const body = Object.fromEntries(Object.entries(args).filter(([, v]) => v !== undefined));
274
+ if (!Object.keys(body).length)
275
+ throw new InputError('Nothing to update: pass at least one Launchpad field.');
276
+ const data = await api.request('PATCH', '/page', { body, headers: { 'X-Hollerpost-Save': 'draft' } });
277
+ return { lead: 'Launchpad draft saved. These changes have not been published.', data };
278
+ },
279
+ }),
280
+ defineTool({
281
+ name: 'launchpad_go_live', title: 'Launchpad go live', scope: 'draft',
282
+ description: 'Switch Your page to live mode and request publication after automatic checks. First use page_get, show the person the saved launch note and primary link (label and URL), and wait for a clear yes. Requires confirm: true after that approval and a claimed handle with an enabled safe HTTPS primary link. A pending_review or review_pending hold is not live: explain owner_reason, do not retry or bypass review. Sends no campaign.',
283
+ input: { confirm: z.literal(true).describe('true only after the person saw the launch note and primary link and approved going live.') },
284
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true }, untrusted: true,
285
+ run: async (api, { confirm }) => {
286
+ if (confirm !== true)
287
+ throw new InputError('Going live requires confirm: true after the person approves the launch note and primary link.');
288
+ const data = await api.request('PATCH', '/page', { body: { mode: 'live', published: true }, headers: { 'X-Hollerpost-Confirm': 'publish' } });
289
+ return { lead: launchpadPublicationLead(data), data };
290
+ },
291
+ }),
235
292
  defineTool({ name: 'page_get', title: 'Get Your page', scope: 'read', description: 'Read Your page, links, events, handle and plan settings. An unsaved draft from the brand kit is returned if no page exists.', input: {}, annotations: READ, untrusted: true,
236
293
  run: async (api) => ({ lead: 'Your page and workspace settings.', data: await api.request('GET', '/page') }) }),
237
- defineTool({ name: 'page_update', title: 'Update Your page', scope: 'draft', description: 'Update Your page fields. Arrays replace existing values. Publishing (published: true) changes the public page immediately: ask the person first and pass confirm_publish: true. Requires a claimed handle; Free must show the badge. HTTPS destinations and contrast are enforced by the API.', input: { updates: pageUpdateSchema, confirm_publish: z.literal(true).optional().describe('true only after the person explicitly approved publishing; required whenever this call publishes.') }, annotations: WRITE_IDEMPOTENT, untrusted: true,
294
+ defineTool({ name: 'page_update', title: 'Update Your page', scope: 'draft', description: 'Update Your page fields, including Launchpad waitlist fields. Arrays replace existing values. Publishing (published: true or mode: live) needs the person\'s approval and confirm_publish: true. Automatic checks may hold changes for review; inspect pending_review, moderation_status and owner_reason before claiming publication. Requires a claimed handle; Free must show the badge. HTTPS destinations and contrast are enforced by the API.', input: { updates: pageUpdateSchema, confirm_publish: z.literal(true).optional().describe('true only after the person explicitly approved publishing; required whenever this call publishes.') }, annotations: WRITE_IDEMPOTENT, untrusted: true,
238
295
  run: async (api, { updates, confirm_publish }) => ({ lead: 'Your page updated.', data: await api.request('PATCH', '/page', { body: updates, ...(confirm_publish ? { headers: { 'X-Hollerpost-Confirm': 'publish' } } : {}) }) }) }),
239
296
  defineTool({ name: 'page_link_add', title: 'Add page link', scope: 'draft', description: 'Add a HTTPS link to Your page (maximum 30). Known URL shorteners are refused. Visible immediately on published pages unless disabled or scheduled.', input: { link: pageLinkSchema }, annotations: WRITE_SAFE, untrusted: true,
240
297
  run: async (api, { link }) => ({ lead: 'Page link added.', data: await api.request('POST', '/page/links', { body: link }) }) }),
@@ -377,7 +434,7 @@ export const TOOLS = [
377
434
  name: 'segments_list',
378
435
  title: 'List segments',
379
436
  scope: 'read',
380
- 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.',
437
+ description: 'Lists contact tags and built-in waitlist audiences (signup_form_id) with subscribed counts. Free and read only. Use it to choose a campaign audience by tag or signup_form_id and to tell the person roughly how many people a send reaches.',
381
438
  input: {},
382
439
  annotations: READ,
383
440
  run: async (api) => {
@@ -753,7 +810,7 @@ export const TOOLS = [
753
810
  name: 'sms_setup_status',
754
811
  title: 'Text messaging setup',
755
812
  scope: 'read',
756
- 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.',
813
+ 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 saved form (registration number masked), 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"). With the account scope you can fill and fix the form (sms_registration_update), run the checks (sms_website_check) and submit after a yes (sms_registration_submit); the registration number is always entered in the dashboard at setup_url. Text campaigns cannot be scheduled until status is verified.',
757
814
  input: {},
758
815
  annotations: READ,
759
816
  run: async (api) => {
@@ -778,6 +835,100 @@ export const TOOLS = [
778
835
  return { lead: parts.join(' '), data };
779
836
  },
780
837
  }),
838
+ defineTool({
839
+ name: 'sms_registration_update',
840
+ title: 'Fill or fix the texting registration',
841
+ scope: 'account',
842
+ description: 'Saves fields of the toll-free texting registration as a draft (only while it is a draft or was rejected; never while the carriers review it). Send only the fields you are changing. Every fact must come from the person: ask for the legal name, entity type, address, contact and how people opt in; never guess or invent them, because carriers reject registrations that don\'t match official records. You may draft the use case summary, opt-in description and sample messages for the person to approve: each sample starts with the business name and ends "Reply STOP to opt out". The registration number (EIN, or SSN for a sole proprietor) cannot be set here: the person enters it in the dashboard. Returns the saved form (number masked) and the checklist. Nothing is sent to the carriers.',
843
+ input: {
844
+ form: z
845
+ .object({
846
+ legal_name: z.string().max(500).optional().describe('Exactly as on the official registration.'),
847
+ dba: z.string().max(500).optional().describe('Brand name customers see, if different.'),
848
+ entity_type: z.enum(['PRIVATE_PROFIT', 'SOLE_PROPRIETOR', 'NON_PROFIT', 'PUBLIC_PROFIT', 'GOVERNMENT']).optional(),
849
+ registration_country: z.string().length(2).optional().describe('2-letter country code, e.g. US.'),
850
+ vertical: z.enum(['general', 'alcohol', 'cannabis_cbd', 'lead_resale', 'mlm', 'tobacco_vape', 'firearms', 'adult', 'gambling', 'high_risk_finance']).optional().describe('Kind of business. Most are general; some kinds cannot be registered at all.'),
851
+ website: z.string().max(500).optional(),
852
+ address1: z.string().max(500).optional(),
853
+ address2: z.string().max(500).optional(),
854
+ city: z.string().max(500).optional(),
855
+ state: z.string().max(500).optional(),
856
+ zip: z.string().max(500).optional(),
857
+ contact_first_name: z.string().max(500).optional(),
858
+ contact_last_name: z.string().max(500).optional(),
859
+ contact_email: z.string().max(500).optional(),
860
+ contact_phone: z.string().max(500).optional(),
861
+ privacy_url: z.string().max(500).optional(),
862
+ terms_url: z.string().max(500).optional(),
863
+ opt_in_url: z.string().max(500).optional().describe('Page where people sign up for texts.'),
864
+ opt_in_screenshot_url: z.string().max(2000).optional(),
865
+ opt_in_description: z.string().max(500).optional().describe('How people agree to get texts, in plain words.'),
866
+ use_case_summary: z.string().max(500).optional().describe('What the texts are for.'),
867
+ monthly_volume: z.string().max(500).optional(),
868
+ samples: z.array(z.string().max(320)).max(3).optional().describe('Up to 3 example messages.'),
869
+ age_gate: z.boolean().optional(),
870
+ confirm_website: z.boolean().optional().describe('The person confirmed the website is theirs and public.'),
871
+ confirm_opt_in: z.boolean().optional().describe('The person confirmed everyone they text agreed to it.'),
872
+ })
873
+ .strict()
874
+ .describe('Only the fields to change.'),
875
+ },
876
+ annotations: WRITE_IDEMPOTENT,
877
+ run: async (api, { form }) => {
878
+ const data = await api.request('PATCH', '/sms/registration', { body: { form } });
879
+ const status = get(data, 'status') ?? 'draft';
880
+ return { lead: `Saved the texting registration (${status}). Nothing was sent to the carriers. Run sms_website_check next.`, data };
881
+ },
882
+ }),
883
+ defineTool({
884
+ name: 'sms_website_check',
885
+ title: 'Check the texting registration',
886
+ scope: 'account',
887
+ description: 'Runs every check the carriers care about on the saved registration, without submitting: missing or invalid form fields, and a live look at the person\'s website, privacy policy and terms (public, has the business name and address, and the privacy policy has the required sentence about mobile information). A few runs per 10 minutes. Use the results to help the person fix their form or their own site, then check again.',
888
+ input: {},
889
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
890
+ run: async (api) => {
891
+ const data = await api.request('POST', '/sms/registration/check', { body: {} });
892
+ const checks = get(data, 'checks');
893
+ const problems = smsCheckProblems(checks);
894
+ const lead = get(checks, 'ok') === true
895
+ ? 'Every check passed. Ask the person if they want to submit (sms_registration_submit).'
896
+ : `${problems.length} problem${problems.length === 1 ? '' : 's'} to fix before submitting:\n${problems.map((p) => `- ${p}`).join('\n')}`;
897
+ return { lead, data };
898
+ },
899
+ }),
900
+ defineTool({
901
+ name: 'sms_numbers',
902
+ title: 'Toll-free numbers to choose from',
903
+ scope: 'account',
904
+ description: 'Lists toll-free numbers available for this workspace\'s first texting registration. Optional prefix (800, 833, 844, 855, 866, 877, 888). Read only: nothing is bought until sms_registration_submit.',
905
+ input: { prefix: z.enum(['800', '833', '844', '855', '866', '877', '888']).optional() },
906
+ annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
907
+ run: async (api, { prefix }) => {
908
+ const data = await api.request('GET', '/sms/numbers', { query: prefix ? { prefix } : undefined });
909
+ const numbers = get(data, 'numbers') ?? [];
910
+ return { lead: `${numbers.length} toll-free number${numbers.length === 1 ? '' : 's'} available. Let the person pick one.`, data };
911
+ },
912
+ }),
913
+ defineTool({
914
+ name: 'sms_registration_submit',
915
+ title: 'Submit the texting registration',
916
+ scope: 'account',
917
+ description: 'Sends the registration to the carriers for review. The first time it also buys the chosen toll-free number (phone_number from sms_numbers, included in the person\'s add-on). After a rejection it resubmits the same request with the fixes. Only after the person reviewed the form (sms_setup_status) and said yes: needs confirm: true. Every check runs again first; if one fails, nothing is sent or bought. Review takes 1 to 2 weeks, sometimes a month; never promise a date. The person gets an email when the status changes.',
918
+ input: {
919
+ confirm: z.literal(true).describe('true: the person approved submitting.'),
920
+ phone_number: z.string().regex(/^\+18(00|33|44|55|66|77|88)\d{7}$/).optional().describe('First submission only: the toll-free number the person picked, E.164 (+18335550100).'),
921
+ },
922
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
923
+ run: async (api, { confirm, phone_number }) => {
924
+ const data = await api.request('POST', '/sms/registration/submit', { body: { confirm, ...(phone_number ? { phone_number } : {}) } });
925
+ if (get(data, 'pending') || get(get(data, 'view'), 'pending_number') === true) {
926
+ return { lead: 'The number is being set up. The registration goes to the carriers automatically in a few minutes; it can\'t be edited until then. Review then usually takes 1 to 2 weeks, and the person gets an email when the status changes.', data };
927
+ }
928
+ const status = get(get(data, 'view'), 'status') ?? 'submitted';
929
+ return { lead: `Submitted to the carriers (status ${status}). Review usually takes 1 to 2 weeks; the person gets an email when it changes.`, data };
930
+ },
931
+ }),
781
932
  defineTool({
782
933
  name: 'surveys_list',
783
934
  title: 'List surveys',
@@ -1133,6 +1284,7 @@ export const TOOLS = [
1133
1284
  }),
1134
1285
  ];
1135
1286
  export const CORE_TOOL_NAMES = [
1287
+ 'launchpad_get', 'launchpad_update', 'launchpad_go_live',
1136
1288
  'page_get', 'page_update', 'page_link_add', 'page_link_update', 'page_link_remove', 'page_links_reorder', 'event_list', 'event_create', 'event_update', 'event_cancel',
1137
1289
  'workspace_info',
1138
1290
  'brand_get',
@@ -1161,6 +1313,10 @@ export const CORE_TOOL_NAMES = [
1161
1313
  'domain_verify',
1162
1314
  'domain_remove',
1163
1315
  'sms_setup_status',
1316
+ 'sms_registration_update',
1317
+ 'sms_website_check',
1318
+ 'sms_numbers',
1319
+ 'sms_registration_submit',
1164
1320
  'surveys_list',
1165
1321
  'survey_results',
1166
1322
  'survey_create',
@@ -1177,6 +1333,13 @@ export async function runTool(def, api, args) {
1177
1333
  return okResult(outcome.lead, outcome.data, api.secrets, { untrusted: def.untrusted === true });
1178
1334
  }
1179
1335
  catch (err) {
1336
+ if (def.name === 'launchpad_go_live' && err instanceof ApiError && ['review_pending', 'pending_review'].includes(err.code)) {
1337
+ return errorResult(new ApiError(err.status, err.code, {
1338
+ ...err.body,
1339
+ moderation_status: 'pending_review',
1340
+ owner_reason: err.body.owner_reason ?? err.body.message ?? 'The page is waiting for review.',
1341
+ }), api.secrets);
1342
+ }
1180
1343
  return errorResult(err, api.secrets);
1181
1344
  }
1182
1345
  }
package/dist/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const VERSION = "0.5.0";
1
+ export declare const VERSION = "0.7.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.5.0';
2
+ export const VERSION = '0.7.0';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hollerpost-mcp",
3
- "version": "0.5.0",
3
+ "version": "0.7.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",