@velaro/mcp-server 0.6.93 → 0.6.94

package/package.json

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

@@ -151,6 +151,18 @@ function extractLogEntries(response) {
   return [];
 }
 
+/**
+ * Body for PUT avatar/groups|workflows/{id}/override. Merge by default (only passed fields change, "" clears one);
+ * `replace: true` replaces the whole override. Mirrors cli/lib/commands/avatar.js.
+ */
+function avatarOverrideBody(args) {
+  const body = { merge: args.replace !== true };
+  for (const k of ['providerSlug', 'avatarId', 'personalityPresetSlug', 'voiceId', 'displayName', 'backgroundMode', 'backgroundValue']) {
+    if (args[k] !== undefined) body[k] = args[k];
+  }
+  return body;
+}
+
 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.'
@@ -1715,6 +1727,8 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         v20_site_id:    { type: 'number', description: 'V20 site ID to migrate TO (defaults to the authenticated site)' },
         dry_run:        { type: 'boolean', description: 'Preview what would be created without creating. Default: false.' },
         enable:         { type: 'boolean', description: 'Enable created workflows immediately. Default: false.' },
+        include_non_routing: { type: 'boolean', description: 'Also migrate v10 rules with IsRouting=false (group-assignment rules). Default: false.' },
+        route_bot_groups_to_team: { type: 'boolean', description: 'Route to the v20 team named after the v10 group even if it had a v10 bot. Default: false.' },
         team_mappings:  { type: 'array',  description: 'Override auto-resolution: [{v10GroupId, v20TeamId}]', items: { type: 'object' } },
         ai_config_mappings: { type: 'array', description: 'Override auto-resolution: [{v10GroupId, v20AiConfigId}]', items: { type: 'object' } },
       },
@@ -1729,10 +1743,25 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       properties: {
         v10_site_id: { type: 'number', description: 'V10 (Livefluence) site ID' },
         v20_site_id: { type: 'number', description: 'V20 site ID to match against (for name suggestions)' },
+        include_non_routing: { type: 'boolean', description: 'Also include v10 rules with IsRouting=false. Default: false.' },
       },
       required: ['v10_site_id'],
     },
   },
