@velaro/mcp-server 2.0.148 → 2.0.149

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/README.md CHANGED
@@ -290,6 +290,8 @@ Claude handles these operations natively. No exports, no copy-paste, no waiting
290
290
 
291
291
  This package is automatically published to npm on every Velaro production deploy. When Velaro ships new tools or improves existing ones, your next `npx` invocation pulls the latest version automatically. You don't need to update a package.json or run `npm install`.
292
292
 
293
+ The server also checks npm once a day. If your copy is behind, it says so three ways: a line on stderr, a note the assistant reads at start-up (so it can tell you), and a one-time note on the first tool result. A global install (`npm install -g @velaro/mcp-server`) updates itself in the background and asks you to restart your MCP client. An `npx` setup shows the notice and the fix: use `npx -y @velaro/mcp-server@latest` in your client config so every start pulls the newest version. Set `VELARO_NO_AUTO_UPDATE=1` to keep the notice but skip the self-update, or `VELARO_MCP_NO_UPDATE_CHECK=1` to turn the check off.
294
+
293
295
  If you want a pinned version for reproducible environments:
294
296
  ```bash
295
297
  npx @velaro/mcp-server@0.1.0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velaro/mcp-server",
3
- "version": "2.0.148",
3
+ "version": "2.0.149",
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": {
@@ -46,6 +46,7 @@
46
46
  "server.js",
47
47
  "tool-annotations.js",
48
48
  "fetch-retry.js",
49
+ "update-check.js",
49
50
  "messaging-base.js",
50
51
  "gateway-routing.js",
51
52
  "survey-email.js",
package/server.js CHANGED
@@ -59,6 +59,7 @@ import { normalizeMultiTabMode, buildMultiTabUpdateFields, normalizeEmailTranscr
59
59
  import { buildResolvePath, buildTimelinePath, buildOverrideBody, buildValidateBody, buildBannerPath, buildOverrideListPath, tolerant, VALIDATE_PATH, OVERRIDE_PATH } from './workflow-schedule.js';
60
60
  import { applyEmailSubmissionsTo } from './survey-email.js';
61
61
  import { shouldUseGateway } from './gateway-routing.js';
62
+ import { startMcpUpdateCheck } from './update-check.js';
62
63
 
63
64
  // Production admin API by default; set VELARO_ADMIN_API to target staging.
64
65
  const API_BASE = process.env.VELARO_ADMIN_API || 'https://api-admin-us-east.velaro.com';
@@ -394,48 +395,48 @@ async function rpc(toolName, args) {
394
395
 
395
396
  // ── Tool definitions ──────────────────────────────────────────────────────────
396
397
 
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
-
398
+ // ── Page widget mode / search scope / mobile version helpers ───────────────
399
+ // SettingsJson keys `mode` and `searchScope`; mobile version is a templated variant rule in DisplayRulesJson.
400
+ const PW_MODES = ['chat_only', 'search_only', 'chat_search'];
401
+ const PW_SCOPES = ['catalog', 'catalog_docs', 'page_data'];
402
+ const PW_MOBILE_TEMPLATE_ID = 'mobile-variant';
403
+ function pwParseJson(text, fallback) {
404
+ if (text == null || text === '') return fallback;
405
+ if (typeof text !== 'string') return text;
406
+ try { return JSON.parse(text); } catch { return fallback; }
407
+ }
408
+ function pwSettings(w) { const v = pwParseJson(w.settingsJson, {}); return v && typeof v === 'object' && !Array.isArray(v) ? v : {}; }
409
+ function pwRules(w) { const v = pwParseJson(w.displayRulesJson, []); return Array.isArray(v) ? v : []; }
410
+ function pwIsMobileRule(r) { return !!r && r.variant === true && r.templateId === PW_MOBILE_TEMPLATE_ID; }
411
+ function pwModeSummary(w) {
412
+ const s = pwSettings(w);
413
+ const mobile = pwRules(w).find(pwIsMobileRule);
414
+ return {
415
+ mode: PW_MODES.includes(s.mode) ? s.mode : 'chat_only',
416
+ searchScope: PW_SCOPES.includes(s.searchScope) ? s.searchScope : 'catalog',
417
+ mobileVersion: mobile ? { enabled: true, overrides: mobile.overrides ?? {} } : { enabled: false },
418
+ };
419
+ }
420
+ function pwBuildMobileRule(settings, overrides) {
421
+ const base = { mode: PW_MODES.includes(settings.mode) ? settings.mode : 'chat_only', layout: settings.layout ?? 'default', placement: settings.position ?? settings.placement ?? 'bottom-right' };
422
+ return {
423
+ templateId: PW_MOBILE_TEMPLATE_ID, variant: true, operator: 'all',
424
+ conditions: [{ type: 'device', value: 'mobile' }],
425
+ overrides: { ...base, ...(overrides ?? {}) },
426
+ };
427
+ }
428
+ // Friendly text for the two documented rejections (402 not entitled, variant rules disabled).
429
+ async function pwPut(id, w) {
430
+ try {
431
+ await api('PUT', `/PageWidgets/${id}`, w);
432
+ } catch (e) {
433
+ const msg = String(e?.message ?? e);
434
+ if (/variant_rules_disabled/.test(msg)) throw new Error('Mobile versions are not available yet for this account (variant_rules_disabled). Nothing was changed.');
435
+ 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.');
436
+ throw e;
437
+ }
438
+ }
439
+
439
440
  const TOOLS = [
440
441
  {
441
442
  name: 'case_list_types',
@@ -1558,6 +1559,31 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
1558
1559
  description: 'Staff: set or remove the per-site monthly translation allowance override. Without confirmed=true it only previews the before and after. Saving needs "Moshky can make changes" on; audit-logged.',
1559
1560
  inputSchema: { type: 'object', properties: { charactersPerMonth: { type: 'number' }, removeOverride: { type: 'boolean' }, reason: { type: 'string' }, confirmed: { type: 'boolean', description: 'true to save after the preview was approved' } }, required: [] },
1560
1561
  },
1562
+ // ── AI Voice Agent (Enterprise) ──────────────────────────────────────────
1563
+ {
1564
+ name: 'voice_agent_status',
1565
+ description: 'Show the AI Voice Agent settings for this site: provider (velaro or foundry), handoff target, and whether caller verification is on. Requires the Voice Agent feature on the plan.',
1566
+ inputSchema: { type: 'object', properties: {}, required: [] },
1567
+ },
1568
+ {
1569
+ name: 'voice_agent_set',
1570
+ description: 'Change AI Voice Agent settings: provider (velaro or foundry), foundryConfigId (a connection id from copilot_studio_list, required for foundry), handoffTarget (team name or phone number that takes handed-off calls) and verification (off or on). Only the fields you pass change.',
1571
+ inputSchema: {
1572
+ type: 'object',
1573
+ properties: {
1574
+ provider: { type: 'string', enum: ['velaro', 'foundry'], description: 'velaro = Velaro AI; foundry = your Azure AI Foundry agent' },
1575
+ foundryConfigId: { type: 'number', description: 'Connection id from copilot_studio_list (foundry only)' },
1576
+ handoffTarget: { type: 'string', description: 'Team name or phone number in international format' },
1577
+ verification: { type: 'string', enum: ['off', 'on'], description: 'Caller verification, off by default' },
1578
+ },
1579
+ required: [],
1580
+ },
1581
+ },
1582
+ {
1583
+ name: 'voice_agent_test_call',
1584
+ description: 'Place a test call so you can hear the voice agent greeting and confirm the handoff reaches the right person.',
1585
+ inputSchema: { type: 'object', properties: {}, required: [] },
1586
+ },
1561
1587
  // ── Copilot Studio / Azure AI Agent connections ──────────────────────────
1562
1588
  {
1563
1589
  name: 'copilot_studio_list',
@@ -3019,7 +3045,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
3019
3045
  },
3020
3046
  {
3021
3047
  name: 'page_widget_get',
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.',
3048
+ 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.',
3023
3049
  inputSchema: {
3024
3050
  type: 'object',
3025
3051
  properties: { id: { type: 'number', description: 'Widget DB row ID (not the widgetId UUID)' } },
@@ -3038,45 +3064,45 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
3038
3064
  required: ['id', 'isEnabled'],
3039
3065
  },
3040
3066
  },
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
- },
3067
+ {
3068
+ name: 'page_widget_set_mode',
3069
+ 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.',
3070
+ inputSchema: {
3071
+ type: 'object',
3072
+ properties: {
3073
+ id: { type: 'number', description: 'Widget DB row ID' },
3074
+ mode: { type: 'string', enum: PW_MODES, description: 'search_only | chat_only | chat_search' },
3075
+ },
3076
+ required: ['id', 'mode'],
3077
+ },
3078
+ },
3079
+ {
3080
+ name: 'page_widget_set_search_scope',
3081
+ 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.',
3082
+ inputSchema: {
3083
+ type: 'object',
3084
+ properties: {
3085
+ id: { type: 'number', description: 'Widget DB row ID' },
3086
+ scope: { type: 'string', enum: PW_SCOPES, description: 'catalog | catalog_docs | page_data' },
3087
+ },
3088
+ required: ['id', 'scope'],
3089
+ },
3090
+ },
3091
+ {
3092
+ name: 'page_widget_set_mobile_version',
3093
+ 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.',
3094
+ inputSchema: {
3095
+ type: 'object',
3096
+ properties: {
3097
+ id: { type: 'number', description: 'Widget DB row ID' },
3098
+ enabled: { type: 'boolean', description: 'true = separate mobile version, false = same as desktop' },
3099
+ mode: { type: 'string', enum: PW_MODES, description: 'Mobile experience override (only when enabled)' },
3100
+ layout: { type: 'string', description: 'Mobile layout override (only when enabled)' },
3101
+ placement: { type: 'string', description: 'Mobile placement override, e.g. bottom-right (only when enabled)' },
3102
+ },
3103
+ required: ['id', 'enabled'],
3104
+ },
3105
+ },
3080
3106
 
3081
3107
  // ── Chat Window launcher copy (per-page launcher label + greeting) ─────────
3082
3108
  {
@@ -6807,6 +6833,36 @@ async function handleTool(name, args) {
6807
6833
  return `Agent connection ${args.id} removed. It will no longer appear as a knowledge source option on workflow nodes.`;
6808
6834
  }
6809
6835
 
6836
+ case 'voice_agent_status': {
6837
+ const s = await api('GET', '/VoiceAgent/settings');
6838
+ return [
6839
+ 'AI Voice Agent',
6840
+ ` Provider: ${s?.provider ?? 'velaro'}${s?.provider === 'foundry' ? ` (connection ${s?.foundryConfigId ?? 'none'})` : ''}`,
6841
+ ` Handoff target: ${s?.handoffTarget || '(none set)'}`,
6842
+ ` Verification: ${s?.verification ?? 'off'}`,
6843
+ ].join('\n');
6844
+ }
6845
+
6846
+ case 'voice_agent_set': {
6847
+ const current = await api('GET', '/VoiceAgent/settings');
6848
+ const next = {
6849
+ provider: args.provider ?? current?.provider ?? 'velaro',
6850
+ foundryConfigId: args.foundryConfigId ?? current?.foundryConfigId ?? null,
6851
+ handoffTarget: args.handoffTarget ?? current?.handoffTarget ?? '',
6852
+ verification: args.verification ?? current?.verification ?? 'off',
6853
+ };
6854
+ if (next.provider === 'foundry' && !next.foundryConfigId) return 'foundryConfigId is required for provider foundry. Use copilot_studio_list to find it.';
6855
+ if (!String(next.handoffTarget).trim()) return 'handoffTarget is required (a team name or phone number).';
6856
+ await api('PUT', '/VoiceAgent/settings', next);
6857
+ return `AI Voice Agent saved. Provider: ${next.provider}. Handoff target: ${next.handoffTarget}. Verification: ${next.verification}.`;
6858
+ }
6859
+
6860
+ case 'voice_agent_test_call': {
6861
+ const r = await api('POST', '/VoiceAgent/test-call', {});
6862
+ if (r?.success === false) return `Test call could not be placed: ${r?.error ?? 'unknown error'}`;
6863
+ return 'Test call placed. Answer it to hear the greeting and check the handoff.';
6864
+ }
6865
+
6810
6866
  case 'copilot_studio_update': {
6811
6867
  if (!args.id) return 'id is required. Use copilot_studio_list to find the config ID.';
6812
6868
  const payload = {
@@ -8518,39 +8574,39 @@ reply: ${r?.reply}`;
8518
8574
 
