@velaro/mcp-server 2.0.58 → 2.0.60

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.58",
3
+ "version": "2.0.60",
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,14 @@
1
+ // velaro after-hours-support (customer): this month's after-hours premium support code for your site.
2
+ // Parity module (CLI group -> MCP tools). The site comes from the credential; only a site administrator can read it, and only when your plan includes it.
3
+
4
+ export const tools = [
5
+ {
6
+ name: 'after_hours_support_get',
7
+ description: 'Show this month\'s after-hours premium support code for your site (the code you read to Velaro support outside business hours, after you have been verified). Site administrators only. Returns 404 when after-hours support is not part of your plan; see your plan under Billing.',
8
+ inputSchema: { type: 'object', properties: {} },
9
+ },
10
+ ];
11
+
12
+ export const handlers = {
13
+ after_hours_support_get: async (_a, ctx) => ctx.api('GET', '/AfterHoursSupport/my'),
14
+ };
@@ -0,0 +1,83 @@
1
+ // MCP parity for `velaro contact-segment` (cli/lib/commands/contact-segment.js).
2
+ // Backend: velaro-admin ContactSegmentController (ContactSegments/engagement/*). Email behavior
3
+ // segments, Klaviyo-parity #1. The site always comes from the credential; no tool takes a site id.
4
+ // Needs the Email Behavior Segments feature on the plan; the API answers 403 entitlement_required otherwise.
5
+
6
+ const EVENT_TYPES = ['opened', 'clicked', 'delivered', 'bounced', 'unsubscribed', 'form_submitted', 'site_visited'];
7
+
8
+ export const tools = [
9
+ {
10
+ name: 'contact_segment_engagement_fields',
11
+ description: 'List the behavior segment condition fields (opened_campaign_since, clicked_campaign_since, not_opened_since, not_clicked_since, engagement_count_gte) with their value format. Use before building a segment with the contactsegment tools or the audience_build_segment skill.',
12
+ inputSchema: { type: 'object', properties: {} },
13
+ },
14
+ {
15
+ name: 'contact_segment_engagement_get',
16
+ description: "Get one contact's recent engagement events (opens, clicks, deliveries, form submits, site visits) and counts by type.",
17
+ inputSchema: {
18
+ type: 'object',
19
+ properties: { email: { type: 'string' }, days: { type: 'number', description: '1 to 3650; default 90' } },
20
+ required: ['email'],
21
+ },
22
+ },
23
+ {
24
+ name: 'contact_segment_send_time_get',
25
+ description: "Get one contact's most common email open hour (send-time groundwork; nothing is scheduled). Returns modalHour null until the contact has enough opens.",
26
+ inputSchema: {
27
+ type: 'object',
28
+ properties: { email: { type: 'string' }, timezone: { type: 'string', description: 'Timezone id; default UTC' } },
29
+ required: ['email'],
30
+ },
31
+ },
32
+ {
33
+ name: 'contact_segment_send_time_list',
34
+ description: "List every contact's most common email open hour (UTC), paged. Contacts with too few opens are left out.",
35
+ inputSchema: { type: 'object', properties: { page: { type: 'number' }, pageSize: { type: 'number', description: '1 to 500' } } },
36
+ },
37
+ {
38
+ name: 'contact_segment_engagement_record',
39
+ description: 'Record one engagement event for a contact, for example a form submission or site visit from your own system. Safe to retry when sourceRef is set.',
40
+ inputSchema: {
41
+ type: 'object',
42
+ properties: {
43
+ email: { type: 'string' },
44
+ eventType: { type: 'string', enum: EVENT_TYPES },
45
+ url: { type: 'string' },
46
+ sourceRef: { type: 'string', description: 'Your own id for the event; makes retries idempotent' },
47
+ campaignId: { type: 'number' },
48
+ campaignKind: { type: 'string', enum: ['broadcast', 'drip'] },
49
+ occurredUtc: { type: 'string', description: 'ISO timestamp; default now' },
50
+ hourOfDayLocal: { type: 'number', description: '0 to 23' },
51
+ },
52
+ required: ['email', 'eventType'],
53
+ },
54
+ },
55
+ {
56
+ name: 'contact_segment_preview',
57
+ description: 'Preview a saved contact segment: how many contacts match now and a small sample.',
58
+ inputSchema: { type: 'object', properties: { segmentId: { type: 'number' } }, required: ['segmentId'] },
59
+ },
60
+ ];
61
+
62
+ const q = (o) => {
63
+ const p = new URLSearchParams();
64
+ for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v));
65
+ const s = p.toString();
66
+ return s ? `?${s}` : '';
67
+ };
68
+
69
+ export const handlers = {
70
+ contact_segment_engagement_fields: async (_a, ctx) => ctx.api('GET', '/ContactSegments/engagement/fields'),
71
+ contact_segment_engagement_get: async (a, ctx) =>
72
+ ctx.api('GET', `/ContactSegments/engagement/contact${q({ email: a.email, days: a.days })}`),
73
+ contact_segment_send_time_get: async (a, ctx) =>
74
+ ctx.api('GET', `/ContactSegments/engagement/send-time${q({ email: a.email, timezone: a.timezone })}`),
75
+ contact_segment_send_time_list: async (a, ctx) =>
76
+ ctx.api('GET', `/ContactSegments/engagement/send-times${q({ page: a.page, pageSize: a.pageSize })}`),
77
+ contact_segment_engagement_record: async (a, ctx) => {
78
+ const body = { email: a.email, eventType: a.eventType };
79
+ for (const k of ['url', 'sourceRef', 'campaignId', 'campaignKind', 'occurredUtc', 'hourOfDayLocal']) if (a[k] !== undefined) body[k] = a[k];
80
+ return ctx.api('POST', '/ContactSegments/engagement/events', body);
81
+ },
82
+ contact_segment_preview: async (a, ctx) => ctx.api('POST', `/ContactSegments/${Number(a.segmentId)}/preview`),
83
+ };
@@ -0,0 +1,144 @@
1
+ // MCP parity for `velaro crm-view`, `velaro crm-bulk` and `velaro crm-webform` (cli/lib/commands/crm-views-bulk-webforms.js).
2
+ // Backend: velaro-messaging CrmSavedViewsController, CrmBulkController and CrmWebFormsController
3
+ // (docs/architecture/crm-studio-program.md, features 7 to 10). Site from the credential, never an argument.
4
+
5
+ const ENTITIES = ['contact', 'company', 'deal'];
6
+ const VISIBILITIES = ['personal', 'team', 'everyone'];
7
+ const ACTIONS = ['update', 'owner', 'stage', 'tag', 'untag', 'delete', 'restore'];
8
+
9
+ const data = (r) => (r && typeof r === 'object' && 'data' in r ? r.data : r);
10
+ const q = (o) => {
11
+ const p = Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => `${k}=${encodeURIComponent(v)}`);
12
+ return p.length ? `?${p.join('&')}` : '';
13
+ };
14
+
15
+ export const tools = [
16
+ {
17
+ name: 'crm_view_list',
18
+ description: 'List the saved CRM views the signed-in user can see (their own personal views, views shared with their teams, and views shared with everyone), optionally for one record type. Each view has its columns, filters and sort. The reply also says whether this plan can save views (see your plan); listing always works.',
19
+ inputSchema: { type: 'object', properties: { entity: { type: 'string', enum: ENTITIES } } },
20
+ },
21
+ {
22
+ name: 'crm_view_get',
23
+ description: 'Get one saved CRM view by id. A personal view that belongs to someone else answers not found.',
24
+ inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] },
25
+ },
26
+ {
27
+ name: 'crm_view_meta',
28
+ description: 'List what a saved view can use: the record types, the built-in fields of each (custom fields are cf:<fieldId>), the default columns, the filter operators and the visibilities.',
29
+ inputSchema: { type: 'object', properties: {} },
30
+ },
31
+ {
32
+ name: 'crm_view_save',
33
+ description: 'Create or update a saved CRM view for contacts, companies or deals. Pass id to update; on update only the keys you send change. Creating, changing and deleting views is part of the CRM Studio package (see your plan). Anyone can save a personal view; sharing with a team or everyone needs a Manager or Administrator. Filters are { field, op, value } with op one of eq, neq, contains, gt, gte, lt, lte, in, empty, notEmpty. Fields are built-in names or cf:<customFieldId>. The record type of an existing view cannot change.',
34
+ inputSchema: {
35
+ type: 'object',
36
+ properties: {
37
+ id: { type: 'number', description: 'Existing view id to update.' },
38
+ entity: { type: 'string', enum: ENTITIES, description: 'Required when creating.' },
39
+ name: { type: 'string', description: 'Required when creating.' },
40
+ visibility: { type: 'string', enum: VISIBILITIES },
41
+ teamId: { type: 'number', description: 'Required when visibility is team.' },
42
+ pipelineId: { type: 'number', description: 'Deal views only.' },
43
+ columns: { type: 'array', items: { type: 'string' }, description: 'Fields to show; empty uses the defaults for the record type.' },
44
+ filters: {
45
+ type: 'array',
46
+ items: { type: 'object', properties: { field: { type: 'string' }, op: { type: 'string' }, value: {} }, required: ['field', 'op'] },
47
+ },
48
+ sort: { type: 'object', properties: { field: { type: 'string' }, direction: { type: 'string', enum: ['asc', 'desc'] } } },
49
+ sortOrder: { type: 'number', description: 'Position in the view list.' },
50
+ },
51
+ },
52
+ },
53
+ {
54
+ name: 'crm_view_delete',
55
+ description: 'Delete a saved CRM view. Only its owner can delete a personal view; shared views need a Manager or Administrator. No records are touched. Part of the CRM Studio package (see your plan).',
56
+ inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] },
57
+ },
58
+ {
59
+ name: 'crm_bulk_meta',
60
+ description: 'List what CRM bulk actions support: the record types, the actions, the built-in fields that can be changed in bulk, the forecast categories and the largest batch.',
61
+ inputSchema: { type: 'object', properties: {} },
62
+ },
63
+ {
64
+ name: 'crm_bulk_run',
65
+ description: 'Run one bulk action on contacts, companies or deals. Actions: update (set one field on every record; blank clears it), owner (set or clear the owner), stage (deals; the same required-field rules as the board apply per record), tag and untag (contacts), delete and restore (Administrator only; contacts are soft-deleted and restorable for a limited time, companies and deals are archived). Manager or Administrator, and part of the CRM Studio package (see your plan). Each record is reported on its own and one failure never blocks the others. ALWAYS call with dryRun true first and show the result before running for real, especially for delete.',
66
+ inputSchema: {
67
+ type: 'object',
68
+ properties: {
69
+ entity: { type: 'string', enum: ENTITIES },
70
+ action: { type: 'string', enum: ACTIONS },
71
+ ids: { type: 'array', items: { type: 'number' }, description: 'Record ids; one batch only (see crm_bulk_meta for the size).' },
72
+ dryRun: { type: 'boolean', description: 'Report per record what would happen without changing anything.' },
73
+ field: { type: 'string', description: 'update: built-in field name (see crm_bulk_meta) or cf:<customFieldId>.' },
74
+ value: { description: 'update: the new value; an empty string clears the field.' },
75
+ ownerId: { type: 'number', description: 'owner: the new owner user id.' },
76
+ clear: { type: 'boolean', description: 'owner: remove the owner instead of setting one.' },
77
+ stageId: { type: 'string', description: 'stage: the target stage id.' },
78
+ lostReason: { type: 'string', description: 'stage: stored when the target stage is a lost stage.' },
79
+ tagId: { type: 'number', description: 'tag and untag: the contact tag id.' },
80
+ },
81
+ required: ['entity', 'action', 'ids'],
82
+ },
83
+ },
84
+ {
85
+ name: 'crm_webform_list',
86
+ description: 'List the CRM form layouts that are published as public web forms, with each form\'s page path and whether it is online. Administrator only.',
87
+ inputSchema: { type: 'object', properties: {} },
88
+ },
89
+ {
90
+ name: 'crm_webform_get',
91
+ description: 'Show the web form published from one form layout (page path, question count, whether it is online). Administrator only.',
92
+ inputSchema: { type: 'object', properties: { layoutId: { type: 'number' } }, required: ['layoutId'] },
93
+ },
94
+ {
95
+ name: 'crm_webform_publish',
96
+ description: 'Publish a CRM form layout as a public web form, or update the one already published (same link). The form is a survey with one CRM field question per layout field, served at the hosted survey page; the reply lists any layout fields that were left out and why. Administrator only; part of the CRM Studio package (see your plan).',
97
+ inputSchema: { type: 'object', properties: { layoutId: { type: 'number' } }, required: ['layoutId'] },
98
+ },
99
+ {
100
+ name: 'crm_webform_unpublish',
101
+ description: 'Take a published CRM web form offline. Administrator only. Works on any plan so a form can always be taken down.',
102
+ inputSchema: { type: 'object', properties: { layoutId: { type: 'number' } }, required: ['layoutId'] },
103
+ },
104
+ ];
105
+
106
+ const id = (v) => encodeURIComponent(v);
107
+
108
+ export const handlers = {
109
+ crm_view_list: async (a, ctx) => data(await ctx.messagingGet(`/CrmSavedViews${q({ entity: a.entity })}`)),
110
+ crm_view_get: async (a, ctx) => data(await ctx.messagingGet(`/CrmSavedViews/${id(a.id)}`)),
111
+ crm_view_meta: async (_a, ctx) => data(await ctx.messagingGet('/CrmSavedViews/meta')),
112
+ crm_view_save: async (a, ctx) => {
113
+ const body = {};
114
+ if (a.id) {
115
+ // The server replaces the whole view on update, so start from the stored one and change only what was sent.
116
+ const cur = data(await ctx.messagingGet(`/CrmSavedViews/${id(a.id)}`));
117
+ Object.assign(body, {
118
+ entity: cur.entity, name: cur.name, visibility: cur.visibility, teamId: cur.teamId ?? null, pipelineId: cur.pipelineId ?? null,
119
+ columns: cur.columns ?? [], filters: cur.filters ?? [], sort: cur.sort ?? null, sortOrder: cur.sortOrder ?? 0,
120
+ });
121
+ } else {
122
+ if (!a.entity) throw new Error('[CRM] entity is required when creating a view.');
123
+ if (!a.name) throw new Error('[CRM] name is required when creating a view.');
124
+ body.entity = a.entity;
125
+ }
126
+ for (const k of ['name', 'visibility', 'teamId', 'pipelineId', 'columns', 'filters', 'sort', 'sortOrder']) {
127
+ if (a[k] !== undefined) body[k] = a[k];
128
+ }
129
+ return data(a.id ? await ctx.messagingPut(`/CrmSavedViews/${id(a.id)}`, body) : await ctx.messagingPost('/CrmSavedViews', body));
130
+ },
131
+ crm_view_delete: async (a, ctx) => data(await ctx.messagingDel(`/CrmSavedViews/${id(a.id)}`)),
132
+ crm_bulk_meta: async (_a, ctx) => data(await ctx.messagingGet('/CrmBulk/meta')),
133
+ crm_bulk_run: async (a, ctx) => {
134
+ const body = { entity: a.entity, action: a.action, ids: a.ids, dryRun: !!a.dryRun };
135
+ for (const k of ['field', 'value', 'ownerId', 'clear', 'stageId', 'lostReason', 'tagId']) {
136
+ if (a[k] !== undefined) body[k] = a[k];
137
+ }
138
+ return data(await ctx.messagingPost('/CrmBulk', body));
139
+ },
140
+ crm_webform_list: async (_a, ctx) => data(await ctx.messagingGet('/CrmWebForms')),
141
+ crm_webform_get: async (a, ctx) => data(await ctx.messagingGet(`/CrmWebForms/${id(a.layoutId)}`)),
142
+ crm_webform_publish: async (a, ctx) => data(await ctx.messagingPost(`/CrmWebForms/${id(a.layoutId)}/publish`, {})),
143
+ crm_webform_unpublish: async (a, ctx) => data(await ctx.messagingDel(`/CrmWebForms/${id(a.layoutId)}/publish`)),
144
+ };
package/server.js CHANGED
@@ -3465,6 +3465,18 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
3465
3465
  description: 'List NetSuite config IDs for the site (id, displayName, company) — a site can have multiple NetSuite connections. Use this to find the configId needed by netsuite_cti_get_urls / netsuite_cti_generate_url. Lives in velaro-messaging — requires VELARO_MESSAGING_API.',
