@velaro/mcp-server 0.6.69 → 0.6.71

package/README.md

@@ -167,6 +167,7 @@ This works with any MCP client that supports HTTP/SSE transport — including Cl
 |------|-------------|
 | `report_roi_summary` | Full ROI report — bot deflections, hours saved, cost savings, AI skill executions, resolution rate, response time, trends vs prior period, monthly breakdown, top skills by call count, channel breakdown |
 | `report_agent_utilization` | Per-agent stats — conversation count, avg handle time, active/away breakdown for any date range |
+| `report_visitor_traffic_overview` | Visitor Traffic report (velaro-messaging) — daily visit trend, top countries and chat-channel breakdown for any date range |
 | `report_campaign_performance` | Email campaign KPIs — open rate, click rate, delivery rate, complaint rate per campaign + aggregate totals |
 | `report_campaign_deliverability` | Deliverability health check — bounce rate, complaint rate, unsubscribe rate, open rate with traffic-light status and fix recommendations |
 | `report_campaign_monthly` | Month-by-month email volume for the last 12 months |

package/package.json

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

@@ -119,12 +119,18 @@ function parseDuration(s) {
   return n * 24 * 3600 * 1000;
 }
 
-async function messagingApi(path) {
+async function messagingApi(path, opts = {}) {
   if (!MESSAGING_API) throw new Error(
     'VELARO_MESSAGING_API is not configured. Add "VELARO_MESSAGING_API": "https://velaro-messaging-api-staging.azurewebsites.net" to your MCP env config.'
   );
   const res = await fetch(`${MESSAGING_API}${path}`, {
-    headers: { Authorization: authHeader(), 'X-Internal-SiteId': '1032' },
+    method: opts.method ?? 'GET',
+    headers: {
+      Authorization: authHeader(),
+      'X-Internal-SiteId': '1032',
+      ...(opts.body ? { 'Content-Type': 'application/json' } : {}),
+    },
+    body: opts.body ? JSON.stringify(opts.body) : undefined,
     signal: AbortSignal.timeout(20000),
   });
   if (!res.ok) {
@@ -525,9 +531,59 @@ const TOOLS = [
       required: ['id', 'title', 'slug', 'topicId', 'content'],
     },
   },
+  {
+    name: 'kb_list_deleted_articles',
+    description: 'List recently deleted KB articles (restorable for 30 days).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'kb_restore_article',
+    description: 'Restore a deleted KB article (and re-index it).',
+    inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'Article ID' } }, required: ['id'] },
+  },
+  {
+    name: 'kb_list_deleted_topics',
+    description: 'List recently deleted KB topics (restorable for 30 days).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'kb_restore_topic',
+    description: 'Restore a deleted KB topic.',
+    inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'Topic ID' } }, required: ['id'] },
+  },
+  {
+    name: 'contactlist_list_deleted',
+    description: 'List recently deleted contact lists (restorable for 30 days).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'contactlist_restore',
+    description: 'Restore a deleted contact list with its members.',
+    inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'List ID' } }, required: ['id'] },
+  },
+  {
+    name: 'contactsegment_list_deleted',
+    description: 'List recently deleted contact segments (restorable for 30 days).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'contactsegment_restore',
+    description: 'Restore a deleted contact segment.',
+    inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'Segment ID' } }, required: ['id'] },
+  },
+  {
+    name: 'contactlist_member_list_deleted',
+    description: 'List members recently removed from a contact list (restorable for 30 days).',
+    inputSchema: { type: 'object', properties: { listId: { type: 'number' } }, required: ['listId'] },
+  },
+  {
+    name: 'contactlist_member_restore',
+    description: 'Restore a member removed from a contact list.',
+    inputSchema: { type: 'object', properties: { listId: { type: 'number' }, memberId: { type: 'number' } }, required: ['listId', 'memberId'] },
+  },
   {
     name: 'kb_delete_article',
-    description: 'Delete a KB article. Irreversible — confirm with the user before calling.',
+    description: 'Delete a KB article (soft delete: restorable for 30 days via kb_restore_article, then purged).',
     inputSchema: {
       type: 'object',
       properties: { id: { type: 'number', description: 'Article ID to delete' } },
@@ -2017,6 +2073,17 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       },
     },
   },
