@velaro/mcp-server 0.6.55 → 0.6.56

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/mcp-server",
-  "version": "0.6.55",
+  "version": "0.6.56",
   "description": "Velaro MCP server — connect Claude and other AI agents directly to your Velaro account: KB, workflows, bots, conversations, contacts, routing, and more.",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
     "qs": "^6.16.0"
   },
   "overrides": {
-    "qs": "^6.16.0"
+    "qs": "^6.16.0",
+    "hono": "^4.13.5"
   },
   "scripts": {
     "start": "node server.js"
@@ -43,5 +44,8 @@
     "server.js",
     "server.json",
     "README.md"
-  ]
+  ],
+  "devDependencies": {
+    "license-checker-rseidelsohn": "^4.4.2"
+  }
 }

package/server.js

@@ -62,6 +62,12 @@ const MESSAGING_API = process.env.VELARO_MESSAGING_API || null;
 const MCP_KEY       = process.env.VELARO_MCP_KEY;
 const JWT           = process.env.VELARO_JWT;
 
+// mcp/staff-server.js defaults to staging instead -- the two servers' defaults intentionally
+// differ, but a zero-result lookup gives no hint which environment was actually searched
+// either way. See ENV_LABEL in staff-server.js for the incident this class of confusion caused
+// (a real production customer read as "doesn't exist" from a staging-scoped search).
+const ENV_LABEL = API_BASE.includes('staging') ? 'staging' : 'production';
+
 // Known admin API hosts, for tools that let a caller explicitly target one environment
 // regardless of what this server process's own API_BASE is configured to (see the `env` param
 // on the calendly_* superadmin tools below). Deliberately NOT used as a default anywhere —
@@ -561,6 +567,18 @@ const TOOLS = [
     },
   },
 
+  {
+    name: 'site_scraper_usage',
+    description: 'Velaro staff only. Scraper/upload/chunk consumption for ANY site in one call: pages this month vs budget (both the admin and messaging ledgers), upload pages, OCR pages, jobs today vs daily cap, and chunks indexed vs MaxIndexedChunkTotal with chunks grouped by index name. Wraps GET ScraperJobs/StaffUsage/{siteId} (IsVelaroAdminAsync + super-admin enforced server-side). Read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Target site ID (need not be your own)' },
+      },
+      required: ['siteId'],
+    },
+  },
+
   // ── Startup migration diagnostics (AdminStartupDiagnostics canary table) ──
   {
     name: 'admin_startup_diagnostics',
@@ -1593,6 +1611,120 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     description: 'Show what is currently indexed for the site: document counts per source type (kb_article, scraper_page, bigcommerce_product, etc). Use to verify ingestion completed and data is present.',
     inputSchema: { type: 'object', properties: {} },
   },
