@velaro/mcp-server 0.6.59 → 0.6.61

package/package.json

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

@@ -245,19 +245,73 @@ function mcpFindUnresolved(value) {
     .map(([k]) => k);
 }
 
+// The hosted gateway requires an initialized session (Mcp-Session-Id + MCP-Protocol-Version) on
+// every call after "initialize". Cache one per process and re-initialize when it expires (404).
+let gatewaySession = null;
+async function gatewayInit() {
+  const res = await fetch(`${API_BASE}/mcp`, {
+    method: 'POST',
+    headers: { Authorization: authHeader(), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'velaro-mcp-server', version: '1' } } }),
+  });
+  if (!res.ok) {
+    const text = await res.text().catch(() => '');
+    throw new Error(`Velaro MCP gateway initialize -> ${res.status}: ${text.slice(0, 300)}`);
+  }
+  const sid = res.headers.get('mcp-session-id');
+  if (!sid) throw new Error('Velaro MCP gateway initialize returned no Mcp-Session-Id');
+  gatewaySession = { sid, version: res.headers.get('mcp-protocol-version') || '2025-11-25' };
+  return gatewaySession;
+}
+
+// Tools served by velaro-messaging's admin-tools gateway (McpAdminGatewayController, POST /mcp/v1/admin-tools/call,
+// no session). The admin /mcp gateway only serves kb_* tools, so these used to fail there.
+const MESSAGING_ADMIN_TOOLS = new Set([
+  'workflow_create', 'workflow_list', 'workflow_get', 'workflow_toggle',
+  'bot_create', 'bot_list', 'bot_get', 'bot_update_prompt', 'bot_set_knowledge',
+  'ai_config_attach_index', 'call_pop_settings_get', 'call_pop_settings_set',
+  'agent_list', 'team_list', 'conversation_list', 'conversation_get', 'conversation_search',
+  'contact_search', 'contact_get', 'routing_list', 'routing_get', 'site_info',
+  'ms_bookings_cancel_appointment', 'ms_bookings_check_availability_range', 'ms_bookings_reschedule_appointment',
+  'outlook_calendar_cancel', 'outlook_calendar_get_available_range',
+]);
+
+async function messagingAdminRpc(toolName, args) {
+  if (!MESSAGING_API) throw new Error('VELARO_MESSAGING_API is not configured.');
+  const res = await fetch(`${MESSAGING_API}/mcp/v1/admin-tools/call`, {
+    method: 'POST',
+    headers: { Authorization: authHeader(), 'Content-Type': 'application/json' },
+    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: toolName, arguments: args ?? {} } }),
+    signal: AbortSignal.timeout(30000),
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok || data.error) {
+    throw new Error(`Velaro admin-tools ${toolName} -> ${res.status}: ${data.error?.message || JSON.stringify(data).slice(0, 300)}`);
+  }
+  const content = data.result?.content?.[0]?.text;
+  if (content === undefined) throw new Error('Empty response from admin-tools gateway');
+  return content;
+}
+
 // Call the hosted MCP gateway (JSON-RPC) for tools that are dispatched server-side.
 async function rpc(toolName, args) {
+  if (MESSAGING_ADMIN_TOOLS.has(toolName)) return messagingAdminRpc(toolName, args);
   const body = {
     jsonrpc: '2.0',
     id: 1,
     method: 'tools/call',
     params: { name: toolName, arguments: args ?? {} },
   };
-  const res = await fetch(`${API_BASE}/mcp`, {
-    method: 'POST',
-    headers: { Authorization: authHeader(), 'Content-Type': 'application/json' },
-    body: JSON.stringify(body),
-  });
+  const send = async () => {
+    const s = gatewaySession || await gatewayInit();
+    return fetch(`${API_BASE}/mcp`, {
+      method: 'POST',
+      headers: { Authorization: authHeader(), 'Content-Type': 'application/json', 'Mcp-Session-Id': s.sid, 'MCP-Protocol-Version': s.version },
+      body: JSON.stringify(body),
+    });
+  };
+  let res = await send();
+  if (res.status === 404) { gatewaySession = null; res = await send(); }
   if (!res.ok) {
     const text = await res.text().catch(() => '');
     throw new Error(`Velaro MCP gateway ${toolName} -> ${res.status}: ${text.slice(0, 300)}`);
@@ -2017,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',
@@ -2448,6 +2535,26 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId'],
     },
   },
+  // -- 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.',
@@ -6638,6 +6745,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': {
@@ -7074,6 +7205,13 @@ async function handleTool(name, args) {
       ).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}.`;
@@ -8249,7 +8387,7 @@ async function handleTool(name, args) {
     }
 
     case 'billing_plan_status': {
-      const s = await api('GET', '/BillingPayment/plan-status');
+      const s = await api('GET', '/BillingPayment/plan-status', undefined, MESSAGING_API);
       const lines = [`Site ${s.siteId} — Subscription Status`];
       if (s.subscription) {
         lines.push(`Seats: ${s.subscription.maxLicensedSeats}  |  Conv/mo: ${s.subscription.maxConversationsPerMonth || '∞'}  |  Self-serve: ${s.subscription.enableSelfServeSeats ? 'YES' : 'no'}`);