@velaro/mcp-server 2.0.85 → 2.0.86

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.85",
3
+ "version": "2.0.86",
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,137 @@
1
+ // MCP parity for `velaro sales` (cli/lib/commands/sales.js). Backend: velaro-admin SalesAutomationController
2
+ // (routes SalesAutomation/...). Revenue Suite package: sales sequences and speed-to-lead on the native Velaro CRM.
3
+ // Site from the credential only; no tool takes a site id. Writes are upserts.
4
+
5
+ const pid = (v) => encodeURIComponent(String(v));
6
+ const int = (v) => Number(v);
7
+
8
+ export const tools = [
9
+ {
10
+ name: 'sales_status',
11
+ description: 'Which Revenue Suite features (sales sequences, speed to lead, deal automation) are on for the signed-in account.',
12
+ inputSchema: { type: 'object', properties: {} },
13
+ },
14
+ {
15
+ name: 'sales_step_types',
16
+ description: 'The step types a sales sequence can use (create task, assign owner, notify rep, call now, book meeting, create deal, advance deal) with their fields.',
17
+ inputSchema: { type: 'object', properties: {} },
18
+ },
19
+ {
20
+ name: 'sales_templates',
21
+ description: 'The starter sales sequences and whether each is already installed (campaign id, active state).',
22
+ inputSchema: { type: 'object', properties: {} },
23
+ },
24
+ {
25
+ name: 'sales_template_install',
26
+ description: 'Install (or re-open) a starter sales sequence. Upsert by name, so repeating it never creates a duplicate. reset replaces the steps after saving a snapshot to the audit trail.',
27
+ inputSchema: {
28
+ type: 'object',
29
+ properties: {
30
+ key: { type: 'string', description: 'Starter sequence key from sales_templates' },
31
+ bookingLinkUrl: { type: 'string', description: 'Full https scheduler link used in booking steps' },
32
+ activate: { type: 'boolean', description: 'Turn the sequence on after installing' },
33
+ reset: { type: 'boolean', description: 'Start over: replace the existing steps' },
34
+ },
35
+ required: ['key'],
36
+ },
37
+ },
38
+ {
39
+ name: 'sales_enroll',
40
+ description: 'Enroll one contact in a sales sequence. Idempotent: a repeat enrolls once.',
41
+ inputSchema: {
42
+ type: 'object',
43
+ properties: {
44
+ campaignId: { type: 'number', description: 'Sequence (campaign) id' },
45
+ email: { type: 'string' },
46
+ name: { type: 'string' },
47
+ context: { type: 'object', description: 'Optional string values merged into the sequence messages', additionalProperties: { type: 'string' } },
48
+ },
49
+ required: ['campaignId', 'email'],
50
+ },
51
+ },
52
+ {
53
+ name: 'speed_to_lead_rules',
54
+ description: 'List the speed to lead rules (triggers, sources, notify and escalate timing, channels, linked sequence).',
55
+ inputSchema: { type: 'object', properties: {} },
56
+ },
57
+ {
58
+ name: 'speed_to_lead_rule_upsert',
59
+ description: 'Create a speed to lead rule, or update one when id is given. Names are unique per account.',
60
+ inputSchema: {
61
+ type: 'object',
62
+ properties: {
63
+ id: { type: 'number', description: 'Rule id to update; omit to create' },
64
+ name: { type: 'string' },
65
+ isActive: { type: 'boolean' },
66
+ triggerTypes: { type: 'array', items: { type: 'string' } },
67
+ sources: { type: 'array', items: { type: 'string' } },
68
+ minScore: { type: 'number', description: 'Minimum lead score 0 to 100' },
69
+ notifySeconds: { type: 'number', description: 'Notify the owner within this many seconds' },
70
+ escalateAfterMinutes: { type: 'number' },
71
+ maxEscalations: { type: 'number' },
72
+ teamId: { type: 'number' },
73
+ skillId: { type: 'number' },
74
+ notifyChannels: { type: 'array', items: { type: 'string', enum: ['desktop', 'teams', 'slack'] } },
75
+ sequenceCampaignId: { type: 'number', description: 'Sequence to enroll the lead in' },
76
+ },
77
+ required: ['name'],
78
+ },
79
+ },
80
+ {
81
+ name: 'speed_to_lead_rule_delete',
82
+ description: 'Delete a speed to lead rule.',
83
+ inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] },
84
+ },
85
+ {
86
+ name: 'speed_to_lead_report',
87
+ description: 'Time to first touch report: how fast new leads are contacted, breaches and escalations over a number of days.',
88
+ inputSchema: { type: 'object', properties: { days: { type: 'number', description: 'Days to cover (default 30)' } } },
89
+ },
90
+ {
91
+ name: 'speed_to_lead_leads',
92
+ description: 'Page through speed to lead leads, newest first, with owner, first touch and status.',
93
+ inputSchema: {
94
+ type: 'object',
95
+ properties: {
96
+ page: { type: 'number' },
97
+ pageSize: { type: 'number' },
98
+ status: { type: 'string', enum: ['pending', 'touched', 'breached'] },
99
+ },
100
+ },
101
+ },
102
+ ];
103
+
104
+ const RULE_KEYS = ['id', 'name', 'isActive', 'triggerTypes', 'sources', 'minScore', 'notifySeconds', 'escalateAfterMinutes', 'maxEscalations', 'teamId', 'skillId', 'notifyChannels', 'sequenceCampaignId'];
105
+
106
+ export const handlers = {
107
+ sales_status: async (_a, ctx) => ctx.api('GET', '/SalesAutomation/Status'),
108
+ sales_step_types: async (_a, ctx) => ctx.api('GET', '/SalesAutomation/StepTypes'),
109
+ sales_templates: async (_a, ctx) => ctx.api('GET', '/SalesAutomation/Templates'),
110
+ sales_template_install: async (a, ctx) =>
111
+ ctx.api('POST', `/SalesAutomation/Templates/${pid(a.key)}/Install`, {
112
+ bookingLinkUrl: a.bookingLinkUrl,
113
+ activate: !!a.activate,
114
+ reset: !!a.reset,
115
+ }),
116
+ sales_enroll: async (a, ctx) =>
117
+ ctx.api('POST', '/SalesAutomation/Enroll', { campaignId: int(a.campaignId), email: a.email, name: a.name, context: a.context }),
118
+ speed_to_lead_rules: async (_a, ctx) => ctx.api('GET', '/SalesAutomation/SpeedToLead/Rules'),
119
+ speed_to_lead_rule_upsert: async (a, ctx) => {
120
+ const body = {};
121
+ for (const k of RULE_KEYS) if (a[k] !== undefined) body[k] = a[k];
122
+ return ctx.api('PUT', '/SalesAutomation/SpeedToLead/Rules', body);
123
+ },
124
+ speed_to_lead_rule_delete: async (a, ctx) => ctx.api('DELETE', `/SalesAutomation/SpeedToLead/Rules/${int(a.id)}`),
125
+ speed_to_lead_report: async (a, ctx) => {
126
+ const qs = a.days ? `?days=${int(a.days)}` : '';
127
+ return ctx.api('GET', `/SalesAutomation/SpeedToLead/Report${qs}`);
128
+ },
129
+ speed_to_lead_leads: async (a, ctx) => {
130
+ const qs = new URLSearchParams();
131
+ if (a.page) qs.set('page', String(int(a.page)));
132
+ if (a.pageSize) qs.set('pageSize', String(int(a.pageSize)));
133
+ if (a.status) qs.set('status', a.status);
134
+ const q = qs.toString();
135
+ return ctx.api('GET', `/SalesAutomation/SpeedToLead/Leads${q ? `?${q}` : ''}`);
136
+ },
137
+ };
@@ -0,0 +1,99 @@
1
+ // velaro service-state: Conversation Intelligence. Pause promotions for contacts who need service
2
+ // (open case, bad recent chat or call, unanswered call, failed delivery) and follow up after unanswered calls.
3
+ // Parity module (CLI group service-state -> MCP tools service_state_*). Site comes from the credential only.
4
+
5
+ const qs = (o) => { const p = new URLSearchParams(); for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v)); const s = p.toString(); return s ? '?' + s : ''; };
6
+ 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; };
7
+ const bool = (v) => (v === undefined ? undefined : v === true || v === 'true');
8
+
9
+ const POLICY_PROPS = {
10
+ enabled: { type: 'boolean', description: 'Turn service pauses on or off' },
11
+ holdOpenCase: { type: 'boolean', description: 'Pause promotions while the contact has an open support case' },
12
+ holdNegativeSentiment: { type: 'boolean', description: 'Pause after a bad recent chat or call' },
13
+ negativeSentimentWindowDays: { type: 'integer', description: 'Days to look back, 1-90' },
14
+ holdUnresolvedVoice: { type: 'boolean', description: 'Pause after an unanswered phone call' },
15
+ unresolvedVoiceWindowDays: { type: 'integer', description: 'Days to look back, 1-90' },
16
+ holdFailedDelivery: { type: 'boolean', description: 'Pause after a message to them failed to deliver' },
17
+ failedDeliveryWindowDays: { type: 'integer', description: 'Days to look back, 1-90' },
18
+ maxHoldDays: { type: 'integer', description: 'Longest a message waits before it is dropped, 1-90 days' },
19
+ recheckMinutes: { type: 'integer', description: 'How often held messages are checked again, 5-1440 minutes' },
20
+ quietHoursStart: { type: 'integer', description: 'Quiet hours start, hour 0-23' },
21
+ quietHoursEnd: { type: 'integer', description: 'Quiet hours end, hour 0-23' },
22
+ quietHoursTimeZone: { type: 'string', description: 'Time zone for quiet hours, for example America/Los_Angeles' },
23
+ voiceFlowEnabled: { type: 'boolean', description: 'Follow up after unanswered calls' },
24
+ voiceFlowCampaignId: { type: 'integer', description: 'Sequence used for the follow-up' },
25
+ voiceFlowMinCallSeconds: { type: 'integer', description: 'Ignore calls shorter than this' },
26
+ };
27
+
28
+ export const tools = [
29
+ {
30
+ name: 'service_state_get_policy',
31
+ description: 'Show the service pause settings: which situations (open support case, bad recent chat or call, unanswered call, failed delivery) hold promotional email and text, how long a message waits, quiet hours, and the unanswered-call follow-up. Works with the recommended defaults if never edited. Needs Conversation Intelligence.',
32
+ inputSchema: { type: 'object', properties: {} },
33
+ },
34
+ {
35
+ name: 'service_state_set_policy',
36
+ description: 'Change service pause settings. Only the fields you pass change. Service messages (receipts, order updates, case replies) are never held. Needs Conversation Intelligence.',
37
+ inputSchema: { type: 'object', properties: POLICY_PROPS },
38
+ },
39
+ {
40
+ name: 'service_state_list_holds',
41
+ description: 'List promotional messages held for a service reason, with the plain-language reason, when they were held and when they expire. Filter by status (held, released, expired) or contact email.',
42
+ inputSchema: { type: 'object', properties: {
43
+ status: { type: 'string', enum: ['held', 'released', 'expired'], description: 'Default held' },
44
+ contactEmail: { type: 'string', description: 'Only this contact' },
45
+ page: { type: 'integer', description: 'Page number, default 1' },
46
+ pageSize: { type: 'integer', description: 'Rows per page, default 25' },
47
+ } },
48
+ },
49
+ {
50
+ name: 'service_state_release_hold',
51
+ description: 'Release one held promotion so it is sent on the next dispatch pass.',
52
+ inputSchema: { type: 'object', properties: { id: { type: 'integer', description: 'Hold id from service_state_list_holds' } }, required: ['id'] },
53
+ },
54
+ {
55
+ name: 'service_state_preview',
56
+ description: 'Check whether a promotional (or service) message to one contact would be held right now. Nothing is sent. Provide an email or phone.',
57
+ inputSchema: { type: 'object', properties: {
58
+ email: { type: 'string', description: 'Contact email' },
59
+ phone: { type: 'string', description: 'Contact phone' },
60
+ messageClass: { type: 'string', enum: ['promotional', 'transactional'], description: 'Default promotional' },
61
+ } },
62
+ },
63
+ {
64
+ name: 'service_state_voice_enrollments',
65
+ description: 'List callers followed up after an unanswered call, and callers skipped with the reason (unknown caller, no consent, unsubscribed).',
66
+ inputSchema: { type: 'object', properties: {
67
+ page: { type: 'integer', description: 'Page number, default 1' },
68
+ pageSize: { type: 'integer', description: 'Rows per page, default 25' },
69
+ } },
70
+ },
71
+ {
72
+ name: 'service_state_voice_flow_setup',
73
+ description: 'Create (or reuse) the ready-made email follow-up sequence for unanswered calls. It stops by itself when a later conversation resolves the question. Returns the sequence id; then turn on voiceFlowEnabled with service_state_set_policy.',
74
+ inputSchema: { type: 'object', properties: {} },
75
+ },
76
+ ];
77
+
78
+ export const handlers = {
79
+ service_state_get_policy: async (_a, ctx) => ctx.api('GET', '/ServiceState/policy'),
80
+ service_state_set_policy: async (a, ctx) => {
81
+ const body = {};
82
+ for (const k of Object.keys(POLICY_PROPS)) {
83
+ if (a[k] === undefined) continue;
84
+ body[k] = POLICY_PROPS[k].type === 'boolean' ? bool(a[k]) : a[k];
85
+ }
86
+ if (!Object.keys(body).length) throw new Error('Provide at least one setting to change');
87
+ return ctx.api('PUT', '/ServiceState/policy', body);
88
+ },
89
+ service_state_list_holds: async (a, ctx) =>
90
+ ctx.api('GET', '/ServiceState/holds' + qs({ status: a.status ?? 'held', contactEmail: a.contactEmail, page: a.page ?? 1, pageSize: a.pageSize ?? 25 })),
91
+ service_state_release_hold: async (a, ctx) => ctx.api('POST', '/ServiceState/holds/' + pid(a.id) + '/release', {}),
92
+ service_state_preview: async (a, ctx) => {
93
+ if (!a.email && !a.phone) throw new Error('email or phone is required');
94
+ return ctx.api('GET', '/ServiceState/preview' + qs({ email: a.email, phone: a.phone, messageClass: a.messageClass ?? 'promotional' }));
95
+ },
96
+ service_state_voice_enrollments: async (a, ctx) =>
97
+ ctx.api('GET', '/ServiceState/voice-enrollments' + qs({ page: a.page ?? 1, pageSize: a.pageSize ?? 25 })),
98
+ service_state_voice_flow_setup: async (_a, ctx) => ctx.api('POST', '/ServiceState/voice-flow/ensure-default', {}),
99
+ };
package/server.js CHANGED
@@ -2626,8 +2626,8 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
2626
2626
  properties: {
2627
2627
  take: { type: 'number', description: 'Page size, 1-100 (default 25)' },
2628
2628
  skip: { type: 'number', description: 'Rows to skip (default 0)' },
2629
- source: { type: 'string', enum: ['Transactional', 'Campaign', 'Broadcast'], description: 'Limit to one send system. Omit for all three.' },
2630
- status: { type: 'string', enum: ['Sent', 'Pending', 'Failed', 'Unsubscribed', 'Skipped'], description: 'Normalized status shared across all three systems' },
2629
+ source: { type: 'string', enum: ['Transactional', 'Campaign', 'Broadcast', 'ServiceHold'], description: 'Limit to one send system. Omit for all three.' },
2630
+ status: { type: 'string', enum: ['Sent', 'Pending', 'Failed', 'Unsubscribed', 'Held', 'Skipped'], description: 'Normalized status shared across all three systems' },
2631
2631
  search: { type: 'string', description: 'Match recipient address or subject' },
2632
2632
  },
