@velaro/mcp-server 0.6.72 → 0.6.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/mcp-server",
-  "version": "0.6.72",
+  "version": "0.6.74",
   "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": {

package/server.js

@@ -179,6 +179,12 @@ function teamRoutingConfigPath(teamId) {
   return `/RoutingConfig?teamId=${n}`;
 }
 const messagingPatch = (path, body) => messagingRequest('PATCH', path, body);
+function execInsightsRange(days) {
+  const d = Math.min(Math.max(Number(days) || 7, 1), 92);
+  const to = new Date();
+  return new URLSearchParams({ from: new Date(to.getTime() - d * 86400000).toISOString(), to: to.toISOString() });
+}
+
 const messagingDel   = (path)       => messagingRequest('DELETE', path);
 
 async function api(method, path, body, base = API_BASE) {
@@ -2103,6 +2109,33 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['reportType', 'isEnabled'],
     },
   },
+  {
+    name: 'report_subscriptions_list',
+    description: "List the caller's own scheduled report email subscriptions (velaro-messaging /report-subscriptions): id, report type, frequency, active, delivery hour, format (pdf/html), extra recipients.",
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'report_subscription_update',
+    description: "Update one of the caller's report subscriptions by id. Only passed fields change. Extra recipients must be other users on the same account (max 10); pass an empty string to clear.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id:                { type: 'number', description: 'Subscription id from report_subscriptions_list' },
+        frequency:         { type: 'string', enum: ['daily', 'weekly', 'bi-monthly', 'monthly'] },
+        deliveryHour:      { type: 'number', description: 'Site-local hour 0-23 to deliver at or after' },
+        clearDeliveryHour: { type: 'boolean', description: 'Remove the delivery hour (send at the first run)' },
+        format:            { type: 'string', enum: ['pdf', 'html'] },
+        extraRecipients:   { type: 'string', description: 'Comma-separated emails; empty string clears' },
+        isActive:          { type: 'boolean', description: 'false pauses, true resumes' },
+      },
+      required: ['id'],
+    },
+  },
+  {
+    name: 'report_subscription_delete',
+    description: "Delete one of the caller's report subscriptions by id (not by report type).",
+    inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'Subscription id' } }, required: ['id'] },
+  },
   {
     name: 'report_export_status',
     description: 'Check the status of a queued async report export (Reports/ExportStatus/{id}) — pending/processing/completed/failed and the download URL once ready.',
@@ -2774,6 +2807,46 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       properties: { report: { type: 'string', description: 'Report key. Omit to list all.' } },
     },
   },
