@velaro/mcp-server 2.0.145 → 2.0.147
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 +2 -1
- package/parity/campaign-send.customer.js +74 -0
- package/parity/email-cutoff.customer.js +48 -0
- package/parity/email-optouts.customer.js +54 -0
- package/parity/email-safeguards.customer.js +40 -0
- package/parity/moshky-guide.customer.js +69 -0
- package/server.js +121 -4
- package/tool-annotations.js +1 -0
- package/tool-schema.js +30 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@velaro/mcp-server",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.147",
|
|
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": {
|
|
@@ -55,6 +55,7 @@
|
|
|
55
55
|
"workflow-schedule.js",
|
|
56
56
|
"chat-window-style.js",
|
|
57
57
|
"toolsets.js",
|
|
58
|
+
"tool-schema.js",
|
|
58
59
|
"report-explain.json",
|
|
59
60
|
"server.json",
|
|
60
61
|
"README.md"
|
|
@@ -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
|
+
};
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
// velaro_guide and moshky_ask: Claude asks Moshky (the Velaro Copilot) what to do and how to set things up.
|
|
2
|
+
// Reuses POST /Copilot/Chat (grounded in copilot-kb, subscription-aware). Writes stay inside Moshky's own
|
|
3
|
+
// propose-then-confirm flow: server-side EnableCopilotWrite / CopilotWritePolicy and the AI_Moshky audit apply.
|
|
4
|
+
// CLI: velaro guide <goal>, velaro moshky-ask <question> [--confirmed]. REST: admin POST /Copilot/Chat.
|
|
5
|
+
|
|
6
|
+
const MAX_HISTORY = 12;
|
|
7
|
+
|
|
8
|
+
// Used only when Moshky is unreachable, so a failure never looks like an empty answer.
|
|
9
|
+
const FALLBACK = {
|
|
10
|
+
bot: 'Set up a bot: 1) kb_search_articles / index_list to see what knowledge exists, 2) add knowledge (scrape or kb_create_article), 3) bot_create, 4) bot_set_knowledge, 5) bot_update_prompt, 6) run the bot health check from the diagnostics tools. Retry velaro_guide for the full Moshky walkthrough.',
|
|
11
|
+
kb: 'Set up the knowledge base: 1) kb_get_settings, 2) kb_update_settings (branding), 3) kb_create_article for each topic (kb_list_topics first), 4) re-index the site knowledge, 5) kb_search_articles to check. Retry velaro_guide for the full Moshky walkthrough.',
|
|
12
|
+
};
|
|
13
|
+
|
|
14
|
+
function fallbackFor(goal) {
|
|
15
|
+
const g = String(goal).toLowerCase();
|
|
16
|
+
if (/\bbot\b/.test(g)) return FALLBACK.bot;
|
|
17
|
+
if (/\bkb\b|knowledge|help center|article/.test(g)) return FALLBACK.kb;
|
|
18
|
+
return 'Start with check_site_health, then retry velaro_guide with a more specific goal.';
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
async function askMoshky(ctx, messages, context) {
|
|
22
|
+
const res = await ctx.api('POST', '/Copilot/Chat', { messages, context, product: 'v20' });
|
|
23
|
+
if (res && res.success === false) throw new Error(res.error || 'Moshky could not answer');
|
|
24
|
+
const reply = res && res.reply;
|
|
25
|
+
if (!reply) throw new Error('Moshky returned no reply');
|
|
26
|
+
return String(reply);
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export const tools = [
|
|
30
|
+
{
|
|
31
|
+
name: 'velaro_guide',
|
|
32
|
+
description: 'Ask Moshky how to set something up. Call this FIRST for any configuration goal (e.g. "set up a bot", "set up the knowledge base", "connect Shopify"). Returns the recommended ordered steps from the Velaro skills library and the exact MCP tools to call for each. Read-only; changes nothing.',
|
|
33
|
+
inputSchema: { type: 'object', properties: { goal: { type: 'string', description: 'What you want to achieve, in plain words' } }, required: ['goal'] },
|
|
34
|
+
},
|
|
35
|
+
{
|
|
36
|
+
name: 'moshky_ask',
|
|
37
|
+
description: 'Ask Moshky (the Velaro Copilot) a question or to make a change. Without confirmed=true Moshky only answers or proposes the change. After the user agrees, call again with confirmed=true and the same history. Moshky applies changes only when "Moshky can make changes" is on for the site (moshky_write_access_get); every change is audit-logged and can be rolled back.',
|
|
38
|
+
inputSchema: {
|
|
39
|
+
type: 'object',
|
|
40
|
+
properties: {
|
|
41
|
+
question: { type: 'string', description: 'The question or requested change' },
|
|
42
|
+
confirmed: { type: 'boolean', description: 'true only after the user approved the change Moshky proposed' },
|
|
43
|
+
history: { type: 'array', description: 'Prior turns [{role:"user"|"assistant", content}] so Moshky keeps the proposal in context', items: { type: 'object', properties: { role: { type: 'string' }, content: { type: 'string' } } } },
|
|
44
|
+
context: { type: 'string', description: 'Optional page or area, e.g. "workflows"' },
|
|
45
|
+
},
|
|
46
|
+
required: ['question'],
|
|
47
|
+
},
|
|
48
|
+
},
|
|
49
|
+
];
|
|
50
|
+
|
|
51
|
+
export const handlers = {
|
|
52
|
+
velaro_guide: async (a, ctx) => {
|
|
53
|
+
if (!a.goal || !String(a.goal).trim()) throw new Error('goal is required');
|
|
54
|
+
const prompt = `An MCP client (an AI assistant) wants to: ${String(a.goal).trim()}. Reply with the recommended ordered setup steps from the Velaro skills library, naming the exact MCP tool for each step, and what to check first. Do not change anything.`;
|
|
55
|
+
try {
|
|
56
|
+
return await askMoshky(ctx, [{ role: 'user', content: prompt }], 'mcp-guide');
|
|
57
|
+
} catch (e) {
|
|
58
|
+
return `Moshky guide unavailable (${String(e.message).slice(0, 160)}). Built-in outline: ${fallbackFor(a.goal)}`;
|
|
59
|
+
}
|
|
60
|
+
},
|
|
61
|
+
moshky_ask: async (a, ctx) => {
|
|
62
|
+
if (!a.question || !String(a.question).trim()) throw new Error('question is required');
|
|
63
|
+
const history = Array.isArray(a.history) ? a.history.slice(-MAX_HISTORY).filter((m) => m && (m.role === 'user' || m.role === 'assistant') && typeof m.content === 'string') : [];
|
|
64
|
+
const q = a.confirmed === true
|
|
65
|
+
? `Confirmed: yes, apply it. ${String(a.question).trim()}`
|
|
66
|
+
: `${String(a.question).trim()}\n\n(From an MCP client. Propose any change and wait for confirmation; do not apply it yet.)`;
|
|
67
|
+
return await askMoshky(ctx, [...history, { role: 'user', content: q }], a.context || 'mcp');
|
|
68
|
+
},
|
|
69
|
+
};
|
package/server.js
CHANGED
|
@@ -51,6 +51,7 @@ import {
|
|
|
51
51
|
ListPromptsRequestSchema,
|
|
52
52
|
} from '@modelcontextprotocol/sdk/types.js';
|
|
53
53
|
import { withAnnotations } from './tool-annotations.js';
|
|
54
|
+
import { normalizeTool } from './tool-schema.js';
|
|
54
55
|
import { loadParity, runParity } from './parity/loader.js';
|
|
55
56
|
import { parseToolsets, filterTools, toolsetBlockedMessage } from './toolsets.js';
|
|
56
57
|
import { resolveMessagingApi } from './messaging-base.js';
|
|
@@ -393,6 +394,48 @@ async function rpc(toolName, args) {
|
|
|
393
394
|
|
|
394
395
|
// ── Tool definitions ──────────────────────────────────────────────────────────
|
|
395
396
|
|
|
397
|
+
// ── Page widget mode / search scope / mobile version helpers ───────────────
|
|
398
|
+
// SettingsJson keys `mode` and `searchScope`; mobile version is a templated variant rule in DisplayRulesJson.
|
|
399
|
+
const PW_MODES = ['chat_only', 'search_only', 'chat_search'];
|
|
400
|
+
const PW_SCOPES = ['catalog', 'catalog_docs', 'page_data'];
|
|
401
|
+
const PW_MOBILE_TEMPLATE_ID = 'mobile-variant';
|
|
402
|
+
function pwParseJson(text, fallback) {
|
|
403
|
+
if (text == null || text === '') return fallback;
|
|
404
|
+
if (typeof text !== 'string') return text;
|
|
405
|
+
try { return JSON.parse(text); } catch { return fallback; }
|
|
406
|
+
}
|
|
407
|
+
function pwSettings(w) { const v = pwParseJson(w.settingsJson, {}); return v && typeof v === 'object' && !Array.isArray(v) ? v : {}; }
|
|
408
|
+
function pwRules(w) { const v = pwParseJson(w.displayRulesJson, []); return Array.isArray(v) ? v : []; }
|
|
409
|
+
function pwIsMobileRule(r) { return !!r && r.variant === true && r.templateId === PW_MOBILE_TEMPLATE_ID; }
|
|
410
|
+
function pwModeSummary(w) {
|
|
411
|
+
const s = pwSettings(w);
|
|
412
|
+
const mobile = pwRules(w).find(pwIsMobileRule);
|
|
413
|
+
return {
|
|
414
|
+
mode: PW_MODES.includes(s.mode) ? s.mode : 'chat_only',
|
|
415
|
+
searchScope: PW_SCOPES.includes(s.searchScope) ? s.searchScope : 'catalog',
|
|
416
|
+
mobileVersion: mobile ? { enabled: true, overrides: mobile.overrides ?? {} } : { enabled: false },
|
|
417
|
+
};
|
|
418
|
+
}
|
|
419
|
+
function pwBuildMobileRule(settings, overrides) {
|
|
420
|
+
const base = { mode: PW_MODES.includes(settings.mode) ? settings.mode : 'chat_only', layout: settings.layout ?? 'default', placement: settings.position ?? settings.placement ?? 'bottom-right' };
|
|
421
|
+
return {
|
|
422
|
+
templateId: PW_MOBILE_TEMPLATE_ID, variant: true, operator: 'all',
|
|
423
|
+
conditions: [{ type: 'device', value: 'mobile' }],
|
|
424
|
+
overrides: { ...base, ...(overrides ?? {}) },
|
|
425
|
+
};
|
|
426
|
+
}
|
|
427
|
+
// Friendly text for the two documented rejections (402 not entitled, variant rules disabled).
|
|
428
|
+
async function pwPut(id, w) {
|
|
429
|
+
try {
|
|
430
|
+
await api('PUT', `/PageWidgets/${id}`, w);
|
|
431
|
+
} catch (e) {
|
|
432
|
+
const msg = String(e?.message ?? e);
|
|
433
|
+
if (/variant_rules_disabled/.test(msg)) throw new Error('Mobile versions are not available yet for this account (variant_rules_disabled). Nothing was changed.');
|
|
434
|
+
if (/402|not_entitled|scope_not_entitled/.test(msg)) throw new Error('That experience or search scope is not included in your plan (see your plan). Nothing was changed.');
|
|
435
|
+
throw e;
|
|
436
|
+
}
|
|
437
|
+
}
|
|
438
|
+
|
|
396
439
|
const TOOLS = [
|
|
397
440
|
{
|
|
398
441
|
name: 'case_list_types',
|
|
@@ -2976,7 +3019,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
|
|
|
2976
3019
|
},
|
|
2977
3020
|
{
|
|
2978
3021
|
name: 'page_widget_get',
|
|
2979
|
-
description: 'Get full configuration for a single page widget, including its SettingsJson (team assignment, workflow, theme, etc.).',
|
|
3022
|
+
description: 'Get full configuration for a single page widget, including its SettingsJson (team assignment, workflow, theme, etc.) plus the experience (mode), search scope and mobile version summary.',
|
|
2980
3023
|
inputSchema: {
|
|
2981
3024
|
type: 'object',
|
|
2982
3025
|
properties: { id: { type: 'number', description: 'Widget DB row ID (not the widgetId UUID)' } },
|
|
@@ -2995,6 +3038,45 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
|
|
|
2995
3038
|
required: ['id', 'isEnabled'],
|
|
2996
3039
|
},
|
|
2997
3040
|
},
|
|
3041
|
+
{
|
|
3042
|
+
name: 'page_widget_set_mode',
|
|
3043
|
+
description: 'Set a page widget experience: search_only (inline search, no chat), chat_only (default) or chat_search (chat with search). Plan-gated; a plan that does not include it is rejected and nothing changes.',
|
|
3044
|
+
inputSchema: {
|
|
3045
|
+
type: 'object',
|
|
3046
|
+
properties: {
|
|
3047
|
+
id: { type: 'number', description: 'Widget DB row ID' },
|
|
3048
|
+
mode: { type: 'string', enum: PW_MODES, description: 'search_only | chat_only | chat_search' },
|
|
3049
|
+
},
|
|
3050
|
+
required: ['id', 'mode'],
|
|
3051
|
+
},
|
|
3052
|
+
},
|
|
3053
|
+
{
|
|
3054
|
+
name: 'page_widget_set_search_scope',
|
|
3055
|
+
description: 'Set what a page widget searches: catalog (products), catalog_docs (products plus help articles and pages) or page_data (products boosted by the current page). Plan-gated.',
|
|
3056
|
+
inputSchema: {
|
|
3057
|
+
type: 'object',
|
|
3058
|
+
properties: {
|
|
3059
|
+
id: { type: 'number', description: 'Widget DB row ID' },
|
|
3060
|
+
scope: { type: 'string', enum: PW_SCOPES, description: 'catalog | catalog_docs | page_data' },
|
|
3061
|
+
},
|
|
3062
|
+
required: ['id', 'scope'],
|
|
3063
|
+
},
|
|
3064
|
+
},
|
|
3065
|
+
{
|
|
3066
|
+
name: 'page_widget_set_mobile_version',
|
|
3067
|
+
description: 'Turn the Mobile version of a page widget on or off. On creates a phone-only variant seeded from the desktop settings (optionally override mode, layout, placement); off removes it so phones match desktop.',
|
|
3068
|
+
inputSchema: {
|
|
3069
|
+
type: 'object',
|
|
3070
|
+
properties: {
|
|
3071
|
+
id: { type: 'number', description: 'Widget DB row ID' },
|
|
3072
|
+
enabled: { type: 'boolean', description: 'true = separate mobile version, false = same as desktop' },
|
|
3073
|
+
mode: { type: 'string', enum: PW_MODES, description: 'Mobile experience override (only when enabled)' },
|
|
3074
|
+
layout: { type: 'string', description: 'Mobile layout override (only when enabled)' },
|
|
3075
|
+
placement: { type: 'string', description: 'Mobile placement override, e.g. bottom-right (only when enabled)' },
|
|
3076
|
+
},
|
|
3077
|
+
required: ['id', 'enabled'],
|
|
3078
|
+
},
|
|
3079
|
+
},
|
|
2998
3080
|
|
|
2999
3081
|
// ── Chat Window launcher copy (per-page launcher label + greeting) ─────────
|
|
3000
3082
|
{
|
|
@@ -4231,6 +4313,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
|
|
|
4231
4313
|
{
|
|
4232
4314
|
name: 'usage_alerts',
|
|
4233
4315
|
description: 'Plan-limit alerts for the authenticated site: every metered resource at or above its warning threshold (80%+), with used/limit, percent, level (warning | critical | limit) and whether overage is billed. Same rules as the usage-limit emails and the dashboard banner. Use to answer "are they near a limit?" or "why did they get a usage email?". Read-only. To raise a limit, use Billing > Contact Account Manager.',
|
|
4316
|
+
inputSchema: { type: 'object', properties: {} },
|
|
4234
4317
|
},
|
|
4235
4318
|
{
|
|
4236
4319
|
name: 'billing_contacts_list',
|
|
@@ -8435,7 +8518,39 @@ reply: ${r?.reply}`;
|
|
|
8435
8518
|
|
|
8436
8519
|
case 'page_widget_get': {
|
|
8437
8520
|
const w = await api('GET', `/PageWidgets/${args.id}`);
|
|
8438
|
-
return JSON.stringify(w, null, 2);
|
|
8521
|
+
return JSON.stringify({ ...w, ...pwModeSummary(w) }, null, 2);
|
|
8522
|
+
}
|
|
8523
|
+
|
|
8524
|
+
case 'page_widget_set_mode': {
|
|
8525
|
+
if (!PW_MODES.includes(args.mode)) return `mode must be one of: ${PW_MODES.join(', ')}.`;
|
|
8526
|
+
const w = await api('GET', `/PageWidgets/${args.id}`);
|
|
8527
|
+
const s = pwSettings(w); s.mode = args.mode;
|
|
8528
|
+
w.settingsJson = JSON.stringify(s);
|
|
8529
|
+
await pwPut(args.id, w);
|
|
8530
|
+
return `Widget ${args.id} experience set to ${args.mode}.`;
|
|
8531
|
+
}
|
|
8532
|
+
|
|
8533
|
+
case 'page_widget_set_search_scope': {
|
|
8534
|
+
if (!PW_SCOPES.includes(args.scope)) return `scope must be one of: ${PW_SCOPES.join(', ')}.`;
|
|
8535
|
+
const w = await api('GET', `/PageWidgets/${args.id}`);
|
|
8536
|
+
const s = pwSettings(w); s.searchScope = args.scope;
|
|
8537
|
+
w.settingsJson = JSON.stringify(s);
|
|
8538
|
+
await pwPut(args.id, w);
|
|
8539
|
+
return `Widget ${args.id} search scope set to ${args.scope}.`;
|
|
8540
|
+
}
|
|
8541
|
+
|
|
8542
|
+
case 'page_widget_set_mobile_version': {
|
|
8543
|
+
if (args.mode !== undefined && !PW_MODES.includes(args.mode)) return `mode must be one of: ${PW_MODES.join(', ')}.`;
|
|
8544
|
+
const w = await api('GET', `/PageWidgets/${args.id}`);
|
|
8545
|
+
const rules = pwRules(w).filter((r) => !pwIsMobileRule(r));
|
|
8546
|
+
if (args.enabled) {
|
|
8547
|
+
const ov = {};
|
|
8548
|
+
for (const k of ['mode', 'layout', 'placement']) if (args[k] !== undefined) ov[k] = args[k];
|
|
8549
|
+
rules.push(pwBuildMobileRule(pwSettings(w), ov));
|
|
8550
|
+
}
|
|
8551
|
+
w.displayRulesJson = JSON.stringify(rules);
|
|
8552
|
+
await pwPut(args.id, w);
|
|
8553
|
+
return `Widget ${args.id} mobile version ${args.enabled ? 'on' : 'off'}.`;
|
|
8439
8554
|
}
|
|
8440
8555
|
|
|
8441
8556
|
case 'page_widget_toggle': {
|
|
@@ -10648,16 +10763,18 @@ const PROMPTS = [
|
|
|
10648
10763
|
},
|
|
10649
10764
|
];
|
|
10650
10765
|
|
|
10766
|
+
const SERVER_INSTRUCTIONS = `Velaro MCP server. Before configuring anything (a bot, the knowledge base, routing, workflows, integrations), call velaro_guide with the goal in plain words, for example "set up a bot" or "set up the knowledge base". It returns Moshky's recommended ordered steps and the exact tools to call. Follow those steps with the other tools. For a question about how something works or what to do next, call moshky_ask. Changes are proposed first; only after the user agrees call again with confirmed=true. Moshky applies changes only when "Moshky can make changes" is on for the site (moshky_write_access_get). If a call returns a 401 about a missing scope, the key needs the admin scope: Settings > MCP keys > Access, or run: velaro mcp-key create --scopes admin.`;
|
|
10767
|
+
|
|
10651
10768
|
const server = new Server(
|
|
10652
10769
|
{ name: 'velaro', version: JSON.parse(_readFileSync(_join(_dirname(_ftu(import.meta.url)), 'package.json'), 'utf8')).version },
|
|
10653
|
-
{ capabilities: { tools: {}, prompts: {} } }
|
|
10770
|
+
{ capabilities: { tools: {}, prompts: {} }, instructions: SERVER_INSTRUCTIONS }
|
|
10654
10771
|
);
|
|
10655
10772
|
|
|
10656
10773
|
const PARITY = await loadParity('customer');
|
|
10657
10774
|
TOOLS.push(...PARITY.tools);
|
|
10658
10775
|
const TOOLSETS = parseToolsets(process.env.VELARO_MCP_TOOLSETS, (m) => process.stderr.write(`[velaro-mcp] ${m}
|
|
10659
10776
|
`));
|
|
10660
|
-
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS.map(withAnnotations).filter((t) => !TOOLSETS || filterTools([t], TOOLSETS).length) }));
|
|
10777
|
+
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS.map(withAnnotations).map(normalizeTool).filter((t) => !TOOLSETS || filterTools([t], TOOLSETS).length) }));
|
|
10661
10778
|
|
|
10662
10779
|
server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: PROMPTS }));
|
|
10663
10780
|
|
package/tool-annotations.js
CHANGED
|
@@ -34,6 +34,7 @@ const MUTATING = new Set([
|
|
|
34
34
|
|
|
35
35
|
// Names that look like writes but only read (checked before the write rules).
|
|
36
36
|
const READ_ONLY_EXPLICIT = new Set([
|
|
37
|
+
'velaro_guide',
|
|
37
38
|
'activity_logs', 'ai_field_extraction_fields', 'keyword_intelligence_top',
|
|
38
39
|
'keyword_intelligence_conversations', 'knowledge_advisor_advise', 'quality_sentiment',
|
|
39
40
|
'quality_agent_performance', 'quality_low_scores', 'quality_calibration', 'appointments_find_open_slots',
|
package/tool-schema.js
ADDED
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
// Every MCP tool must publish inputSchema {type:'object', properties:{...}}.
|
|
2
|
+
// Claude Code rejects the WHOLE tool list when one tool has a malformed schema
|
|
3
|
+
// (usage_alerts shipped without one and took ~875 tools down for a customer on site 2121).
|
|
4
|
+
// Build-time guard: scripts/validate-mcp-tool-schemas.js and mcp/tool-schema.test.js.
|
|
5
|
+
// Runtime safety net: normalizeTool() is applied to every tool at list time.
|
|
6
|
+
|
|
7
|
+
const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);
|
|
8
|
+
|
|
9
|
+
export function schemaProblem(tool) {
|
|
10
|
+
const s = tool && tool.inputSchema;
|
|
11
|
+
if (!isObj(s)) return 'inputSchema is missing';
|
|
12
|
+
if (s.type !== 'object') return "inputSchema.type must be 'object'";
|
|
13
|
+
if (!isObj(s.properties)) return 'inputSchema.properties must be an object';
|
|
14
|
+
return null;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
export function normalizeTool(tool) {
|
|
18
|
+
if (schemaProblem(tool) === null) return tool;
|
|
19
|
+
const s = isObj(tool && tool.inputSchema) ? tool.inputSchema : {};
|
|
20
|
+
return { ...tool, inputSchema: { ...s, type: 'object', properties: isObj(s.properties) ? s.properties : {} } };
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
export function assertToolSchemas(tools) {
|
|
24
|
+
const bad = [];
|
|
25
|
+
for (const t of tools) {
|
|
26
|
+
const p = schemaProblem(t);
|
|
27
|
+
if (p) bad.push(`${t && t.name}: ${p}`);
|
|
28
|
+
}
|
|
29
|
+
return bad;
|
|
30
|
+
}
|