2633
2633
  required: [],
@@ -2654,7 +2654,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
2654
2654
  take: { type: 'number', description: 'Page size, 1-100 (default 25)' },
2655
2655
  skip: { type: 'number', description: 'Rows to skip (default 0)' },
2656
2656
  source: { type: 'string', enum: ['Transactional', 'Campaign', 'Broadcast'], description: 'Limit to one send system. Omit for all three.' },
2657
- status: { type: 'string', enum: ['Sent', 'Pending', 'Failed', 'Unsubscribed', 'Skipped'], description: 'Normalized status shared across all three systems' },
2657
+ status: { type: 'string', enum: ['Sent', 'Pending', 'Failed', 'Unsubscribed', 'Held', 'Skipped'], description: 'Normalized status shared across all three systems' },
2658
2658
  },
2659
2659
  required: ['email'],
2660
2660
  },
@@ -28,6 +28,7 @@ const MUTATING = new Set([
28
28
  'zoom_phone_set_config', 'callpresence_set', 'callpresence_set_groups', 'callpresence_clear',
29
29
  'billing_insights_set_preferences', 'billing_insights_dismiss_recommendation',
30
30
  'site_sale_create', 'site_sale_update', 'site_sale_end',
31
+ 'service_state_set_policy', 'service_state_release_hold', 'service_state_voice_flow_setup',
31
32
  'integration_config_restore',
32
33
  ]);
33
34