+  {
+    name: 'index_move_preview',
+    description: 'Preview moving (or copying) documents between two knowledge indexes on the site. Writes nothing. Returns document/chunk/page counts, per-document method (copy_vectors, rechunk, already_in_target, blocked), quota effect, and whether it can run. No rescan and no OCR is ever needed. Moving into a troubleshooting index needs the EnableTroubleshootingKnowledge entitlement. Wraps POST IndexMove/Preview (velaro-messaging); the site comes from the caller auth, never an argument.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromIndex: { type: 'string', description: 'Source index name' },
+        toIndex:   { type: 'string', description: 'Target index name' },
+        kind:      { type: 'string', enum: ['move', 'copy'], description: 'Default move' },
+        skipBlocked: { type: 'boolean', description: 'Leave blocked documents in place and move the rest' },
+        selector: {
+          type: 'object',
+          description: 'What to move. Needs at least one field or all:true. Fields: all (bool), jobId, urlPrefix, sourceIds[], fileNames[], docIds[] (numbers), sourceType (website_page | video_transcript | uploaded_document | onedrive_file | custom_content).',
+        },
+      },
+      required: ['fromIndex', 'toIndex', 'selector'],
+    },
+  },
+  {
+    name: 'index_move_execute',
+    description: 'Run a move/copy between knowledge indexes. Always call index_move_preview first and check canExecute. Write-then-delete and resumable: content is never missing from both indexes. Returns a moveId; poll index_move_status. Wraps POST IndexMove/Execute.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromIndex: { type: 'string' },
+        toIndex:   { type: 'string' },
+        kind:      { type: 'string', enum: ['move', 'copy'] },
+        skipBlocked: { type: 'boolean' },
+        selector: {
+          type: 'object',
+          description: 'What to move. Needs at least one field or all:true. Fields: all (bool), jobId, urlPrefix, sourceIds[], fileNames[], docIds[] (numbers), sourceType (website_page | video_transcript | uploaded_document | onedrive_file | custom_content).',
+        },
+      },
+      required: ['fromIndex', 'toIndex', 'selector'],
+    },
+  },
+  {
+    name: 'index_split_preview',
+    description: 'Detect manual-like documents in a general index and preview moving them into an existing troubleshooting-purpose index. Writes nothing. Wraps POST IndexMove/Split/Preview. Use index_split_execute to run it.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromIndex: { type: 'string' },
+        toIndex:   { type: 'string', description: 'Existing troubleshooting-purpose index' },
+        docIds:    { type: 'array', items: { type: 'number' }, description: 'Only these documents (default: every detected manual)' },
+        skipBlocked: { type: 'boolean' },
+      },
+      required: ['fromIndex', 'toIndex'],
+    },
+  },
+  {
+    name: 'index_split_execute',
+    description: 'Run a split: move detected manuals from a general index into an existing troubleshooting-purpose index. Call index_split_preview first. Resumable and undoable via index_move_control. Wraps POST IndexMove/Split/Execute.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromIndex: { type: 'string' },
+        toIndex:   { type: 'string' },
+        docIds:    { type: 'array', items: { type: 'number' } },
+        skipBlocked: { type: 'boolean' },
+      },
+      required: ['fromIndex', 'toIndex'],
+    },
+  },
+  {
+    name: 'index_move_status',
+    description: 'Status of one move (moveId) or the recent moves (omit moveId): status, per-document progress, canResume/canAbort/canUndo. Wraps GET IndexMove/Moves[/{id}].',
+    inputSchema: {
+      type: 'object',
+      properties: { moveId: { type: 'string' } },
+    },
+  },
+  {
+    name: 'index_move_control',
+    description: 'Resume a stopped move, abort a queued/failed move that has not started removing content, or undo a completed move. Wraps POST IndexMove/Moves/{id}/Resume|Abort|Undo.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        moveId: { type: 'string' },
+        action: { type: 'string', enum: ['resume', 'abort', 'undo'] },
+      },
+      required: ['moveId', 'action'],
+    },
+  },
+  {
+    name: 'index_mixed_content',
+    description: 'Check whether a general index holds manual-like documents that belong in a Troubleshooting Assistant index. Read-only. Wraps GET IndexMove/MixedContent.',
+    inputSchema: {
+      type: 'object',
+      properties: { indexName: { type: 'string' } },
+      required: ['indexName'],
+    },
+  },
+  {
+    name: 'index_integrity_check',
+    description: 'Read-only integrity report for a knowledge index: orphan chunks, records without chunks, count mismatches, duplicate records. Wraps GET IndexMove/Integrity.',
+    inputSchema: {
+      type: 'object',
+      properties: { indexName: { type: 'string' } },
+      required: ['indexName'],
+    },
+  },
+  {
+    name: 'index_integrity_repair',
+    description: 'Repair a knowledge index. Additive and idempotent: corrects counts and adopts orphan chunks into tracking rows, never deletes vectors. removeDuplicateRecords also removes duplicate tracking rows. Run index_integrity_check first. Wraps POST IndexMove/Integrity/Repair.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        indexName: { type: 'string' },
+        removeDuplicateRecords: { type: 'boolean' },
+      },
+      required: ['indexName'],
+    },
+  },
   {
     name: 'index_ingest',
     description: 'Trigger ingestion of a scraper job into the knowledge index. Fires in the background; use index_status after ~2 minutes to verify chunks appeared.',
@@ -2331,6 +2463,17 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId'],
     },
   },
