hollerpost-mcp 0.2.1 → 0.4.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,6 +1,55 @@
1
1
  # Changelog
2
2
 
3
- ## 0.2.1 (unreleased)
3
+ ## 0.4.0 (2026-11-08)
4
+
5
+ More than one picture per email.
6
+
7
+ - `email_image_upload` (scope `draft`): stores an image on Hollerpost from a
8
+ public https URL or base64 data (JPEG, PNG, WebP, GIF, up to 5 MB) and
9
+ returns its URL. Emails link to images, they are never attached. Images
10
+ are shrunk to at most 1200px wide and saved as JPEG (PNG when
11
+ transparent); GIFs up to 2 MB. Limits: 100 uploads per API key per 24
12
+ hours, 500 per workspace per 30 days (`image_limit_reached`, not retried).
13
+ - `campaign_draft` / `campaign_update` blocks:
14
+ - `body_md` takes image lines: `![alt](https://...)` or, clickable,
15
+ `[![alt](https://...)](https://link)`, each on a line by itself.
16
+ Images inside a sentence are refused (`image_on_its_own_line`), and alt
17
+ text is required.
18
+ - `sections`: up to 8 parts after the body, each with its own sub-heading,
19
+ image (`image_position` top, left or right), copy and button.
20
+ - Up to 20 images per email. The plain template stays copy only.
21
+ - Brand colors that are hard to read (neon yellow, lime) no longer give
22
+ white button labels or yellow links: Hollerpost picks a readable label and
23
+ darkens the link color. Colors chosen for one email are kept.
24
+
25
+ ## 0.3.0 (2026-11-04)
26
+
27
+ New tools for Your page, calendar events and social posts. Not yet on npm or
28
+ mcp.hollerpost.com at the time of writing.
29
+
30
+ - Your page: `page_get`, `page_update`, `page_link_add`, `page_link_update`,
31
+ `page_link_remove`, `page_links_reorder`. Arrays in updates replace the
32
+ existing ones; the API enforces HTTPS links, contrast and the Free badge.
33
+ - Calendar events: `event_list`, `event_create`, `event_update`,
34
+ `event_cancel` (on `/api/v1/page/events`; `events_recent` is still
35
+ delivery activity).
36
+ - Publishing needs explicit approval: `page_update` with `published: true`,
37
+ and `event_create` / `event_update` that publish, require
38
+ `confirm_publish: true`. `page_link_remove` and `event_cancel` require
39
+ `confirm: true`.
40
+ - Social posts (beta): 17 tools for channels (connect by a one-time link, so
41
+ no password or token passes through the assistant), media upload, post
42
+ draft, AI draft from a brief or an email, preview, schedule, cancel, queue,
43
+ delivery status and usage. They register only when the key holds a social
44
+ scope; `social_post_schedule` needs `preview_revision` and `confirm: true`.
45
+ - Connector requests never follow redirects; media import follows at most 3
46
+ and re-checks each hop. API error wording matches the codes the API returns.
47
+ - The remote server sends `Strict-Transport-Security` on https responses.
48
+ - README: Claude connector setup uses the URL with the key in it (the
49
+ dashboard shows it ready to copy when you create a key); page and event
50
+ tool docs.
51
+
52
+ ## 0.2.1 (2026-10-28)
4
53
 
5
54
  Security hardening before launch. No new tools.
6
55
 
package/README.md CHANGED
@@ -31,7 +31,7 @@ Needs Node.js 20 or newer.
31
31
 
32
32
  ### Claude.ai and Claude Desktop connectors (remote)
33
33
 
34
- Settings, Connectors, Add custom connector. Connectors cannot send a custom header yet, so put the key in the URL:
34
+ Settings, Connectors, Add custom connector. Use the URL with the key in it and leave authentication and request headers empty. The URL is the setup tested end to end with Claude connectors (2026-11-02). The dashboard shows this URL, ready to copy, when you create a key:
35
35
 
36
36
  ```
37
37
  https://mcp.hollerpost.com/mcp?key=hp_live_your_key_here
@@ -113,10 +113,11 @@ If a tool needs a scope the key lacks, the tool answers `insufficient_scope`, na
113
113
  | `brand_get` | read | Brand settings and writing voice |
114
114
  | `brand_set_voice` | draft | Save the brand voice notes (replaces the old text) |
115
115
  | `templates_list` | read | Templates and the content blocks each accepts |
116
+ | `email_image_upload` | draft | Store an image (from a URL or the file) for use in an email; returns its URL |
116
117
  | `segments_list` | read | Tags with subscribed counts, for choosing an audience |
117
118
  | `contacts_search` | read | Find contacts by email, status or tag |
118
119
  | `contacts_add` | contacts | Add one contact who opted in (`consent: true` required) |
119
- | `campaign_draft` | draft | Create a draft from a template, content blocks and an audience, optionally with one survey question. Sends nothing |
120
+ | `campaign_draft` | draft | Create a draft from a template, content blocks (image lines in `body_md`, `sections` for several products) and an audience, optionally with one survey question. Sends nothing |
120
121
  | `campaign_update` | draft | Edit a draft, including adding or removing its survey question |
121
122
  | `campaign_preview` | draft | Rendered text, live audience count, quota after sending, warnings |
122
123
  | `campaign_send_test` | draft | Test copy to up to 3 workspace users |
@@ -138,6 +139,25 @@ If a tool needs a scope the key lacks, the tool answers `insufficient_scope`, na
138
139
  | `survey_create` | draft | Create a draft survey (1 to 30 questions) |
139
140
  | `survey_update` | draft | Edit a survey, or open or close it |
140
141
  | `billing_portal_link` | account | A short-lived Stripe portal link for the person to open |
142
+ | `page_get` | read | Read Your page, links, calendar events and plan settings |
143
+ | `page_update` | draft | Save page fields via `updates`; publishing changes the public page immediately and needs `confirm_publish: true` after the person approves |
144
+ | `page_link_add` | draft | Add a HTTPS link via `link` (max 30) |
145
+ | `page_link_update` | draft | Update a link by `id` and `updates` |
146
+ | `page_link_remove` | draft | Permanently remove a link (`confirm: true`) |
147
+ | `page_links_reorder` | draft | Supply all link `ids` exactly once in display order |
148
+ | `event_list` | read | List calendar events, upcoming and past 90 days |
149
+ | `event_create` | draft | Create an `event`, draft by default; creating it as published needs `confirm_publish: true` |
150
+ | `event_update` | draft | Update an event by `id` and `updates` |
151
+ | `event_cancel` | draft | Cancel and retain an event (`confirm: true`) |
152
+
153
+ Your page tools use `/api/v1/page` and `/api/v1/page/links`. Calendar events
154
+ use `/api/v1/page/events`; `/api/v1/events` remains delivery activity for
155
+ `events_recent`. Tenant API keys require `mcp_enabled` and read/draft scopes.
156
+ The API enforces workspace ownership, URL safety, contrast, badge and date
157
+ rules shared with the dashboard. `page_get` returns an unsaved brand draft
158
+ when no page exists. Claim a handle in the dashboard before publishing.
159
+ Arrays in page updates replace the existing arrays. The two removal/cancel
160
+ tools have `destructiveHint: true`; page/event reads have `readOnlyHint: true`.
141
161
 
142
162
  Resources (context a client can attach without a tool call): `hollerpost://brand`, `hollerpost://templates`, `hollerpost://quota`, `hollerpost://domains`.