+  {
+    name: 'friction_radar',
+    description: 'Friction Radar: conversation topics ranked by estimated agent cost (handle time plus a fixed penalty per escalation and abandoned chat), with volume, week-over-week growth versus the prior period of equal length and up to 3 example conversation ids per topic. Demo data excluded. Chat Intelligence entitlement required. Scoped to the caller site.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days:  { type: 'number', description: 'Look-back window in days, 1-92 (default 7).' },
+        limit: { type: 'number', description: 'Max topics, 1-100 (default 20).' },
+      },
+    },
+  },
+  {
+    name: 'executive_brief',
+    description: 'Executive brief for the last N days: conversation volume and growth, sentiment split, average QA rubric score, Experience Impact (index, CSAT, service level, missed chats), fastest rising keywords and top friction topics. Same data as the Monday executive-brief email. Chat Intelligence entitlement required.',
+    inputSchema: {
+      type: 'object',
+      properties: { days: { type: 'number', description: 'Look-back window in days, 1-92 (default 7).' } },
+    },
+  },
+  {
+    name: 'report_data_export',
+    description: 'Export conversations as CSV (sentiment, QA score, tag, escalations, handle seconds, abandoned, keywords) for the last N days; max 20,000 rows. To schedule it by email use executive_insights_subscribe with reportType data-export. Chat Intelligence entitlement required.',
+    inputSchema: {
+      type: 'object',
+      properties: { days: { type: 'number', description: 'Look-back window in days, 1-92 (default 7).' } },
+    },
+  },
+  {
+    name: 'executive_insights_subscribe',
+    description: 'Email the caller the executive-brief (weekly sends on Monday at deliveryHour site time, default 7 = 7:00 AM) or a scheduled data-export CSV. Creates or updates the caller report subscription.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        reportType:   { type: 'string', enum: ['executive-brief', 'data-export'] },
+        frequency:    { type: 'string', enum: ['daily', 'biweekly', 'weekly', 'monthly'], description: 'Default weekly.' },
+        deliveryHour: { type: 'number', description: 'Site-local hour 0-23 (default 7).' },
+      },
+      required: ['reportType'],
+    },
+  },
   {
     name: 'experience_impact_report',
     description: 'Experience Impact report: shows how staffing and schedule adherence affect customer experience. Returns a 0-100 experience index (adherence 25, service level 30, missed-chat rate 20, CSAT 25), per-interval staffing vs chat demand (scheduled vs actual agents, missed chats, wait time, CSAT), per-agent rows, a bot-vs-human breakdown (bot only, bot-to-human handoff, human only, with wait, missed, CSAT and bot containment rate), and plain-language insights. Scoped to the caller site.',
@@ -6901,6 +6974,33 @@ async function handleTool(name, args) {
         : `Failed to save schedule for "${args.reportType}".`;
     }
 
+    case 'report_subscriptions_list': {
+      const rows = await messagingGet('/report-subscriptions');
+      if (!Array.isArray(rows) || !rows.length) return 'No report subscriptions.';
+      return rows.map(x =>
+        `#${x.id} ${x.reportType}: ${x.isActive ? 'active' : 'paused'}, ${x.frequency}, ${x.deliveryHour == null ? 'any hour' : String(x.deliveryHour).padStart(2, '0') + ':00'}, ${x.format ?? 'pdf'}${x.extraRecipients ? ' | also to ' + x.extraRecipients : ''}`
+      ).join('\n');
+    }
+
+    case 'report_subscription_update': {
+      if (!Number.isInteger(args.id)) return 'Error: id is required.';
+      const body = {};
+      for (const k of ['frequency', 'format', 'extraRecipients', 'isActive', 'clearDeliveryHour']) if (args[k] !== undefined) body[k] = args[k];
+      if (args.deliveryHour !== undefined) {
+        if (!Number.isInteger(args.deliveryHour) || args.deliveryHour < 0 || args.deliveryHour > 23) return 'Error: deliveryHour must be an integer 0-23.';
+        body.deliveryHour = args.deliveryHour;
+      }
+      if (!Object.keys(body).length) return 'Error: pass at least one field to update.';
+      await messagingRequest('PUT', `/report-subscriptions/${args.id}`, body);
+      return `Subscription #${args.id} updated.`;
+    }
+
+    case 'report_subscription_delete': {
+      if (!Number.isInteger(args.id)) return 'Error: id is required.';
+      await messagingRequest('DELETE', `/report-subscriptions/${args.id}`);
+      return `Subscription #${args.id} deleted.`;
+    }
+
     case 'report_export_status': {
       if (!args.exportId) return 'Error: exportId is required.';
       const s = await api('GET', `/Reports/ExportStatus/${args.exportId}`);
@@ -7843,6 +7943,39 @@ async function handleTool(name, args) {
       return [`=== ${r.name} ===`, `Answers: ${r.answers}`, `Sources: ${r.sources}`, `Setup: ${r.prerequisites}`, `How to read: ${r.interpret}`, `Why zero/empty: ${r.whyZero}`, `What to do: ${r.fix}`, `Related: ${r.related}`].join('\n');
     }
 
+    case 'friction_radar': {
+      const qs = execInsightsRange(args.days);
+      qs.set('limit', String(Math.min(Math.max(Number(args.limit) || 20, 1), 100)));
+      const r = await messagingGet(`/executive-insights/friction-radar?${qs}`);
+      const lines = [`=== Friction Radar (${r.conversationsScanned} conversations${r.truncated ? ', truncated' : ''}) ===`];
+      for (const t of r.topics ?? []) {
+        const growth = t.isNew ? 'new' : t.growthPct == null ? 'n/a' : `${t.growthPct}%`;
+        lines.push(`#${t.costRank} ${t.topic}: ${t.volume} chats (volume rank ${t.volumeRank}, ${growth}), ${t.escalations} escalated, ${t.abandoned} abandoned, ~${Math.round(t.estimatedCostMinutes)} agent min, examples ${(t.exampleConversationIds ?? []).join(', ') || '-'}`);
+      }
+      if (!(r.topics ?? []).length) lines.push('No tagged topics in this period.');
+      return lines.join('\n');
+    }
+
+    case 'executive_brief': {
+      const r = await messagingGet(`/executive-insights/brief?${execInsightsRange(args.days)}`);
+      return JSON.stringify(r.brief, null, 2);
+    }
+
+    case 'report_data_export': {
+      const r = await messagingGet(`/executive-insights/export?${execInsightsRange(args.days)}`);
+      return `${r.rows} rows${r.truncated ? ' (truncated at the row cap)' : ''}\n${r.csv}`;
+    }
+
+    case 'executive_insights_subscribe': {
+      if (!['executive-brief', 'data-export'].includes(args.reportType)) return 'Error: reportType must be executive-brief or data-export.';
+      await messagingPost('/report-subscriptions', {
+        reportType: args.reportType,
+        frequency: args.frequency ?? 'weekly',
+        deliveryHour: args.deliveryHour ?? 7,
+      });
+      return `Subscribed to ${args.reportType} (${args.frequency ?? 'weekly'}, ${args.deliveryHour ?? 7}:00 site time).`;
+    }
+
     case 'experience_impact_report': {
       const qs = new URLSearchParams();
       for (const k of ['from', 'to', 'teamId']) if (args[k] != null && args[k] !== '') qs.set(k, String(args[k]));