+  {
+    name: 'livefluence_create_teams',
+    description: 'Copy v10 (Livefluence) groups to v20 teams on a site. v10 is read-only; idempotent by name; "Default Group" maps to the site default team; members are not copied. Use dry_run=true first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        v10_site_id: { type: 'number', description: 'V10 (Livefluence) site ID to copy FROM' },
+        v20_site_id: { type: 'number', description: 'V20 site ID to create teams on' },
+        group_names: { type: 'array', items: { type: 'string' }, description: 'Group names to copy (default: every non-deleted v10 group)' },
+        dry_run:     { type: 'boolean', description: 'Preview without creating. Default: false.' },
+      },
+      required: ['v10_site_id', 'v20_site_id'],
+    },
+  },
 
   // ── Smart Routing Engine ──────────────────────────────────────────────────
   {
@@ -3328,19 +3357,24 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
   {
     name: 'avatar_get_group_effective',
-    description: 'Show the effective avatar settings for a group (group override field, else site default) and whether an override exists.',
-    inputSchema: { type: 'object', properties: { groupId: { type: 'number' } }, required: ['groupId'] },
+    description: 'Show the effective avatar settings (person, personality, voice, display name, backdrop) for a group, layered perWorkflow ?? perGroup ?? perSite. Pass workflowId too to see what a conversation in that workflow inside that group gets. Also returns whether each override exists.',
+    inputSchema: { type: 'object', properties: { groupId: { type: 'number', description: 'Team (group) id.' }, workflowId: { type: 'number', description: 'Optional workflow id to layer on top of the group.' } }, required: ['groupId'] },
   },
   {
     name: 'avatar_set_group_override',
-    description: 'Override avatar/personality/provider for one group. Omitted fields inherit the site default.',
+    description: 'Override the avatar person/personality/voice/display name/backdrop for one group (a group is a Team). Only the fields you pass change (merge); pass an empty string to clear one field back to the site default. A library avatarId always uses the velaro provider. Backdrop: backgroundMode none|color|gradient|image with backgroundValue (hex, "#a,#b", or an https image URL).',
     inputSchema: {
       type: 'object',
       properties: {
         groupId: { type: 'number' },
         providerSlug: { type: 'string' },
-        avatarId: { type: 'string' },
+        avatarId: { type: 'string', description: 'Library slug (see avatar_list_library), e.g. priya.' },
         personalityPresetSlug: { type: 'string' },
+        voiceId: { type: 'string', description: 'ElevenLabs voice id.' },
+        displayName: { type: 'string', description: 'Visitor-facing avatar name.' },
+        backgroundMode: { type: 'string', description: 'none | color | gradient | image. "none" = explicitly no backdrop.' },
+        backgroundValue: { type: 'string', description: 'Hex color, "#a,#b" gradient, or https image URL.' },
+        replace: { type: 'boolean', description: 'true = replace the whole override (omitted fields inherit) instead of merging.' },
       },
       required: ['groupId'],
     },
@@ -3350,9 +3384,38 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     description: 'Reset one group to the site default avatar settings (removes its override).',
     inputSchema: { type: 'object', properties: { groupId: { type: 'number' } }, required: ['groupId'] },
   },
+  {
+    name: 'avatar_get_workflow_effective',
+    description: 'Show the effective avatar settings for a workflow (workflow override, else its group, else site). Pass groupId to include a group override beneath the workflow.',
+    inputSchema: { type: 'object', properties: { workflowId: { type: 'number' }, groupId: { type: 'number' } }, required: ['workflowId'] },
+  },
+  {
+    name: 'avatar_set_workflow_override',
+    description: 'Override the avatar person/personality/voice/display name/backdrop for one workflow (wins over its group and the site). Same fields and merge semantics as avatar_set_group_override. Example: library avatar priya with the Timken HR office backdrop https://admin.velaro.com/avatar-backdrops/timken-hr-office.png for the recruiter workflow.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        workflowId: { type: 'number' },
+        providerSlug: { type: 'string' },
+        avatarId: { type: 'string' },
+        personalityPresetSlug: { type: 'string' },
+        voiceId: { type: 'string' },
+        displayName: { type: 'string' },
+        backgroundMode: { type: 'string', description: 'none | color | gradient | image' },
+        backgroundValue: { type: 'string' },
+        replace: { type: 'boolean' },
+      },
+      required: ['workflowId'],
+    },
+  },
+  {
+    name: 'avatar_reset_workflow',
+    description: 'Reset one workflow to its group / site default avatar settings (removes its override).',
+    inputSchema: { type: 'object', properties: { workflowId: { type: 'number' } }, required: ['workflowId'] },
+  },
   {
     name: 'avatar_reset_all_overrides',
-    description: 'Reset ALL group overrides for the calling site back to the site default.',
+    description: 'Reset ALL group and workflow overrides for the calling site back to the site default.',
     inputSchema: { type: 'object', properties: {} },
   },
 
@@ -5177,6 +5240,45 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['listingId'],
     },
   },
