@velaro/mcp-server 0.6.69 → 0.6.70

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.70",
   "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',
@@ -2638,6 +2764,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 +4799,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 +5177,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 +5293,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 +6782,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 +7246,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 +7471,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');
@@ -9253,6 +9561,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 +9683,4 @@ if (mode === 'http') {
 } else {
   const transport = new StdioServerTransport();
   await server.connect(transport);
-}
+}