@velaro/mcp-server 0.6.60 → 0.6.62

package/package.json

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

@@ -2071,6 +2071,39 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  // -- Email delivery visibility (Velaro staff only; velaro-messaging SuperAdmin) --
+  {
+    name: 'email_queue_status',
+    description: 'Velaro staff only. Live ACS email send-queue health: queued/parked counts, oldest open item age, cooldown state, retries, 429s, sends in the last hour and a drain-time estimate. Aggregates only, no message bodies. Wraps GET SuperAdmin/email-delivery/status on velaro-messaging.',
+    inputSchema: {
+      type: 'object',
+      properties: { siteId: { type: 'number', description: 'Optional: limit to one site ID' } },
+      required: [],
+    },
+  },
+  {
+    name: 'email_delivery_stats',
+    description: 'Velaro staff only. Email throughput per day and per hour, retry counts, priority/tag breakdown, attempts histogram, and ACS-side delivery outcomes (succeeded/failed/pending). Wraps GET SuperAdmin/email-delivery/stats on velaro-messaging.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Optional: limit to one site ID' },
+        days: { type: 'number', description: 'Daily window, 1-30 (default 30; ACS-side capped at 14)' },
+        hours: { type: 'number', description: 'Hourly window, 1-168 (default 48)' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'email_queue_replay',
+    description: 'Velaro staff ADMIN ONLY. Replays the queued ACS email backlog now. dryRun defaults to TRUE and only reports what a replay would send; pass dryRun=false to clear the cooldown and drain the queue immediately. Wraps POST SuperAdmin/email-delivery/replay on velaro-messaging.',
+    inputSchema: {
+      type: 'object',
+      properties: { dryRun: { type: 'boolean', description: 'Default true. Set false to actually replay.' } },
+      required: [],
+    },
+  },
+
   // ── Unified Outbound Activity (Klaviyo-parity Gap 6) ──────────────────────
   {
     name: 'outbound_activity_list',
@@ -2502,6 +2535,38 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId'],
     },
   },
+  {
+    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, and plain-language insights. Scoped to the caller site.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from:   { type: 'string', description: 'yyyy-MM-dd start (default: 7 days ago).' },
+        to:     { type: 'string', description: 'yyyy-MM-dd end (default: today).' },
+        teamId: { type: 'number', description: 'Optional team ID to narrow the report.' },
+      },
+    },
+  },
+  // -- Staff: schedule adherence by site + role (SupportTools-style: explicit siteId, never auth-derived) --
+  // Backend: velaro-messaging ReportsController.ScheduleAdherenceDiagnosticsAsync, gated by
+  // IsSuperAdminAsync(allowSupport: true) -> 403 for non-staff. role=agent REQUIRES agentId (fails closed).
+  {
+    name: 'support_schedule_adherence',
+    description: 'Velaro staff only. Schedule-adherence overview (totals + per-agent metrics), per-day breakdown (incl. nonAvailableMinutes), current status (intraday) and range-end-day timeline for a site, scoped as a manager (all agents) or as one agent (own row only) -- the exact scope the customer UI applies. Use for schedule-adherence QA instead of a browser pass.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId:  { type: 'number', description: 'Target customer site ID' },
+        role:    { type: 'string', enum: ['manager', 'agent'], description: 'Scope to apply. Default manager.' },
+        agentId: { type: 'number', description: 'WorkspaceUser id; required when role=agent.' },
+        start:   { type: 'string', description: 'yyyy-MM-dd (default: 6 days ago, site tz).' },
+        end:     { type: 'string', description: 'yyyy-MM-dd (default: today, site tz).' },
+        tz:      { type: 'string', description: 'IANA time zone override.' },
+      },
+      required: ['siteId'],
+    },
+  },
+
   {
     name: 'support_site_agents',
     description: 'List all agents/admins on a customer site with their roles, active status, and last login date. Velaro staff only.',
@@ -6692,6 +6757,30 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    // -- Email delivery visibility (Velaro staff only) --
+    case 'email_queue_status': {
+      const q = args.siteId != null ? `?siteId=${encodeURIComponent(args.siteId)}` : '';
+      const r = await messagingGet(`/SuperAdmin/email-delivery/status${q}`);
+      return JSON.stringify(r, null, 2);
+    }
+
+    case 'email_delivery_stats': {
+      const params = new URLSearchParams();
+      if (args.siteId != null) params.set('siteId', String(args.siteId));
+      if (args.days != null) params.set('days', String(args.days));
+      if (args.hours != null) params.set('hours', String(args.hours));
+      const qs = params.toString();
+      const r = await messagingGet(`/SuperAdmin/email-delivery/stats${qs ? '?' + qs : ''}`);
+      return JSON.stringify(r, null, 2);
+    }
+
+    case 'email_queue_replay': {
+      // Safe by default: anything other than an explicit boolean false stays a dry run.
+      const dryRun = args.dryRun !== false;
+      const r = await messagingPost(`/SuperAdmin/email-delivery/replay?dryRun=${dryRun}`);
+      return JSON.stringify(r, null, 2);
+    }
+
     // ── Unified Outbound Activity ──────────────────────────────────────────
     case 'outbound_activity_list':
     case 'outbound_activity_for_contact': {
@@ -7128,6 +7217,29 @@ async function handleTool(name, args) {
       ).join('\n');
     }
 
+    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]));
+      const r = await messagingGet(`/Reports/experience-impact${qs.toString() ? '?' + qs : ''}`);
+      const sm = r.summary ?? {};
+      const lines = [
+        `=== Experience Impact ${r.range?.from ?? ''}..${r.range?.to ?? ''} ===`,
+        `Experience index: ${sm.experienceIndex ?? '-'} / 100`,
+        `Adherence ${sm.adherencePct ?? '-'}% | Service level ${sm.serviceLevelPct ?? '-'}% | Missed chats ${sm.missedChats ?? '-'} | Avg wait ${sm.avgWaitSec ?? '-'}s | CSAT ${sm.csatAvg ?? '-'} (${sm.csatResponses ?? 0} responses)`,
+        ...(r.insights ?? []).map(i => `  [${i.severity}] ${i.text}`),
+        `Intervals: ${(r.intervals ?? []).length} | Agents: ${(r.agents ?? []).length}`,
+      ];
+      for (const a of r.agents ?? []) lines.push(`  ${a.name}: index ${a.experienceIndex} | adherence ${a.adherencePct}% | CSAT ${a.csatAvg ?? '-'} | handled ${a.handled}`);
+      return lines.join('\n');
+    }
+
+    case 'support_schedule_adherence': {
+      if (args.role === 'agent' && !args.agentId) throw new Error('agentId is required when role=agent');
+      const qs = new URLSearchParams({ detail: 'true' });
+      for (const k of ['role', 'agentId', 'start', 'end', 'tz']) if (args[k] != null && args[k] !== '') qs.set(k, String(args[k]));
+      return JSON.stringify(await messagingGet(`/Reports/sites/${encodeURIComponent(args.siteId)}/schedule-adherence-diagnostics?${qs}`), null, 2);
+    }
+
     case 'support_site_agents': {
       const agents = await api('GET', `/SupportTools/sites/${args.siteId}/agents`);
       if (!Array.isArray(agents) || !agents.length) return `No agents found for site ${args.siteId}.`;