@velaro/mcp-server 2.0.0 → 2.0.1

package/package.json

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

@@ -1067,6 +1067,8 @@ Key node shapes:
     propName:"myAnswerVar" }                      // variable that stores the result as JSON array string
 • condition:      { type:"action", actionType:"condition", conditionOptions:[...] }
 • transferToAI:   { type:"action", actionType:"transferToAI", aiConfigId:N }
+• selectPreChat:  { type:"action", actionType:"selectPreChat", surveyId:N, surveyCompact:true|false|null, child:N }
+  surveyCompact (optional tri-state): null/omitted = follow the survey's own compactMode, true = compact, false = regular.
 • sendSurvey:     { type:"action", actionType:"sendSurvey", sendSurveyId:N, surveyDeliveryMode:"conversational"|"form", closeAfterSurvey:true|false, child:N }
   closeAfterSurvey (optional, default false): when true the chat closes once the visitor completes the survey (use for Unavailable/after-hours surveys that replace a live chat). Omit to keep the old behaviour.
   AI follow-up suggestions ("AI mode"): add suggestFollowUps:true|false (omit = use the account default, set via ai_followups_site_set), suggestFollowUpCount:2-4, suggestFollowUpInstruction:"<=300 chars". After each web-chat bot reply the bot offers short tappable follow-up replies; typing stays available.
@@ -1132,13 +1134,14 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
   {
     name: 'survey_upsert',
-    description: 'Create (omit id or set id=0) or update (set id) a survey. body must be the full SurveyViewModel JSON shape (id, name, questions[], each question with type/text/options/required/variable/etc.). Use survey_get on an existing survey to fetch this full shape as a template rather than guessing the question schema from scratch. Each question also accepts isThemeAnchor (boolean, default false: this answer sets the Chat Intelligence topic) and themeMapping (string: JSON object mapping answer text to a site topic, e.g. "{\\"Pay my bill\\":\\"Billing Questions\\"}"). Both only take effect when the site has the multi-topic setting on.',
+    description: 'Create (omit id or set id=0) or update (set id) a survey. body must be the full SurveyViewModel JSON shape (id, name, questions[], each question with type/text/options/required/variable/etc.). Use survey_get on an existing survey to fetch this full shape as a template rather than guessing the question schema from scratch. Each question also accepts isThemeAnchor (boolean, default false: this answer sets the Chat Intelligence topic) and themeMapping (string: JSON object mapping answer text to a site topic, e.g. "{\\"Pay my bill\\":\\"Billing Questions\\"}"). Both only take effect when the site has the multi-topic setting on. body.compactMode is tri-state: null/omitted = follow default (regular size), true = compact, false = regular.',
     inputSchema: {
       type: 'object',
       properties: { body: {
         type: 'object',
         description: 'Full SurveyViewModel JSON',
         properties: {
+          compactMode: { type: ['boolean', 'null'], description: 'Tri-state survey size: null/omitted = follow default (regular size), true = compact, false = regular' },
           questions: {
             type: 'array',
             items: {
@@ -1582,6 +1585,28 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  {
+    name: 'agent_force_sign_out',
+    description: 'Security control: force one agent to sign in again. Revokes every active session of that agent now (their existing tokens stop working) and sets them Offline. Administrator only; the agent must belong to your site; audited (who/when/target). You cannot force sign out your own account.',
+    inputSchema: {
+      type: 'object',
+      properties: { userId: { type: 'number', description: 'Agent user id from agent_list' } },
+      required: ['userId'],
+    },
+  },
+  {
+    name: 'agent_set_status',
+    description: 'Set an agent availability status (Available, Busy, Away, Offline). Use Offline or Away to make an agent Unavailable for routing. Site manager only; the agent must belong to your site; audited with the acting admin.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        userId: { type: 'number', description: 'Agent user id from agent_list' },
+        status: { type: 'string', enum: ['Available', 'Busy', 'Away', 'Offline'] },
+      },
+      required: ['userId', 'status'],
+    },
+  },
+
   // ── Dynamics per-team overrides (effective = team override ?? connection default) ──
   {
     name: 'dynamics_team_overrides_get',
@@ -2061,6 +2086,27 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       },
     },
   },
+  {
+    name: 'safety_policy_get',
+    description: 'Get the safety controls policy: per control (emergency_self_harm, abuse_ladder, threat_detection, input_jailbreak, output_filter) whether it is on for AI bot and human agent, any overrides, the always-on floor, a warning when anything is off, and the acknowledgement text and version needed to turn a control off. Wraps GET SafetyPolicy.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'safety_policy_set',
+    description: 'Turn a safety control on, off, or back to default. Every control is ON by default. Turning one OFF is refused unless acknowledged=true AND ackTextVersion equals the current acknowledgement version (read it from safety_policy_get and show the acknowledgement text to the account owner first). This tool never accepts the acknowledgement on anyone\'s behalf. Turning on or resetting needs no acknowledgement. Wraps PUT SafetyPolicy.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        control:        { type: 'string', enum: ['emergency_self_harm', 'abuse_ladder', 'threat_detection', 'input_jailbreak', 'output_filter'] },
+        audience:       { type: 'string', enum: ['ai_bot', 'human_agent'] },
+        featureKey:     { type: 'string', description: 'Optional per-feature/channel scope (chat, voice, sms, whatsapp, email). Omit for the whole account.' },
+        enabled:        { type: ['boolean', 'null'], description: 'true = on, false = off, null = clear the override (default on)' },
+        acknowledged:   { type: 'boolean', description: 'Required true when enabled=false: the account owner accepted the acknowledgement text' },
+        ackTextVersion: { type: 'string', description: 'Required when enabled=false: the acknowledgement version from safety_policy_get' },
+      },
+      required: ['control', 'audience', 'enabled'],
+    },
+  },
   {
     name: 'safety_settings_test',
     description: 'Send a test safety alert to the configured recipients. Wraps POST SafetyEvents/settings/test.',
@@ -3314,6 +3360,34 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
 
 
+  {
+    name: 'magento_get_sidebar_fields',
+    description: 'Get the Magento fields shown in the agent sidebar panel for the authenticated site (empty list = out-of-box defaults). Calls messaging GET Magento/data/sidebar-fields. Site comes from the bearer token only. Read-only.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'magento_set_sidebar_fields',
+    description: 'Set the Magento fields shown in the agent sidebar panel for the authenticated site. Partial update: omit fields to leave the saved list untouched; an empty array clears it. Site comes from the bearer token only. Calls messaging PUT Magento/data/sidebar-fields.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fields: {
+          type: 'array',
+          description: 'Sidebar fields to show, in order',
+          items: {
+            type: 'object',
+            properties: {
+              fieldName: { type: 'string', description: 'Magento field name, e.g. "email"' },
+              entity:    { type: 'string', description: 'Entity the field belongs to, e.g. "customer" or "order"' },
+              label:     { type: 'string', description: 'Optional display label' },
+            },
+            required: ['fieldName'],
+          },
+        },
+      },
+    },
+  },
+
   {
     name: 'business_action_list',
     description: 'List the shared business actions registered on the messaging API (e.g. get_customer_pricing, create_quote): name, whether it is a write, data class, freshness window, request JSON schema and the AI skill tool names that project it. One definition is served by the Velaro catalog or a connected ERP (SAP) beneath it. Site scope comes from the caller\'s auth context. Calls GET /BusinessActions.',
@@ -3480,6 +3554,29 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     inputSchema: { type: 'object', properties: {}, required: [] },
   },
 