+  {
+    name: 'report_visitor_traffic_overview',
+    description: 'Visitor Traffic report (velaro-messaging) — daily visit trend, top countries and chat-channel breakdown over a date range. Site is resolved server-side from the service key/JWT, never a client-supplied value. Lives in velaro-messaging — requires VELARO_MESSAGING_API.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        startDate: { type: 'string', description: 'ISO 8601 start date, e.g. 2026-01-01 (default: 30 days ago)' },
+        endDate:   { type: 'string', description: 'ISO 8601 end date, e.g. 2026-04-19 (default: now)' },
+      },
+    },
+  },
   {
     name: 'report_schedules_get',
     description: 'List the recurring report email schedules configured for this site (Reports/Schedules) — report type, frequency, recipients, enabled state.',
@@ -2197,6 +2264,37 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  // ── Klaviyo migration ─────────────────────────────────────────────────────
+  {
+    name: 'klaviyo_migration_run',
+    description: 'Import the customer\'s Klaviyo lists, segments and flows into Velaro (uses the key stored by the Klaviyo integration). SAFE BY DEFAULT: dryRun defaults to true and writes nothing; pass dryRun=false only after reviewing the preview. Idempotent. Only SUBSCRIBED profiles are imported; flows arrive inactive.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        dryRun: { type: 'boolean', description: 'Default true. false = apply the import.' },
+        listIds: { type: 'array', items: { type: 'string' }, description: 'Klaviyo list ids (omit for all)' },
+        segmentIds: { type: 'array', items: { type: 'string' }, description: 'Klaviyo segment ids (omit for all)' },
+        flowIds: { type: 'array', items: { type: 'string' }, description: 'Klaviyo flow ids (omit for all)' },
+        includeFlows: { type: 'boolean', description: 'Default true' },
+        maxProfilesPerGroup: { type: 'number', description: 'Cap per list/segment (default 5000)' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'klaviyo_savings_calculator',
+    description: 'Compare a Klaviyo monthly bill to a Velaro plan\'s catalog price. Velaro price comes only from the pricing catalog. Both profiles and klaviyoMonthlyBill are REQUIRED.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        profiles: { type: 'number', description: 'Klaviyo profile count' },
+        klaviyoMonthlyBill: { type: 'number', description: 'Current Klaviyo monthly bill in USD' },
+        planKey: { type: 'string', description: 'Velaro plan key, default plan.professional' },
+      },
+      required: ['profiles', 'klaviyoMonthlyBill'],
+    },
+  },
+
   // ── Conversion tracking tools ─────────────────────────────────────────────
   {
     name: 'conversion_list_goals',
@@ -2329,6 +2427,34 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  {
+    name: 'ai_model_set_site_thinking',
+    description: 'Set the extended-thinking level for a site (off | low | medium | high), optionally scoped to one role. Staff only. Thinking bills as output tokens, is off by default, and only takes effect when the site holds the EnableAiThinking entitlement. Opus 5.5 always thinks at model-default effort regardless.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Site ID' },
+        effort: { type: 'string', enum: ['off', 'low', 'medium', 'high'], description: 'Thinking level' },
+        role: { type: 'string', description: 'Optional role to scope the setting to (e.g. chatbot). Omit for the site-wide value.' },
+      },
+      required: ['siteId', 'effort'],
+    },
+  },
+  {
+    name: 'ai_model_set_site_pin',
+    description: 'Set a per-site role model override and choose whether to pin its exact version (pinVersion=true keeps a still-callable legacy model like claude-opus-5 instead of auto-upgrading to the latest). Staff only. Non-pinnable ids ignore the pin.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Site ID' },
+        role: { type: 'string', description: 'Role (e.g. chatbot, ivr, skill_synthesis)' },
+        model: { type: 'string', description: 'Model id/alias to set for this role' },
+        pinVersion: { type: 'boolean', description: 'true = keep this exact model, do not auto-upgrade' },
+      },
+      required: ['siteId', 'role', 'model', 'pinVersion'],
+    },
+  },
+
   // ── Page Widgets ──────────────────────────────────────────────────────────
   {
     name: 'page_widget_list',
@@ -2491,6 +2617,22 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
 
   // ── Support Tools (Velaro staff only) ────────────────────────────────────────
+  {
+    name: 'support_add_site_user',
+    description: 'Velaro staff only. Create or ensure a NORMAL user (role agent or administrator, never staff/superadmin) on ANY customer site with an explicit non-forcing password, usable immediately. Idempotent: an existing user just gets the password set. Password goes in the HTTPS body only and is never logged or returned. Composes velaro-messaging SuperAdmin users create + set-password (same staff-WorkspaceUser auth caveat as site_provision: an MCP-key-only session may 403; use `velaro support add-site-user` then).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId:    { type: 'number', description: 'Target customer site ID' },
+        email:     { type: 'string' },
+        password:  { type: 'string', description: 'Min 8 characters' },
+        role:      { type: 'string', enum: ['agent', 'administrator'], description: 'Default agent' },
+        firstName: { type: 'string' },
+        lastName:  { type: 'string' },
+      },
+      required: ['siteId', 'email', 'password'],
+    },
+  },
   {
     name: 'support_agent_lookup',
     description: 'Resolve a bare messaging WorkspaceUser.Id (AgentId, e.g. from an AgentPresenceFlapping WARN or AgentConnectionLog entry that carries no SiteId) to its Email/DisplayName/SiteId across ALL sites. Read-only, Velaro staff only. Different ID space from support_user_lookup (which searches ApplicationUsers/login identity, not the per-agent messaging record).',
@@ -2578,6 +2720,34 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId'],
     },
   },