3466
3466
  inputSchema: { type: 'object', properties: {}, required: [] },
3467
3467
  },
3468
+ {
3469
+ name: 'netsuite_screen_pop_every_page',
3470
+ description: 'Get or set whether the NetSuite screen pop shows on every NetSuite page (needs SuiteApp 1.2.0 or later; the Screen Pop page and dashboard portlet keep working). action=get returns the current value; action=set requires enabled (true/false) and keeps every other call-pop setting as it is. Lives in velaro-messaging (api/v1/CallPopSettings, row netsuite) — requires VELARO_MESSAGING_API.',
3471
+ inputSchema: {
3472
+ type: 'object',
3473
+ properties: {
3474
+ action: { type: 'string', enum: ['get', 'set'], description: 'get or set.' },
3475
+ enabled: { type: 'boolean', description: 'Required for action=set.' },
3476
+ },
3477
+ required: ['action'],
3478
+ },
3479
+ },
3468
3480
  {
3469
3481
  name: 'netsuite_cti_get_urls',
3470
3482
  description: 'Get the current NetSuite click-to-dial (CTI) setup URLs for a config — the dial URL to paste into NetSuite Home > Set Preferences > Telephony > CTI URL, and the (unconfirmed-automatic) screen-pop URL. Returns null URLs if a token has never been generated. Lives in velaro-messaging — requires VELARO_MESSAGING_API.',
@@ -7958,6 +7970,24 @@ reply: ${r?.reply}`;
7958
7970
  ` | clientId ${c.clientIdSaved ? 'saved' : 'MISSING'}, certificate ${c.certificateIdSaved ? 'saved' : 'MISSING'}` +
7959
7971
  `${c.certificateExpiresAt ? `, expires ${c.certificateExpiresAt}` : ''}`).join('\n');
7960
7972
  }
7973
+ case 'netsuite_screen_pop_every_page': {
7974
+ const raw = await messagingGet('/api/v1/CallPopSettings');
7975
+ const body = raw?.data ?? raw;
7976
+ const rows = Array.isArray(body) ? body : [...(body?.global ? [body.global] : []), ...(body?.overrides ?? [])];
7977
+ const row = rows.find(x => x.integrationSlug === 'netsuite') ?? null;
7978
+ const was = row?.showOnEveryPage ?? null;
7979
+ const label = v => (v === null ? 'not set (inherits the default)' : v ? 'on' : 'off');
7980
+ if (args.action === 'get') return `Screen pop on every NetSuite page: ${label(was)}`;
7981
+ if (args.action !== 'set' || typeof args.enabled !== 'boolean') throw new Error('action must be get or set; set requires enabled (true or false).');
7982
+ const r = row ?? {};
7983
+ await messagingPut('/api/v1/CallPopSettings/netsuite', {
7984
+ popMode: r.popMode ?? null, popOnInbound: r.popOnInbound ?? null, popOnOutbound: r.popOnOutbound ?? null,
7985
+ autoOpenRecord: r.autoOpenRecord ?? null, unknownCallerInbox: r.unknownCallerInbox ?? null,
7986
+ promptNotesAfterCall: r.promptNotesAfterCall ?? null, displayFieldsCsv: r.displayFieldsCsv || null,
7987
+ callLogAssociationsCsv: r.callLogAssociationsCsv || null, showOnEveryPage: args.enabled,
7988
+ });
7989
+ return `Screen pop on every NetSuite page: ${label(args.enabled)} (was ${label(was)}).`;
7990
+ }
7961
7991
  case 'netsuite_cti_get_urls': {
7962
7992
  const urls = await messagingGet(`/NetSuite/Integrations/${args.configId}/CtiUrls`);
7963
7993
  if (!urls.ctiUrlToken) return `No CTI URL generated yet for config ${args.configId}. Use netsuite_cti_generate_url to create one.`;