+  {
+    name: 'teams_phone_list_agents',
+    description: "List the site's agents with their Microsoft Teams user Object ID mapping (agent -> Entra user), used to route inbound Teams Phone calls to the right agent. Admin only. Lives in velaro-messaging — requires VELARO_MESSAGING_API.",
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'teams_phone_set_agent',
+    description: 'Map one Velaro agent (workspace user id) to a Microsoft Entra user Object ID (GUID) so inbound Teams Phone calls reach them. Upsert; pass "" to clear. Must be unique per site. Lives in velaro-messaging — requires VELARO_MESSAGING_API.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        agentId:     { type: 'number', description: 'Velaro agent (workspace user) id from teams_phone_list_agents.' },
+        teamsUserId: { type: 'string', description: 'Entra user Object ID (GUID). "" clears the mapping.' },
+      },
+      required: ['agentId', 'teamsUserId'],
+    },
+  },
+  {
+    name: 'teams_phone_delete_agent',
+    description: "Clear one agent's Teams user mapping. Calls to that Teams user will no longer route to the agent.",
+    inputSchema: { type: 'object', properties: { agentId: { type: 'number', description: 'Velaro agent (workspace user) id.' } }, required: ['agentId'] },
+  },
+
   // ── Webflow (config CRUD) ──────────────────────────────────────────────────
   // Lives in velaro-admin's own WebflowController.cs (this API), not velaro-messaging.
   // The other 6 Webflow AI skills (webflow_list_sites, webflow_get_site,
@@ -3827,6 +3924,8 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  // ── Billing agents + package builder (staff; docs/architecture/billing-agents-and-package-builder.md) ──
+  { name: 'package_builder_my', description: 'Customer-safe: the caller\'s own package name and what it includes. No prices or staff data.', inputSchema: { type: 'object', properties: {} } },
   // ── Pricing Catalog ───────────────────────────────────────────────────────
   {
     name: 'pricing_catalog_list',
@@ -5809,6 +5908,19 @@ reply: ${r?.reply}`;
     case 'agent_list':
       return await rpc('agent_list', args);
 
+    case 'agent_force_sign_out': {
+      if (!Number.isInteger(args.userId) || args.userId <= 0) return 'userId is required (positive integer).';
+      await messagingPost(`/Users/${args.userId}/ForceSignOut`, {});
+      return `Agent ${args.userId} was signed out of every session and set to Offline. They must sign in again.`;
+    }
+
+    case 'agent_set_status': {
+      if (!Number.isInteger(args.userId) || args.userId <= 0) return 'userId is required (positive integer).';
+      if (!['Available', 'Busy', 'Away', 'Offline'].includes(args.status)) return 'status must be Available, Busy, Away or Offline.';
+      await messagingPost('/UserStatus/admin', { userId: args.userId, status: args.status });
+      return `Agent ${args.userId} set to ${args.status}.`;
+    }
+
     // ── Teams ──────────────────────────────────────────────────────────────
     case 'team_list':
       return await rpc('team_list', args);
@@ -6386,6 +6498,21 @@ reply: ${r?.reply}`;
       }
       return JSON.stringify(await messagingPut('/SafetyEvents/settings', next), null, 2);
     }