+  {
+    name: 'support_connection_timeline',
+    description: 'Raw ordered connection events (connected, disconnected, reconnecting) for ONE agent at a site over a time window, from velaro-messaging AgentConnectionLogs. Velaro staff only, read-only. Defaults to the last 24 hours.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId:          { type: 'number', description: 'Target site ID' },
+        workspaceUserId: { type: 'number', description: 'WorkspaceUser.Id of the agent (see support_site_agents)' },
+        from:            { type: 'string', description: 'ISO start (default: 24h before "to")' },
+        to:              { type: 'string', description: 'ISO end (default: now)' },
+        limit:           { type: 'number', description: 'Max events, 1-5000 (default 2000)' },
+      },
+      required: ['siteId', 'workspaceUserId'],
+    },
+  },
+  {
+    name: 'support_connection_evidence',
+    description: 'Dispute-grade connection evidence for a site and window: Velaro independent probe uptime %, incidents (including ones excluded from uptime, with the reason), per-agent disconnect counts, and client-vs-server reconciliation (disconnects with no unhealthy Velaro probe within 5 minutes are client/network side). Velaro staff only, read-only. Defaults to the last 30 days.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Target site ID' },
+        from:   { type: 'string', description: 'ISO start (default: 30 days before "to")' },
+        to:     { type: 'string', description: 'ISO end (default: now)' },
+      },
+      required: ['siteId'],
+    },
+  },
   {
     name: 'support_site_health',
     description: 'Get a full health snapshot for a customer site: subscription status/expiry, active agent count, last login, 7-day activity count, and integration error count. Velaro staff only.',
@@ -2596,6 +2766,14 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId'],
     },
   },
+  {
+    name: 'report_explain',
+    description: 'How to use and interpret a Velaro report: what it answers, data sources, setup prerequisites, how to read the numbers, why a value could be zero or empty, what to do, and related reports. Pass a report key (e.g. experience-impact, missed, surveys, schedule-adherence) or omit to list all keys. Static guidance, no site data.',
+    inputSchema: {
+      type: 'object',
+      properties: { report: { type: 'string', description: 'Report key. Omit to list all.' } },
+    },
+  },
   {
     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.',
@@ -2638,6 +2816,30 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId'],
     },
   },
