@velaro/mcp-server 2.0.68 → 2.0.70
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 +1 -1
- package/parity/signup-form.customer.js +86 -0
- package/server.js +105 -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.70",
|
|
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,86 @@
|
|
|
1
|
+
// velaro signup-form: signup forms, popups and slide-ins = the LIST-GROWTH LAYER of a survey (Survey.GrowthConfigJson).
|
|
2
|
+
// Not a separate form system: fields, consent wording, versions and submissions are the survey's. Site comes from the credential only.
|
|
3
|
+
// Needs the Email Growth package; the server answers 403 naming it. Parity module (CLI group signup-form -> MCP tools signup_form_*).
|
|
4
|
+
|
|
5
|
+
const pid = (v, n = 'id') => { const x = Number(v); if (!Number.isInteger(x) || x <= 0) throw new Error(n + ' must be a positive integer'); return x; };
|
|
6
|
+
|
|
7
|
+
const findSurvey = async (ctx, id) => {
|
|
8
|
+
const all = (await ctx.messagingGet('/Surveys/list')) ?? [];
|
|
9
|
+
const s = all.find((x) => x.id === pid(id));
|
|
10
|
+
if (!s) throw new Error('Survey ' + id + ' not found');
|
|
11
|
+
return s;
|
|
12
|
+
};
|
|
13
|
+
const growthOf = (s) => { if (!s.growthConfigJson) return null; try { return JSON.parse(s.growthConfigJson); } catch { return null; } };
|
|
14
|
+
|
|
15
|
+
export const tools = [
|
|
16
|
+
{
|
|
17
|
+
name: 'signup_form_list',
|
|
18
|
+
description: 'List signup forms (surveys that have the list-growth layer switched on): display type, trigger, target list and the shareable-link slug.',
|
|
19
|
+
inputSchema: { type: 'object', properties: {} },
|
|
20
|
+
},
|
|
21
|
+
{
|
|
22
|
+
name: 'signup_form_get',
|
|
23
|
+
description: 'Get one signup form (a survey id) with its list-growth settings: display (popup, slide_in, embedded; timed, scroll, exit intent; URL rules; frequency cap), target list, tags, double opt-in, success action, protection.',
|
|
24
|
+
inputSchema: { type: 'object', properties: { id: { type: 'integer', description: 'Survey id' } }, required: ['id'] },
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
name: 'signup_form_set',
|
|
28
|
+
description: 'Change the list-growth settings of a survey. Pass growth (the full settings object) and/or enabled. The survey fields and consent wording are edited with the survey tools. Needs consent wording switched on and the Email Growth package.',
|
|
29
|
+
inputSchema: {
|
|
30
|
+
type: 'object',
|
|
31
|
+
properties: {
|
|
32
|
+
id: { type: 'integer', description: 'Survey id' },
|
|
33
|
+
enabled: { type: 'boolean', description: 'Switch the layer on or off' },
|
|
34
|
+
growth: { type: 'object', description: 'Full growth settings: { enabled, display:{type,trigger,delaySeconds,scrollPercent,urlRules,frequencyCapDays,hideForKnownSubscribers,position}, list:{listId,tags,emailQuestionId,attributeMap,doubleOptIn:{enabled,subject,bodyHtml,expiryHours}}, success:{messageHtml,redirectUrl}, protection:{allowedOrigins,captcha,captchaSiteKey}, chatCapture:{enabled}, notifyMe:{enabled,type} }' },
|
|
35
|
+
},
|
|
36
|
+
required: ['id'],
|
|
37
|
+
},
|
|
38
|
+
},
|
|
39
|
+
{
|
|
40
|
+
name: 'signup_form_stats',
|
|
41
|
+
description: 'Per-form conversion: views, dismissals, signups, subscribed, awaiting double opt-in confirmation, confirmed, suppressed, conversion rate, daily impressions.',
|
|
42
|
+
inputSchema: { type: 'object', properties: { id: { type: 'integer' }, days: { type: 'integer', description: 'Window in days (default 30, max 365)' } }, required: ['id'] },
|
|
43
|
+
},
|
|
44
|
+
{
|
|
45
|
+
name: 'signup_form_submissions',
|
|
46
|
+
description: 'Paginated signups for a form with opt-in status and the consent record id that proves consent.',
|
|
47
|
+
inputSchema: { type: 'object', properties: { id: { type: 'integer' }, page: { type: 'integer' }, pageSize: { type: 'integer', description: 'Max 100' }, status: { type: 'string', enum: ['subscribed', 'pending_confirmation', 'confirmed', 'suppressed', 'list_sync_failed'] } }, required: ['id'] },
|
|
48
|
+
},
|
|
49
|
+
{
|
|
50
|
+
name: 'signup_form_snippet',
|
|
51
|
+
description: 'The one-line install snippet (works in Shopify theme.liquid and WordPress header/footer plugins). Needs the shareable link enabled.',
|
|
52
|
+
inputSchema: { type: 'object', properties: { id: { type: 'integer' }, host: { type: 'string', description: 'Script host (default https://messaging.velaro.com)' } }, required: ['id'] },
|
|
53
|
+
},
|
|
54
|
+
];
|
|
55
|
+
|
|
56
|
+
export const handlers = {
|
|
57
|
+
signup_form_list: async (a, ctx) => {
|
|
58
|
+
const all = ((await ctx.messagingGet('/Surveys/list')) ?? []).filter((s) => growthOf(s)?.enabled);
|
|
59
|
+
return all.map((s) => ({ id: s.id, name: s.name, publicSlug: s.publicSlug, display: growthOf(s).display, listId: growthOf(s).list?.listId ?? null }));
|
|
60
|
+
},
|
|
61
|
+
signup_form_get: async (a, ctx) => {
|
|
62
|
+
const s = await findSurvey(ctx, a.id);
|
|
63
|
+
return { id: s.id, name: s.name, publicSlug: s.publicSlug, allowStandaloneAccess: s.allowStandaloneAccess, consentEnabled: s.consentEnabled, growth: growthOf(s) };
|
|
64
|
+
},
|
|
65
|
+
signup_form_set: async (a, ctx) => {
|
|
66
|
+
const s = await findSurvey(ctx, a.id);
|
|
67
|
+
const cfg = a.growth ?? growthOf(s) ?? { enabled: false };
|
|
68
|
+
if (a.enabled !== undefined) cfg.enabled = a.enabled;
|
|
69
|
+
const saved = await ctx.messagingPost('/Surveys', { ...s, growthConfigJson: JSON.stringify(cfg) });
|
|
70
|
+
if (cfg.enabled && !saved.allowStandaloneAccess) await ctx.messagingPost('/Surveys/' + saved.id + '/standalone-link');
|
|
71
|
+
return { id: saved.id, growth: growthOf(saved) };
|
|
72
|
+
},
|
|
73
|
+
signup_form_stats: async (a, ctx) => ctx.messagingGet('/Surveys/' + pid(a.id) + '/growth/stats?days=' + Math.min(365, Math.max(1, a.days ?? 30))),
|
|
74
|
+
signup_form_submissions: async (a, ctx) => {
|
|
75
|
+
const q = 'page=' + Math.max(1, a.page ?? 1) + '&pageSize=' + Math.min(100, Math.max(1, a.pageSize ?? 25)) + (a.status ? '&status=' + encodeURIComponent(a.status) : '');
|
|
76
|
+
return ctx.messagingGet('/Surveys/' + pid(a.id) + '/growth/submissions?' + q);
|
|
77
|
+
},
|
|
78
|
+
signup_form_snippet: async (a, ctx) => {
|
|
79
|
+
const s = await findSurvey(ctx, a.id);
|
|
80
|
+
if (!s.publicSlug || !s.allowStandaloneAccess) throw new Error('Enable the shareable link first (signup_form_set with enabled: true).');
|
|
81
|
+
const host = a.host || 'https://messaging.velaro.com';
|
|
82
|
+
const lines = ['<script async src="' + host + '/messenger/forms.js" data-form="' + s.publicSlug + '"></script>'];
|
|
83
|
+
if (growthOf(s)?.display?.type === 'embedded') lines.push('<div data-velaro-form="' + s.publicSlug + '"></div>');
|
|
84
|
+
return lines.join('\n');
|
|
85
|
+
},
|
|
86
|
+
};
|
package/server.js
CHANGED
|
@@ -1567,6 +1567,53 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
|
|
|
1567
1567
|
required: ['id'],
|
|
1568
1568
|
},
|
|
1569
1569
|
},
|
|
1570
|
+
{
|
|
1571
|
+
name: 'contact_upsert',
|
|
1572
|
+
description: "Create or update a contact by email in Velaro's Contacts CRM (POST /api/v1/contacts, the same call Make/Zapier/Power Automate use). Fields not sent are left unchanged. Optional tags are applied.",
|
|
1573
|
+
inputSchema: {
|
|
1574
|
+
type: 'object',
|
|
1575
|
+
properties: {
|
|
1576
|
+
email: { type: 'string' }, firstName: { type: 'string' }, lastName: { type: 'string' },
|
|
1577
|
+
phone: { type: 'string' }, mobile: { type: 'string' }, company: { type: 'string' }, jobTitle: { type: 'string' },
|
|
1578
|
+
tags: { type: 'array', items: { type: 'string' } },
|
|
1579
|
+
},
|
|
1580
|
+
required: ['email'],
|
|
1581
|
+
},
|
|
1582
|
+
},
|
|
1583
|
+
{
|
|
1584
|
+
name: 'contact_tag',
|
|
1585
|
+
description: "Tag a contact by email (or contactId); the tag is created if new (POST /api/v1/contacts/tag).",
|
|
1586
|
+
inputSchema: {
|
|
1587
|
+
type: 'object',
|
|
1588
|
+
properties: { email: { type: 'string' }, contactId: { type: 'number' }, tag: { type: 'string' } },
|
|
1589
|
+
required: ['tag'],
|
|
1590
|
+
},
|
|
1591
|
+
},
|
|
1592
|
+
{
|
|
1593
|
+
name: 'public_api_conversations_list',
|
|
1594
|
+
description: "List or fetch conversations for this site through the public REST API (GET /api/v1/conversations, scope read:conversations). Optional id returns one conversation; otherwise filter by status and from/to dates.",
|
|
1595
|
+
inputSchema: { type: 'object', properties: { id: { type: 'number' }, status: { type: 'string' }, from: { type: 'string' }, to: { type: 'string' }, page: { type: 'number' }, pageSize: { type: 'number' } } },
|
|
1596
|
+
},
|
|
1597
|
+
{
|
|
1598
|
+
name: 'public_api_appointments_list',
|
|
1599
|
+
description: "List or fetch booked appointments through the public REST API (GET /api/v1/appointments, scope read:appointments). Optional id returns one appointment; otherwise filter by status and from/to dates.",
|
|
1600
|
+
inputSchema: { type: 'object', properties: { id: { type: 'number' }, status: { type: 'string' }, from: { type: 'string' }, to: { type: 'string' }, page: { type: 'number' }, pageSize: { type: 'number' } } },
|
|
1601
|
+
},
|
|
1602
|
+
{
|
|
1603
|
+
name: 'public_api_agents_list',
|
|
1604
|
+
description: "List the site's agents or teams through the public REST API (GET /api/v1/agents or /api/v1/teams, scope read:agents). Set kind to 'teams' for teams; default is agents.",
|
|
1605
|
+
inputSchema: { type: 'object', properties: { kind: { type: 'string', enum: ['agents', 'teams'] }, page: { type: 'number' }, pageSize: { type: 'number' } } },
|
|
1606
|
+
},
|
|
1607
|
+
{
|
|
1608
|
+
name: 'public_api_webhooks',
|
|
1609
|
+
description: "Manage outbound webhook subscriptions through the public REST API (/api/v1/webhooks). action=list (scope read:webhooks), create (needs url, optional events; returns the signing secret ONCE) or delete (needs id) (scope write:webhooks). Events: contact_tag_added, conversation_started, conversation_closed. Deliveries are signed with X-Velaro-Signature (HMAC-SHA256).",
|
|
1610
|
+
inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['list', 'create', 'delete'] }, url: { type: 'string' }, events: { type: 'array', items: { type: 'string' } }, id: { type: 'number' }, idempotencyKey: { type: 'string' } }, required: ['action'] },
|
|
1611
|
+
},
|
|
1612
|
+
{
|
|
1613
|
+
name: 'public_api_contact_note_add',
|
|
1614
|
+
description: "Add a note to a contact through the public REST API (POST /api/v1/contacts/{id}/notes, scope write:contacts). Optional idempotencyKey makes a retry return the original result.",
|
|
1615
|
+
inputSchema: { type: 'object', properties: { contactId: { type: 'number' }, note: { type: 'string' }, idempotencyKey: { type: 'string' } }, required: ['contactId', 'note'] },
|
|
1616
|
+
},
|
|
1570
1617
|
{
|
|
1571
1618
|
name: 'contacts_tags_list',
|
|
1572
1619
|
description: "List all contact tags defined for this site, in Velaro's native Contacts CRM.",
|
|
@@ -6101,6 +6148,64 @@ reply: ${r?.reply}`;
|
|
|
6101
6148
|
return list.map(e => `[${e.timestamp ?? e.date ?? '—'}] ${e.type ?? e.eventType ?? 'event'}: ${e.summary ?? e.description ?? ''}`).join('\n');
|
|
6102
6149
|
}
|
|
6103
6150
|
|
|
6151
|
+
// POST api/v1/contacts -> PublicApiController.UpsertContact
|
|
6152
|
+
case 'contact_upsert': {
|
|
6153
|
+
const r = await api('POST', '/api/v1/contacts', args);
|
|
6154
|
+
return `${r.created ? 'Created' : 'Updated'} contact #${r.id} (${r.email})${r.tags?.length ? ' tags: ' + r.tags.join(', ') : ''}`;
|
|
6155
|
+
}
|
|
6156
|
+
|
|
6157
|
+
// POST api/v1/contacts/tag -> PublicApiController.TagContact
|
|
6158
|
+
case 'contact_tag': {
|
|
6159
|
+
const r = await api('POST', '/api/v1/contacts/tag', args);
|
|
6160
|
+
return `Tagged contact #${r.contactId} with "${r.tag}"`;
|
|
6161
|
+
}
|
|
6162
|
+
|
|
6163
|
+
// GET /api/v1/conversations[/{id}] -> PublicApiDirectoryController
|
|
6164
|
+
case 'public_api_conversations_list': {
|
|
6165
|
+
const { id, ...q } = args || {};
|
|
6166
|
+
const qs = new URLSearchParams(Object.entries(q).filter(([, v]) => v !== undefined && v !== '')).toString();
|
|
6167
|
+
const r = await api('GET', id ? `/api/v1/conversations/${encodeURIComponent(id)}` : `/api/v1/conversations${qs ? '?' + qs : ''}`);
|
|
6168
|
+
return JSON.stringify(r, null, 2);
|
|
6169
|
+
}
|
|
6170
|
+
|
|
6171
|
+
// GET /api/v1/appointments[/{id}] -> PublicApiDirectoryController
|
|
6172
|
+
case 'public_api_appointments_list': {
|
|
6173
|
+
const { id, ...q } = args || {};
|
|
6174
|
+
const qs = new URLSearchParams(Object.entries(q).filter(([, v]) => v !== undefined && v !== '')).toString();
|
|
6175
|
+
const r = await api('GET', id ? `/api/v1/appointments/${encodeURIComponent(id)}` : `/api/v1/appointments${qs ? '?' + qs : ''}`);
|
|
6176
|
+
return JSON.stringify(r, null, 2);
|
|
6177
|
+
}
|
|
6178
|
+
|
|
6179
|
+
// GET /api/v1/agents | /api/v1/teams -> PublicApiDirectoryController
|
|
6180
|
+
case 'public_api_agents_list': {
|
|
6181
|
+
const { kind, ...q } = args || {};
|
|
6182
|
+
const qs = new URLSearchParams(Object.entries(q).filter(([, v]) => v !== undefined && v !== '')).toString();
|
|
6183
|
+
const r = await api('GET', `/api/v1/${kind === 'teams' ? 'teams' : 'agents'}${qs ? '?' + qs : ''}`);
|
|
6184
|
+
return JSON.stringify(r, null, 2);
|
|
6185
|
+
}
|
|
6186
|
+
|
|
6187
|
+
// /api/v1/webhooks -> PublicApiWriteController
|
|
6188
|
+
case 'public_api_webhooks': {
|
|
6189
|
+
const { action, url, events, id } = args || {};
|
|
6190
|
+
if (action === 'list') return JSON.stringify(await api('GET', '/api/v1/webhooks'), null, 2);
|
|
6191
|
+
if (action === 'delete') {
|
|
6192
|
+
if (!id) throw new Error('id is required for delete');
|
|
6193
|
+
return JSON.stringify(await api('DELETE', `/api/v1/webhooks/${encodeURIComponent(id)}`), null, 2);
|
|
6194
|
+
}
|
|
6195
|
+
if (action === 'create') {
|
|
6196
|
+
if (!url) throw new Error('url is required for create');
|
|
6197
|
+
return JSON.stringify(await api('POST', '/api/v1/webhooks', { url, events }), null, 2);
|
|
6198
|
+
}
|
|
6199
|
+
throw new Error('action must be list, create or delete');
|
|
6200
|
+
}
|
|
6201
|
+
|
|
6202
|
+
// POST /api/v1/contacts/{id}/notes -> PublicApiWriteController
|
|
6203
|
+
case 'public_api_contact_note_add': {
|
|
6204
|
+
const { contactId, note } = args || {};
|
|
6205
|
+
if (!contactId || !note) throw new Error('contactId and note are required');
|
|
6206
|
+
return JSON.stringify(await api('POST', `/api/v1/contacts/${encodeURIComponent(contactId)}/notes`, { note }), null, 2);
|
|
6207
|
+
}
|
|
6208
|
+
|
|
6104
6209
|
// GET Contacts/Tags -> ContactsController.GetTags
|
|
6105
6210
|
case 'contacts_tags_list': {
|
|
6106
6211
|
const tags = await api('GET', '/Contacts/Tags');
|