@velaro/mcp-server 0.6.51 → 0.6.53

package/package.json

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

@@ -9,7 +9,7 @@
  *   VELARO_JWT=<token>            short-lived Velaro JWT (from velaro login, for dev use)
  *
  * API base:
- *   VELARO_ADMIN_API=https://help.velaro.com   (default, production)
+ *   VELARO_ADMIN_API=https://api-admin-us-east.velaro.com   (default, production)
  *   VELARO_ADMIN_API=https://velaro-admin-staging.azurewebsites.net  (staging)
  *
  * Claude Desktop config (~/.claude/claude_desktop_config.json):
@@ -49,11 +49,45 @@ import {
   ListPromptsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 
-const API_BASE      = process.env.VELARO_ADMIN_API     || 'https://help.velaro.com';
+// Default was 'https://help.velaro.com'. Renamed to the recognizable admin API hostname for
+// clarity during the 2026-09-10 Donaldson bot Calendly status investigation
+// (docs/qa/chatbot-hallucinated-booking-donaldson-bot.md) — but this is NOT a functional fix and
+// does NOT explain that incident: live-verified same day that 'https://help.velaro.com' and
+// 'https://api-admin-us-east.velaro.com' are the SAME deployment (identical /api/health build SHA,
+// and /Calendly/superadmin/status returns 401 — auth-gated, not 404 — on both hosts). Whatever
+// caused that investigation's status/reality contradiction, it was NOT this default resolving to a
+// broken or different host; that theory is disproven. Left as a naming clarity improvement only.
+const API_BASE      = process.env.VELARO_ADMIN_API     || 'https://api-admin-us-east.velaro.com';
 const MESSAGING_API = process.env.VELARO_MESSAGING_API || null;
 const MCP_KEY       = process.env.VELARO_MCP_KEY;
 const JWT           = process.env.VELARO_JWT;
 
+// 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 —
+// defaulting env-selectable tools to one hardcoded environment while every other tool in this
+// file follows the single global API_BASE would recreate the exact bug being fixed here: an
+// operator configured for one environment would silently get a DIFFERENT environment's answer
+// from just these tools with no indication anything was different.
+const ADMIN_API_HOSTS = {
+  staging:    'https://velaro-admin-staging.azurewebsites.net',
+  production: 'https://api-admin-us-east.velaro.com',
+};
+
+/// Resolves an optional `env` tool argument to a target admin API base. Throws on an unrecognized
+/// value instead of silently falling through to API_BASE (the JS default-parameter behavior of
+/// `api(..., base)` when `base` is `undefined`) — a typo like `env: 'prod'` must not silently run
+/// a DESTRUCTIVE call (calendly_disconnect) against whatever this server defaults to while telling
+/// the caller it targeted a different environment. `hasOwnProperty` (not truthiness) also closes
+/// the prototype-chain edge case (`env: 'constructor'`, `env: 'toString'`, etc.).
+function resolveAdminBase(env) {
+  if (env === undefined || env === null) return API_BASE;
+  if (!Object.prototype.hasOwnProperty.call(ADMIN_API_HOSTS, env)) {
+    throw new Error(`Unknown env "${env}" — use "staging" or "production" (or omit it to use this server's configured default).`);
+  }
+  return ADMIN_API_HOSTS[env];
+}
+
 if (!MCP_KEY && !JWT) {
   process.stderr.write('ERROR: Set VELARO_MCP_KEY=vel_live_... or VELARO_JWT=<token>\n');
   process.exit(1);
@@ -94,6 +128,17 @@ async function messagingApi(path) {
   return res.json();
 }
 
+// FIXED 2026-09-24: velaro-messaging's /superadmin/logs/search used to return a bare JSON array
+// for some queries and {entries, nextCursor} for others, depending on which internal code path
+// served the request (see that repo's LogsController.cs ENVELOPE SHAPE comment). It now always
+// returns {entries, nextCursor} -- this helper also accepts a bare array so callers degrade
+// gracefully rather than throwing if ever pointed at an older deploy.
+function extractLogEntries(response) {
+  if (Array.isArray(response)) return response;
+  if (response && Array.isArray(response.entries)) return response.entries;
+  return [];
+}
+
 async function messagingRequest(method, path, body) {
   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.'
@@ -118,8 +163,8 @@ const messagingPut   = (path, body) => messagingRequest('PUT',  path, body);
 const messagingPatch = (path, body) => messagingRequest('PATCH', path, body);
 const messagingDel   = (path)       => messagingRequest('DELETE', path);
 
-async function api(method, path, body) {
-  const res = await fetch(`${API_BASE}${path}`, {
+async function api(method, path, body, base = API_BASE) {
+  const res = await fetch(`${base}${path}`, {
     method,
     headers: { Authorization: authHeader(), 'Content-Type': 'application/json' },
     body: body !== undefined ? JSON.stringify(body) : undefined,
@@ -127,6 +172,19 @@ async function api(method, path, body) {
   });
   if (!res.ok) {
     const text = await res.text().catch(() => '');
+    if ((res.status === 401 || res.status === 403) && base !== API_BASE) {
+      // Cross-environment call with the single global credential (MCP_KEY/JWT) — this session's
+      // credential is issued for one environment, so pointing a tool at the OTHER one via an
+      // explicit `env` override will look like a real auth failure rather than "wrong environment
+      // selected." Surface that explicitly instead of a bare HTTP error, so a caller doesn't
+      // misread it as "not configured" or a generic outage.
+      throw new Error(
+        `Velaro API ${method} ${path} -> ${res.status} against ${base}: this session's credentials ` +
+        `may not be valid for that environment (VELARO_MCP_KEY/VELARO_JWT are single, per-environment ` +
+        `credentials — re-run with credentials issued for that environment, or omit "env" to use ` +
+        `whichever environment this server is currently configured for). Raw response: ${text.slice(0, 300)}`
+      );
+    }
     throw new Error(`Velaro API ${method} ${path} -> ${res.status}: ${text.slice(0, 300)}`);
   }
   const text = await res.text();
@@ -449,14 +507,16 @@ const TOOLS = [
   },
   {
     name: 'kb_capture_screenshot',
-    description: 'Log into admin or messaging staging, navigate to a route, capture a screenshot, optionally polish/annotate it, upload it, and insert it into a KB article (after a matching <h2>/<h3> heading, or appended to the end). Requires E2E_USER_EMAIL/E2E_USER_PASSWORD env vars and the optional "playwright" package installed.',
+    description: 'Log into admin, messaging, or livefluence (v10) staging, navigate to a route, optionally click something (e.g. to open an export menu or a popup window), capture a screenshot, optionally polish/annotate it, upload it, and insert it into a KB article (after a matching <h2>/<h3> heading, or appended to the end). Requires E2E_USER_EMAIL/E2E_USER_PASSWORD env vars and the optional "playwright" package installed.',
     inputSchema: {
       type: 'object',
       properties: {
-        app:         { type: 'string', description: 'Which app to capture from', enum: ['admin', 'messaging'] },
+        app:         { type: 'string', description: 'Which app to capture from', enum: ['admin', 'messaging', 'livefluence'] },
         route:       { type: 'string', description: 'Route to navigate to, e.g. "/Settings/Routing"' },
         articleId:   { type: 'number', description: 'Target article ID' },
         heading:     { type: 'string', description: 'Insert the image immediately after the <h2>/<h3> whose text contains this (case-insensitive). Falls back to appending at the end.' },
+        click:       { type: 'string', description: 'Selector to click after the route loads, before capturing (CSS, or Playwright\'s "text=..."/"role=..." engines) — e.g. "text=Export"' },
+        popup:       { type: 'boolean', description: 'The click target opens a NEW browser window (window.open/target=_blank) rather than something in the current page — e.g. a per-transcript export action. Capture that window instead of the original page. Requires click.' },
         annotations: {
           type: 'array',
           description: 'Optional numbered/labeled circle annotations, in raw screenshot pixel coordinates.',
@@ -1195,6 +1255,47 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['message'],
     },
   },
+  {
+    name: 'teams_push_settings_get',
+    description: 'Get the Velaro Bot proactive-alert settings for this site: per-alert switches (new chat, missed chat, ticket created, ticket assigned, daily digest), the effective daily cap and the push count for today. Site is resolved server-side.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'teams_push_settings_update',
+    description: 'Change the Velaro Bot proactive-alert settings for this site. Only fields you pass are changed; omitted fields keep their value. Set resetDailyPushCap=true to clear the per-site cap and use the platform default.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        pushNewChat:        { type: 'boolean', description: 'New chat alerts' },
+        pushMissed:         { type: 'boolean', description: 'Missed chat alerts' },
+        pushTicketCreated:  { type: 'boolean', description: 'Ticket created alerts' },
+        pushTicketAssigned: { type: 'boolean', description: 'Ticket assigned alerts' },
+        pushDailyDigest:    { type: 'boolean', description: 'Daily digest (off by default)' },
+        dailyPushCap:       { type: 'number',  description: 'Max alerts per day for this site' },
+        resetDailyPushCap:  { type: 'boolean', description: 'Clear the per-site cap (use platform default)' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'teams_channel_config_get',
+    description: 'Get this site\'s Teams Channel (customer chat) settings: whether it\'s enabled, the welcome message sent to a Teams user opening a new conversation, and the team new conversations route to (null = site default team). Site is resolved server-side.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'teams_channel_config_update',
+    description: 'Change this site\'s Teams Channel settings. Only fields you pass are changed. Enabling this is what makes free-text messages to the Velaro Teams bot open a real, agent-routed conversation instead of the default staff-command-only reply.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        enabled:        { type: 'boolean', description: 'Turn Teams Channel (customer chat) on or off for this site' },
+        welcomeMessage: { type: 'string',  description: 'Sent to the Teams user when their message opens a new conversation. Use {{user.name}} for their display name. Max 1000 characters.' },
+        teamId:         { type: 'number',  description: 'Route new conversations to this team id (must be a real, non-deleted team on this site)' },
+        clearTeamId:    { type: 'boolean', description: 'Clear the team override and fall back to the site default team' },
+      },
+      required: [],
+    },
+  },
   {
     name: 'teams_notify_card',
     description: 'Send a rich Adaptive Card (title + fact/value fields + optional action button) to a Teams webhook — use this for structured summaries (CI results, QA report pass/fail counts, ops status) instead of teams_notify\'s plain message.',
@@ -1727,6 +1828,38 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  // ── Unified Outbound Activity (Klaviyo-parity Gap 6) ──────────────────────
+  {
+    name: 'outbound_activity_list',
+    description: 'Unified outbound email feed across ALL THREE send systems at once: transactional/system mail (password resets, alerts), sequence/drip campaign steps, and one-off broadcasts. Newest first. Use this instead of checking the broadcast, sequence and transactional views separately. Site scoping is enforced server-side.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        take: { type: 'number', description: 'Page size, 1-100 (default 25)' },
+        skip: { type: 'number', description: 'Rows to skip (default 0)' },
+        source: { type: 'string', enum: ['Transactional', 'Campaign', 'Broadcast'], description: 'Limit to one send system. Omit for all three.' },
+        status: { type: 'string', enum: ['Sent', 'Pending', 'Failed', 'Unsubscribed', 'Skipped'], description: 'Normalized status shared across all three systems' },
+        search: { type: 'string', description: 'Match recipient address or subject' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'outbound_activity_for_contact',
+    description: 'Every email this account has sent to ONE specific address, across transactional, sequence and broadcast sends — the "what have we sent this customer" answer that previously required checking three separate screens. The email address is REQUIRED and matched exactly; it is never optional, because an omitted address must not widen this into a site-wide listing.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        email: { type: 'string', description: 'Exact recipient email address (required)' },
+        take: { type: 'number', description: 'Page size, 1-100 (default 25)' },
+        skip: { type: 'number', description: 'Rows to skip (default 0)' },
+        source: { type: 'string', enum: ['Transactional', 'Campaign', 'Broadcast'], description: 'Limit to one send system. Omit for all three.' },
+        status: { type: 'string', enum: ['Sent', 'Pending', 'Failed', 'Unsubscribed', 'Skipped'], description: 'Normalized status shared across all three systems' },
+      },
+      required: ['email'],
+    },
+  },
+
   // ── Conversion tracking tools ─────────────────────────────────────────────
   {
     name: 'conversion_list_goals',
@@ -1822,13 +1955,18 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     inputSchema: {
       type: 'object',
       properties: {
-        q:           { type: 'string',  description: 'Text to search for in log messages (plain or regex)' },
-        level:       { type: 'string',  enum: ['ERROR', 'WARN', 'INFO', 'DEBUG'], description: 'Filter by log level' },
-        integration: { type: 'string',  description: 'Integration tag filter (HubSpot, [Skill], NetSuite, etc.)' },
-        siteId:      { type: 'number',  description: 'Filter by site ID' },
-        last:        { type: 'string',  description: 'Time window: 30m, 2h, 1d (default: 2h)' },
-        take:        { type: 'number',  description: 'Max results (default: 50, max: 500)' },
-        regex:       { type: 'boolean', description: 'Treat q as a regex pattern (default: false)' },
+        q:             { type: 'string',  description: 'Text to search for in log messages (plain or regex)' },
+        level:         { type: 'string',  enum: ['ERROR', 'WARN', 'INFO', 'DEBUG'], description: 'Filter by log level' },
+        logger:        { type: 'string',  description: 'Logger name filter (substring match, or regex when regex=true)' },
+        integration:   { type: 'string',  description: 'Integration tag filter (HubSpot, [Skill], NetSuite, etc.)' },
+        siteId:        { type: 'number',  description: 'Filter by site ID' },
+        source:        { type: 'string',  description: 'Source/app-tag filter, e.g. velaro-messaging-Staging' },
+        platform:      { type: 'string',  enum: ['v10', 'v20', 'admin'], description: 'Filter by platform' },
+        environment:   { type: 'string',  enum: ['Production', 'Staging', 'Development'] },
+        correlationId: { type: 'string',  description: 'Exact correlation/trace ID filter' },
+        last:          { type: 'string',  description: 'Time window: 30m, 2h, 1d (default: 2h)' },
+        take:          { type: 'number',  description: 'Max results (default: 50, max: 500)' },
+        regex:         { type: 'boolean', description: 'Treat q/logger as a regex pattern (default: false)' },
       },
     },
   },
@@ -2112,6 +2250,15 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId'],
     },
   },
+  {
+    name: 'support_site_deployments',
+    description: 'List active widget deployment embed keys and assigned survey IDs for one site. Staff-only and read-only. Use deploymentId (the string embed key) in the widget test harness, not the numeric database id.',
+    inputSchema: {
+      type: 'object',
+      properties: { siteId: { type: 'number', description: 'Target site ID' } },
+      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.',
@@ -2231,11 +2378,12 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   // ── Calendly integration management (superadmin) ──────────────────────────
   {
     name: 'calendly_get_status',
-    description: 'Check whether Calendly is configured for a site and show the current settings. Velaro admin only.',
+    description: 'Check whether Calendly is configured for a site and show the current settings. Velaro admin only. Queries whichever admin API environment this server is currently configured for (VELARO_ADMIN_API) unless "env" is given explicitly.',
     inputSchema: {
       type: 'object',
       properties: {
         siteId: { type: 'number', description: 'Site ID to check' },
+        env: { type: 'string', enum: ['staging', 'production'], description: 'Explicitly target one environment instead of this server\'s configured default (VELARO_ADMIN_API). Use this when a site is known to live in one specific environment (e.g. a staging-only test site) — omitting it can silently report "not configured" for a site that is only set up in the OTHER environment from the one this server defaults to. Requires credentials valid for that environment.' },
       },
       required: ['siteId'],
     },
@@ -2252,6 +2400,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         defaultEventTypeName: { type: 'string', description: 'Human-readable name for the default event type. Optional.' },
         displayName:      { type: 'string',  description: 'Label shown in admin UI, e.g. "Acme Demo Booking". Optional.' },
         useSingleUseLinks:{ type: 'boolean', description: 'true = generate single-use links per visitor (requires scheduling_links:write). false = reusable event-type URL. Default: true.' },
+        env: { type: 'string', enum: ['staging', 'production'], description: 'Explicitly target one environment instead of this server\'s configured default (VELARO_ADMIN_API). Requires credentials valid for that environment.' },
       },
       required: ['siteId', 'accessToken'],
     },
@@ -2263,6 +2412,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       type: 'object',
       properties: {
         siteId: { type: 'number', description: 'Site ID to disconnect' },
+        env: { type: 'string', enum: ['staging', 'production'], description: 'Explicitly target one environment instead of this server\'s configured default (VELARO_ADMIN_API). Requires credentials valid for that environment.' },
       },
       required: ['siteId'],
     },
@@ -3316,6 +3466,18 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId', 'planKey'],
     },
   },
+  { // wires EntitlementsController.SetEntitlementLock (PUT Entitlements/admin/lock/{siteId})
+    name: 'entitlement_set_lock',
+    description: 'Lock a site\'s entitlement resolution to a point-in-time PlanEntitlement version (freezes what plan changes the site sees), or clear an existing lock so it resolves against the current plan version again. Pass lockedAt=null to unlock. Refuses to lock to a timestamp with no defined PlanEntitlement row for the site\'s current plan. Superadmin only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId:    { type: 'number', description: 'Site ID to lock or unlock.' },
+        lockedAt:  { type: 'string', description: 'ISO 8601 timestamp to lock entitlement resolution to. Pass null (or omit) to clear an existing lock.' },
+      },
+      required: ['siteId'],
+    },
+  },
   {
     name: 'entitlement_seed_plans',
     description: 'Seed PlanEntitlement rows from live PackageVersions in the messaging DB. Maps each plan×feature to its current value. Idempotent — inserts new rows, versions changed rows. Run after entitlement_seed and after any PackageVersion change. Superadmin only.',
@@ -4318,6 +4480,8 @@ async function handleTool(name, args) {
         articleId:   args.articleId,
         heading:     args.heading,
         annotations: args.annotations ?? [],
+        click:       args.click,
+        popup:       args.popup ?? false,
         auth:        { token, apiBase: API_BASE },
       });
       return result.insertedAfterHeading
@@ -4899,6 +5063,26 @@ async function handleTool(name, args) {
       return `Sent to Teams webhook "${webhook.name}".`;
     }
 
+    case 'teams_push_settings_get':
+      return await api('GET', '/TeamsBot/PushSettings');
+
+    case 'teams_push_settings_update': {
+      const body = {};
+      for (const k of ['pushNewChat','pushMissed','pushTicketCreated','pushTicketAssigned','pushDailyDigest','dailyPushCap','resetDailyPushCap'])
+        if (args[k] !== undefined) body[k] = args[k];
+      return await api('PUT', '/TeamsBot/PushSettings', body);
+    }
+
+    case 'teams_channel_config_get':
+      return await api('GET', '/TeamsBot/ChannelConfig');
+
+    case 'teams_channel_config_update': {
+      const body = {};
+      for (const k of ['enabled','welcomeMessage','teamId','clearTeamId'])
+        if (args[k] !== undefined) body[k] = args[k];
+      return await api('PUT', '/TeamsBot/ChannelConfig', body);
+    }
+
     case 'teams_notify_card': {
       const webhooks = await api('GET', '/TeamsNotification');
       if (!Array.isArray(webhooks) || !webhooks.length)
@@ -5301,7 +5485,8 @@ async function handleTool(name, args) {
       const velaroLoggerP = safeJson(async () => {
         if (!MESSAGING_API) return { _error: 'VELARO_MESSAGING_API not set — add it to MCP env config' };
         const q = encodeURIComponent('ERROR|WF-AI-ROUTE|PERF-SLOW');
-        return messagingApi(`/superadmin/logs/search?q=${q}&from=${encodeURIComponent(from1h)}&take=30&regex=true`);
+        const res = await messagingApi(`/superadmin/logs/search?q=${q}&from=${encodeURIComponent(from1h)}&take=30&regex=true`);
+        return extractLogEntries(res);
       });
 
       // ── Layer 4b: Loggly ERROR + SLOW + AI-routing logs (last 1h) — SECONDARY (migrating away)
@@ -6004,6 +6189,57 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    // ── Unified Outbound Activity ──────────────────────────────────────────
+    case 'outbound_activity_list':
+    case 'outbound_activity_for_contact': {
+      const forContact = name === 'outbound_activity_for_contact';
+      const email = String(args.email ?? '').trim();
+      // Required scoping identifier — never fall through to a site-wide listing.
+      if (forContact && !email) return 'Error: email is required for outbound_activity_for_contact';
+
+      const params = new URLSearchParams();
+      params.set('take', String(args.take ?? 25));
+      params.set('skip', String(args.skip ?? 0));
+      if (args.source) params.set('source', args.source);
+      if (args.status) params.set('status', args.status);
+      if (!forContact && args.search) params.set('search', args.search);
+
+      const path = forContact
+        ? `/Marketing/Contacts/${encodeURIComponent(email)}/OutboundActivity?${params}`
+        : `/Marketing/OutboundActivity?${params}`;
+
+      const r = await api('GET', path);
+      const items = r?.items ?? [];
+      const srcLabel = { Transactional: 'Transactional', Campaign: 'Sequence', Broadcast: 'Broadcast' };
+
+      const lines = [forContact ? `=== Outbound Activity: ${email} ===` : '=== Outbound Activity ==='];
+
+      // A partial feed is never reported as if it were complete.
+      if (r?.degradedSources?.length) {
+        lines.push(`  ! INCOMPLETE - could not load: ${r.degradedSources.map(s => srcLabel[s] ?? s).join(', ')}. Rows from those systems are MISSING below.`);
+      }
+      if (!items.length) {
+        lines.push('  (no outbound activity matched)');
+        return lines.join('\n');
+      }
+
+      for (const i of items) {
+        const when = i.sentAt ? new Date(i.sentAt).toISOString() : 'not sent';
+        lines.push(`  [${i.status}] ${srcLabel[i.source] ?? i.source} ${when} -> ${i.toEmail ?? '(none)'}`);
+        lines.push(`      ${i.subject ?? ''}`);
+        const meta = [];
+        if (i.campaignOrBroadcastName) meta.push(`campaign: ${i.campaignOrBroadcastName}`);
+        if (i.tag) meta.push(`tag: ${i.tag}`);
+        if (i.channel && i.channel !== 'email') meta.push(`channel: ${i.channel}`);
+        // Transactional sends have no open/click tracking at all — report nothing rather than a
+        // zero that would read as a measured zero.
+        if (i.source !== 'Transactional') meta.push(`opens ${i.openCount}, clicks ${i.clickCount}`);
+        if (meta.length) lines.push(`      ${meta.join(' | ')}`);
+      }
+      lines.push(`  ${items.length} shown of ${r?.totalCountIsApproximate ? 'about ' : ''}${r?.totalCount ?? items.length}.`);
+      return lines.join('\n');
+    }
+
     // ── Audit Trail ────────────────────────────────────────────────────────
     case 'audit_trail_list': {
       const params = new URLSearchParams();
@@ -6102,13 +6338,18 @@ async function handleTool(name, args) {
     case 'velaro_logs_search': {
       const from   = new Date(Date.now() - parseDuration(args.last));
       const params = new URLSearchParams({ from: from.toISOString(), take: String(args.take ?? 50) });
-      if (args.q)           params.set('q',           args.q);
-      if (args.level)       params.set('level',        args.level.toUpperCase());
-      if (args.integration) params.set('integration',  args.integration);
-      if (args.siteId)      params.set('siteId',        String(args.siteId));
-      if (args.regex)       params.set('regex',         'true');
-      const entries = await messagingApi(`/superadmin/logs/search?${params}`);
-      if (!Array.isArray(entries) || !entries.length) return 'No results.';
+      if (args.q)             params.set('q',             args.q);
+      if (args.level)         params.set('level',         args.level.toUpperCase());
+      if (args.logger)        params.set('logger',        args.logger);
+      if (args.integration)   params.set('integration',   args.integration);
+      if (args.siteId)        params.set('siteId',        String(args.siteId));
+      if (args.source)        params.set('source',        args.source);
+      if (args.platform)      params.set('platform',      args.platform);
+      if (args.environment)   params.set('environment',   args.environment);
+      if (args.correlationId) params.set('correlationId', args.correlationId);
+      if (args.regex)         params.set('regex',         'true');
+      const entries = extractLogEntries(await messagingApi(`/superadmin/logs/search?${params}`));
+      if (!entries.length) return 'No results.';
       const lines = [`${entries.length} result(s) from ${from.toISOString().slice(0, 16)} UTC\n`];
       for (const e of entries) {
         const ts    = new Date(e.timestamp ?? e.LogTimestamp).toISOString().replace('T', ' ').slice(0, 19);
@@ -6376,6 +6617,14 @@ async function handleTool(name, args) {
       ].join('\n');
     }
 
+    case 'support_site_deployments': {
+      const data = await api('GET', `/SupportTools/sites/${args.siteId}/deployments`);
+      if (!data.deployments?.length) return `No active widget deployments for site ${args.siteId}.`;
+      return data.deployments.map(d =>
+        `[id=${d.id}] ${d.displayName || '(unnamed)'} | embed key: ${d.deploymentId} | team: ${d.teamId} | surveys: pre-chat ${d.preChatSurveyId ?? '—'}, post-chat ${d.postChatSurveyId ?? '—'}, unavailable ${d.unavailableSurveyId ?? '—'}`
+      ).join('\n');
+    }
+
     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}.`;
@@ -6468,10 +6717,26 @@ async function handleTool(name, args) {
     }
 
     case 'calendly_get_status': {
-      const data = await api('GET', `/Calendly/superadmin/status?siteId=${args.siteId}`);
-      if (!data.configured) return `Site ${args.siteId}: Calendly NOT configured.`;
+      // `env`, when given, targets one specific admin API environment instead of whatever
+      // VELARO_ADMIN_API this server process happens to be configured with — see ADMIN_API_HOSTS
+      // and resolveAdminBase() above. No default override here: an unspecified `env` means "use
+      // this server's configured environment," same as every other tool in this file.
+      const base = resolveAdminBase(args.env);
+      const data = await api('GET', `/Calendly/superadmin/status?siteId=${args.siteId}`, undefined, base);
+      const envSuffix = ` (${args.env ?? 'this server\'s configured env'}: ${base})`;
+      if (!data.configured) {
+        // exists === true means a row IS present but Enabled is false — a real, different state
+        // from "never configured," which used to render identically (see CalendlyController.cs
+        // SuperAdminStatus) and is one plausible (unconfirmed) explanation for the 2026-09-08
+        // Donaldson bot Calendly status contradiction. exists === undefined means this admin API
+        // build predates the field (staging/production deploy independently) — don't assert a
+        // specific DB state the response didn't actually report.
+        if (data.exists === true) return `Site ${args.siteId}${envSuffix}: Calendly configured but DISABLED (a config row exists with Enabled=false).`;
+        if (data.exists === undefined) return `Site ${args.siteId}${envSuffix}: Calendly not enabled. (This API build does not report "exists" yet, so a disabled row can't be distinguished from no row at all — re-check once this endpoint is deployed there.)`;
+        return `Site ${args.siteId}${envSuffix}: Calendly NOT configured (no config row found in this environment).`;
+      }
       return [
-        `Site ${args.siteId}: Calendly configured ✓`,
+        `Site ${args.siteId}${envSuffix}: Calendly configured ✓`,
         `  Account:      ${data.userName}`,
         `  Default type: ${data.defaultEventTypeName || '(none)'}`,
         `  Single-use:   ${data.useSingleUseLinks ? 'yes' : 'no'}`,
@@ -6480,20 +6745,22 @@ async function handleTool(name, args) {
     }
 
     case 'calendly_configure': {
+      const base = resolveAdminBase(args.env);
       const res = await api('POST', `/Calendly/superadmin/config?siteId=${args.siteId}`, {
         accessToken:          args.accessToken,
         displayName:          args.displayName          ?? '',
         defaultEventTypeUri:  args.defaultEventTypeUri  ?? '',
         defaultEventTypeName: args.defaultEventTypeName ?? '',
         useSingleUseLinks:    args.useSingleUseLinks     ?? true,
-      });
+      }, base);
       if (!res?.success) throw new Error(res?.error || 'Configure failed');
-      return `✓ Calendly configured for site ${args.siteId}. Account: ${res.userName}`;
+      return `✓ Calendly configured for site ${args.siteId} (${args.env ?? 'this server\'s configured env'}: ${base}). Account: ${res.userName}`;
     }
 
     case 'calendly_disconnect': {
-      await api('DELETE', `/Calendly/superadmin/config?siteId=${args.siteId}`);
-      return `✓ Calendly disconnected from site ${args.siteId}.`;
+      const base = resolveAdminBase(args.env);
+      await api('DELETE', `/Calendly/superadmin/config?siteId=${args.siteId}`, undefined, base);
+      return `✓ Calendly disconnected from site ${args.siteId} (${args.env ?? 'this server\'s configured env'}: ${base}).`;
     }
 
     // ── Acuity Scheduling ─────────────────────────────────────────────────────
@@ -7641,6 +7908,15 @@ async function handleTool(name, args) {
       return `✅ Site ${args.siteId} comped on plan ${args.planKey}${expiry}. Use entitlement_set_override to customize features.`;
     }
 
+    case 'entitlement_set_lock': {
+      if (!args.siteId) throw new Error('siteId is required');
+      const lockedAt = args.lockedAt ?? null;
+      const result = await api('PUT', `/Entitlements/admin/lock/${args.siteId}`, { lockedAt });
+      return lockedAt
+        ? `✅ Site ${args.siteId} entitlements locked to ${result.entitlementLockedAt} (plan ${result.planKey}).`
+        : `✅ Site ${args.siteId} entitlement lock cleared. Resolves against the current plan version again.`;
+    }
+
     case 'entitlement_seed_plans': {
       const result = await api('POST', '/Entitlements/admin/seed-plans');
       if (result.error) return `❌ ${result.error}`;