+  {
+    name: 'tour_insights',
+    description: 'Moshky setup-tour funnel and feedback (Velaro staff only). Without siteId: per-tour, per-step counts of offered/opened/step_viewed/arrived/stuck/completed/dismissed/load_error over the last N days plus recent scrubbed feedback. With siteId: that one site\'s tour event timeline and feedback. Feedback comments are PII-scrubbed and for staff eyes only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Optional. When set, returns that site\'s tour timeline instead of the cross-site funnel.' },
+        days:   { type: 'number', description: 'Look-back window in days (default 30, max 365)' },
+      },
+    },
+  },
   {
     name: 'support_extend_subscription',
     description: 'Extend a customer site\'s subscription expiration by N days. SuperAdmin only.',
@@ -2935,6 +3078,18 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  {
+    name: 'magento_diagnose',
+    description: 'Run the Magento live-connection diagnostic for a site: config present, access token valid, /rest/V1 reachability, store code/base URL, and ACL scope probes. Calls messaging GET diagnostics/test-magento?siteId=<id>. Read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Site to diagnose (e.g. 1032)' },
+      },
+      required: ['siteId'],
+    },
+  },
+
   // ── CallRail Attribution ──────────────────────────────────────────────────────
   {
     name: 'callrail_get_attributions',
@@ -4583,6 +4738,11 @@ async function handleTool(name, args) {
       return JSON.stringify(result, null, 2);
     }
 
+    case 'site_scraper_usage': {
+      const result = await api('GET', `ScraperJobs/StaffUsage/${encodeURIComponent(args.siteId)}`);
+      return JSON.stringify(result, null, 2);
+    }
+
     case 'apple_health': {
       const h = await messagingGet(`/SupportTools/sites/${args.siteId}/apple/health`);
       return JSON.stringify(h, null, 2);
@@ -5848,6 +6008,53 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    case 'index_move_preview': {
+      const { fromIndex, toIndex, kind, skipBlocked, selector } = args;
+      const r = await messagingPost('/IndexMove/Preview', { fromIndex, toIndex, kind, skipBlocked, selector });
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_move_execute': {
+      const { fromIndex, toIndex, kind, skipBlocked, selector } = args;
+      const r = await messagingPost('/IndexMove/Execute', { fromIndex, toIndex, kind, skipBlocked, selector });
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_split_preview': {
+      const body = { fromIndex: args.fromIndex, toIndex: args.toIndex, docIds: args.docIds, skipBlocked: args.skipBlocked };
+      const r = await messagingPost('/IndexMove/Split/Preview', body);
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_split_execute': {
+      const body = { fromIndex: args.fromIndex, toIndex: args.toIndex, docIds: args.docIds, skipBlocked: args.skipBlocked };
+      const r = await messagingPost('/IndexMove/Split/Execute', body);
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_move_status': {
+      const r = await messagingGet(args.moveId
+        ? `/IndexMove/Moves/${encodeURIComponent(args.moveId)}`
+        : '/IndexMove/Moves?take=25');
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_move_control': {
+      const verb = { resume: 'Resume', abort: 'Abort', undo: 'Undo' }[args.action];
+      if (!verb) throw new Error('action must be resume, abort or undo');
+      const r = await messagingPost(`/IndexMove/Moves/${encodeURIComponent(args.moveId)}/${verb}`);
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_mixed_content': {
+      const r = await messagingGet(`/IndexMove/MixedContent?index=${encodeURIComponent(args.indexName)}`);
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_integrity_check': {
+      const r = await messagingGet(`/IndexMove/Integrity?index=${encodeURIComponent(args.indexName)}`);
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_integrity_repair': {
+      const r = await messagingPost('/IndexMove/Integrity/Repair', {
+        indexName: args.indexName,
+        removeDuplicateRecords: !!args.removeDuplicateRecords,
+      });
+      return JSON.stringify(r, null, 2);
+    }
     case 'index_status': {
       const sources = await api('GET', '/AzureIndexes/IntegrationSources');
       if (!Array.isArray(sources) || !sources.length) return 'No indexed sources found. Run index_ingest to populate.';
@@ -6737,7 +6944,7 @@ async function handleTool(name, args) {
 
     case 'support_user_lookup': {
       const users = await api('GET', `/SupportTools/users/search?q=${encodeURIComponent(args.query)}`);
-      if (!Array.isArray(users) || !users.length) return `No users found matching "${args.query}".`;
+      if (!Array.isArray(users) || !users.length) return `No users found matching "${args.query}" in ${ENV_LABEL}. If this looks like a real customer, re-run with VELARO_ADMIN_API set to the other environment before concluding they don't exist.`;
       return users.map(u => {
         const roles = u.sites?.map(s =>
           `  site ${s.siteId} (${s.companyName}) — ${s.isAdministrator ? 'Admin' : s.isManager ? 'Manager' : 'Agent'}${s.isActive === false ? ' INACTIVE' : ''}`
@@ -6753,7 +6960,7 @@ async function handleTool(name, args) {
 
     case 'support_site_lookup': {
       const sites = await api('GET', `/SupportTools/sites/search?q=${encodeURIComponent(args.query)}`);
-      if (!Array.isArray(sites) || !sites.length) return `No sites found matching "${args.query}".`;
+      if (!Array.isArray(sites) || !sites.length) return `No sites found matching "${args.query}" in ${ENV_LABEL}. If this looks like a real customer, re-run with VELARO_ADMIN_API set to the other environment before concluding they don't exist.`;
       return sites.map(s => {
         const admins = s.admins?.map(a => `  ${a.userName} (${a.firstName} ${a.lastName})`).join('\n') ?? 'none';
         return `[siteId=${s.siteId}] ${s.companyName}${s.isTestSite ? ' [TEST]' : ''}\n  URL: ${s.companyURL ?? '—'} | Created: ${s.dateCreated ? s.dateCreated.slice(0,10) : '—'}\n  Admins:\n${admins}`;
@@ -6850,6 +7057,14 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    case 'tour_insights': {
+      const days = Math.min(365, Math.max(1, args.days ?? 30));
+      const path = args.siteId
+        ? `/SupportTools/sites/${args.siteId}/tour-events?days=${days}`
+        : `/SupportTools/tour-insights?days=${days}`;
+      return JSON.stringify(await api('GET', path), null, 2);
+    }
+
     case 'support_extend_subscription': {
       const res = await api('POST', `/SupportTools/sites/${args.siteId}/extend-subscription`, { days: args.days });
       return res?.success
@@ -7429,6 +7644,12 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    case 'magento_diagnose': {
+      if (!args.siteId) return 'siteId is required.';
+      const r = await api('GET', `/diagnostics/test-magento?siteId=${encodeURIComponent(args.siteId)}`);
+      return JSON.stringify(r, null, 2);
+    }
+
     // ── CallRail Attribution ──────────────────────────────────────────────────
     case 'callrail_get_attributions': {
       const limit = Math.min(100, args.limit ?? 25);