+  // -- Job Board hosted pages (package "job-board-hosted", default OFF: 403 for a site without it) --
+  {
+    name: 'jobboard_hosted_status',
+    description: 'Hosted public job pages for this site: is the package included, are the pages published, and the opaque board link, sitemap, Indeed feed and Google feed URLs (the feed URLs contain a secret key). Returns { entitled, enabled, boardUrl, sitemapUrl, indeedFeedUrl, googleFeedUrl, publicApplyEnabled, eeocSelfIdAvailable, liveListings }; { entitled:false } without the package.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'jobboard_hosted_set',
+    description: 'Publish or unpublish the hosted job pages (apply-if-present). enabled=true issues the opaque board link and feed key the first time. regenerateLink=true issues a NEW board link and every old hosted URL answers 404 (administrators only). Requires the Job Board hosted pages package (403 otherwise).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        enabled: { type: 'boolean' },
+        regenerateLink: { type: 'boolean', description: 'Retire the current board link and issue a new one (administrators only)' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'jobboard_rotate_feed_key',
+    description: 'Rotate the outbound feed key: the current Indeed and Google feed URLs stop working immediately and the response carries the new ones. Administrators only; requires the Job Board hosted pages package (403 otherwise).',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'jobboard_set_listing_pay',
+    description: 'Set or clear the pay range of a job listing (pay transparency): shown on the hosted page and in its schema.org baseSalary. A manual value is never overwritten by a feed sync. Pass clear=true to remove it. Requires the Job Board hosted pages package (403 otherwise); 404 for an id that is not on this site.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        listingId: { type: 'number' },
+        min: { type: 'number', description: 'Minimum (or only) amount, greater than 0' },
+        max: { type: 'number', description: 'Maximum amount, at least min (optional)' },
+        currency: { type: 'string', description: '3-letter ISO code, default USD' },
+        period: { type: 'string', description: 'Hour | Day | Week | Month | Year' },
+        clear: { type: 'boolean', description: 'Remove the stated pay' },
+      },
+      required: ['listingId'],
+    },
+  },
   {
     name: 'jobboard_move_application_stage',
     description: 'Move a candidate application to a new HR/agency-side pipeline stage on the applicant Kanban board (Applied, Screened, Interview, Offer, Hired, Rejected).',
@@ -6924,7 +7026,10 @@ async function handleTool(name, args) {
 
     // ── Livefluence Migration ──────────────────────────────────────────────
     case 'livefluence_export': {
-      const qs = args.v20_site_id ? `?v20SiteId=${args.v20_site_id}` : '';
+      const params = [];
+      if (args.v20_site_id) params.push(`v20SiteId=${args.v20_site_id}`);
+      if (args.include_non_routing) params.push('includeNonRouting=true');
+      const qs = params.length ? `?${params.join('&')}` : '';
       const data = await api('GET', `/DatabaseTool/V10Export/${args.v10_site_id}${qs}`);
       const lines = [
         `V10 Site ${data.v10SiteId} — ${data.ruleCount} routing rule(s), ${data.groupCount} group(s)`,
@@ -6949,6 +7054,16 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    case 'livefluence_create_teams': {
+      const result = await api('POST', '/DatabaseTool/V10CreateTeams', {
+        v10SiteId:  args.v10_site_id,
+        v20SiteId:  args.v20_site_id,
+        dryRun:     args.dry_run ?? false,
+        groupNames: args.group_names ?? [],
+      });
+      return JSON.stringify(result, null, 2);
+    }
+
     case 'livefluence_seed_url_rules': {
       const result = await api('POST', '/DatabaseTool/V10SeedUrlRules', {
         siteId: args.site_id, aiConfigId: args.ai_config_id, dryRun: !!args.dry_run, rules: args.rules,
@@ -6962,6 +7077,8 @@ async function handleTool(name, args) {
         v20SiteId:        args.v20_site_id ?? null,
         dryRun:           args.dry_run  ?? false,
         enable:           args.enable   ?? false,
+        includeNonRouting:    args.include_non_routing ?? false,
+        routeBotGroupsToTeam: args.route_bot_groups_to_team ?? false,
         teamMappings:     args.team_mappings     ?? [],
         aiConfigMappings: args.ai_config_mappings ?? [],
       });
@@ -6977,6 +7094,7 @@ async function handleTool(name, args) {
         for (const item of result.createdItems) {
           lines.push(`  [#${item.priority}] ${item.ruleName}${item.workflowId ? ` → id=${item.workflowId}` : ''}`);
           lines.push(`    Action: ${item.action}${item.v2AiConfigId ? `, aiConfigId=${item.v2AiConfigId}` : ''}${item.v2TeamId ? `, teamId=${item.v2TeamId}` : ''}`);
+          for (const u of item.unconverted ?? []) lines.push(`    not converted: ${u}`);
         }
         lines.push('');
       }
@@ -8771,12 +8889,17 @@ async function handleTool(name, args) {
       return JSON.stringify(await messagingRequest('POST', '/avatar/site-default', {
         providerSlug: args.providerSlug, avatarId: args.avatarId, personalityPresetSlug: args.personalityPresetSlug }), null, 2);
     case 'avatar_get_group_effective':
-      return JSON.stringify(await messagingRequest('GET', `/avatar/groups/${Number(args.groupId)}/effective`), null, 2);
+      return JSON.stringify(await messagingRequest('GET', `/avatar/groups/${Number(args.groupId)}/effective${args.workflowId != null ? `?workflowId=${Number(args.workflowId)}` : ''}`), null, 2);
     case 'avatar_set_group_override':
-      return JSON.stringify(await messagingRequest('PUT', `/avatar/groups/${Number(args.groupId)}/override`, {
-        providerSlug: args.providerSlug, avatarId: args.avatarId, personalityPresetSlug: args.personalityPresetSlug }), null, 2);
+      return JSON.stringify(await messagingRequest('PUT', `/avatar/groups/${Number(args.groupId)}/override`, avatarOverrideBody(args)), null, 2);
     case 'avatar_reset_group':
       return JSON.stringify(await messagingRequest('DELETE', `/avatar/groups/${Number(args.groupId)}/override`), null, 2);
+    case 'avatar_get_workflow_effective':
+      return JSON.stringify(await messagingRequest('GET', `/avatar/workflows/${Number(args.workflowId)}/effective${args.groupId != null ? `?groupId=${Number(args.groupId)}` : ''}`), null, 2);
+    case 'avatar_set_workflow_override':
+      return JSON.stringify(await messagingRequest('PUT', `/avatar/workflows/${Number(args.workflowId)}/override`, avatarOverrideBody(args)), null, 2);
+    case 'avatar_reset_workflow':
+      return JSON.stringify(await messagingRequest('DELETE', `/avatar/workflows/${Number(args.workflowId)}/override`), null, 2);
     case 'avatar_reset_all_overrides':
       return JSON.stringify(await messagingRequest('POST', '/avatar/group-overrides/reset-all', {}), null, 2);
 
@@ -10512,6 +10635,48 @@ async function handleTool(name, args) {
       return JSON.stringify(r, null, 2);
     }
 
+    case 'jobboard_hosted_status': {
+      const r = await messagingGet('/Recruiting/Hosted');
+      return JSON.stringify(r, null, 2);
+    }
+    case 'jobboard_hosted_set': {
+      const body = {};
+      if (args.enabled !== undefined) body.enabled = Boolean(args.enabled);
+      if (args.regenerateLink) body.regenerateSlug = true;
+      if (!Object.keys(body).length) throw new Error('Specify enabled and/or regenerateLink (use jobboard_hosted_status to read).');
+      const r = await messagingPut('/Recruiting/Hosted', body);
+      return JSON.stringify(r, null, 2);
+    }
+    case 'jobboard_rotate_feed_key': {
+      const r = await messagingPost('/Recruiting/Hosted/FeedKey/Rotate', {});
+      return JSON.stringify(r, null, 2);
+    }
+    case 'jobboard_set_listing_pay': {
+      const id = Number(args.listingId);
+      if (!Number.isInteger(id) || id <= 0) throw new Error('listingId must be a positive integer.');
+      let body;
+      if (args.clear) {
+        body = { clear: true };
+      } else {
+        const lo = Number(args.min);
+        if (args.min === undefined || !Number.isFinite(lo) || lo <= 0) throw new Error('min must be a number greater than 0 (or pass clear=true).');
+        body = { salaryMin: lo };
+        if (args.max !== undefined) {
+          const hi = Number(args.max);
+          if (!Number.isFinite(hi) || hi < lo) throw new Error('max must be a number greater than or equal to min.');
+          body.salaryMax = hi;
+        }
+        const cur = String(args.currency ?? 'USD').trim().toUpperCase();
+        if (!/^[A-Z]{3}$/.test(cur)) throw new Error('currency must be a 3-letter ISO code such as USD.');
+        body.salaryCurrency = cur;
+        const per = ['Hour', 'Day', 'Week', 'Month', 'Year'].find((p) => p.toLowerCase() === String(args.period ?? '').trim().toLowerCase());
+        if (!per) throw new Error('period must be one of: Hour, Day, Week, Month, Year.');
+        body.salaryPeriod = per;
+      }
+      const r = await messagingPut(`/Recruiting/Jobs/${id}/Pay`, body);
+      return JSON.stringify(r, null, 2);
+    }
+
     case 'jobboard_move_application_stage': {
       const app = await messagingPut(`/Recruiting/Applications/${args.applicationId}/Stage`, { stage: args.stage });
       return JSON.stringify(app, null, 2);