8519
8575
  case 'page_widget_get': {
8520
8576
  const w = await api('GET', `/PageWidgets/${args.id}`);
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'}.`;
8577
+ return JSON.stringify({ ...w, ...pwModeSummary(w) }, null, 2);
8578
+ }
8579
+
8580
+ case 'page_widget_set_mode': {
8581
+ if (!PW_MODES.includes(args.mode)) return `mode must be one of: ${PW_MODES.join(', ')}.`;
8582
+ const w = await api('GET', `/PageWidgets/${args.id}`);
8583
+ const s = pwSettings(w); s.mode = args.mode;
8584
+ w.settingsJson = JSON.stringify(s);
8585
+ await pwPut(args.id, w);
8586
+ return `Widget ${args.id} experience set to ${args.mode}.`;
8587
+ }
8588
+
8589
+ case 'page_widget_set_search_scope': {
8590
+ if (!PW_SCOPES.includes(args.scope)) return `scope must be one of: ${PW_SCOPES.join(', ')}.`;
8591
+ const w = await api('GET', `/PageWidgets/${args.id}`);
8592
+ const s = pwSettings(w); s.searchScope = args.scope;
8593
+ w.settingsJson = JSON.stringify(s);
8594
+ await pwPut(args.id, w);
8595
+ return `Widget ${args.id} search scope set to ${args.scope}.`;
8596
+ }
8597
+
8598
+ case 'page_widget_set_mobile_version': {
8599
+ if (args.mode !== undefined && !PW_MODES.includes(args.mode)) return `mode must be one of: ${PW_MODES.join(', ')}.`;
8600
+ const w = await api('GET', `/PageWidgets/${args.id}`);
8601
+ const rules = pwRules(w).filter((r) => !pwIsMobileRule(r));
8602
+ if (args.enabled) {
8603
+ const ov = {};
8604
+ for (const k of ['mode', 'layout', 'placement']) if (args[k] !== undefined) ov[k] = args[k];
8605
+ rules.push(pwBuildMobileRule(pwSettings(w), ov));
8606
+ }
8607
+ w.displayRulesJson = JSON.stringify(rules);
8608
+ await pwPut(args.id, w);
8609
+ return `Widget ${args.id} mobile version ${args.enabled ? 'on' : 'off'}.`;
8554
8610
  }
