hollerpost-mcp 0.10.0 → 0.12.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,23 @@
1
1
  # Changelog
2
2
 
3
+ ## Unreleased (goes out in 0.12.0)
4
+
5
+ - `brand_set_footer`: up to 10 footer link buttons (was 5).
6
+ - Hollerpost admin keys (`hp_admin_...`, made on app.hollerpost.com/admin)
7
+ work in workspaces whose owner asked Hollerpost for help (Managed). With
8
+ one, the server adds `admin_list_managed_workspaces` and an optional
9
+ `workspace` argument (a workspace id) on every other tool, sent as
10
+ `X-Hollerpost-Workspace`. Billing, API keys, workspace deletion and
11
+ contact exports stay with the owner, and every call is logged. Workspace
12
+ keys see no change.
13
+
14
+ ## 0.11.0 (2026-11-17)
15
+
16
+ - `brand_set_theme` takes `theme.logo_dark`: an https image URL (store it
17
+ with `email_image_upload` first) for the logo shown when the reader's mail
18
+ app is in dark mode. `""` removes it. `brand_get` returns it as
19
+ `theme.logo_dark` (null when there is none).
20
+
3
21
  ## 0.10.0 (2026-11-16)
4
22
 
5
23
  - New `launchpad_domain_set` (`hostname`, `confirm: true`) and
