hollerpost-mcp 0.1.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/README.md +230 -0
- package/dist/client.d.ts +49 -0
- package/dist/client.js +163 -0
- package/dist/format.d.ts +25 -0
- package/dist/format.js +142 -0
- package/dist/prompts.d.ts +15 -0
- package/dist/prompts.js +122 -0
- package/dist/resources.d.ts +13 -0
- package/dist/resources.js +72 -0
- package/dist/server.d.ts +7 -0
- package/dist/server.js +23 -0
- package/dist/stdio.d.ts +2 -0
- package/dist/stdio.js +27 -0
- package/dist/tools.d.ts +25 -0
- package/dist/tools.js +562 -0
- package/dist/version.d.ts +1 -0
- package/dist/version.js +2 -0
- package/package.json +48 -0
package/dist/prompts.js
ADDED
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
// MCP prompts: reusable starting points that clients show in their UI.
|
|
2
|
+
import { z } from 'zod';
|
|
3
|
+
const SAFETY = [
|
|
4
|
+
'Ground rules:',
|
|
5
|
+
'- Never schedule or send anything without the person saying yes to the exact audience count first.',
|
|
6
|
+
'- Only add contacts the person confirms opted in to email from this business.',
|
|
7
|
+
'- You cannot change plans or buy anything. For billing, give the link from billing_portal_link.',
|
|
8
|
+
'- If a tool reports insufficient_scope, tell the person which scope is missing and that the owner can enable it in Dashboard, Settings, Developer API.',
|
|
9
|
+
].join('\n');
|
|
10
|
+
export const PROMPTS = [
|
|
11
|
+
{
|
|
12
|
+
name: 'write_campaign',
|
|
13
|
+
title: 'Write a campaign',
|
|
14
|
+
description: 'Draft an on-brand campaign about a topic, preview it, send a test, and stop before scheduling.',
|
|
15
|
+
args: {
|
|
16
|
+
topic: z.string().describe('What the campaign is about, for example "fall sale, 20% off color services".'),
|
|
17
|
+
audience_tag: z.string().optional().describe('Optional tag to send to (see segments_list). Leave empty to ask.'),
|
|
18
|
+
},
|
|
19
|
+
build: (a) => [
|
|
20
|
+
`Write a Hollerpost email campaign about: ${a.topic ?? '(ask me for the topic)'}.`,
|
|
21
|
+
a.audience_tag ? `Audience: contacts tagged "${a.audience_tag}".` : 'Audience: ask me which tag to send to, after showing me segments_list.',
|
|
22
|
+
'',
|
|
23
|
+
'Steps:',
|
|
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.',
|
|
26
|
+
'3. Call campaign_draft. Show me the subject, preheader and copy, plus the preview_url.',
|
|
27
|
+
'4. Call campaign_preview and tell me the audience count, the quota it uses and every warning.',
|
|
28
|
+
'5. Offer campaign_send_test to my address and send it if I agree.',
|
|
29
|
+
'6. Stop. Ask me whether to schedule, and when. Do not call campaign_schedule until I say yes to the audience count.',
|
|
30
|
+
'',
|
|
31
|
+
SAFETY,
|
|
32
|
+
].join('\n'),
|
|
33
|
+
},
|
|
34
|
+
{
|
|
35
|
+
name: 'weekly_report',
|
|
36
|
+
title: 'Weekly report',
|
|
37
|
+
description: 'Summarize the last 7 days of campaigns and their stats in plain words.',
|
|
38
|
+
build: () => [
|
|
39
|
+
'Write a short weekly report for my Hollerpost workspace covering the last 7 days.',
|
|
40
|
+
'',
|
|
41
|
+
'Steps:',
|
|
42
|
+
'1. Call campaigns_list with status sent (and sending), and keep the ones from the last 7 days.',
|
|
43
|
+
'2. Call campaign_stats for each of them.',
|
|
44
|
+
'3. Call events_recent for email.bounced and email.complained to spot list problems.',
|
|
45
|
+
'4. Write a plain summary: what went out, delivered, open and click rates, unsubscribes, bounces and complaints, the best performing subject line, and one or two practical suggestions.',
|
|
46
|
+
'',
|
|
47
|
+
'Read only: do not draft, schedule or change anything.',
|
|
48
|
+
].join('\n'),
|
|
49
|
+
},
|
|
50
|
+
{
|
|
51
|
+
name: 'setup_workspace',
|
|
52
|
+
title: 'Set up my workspace',
|
|
53
|
+
description: 'Onboarding from chat: check the account, add and verify a sending domain, save the brand voice, import first contacts with consent, draft a welcome campaign, and stop before scheduling.',
|
|
54
|
+
args: {
|
|
55
|
+
domain: z.string().optional().describe('The domain to send from, for example mail.example.com. Leave empty to be asked.'),
|
|
56
|
+
},
|
|
57
|
+
build: (a) => [
|
|
58
|
+
'Set up my Hollerpost workspace with me, one step at a time. Wait for my answer where a step needs one.',
|
|
59
|
+
'',
|
|
60
|
+
'1. Call workspace_info and account_get. Tell me the plan, trial status and which scopes this key has. If a scope you need is missing, tell me which and where to enable it.',
|
|
61
|
+
a.domain
|
|
62
|
+
? `2. Call domain_add for ${a.domain}.`
|
|
63
|
+
: '2. Ask which domain I want to send from (a subdomain like mail.mybusiness.com is a good choice), then call domain_add.',
|
|
64
|
+
'3. Hand me the DNS records as a table. If you have a DNS tool for the registrar_hint provider connected (for example a Cloudflare MCP), offer to add the records yourself and do it only if I agree.',
|
|
65
|
+
'4. Call domain_verify. If records are missing, explain each one in plain words, wait a few minutes and verify again until it is verified.',
|
|
66
|
+
'5. Call brand_get. Ask me how my business talks to customers, and save my answer with brand_set_voice once I approve the wording. If the footer address or from name is missing, ask and save with account_update.',
|
|
67
|
+
'6. Ask me to paste my first contacts. For each, confirm they agreed to get email from me, then add them with contacts_add (consent true). Skip anyone I am unsure about.',
|
|
68
|
+
'7. Draft a welcome campaign with campaign_draft, run campaign_preview, and offer a campaign_send_test to my address.',
|
|
69
|
+
'8. Stop before scheduling. Tell me the audience count and that the first campaign goes to a quick human review at Hollerpost before it sends.',
|
|
70
|
+
'',
|
|
71
|
+
SAFETY,
|
|
72
|
+
].join('\n'),
|
|
73
|
+
},
|
|
74
|
+
{
|
|
75
|
+
name: 'fix_domain',
|
|
76
|
+
title: 'Fix my sending domain',
|
|
77
|
+
description: 'Run a verification, explain every failing DNS record in plain words, and offer to fix it with a connected DNS tool.',
|
|
78
|
+
args: {
|
|
79
|
+
domain: z.string().describe('The sending domain to check, for example mail.example.com.'),
|
|
80
|
+
},
|
|
81
|
+
build: (a) => [
|
|
82
|
+
`Check the Hollerpost sending domain ${a.domain ?? '(ask me which domain)'}.`,
|
|
83
|
+
'',
|
|
84
|
+
'1. Call domain_verify for it.',
|
|
85
|
+
'2. For each record that is not found, explain in plain words what is wrong (missing, wrong value, wrong host, proxied when it should not be) using expected vs actual.',
|
|
86
|
+
'3. If you have a DNS provider tool connected for this domain, offer to correct the records and only change them if I agree. Otherwise give me exact step-by-step instructions for my registrar (see registrar_hint from domain_list).',
|
|
87
|
+
'4. After changes, wait a few minutes and run domain_verify again.',
|
|
88
|
+
'',
|
|
89
|
+
'Never remove the domain unless I explicitly ask.',
|
|
90
|
+
].join('\n'),
|
|
91
|
+
},
|
|
92
|
+
{
|
|
93
|
+
name: 'clean_list',
|
|
94
|
+
title: 'Review list health',
|
|
95
|
+
description: 'List recent bounces and complaints and explain what they mean. Proposes nothing destructive.',
|
|
96
|
+
build: () => [
|
|
97
|
+
'Review the health of my Hollerpost contact list.',
|
|
98
|
+
'',
|
|
99
|
+
'1. Call events_recent with type email.bounced, then with type email.complained.',
|
|
100
|
+
'2. Group the addresses: hard bounces, repeat bounces, complaints. Hollerpost already suppresses bounced and complaining addresses automatically, so explain that no action is needed to stop mailing them.',
|
|
101
|
+
'3. Point out patterns (one domain bouncing a lot, a recent import with many bounces, a campaign that drew complaints) and suggest practical fixes such as better opt-in at signup.',
|
|
102
|
+
'',
|
|
103
|
+
'Do not change, delete or add anything. There is no delete tool on purpose.',
|
|
104
|
+
].join('\n'),
|
|
105
|
+
},
|
|
106
|
+
];
|
|
107
|
+
export function buildPrompt(def, args) {
|
|
108
|
+
return {
|
|
109
|
+
description: def.description,
|
|
110
|
+
messages: [{ role: 'user', content: { type: 'text', text: def.build(args) } }],
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
export function registerPrompts(server) {
|
|
114
|
+
for (const def of PROMPTS) {
|
|
115
|
+
if (def.args) {
|
|
116
|
+
server.registerPrompt(def.name, { title: def.title, description: def.description, argsSchema: def.args }, ((args) => buildPrompt(def, args ?? {})));
|
|
117
|
+
}
|
|
118
|
+
else {
|
|
119
|
+
server.registerPrompt(def.name, { title: def.title, description: def.description }, () => buildPrompt(def, {}));
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
}
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
|
+
import type { ReadResourceResult } from '@modelcontextprotocol/sdk/types.js';
|
|
3
|
+
import { type HollerpostClient } from './client.js';
|
|
4
|
+
export interface ResourceDef {
|
|
5
|
+
name: string;
|
|
6
|
+
uri: string;
|
|
7
|
+
title: string;
|
|
8
|
+
description: string;
|
|
9
|
+
load: (api: HollerpostClient) => Promise<unknown>;
|
|
10
|
+
}
|
|
11
|
+
export declare const RESOURCES: ResourceDef[];
|
|
12
|
+
export declare function readResource(def: ResourceDef, api: HollerpostClient): Promise<ReadResourceResult>;
|
|
13
|
+
export declare function registerResources(server: McpServer, api: HollerpostClient): void;
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
// MCP resources: read-only context a client can attach without a tool call.
|
|
2
|
+
import { ApiError, redactDeep, redactString } from './client.js';
|
|
3
|
+
import { describeApiError } from './format.js';
|
|
4
|
+
function n(v) {
|
|
5
|
+
return typeof v === 'number' && Number.isFinite(v) ? v : null;
|
|
6
|
+
}
|
|
7
|
+
function remaining(q) {
|
|
8
|
+
if (!q || typeof q !== 'object')
|
|
9
|
+
return null;
|
|
10
|
+
const used = n(q.used);
|
|
11
|
+
const limit = n(q.limit);
|
|
12
|
+
if (used === null || limit === null)
|
|
13
|
+
return null;
|
|
14
|
+
return Math.max(0, limit - used);
|
|
15
|
+
}
|
|
16
|
+
export const RESOURCES = [
|
|
17
|
+
{
|
|
18
|
+
name: 'brand',
|
|
19
|
+
uri: 'hollerpost://brand',
|
|
20
|
+
title: 'Brand',
|
|
21
|
+
description: 'Brand settings for this workspace: names, colors, logo, footer address, writing voice and sending domain. Read it to write on-brand.',
|
|
22
|
+
load: (api) => api.request('GET', '/brand'),
|
|
23
|
+
},
|
|
24
|
+
{
|
|
25
|
+
name: 'templates',
|
|
26
|
+
uri: 'hollerpost://templates',
|
|
27
|
+
title: 'Templates',
|
|
28
|
+
description: 'Email templates with the JSON Schema of the content blocks each one accepts.',
|
|
29
|
+
load: (api) => api.request('GET', '/templates'),
|
|
30
|
+
},
|
|
31
|
+
{
|
|
32
|
+
name: 'quota',
|
|
33
|
+
uri: 'hollerpost://quota',
|
|
34
|
+
title: 'Quota',
|
|
35
|
+
description: 'Plan and what is left this billing period: { plan, emails_remaining, sms_remaining, period_ends }.',
|
|
36
|
+
load: async (api) => {
|
|
37
|
+
const account = (await api.request('GET', '/account'));
|
|
38
|
+
const quota = (account.quota ?? {});
|
|
39
|
+
return {
|
|
40
|
+
plan: account.plan ?? null,
|
|
41
|
+
emails_remaining: remaining(quota.email),
|
|
42
|
+
sms_remaining: remaining(quota.sms),
|
|
43
|
+
period_ends: account.billing_period_ends ?? null,
|
|
44
|
+
};
|
|
45
|
+
},
|
|
46
|
+
},
|
|
47
|
+
{
|
|
48
|
+
name: 'domains',
|
|
49
|
+
uri: 'hollerpost://domains',
|
|
50
|
+
title: 'Sending domains',
|
|
51
|
+
description: 'Sending domains and their verification status, so you know before drafting whether anything can send yet.',
|
|
52
|
+
load: (api) => api.request('GET', '/domains'),
|
|
53
|
+
},
|
|
54
|
+
];
|
|
55
|
+
export async function readResource(def, api) {
|
|
56
|
+
try {
|
|
57
|
+
const data = redactDeep(await def.load(api), api.secrets);
|
|
58
|
+
return { contents: [{ uri: def.uri, mimeType: 'application/json', text: JSON.stringify(data, null, 2) }] };
|
|
59
|
+
}
|
|
60
|
+
catch (err) {
|
|
61
|
+
// Surface a clean protocol error: plain message, no stack details.
|
|
62
|
+
const message = err instanceof ApiError ? describeApiError(err) : 'Hollerpost MCP internal error while reading this resource.';
|
|
63
|
+
const clean = new Error(redactString(message, api.secrets));
|
|
64
|
+
clean.stack = undefined;
|
|
65
|
+
throw clean;
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
export function registerResources(server, api) {
|
|
69
|
+
for (const def of RESOURCES) {
|
|
70
|
+
server.registerResource(def.name, def.uri, { title: def.title, description: def.description, mimeType: 'application/json' }, async () => readResource(def, api));
|
|
71
|
+
}
|
|
72
|
+
}
|
package/dist/server.d.ts
ADDED
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
2
|
+
import type { ServerOptions } from '@modelcontextprotocol/sdk/server/index.js';
|
|
3
|
+
import { HollerpostClient, type ClientOptions } from './client.js';
|
|
4
|
+
export declare const SERVER_INSTRUCTIONS: string;
|
|
5
|
+
export declare function createServer(client: HollerpostClient, options?: Pick<ServerOptions, 'jsonSchemaValidator'>): McpServer;
|
|
6
|
+
export { HollerpostClient };
|
|
7
|
+
export type { ClientOptions };
|
package/dist/server.js
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
// Builds one McpServer with every tool, resource and prompt, bound to one
|
|
2
|
+
// API client. Used by both transports (stdio.ts and worker.ts).
|
|
3
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
4
|
+
import { HollerpostClient } from './client.js';
|
|
5
|
+
import { registerPrompts } from './prompts.js';
|
|
6
|
+
import { registerResources } from './resources.js';
|
|
7
|
+
import { registerTools } from './tools.js';
|
|
8
|
+
import { VERSION } from './version.js';
|
|
9
|
+
export const SERVER_INSTRUCTIONS = [
|
|
10
|
+
'Hollerpost sends email campaigns for a small business. You draft, preview, test and report; the person approves every send.',
|
|
11
|
+
'Start with workspace_info to learn the plan, the key scopes and the brand voice.',
|
|
12
|
+
'Campaigns are created as drafts. Before campaign_schedule always run campaign_preview, tell the person the audience count and quota use, and wait for a yes.',
|
|
13
|
+
'A workspace first campaign is held for a one-time human review (review_pending): it is not sent yet, do not retry.',
|
|
14
|
+
'Only add contacts who agreed to receive email. No tool can change billing; billing_portal_link gives the person a link.',
|
|
15
|
+
].join(' ');
|
|
16
|
+
export function createServer(client, options = {}) {
|
|
17
|
+
const server = new McpServer({ name: 'hollerpost-mcp', title: 'Hollerpost', version: VERSION, websiteUrl: 'https://hollerpost.com/docs/mcp/' }, { instructions: SERVER_INSTRUCTIONS, ...options });
|
|
18
|
+
registerTools(server, client);
|
|
19
|
+
registerResources(server, client);
|
|
20
|
+
registerPrompts(server);
|
|
21
|
+
return server;
|
|
22
|
+
}
|
|
23
|
+
export { HollerpostClient };
|
package/dist/stdio.d.ts
ADDED
package/dist/stdio.js
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// npx entry: MCP over stdio. Reads the key from HOLLERPOST_KEY.
|
|
3
|
+
// stdout carries the protocol, so diagnostics go to stderr and never include
|
|
4
|
+
// the key.
|
|
5
|
+
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
6
|
+
import { DEFAULT_API_BASE, HollerpostClient } from './client.js';
|
|
7
|
+
import { createServer } from './server.js';
|
|
8
|
+
import { VERSION } from './version.js';
|
|
9
|
+
async function main() {
|
|
10
|
+
const key = (process.env.HOLLERPOST_KEY || '').trim();
|
|
11
|
+
if (!key) {
|
|
12
|
+
process.stderr.write('hollerpost-mcp: HOLLERPOST_KEY is not set. Tools will answer missing_api_key until it is. Create a key in Dashboard, Settings, Developer API.\n');
|
|
13
|
+
}
|
|
14
|
+
const client = new HollerpostClient({
|
|
15
|
+
authorization: key ? `Bearer ${key}` : null,
|
|
16
|
+
transport: 'stdio',
|
|
17
|
+
baseUrl: process.env.HOLLERPOST_API_BASE || DEFAULT_API_BASE,
|
|
18
|
+
});
|
|
19
|
+
const server = createServer(client);
|
|
20
|
+
await server.connect(new StdioServerTransport());
|
|
21
|
+
process.stderr.write(`hollerpost-mcp ${VERSION} ready on stdio\n`);
|
|
22
|
+
}
|
|
23
|
+
main().catch(() => {
|
|
24
|
+
// Do not print the error object: keep output free of request details.
|
|
25
|
+
process.stderr.write('hollerpost-mcp: failed to start\n');
|
|
26
|
+
process.exit(1);
|
|
27
|
+
});
|
package/dist/tools.d.ts
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
3
|
+
import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
|
|
4
|
+
import { type HollerpostClient } from './client.js';
|
|
5
|
+
export type Scope = 'read' | 'contacts' | 'draft' | 'send' | 'webhooks' | 'account';
|
|
6
|
+
export interface ToolOutcome {
|
|
7
|
+
/** One or two plain sentences that lead the text content. */
|
|
8
|
+
lead: string;
|
|
9
|
+
/** The API JSON, returned in full as structuredContent. */
|
|
10
|
+
data: unknown;
|
|
11
|
+
}
|
|
12
|
+
export interface ToolDef<S extends z.ZodRawShape = z.ZodRawShape> {
|
|
13
|
+
name: string;
|
|
14
|
+
title: string;
|
|
15
|
+
scope: Scope;
|
|
16
|
+
description: string;
|
|
17
|
+
input: S;
|
|
18
|
+
annotations: ToolAnnotations;
|
|
19
|
+
run: (api: HollerpostClient, args: z.infer<z.ZodObject<S>>) => Promise<ToolOutcome>;
|
|
20
|
+
}
|
|
21
|
+
export declare const TOOLS: ToolDef[];
|
|
22
|
+
export declare const TOOL_NAMES: string[];
|
|
23
|
+
/** Run one tool and turn its outcome (or failure) into an MCP result. */
|
|
24
|
+
export declare function runTool(def: ToolDef, api: HollerpostClient, args: unknown): Promise<CallToolResult>;
|
|
25
|
+
export declare function registerTools(server: McpServer, api: HollerpostClient): void;
|