+  {
+    name: 'support_create_agent',
+    description: 'Provision a new licensed agent/admin (Entra/V20 WorkspaceUser) on an EXISTING site. ' +
+      'Velaro staff only. Closes a real gap: site-provision only creates brand-new sites (rejects an ' +
+      'ExplicitSiteId that already exists), and the ordinary Users/List create endpoint requires an ' +
+      'existing site admin to call it -- impossible on a zero-agent site (a fresh review/demo site, or ' +
+      'any site whose only admin left). Enforces the site\'s license/seat cap same as the ordinary ' +
+      'create-user flow. "Velaro Admin"/"Velaro Support" roles are always stripped server-side -- this ' +
+      'tool provisions customer/site agents, never internal staff privilege escalation. Entra/V20 sites ' +
+      'only (does not cover a site still on the legacy V10 identity model).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId:    { type: 'number', description: 'Target site ID (must already exist)' },
+        email:     { type: 'string', description: 'New agent email' },
+        firstName: { type: 'string', description: 'First name' },
+        lastName:  { type: 'string', description: 'Last name' },
+        roles:     { type: 'array', items: { type: 'string' }, description: 'Roles to grant (default: ["Administrator"])' },
+        teamIds:   { type: 'array', items: { type: 'number' }, description: 'Team IDs on the target site (default: the site\'s first team)' },
+        maxChats:  { type: 'number', description: 'Concurrent chat capacity (default: site ceiling)' },
+      },
+      required: ['siteId', 'email'],
+    },
+  },
   {
     name: 'support_site_activity',
     description: 'Get recent activity log entries for a customer site — who did what and when (workflows, logins, settings changes, etc.). Velaro staff only.',
@@ -4649,6 +4851,37 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['ruleId'],
     },
   },