143
163
 
@@ -153,7 +173,7 @@ These are built into the server and the API, not left to the agent:
153
173
  - **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.
154
174
  - **Consent.** Contacts can only be added with `consent: true`, and addresses that unsubscribed, bounced or complained can never be re-added.
155
175
  - **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.
156
- - **Almost nothing destructive.** There is no contact delete, campaign delete or webhook delete. The only destructive tool is `domain_remove` (needs `confirm: true`, refused while a campaign is scheduled on the domain). `campaign_cancel` is the undo for a scheduled send.
176
+ - **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.
157
177
  - **Quota.** A send larger than the remaining monthly quota is refused with `quota_exceeded`, with a link where you can buy a send pack yourself.
158
178
  - **Your key stays yours.** The remote server forwards your `Authorization` header to the API on each request and stores nothing. Keys are never echoed in tool output and never logged; anything shaped like a key is redacted from output even if the API were to return it.
159
179
 
@@ -219,7 +239,7 @@ Add `HOLLERPOST_MCP_URL=https://mcp.hollerpost.com/mcp` to go through the deploy
219
239
  ## Layout
220
240
 
221
241
  ```
222
- src/tools.ts the 29 tools: schemas, descriptions, handlers (transport agnostic)
242
+ src/tools.ts the 39 core tools: schemas, descriptions, handlers (transport agnostic)
223
243
  src/client.ts fetch wrapper: auth passthrough, 429 retry, User-Agent, key redaction
224
244
  src/format.ts tool results, 50-row truncation, API error messages
225
245
  src/resources.ts hollerpost://brand, templates, quota, domains
package/dist/client.d.ts CHANGED
@@ -13,6 +13,8 @@ export interface ClientOptions {
13
13
  fetch?: FetchLike;
14
14
  /** Injected for tests. */
15
15
  sleep?: (ms: number) => Promise<void>;
16
+ /** Optional active scopes allowed for this client. */
17
+ scopes?: string[];
16
18
  }
17
19
  export interface RequestOptions {
18
20
  query?: Record<string, string | number | boolean | undefined | null>;
@@ -28,19 +30,27 @@ export declare class ApiError extends Error {
28
30
  readonly local: boolean;
29
31
  constructor(status: number, code: string, body?: Record<string, unknown>, local?: boolean);
30
32
  }
31
- /** Replace anything that looks like a Hollerpost key with a fixed marker. */
32
- export declare function redactString(text: string, secrets?: string[]): string;
33
+ /** Replace anything that looks like a Hollerpost key or OAuth credential with a fixed marker. */
34
+ export declare function redactSecrets(text: string, secrets?: string[]): string;
35
+ export declare const redactString: typeof redactSecrets;
33
36
  /** Deep copy of a JSON value with every string passed through redactString. */
34
37
  export declare function redactDeep<T>(value: T, secrets?: string[]): T;
35
38
  /** Parse Retry-After (delta seconds or HTTP date) into milliseconds. */
36
39
  export declare function parseRetryAfter(header: string | null, now?: number): number | null;
37
40
  export declare class HollerpostClient {
38
41
  readonly transport: TransportKind;
42
+ readonly scopes?: string[];
39
43
  private readonly authorization;
40
44
  private readonly baseUrl;
41
45
  private readonly fetchImpl;
42
46
  private readonly sleep;
43
47
  constructor(opts: ClientOptions);
48
+ /**
49
+ * The scopes this key holds (from /me), or [] when that can't be read
50
+ * (no key, a network error). Used only to decide which optional tools to
51
+ * offer; the API enforces scopes on every call either way.
52
+ */
53
+ keyScopes(): Promise<string[]>;
44
54
  get userAgent(): string;
45
55
  /** Strings that must never appear in output: the raw key and the header. */
46
56
  get secrets(): string[];
package/dist/client.js CHANGED
@@ -32,15 +32,24 @@ export class ApiError extends Error {
32
32
  }
33
33
  }
34
34
  const KEY_PATTERN = /\b(hp|uc)_(live|test)_[A-Za-z0-9_\-]+/g;
35
- /** Replace anything that looks like a Hollerpost key with a fixed marker. */
36
- export function redactString(text, secrets = []) {
37
- let out = text.replace(KEY_PATTERN, '[redacted key]');
35
+ const BEARER_PATTERN = /\bBearer\s+[A-Za-z0-9._\-~+/]+=*/gi;
36
+ const SENSITIVE_JSON_KEY_PATTERN = /"(access_token|refresh_token|client_secret|app_password)"\s*:\s*"[^"]+"/gi;
37
+ const SENSITIVE_PARAM_PATTERN = /\b(access_token|refresh_token|client_secret|app_password)=(\[redacted secret\]|[^\s&"']+)/gi;
38
+ const SENSITIVE_KEY_NAMES = new Set(['access_token', 'refresh_token', 'client_secret', 'app_password']);
39
+ /** Replace anything that looks like a Hollerpost key or OAuth credential with a fixed marker. */
40
+ export function redactSecrets(text, secrets = []) {
41
+ let out = text
42
+ .replace(KEY_PATTERN, '[redacted key]')
43
+ .replace(BEARER_PATTERN, 'Bearer [redacted token]')
44
+ .replace(SENSITIVE_JSON_KEY_PATTERN, '"$1": "[redacted secret]"')
45
+ .replace(SENSITIVE_PARAM_PATTERN, '$1=[redacted secret]');
38
46
  for (const s of secrets) {
39
47
  if (s && s.length >= 6)
40
48
  out = out.split(s).join('[redacted key]');
41
49
  }
42
50
  return out;
43
51
  }
52
+ export const redactString = redactSecrets;
44
53
  /** Deep copy of a JSON value with every string passed through redactString. */
45
54
  export function redactDeep(value, secrets = []) {
46
55
  if (typeof value === 'string')
@@ -50,12 +59,27 @@ export function redactDeep(value, secrets = []) {
50
59
  if (value && typeof value === 'object') {
51
60
  const out = {};
52
61
  for (const [k, v] of Object.entries(value)) {
53
- out[k] = redactDeep(v, secrets);
62
+ if (typeof v === 'string' && SENSITIVE_KEY_NAMES.has(k.toLowerCase())) {
63
+ out[k] = '[redacted secret]';
64
+ }
65
+ else {
66
+ out[k] = redactDeep(v, secrets);
67
+ }
54
68
  }
55
69
  return out;
56
70
  }
57
71
  return value;
58
72
  }
73
+ /** True when a 429 is a usage limit rather than the per-minute rate limit. */
74
+ async function isUsageLimit(res) {
75
+ try {
76
+ const body = (await res.clone().json());
77
+ return body?.error === 'image_limit_reached';
78
+ }
79
+ catch {
80
+ return false;
81
+ }
82
+ }
59
83
  /** Parse Retry-After (delta seconds or HTTP date) into milliseconds. */
60
84
  export function parseRetryAfter(header, now = Date.now()) {
61
85
  if (!header)
@@ -71,17 +95,35 @@ export function parseRetryAfter(header, now = Date.now()) {
71
95
  const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
72
96
  export class HollerpostClient {
73
97
  transport;
98
+ scopes;
74
99
  authorization;
75
100
  baseUrl;
76
101
  fetchImpl;
77
102
  sleep;
78
103
  constructor(opts) {
79
104
  this.transport = opts.transport;
105
+ this.scopes = opts.scopes;
80
106
  this.authorization = opts.authorization?.trim() || null;
81
107
  this.baseUrl = (opts.baseUrl || DEFAULT_API_BASE).replace(/\/+$/, '');
82
108
  this.fetchImpl = opts.fetch ?? ((input, init) => fetch(input, init));
83
109
  this.sleep = opts.sleep ?? defaultSleep;
84
110
  }
111
+ /**
112
+ * The scopes this key holds (from /me), or [] when that can't be read
113
+ * (no key, a network error). Used only to decide which optional tools to
114
+ * offer; the API enforces scopes on every call either way.
115
+ */
116
+ async keyScopes() {
117
+ if (!this.authorization)
118
+ return [];
119
+ try {
120
+ const me = (await this.request('GET', '/me'));
121
+ return Array.isArray(me?.scopes) ? me.scopes.filter((s) => typeof s === 'string') : [];
122
+ }
123
+ catch {
124
+ return [];
125
+ }
126
+ }
85
127
  get userAgent() {
86
128
  return `hollerpost-mcp/${VERSION} (${this.transport})`;
87
129
  }
@@ -117,7 +159,8 @@ export class HollerpostClient {
117
159
  init.body = JSON.stringify(opts.body);
118
160
  }
119
161
  let res = await this.send(url.toString(), init);
120
- if (res.status === 429) {
162
+ // A usage limit (image uploads) won't clear in a second: don't retry it.
163
+ if (res.status === 429 && !(await isUsageLimit(res))) {
121
164
  const wait = parseRetryAfter(res.headers.get('retry-after')) ?? 1000;
122
165
  if (wait <= MAX_RETRY_WAIT_MS) {
123
166
  await res.body?.cancel().catch(() => { });
package/dist/format.js CHANGED
@@ -82,6 +82,10 @@ export function describeApiError(err) {
82
82
  const secs = typeof b.retry_after_seconds === 'number' ? ` Try again in about ${b.retry_after_seconds} seconds.` : '';
83
83
  return `${head} The key hit its request rate limit and one automatic retry did not clear it.${secs}`;
84
84
  }
85
+ case 'image_limit_reached': {
86
+ const msg = typeof b.message === 'string' ? ` ${b.message}` : '';
87
+ return `${head}${msg} Nothing was stored. Do not retry now. Reuse the url of an image you already uploaded, or tell the person the limit was reached.`;
88
+ }
85
89
  case 'review_pending': {
86
90
  const id = typeof b.campaign_id === 'string' ? ` Campaign ${b.campaign_id}` : ' The campaign';
87
91
  return `${head}${id} was NOT sent. A workspace's first campaign is held for a one-time human review by the Hollerpost team (status "held_for_review"). It goes out after it is approved, and later campaigns schedule normally. Tell the person it is waiting for review. Do not retry, and do not create a duplicate campaign to get around the review.`;
