hollerpost-mcp 0.5.0 → 0.6.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,22 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.6.0 (2026-11-11)
4
+
5
+ Texting setup with an agent, not just status.
6
+
7
+ - `sms_registration_update` (scope `account`): fill or fix the toll-free
8
+ registration form while it's a draft or after a rejection. Business facts
9
+ come from the person; the agent may draft the use case, opt-in description
10
+ and sample messages for approval. The registration number (EIN, or SSN for
11
+ a sole proprietor) can't be set through an agent: it's entered in the
12
+ dashboard.
13
+ - `sms_website_check` (scope `account`): the carrier checks on the form and
14
+ a live look at the website, privacy policy and terms, listed as fixes.
15
+ - `sms_numbers` (scope `account`): toll-free numbers to pick from.
16
+ - `sms_registration_submit` (scope `account`): submit after the person's
17
+ yes (`confirm: true`); the first time it buys the chosen number. Every
18
+ check runs again first, and nothing is sent or bought if one fails.
19
+
3
20
  ## 0.5.0 (2026-11-09)
4
21
 
5
22
  Pictures from the person's own device.
package/README.md CHANGED
@@ -136,6 +136,10 @@ 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) |
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,6 +60,29 @@ 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})` : ''}.`;
@@ -175,6 +198,24 @@ export function describeApiError(err) {
175
198
  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
199
  case 'beyond_scheduling_horizon':
177
200
  return `${head} That time is further ahead than this plan can schedule${b.limit_days ? ` (${num(b.limit_days)} days)` : ''}.`;
201
+ case 'field_dashboard_only':
202
+ 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.`;
203
+ case 'confirmation_required':
204
+ 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.`;
205
+ case 'registration_locked':
206
+ 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.`;
207
+ case 'sms_not_eligible':
208
+ 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.`;
209
+ case 'checks_failed': {
210
+ const problems = smsCheckProblems(b.checks);
211
+ 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.`;
212
+ }
213
+ case 'phone_number_required':
214
+ return `${head} The first submission needs a toll-free number. Call sms_numbers, let the person pick one, then submit with phone_number.`;
215
+ case 'number_taken':
216
+ return `${head} Someone else just took that number. Call sms_numbers and let the person pick another.`;
217
+ case 'resubmit_not_allowed':
218
+ return `${head} This rejection is handled with the carrier directly by the Hollerpost team. Don't resubmit; the person will get an email.`;
178
219
  case 'not_available_yet':
179
220
  return `${head} That part of Hollerpost Social comes in a later beta release.`;
180
221
  default: {
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',
@@ -753,7 +753,7 @@ export const TOOLS = [
753
753
  name: 'sms_setup_status',
754
754
  title: 'Text messaging setup',
755
755
  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.',
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 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
757
  input: {},
758
758
  annotations: READ,
759
759
  run: async (api) => {
@@ -778,6 +778,100 @@ export const TOOLS = [
778
778
  return { lead: parts.join(' '), data };
779
779
  },
780
780
  }),
781
+ defineTool({
782
+ name: 'sms_registration_update',
783
+ title: 'Fill or fix the texting registration',
784
+ scope: 'account',
785
+ 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.',
786
+ input: {
787
+ form: z
788
+ .object({
789
+ legal_name: z.string().max(500).optional().describe('Exactly as on the official registration.'),
790
+ dba: z.string().max(500).optional().describe('Brand name customers see, if different.'),
791
+ entity_type: z.enum(['PRIVATE_PROFIT', 'SOLE_PROPRIETOR', 'NON_PROFIT', 'PUBLIC_PROFIT', 'GOVERNMENT']).optional(),
792
+ registration_country: z.string().length(2).optional().describe('2-letter country code, e.g. US.'),
793
+ 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.'),
794
+ website: z.string().max(500).optional(),
795
+ address1: z.string().max(500).optional(),
796
+ address2: z.string().max(500).optional(),
797
+ city: z.string().max(500).optional(),
798
+ state: z.string().max(500).optional(),
799
+ zip: z.string().max(500).optional(),
800
+ contact_first_name: z.string().max(500).optional(),
801
+ contact_last_name: z.string().max(500).optional(),
802
+ contact_email: z.string().max(500).optional(),
803
+ contact_phone: z.string().max(500).optional(),
804
+ privacy_url: z.string().max(500).optional(),
805
+ terms_url: z.string().max(500).optional(),
806
+ opt_in_url: z.string().max(500).optional().describe('Page where people sign up for texts.'),
807
+ opt_in_screenshot_url: z.string().max(2000).optional(),
808
+ opt_in_description: z.string().max(500).optional().describe('How people agree to get texts, in plain words.'),
809
+ use_case_summary: z.string().max(500).optional().describe('What the texts are for.'),
810
+ monthly_volume: z.string().max(500).optional(),
811
+ samples: z.array(z.string().max(320)).max(3).optional().describe('Up to 3 example messages.'),
812
+ age_gate: z.boolean().optional(),
813
+ confirm_website: z.boolean().optional().describe('The person confirmed the website is theirs and public.'),
814
+ confirm_opt_in: z.boolean().optional().describe('The person confirmed everyone they text agreed to it.'),
815
+ })
816
+ .strict()
817
+ .describe('Only the fields to change.'),
818
+ },
819
+ annotations: WRITE_IDEMPOTENT,
820
+ run: async (api, { form }) => {
821
+ const data = await api.request('PATCH', '/sms/registration', { body: { form } });
822
+ const status = get(data, 'status') ?? 'draft';
823
+ return { lead: `Saved the texting registration (${status}). Nothing was sent to the carriers. Run sms_website_check next.`, data };
824
+ },
825
+ }),
826
+ defineTool({
827
+ name: 'sms_website_check',
828
+ title: 'Check the texting registration',
829
+ scope: 'account',
830
+ 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.',
831
+ input: {},
832
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
833
+ run: async (api) => {
834
+ const data = await api.request('POST', '/sms/registration/check', { body: {} });
835
+ const checks = get(data, 'checks');
836
+ const problems = smsCheckProblems(checks);
837
+ const lead = get(checks, 'ok') === true
838
+ ? 'Every check passed. Ask the person if they want to submit (sms_registration_submit).'
839
+ : `${problems.length} problem${problems.length === 1 ? '' : 's'} to fix before submitting:\n${problems.map((p) => `- ${p}`).join('\n')}`;
840
+ return { lead, data };
841
+ },
842
+ }),
843
+ defineTool({
844
+ name: 'sms_numbers',
845
+ title: 'Toll-free numbers to choose from',
846
+ scope: 'account',
847
+ 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.',
848
+ input: { prefix: z.enum(['800', '833', '844', '855', '866', '877', '888']).optional() },
849
+ annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
850
+ run: async (api, { prefix }) => {
851
+ const data = await api.request('GET', '/sms/numbers', { query: prefix ? { prefix } : undefined });
852
+ const numbers = get(data, 'numbers') ?? [];
853
+ return { lead: `${numbers.length} toll-free number${numbers.length === 1 ? '' : 's'} available. Let the person pick one.`, data };
854
+ },
855
+ }),
856
+ defineTool({
857
+ name: 'sms_registration_submit',
858
+ title: 'Submit the texting registration',
859
+ scope: 'account',
860
+ 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.',
861
+ input: {
862
+ confirm: z.literal(true).describe('true: the person approved submitting.'),
863
+ 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).'),
864
+ },
865
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
866
+ run: async (api, { confirm, phone_number }) => {
867
+ const data = await api.request('POST', '/sms/registration/submit', { body: { confirm, ...(phone_number ? { phone_number } : {}) } });
868
+ if (get(data, 'pending') || get(get(data, 'view'), 'pending_number') === true) {
869
+ 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 };
870
+ }
871
+ const status = get(get(data, 'view'), 'status') ?? 'submitted';
872
+ return { lead: `Submitted to the carriers (status ${status}). Review usually takes 1 to 2 weeks; the person gets an email when it changes.`, data };
873
+ },
874
+ }),
781
875
  defineTool({
782
876
  name: 'surveys_list',
783
877
  title: 'List surveys',
@@ -1161,6 +1255,10 @@ export const CORE_TOOL_NAMES = [
1161
1255
  'domain_verify',
1162
1256
  'domain_remove',
1163
1257
  'sms_setup_status',
1258
+ 'sms_registration_update',
1259
+ 'sms_website_check',
1260
+ 'sms_numbers',
1261
+ 'sms_registration_submit',
1164
1262
  'surveys_list',
1165
1263
  'survey_results',
1166
1264
  'survey_create',
package/dist/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const VERSION = "0.5.0";
1
+ export declare const VERSION = "0.6.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.6.0';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hollerpost-mcp",
3
- "version": "0.5.0",
3
+ "version": "0.6.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",