+    case 'safety_policy_get':
+      return JSON.stringify(await messagingGet('/SafetyPolicy'), null, 2);
+    case 'safety_policy_set': {
+      if (args.enabled === false && (args.acknowledged !== true || !args.ackTextVersion)) {
+        throw new Error('Turning a safety control off requires acknowledged=true and ackTextVersion (from safety_policy_get). This tool never accepts the acknowledgement automatically.');
+      }
+      const body = {
+        control: args.control,
+        audience: args.audience,
+        featureKey: args.featureKey ?? null,
+        enabled: args.enabled === undefined ? null : args.enabled,
+        ...(args.enabled === false ? { acknowledged: true, ackTextVersion: args.ackTextVersion } : {}),
+      };
+      return JSON.stringify(await messagingPut('/SafetyPolicy', body), null, 2);
+    }
     case 'safety_settings_test':
       return JSON.stringify(await messagingPost('/SafetyEvents/settings/test'), null, 2);
     case 'safety_need_help':
@@ -7577,6 +7704,21 @@ reply: ${r?.reply}`;
       return lines.join('\n');
     }
 
+    case 'magento_get_sidebar_fields': {
+      const r = await messagingRequest('GET', '/Magento/data/sidebar-fields');
+      return JSON.stringify(r, null, 2);
+    }
+
+    case 'magento_set_sidebar_fields': {
+      const body = {};
+      if (args.fields !== undefined) {
+        if (!Array.isArray(args.fields)) return 'fields must be an array.';
+        body.fields = args.fields;
+      }
+      const r = await messagingRequest('PUT', '/Magento/data/sidebar-fields', body);
+      return JSON.stringify(r, null, 2);
+    }
+
     case 'business_action_list': {
       const r = await messagingRequest('GET', '/BusinessActions');
       return JSON.stringify(r, null, 2);
@@ -7730,6 +7872,20 @@ reply: ${r?.reply}`;
       return lines.join(String.fromCharCode(10));
     }
 
+    case 'teams_phone_list_agents': {
+      const agents = await messagingGet('/TeamsPhone/Agents');
+      if (!Array.isArray(agents) || agents.length === 0) return 'No agents found.';
+      return agents.map(a => `${a.id}  ${`${a.firstName ?? ''} ${a.lastName ?? ''}`.trim()}  ${a.email ?? ''}  ${a.teamsUserId || '(unmapped)'}`).join(String.fromCharCode(10));
+    }
+    case 'teams_phone_set_agent': {
+      const r = await messagingPut(`/TeamsPhone/Agents/${encodeURIComponent(args.agentId)}`, { teamsUserId: args.teamsUserId });
+      return r?.configured ? `Agent ${args.agentId} mapped to Teams user ${r.teamsUserId}.` : `Agent ${args.agentId} mapping cleared.`;
+    }
+    case 'teams_phone_delete_agent': {
+      await messagingDel(`/TeamsPhone/Agents/${encodeURIComponent(args.agentId)}`);
+      return `Agent ${args.agentId} mapping cleared.`;
+    }
+
     // ── Shopify write policy (velaro-messaging /api/Shopify/WritePolicy) ───────
     case 'shopify_get_write_policy': {
       return JSON.stringify(await messagingGet('/Shopify/WritePolicy'), null, 2);
@@ -8154,6 +8310,9 @@ ${JSON.stringify(result, null, 2)}`;
       return lines.join('\n');
     }
 
+    // ── Billing agents + package builder ──────────────────────────────────────
+    case 'package_builder_my': return JSON.stringify(await api('GET', '/PackageBuilder/my'), null, 2);
+
     // ── Pricing Catalog ───────────────────────────────────────────────────────
     case 'pricing_catalog_list': {
       const pkgs = await api('GET', '/Pricing/catalog');

package/tool-annotations.js

@@ -26,7 +26,7 @@ const MUTATING = new Set([
   'pickup_update_config', 'payment_recovery_update_config', 'recruiting_sync_jobs',
   'ai_config_set_reply_format', 'ai_model_set_site_thinking', 'ai_model_set_site_pin',
   'entitlement_reconcile', 'entitlement_sync_stripe', 'entitlement_backfill_subscriptions',
-  'calendly_configure', 'acuity_configure', 'ms_bookings_configure',
+  'calendly_configure', 'acuity_configure', 'ms_bookings_configure', 'magento_set_sidebar_fields',
   'zoom_phone_set_config',
 ]);