8555
8611
 
8556
8612
  case 'page_widget_toggle': {
@@ -10765,9 +10821,17 @@ const PROMPTS = [
10765
10821
 
10766
10822
  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
10823
 
10824
+ const SERVER_VERSION = JSON.parse(_readFileSync(_join(_dirname(_ftu(import.meta.url)), 'package.json'), 'utf8')).version;
10825
+ // Tells the user (stderr, server instructions, first tool result) when a newer @velaro/mcp-server exists; global installs update themselves.
10826
+ const UPDATE = startMcpUpdateCheck({ currentVersion: SERVER_VERSION });
10827
+ let updateNoticePending = UPDATE.notice;
10828
+ if (UPDATE.notice) process.stderr.write(`[velaro-mcp] ${UPDATE.notice}
10829
+ `);
10768
10830
  const server = new Server(
10769
- { name: 'velaro', version: JSON.parse(_readFileSync(_join(_dirname(_ftu(import.meta.url)), 'package.json'), 'utf8')).version },
10770
- { capabilities: { tools: {}, prompts: {} }, instructions: SERVER_INSTRUCTIONS }
10831
+ { name: 'velaro', version: SERVER_VERSION },
10832
+ { capabilities: { tools: {}, prompts: {} }, instructions: UPDATE.notice ? `${SERVER_INSTRUCTIONS}
10833
+
10834
+ ${UPDATE.notice} Tell the user once, in plain words, that an update is available.` : SERVER_INSTRUCTIONS }
10771
10835
  );
10772
10836
 
10773
10837
  const PARITY = await loadParity('customer');
@@ -10796,7 +10860,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
10796
10860
  try {
10797
10861
  const parityResult = await runParity(PARITY, name, args ?? {}, { api, messagingGet, messagingText, messagingPost, messagingPut, messagingDel, messagingPatch });
10798
10862
  const result = parityResult !== undefined ? parityResult : await handleTool(name, args ?? {});
10799
- return { content: [{ type: 'text', text: String(result) }] };
10863
+ const out = String(result) + (updateNoticePending ? `
10864
+
10865
+ [Velaro MCP update] ${updateNoticePending}` : '');
10866
+ updateNoticePending = null;
10867
+ return { content: [{ type: 'text', text: out }] };
10800
10868
  } catch (err) {
10801
10869
  return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
10802
10870
  }
@@ -29,7 +29,7 @@ const MUTATING = new Set([
29
29
  'billing_insights_set_preferences', 'billing_insights_dismiss_recommendation',
30
30
  'site_sale_create', 'site_sale_update', 'site_sale_end',
31
31
  'service_state_set_policy', 'service_state_release_hold', 'service_state_voice_flow_setup',
32
- 'integration_config_restore',
32
+ 'integration_config_restore', 'voice_agent_test_call',
33
33
  ]);
34
34
 
35
35
  // Names that look like writes but only read (checked before the write rules).
@@ -93,7 +93,7 @@ const OPEN_WORLD_PREFIXES = [
93
93
  'outlook', 'ms_bookings', 'shopify', 'magento', 'netsuite', 'monday', 'notion', 'teams', 'slack',
94
94
  'webflow', 'klaviyo', 'callrail', 'copilot_studio', 'scraper', 'apple', 'jobboard', 'recruiting',
95
95
  'payment_recovery', 'pickup_notify', 'telephony', 'business_action', 'campaign_sender_auth',
96
- 'ivr_update_line',
96
+ 'ivr_update_line', 'voice_agent',
97
97
  ];
98
98
 
99
99
  const ACRONYMS = {
package/toolsets.js CHANGED
@@ -34,7 +34,7 @@ const GROUPS = {
34
34
  'jobboard', 'teams', 'netsuite', 'magento', 'woocommerce', 'shopify', 'bigcommerce', 'apple', 'monday', 'dynamics',
35
35
  'zoom', 'notion', 'klaviyo', 'outlook', 'slack', 'webflow', 'squarespace', 'callrail', 'recruiting', 'product',
36
36
  'commerce', 'pickup', 'ms', 'linked', 'part', 'acuity', 'calendly', 'telephony', 'livefluence', 'sitesync',
37
- 'code', 'mobile', 'copilot_studio', 'sse', 'missed', 'page_widget',
37
+ 'code', 'mobile', 'copilot_studio', 'voice_agent', 'sse', 'missed', 'page_widget',
38
38
  ],
39
39
  };
40
40
  const GROUP_NAMES = [...Object.keys(GROUPS), 'misc'];
@@ -0,0 +1,84 @@
1
+ // Update notice for the self-hosted MCP server (npx @velaro/mcp-server). Once a day it asks the npm registry
2
+ // for the latest version (cached in ~/.velaro/mcp-update.json); when a newer one exists it tells the user
3
+ // (stderr line, the server instructions the assistant reads, and the first tool result), and a global install
4
+ // updates itself in the background. npx cache runs only get the notice (npx reuses its cache until told otherwise).
5
+ // Never blocks start-up and never throws: a registry failure is silent and the server runs as before.
6
+ // Opt out: VELARO_MCP_NO_UPDATE_CHECK=1 (no check) or VELARO_NO_AUTO_UPDATE=1 (notice only, no install).
7
+ import { readFileSync, writeFileSync, mkdirSync, realpathSync } from 'node:fs';
8
+ import { homedir } from 'node:os';
9
+ import { join, dirname } from 'node:path';
10
+ import { spawn } from 'node:child_process';
11
+ import { fileURLToPath } from 'node:url';
12
+
13
+ const REGISTRY = 'https://registry.npmjs.org/@velaro/mcp-server/latest';
14
+ export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
15
+ const CACHE = join(homedir(), '.velaro', 'mcp-update.json');
16
+
17
+ export function isNewer(a, b) {
18
+ const pa = String(a).split('.').map(Number);
19
+ const pb = String(b).split('.').map(Number);
20
+ for (let i = 0; i < 3; i++) {
21
+ if ((pa[i] || 0) > (pb[i] || 0)) return true;
22
+ if ((pa[i] || 0) < (pb[i] || 0)) return false;
23
+ }
24
+ return false;
25
+ }
26
+
27
+ export function installKind(modulePath) {
28
+ let p = modulePath;
29
+ try { p = realpathSync(modulePath); } catch { /* keep as given */ }
30
+ if (/[\\/]_npx[\\/]/.test(p)) return 'npx';
31
+ if (/[\\/]node_modules[\\/]@velaro[\\/]mcp-server[\\/]/.test(p)) return 'global';
32
+ return 'checkout';
33
+ }
34
+
35
+ export function buildNotice(current, latest, kind, autoUpdating = false) {
36
+ if (!latest || !isNewer(latest, current)) return null;
37
+ const head = `Velaro MCP server ${current} is out of date (latest ${latest}).`;
38
+ if (autoUpdating) return `${head} Updating in the background; restart your MCP client to use ${latest}. Set VELARO_NO_AUTO_UPDATE=1 to turn this off.`;
39
+ if (kind === 'npx') return `${head} Point your MCP client at "npx -y @velaro/mcp-server@latest" and restart it.`;
40
+ if (kind === 'global') return `${head} Run: npm install -g @velaro/mcp-server@latest, then restart your MCP client.`;
41
+ return `${head} This is a dev checkout: git pull in velaro-admin/mcp.`;
42
+ }
43
+
44
+ function readCache(path) {
45
+ try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return {}; }
46
+ }
47
+ function writeCache(path, v) {
48
+ try { mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, JSON.stringify(v)); } catch { /* cache is optional */ }
49
+ }
50
+
51
+ /**
52
+ * Returns { notice, refresh, kind } immediately. `notice` comes from the cached last check (null when current or unknown);
53
+ * `refresh` is a promise for the registry call that updates the cache (resolves to the latest version or null).
54
+ */
55
+ export function startMcpUpdateCheck({ currentVersion, modulePath = fileURLToPath(import.meta.url), env = process.env, cachePath = CACHE, fetchImpl = fetch, now = Date.now(), spawnImpl = spawn } = {}) {
56
+ if (env.VELARO_MCP_NO_UPDATE_CHECK) return { notice: null, refresh: Promise.resolve(null), kind: 'off' };
57
+ const kind = installKind(modulePath);
58
+ const cache = readCache(cachePath);
59
+ const auto = kind === 'global' && !env.VELARO_NO_AUTO_UPDATE && !env.CI;
60
+ let autoStarted = false;
61
+ const maybeAuto = (latest) => {
62
+ if (!auto || autoStarted || !latest || !isNewer(latest, currentVersion) || readCache(cachePath)._autoTried === latest) return false;
63
+ try {
64
+ const child = spawnImpl(process.platform === 'win32' ? 'npm.cmd' : 'npm', ['install', '-g', '@velaro/mcp-server@latest'], { detached: true, stdio: 'ignore', shell: process.platform === 'win32' });
65
+ child.on?.('error', () => {});
66
+ child.unref?.();
67
+ writeCache(cachePath, { ...readCache(cachePath), _autoTried: latest });
68
+ autoStarted = true;
69
+ return true;
70
+ } catch { return false; }
71
+ };
72
+ const fresh = now - (cache.checkedAt || 0) < CHECK_INTERVAL_MS;
73
+ const started = maybeAuto(cache.latest);
74
+ const notice = buildNotice(currentVersion, cache.latest, kind, started);
75
+ const refresh = fresh ? Promise.resolve(cache.latest ?? null) : (async () => {
76
+ try {
77
+ const r = await fetchImpl(REGISTRY, { signal: AbortSignal.timeout(4000) });
78
+ const latest = (await r.json())?.version ?? null;
79
+ if (latest) { writeCache(cachePath, { ...readCache(cachePath), checkedAt: now, latest }); maybeAuto(latest); }
80
+ return latest;
81
+ } catch { return null; }
82
+ })();
83
+ return { notice, refresh, kind };
84
+ }