@@ -0,0 +1,19 @@
1
+ import { z } from 'zod';
2
+ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3
+ import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
4
+ import type { HollerpostClient } from './client.js';
5
+ export declare const ADMIN_LIST_TOOL = "admin_list_managed_workspaces";
6
+ export declare const PICK_WORKSPACE_MESSAGE = "Pick a managed workspace first: call admin_list_managed_workspaces, then pass the workspace id as the workspace argument.";
7
+ export declare const WORKSPACE_ARG_DESCRIPTION = "Admin keys only: the id of the managed workspace to work in, from admin_list_managed_workspaces. Required with an admin key.";
8
+ export declare const ADMIN_INSTRUCTIONS = "This is a Hollerpost admin key. It works only in workspaces whose owner asked Hollerpost for help (managed workspaces). Call admin_list_managed_workspaces first, then pass that workspace id as the workspace argument on every other tool. Billing, API keys, deleting the workspace and contact exports stay with the owner. Every call is logged and the owner can see that Hollerpost worked in the workspace.";
9
+ export declare const workspaceArg: z.ZodOptional<z.ZodString>;
10
+ /**
11
+ * Wrap one workspace tool for an admin key: add `workspace` to its input
12
+ * shape, and run it with a client that names that workspace (and the tool,
13
+ * for the access log) on every request.
14
+ */
15
+ export declare function adminToolShape<S extends z.ZodRawShape>(name: string, input: S): S & {
16
+ workspace: typeof workspaceArg;
17
+ };
18
+ export declare function runAsAdmin(name: string, api: HollerpostClient, args: unknown, run: (scoped: HollerpostClient, rest: Record<string, unknown>) => Promise<CallToolResult>): Promise<CallToolResult>;
19
+ export declare function registerAdminTools(server: McpServer, api: HollerpostClient): void;
package/dist/admin.js ADDED
@@ -0,0 +1,58 @@
1
+ // Platform admin keys (hp_admin_...): Hollerpost staff working inside
2
+ // workspaces the owner asked for help with ("managed" workspaces).
3
+ //
4
+ // Only when the client holds an admin key:
5
+ // - admin_list_managed_workspaces is offered (GET /admin/managed-workspaces);
6
+ // - every workspace tool takes an optional `workspace` argument (a workspace
7
+ // id), sent as X-Hollerpost-Workspace. Without it the tool answers with
8
+ // PICK_WORKSPACE_MESSAGE and makes no request.
9
+ // With a workspace key, nothing here runs: schemas and behavior are as before.
10
+ //
11
+ // The API decides what an admin may do (billing, key management, deletion
12
+ // and contact export are refused) and logs every call.
13
+ import { z } from 'zod';
14
+ import { errorResult, InputError, okResult } from './format.js';
15
+ export const ADMIN_LIST_TOOL = 'admin_list_managed_workspaces';
16
+ export const PICK_WORKSPACE_MESSAGE = 'Pick a managed workspace first: call admin_list_managed_workspaces, then pass the workspace id as the workspace argument.';
17
+ export const WORKSPACE_ARG_DESCRIPTION = 'Admin keys only: the id of the managed workspace to work in, from admin_list_managed_workspaces. Required with an admin key.';
18
+ export const ADMIN_INSTRUCTIONS = 'This is a Hollerpost admin key. It works only in workspaces whose owner asked Hollerpost for help (managed workspaces). Call admin_list_managed_workspaces first, then pass that workspace id as the workspace argument on every other tool. Billing, API keys, deleting the workspace and contact exports stay with the owner. Every call is logged and the owner can see that Hollerpost worked in the workspace.';
19
+ export const workspaceArg = z.string().uuid('Use a workspace id (a UUID) from admin_list_managed_workspaces.').optional().describe(WORKSPACE_ARG_DESCRIPTION);
20
+ /**
21
+ * Wrap one workspace tool for an admin key: add `workspace` to its input
22
+ * shape, and run it with a client that names that workspace (and the tool,
23
+ * for the access log) on every request.
24
+ */
25
+ export function adminToolShape(name, input) {
26
+ if (Object.prototype.hasOwnProperty.call(input, 'workspace')) {
27
+ throw new Error(`tool ${name} already has a workspace argument; the admin wrapper would shadow it`);
28
+ }
29
+ return { ...input, workspace: workspaceArg };
30
+ }
31
+ export async function runAsAdmin(name, api, args, run) {
32
+ const { workspace, ...rest } = (args ?? {});
33
+ if (typeof workspace !== 'string' || !workspace) {
34
+ return errorResult(new InputError(PICK_WORKSPACE_MESSAGE), api.secrets);
35
+ }
36
+ const scoped = api.withHeaders({ 'X-Hollerpost-Workspace': workspace, 'X-Hollerpost-Tool': name });
37
+ return run(scoped, rest);
38
+ }
39
+ export function registerAdminTools(server, api) {
40
+ server.registerTool(ADMIN_LIST_TOOL, {
41
+ title: 'List managed workspaces',
42
+ description: 'Admin keys only. Lists the workspaces whose owner asked Hollerpost for help and that are marked Managed right now: id, name, page handle, and the reason and end date when set. Pass one id as the workspace argument on every other tool. Read only.',
43
+ inputSchema: z.object({}),
44
+ annotations: { title: 'List managed workspaces', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
45
+ }, async () => {
46
+ try {
47
+ const data = (await api.request('GET', '/admin/managed-workspaces'));
48
+ const list = Array.isArray(data?.data) ? data.data : [];
49
+ const lead = list.length
50
+ ? `${list.length} managed workspace${list.length === 1 ? '' : 's'}. Pass the id as workspace on other tools.`
51
+ : 'No workspaces are marked Managed right now. Turn Managed on for a workspace in the admin panel first.';
52
+ return okResult(lead, data, api.secrets);
53
+ }
54
+ catch (err) {
55
+ return errorResult(err, api.secrets);
56
+ }
57
+ });
58
+ }
package/dist/client.d.ts CHANGED
@@ -15,6 +15,8 @@ export interface ClientOptions {
15
15
  sleep?: (ms: number) => Promise<void>;
16
16
  /** Optional active scopes allowed for this client. */
17
17
  scopes?: string[];
18
+ /** Headers sent on every request (withHeaders sets them per tool call). */
19
+ defaultHeaders?: Record<string, string>;
18
20
  }
19
21
  export interface RequestOptions {
20
22
  query?: Record<string, string | number | boolean | undefined | null>;
@@ -37,6 +39,8 @@ export declare const redactString: typeof redactSecrets;
37
39
  export declare function redactDeep<T>(value: T, secrets?: string[]): T;
38
40
  /** Parse Retry-After (delta seconds or HTTP date) into milliseconds. */
39
41
  export declare function parseRetryAfter(header: string | null, now?: number): number | null;
42
+ /** A platform admin key (hp_admin_...): works in managed workspaces only, one per call. */
43
+ export declare const ADMIN_KEY_PATTERN: RegExp;
40
44
  export declare class HollerpostClient {
41
45
  readonly transport: TransportKind;
42
46
  readonly scopes?: string[];
@@ -44,7 +48,13 @@ export declare class HollerpostClient {
44
48
  private readonly baseUrl;
45
49
  private readonly fetchImpl;
46
50
  private readonly sleep;
51
+ private readonly defaultHeaders;
52
+ private readonly options;
47
53
  constructor(opts: ClientOptions);
54
+ /** True for a platform admin key (hp_admin_...). */
55
+ get isAdminKey(): boolean;
56
+ /** A copy of this client that adds these headers to every request. */
57
+ withHeaders(headers: Record<string, string>): HollerpostClient;
48
58
  /**
49
59
  * The scopes this key holds (from /me), or [] when that can't be read
50
60
  * (no key, a network error). Used only to decide which optional tools to
package/dist/client.js CHANGED
@@ -31,7 +31,7 @@ export class ApiError extends Error {
31
31
  this.local = local;
32
32
  }
33
33
  }
34
- const KEY_PATTERN = /\b(hp|uc)_(live|test)_[A-Za-z0-9_\-]+/g;
34
+ const KEY_PATTERN = /\b(hp|uc)_(live|test|admin)_[A-Za-z0-9_\-]+/g;
35
35
  const BEARER_PATTERN = /\bBearer\s+[A-Za-z0-9._\-~+/]+=*/gi;
36
36
  const SENSITIVE_JSON_KEY_PATTERN = /"(access_token|refresh_token|client_secret|app_password)"\s*:\s*"[^"]+"/gi;
37
37
  const SENSITIVE_PARAM_PATTERN = /\b(access_token|refresh_token|client_secret|app_password)=(\[redacted secret\]|[^\s&"']+)/gi;
@@ -93,6 +93,8 @@ export function parseRetryAfter(header, now = Date.now()) {
93
93
  return Math.max(0, at - now);
94
94
  }
95
95
  const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
96
+ /** A platform admin key (hp_admin_...): works in managed workspaces only, one per call. */
97
+ export const ADMIN_KEY_PATTERN = /^Bearer\s+hp_admin_/i;
96
98
  export class HollerpostClient {
97
99
  transport;
98
100
  scopes;
@@ -100,13 +102,25 @@ export class HollerpostClient {
100
102
  baseUrl;
101
103
  fetchImpl;
102
104
  sleep;
105
+ defaultHeaders;
106
+ options;
103
107
  constructor(opts) {
108
+ this.options = opts;
104
109
  this.transport = opts.transport;
105
110
  this.scopes = opts.scopes;
106
111
  this.authorization = opts.authorization?.trim() || null;
107
112
  this.baseUrl = (opts.baseUrl || DEFAULT_API_BASE).replace(/\/+$/, '');
108
113
  this.fetchImpl = opts.fetch ?? ((input, init) => fetch(input, init));
109
114
  this.sleep = opts.sleep ?? defaultSleep;
115
+ this.defaultHeaders = { ...(opts.defaultHeaders ?? {}) };
116
+ }
117
+ /** True for a platform admin key (hp_admin_...). */
118
+ get isAdminKey() {
119
+ return !!this.authorization && ADMIN_KEY_PATTERN.test(this.authorization);
120
+ }
121
+ /** A copy of this client that adds these headers to every request. */
122
+ withHeaders(headers) {
123
+ return new HollerpostClient({ ...this.options, defaultHeaders: { ...this.defaultHeaders, ...headers } });
110
124
  }
111
125
  /**
112
126
  * The scopes this key holds (from /me), or [] when that can't be read
@@ -116,6 +130,10 @@ export class HollerpostClient {
116
130
  async keyScopes() {
117
131
  if (!this.authorization)
118
132
  return [];
133
+ // An admin key has no workspace of its own, so /me has nothing to say;
134
+ // registerTools offers it every tool.
135
+ if (this.isAdminKey)
136
+ return [];
119
137
  try {
120
138
  const me = (await this.request('GET', '/me'));
121
139
  return Array.isArray(me?.scopes) ? me.scopes.filter((s) => typeof s === 'string') : [];
@@ -132,7 +150,7 @@ export class HollerpostClient {
132
150
  if (!this.authorization)
133
151
  return [];
134
152
  const token = this.authorization.replace(/^Bearer\s+/i, '');
135
- const bare = token.replace(/^(hp|uc)_(live|test)_/, '');
153
+ const bare = token.replace(/^(hp|uc)_(live|test|admin)_/, '');
136
154
  return [this.authorization, token, ...(bare.length >= 12 ? [bare] : [])];
137
155
  }
138
156
  hasKey() {
@@ -151,6 +169,7 @@ export class HollerpostClient {
151
169
  Authorization: this.authorization,
152
170
  Accept: 'application/json',
153
171
  'User-Agent': this.userAgent,
172
+ ...this.defaultHeaders,
154
173
  ...(opts.headers ?? {}),
155
174
  };
156
175
  const init = { method, headers };
package/dist/format.js CHANGED
@@ -180,6 +180,18 @@ export function describeApiError(err) {
180
180
  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.`;
181
181
  case 'tenant_key_required':
182
182
  return `${head} This is a platform key. The MCP server needs a workspace key (hp_live_... or uc_live_...).`;
183
+ // Admin keys (hp_admin_...), see src/admin.ts.
184
+ case 'workspace_required':
185
+ return `${head} Pick a managed workspace first: call admin_list_managed_workspaces, then pass the workspace id as the workspace argument.`;
186
+ case 'workspace_not_managed':
187
+ case 'invalid_workspace':
188
+ return `${head} That workspace is not one Hollerpost manages right now. Call admin_list_managed_workspaces and use an id from it. Nothing was changed.`;
189
+ case 'admin_access_not_allowed': {
190
+ const msg = typeof b.message === 'string' ? ` ${b.message}` : '';
191
+ return `${head} An admin key cannot do this; it stays with the workspace owner.${msg} Do not retry. Nothing was changed.`;
192
+ }
193
+ case 'admin_only':
194
+ return `${head} This needs a Hollerpost admin, and the key's owner is not one. Nothing was changed.`;
183
195
  case 'social_coming_soon':
184
196
  return `${head} Hollerpost Social isn't switched on for this workspace yet.`;
185
197
  case 'provider_not_available':
package/dist/resources.js CHANGED
@@ -25,7 +25,7 @@ export const RESOURCES = [
25
25
  name: 'templates',
26
26
  uri: 'hollerpost://templates',
27
27
  title: 'Templates',
28
- description: 'Email templates with the JSON Schema of the content blocks each one accepts.',
28
+ description: 'Email templates with the JSON Schema of their content blocks, plus email_themes page ids for blocks.theme.theme_id.',
29
29
  load: (api) => api.request('GET', '/templates'),
30
30
  },
31
31
  {
package/dist/server.js CHANGED
@@ -7,6 +7,7 @@ import { registerResources } from './resources.js';
7
7
  import { registerTools } from './tools.js';
8
8
  import { UNTRUSTED_DATA_NOTICE } from './format.js';
9
9
  import { VERSION } from './version.js';
10
+ import { ADMIN_INSTRUCTIONS } from './admin.js';
10
11
  export const SERVER_INSTRUCTIONS = [
11
12
  'Hollerpost sends email campaigns for a small business. You draft, preview, test and report; the person approves every send.',
12
13
  'Start with workspace_info to learn the plan, the key scopes and the brand voice.',
@@ -22,7 +23,9 @@ export const SERVER_INSTRUCTIONS = [
22
23
  // scopes: the key's scopes (client.keyScopes()), which decide whether the
23
24
  // social tools are offered.
24
25
  export function createServer(client, options = {}, scopes = null) {
25
- const server = new McpServer({ name: 'hollerpost-mcp', title: 'Hollerpost', version: VERSION, websiteUrl: 'https://hollerpost.com/docs/mcp/?utm_source=mcp-client&utm_medium=referral&utm_campaign=mcp' }, { instructions: SERVER_INSTRUCTIONS, ...options });
26
+ const server = new McpServer({ name: 'hollerpost-mcp', title: 'Hollerpost', version: VERSION, websiteUrl: 'https://hollerpost.com/docs/mcp/?utm_source=mcp-client&utm_medium=referral&utm_campaign=mcp' },
27
+ // An admin key (hp_admin_...) also hears how to pick a managed workspace.
28
+ { instructions: client.isAdminKey ? `${SERVER_INSTRUCTIONS} ${ADMIN_INSTRUCTIONS}` : SERVER_INSTRUCTIONS, ...options });
26
29
  registerTools(server, client, { scopes });
27
30
  registerResources(server, client);
28
31
  registerPrompts(server);
package/dist/tools.js CHANGED
@@ -12,6 +12,7 @@
12
12
  import { z } from 'zod';
13
13
  import { ApiError } from './client.js';
14
14
  import { errorResult, InputError, okResult, smsCheckProblems } from './format.js';
15
+ import { adminToolShape, registerAdminTools, runAsAdmin } from './admin.js';
15
16
  export const DEFAULT_ASSUMED_SCOPES = ['read', 'contacts', 'draft', 'send', 'webhooks', 'account'];
16
17
  export const ALL_SCOPES = [
17
18
  'read',
@@ -77,6 +78,7 @@ const infoBarSchema = z
77
78
  .describe('Dark band across the top of the email. An object sets it for this email (replacing the brand default); "off" hides the brand default for this email.');
78
79
  const themeSchema = z
79
80
  .object({
81
+ theme_id: z.string().regex(/^[a-z0-9-]{1,64}$/).optional().describe('Page theme id from templates_list email_themes. Matches its email-safe palette, local font stacks and shapes. Unknown ids use the current default.'),
80
82
  background: hexColor.optional().describe('Page color around the email.'),
81
83
  surface: hexColor.optional().describe('Email card color. A dark surface gets light text and light outline buttons automatically.'),
82
84
  text: hexColor.optional().describe('Body text color. Needs at least 4.5:1 contrast with surface (campaign_preview warns low_contrast_text).'),
@@ -271,53 +273,87 @@ const pageEventSchema = z.object({
271
273
  });
272
274
  // Your page fonts (L-43). Must match PAGE_FONTS and HEADING_FONTS in the API's
273
275
  // src/lib/page/validation.js (worker/page-themes.test.mjs checks).
274
- const PAGE_BODY_FONTS = ['Nunito Sans', 'Nunito', 'sans-serif', 'serif', 'monospace', 'Arial', 'Georgia', 'Lora', 'Outfit', 'Manrope', 'Bricolage Grotesque', 'Space Mono'];
275
- const PAGE_HEADING_FONTS = ['body', 'Fraunces', 'Instrument Serif', 'Lora', 'Outfit', 'Manrope', 'Bricolage Grotesque', 'Nunito', 'Nunito Sans', 'Unbounded', 'Caveat', 'Pacifico', 'Space Mono'];
276
+ const PAGE_BODY_FONTS = ['Nunito Sans', 'Nunito', 'sans-serif', 'serif', 'monospace', 'Arial', 'Georgia', 'Lora', 'Outfit', 'Manrope', 'Bricolage Grotesque', 'Space Mono', 'Chakra Petch', 'Barlow Condensed', 'Fredoka', 'Newsreader', 'JetBrains Mono', 'VT323', 'Bitter', 'Space Grotesk', 'Lexend', 'Alegreya'];
277
+ const PAGE_HEADING_FONTS = ['body', 'Fraunces', 'Instrument Serif', 'Lora', 'Outfit', 'Manrope', 'Bricolage Grotesque', 'Nunito', 'Nunito Sans', 'Unbounded', 'Caveat', 'Pacifico', 'Space Mono', 'Chakra Petch', 'Syne', 'Cormorant Garamond', 'Barlow Condensed', 'Archivo Black', 'Fredoka', 'Newsreader', 'Silkscreen', 'Orbitron', 'JetBrains Mono', 'VT323', 'Audiowide', 'Poiret One', 'Shrikhand', 'Bitter', 'Rubik Mono One', 'Space Grotesk', 'Lexend', 'Alegreya', 'Bungee'];
276
278
  // L-46 story sections. The API checks the same rules (and the image host).
277
279
  const pageSectionSchema = z.object({
278
280
  id: z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9-]{0,39}$/).optional().describe('Keep the id of an existing section; leave it out for a new one.'),
279
281
  kind: z.literal('story').optional().describe('Always story.'),
280
282
  heading: z.string().min(1).max(80).describe('Section heading, plain text.'),
281
283
  body: z.string().min(1).max(1500).describe('Plain text. Separate paragraphs with a blank line. No HTML, no markdown links.'),
282
- image_url: z.string().max(2048).optional().describe('Optional picture. Must be an https://images.hollerpost.com URL: store it with email_image_upload first.'),
284
+ image_url: z.string().max(2048).optional().describe('Optional picture. Must be an https://images.hollerpost.com URL (uploaded with email_image_upload or from the Hollerpost stock catalog).'),
283
285
  image_alt: z.string().max(200).optional().describe('Required with image_url: what the picture shows.'),
284
286
  }).strict();
285
287
  // Advanced Launchpad editor: the launch page as blocks. The API checks the
286
288
  // same rules (src/lib/page/design.js), including contrast and the image host.
287
289
  const designText = (max) => z.string().max(max);
288
- const designImage = z.string().max(2048).describe('A picture stored with email_image_upload (https://images.hollerpost.com/...). Other hosts are refused.');
290
+ // Must match HOURS_DAY_LABELS and the new block rules in design.js.
291
+ const HOURS_DAY_LABELS = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun', 'Mon to Tue', 'Mon to Wed', 'Mon to Thu', 'Mon to Fri', 'Mon to Sat', 'Mon to Sun', 'Tue to Wed', 'Tue to Thu', 'Tue to Fri', 'Tue to Sat', 'Tue to Sun', 'Wed to Thu', 'Wed to Fri', 'Wed to Sat', 'Wed to Sun', 'Thu to Fri', 'Thu to Sat', 'Thu to Sun', 'Fri to Sat', 'Fri to Sun', 'Sat to Sun'];
292
+ const blockMarkup = /<\/?[a-z!?][^>]*>|\[[^\]\n]*\]\([^)\s]*\)|https?:\/\/|javascript\s*:|data\s*:(?=\S|\s*(?:[\w.+-]+\/[\w.+-]+|;|,))|`|(^|\s)[*_]{1,3}\S|(^|\n)\s{0,3}(?:#{1,6}\s|>\s|[-+*]\s)/i;
293
+ const blockText = (max) => z.string().trim().max(max).refine(v => !blockMarkup.test(v), 'Use plain text, without Markdown or URLs.');
294
+ function visiblePageText(v) {
295
+ return /[\p{L}\p{N}\p{P}\p{S}]/u.test(v.replace(/[\p{Default_Ignorable_Code_Point}\u2800]/gu, ''));
296
+ }
297
+ const requiredDesignText = (max) => designText(max).min(1).refine(visiblePageText, 'Enter visible text.');
298
+ const requiredBlockText = (max) => blockText(max).min(1).refine(visiblePageText, 'Enter visible text.');
299
+ const galleryImage = z.string().max(2048).refine(v => {
300
+ try {
301
+ if (/\\|\s|\p{Cc}/u.test(v))
302
+ return false;
303
+ const host = v.match(/^https:\/\/([a-z0-9.-]+)(?:[/?#]|$)/i)?.[1]?.toLowerCase();
304
+ const u = new URL(v);
305
+ return !!host && ['images.hollerpost.com', 'images-staging.hollerpost.com'].includes(host) && !u.port && !u.username && !u.password;
306
+ }
307
+ catch {
308
+ return false;
309
+ }
310
+ }, 'Use a canonical HTTPS upload URL without a port.');
311
+ const designImage = z.union([z.literal(''), galleryImage]).describe('An uploaded or stock Hollerpost picture on images.hollerpost.com; blank only for the optional hero image.');
312
+ const hoursRow = z.union([
313
+ z.object({ day: z.enum(HOURS_DAY_LABELS), open: requiredBlockText(20), close: requiredBlockText(20), closed: z.literal(false).optional() }).strict(),
314
+ z.object({ day: z.enum(HOURS_DAY_LABELS), open: blockText(0).optional(), close: blockText(0).optional(), closed: z.literal(true) }).strict(),
315
+ ]);
289
316
  const designBlockSchema = z.discriminatedUnion('type', [
290
- z.object({ type: z.literal('hero'), id: z.string().optional(), headline: designText(120).min(1).describe('The page headline (the only h1).'), text: designText(600).optional().describe('Plain text under the headline. Blank line = new paragraph.'), image_url: designImage.optional(), image_alt: designText(200).optional().describe('Required with image_url.'), show_logo: z.boolean().optional().describe('Show the page logo (avatar_url) above the headline.') }).strict(),
291
- z.object({ type: z.literal('text'), id: z.string().optional(), heading: designText(120).optional(), body: designText(2000).min(1).describe('Plain text. No HTML or markdown links.') }).strict(),
292
- z.object({ type: z.literal('image'), id: z.string().optional(), image_url: designImage, image_alt: designText(200).min(1).describe('What the picture shows.'), link_url: z.string().max(2048).optional().describe('Optional https link when the picture is tapped.'), caption: designText(200).optional() }).strict(),
293
- z.object({ type: z.literal('button'), id: z.string().optional(), label: designText(60).min(1), url: z.string().max(2048).describe('Full https link. URL shorteners are refused.') }).strict(),
294
- z.object({ type: z.literal('list'), id: z.string().optional(), heading: designText(120).optional(), style: z.enum(['bullets', 'checks', 'cards']).optional(), items: z.array(z.object({ title: designText(80).optional(), text: designText(300).optional() }).strict()).min(1).max(12) }).strict(),
317
+ z.object({ type: z.literal('hero'), id: z.string().optional(), headline: requiredDesignText(120).describe('The page headline (the only h1).'), text: designText(600).optional().describe('Plain text under the headline. Blank line = new paragraph.'), image_url: designImage.optional(), image_alt: designText(200).optional().describe('Required with image_url.'), show_logo: z.boolean().optional().describe('Show the page logo (avatar_url) above the headline.') }).strict().superRefine((b, ctx) => { if (b.image_url && !visiblePageText(b.image_alt || ''))
318
+ ctx.addIssue({ code: 'custom', path: ['image_alt'], message: 'Describe the picture with visible text.' }); }),
319
+ z.object({ type: z.literal('text'), id: z.string().optional(), heading: designText(120).optional(), body: requiredDesignText(2000).describe('Plain text. No HTML or markdown links.') }).strict(),
320
+ z.object({ type: z.literal('image'), id: z.string().optional(), image_url: galleryImage, image_alt: requiredDesignText(200).describe('What the picture shows.'), link_url: z.string().max(2048).optional().describe('Optional https link when the picture is tapped.'), caption: designText(200).optional() }).strict(),
321
+ z.object({ type: z.literal('button'), id: z.string().optional(), label: requiredDesignText(60), url: z.string().max(2048).describe('Full https link. URL shorteners are refused.') }).strict(),
322
+ z.object({ type: z.literal('list'), id: z.string().optional(), heading: designText(120).optional(), style: z.enum(['bullets', 'checks', 'cards']).optional(), items: z.array(z.object({ title: designText(80).optional(), text: designText(300).optional() }).strict().refine(item => visiblePageText(item.title || '') || visiblePageText(item.text || ''), 'Enter visible text.')).min(1).max(12) }).strict(),
295
323
  z.object({ type: z.literal('countdown'), id: z.string().optional(), heading: designText(80).optional().describe('Default "Launching".'), date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).describe('Launch date, YYYY-MM-DD.'), show_days: z.boolean().optional().describe('Also show "N days to go".') }).strict(),
296
- z.object({ type: z.literal('faq'), id: z.string().optional(), heading: designText(120).optional(), items: z.array(z.object({ question: designText(160).min(1), answer: designText(1000).min(1) }).strict()).min(1).max(12) }).strict(),
324
+ z.object({ type: z.literal('faq'), id: z.string().optional(), heading: designText(120).optional(), items: z.array(z.object({ question: requiredDesignText(160), answer: requiredDesignText(1000) }).strict()).min(1).max(12) }).strict(),
297
325
  z.object({ type: z.literal('social'), id: z.string().optional(), items: 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().describe('Handle or full profile link.') }).strict()).min(1).max(15) }).strict(),
326
+ z.object({ type: z.literal('hours'), id: z.string().optional(), heading: blockText(120).optional(), rows: z.array(hoursRow).min(1).max(7), note: blockText(120).optional() }).strict(),
327
+ z.object({ type: z.literal('gallery'), id: z.string().optional(), heading: blockText(120).optional(), images: z.array(z.object({ image_url: galleryImage, image_alt: requiredBlockText(140), caption: blockText(80).optional() }).strict()).min(1).max(12) }).strict(),
328
+ z.object({ type: z.literal('offers'), id: z.string().optional(), heading: blockText(120).optional(), items: z.array(z.object({ name: requiredBlockText(60), note: blockText(140).optional(), label: blockText(20).optional(), price: blockText(20).optional().describe('Owner-supplied plain text. Never calculate or invent a price.') }).strict()).min(1).max(12) }).strict(),
298
329
  z.object({ type: z.literal('divider'), id: z.string().optional() }).strict(),
299
330
  z.object({ type: z.literal('spacer'), id: z.string().optional(), size: z.enum(['sm', 'md', 'lg']).optional() }).strict(),
300
331
  z.object({ type: z.literal('signup'), id: z.string().optional(), heading: designText(120).optional().describe('Default: "Join <page title>".'), text: designText(300).optional(), button_label: designText(40).optional() }).strict(),
301
332
  ]);
302
333
  const hex = z.string().regex(/^#[0-9a-fA-F]{6}$/);
303
334
  // Page motion (11/16). Must match MOTION_LEVELS in the API's src/lib/page/validation.js.
304
- const pageMotion = z.enum(['lively', 'subtle', 'off']).optional().describe('How much the page moves. lively (default): gentle entrance, button lift, signup shine, a small celebration on joining. subtle: soft fade and small hover lifts. off: no movement. Visitors who ask their device for reduced motion always get none.');
335
+ const pageMotion = z.enum(['lively', 'subtle', 'off', 'cyber-pulse', 'editorial-fade']).optional().describe('How much the page moves. lively (default): gentle entrance, button lift, signup shine, a small celebration on joining. subtle: soft fade and small hover lifts. off: no movement. Visitors who ask their device for reduced motion always get none.');
305
336
  const launchDesignSchema = z.object({
306
337
  version: z.literal(1).optional(),
307
338
  mode: z.enum(['advanced', 'simple']).optional().describe('advanced (default) shows the blocks. simple goes back to the simple page and keeps these blocks saved.'),
308
339
  style: z.object({
309
340
  backgroundColor: hex.optional(), surfaceColor: hex.optional().describe('Boxes and cards (signup box, FAQ, list cards).'), textColor: hex.optional(),
310
- accentColor: hex.optional().describe('Buttons.'), buttonTextColor: hex.optional(),
341
+ accentColor: hex.optional().describe('Button color for legacy styles; decorative accent when brandColor is present.'), buttonTextColor: hex.optional(),
311
342
  fontFamily: z.enum(PAGE_BODY_FONTS).optional(), headingFont: z.enum(PAGE_HEADING_FONTS).optional().describe('body means the same as fontFamily.'),
312
343
  buttonShape: z.enum(['square', 'rounded', 'pill']).optional(), buttonStyle: z.enum(['solid', 'outline']).optional(),
313
344
  motion: pageMotion,
314
- }).strict().optional().describe('Page look. Text on background and on surface, and button text on accent, each need 4.5:1 contrast (the API refuses less).'),
315
- blocks: z.array(designBlockSchema).max(30).describe('The whole page, top to bottom. Exactly one signup block (required). At most one hero, one countdown and one social block. Plain text only; links https only; pictures from images.hollerpost.com with alt text. Keep ids from launchpad_get to keep blocks.'),
345
+ backgroundStyle: z.enum(['solid', 'gradient', 'glow', 'dots', 'grid', 'lined', 'stripes', 'checker', 'sunburst', 'scanlines', 'cybergrid', 'noise', 'halftone', 'contour', 'glitch-bands', 'rain-streaks', 'horizon-grid', 'woven', 'vinyl-grooves', 'retro-waves', 'margin-rule', 'arch-scallop', 'chevron']).optional(),
346
+ layout: z.enum(['centered', 'left', 'card', 'framed', 'split-hero']).optional(),
347
+ cardStyle: z.enum(['flat', 'hairline', 'hard-shadow', 'soft-elevated', 'neon-glow', 'notched', 'offset-print', 'film-frame', 'glitch-split', 'status-bezel', 'window-bevel', 'stitched', 'letterpress-inset', 'gallery-mat', 'accent-rail', 'arch-frame']).optional(),
348
+ linkStyle: z.enum(['button', 'outline', 'pill', 'todo', 'checklist', 'microchip', 'clouds', 'ticket', 'neon-wire', 'editorial-rule', 'brutalist-block', 'circuit', 'sticker', 'terminal-prompt', 'keycap', 'bevel-btn', 'banner-flag']).optional(),
349
+ brandColor: hex.optional().describe('Existing theme button color when accentColor carries the decorative accent.'),
350
+ }).strict().optional().describe('Page look. Text on background and on surface, and button text on the CTA color (brandColor when supplied, otherwise accentColor), each need 4.5:1 contrast (the API refuses less).'),
351
+ blocks: z.array(designBlockSchema).max(30).describe('The whole page, top to bottom. Exactly one signup block (required). At most one hero, one countdown, one social and one hours block, and at most three gallery and three offers blocks. Plain text only; links https only; pictures from images.hollerpost.com with alt text. Keep ids from launchpad_get to keep blocks.'),
316
352
  }).strict();
317
353
  // Your page only (L-45). Waitlist fields live on the launch page: launchpad_update.
318
354
  const pageUpdateSchema = z.object({
319
355
  title: z.string().max(120).optional(), tagline: z.string().max(240).optional(), avatar_url: z.union([z.string().max(2048), z.null()]).optional(),
320
- 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.'), motion: pageMotion }).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(),
356
+ 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', 'neon-wire', 'editorial-rule', 'brutalist-block', 'circuit', 'sticker', 'terminal-prompt', 'keycap', 'bevel-btn', 'banner-flag']).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', 'scanlines', 'cybergrid', 'noise', 'halftone', 'contour', 'glitch-bands', 'rain-streaks', 'horizon-grid', 'woven', 'vinyl-grooves', 'retro-waves', 'margin-rule', 'arch-scallop', 'chevron']).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', 'framed', 'split-hero']).optional().describe('centered, left aligned, or the page on a card over the background.'), cardStyle: z.enum(['flat', 'hairline', 'hard-shadow', 'soft-elevated', 'neon-glow', 'notched', 'offset-print', 'film-frame', 'glitch-split', 'status-bezel', 'window-bevel', 'stitched', 'letterpress-inset', 'gallery-mat', 'accent-rail', 'arch-frame']).optional(), motion: pageMotion }).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(),
321
357
  show_badge: z.boolean().optional(), signup_form_id: z.string().uuid().nullable().optional(),
322
358
  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().describe('The handle (like yourbusiness) or the full profile link. Saved as the full https link. WhatsApp takes the number with country code.') })).max(15).optional(),
323
359
  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(),
@@ -475,7 +511,7 @@ export const TOOLS = [
475
511
  name: 'brand_get',
476
512
  title: 'Get brand',
477
513
  scope: 'read',
478
- description: 'Returns the brand settings: workspace and from name, reply-to, logo, colors, the theme (background, surface, text, button_style, button_shape), the default info_bar, the footer (address, link buttons, disclaimer, social_icons), social profile links, the saved writing voice and the sending domain status. Free and read only. Read this before writing any campaign copy and follow the voice exactly.',
514
+ description: 'Returns the brand settings: workspace and from name, reply-to, logo, colors, the theme (background, surface, text, button_style, button_shape, logo_dark: the logo shown when the reader\u2019s mail app is in dark mode, null when there is none), the default info_bar, the footer (address, link buttons, disclaimer, social_icons), social profile links, the saved writing voice and the sending domain status. Free and read only. Read this before writing any campaign copy and follow the voice exactly.',
479
515
  input: {},
480
516
  annotations: READ,
481
517
  run: async (api) => {
@@ -501,10 +537,10 @@ export const TOOLS = [
501
537
  name: 'brand_set_footer',
502
538
  title: 'Save email footer',
503
539
  scope: 'draft',
504
- description: 'Saves the footer every email carries, above the mailing address and unsubscribe link (those two are always added and cannot be changed here): up to 5 full-width link buttons (links, for example Shop men\u2019s, Find your store), the "Follow us" social icon row (social handles plus social_icons: true), and a small disclaimer (pricing or legal note). Fields you leave out stay as they are; links: [] removes the buttons, disclaimer: "" removes the note. Applies to every email sent after saving, including scheduled ones that have not gone out yet. Uses no quota and sends nothing. Read brand_get first and only save what the person approved. ' +
540
+ description: 'Saves the footer every email carries, above the mailing address and unsubscribe link (those two are always added and cannot be changed here): up to 10 full-width link buttons (links, for example Shop men\u2019s, Find your store), the "Follow us" social icon row (social handles plus social_icons: true), and a small disclaimer (pricing or legal note). Fields you leave out stay as they are; links: [] removes the buttons, disclaimer: "" removes the note. Applies to every email sent after saving, including scheduled ones that have not gone out yet. Uses no quota and sends nothing. Read brand_get first and only save what the person approved. ' +
505
541
  'Example: {"links": [{"label": "Shop men\u2019s", "url": "https://shop.example/men"}, {"label": "Find your store", "url": "https://shop.example/stores"}], "social": {"instagram": "shopexample", "youtube": "shopexample"}, "social_icons": true, "disclaimer": "Prices may differ in stores."}',
506
542
  input: {
507
- links: z.array(footerLinkSchema).max(5).optional().describe('Footer link buttons, top to bottom. Replaces the current list.'),
543
+ links: z.array(footerLinkSchema).max(10).optional().describe('Footer link buttons, top to bottom. Replaces the current list.'),
508
544
  disclaimer: z.string().max(1500).optional().describe('Small print above the address, for example pricing, shipping or legal notes. **bold**, *italic* and [links](https://...) work. "" removes it.'),
509
545
  social: z
510
546
  .object(Object.fromEntries(SOCIAL_NETWORKS.map((n) => [n, z.string().max(300).optional()])))
@@ -537,7 +573,7 @@ export const TOOLS = [
537
573
  name: 'brand_set_theme',
538
574
  title: 'Save email look',
539
575
  scope: 'draft',
540
- description: 'Saves the default look of every email: theme colors (background, surface, text), buttons (button_style solid or outline, button_shape pill or rounded) and the info bar, a dark band across the top (for example free shipping). A single campaign can override any of these with blocks.theme and blocks.info_bar. Fields you leave out stay as they are; info_bar: null removes the bar; a color "" goes back to the default. Text needs 4.5:1 contrast with the surface; campaign_preview warns when it does not. Uses no quota and sends nothing. Only save what the person approved. ' +
576
+ description: 'Saves the default look of every email: theme colors (background, surface, text), buttons (button_style solid or outline, button_shape pill or rounded), the dark-mode logo (logo_dark) and the info bar, a dark band across the top (for example free shipping). A single campaign can override any of these with blocks.theme and blocks.info_bar. Fields you leave out stay as they are; info_bar: null removes the bar; a color "" goes back to the default. Text needs 4.5:1 contrast with the surface; campaign_preview warns when it does not. logo_dark is a light-colored version of the logo for readers in dark mode (Apple Mail, iOS Mail, Outlook.com); store it first with email_image_upload (a PNG with a transparent background works best) and pass the returned url; "" removes it. Uses no quota and sends nothing. Only save what the person approved. ' +
541
577
  'Example: {"theme": {"surface": "#ffffff", "text": "#27272a", "button_style": "outline", "button_shape": "pill"}, "info_bar": {"text": "Free shipping on orders over $99", "url": "https://shop.example/shipping"}}',
542
578
  input: {
543
579
  theme: z
@@ -547,6 +583,7 @@ export const TOOLS = [
547
583
  text: hexColor.or(z.literal('')).optional().describe('Body text color.'),
548
584
  button_style: z.enum(['solid', 'outline']).nullable().optional().describe('solid or outline; null goes back to solid.'),
549
585
  button_shape: z.enum(['pill', 'rounded']).nullable().optional().describe('pill or rounded; null goes back to the brand radius.'),
586
+ logo_dark: https.max(2000).or(z.literal('')).optional().describe('Logo for dark mode: an https image URL from email_image_upload, light-colored so it reads on a dark background. "" removes it.'),
550
587
  })
551
588
  .strict()
552
589
  .optional(),
@@ -577,7 +614,7 @@ export const TOOLS = [
577
614
  name: 'templates_list',
578
615
  title: 'List templates',
579
616
  scope: 'read',
580
- 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.',
617
+ 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). Also returns email_themes with page theme ids; pass one as blocks.theme.theme_id to match its palette, local font stacks and email-safe shapes. Free and read only. Pick a template here before campaign_draft and fill only the blocks its schema accepts.',
581
618
  input: {},
582
619
  annotations: READ,
583
620
  run: async (api) => {
@@ -1566,15 +1603,26 @@ export async function runTool(def, api, args) {
1566
1603
  // Core tools always register (the API answers insufficient_scope for a key
1567
1604
  // that lacks one), as before social. Social tools register only when the
1568
1605
  // key holds that social scope, so keys without social see no social tools.
1606
+ //
1607
+ // An admin key (hp_admin_...) gets every tool, each with an optional
1608
+ // `workspace` argument (src/admin.ts), plus admin_list_managed_workspaces.
1609
+ // Workspace keys see exactly the schemas they always did.
1569
1610
  export function registerTools(server, api, options) {
1570
- const scopes = options?.scopes ?? api.scopes ?? [];
1611
+ const admin = api.isAdminKey;
1612
+ const scopes = admin ? ALL_SCOPES : (options?.scopes ?? api.scopes ?? []);
1571
1613
  const toolsToRegister = TOOLS.filter((def) => !def.scope.startsWith('social_') || scopes.includes(def.scope));
1572
1614
  for (const def of toolsToRegister) {
1573
1615
  server.registerTool(def.name, {
1574
1616
  title: def.title,
1575
- description: `${def.description} Requires API key scope: ${def.scope}.`,
1576
- inputSchema: z.object(def.input),
1617
+ description: admin
1618
+ ? `${def.description} Admin key: pass workspace (an id from admin_list_managed_workspaces).`
1619
+ : `${def.description} Requires API key scope: ${def.scope}.`,
1620
+ inputSchema: z.object(admin ? adminToolShape(def.name, def.input) : def.input),
1577
1621
  annotations: { title: def.title, ...def.annotations },
1578
- }, async (args) => runTool(def, api, args));
1622
+ }, admin
1623
+ ? async (args) => runAsAdmin(def.name, api, args, (scoped, rest) => runTool(def, scoped, rest))
1624
+ : async (args) => runTool(def, api, args));
1579
1625
  }
1626
+ if (admin)
1627
+ registerAdminTools(server, api);
1580
1628
  }
package/dist/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const VERSION = "0.10.0";
1
+ export declare const VERSION = "0.12.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.10.0';
2
+ export const VERSION = '0.12.0';
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "hollerpost-mcp",
3
3
  "mcpName": "com.hollerpost/mcp",
4
- "version": "0.10.0",
4
+ "version": "0.12.0",
5
5
  "description": "MCP server for Hollerpost: let your own AI agent draft, preview, schedule and report on email campaigns in your Hollerpost workspace.",
6
6
  "license": "MIT",
7
7
  "type": "module",