@@ -146,6 +150,33 @@ export function describeApiError(err) {
146
150
  return `${head} api.hollerpost.com did not answer within ${Math.round(REQUEST_TIMEOUT_MS / 1000)} seconds. The request may or may not have completed; check with the matching list tool before retrying a write.`;
147
151
  case 'tenant_key_required':
148
152
  return `${head} This is a platform key. The MCP server needs a workspace key (hp_live_... or uc_live_...).`;
153
+ case 'social_coming_soon':
154
+ return `${head} Hollerpost Social isn't switched on for this workspace yet.`;
155
+ case 'provider_not_available':
156
+ return `${head} That network can't be connected yet. social_capabilities_list shows the ones that can.`;
157
+ case 'channel_limit':
158
+ return `${head} This workspace has connected the most channels its plan allows${b.limit !== undefined ? ` (${num(b.limit)})` : ''}. Disconnect one, or the person can upgrade with billing_portal_link.`;
159
+ case 'publication_limit':
160
+ return `${head} Nothing was scheduled: this period's publications are used up${b.limit !== undefined ? ` (${num(b.limit)})` : ''}. Each channel a post goes to counts as one. See social_usage_get.`;
161
+ case 'channel_pending_limit':
162
+ case 'workspace_pending_limit':
163
+ return `${head} Nothing was scheduled: too many posts are already waiting to go out${b.limit !== undefined ? ` (limit ${num(b.limit)})` : ''}. Wait for some to publish or cancel one.`;
164
+ case 'draft_limit':
165
+ return `${head} This workspace has the most drafts its plan allows. Schedule or delete some first.`;
166
+ case 'storage_limit':
167
+ case 'monthly_upload_limit':
168
+ return `${head} This workspace's media ${err.code === 'storage_limit' ? 'storage' : 'uploads for this period'} are used up. See social_usage_get.`;
169
+ case 'media_too_large':
170
+ case 'unsupported_media':
171
+ return `${head} ${typeof b.message === 'string' ? b.message : 'That file can\'t be used.'}`;
172
+ case 'preview_revision_mismatch':
173
+ return `${head} The post or its channels changed after that preview. Run social_post_preview again, show the person, and use the new preview_revision.`;
174
+ case 'post_not_draft':
175
+ 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
+ case 'beyond_scheduling_horizon':
177
+ return `${head} That time is further ahead than this plan can schedule${b.limit_days ? ` (${num(b.limit_days)} days)` : ''}.`;
178
+ case 'not_available_yet':
179
+ return `${head} That part of Hollerpost Social comes in a later beta release.`;
149
180
  default: {
150
181
  const extra = { ...b };
151
182
  delete extra.error;
package/dist/prompts.js CHANGED
@@ -22,7 +22,7 @@ export const PROMPTS = [
22
22
  '',
23
23
  'Steps:',
24
24
  '1. Call brand_get and follow the voice exactly.',
25
- '2. Call templates_list and pick the template that fits; fill only the blocks its blocks_schema accepts.',
25
+ '2. Call templates_list and pick the template that fits; fill only the blocks its blocks_schema accepts. For pictures, store each with email_image_upload and use the returned URL; for several products or stories use sections.',
26
26
  '3. Call campaign_draft. Show me the subject, preheader and copy, plus the preview_url.',
27
27
  '4. Call campaign_preview and tell me the audience count, the quota it uses and every warning.',
28
28
  '5. Offer campaign_send_test to my address and send it if I agree.',
package/dist/server.d.ts CHANGED
@@ -2,6 +2,6 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
2
  import type { ServerOptions } from '@modelcontextprotocol/sdk/server/index.js';
3
3
  import { HollerpostClient, type ClientOptions } from './client.js';
4
4
  export declare const SERVER_INSTRUCTIONS: string;
5
- export declare function createServer(client: HollerpostClient, options?: Pick<ServerOptions, 'jsonSchemaValidator'>): McpServer;
5
+ export declare function createServer(client: HollerpostClient, options?: Pick<ServerOptions, 'jsonSchemaValidator'>, scopes?: string[] | null): McpServer;
6
6
  export { HollerpostClient };
7
7
  export type { ClientOptions };
package/dist/server.js CHANGED
@@ -12,13 +12,17 @@ export const SERVER_INSTRUCTIONS = [
12
12
  'Start with workspace_info to learn the plan, the key scopes and the brand voice.',
13
13
  'Campaigns are created as drafts. Before campaign_schedule always run campaign_preview, tell the person the audience count and quota use, and wait for a yes.',
14
14
  'A workspace first campaign is held for a one-time human review (review_pending): it is not sent yet, do not retry.',
15
+ 'Pictures: store each one with email_image_upload (from a public URL or the file itself), then use the URL as image_url, a section image or an image line in body_md. Several products or stories go in blocks.sections, one per item.',
15
16
  'Surveys: survey_create makes a draft survey; campaign_draft can ask one of its rating, nps or single-choice questions in the email; open the survey with survey_update before testing or scheduling; read answers with survey_results.',
16
17
  'Only add contacts who agreed to receive email. No tool can change billing; billing_portal_link gives the person a link.',
18
+ 'Social posts (beta, only when this key has social scopes): the person connects an account by opening the link from social_channel_connect, never by giving you a password. Draft, run social_post_preview, show the person each network\'s text, and only after their yes call social_post_schedule with that preview_revision and confirm: true.',
17
19
  UNTRUSTED_DATA_NOTICE,
18
20
  ].join(' ');
19
- export function createServer(client, options = {}) {
21
+ // scopes: the key's scopes (client.keyScopes()), which decide whether the
22
+ // social tools are offered.
23
+ export function createServer(client, options = {}, scopes = null) {
20
24
  const server = new McpServer({ name: 'hollerpost-mcp', title: 'Hollerpost', version: VERSION, websiteUrl: 'https://hollerpost.com/docs/mcp/' }, { instructions: SERVER_INSTRUCTIONS, ...options });
21
- registerTools(server, client);
25
+ registerTools(server, client, { scopes });
22
26
  registerResources(server, client);
23
27
  registerPrompts(server);
24
28
  return server;
package/dist/stdio.js CHANGED
@@ -16,7 +16,7 @@ async function main() {
16
16
  transport: 'stdio',
17
17
  baseUrl: process.env.HOLLERPOST_API_BASE || DEFAULT_API_BASE,
18
18
  });
19
- const server = createServer(client);
19
+ const server = createServer(client, {}, await client.keyScopes());
20
20
  await server.connect(new StdioServerTransport());
21
21
  process.stderr.write(`hollerpost-mcp ${VERSION} ready on stdio\n`);
22
22
  }
package/dist/tools.d.ts CHANGED
@@ -2,7 +2,9 @@ import { z } from 'zod';
2
2
  import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3
3
  import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
4
4
  import { type HollerpostClient } from './client.js';
5
- export type Scope = 'read' | 'contacts' | 'draft' | 'send' | 'webhooks' | 'account';
5
+ export type Scope = 'read' | 'contacts' | 'draft' | 'send' | 'webhooks' | 'account' | 'social_read' | 'social_connect' | 'social_draft' | 'social_publish' | 'social_reply';
6
+ export declare const DEFAULT_ASSUMED_SCOPES: Scope[];
7
+ export declare const ALL_SCOPES: Scope[];
6
8
  export interface ToolOutcome {
7
9
  /** One or two plain sentences that lead the text content. */
8
10
  lead: string;
@@ -33,7 +35,12 @@ export declare const ANSWER_TEXT_LIMIT = 2000;
33
35
  */
34
36
  export declare function clipWrittenAnswers(data: unknown): unknown;
35
37
  export declare const TOOLS: ToolDef[];
38
+ export declare const CORE_TOOL_NAMES: string[];
36
39
  export declare const TOOL_NAMES: string[];
40
+ export declare const ALL_TOOL_NAMES: string[];
41
+ export declare const SOCIAL_TOOL_NAMES: string[];
37
42
  /** Run one tool and turn its outcome (or failure) into an MCP result. */
38
43
  export declare function runTool(def: ToolDef, api: HollerpostClient, args: unknown): Promise<CallToolResult>;
39
- export declare function registerTools(server: McpServer, api: HollerpostClient): void;
44
+ export declare function registerTools(server: McpServer, api: HollerpostClient, options?: {
45
+ scopes?: string[] | null;
46
+ }): void;
package/dist/tools.js CHANGED
@@ -5,13 +5,27 @@
5
5
  // adds schemas, careful descriptions and readable results on top.
6
6
  //
7
7
  // Safety rules baked in here (plan 4.4):
8
- // - No destructive tools except domain_remove, which needs confirm: true.
8
+ // - Destructive removals/cancellations require confirm: true.
9
9
  // - No tool moves money. billing_portal_link only hands back a URL.
10
10
  // - consent and confirm fields are z.literal(true): the call cannot even be
11
11
  // formed without them.
12
12
  import { z } from 'zod';
13
13
  import { ApiError } from './client.js';
14
14
  import { errorResult, InputError, okResult } from './format.js';
15
+ export const DEFAULT_ASSUMED_SCOPES = ['read', 'contacts', 'draft', 'send', 'webhooks', 'account'];
16
+ export const ALL_SCOPES = [
17
+ 'read',
18
+ 'contacts',
19
+ 'draft',
20
+ 'send',
21
+ 'webhooks',
22
+ 'account',
23
+ 'social_read',
24
+ 'social_connect',
25
+ 'social_draft',
26
+ 'social_publish',
27
+ 'social_reply',
28
+ ];
15
29
  function defineTool(def) {
16
30
  return def;
17
31
  }
@@ -20,29 +34,54 @@ const READ = { readOnlyHint: true, destructiveHint: false, idempotentHint: true,
20
34
  const WRITE_SAFE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
21
35
  const WRITE_IDEMPOTENT = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
22
36
  const SENDS_MAIL = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
37
+ const SOCIAL_PUBLISH = { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
23
38
  // ---------------------------------------------------------------------------
24
39
  // Shared schema pieces
25
40
  // Ids are UUIDs (the API's UUID_RE); anything else is refused before any
26
41
  // request goes out.
27
42
  const campaignId = z.string().uuid().describe('Campaign id (a UUID), as returned by campaign_draft or campaigns_list.');
43
+ const postId = z.string().uuid().describe('Social post id (a UUID), as returned by social_post_draft.');
44
+ const mediaId = z.string().uuid().describe('Social media item id (a UUID), as returned by social_media_upload.');
45
+ const deliveryId = z.string().uuid().describe('Social delivery id (a UUID).');
28
46
  const domainName = z
29
47
  .string()
30
48
  .min(3)
31
49
  .max(253)
32
50
  .regex(/^(?!-)[A-Za-z0-9-]+(\.[A-Za-z0-9-]+)+$/, 'Must be a bare domain such as mail.example.com (no scheme, no path).')
33
51
  .describe('A sending domain or subdomain, for example mail.example.com. No https://, no path.');
52
+ const https = z.string().regex(/^https:\/\//, 'Must start with https://');
53
+ const sectionSchema = z
54
+ .object({
55
+ heading: z.string().max(140).optional().describe('Sub-heading for this section.'),
56
+ body_md: z.string().max(3000).optional().describe('Copy for this section. Same Markdown as body_md, image lines allowed.'),
57
+ image_url: https.max(2000).optional().describe('Section image (https URL). Use email_image_upload first to host it on Hollerpost.'),
58
+ image_alt: z.string().max(140).optional().describe('What the image shows. Required when image_url is set.'),
59
+ image_link: https.max(2000).optional().describe('Where a click on the image goes. Defaults to cta_url.'),
60
+ image_position: z.enum(['top', 'left', 'right']).optional().describe('top (default): image above the copy. left or right: image beside the copy on wide screens, stacked on phones.'),
61
+ cta_text: z.string().max(40).optional().describe('Button label for this section.'),
62
+ cta_url: https.max(2000).optional().describe('Button link for this section.'),
63
+ })
64
+ .strict();
34
65
  const blocksSchema = z
35
66
  .object({
36
67
  heading: z.string().optional().describe('Main heading of the email.'),
37
- body_md: z.string().optional().describe('Body copy in Markdown. Hollerpost renders it inside the brand template.'),
68
+ body_md: z
69
+ .string()
70
+ .optional()
71
+ .describe('Body copy in Markdown: blank line between paragraphs, "- " lists, **bold**, *italic*, [text](https://...). To add a picture, put it on a line by itself: ![What it shows](https://...) or, clickable, [![What it shows](https://...)](https://link). Images inside a sentence are refused.'),
38
72
  cta_text: z.string().optional().describe('Button label, for example "Book a visit".'),
39
73
  cta_url: z.string().optional().describe('Button link (https URL).'),
40
- image_url: z.string().optional().describe('Optional hero image (https URL).'),
74
+ image_url: z.string().optional().describe('Optional hero image at the top (https URL). For more pictures use image lines in body_md or sections.'),
41
75
  image_alt: z.string().optional().describe('Alt text for the hero image. Required whenever image_url is set.'),
76
+ sections: z
77
+ .array(sectionSchema)
78
+ .max(8)
79
+ .optional()
80
+ .describe('Optional: up to 8 sections after body_md, each with its own sub-heading, image, copy and button, divided by a line. Use for a promotion with several products or a newsletter with several stories. Each needs at least a heading, body_md or image_url. Up to 20 images per email in total.'),
42
81
  })
43
82
  // Templates may add more text blocks later; accept them as strings.
44
83
  .catchall(z.string())
45
- .describe('Content blocks for the template. Check templates_list for the blocks_schema of the template you pick. Never send raw HTML: Hollerpost renders the blocks with the brand header, footer, unsubscribe link and address.');
84
+ .describe('Content blocks for the template. Check templates_list for the blocks_schema of the template you pick. Never send raw HTML: Hollerpost renders the blocks with the brand header, footer, unsubscribe link and address. The plain template takes no images.');
46
85
  const audienceSchema = z
47
86
  .union([
48
87
  z.object({
@@ -171,7 +210,48 @@ function verifyLines(domain) {
171
210
  }
172
211
  // ---------------------------------------------------------------------------
173
212
  // The 29 tools
213
+ const pageLinkSchema = z.object({
214
+ label: z.string().min(1).max(80), url: z.string().max(2048),
215
+ thumbnail_url: z.union([z.string().max(2048), z.null()]).optional(), starts_at: z.union([z.string().max(2048), z.null()]).optional(),
216
+ ends_at: z.union([z.string().max(2048), z.null()]).optional(), enabled: z.boolean().optional(), position: z.number().int().min(0).max(29).optional(),
217
+ });
218
+ const pageEventSchema = z.object({
219
+ title: z.string().min(1).max(120), starts_at: z.string(), timezone: z.string(),
220
+ description: z.union([z.string().max(2000), z.null()]).optional(), ends_at: z.union([z.string().max(2048), z.null()]).optional(),
221
+ venue_name: z.union([z.string().max(2048), z.null()]).optional(), address: z.union([z.string().max(2048), z.null()]).optional(),
222
+ 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
+ status: z.enum(['draft', 'published', 'canceled']).optional(), show_on_page: z.boolean().optional(),
224
+ });
225
+ const pageUpdateSchema = z.object({
226
+ 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(),
228
+ show_badge: z.boolean().optional(), signup_form_id: z.string().uuid().nullable().optional(),
229
+ 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
+ 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
+ show_events: z.boolean().optional(), published: z.boolean().optional(),
232
+ });
233
+ const PAGE_DESTRUCTIVE = { ...WRITE_IDEMPOTENT, destructiveHint: true };
174
234
  export const TOOLS = [
235
+ 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
+ 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,
238
+ 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
+ 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
+ run: async (api, { link }) => ({ lead: 'Page link added.', data: await api.request('POST', '/page/links', { body: link }) }) }),
241
+ defineTool({ name: 'page_link_update', title: 'Update page link', scope: 'draft', description: 'Update a workspace page link by ID. Omitted fields stay unchanged.', input: { id: z.string().uuid(), updates: pageLinkSchema.partial() }, annotations: WRITE_IDEMPOTENT, untrusted: true,
242
+ run: async (api, { id, updates }) => ({ lead: 'Page link updated.', data: await api.request('PATCH', `/page/links/${seg(id)}`, { body: updates }) }) }),
243
+ defineTool({ name: 'page_link_remove', title: 'Remove page link', scope: 'draft', description: 'Permanently remove a page link. Ask for confirmation before calling; requires confirm: true.', input: { id: z.string().uuid(), confirm: z.literal(true) }, annotations: PAGE_DESTRUCTIVE,
244
+ run: async (api, { id }) => ({ lead: 'Page link removed.', data: await api.request('DELETE', `/page/links/${seg(id)}`) }) }),
245
+ defineTool({ name: 'page_links_reorder', title: 'Reorder page links', scope: 'draft', description: 'Replace link ordering. Include every workspace link ID exactly once.', input: { ids: z.array(z.string().uuid()).max(30) }, annotations: WRITE_IDEMPOTENT,
246
+ run: async (api, { ids }) => ({ lead: 'Page links reordered.', data: await api.request('PUT', '/page/links/order', { body: { ids } }) }) }),
247
+ defineTool({ name: 'event_list', title: 'List calendar events', scope: 'read', description: 'List workspace calendar events, including upcoming and the past 90 days. These are calendar events, not email delivery events.', input: {}, annotations: READ, untrusted: true,
248
+ run: async (api) => ({ lead: 'Workspace calendar events.', data: await api.request('GET', '/page/events') }) }),
249
+ defineTool({ name: 'event_create', title: 'Create calendar event', scope: 'draft', description: 'Create a calendar event. Defaults to draft. Status published shows it on Your page right away: ask the person first and pass confirm_publish: true. Use an IANA timezone and ISO dates with offsets.', input: { event: pageEventSchema, confirm_publish: z.literal(true).optional().describe('true only after the person explicitly approved publishing; required whenever this call publishes.') }, annotations: WRITE_SAFE, untrusted: true,
250
+ run: async (api, { event, confirm_publish }) => ({ lead: 'Calendar event created.', data: await api.request('POST', '/page/events', { body: event, ...(confirm_publish ? { headers: { 'X-Hollerpost-Confirm': 'publish' } } : {}) }) }) }),
251
+ defineTool({ name: 'event_update', title: 'Update calendar event', scope: 'draft', description: 'Update a calendar event by ID. Fields omitted are unchanged. Changes to a published event affect Your page. Setting status published needs the person\'s approval and confirm_publish: true.', input: { id: z.string().uuid(), updates: pageEventSchema.omit({ status: true }).extend({ status: z.enum(['draft', 'published']).optional() }).partial(), 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,
252
+ run: async (api, { id, updates, confirm_publish }) => ({ lead: 'Calendar event updated.', data: await api.request('PATCH', `/page/events/${seg(id)}`, { body: updates, ...(confirm_publish ? { headers: { 'X-Hollerpost-Confirm': 'publish' } } : {}) }) }) }),
253
+ defineTool({ name: 'event_cancel', title: 'Cancel calendar event', scope: 'draft', description: 'Cancel an event and remove it from the public page, retaining its record. Ask for confirmation before calling; requires confirm: true.', input: { id: z.string().uuid(), confirm: z.literal(true) }, annotations: PAGE_DESTRUCTIVE, untrusted: true,
254
+ run: async (api, { id }) => ({ lead: 'Calendar event canceled.', data: await api.request('PATCH', `/page/events/${seg(id)}`, { body: { status: 'canceled' } }) }) }),
175
255
  defineTool({
176
256
  name: 'workspace_info',
177
257
  title: 'Workspace info',
@@ -224,7 +304,7 @@ export const TOOLS = [
224
304
  name: 'templates_list',
225
305
  title: 'List templates',
226
306
  scope: 'read',
227
- description: 'Lists the email templates and, for each, the blocks_schema (JSON Schema for heading, body_md, cta_text, cta_url, image_url, image_alt). Free and read only. Pick a template here before campaign_draft and fill only the blocks its schema accepts.',
307
+ description: 'Lists the email templates and, for each, the blocks_schema (JSON Schema for heading, body_md, cta_text, cta_url, image_url, image_alt and sections). Free and read only. Pick a template here before campaign_draft and fill only the blocks its schema accepts.',
228
308
  input: {},
229
309
  annotations: READ,
230
310
  run: async (api) => {
@@ -232,6 +312,25 @@ export const TOOLS = [
232
312
  return { lead: countLead('templates', data), data };
233
313
  },
234
314
  }),
315
+ defineTool({
316
+ name: 'email_image_upload',
317
+ title: 'Add an email image',
318
+ scope: 'draft',
319
+ description: 'Stores an image on Hollerpost for use in an email and returns its https URL. Pass url (a public https image, for example from the business website) or data_base64 (the file itself, for a picture the person gave you). JPEG, PNG, WebP or GIF, up to 5 MB (GIFs up to 2 MB). Hollerpost shrinks it to at most 1200px wide and saves it as JPEG, or PNG when it has transparency, so the returned type can differ from the upload. Emails link to the image rather than attaching it, so it adds nothing to the message size. Limits: 100 uploads per API key per 24 hours and 500 per workspace per 30 days, so upload each picture once and reuse its url. Use the returned url in image_url, a section image_url, or an image line in body_md: ![What it shows](url). Sends nothing.',
320
+ input: {
321
+ url: https.max(2000).optional().describe('Public https URL of the image to copy.'),
322
+ data_base64: z.string().max(7_000_000).optional().describe('The image file, base64 encoded (a data: URL prefix is fine).'),
323
+ filename: z.string().max(200).optional().describe('A file name, for example "junior-cues-banner.png".'),
324
+ },
325
+ annotations: WRITE_SAFE,
326
+ run: async (api, args) => {
327
+ if (!args.url === !args.data_base64)
328
+ throw new InputError('Pass exactly one of url or data_base64.');
329
+ const body = Object.fromEntries(Object.entries(args).filter(([, v]) => v !== undefined));
330
+ const data = await api.request('POST', '/media', { body });
331
+ return { lead: `Image stored: ${get(data, 'url') ?? 'n/a'}. Use it in image_url, a section, or an image line in body_md.`, data };
332
+ },
333
+ }),
235
334
  defineTool({
236
335
  name: 'segments_list',
237
336
  title: 'List segments',
@@ -725,8 +824,308 @@ export const TOOLS = [
725
824
  return { lead: `Billing portal link for the person to open: ${get(data, 'url') ?? 'unavailable'}`, data };
726
825
  },
727
826
  }),
827
+ // ---------------------------------------------------------------------------
828
+ // Hollerpost Social (beta). Registered only for keys that hold a social_*
829
+ // scope. Publishing follows the campaign rule: draft, preview, the person
830
+ // approves, then schedule with the preview_revision and confirm: true.
831
+ defineTool({
832
+ name: 'social_capabilities_list',
833
+ title: 'Social networks',
834
+ scope: 'social_read',
835
+ description: 'Lists the social networks this workspace can connect right now, what each takes (characters, images, video), and the networks that are planned but not available yet. Also returns the plan tier and its allowances. Read only.',
836
+ input: {},
837
+ annotations: READ,
838
+ run: async (api) => {
839
+ const data = await api.request('GET', '/social/capabilities');
840
+ const nets = get(data, 'networks') || [];
841
+ const on = nets.filter((n) => n.available).map((n) => n.name || n.provider);
842
+ return { lead: on.length ? `Available now: ${on.join(', ')}.` : 'No social networks are available for this workspace yet.', data };
843
+ },
844
+ }),
845
+ defineTool({
846
+ name: 'social_channels_list',
847
+ title: 'Social channels',
848
+ scope: 'social_read',
849
+ description: 'Lists the connected social channels (accounts, channels, webhooks) with their status. A channel in reconnect_required needs social_channel_connect again. Read only.',
850
+ input: {
851
+ provider: z.string().max(40).optional().describe('Only this network, for example bluesky.'),
852
+ },
853
+ annotations: READ,
854
+ untrusted: true,
855
+ run: async (api, { provider }) => {
856
+ const data = await api.request('GET', '/social/channels', { query: { provider } });
857
+ const n = (get(data, 'channels') || []).length;
858
+ return { lead: `${n} connected channel${n === 1 ? '' : 's'}.`, data };
859
+ },
860
+ }),
861
+ defineTool({
862
+ name: 'social_channel_connect',
863
+ title: 'Connect a social channel',
864
+ scope: 'social_connect',
865
+ description: 'Returns a one-time Hollerpost link (valid 30 minutes) where the person enters the account details themselves, for example a Bluesky app password or a Mastodon access token. Give the link to the person; never ask them to paste a password or token into the chat. Call social_capabilities_list first for the available networks.',
866
+ input: {
867
+ provider: z.string().min(1).max(40).describe('Network id from social_capabilities_list, for example bluesky, mastodon, telegram or discord.'),
868
+ },
869
+ annotations: WRITE_SAFE,
870
+ run: async (api, { provider }) => {
871
+ const data = await api.request('POST', '/social/channels/connect', { body: { provider } });
872
+ return { lead: `Give the person this link to connect ${provider}: ${get(data, 'connect_url') ?? 'unavailable'} (expires in 30 minutes, works once).`, data };
873
+ },
874
+ }),
875
+ defineTool({
876
+ name: 'social_channel_disconnect',
877
+ title: 'Disconnect a social channel',
878
+ scope: 'social_connect',
879
+ description: 'Disconnects a channel: its stored credential is deleted and its scheduled posts that have not started are canceled. History stays. Ask the person first.',
880
+ input: {
881
+ id: z.string().uuid().describe('Channel id from social_channels_list.'),
882
+ },
883
+ annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
884
+ run: async (api, { id }) => {
885
+ const data = await api.request('DELETE', `/social/channels/${seg(id)}`);
886
+ return { lead: `Channel ${id} disconnected.`, data };
887
+ },
888
+ }),
889
+ defineTool({
890
+ name: 'social_channel_priority',
891
+ title: 'Order social channels',
892
+ scope: 'social_connect',
893
+ description: 'Sets the order of connected channels, first is highest. If the plan changes to one with fewer channels, the highest ones stay active.',
894
+ input: {
895
+ channel_ids: z.array(z.string().uuid()).min(1).max(50).describe('Channel ids in order, highest first.'),
896
+ },
897
+ annotations: WRITE_IDEMPOTENT,
898
+ run: async (api, { channel_ids }) => {
899
+ const data = await api.request('POST', '/social/channels/priority', { body: { channel_ids } });
900
+ return { lead: 'Channel order saved.', data };
901
+ },
902
+ }),
903
+ defineTool({
904
+ name: 'social_media_upload',
905
+ title: 'Add an image or video',
906
+ scope: 'social_draft',
907
+ description: 'Imports an image (JPEG, PNG, GIF, WebP, up to 20 MB) or video (MP4, MOV, WebM, up to 50 MB) from a public https URL for use in social posts. The file type is read from the file itself. Publishes nothing. Always give alt_text for images.',
908
+ input: {
909
+ media_url: z.string().url().max(2000).describe('Public https URL of the file.'),
910
+ alt_text: z.string().max(2000).optional().describe('What the image shows, for people who can\'t see it.'),
911
+ title: z.string().max(200).optional().describe('A file name to show later.'),
912
+ },
913
+ annotations: WRITE_SAFE,
914
+ run: async (api, args) => {
915
+ const body = Object.fromEntries(Object.entries(args).filter(([, v]) => v !== undefined));
916
+ const data = await api.request('POST', '/social/media/upload', { body });
917
+ return { lead: `Media ${get(data, 'media.id') ?? ''} is ready.`, data };
918
+ },
919
+ }),
920
+ defineTool({
921
+ name: 'social_media_status',
922
+ title: 'Social media file',
923
+ scope: 'social_read',
924
+ description: 'Returns one uploaded media file: type, size, dimensions, alt text and status. Read only.',
925
+ input: { id: mediaId },
926
+ annotations: READ,
927
+ run: async (api, { id }) => {
928
+ const data = await api.request('GET', `/social/media/${seg(id)}`);
929
+ return { lead: `Media ${id}: ${get(data, 'media.status') ?? 'unknown'}.`, data };
930
+ },
931
+ }),
932
+ defineTool({
933
+ name: 'social_post_draft',
934
+ title: 'Draft a social post',
935
+ scope: 'social_draft',
936
+ description: 'Creates a draft social post. Publishes nothing. variants may override the text or media per network ("bluesky") or per channel id. Next: social_post_preview.',
937
+ input: {
938
+ text: z.string().min(1).max(50000).describe('The post text.'),
939
+ channel_ids: z.array(z.string().uuid()).min(1).max(20).describe('Channels to post to, from social_channels_list.'),
940
+ media_ids: z.array(z.string().uuid()).max(10).optional().describe('Media from social_media_upload.'),
941
+ variants: z.record(z.string(), z.object({ text: z.string().max(50000).optional(), media_ids: z.array(z.string().uuid()).max(10).optional() })).optional()
942
+ .describe('Overrides keyed by network or channel id, for example {"bluesky": {"text": "Shorter version"}}.'),
943
+ title: z.string().max(200).optional().describe('A name for your own reference.'),
944
+ },
945
+ annotations: WRITE_SAFE,
946
+ run: async (api, { text, ...rest }) => {
947
+ const body = Object.fromEntries(Object.entries({ base_text: text, ...rest }).filter(([, v]) => v !== undefined));
948
+ const data = await api.request('POST', '/social/posts', { body });
949
+ return { lead: `Draft ${get(data, 'post.id') ?? ''} created. Preview it with social_post_preview.`, data };
950
+ },
951
+ }),
952
+ defineTool({
953
+ name: 'social_ai_draft',
954
+ title: 'Write a social draft with AI',
955
+ scope: 'social_draft',
956
+ description: 'Writes a draft social post in the business\'s voice, from a short brief or by repurposing an email campaign (campaign_id), with a version per network sized to fit. Creates a draft only; nothing is posted. Uses the workspace\'s monthly AI allowance (shared with email). Next: social_post_preview.',
957
+ input: {
958
+ channel_ids: z.array(z.string().uuid()).min(1).max(20).describe('Channels it is for, from social_channels_list.'),
959
+ brief: z.string().max(4000).optional().describe('What the post is about. Include the facts: dates, prices, offers.'),
960
+ campaign_id: z.string().uuid().optional().describe('An email campaign to turn into social posts instead of a brief.'),
961
+ link_url: z.string().url().max(2000).optional().describe('An https link to include once.'),
962
+ },
963
+ annotations: WRITE_SAFE,
964
+ run: async (api, args) => {
965
+ if (!args.brief && !args.campaign_id)
966
+ throw new InputError('Pass a brief or a campaign_id.');
967
+ const body = Object.fromEntries(Object.entries(args).filter(([, v]) => v !== undefined));
968
+ const data = await api.request('POST', '/social/ai/draft', { body });
969
+ const warnings = get(data, 'warnings') || [];
970
+ return { lead: `Draft ${get(data, 'post.id') ?? ''} written.${warnings.length ? ` Check: ${warnings.join(' ')}` : ''} Preview it with social_post_preview.`, data };
971
+ },
972
+ }),
973
+ defineTool({
974
+ name: 'social_post_update',
975
+ title: 'Edit a social draft',
976
+ scope: 'social_draft',
977
+ description: 'Edits a draft social post. Any edit means it must be previewed again before scheduling. Only drafts can be edited; cancel a scheduled post first.',
978
+ input: {
979
+ id: postId,
980
+ text: z.string().min(1).max(50000).optional(),
981
+ channel_ids: z.array(z.string().uuid()).max(20).optional(),
982
+ media_ids: z.array(z.string().uuid()).max(10).optional(),
983
+ variants: z.record(z.string(), z.object({ text: z.string().max(50000).optional(), media_ids: z.array(z.string().uuid()).max(10).optional() })).optional(),
984
+ title: z.string().max(200).optional(),
985
+ },
986
+ annotations: WRITE_IDEMPOTENT,
987
+ run: async (api, { id, text, ...rest }) => {
988
+ const body = Object.fromEntries(Object.entries({ base_text: text, ...rest }).filter(([, v]) => v !== undefined));
989
+ if (!Object.keys(body).length)
990
+ throw new InputError('Nothing to update: pass at least one field to change.');
991
+ const data = await api.request('PATCH', `/social/posts/${seg(id)}`, { body });
992
+ return { lead: `Draft ${id} updated. Preview it again before scheduling.`, data };
993
+ },
994
+ }),
995
+ defineTool({
996
+ name: 'social_post_get',
997
+ title: 'Social post',
998
+ scope: 'social_read',
999
+ description: 'Returns one social post and, once scheduled, each destination\'s status and link. Read only.',
1000
+ input: { id: postId },
1001
+ annotations: READ,
1002
+ untrusted: true,
1003
+ run: async (api, { id }) => {
1004
+ const data = await api.request('GET', `/social/posts/${seg(id)}`);
1005
+ return { lead: `Post ${id}: ${get(data, 'post.status') ?? 'unknown'}.`, data };
1006
+ },
1007
+ }),
1008
+ defineTool({
1009
+ name: 'social_post_preview',
1010
+ title: 'Preview a social post',
1011
+ scope: 'social_draft',
1012
+ description: 'Checks a draft against every destination and returns exactly what each will get, any problems, and a preview_revision. Show the person the text per network and wait for their yes before social_post_schedule. Publishes nothing.',
1013
+ input: { id: postId },
1014
+ annotations: WRITE_IDEMPOTENT,
1015
+ run: async (api, { id }) => {
1016
+ const data = await api.request('POST', `/social/posts/${seg(id)}/preview`, { body: {} });
1017
+ const ok = get(data, 'ok') === true;
1018
+ return { lead: ok ? `Ready. preview_revision: ${get(data, 'preview_revision')}. Show the person the preview and ask before scheduling.` : 'Not ready: fix the errors listed, then preview again.', data };
1019
+ },
1020
+ }),
1021
+ defineTool({
1022
+ name: 'social_post_schedule',
1023
+ title: 'Schedule a social post',
1024
+ scope: 'social_publish',
1025
+ description: 'Publishes a previewed post now or at a set time, to every destination in that preview. Only after the person said yes to that preview. Needs the preview_revision from social_post_preview and confirm: true. It can be canceled until each destination starts.',
1026
+ input: {
1027
+ id: postId,
1028
+ send_at: z.string().min(1).describe('"now", or an ISO 8601 time such as 2026-11-01T15:00:00Z.'),
1029
+ preview_revision: z.string().min(1).describe('From social_post_preview.'),
1030
+ confirm: z.literal(true).describe('true: the person approved this preview.'),
1031
+ },
1032
+ annotations: SOCIAL_PUBLISH,
1033
+ run: async (api, { id, send_at, preview_revision, confirm }) => {
1034
+ const data = await api.request('POST', `/social/posts/${seg(id)}/schedule`, { body: { send_at, preview_revision, confirm } });
1035
+ return { lead: `Post ${id} scheduled for ${get(data, 'send_at') ?? send_at}.`, data };
1036
+ },
1037
+ }),
1038
+ defineTool({
1039
+ name: 'social_post_cancel',
1040
+ title: 'Cancel a scheduled social post',
1041
+ scope: 'social_publish',
1042
+ description: 'Cancels the destinations of a scheduled post that have not started. If none had started, the post becomes a draft again.',
1043
+ input: { id: postId },
1044
+ annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
1045
+ run: async (api, { id }) => {
1046
+ const data = await api.request('POST', `/social/posts/${seg(id)}/cancel`, { body: {} });
1047
+ return { lead: get(data, 'status') === 'draft' ? `Post ${id} canceled; it is a draft again.` : `Canceled what had not started on post ${id}.`, data };
1048
+ },
1049
+ }),
1050
+ defineTool({
1051
+ name: 'social_queue_list',
1052
+ title: 'Social queue',
1053
+ scope: 'social_read',
1054
+ description: 'Lists scheduled and in-progress social deliveries (one per destination), soonest first, or any status you name. Read only.',
1055
+ input: {
1056
+ status: z.enum(['pending', 'publishing', 'reconcile_needed', 'published', 'failed', 'canceled']).optional(),
1057
+ limit: z.number().int().min(1).max(200).optional(),
1058
+ },
1059
+ annotations: READ,
1060
+ untrusted: true,
1061
+ run: async (api, { status, limit }) => {
1062
+ const data = await api.request('GET', '/social/queue', { query: { status, limit } });
1063
+ const n = (get(data, 'deliveries') || []).length;
1064
+ return { lead: `${n} deliver${n === 1 ? 'y' : 'ies'}.`, data };
1065
+ },
1066
+ }),
1067
+ defineTool({
1068
+ name: 'social_delivery_status',
1069
+ title: 'Social delivery',
1070
+ scope: 'social_read',
1071
+ description: 'Returns one delivery (one post to one channel) with each attempt. error_code outcome_unknown means we could not confirm whether it posted and did not retry, so it cannot post twice: ask the person to check the channel. Read only.',
1072
+ input: { id: deliveryId },
1073
+ annotations: READ,
1074
+ untrusted: true,
1075
+ run: async (api, { id }) => {
1076
+ const data = await api.request('GET', `/social/deliveries/${seg(id)}`);
1077
+ return { lead: `Delivery ${id}: ${get(data, 'delivery.status') ?? 'unknown'}.`, data };
1078
+ },
1079
+ }),
1080
+ defineTool({
1081
+ name: 'social_usage_get',
1082
+ title: 'Social usage',
1083
+ scope: 'social_read',
1084
+ description: 'Returns this period\'s use against the plan: channels, pending posts, publications, uploads and storage. Read only.',
1085
+ input: {},
1086
+ annotations: READ,
1087
+ run: async (api) => {
1088
+ const data = await api.request('GET', '/social/usage');
1089
+ return { lead: `Social plan: ${get(data, 'tier') ?? 'free'}.`, data };
1090
+ },
1091
+ }),
1092
+ ];
1093
+ export const CORE_TOOL_NAMES = [
1094
+ 'page_get', 'page_update', 'page_link_add', 'page_link_update', 'page_link_remove', 'page_links_reorder', 'event_list', 'event_create', 'event_update', 'event_cancel',
1095
+ 'workspace_info',
1096
+ 'brand_get',
1097
+ 'brand_set_voice',
1098
+ 'templates_list',
1099
+ 'email_image_upload',
1100
+ 'segments_list',
1101
+ 'contacts_search',
1102
+ 'contacts_add',
1103
+ 'campaign_draft',
1104
+ 'campaign_update',
1105
+ 'campaign_preview',
1106
+ 'campaign_send_test',
1107
+ 'campaign_schedule',
1108
+ 'campaign_cancel',
1109
+ 'campaigns_list',
1110
+ 'campaign_stats',
1111
+ 'email_send',
1112
+ 'events_recent',
1113
+ 'account_get',
1114
+ 'account_update',
1115
+ 'domain_add',
1116
+ 'domain_list',
1117
+ 'domain_verify',
1118
+ 'domain_remove',
1119
+ 'sms_setup_status',
1120
+ 'surveys_list',
1121
+ 'survey_results',
1122
+ 'survey_create',
1123
+ 'survey_update',
1124
+ 'billing_portal_link',
728
1125
  ];
729
- export const TOOL_NAMES = TOOLS.map((t) => t.name);
1126
+ export const TOOL_NAMES = CORE_TOOL_NAMES;
1127
+ export const ALL_TOOL_NAMES = TOOLS.map((t) => t.name);
1128
+ export const SOCIAL_TOOL_NAMES = TOOLS.filter((t) => t.scope.startsWith('social_')).map((t) => t.name);
730
1129
  /** Run one tool and turn its outcome (or failure) into an MCP result. */
731
1130
  export async function runTool(def, api, args) {
732
1131
  try {
@@ -737,8 +1136,13 @@ export async function runTool(def, api, args) {
737
1136
  return errorResult(err, api.secrets);
738
1137
  }
739
1138
  }
740
- export function registerTools(server, api) {
741
- for (const def of TOOLS) {
1139
+ // Core tools always register (the API answers insufficient_scope for a key
1140
+ // that lacks one), as before social. Social tools register only when the
1141
+ // key holds that social scope, so keys without social see no social tools.
1142
+ export function registerTools(server, api, options) {
1143
+ const scopes = options?.scopes ?? api.scopes ?? [];
1144
+ const toolsToRegister = TOOLS.filter((def) => !def.scope.startsWith('social_') || scopes.includes(def.scope));
1145
+ for (const def of toolsToRegister) {
742
1146
  server.registerTool(def.name, {
743
1147
  title: def.title,
744
1148
  description: `${def.description} Requires API key scope: ${def.scope}.`,
package/dist/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const VERSION = "0.2.1";
1
+ export declare const VERSION = "0.4.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.1';
2
+ export const VERSION = '0.4.0';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "hollerpost-mcp",
3
- "version": "0.2.1",
3
+ "version": "0.4.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",