@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velaro/mcp-server",
3
- "version": "2.0.68",
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');