@velaro/mcp-server 2.0.144 → 2.0.146

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velaro/mcp-server",
3
- "version": "2.0.144",
3
+ "version": "2.0.146",
4
4
  "description": "Velaro MCP server — connect Claude and other AI agents directly to your Velaro account: KB, workflows, bots, conversations, contacts, routing, and more.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -0,0 +1,74 @@
1
+ // MCP parity for `velaro campaigns create | send-test | send | cancel` (cli/lib/commands/campaigns.js).
2
+ // The site comes from the credential only; no tool takes a siteId.
3
+ // Backend: BroadcastCampaignController (POST BroadcastCampaigns, /{id}/SendTest, /{id}/SendPreview, /{id}/SendConfirmed, /{id}/cancel).
4
+ // A real send is two steps: campaign_send_preview shows audience size, consent/suppression exclusions and quota and returns a
5
+ // confirmToken; campaign_send_confirm schedules the send only with that token. The server refuses a missing or stale token.
6
+
7
+ const id = (a) => {
8
+ const n = Number(a.campaignId);
9
+ if (!Number.isInteger(n) || n <= 0) throw new Error('campaignId must be a positive whole number');
10
+ return n;
11
+ };
12
+
13
+ export const tools = [
14
+ {
15
+ name: 'campaign_create',
16
+ description: 'Create a draft email campaign for one contact list or one segment. Nothing is sent. Follow with campaign_send_test, then campaign_send_preview.',
17
+ inputSchema: {
18
+ type: 'object',
19
+ properties: {
20
+ name: { type: 'string' }, subject: { type: 'string' }, bodyHtml: { type: 'string' }, bodyText: { type: 'string' },
21
+ listId: { type: 'number', description: 'Contact list id (use this or segmentId)' },
22
+ segmentId: { type: 'number', description: 'Segment id (use this or listId)' },
23
+ fromName: { type: 'string' }, fromAddress: { type: 'string', description: 'On a verified sending domain' },
24
+ suppressionHours: { type: 'number', description: 'Skip people who chatted within this many hours' },
25
+ },
26
+ required: ['name', 'subject', 'bodyHtml'],
27
+ },
28
+ },
29
+ {
30
+ name: 'campaign_send_test',
31
+ description: 'Send one test copy of an email campaign to a single address.',
32
+ inputSchema: { type: 'object', properties: { campaignId: { type: 'number' }, email: { type: 'string' } }, required: ['campaignId', 'email'] },
33
+ },
34
+ {
35
+ name: 'campaign_send_preview',
36
+ description: 'Step 1 of sending. Shows the audience size, who is left out (no email, unsubscribed, recently chatted), the quota check and anything blocking the send, and returns a confirmToken. Show it to the user before campaign_send_confirm. Nothing is sent.',
37
+ inputSchema: { type: 'object', properties: { campaignId: { type: 'number' } }, required: ['campaignId'] },
38
+ },
39
+ {
40
+ name: 'campaign_send_confirm',
41
+ description: 'Step 2 of sending: schedules the campaign for real. Only after the user has seen the campaign_send_preview result and agreed. Needs that preview confirmToken.',
42
+ inputSchema: {
43
+ type: 'object',
44
+ properties: { campaignId: { type: 'number' }, confirmToken: { type: 'string' }, sendAt: { type: 'string', description: 'ISO 8601 send time (optional, default now)' } },
45
+ required: ['campaignId', 'confirmToken'],
46
+ },
47
+ },
48
+ {
49
+ name: 'campaign_cancel',
50
+ description: 'Cancel a draft or scheduled campaign so it does not send. A campaign that already sent cannot be cancelled.',
51
+ inputSchema: { type: 'object', properties: { campaignId: { type: 'number' } }, required: ['campaignId'] },
52
+ },
53
+ ];
54
+
55
+ export const handlers = {
56
+ campaign_create: async (a, ctx) => {
57
+ if (!a.bodyHtml) throw new Error('bodyHtml is required');
58
+ if ((a.listId === undefined) === (a.segmentId === undefined)) throw new Error('Give exactly one of listId or segmentId');
59
+ return ctx.api('POST', '/BroadcastCampaigns', {
60
+ channel: 'email', name: a.name, subject: a.subject, bodyHtml: a.bodyHtml, bodyText: a.bodyText, listId: a.listId, segmentId: a.segmentId,
61
+ fromName: a.fromName, fromAddress: a.fromAddress, suppressionHours: a.suppressionHours || 0,
62
+ });
63
+ },
64
+ campaign_send_test: async (a, ctx) => {
65
+ if (!a.email) throw new Error('email is required');
66
+ return ctx.api('POST', `/BroadcastCampaigns/${id(a)}/SendTest`, { email: a.email });
67
+ },
68
+ campaign_send_preview: async (a, ctx) => ctx.api('POST', `/BroadcastCampaigns/${id(a)}/SendPreview`),
69
+ campaign_send_confirm: async (a, ctx) => {
70
+ if (!a.confirmToken) throw new Error('confirmToken is required: run campaign_send_preview first and show the user the result');
71
+ return ctx.api('POST', `/BroadcastCampaigns/${id(a)}/SendConfirmed`, { confirmToken: a.confirmToken, sendAt: a.sendAt });
72
+ },
73
+ campaign_cancel: async (a, ctx) => ctx.api('POST', `/BroadcastCampaigns/${id(a)}/cancel`),
74
+ };
@@ -0,0 +1,48 @@
1
+ // velaro email-cutoff (customer): the date and time before which received email is never processed.
2
+ // Site comes from the credential only; no siteId is ever passed. Parity module (CLI group -> MCP tools).
3
+
4
+ const iso = (v, n) => {
5
+ const d = new Date(v);
6
+ if (Number.isNaN(d.getTime())) throw new Error(n + ' must be a valid date and time, for example 2026-11-18T09:00:00Z');
7
+ return d.toISOString();
8
+ };
9
+
10
+ const pick = (c) => ({
11
+ emailProcessFromUtc: c.emailProcessFromUtc ?? null,
12
+ emailHistoricImportFromUtc: c.emailHistoricImportFromUtc ?? null,
13
+ autoReplyEnabledAt: c.autoReplyEnabledAt ?? null,
14
+ });
15
+
16
+ export const tools = [
17
+ {
18
+ name: 'email_cutoff_get',
19
+ description: 'Show the email processing cutoff: email received before it is never turned into a ticket or answered. Also shows the optional historic import date and when auto-reply was turned on.',
20
+ inputSchema: { type: 'object', properties: {} },
21
+ },
22
+ {
23
+ name: 'email_cutoff_set',
24
+ description: 'Set "do not process email received before" for the helpdesk. A later date is always safe. An earlier date than the saved one only applies when allowEarlierCutoff is true. A historic import date can reach back at most 14 days, and a historic import never sends replies or re-creates tickets that already exist.',
25
+ inputSchema: {
26
+ type: 'object',
27
+ properties: {
28
+ processFrom: { type: 'string', description: 'Date and time (ISO 8601, for example 2026-11-18T09:00:00Z). Email received before it is not processed.' },
29
+ historicImportFrom: { type: 'string', description: 'Optional one-time historic import date (ISO 8601), at most 14 days ago. Needs allowEarlierCutoff true.' },
30
+ clearHistoricImport: { type: 'boolean', description: 'Remove the saved historic import date' },
31
+ allowEarlierCutoff: { type: 'boolean', description: 'Set true only when you deliberately want an earlier date than the one saved' },
32
+ },
33
+ },
34
+ },
35
+ ];
36
+
37
+ export const handlers = {
38
+ email_cutoff_get: async (_a, ctx) => pick(await ctx.messagingGet('/ticket/configuration')),
39
+ email_cutoff_set: async (a, ctx) => {
40
+ const body = {};
41
+ if (a.processFrom !== undefined) body.emailProcessFromUtc = iso(a.processFrom, 'processFrom');
42
+ if (a.historicImportFrom !== undefined) body.emailHistoricImportFromUtc = iso(a.historicImportFrom, 'historicImportFrom');
43
+ if (a.clearHistoricImport) body.clearEmailHistoricImport = true;
44
+ if (!Object.keys(body).length) throw new Error('Pass at least one of processFrom, historicImportFrom or clearHistoricImport.');
45
+ if (a.allowEarlierCutoff) body.allowEarlierCutoff = true;
46
+ return pick(await ctx.messagingPut('/ticket/configuration', body));
47
+ },
48
+ };
@@ -0,0 +1,54 @@
1
+ // velaro email-optouts (customer): the list of addresses opted out of your account's email.
2
+ // Site comes from the credential, never an argument. Re-adding someone needs the explicit confirmation that they
3
+ // asked to be re-added plus a reason (recorded in the audit history). Bounce and complaint addresses are protected.
4
+ // Parity module (CLI group -> MCP tools).
5
+
6
+ export const tools = [
7
+ {
8
+ name: 'email_optouts_list',
9
+ description: "List the email addresses opted out of your account's email (unsubscribed, added by your team, or bounced). Optional search text matches part of an address.",
10
+ inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'Part of an email address' }, page: { type: 'integer', description: 'Page number, default 1' } } },
11
+ },
12
+ {
13
+ name: 'email_optout_add',
14
+ description: 'Add an email address to your opt-out list so your account stops emailing it (ticket replies, campaigns, sequences).',
15
+ inputSchema: { type: 'object', properties: { email: { type: 'string' }, reason: { type: 'string', description: 'Why (optional, up to 500 characters)' } }, required: ['email'] },
16
+ },
17
+ {
18
+ name: 'email_optout_remove',
19
+ description: 'Re-add a person to your email by removing their opt-out. Only for a person who asked to be re-added: confirm_readd_requested must be true and a reason is required. Bounce and complaint addresses are protected and cannot be removed.',
20
+ inputSchema: { type: 'object', properties: { email: { type: 'string' }, confirm_readd_requested: { type: 'boolean', description: 'Must be true: the person asked to be re-added' }, reason: { type: 'string', description: 'Why (required, up to 500 characters)' } }, required: ['email', 'confirm_readd_requested', 'reason'] },
21
+ },
22
+ ];
23
+
24
+ const norm = (e) => String(e || '').trim().toLowerCase();
25
+
26
+ export const handlers = {
27
+ email_optouts_list: async (a, ctx) => {
28
+ const q = encodeURIComponent(a?.query || '');
29
+ const page = Number.isInteger(a?.page) && a.page > 0 ? a.page : 1;
30
+ return ctx.messagingGet(`/email/optouts?q=${q}&page=${page}&pageSize=50`);
31
+ },
32
+ email_optout_add: async (a, ctx) => ctx.messagingPost('/email/optouts', { email: norm(a?.email), reason: String(a?.reason || '').trim() }),
33
+ email_optout_remove: async (a, ctx) => {
34
+ const email = norm(a?.email);
35
+ const reason = String(a?.reason || '').trim();
36
+ if (a?.confirm_readd_requested !== true) throw new Error('confirm_readd_requested must be true: only re-add a person who asked to be re-added.');
37
+ if (!reason) throw new Error('A reason is required.');
38
+ const found = await ctx.messagingGet(`/email/optouts?q=${encodeURIComponent(email)}&page=1&pageSize=50`);
39
+ const item = (found?.items || []).find((i) => norm(i.email) === email);
40
+ if (!item) throw new Error(`${email} is not on the opt-out list.`);
41
+ if (!item.removable) throw new Error(item.reason || 'This address is protected and cannot be re-added.');
42
+ const origins = item.origins || [];
43
+ let removed = 0;
44
+ if (origins.includes('campaigns')) {
45
+ const r = await ctx.api('POST', '/EmailCampaigns/Resubscribe', { email, confirmReaddRequested: true, reason });
46
+ removed += r?.removed || 0;
47
+ }
48
+ if (origins.some((o) => o !== 'campaigns')) {
49
+ const r = await ctx.messagingPost('/email/optouts/remove', { email, confirmReaddRequested: true, reason });
50
+ removed += r?.removed || 0;
51
+ }
52
+ return { removed };
53
+ },
54
+ };
@@ -0,0 +1,40 @@
1
+ // velaro email-safeguards (customer): read-only view of the site's effective email and ticket safeguards.
2
+ // Site comes from the credential only; no siteId is ever passed. Parity module (CLI group -> MCP tools).
3
+ // Each part is read from its own existing endpoint. A part that cannot be read comes back as null with a
4
+ // note, never as a zero or an empty list, so a failure never looks like "nothing configured".
5
+
6
+ export async function readEmailSafeguards(get) {
7
+ const notes = [];
8
+ const attempt = async (label, path) => {
9
+ try { return await get(path); } catch { notes.push(`${label} could not be read right now.`); return null; }
10
+ };
11
+ const [cfg, setup, optouts] = await Promise.all([
12
+ attempt('Email processing cutoff', '/ticket/configuration'),
13
+ attempt('Email setup status', '/ticket/email-setup-status'),
14
+ attempt('Opt-out list', 'email/optouts?page=1&pageSize=1'),
15
+ ]);
16
+ return {
17
+ emailProcessFromUtc: cfg ? (cfg.emailProcessFromUtc ?? null) : null,
18
+ emailHistoricImportFromUtc: cfg ? (cfg.emailHistoricImportFromUtc ?? null) : null,
19
+ connectedMailboxes: cfg && Array.isArray(cfg.effectiveMailboxCutoffs)
20
+ ? cfg.effectiveMailboxCutoffs.map((m) => ({ mailbox: m.mailboxEmail, provider: m.provider, processesEmailFromUtc: m.effectiveCutoffUtc }))
21
+ : null,
22
+ repliesReady: setup ? setup.ready === true : null,
23
+ notSentLast24h: setup ? (setup.blockedLast24h ?? 0) : null,
24
+ lastNotSentAt: setup ? (setup.lastBlockedAt ?? null) : null,
25
+ optOutCount: optouts ? (optouts.total ?? null) : null,
26
+ notes,
27
+ };
28
+ }
29
+
30
+ export const tools = [
31
+ {
32
+ name: 'email_safeguards_status',
33
+ description: 'Show this site\'s effective email and ticket safeguards: the date email is processed from, connected mailboxes, whether customer replies are going out, how many sends were not sent in the last 24 hours, and the opt-out list size. Read-only.',
34
+ inputSchema: { type: 'object', properties: {} },
35
+ },
36
+ ];
37
+
38
+ export const handlers = {
39
+ email_safeguards_status: async (_a, ctx) => readEmailSafeguards((p) => ctx.messagingGet(p)),
40
+ };