+  {
+    name: 'booking_list_appointments',
+    description: 'List actual bookings (Phase 1c) made against the booking engine for this site, optionally filtered by date range or service.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromUtc:           { type: 'string', description: 'Only bookings starting at or after this ISO 8601 UTC timestamp' },
+        toUtc:             { type: 'string', description: 'Only bookings starting at or before this ISO 8601 UTC timestamp' },
+        bookableServiceId: { type: 'number', description: 'Only bookings for this bookable service id' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'booking_get_appointment',
+    description: 'Get a single booking (Phase 1c) by id.',
+    inputSchema: {
+      type: 'object',
+      properties: { bookingId: { type: 'number', description: 'Booking ID. Required.' } },
+      required: ['bookingId'],
+    },
+  },
+  {
+    name: 'booking_cancel_appointment',
+    description: 'Cancel a booking (Phase 1c), staff-initiated. Releases the held slot capacity.',
+    inputSchema: {
+      type: 'object',
+      properties: { bookingId: { type: 'number', description: 'Booking ID. Required.' } },
+      required: ['bookingId'],
+    },
+  },
 
   // Focus Inbox -- draft pregeneration usage/cap report ("Always Learning" addon,
   // issue #582 Phase D). Entitlements-gated (EnableFocusDraftPregeneration), not a
@@ -4996,6 +5229,61 @@ async function handleTool(name, args) {
       return `Updated KB settings. ${JSON.stringify(args)}`;
     }
 
+    case 'kb_list_deleted_articles': {
+      const rows = await api('GET', `/api/kb/articles/deleted`);
+      if (!Array.isArray(rows) || !rows.length) return 'Nothing in Recently deleted.';
+      return rows.map(r => `#${r.id} ${r.name} (deleted ${r.deletedAt}, purges in ${r.daysUntilPurge} day(s))`).join('\n');
+    }
+
+    case 'kb_restore_article': {
+      await api('POST', `/api/kb/articles/${args.id}/restore`);
+      return `Restored #${args.id}.`;
+    }
+
+    case 'kb_list_deleted_topics': {
+      const rows = await api('GET', `/api/kb/topics/deleted`);
+      if (!Array.isArray(rows) || !rows.length) return 'Nothing in Recently deleted.';
+      return rows.map(r => `#${r.id} ${r.name} (deleted ${r.deletedAt}, purges in ${r.daysUntilPurge} day(s))`).join('\n');
+    }
+
+    case 'kb_restore_topic': {
+      await api('POST', `/api/kb/topics/${args.id}/restore`);
+      return `Restored #${args.id}.`;
+    }
+
+    case 'contactlist_list_deleted': {
+      const rows = await api('GET', `/ContactLists/deleted`);
+      if (!Array.isArray(rows) || !rows.length) return 'Nothing in Recently deleted.';
+      return rows.map(r => `#${r.id} ${r.name} (deleted ${r.deletedAt}, purges in ${r.daysUntilPurge} day(s))`).join('\n');
+    }
+
+    case 'contactlist_restore': {
+      await api('POST', `/ContactLists/${args.id}/restore`);
+      return `Restored #${args.id}.`;
+    }
+
+    case 'contactsegment_list_deleted': {
+      const rows = await api('GET', `/ContactSegments/deleted`);
+      if (!Array.isArray(rows) || !rows.length) return 'Nothing in Recently deleted.';
+      return rows.map(r => `#${r.id} ${r.name} (deleted ${r.deletedAt}, purges in ${r.daysUntilPurge} day(s))`).join('\n');
+    }
+
+    case 'contactsegment_restore': {
+      await api('POST', `/ContactSegments/${args.id}/restore`);
+      return `Restored #${args.id}.`;
+    }
+
+    case 'contactlist_member_list_deleted': {
+      const rows = await api('GET', `/ContactLists/${args.listId}/Members/deleted`);
+      if (!Array.isArray(rows) || !rows.length) return 'Nothing in Recently deleted.';
+      return rows.map(r => `#${r.id} ${r.name} (purges in ${r.daysUntilPurge} day(s))`).join('\n');
+    }
+
+    case 'contactlist_member_restore': {
+      await api('POST', `/ContactLists/${args.listId}/Members/${args.memberId}/restore`);
+      return `Restored member #${args.memberId}.`;
+    }
+
     case 'kb_delete_article': {
       await api('DELETE', `/api/kb/articles?id=${args.id}`);
       return `Article ${args.id} deleted.`;
@@ -5057,6 +5345,18 @@ async function handleTool(name, args) {
       return JSON.stringify(h, null, 2);
     }
 
+    case 'support_create_agent': {
+      const r = await messagingPost(`/SupportTools/sites/${args.siteId}/agents`, {
+        email: args.email,
+        firstName: args.firstName,
+        lastName: args.lastName,
+        roles: args.roles,
+        teamIds: args.teamIds,
+        maxChats: args.maxChats ?? 0,
+      });
+      return JSON.stringify(r, null, 2);
+    }
+
     case 'apple_test_control': {
       const r = await messagingPost(`/SupportTools/sites/${args.siteId}/apple/test-control`, {
         control: args.control,
@@ -6534,6 +6834,31 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    case 'report_visitor_traffic_overview': {
+      const end = args.endDate ? new Date(args.endDate) : new Date();
+      const start = args.startDate ? new Date(args.startDate) : new Date(end.getTime() - 30 * 24 * 3600 * 1000);
+      const r = await messagingPost('/reports/visitor-traffic-overview', {
+        start: start.toISOString(),
+        end: end.toISOString(),
+      });
+      const k = r?.kpis ?? {};
+      const lines = [
+        `=== Visitor Traffic (${r?.start ?? start.toISOString().slice(0, 10)} – ${r?.end ?? end.toISOString().slice(0, 10)}) ===`,
+        `Total Visits: ${k.totalVisits ?? 0}  |  Avg Daily: ${k.avgDailyVisits ?? 0}  |  Countries Reached: ${k.countriesReached ?? 0}  |  Chats Started: ${k.chatsStarted ?? 0}`,
+        '',
+        '--- Top Countries ---',
+        ...(Array.isArray(r?.countryBreakdown) && r.countryBreakdown.length
+          ? r.countryBreakdown.map((c) => `  ${c.country}: ${c.count}`)
+          : ['  (no data)']),
+        '',
+        '--- By Channel ---',
+        ...(Array.isArray(r?.channelBreakdown) && r.channelBreakdown.length
+          ? r.channelBreakdown.map((c) => `  ${c.name}: ${c.count} (${c.pct}%)`)
+          : ['  (no data)']),
+      ];
+      return lines.join('\n');
+    }
+
     case 'report_schedules_get': {
       const rows = await api('GET', '/Reports/Schedules');
       if (!Array.isArray(rows) || !rows.length) return 'No scheduled reports configured for this site.';
@@ -6973,6 +7298,25 @@ async function handleTool(name, args) {
       return JSON.stringify(r, null, 2);
     }
 
+    // ── Klaviyo migration ──────────────────────────────────────────────────
+    case 'klaviyo_migration_run': {
+      // Anything other than an explicit boolean false stays a dry run.
+      const dryRun = args.dryRun !== false;
+      const r = await api('POST', `/KlaviyoMigration/${dryRun ? 'Preview' : 'Apply'}`, {
+        listIds: args.listIds, segmentIds: args.segmentIds, flowIds: args.flowIds,
+        includeFlows: args.includeFlows, maxProfilesPerGroup: args.maxProfilesPerGroup,
+      });
+      return JSON.stringify(r, null, 2);
+    }
+
+    case 'klaviyo_savings_calculator': {
+      if (args.profiles == null || args.klaviyoMonthlyBill == null) return 'Error: profiles and klaviyoMonthlyBill are required';
+      const p = new URLSearchParams({ profiles: String(args.profiles), klaviyoMonthlyBill: String(args.klaviyoMonthlyBill) });
+      if (args.planKey) p.set('planKey', args.planKey);
+      const r = await api('GET', `/KlaviyoMigration/SavingsCalculator?${p}`);
+      return JSON.stringify(r, null, 2);
+    }
+
     // ── Unified Outbound Activity ──────────────────────────────────────────
     case 'outbound_activity_list':
     case 'outbound_activity_for_contact': {
@@ -7179,6 +7523,22 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    case 'ai_model_set_site_thinking': {
+      const data = await messagingApi(`/superadmin/ai-models/site/${Number(args.siteId)}/thinking`, {
+        method: 'POST',
+        body: { effort: args.effort, ...(args.role ? { role: args.role } : {}) },
+      });
+      return `Site ${data.siteId}: ${data.key} = ${data.effort}. (Only active if the site holds the EnableAiThinking entitlement.)`;
+    }
+
+    case 'ai_model_set_site_pin': {
+      const data = await messagingApi(`/superadmin/ai-models/site/${Number(args.siteId)}`, {
+        method: 'POST',
+        body: { role: args.role, model: args.model, pinVersion: args.pinVersion === true, updatedBy: 'velaro-mcp' },
+      });
+      return `Site ${data.siteId} role ${data.role}: model ${data.model}, pinVersion=${data.pinVersion}`;
+    }
+
     // ── Page Widgets ──────────────────────────────────────────────────────
     case 'page_widget_list': {
       const data = await api('GET', '/PageWidgets');
@@ -7314,6 +7674,28 @@ async function handleTool(name, args) {
     }
 
     // ── Support Tools ─────────────────────────────────────────────────────────
+    case 'support_add_site_user': {
+      const roleMap = { agent: 'Agent', administrator: 'Administrator' };
+      const role = String(args.role || 'agent').toLowerCase();
+      if (!roleMap[role]) throw new Error('role must be agent or administrator.');
+      const email = String(args.email || '').trim().toLowerCase();
+      if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) throw new Error('A valid email is required.');
+      if (typeof args.password !== 'string' || args.password.length < 8) throw new Error('password is required (min 8 characters).');
+      const listed = await messagingGet(`/SuperAdmin/users/${args.siteId}`);
+      const users = Array.isArray(listed) ? listed : (listed?.users || []);
+      let u = users.find(x => String(x.email || '').toLowerCase() === email);
+      let created = false;
+      if (!u) {
+        const c = await messagingPost(`/SuperAdmin/users/${args.siteId}`, { email, firstName: args.firstName || '', lastName: args.lastName || '', roles: [roleMap[role]], sendEmail: false });
+        if (!c?.success) throw new Error(`Create failed: ${c?.error || c?.message || 'unknown error'}`);
+        u = { id: c.user.id ?? c.user.Id };
+        created = true;
+      }
+      const sp = await messagingPost(`/SuperAdmin/users/${args.siteId}/${u.id}/set-password`, { newPassword: args.password });
+      if (sp && sp.success === false) throw new Error(`set-password failed: ${sp.error || 'unknown error'}`);
+      return JSON.stringify({ success: true, siteId: args.siteId, userId: u.id, email, created, passwordSet: true });
+    }
+
     case 'support_agent_lookup': {
       if (!args.id) return 'id is required (WorkspaceUser.Id / AgentId).';
       const res = await messagingApi(`/SuperAdmin/agents/${args.id}/lookup`);
@@ -7383,6 +7765,29 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    case 'support_connection_timeline': {
+      if (!args.siteId || !args.workspaceUserId) return 'siteId and workspaceUserId are required.';
+      const q = new URLSearchParams();
+      if (args.from) q.set('from', args.from);
+      if (args.to) q.set('to', args.to);
+      if (args.limit) q.set('limit', String(args.limit));
+      const qs = q.toString() ? `?${q}` : '';
+      const res = await messagingApi(`/SupportTools/sites/${args.siteId}/agents/${args.workspaceUserId}/connection-timeline${qs}`);
+      if (res?.error) return `Error: ${res.error}`;
+      return JSON.stringify(res, null, 2);
+    }
+
+    case 'support_connection_evidence': {
+      if (!args.siteId) return 'siteId is required.';
+      const q = new URLSearchParams();
+      if (args.from) q.set('from', args.from);
+      if (args.to) q.set('to', args.to);
+      const qs = q.toString() ? `?${q}` : '';
+      const res = await messagingApi(`/SupportTools/sites/${args.siteId}/connection-evidence${qs}`);
+      if (res?.error) return `Error: ${res.error}`;
+      return JSON.stringify(res, null, 2);
+    }
+
     case 'support_site_health': {
       const h = await api('GET', `/SupportTools/sites/${args.siteId}/health`);
       const sub = h.subscription;
@@ -7409,6 +7814,15 @@ async function handleTool(name, args) {
       ).join('\n');
     }
 
+    case 'report_explain': {
+      const all = JSON.parse(_readFileSync(_join(_dirname(_ftu(import.meta.url)), '..', 'cli', 'lib', 'report-explain.json'), 'utf8'));
+      const key = String(args.report ?? '').trim().toLowerCase();
+      if (!key) return Object.entries(all).map(([k, r]) => `${k}: ${r.name}`).join('\n');
+      const r = all[key];
+      if (!r) return `Unknown report "${key}". Valid keys: ${Object.keys(all).join(', ')}`;
+      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 '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]));
@@ -7431,6 +7845,12 @@ async function handleTool(name, args) {
           lines.push(`  ${label}: ${x.chats} chats | avg wait ${x.avgWaitSec}s | missed ${x.missed} | CSAT ${x.csatResponses ? x.csatAvg : '-'} (${x.csatResponses ?? 0})`);
         }
       }
+      // Additive fields from the rebuilt report (absent on older backends): CSAT coverage + per-KPI reasons.
+      if (r.coverage) {
+        const c = r.coverage;
+        lines.push(`CSAT coverage: ${(c.sources ?? []).map(x => `${x.label} ${x.responses} (avg ${x.avg ?? '-'})`).join(' | ')} | survey submissions ${c.surveySubmissions ?? 0}, rated ${c.surveyRated ?? 0}, response rate ${c.responseRatePct ?? 0}% | CSAT survey configured: ${c.csatSurveyConfigured ? 'yes' : 'no'}`);
+      }
+      for (const x of r.reasons ?? []) lines.push(`  Why ${x.kpi} is low/empty [${x.code}]: ${x.message}${x.action ? ' Action: ' + x.action : ''}`);
       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');
     }
@@ -9253,6 +9673,28 @@ async function handleTool(name, args) {
       return JSON.stringify(result, null, 2);
     }
 
+    case 'booking_list_appointments': {
+      const params = [];
+      if (args.fromUtc != null) params.push(`fromUtc=${encodeURIComponent(args.fromUtc)}`);
+      if (args.toUtc != null) params.push(`toUtc=${encodeURIComponent(args.toUtc)}`);
+      if (args.bookableServiceId != null) params.push(`bookableServiceId=${encodeURIComponent(args.bookableServiceId)}`);
+      const qs = params.length ? `?${params.join('&')}` : '';
+      const result = await messagingGet(`/Bookings${qs}`);
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'booking_get_appointment': {
+      if (args.bookingId == null) return 'bookingId is required.';
+      const result = await messagingGet(`/Bookings/${encodeURIComponent(args.bookingId)}`);
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'booking_cancel_appointment': {
+      if (args.bookingId == null) return 'bookingId is required.';
+      const result = await messagingPost(`/Bookings/${encodeURIComponent(args.bookingId)}/cancel`, {});
+      return JSON.stringify(result, null, 2);
+    }
+
     default:
       throw new Error(`Unknown tool: ${name}`);
   }
@@ -9353,4 +9795,4 @@ if (mode === 'http') {
 } else {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-}
+}