@velaro/mcp-server 0.6.94 → 0.6.96

package/package.json

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

@@ -1699,6 +1699,79 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
 
   // ── Livefluence Migration ─────────────────────────────────────────────────
+  {
+    name: 'livefluence_site_workflows_list',
+    description: 'Velaro staff only (superadmin). List ANOTHER v20 site\'s workflows: id, name, enabled, priority, action, team/AI target. Use after livefluence_migrate to see what exists on the destination site (e.g. 100140).',
+    inputSchema: { type: 'object', properties: { site_id: { type: 'number', description: 'V20 site ID to inspect' } }, required: ['site_id'] },
+  },
+  {
+    name: 'livefluence_site_workflows_set_enabled',
+    description: 'Velaro staff only (superadmin). Enable or disable workflows on a v20 site by ids or names. Idempotent, audit-logged. Enabling REFUSES a workflow whose trigger is not fully converted from v10 unless force_partial=true; pass v10_site_id to check each against its same-named v10 rule. Use dry_run=true first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        site_id:       { type: 'number', description: 'V20 site ID' },
+        workflow_ids:  { type: 'array', items: { type: 'number' } },
+        names:         { type: 'array', items: { type: 'string' } },
+        enabled:       { type: 'boolean', description: 'true = enable, false = disable' },
+        v10_site_id:   { type: 'number', description: 'Verify conversion against this v10 site rules' },
+        force_partial: { type: 'boolean', description: 'Enable even if v10 expression terms were not converted' },
+        dry_run:       { type: 'boolean' },
+      },
+      required: ['site_id', 'enabled'],
+    },
+  },
+  {
+    name: 'livefluence_site_workflow_create',
+    description: 'Velaro staff only (superadmin). Create a workflow on a v20 site from a nodes-blob JSON (object of nodes with a trigger node). Disabled unless enabled=true. Idempotent by name; validates that referenced AI configs/teams exist on the site. Use dry_run=true first.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        site_id:      { type: 'number' },
+        name:         { type: 'string' },
+        nodes_blob:   { type: 'string', description: 'JSON string of the nodes object' },
+        trigger_type: { type: 'string', description: 'Default conversation_opened' },
+        enabled:      { type: 'boolean' },
+        dry_run:      { type: 'boolean' },
+      },
+      required: ['site_id', 'name', 'nodes_blob'],
+    },
+  },
+  {
+    name: 'livefluence_site_workflow_set_action',
+    description: 'Velaro staff only (superadmin). Set a workflow action node on a v20 site to transferToAI {aiConfigId} or routeToTeam {teamId}. Validates the target exists on that site. Idempotent, audit-logged.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        site_id:     { type: 'number' },
+        workflow_id: { type: 'number' },
+        action_type: { type: 'string', enum: ['transferToAI', 'routeToTeam'] },
+        target_id:   { type: 'number', description: 'aiConfigId for transferToAI, teamId for routeToTeam' },
+        dry_run:     { type: 'boolean' },
+      },
+      required: ['site_id', 'workflow_id', 'action_type', 'target_id'],
+    },
+  },
+  {
+    name: 'livefluence_site_rules_list',
+    description: 'Velaro staff only (superadmin). List a v20 site Rules (e.g. the use-ai rules seeded by livefluence_seed_url_rules) with enabled state.',
+    inputSchema: { type: 'object', properties: { site_id: { type: 'number' } }, required: ['site_id'] },
+  },
+  {
+    name: 'livefluence_site_rules_set_enabled',
+    description: 'Velaro staff only (superadmin). Switch v20 Rules off/on without deleting them (reversible), by rule ids or by trigger (e.g. use-ai). Use to turn off the url-rules seeded earlier so they do not double-route with migrated workflows. Idempotent, audit-logged.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        site_id:  { type: 'number' },
+        rule_ids: { type: 'array', items: { type: 'number' } },
+        trigger:  { type: 'string', description: 'Every rule with this trigger, e.g. use-ai' },
+        enabled:  { type: 'boolean' },
+        dry_run:  { type: 'boolean' },
+      },
+      required: ['site_id', 'enabled'],
+    },
+  },
   {
     name: 'livefluence_seed_url_rules',
     description: 'Velaro staff only. Seed v20 use-ai routing rules on a target site from v10 URL rules. Each rule matches "url contains <path>" with scheme/host stripped (path-only), so a demo page path triggers the same rule as the customer real URL. Idempotent. Domain-only URLs are skipped. Use dry_run=true first.',
@@ -2160,6 +2233,20 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['jobId'],
     },
   },
+  {
+    name: 'index_create',
+    description: 'Velaro staff only. Create a named virtual knowledge index on ANY site (e.g. "100140-troubleshooting", "100140-manual-catalog") so uploads/publishes with that indexName work. Idempotent: returns the existing index if the name already exists. Respects the site index quota. Wraps POST KnowledgeSetup/Staff/{siteId}/create-index.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId:                { type: 'number', description: 'Target site ID' },
+        indexName:             { type: 'string', description: 'Index name (lowercased, a-z 0-9 and dashes)' },
+        purpose:               { type: 'string', enum: ['general', 'troubleshooting', 'catalog'], description: 'Index purpose (default general)' },
+        excludeFromAllSources: { type: 'boolean', description: 'Keep out of the ["*"] all-sources search' },
+      },
+      required: ['siteId', 'indexName'],
+    },
+  },
   {
     name: 'uploaded_file_reindex',
     description: 'Re-index an already-uploaded AI training file from blob storage — use when a file shows 0 chunks (e.g. PDF uploaded before PDF support was added). Reads from blob and re-runs full ingestion. Use index_status after ~30s to verify chunks appear.',
@@ -5281,16 +5368,97 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
   {
     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).',
+    description: 'Move a candidate application to a new HR/agency-side pipeline stage on the applicant Kanban board. Default stages: Applied, Screened, Interview, Offer, Hired, Rejected; a site with the Job board pipeline package uses its own configured stage keys (see jobboard_pipeline_get). Optional note is recorded in the stage history.',
     inputSchema: {
       type: 'object',
       properties: {
         applicationId: { type: 'number' },
-        stage: { type: 'string', description: 'Applied | Screened | Interview | Offer | Hired | Rejected' },
+        stage: { type: 'string', description: 'A stage key from jobboard_pipeline_get (default list: Applied | Screened | Interview | Offer | Hired | Rejected)' },
+        note: { type: 'string', description: 'Optional note recorded in the stage history (2000 characters max)' },
       },
       required: ['applicationId', 'stage'],
     },
   },
+  // -- Job Board pipeline (package "job-board-pipeline", default OFF: 403 job_board_pipeline_not_entitled without it, except jobboard_pipeline_get) --
+  {
+    name: 'jobboard_pipeline_get',
+    description: 'The recruiter pipeline stages for this site. Returns { entitled, source: "default"|"caseType", caseTypeId, stages:[{key,label,color,applicantVisible,applicantLabel}] }. Without the Job board pipeline package it returns the default list with entitled:false (stage moves still work on the default stages).',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'jobboard_pipeline_set',
+    description: 'Replace the pipeline stages (1 to 12, unique keys up to 64 characters). Removing a stage that still holds applications is refused with a 400 naming the count; move them first. Requires the Job board pipeline package (403 otherwise). Applicants see only stages with applicantVisible=true (using applicantLabel or label); every other stage shows as In review.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        stages: {
+          type: 'array',
+          description: 'The full ordered stage list',
+          items: {
+            type: 'object',
+            properties: {
+              key: { type: 'string' },
+              label: { type: 'string' },
+              color: { type: 'string', description: '#rrggbb (optional)' },
+              applicantVisible: { type: 'boolean' },
+              applicantLabel: { type: 'string', description: 'Name applicants see (optional)' },
+            },
+            required: ['key', 'label'],
+          },
+        },
+      },
+      required: ['stages'],
+    },
+  },
+  {
+    name: 'jobboard_application_history',
+    description: 'Stage, note and assignment history of one application, newest first: { events:[{id,kind:"Stage"|"Note"|"Assign",fromStage,toStage,actorType:"User"|"ApiKey"|"CaseSync"|"System",actorId,at,note}] }. For an Assign event the new recruiter is in note (empty = unassigned) and toStage is only the stage at that time. Requires the Job board pipeline package (403 otherwise); 404 for an id not on this site.',
+    inputSchema: { type: 'object', properties: { applicationId: { type: 'number' } }, required: ['applicationId'] },
+  },
+  {
+    name: 'jobboard_application_note',
+    description: 'Add an internal note to an application (1 to 2000 characters). Never shown to the applicant. Requires the Job board pipeline package (403 otherwise).',
+    inputSchema: {
+      type: 'object',
+      properties: { applicationId: { type: 'number' }, note: { type: 'string' } },
+      required: ['applicationId', 'note'],
+    },
+  },
+  {
+    name: 'jobboard_application_assign',
+    description: 'Assign a recruiter to an application (free text up to 200 characters, for example an email). Pass assignedTo as null or an empty string to unassign. Requires the Job board pipeline package (403 otherwise).',
+    inputSchema: {
+      type: 'object',
+      properties: { applicationId: { type: 'number' }, assignedTo: { type: ['string', 'null'] } },
+      required: ['applicationId'],
+    },
+  },
+  {
+    name: 'jobboard_retention_get',
+    description: 'Applicant record retention settings: { enabled, dryRun, retentionDays, isFederalContractor, legalHold, floorDays, effectiveDays, lastRunAt, lastRunDeleted, lastRunWouldDelete }. Records are never deleted before 1 year (2 years for federal contractors; 29 CFR 1602.14), so effectiveDays is never below floorDays. Requires the Job board pipeline package (403 otherwise).',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'jobboard_retention_set',
+    description: 'Change retention settings (apply-if-present). retentionDays below the legal floor is accepted and the floor applies. legalHold=true stops all deletion. Administrators only; requires the Job board pipeline package (403 otherwise).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        enabled: { type: 'boolean' },
+        dryRun: { type: 'boolean', description: 'Count only, never delete' },
+        retentionDays: { type: 'number' },
+        isFederalContractor: { type: 'boolean' },
+        legalHold: { type: 'boolean' },
+        confirm: { type: 'boolean', description: 'Required true when dryRun=false or legalHold=false (this can start real deletion or lift a hold)' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'jobboard_retention_run',
+    description: 'Run retention now. dryRun defaults to true: counts what is due and deletes nothing. dryRun=false really deletes records past retention (never before the legal floor, never under a legal hold). Returns counts only: { dryRun, due, deleted, resumesDeleted, skippedLegalHold, floorDays }. Administrators only; requires the Job board pipeline package (403 otherwise).',
+    inputSchema: { type: 'object', properties: { dryRun: { type: 'boolean', description: 'Default true' }, confirm: { type: 'boolean', description: 'Required true when dryRun=false (permanently deletes records)' } }, required: [] },
+  },
 
   // ── Velaro Appointments ──────────────────────────────────────────────────────
   // Backend: server/Velaro.Messaging/Controllers/AppointmentsController.cs.
@@ -7064,6 +7232,47 @@ async function handleTool(name, args) {
       return JSON.stringify(result, null, 2);
     }
 
+    case 'livefluence_site_workflows_list': {
+      const result = await api('GET', `/DatabaseTool/SiteWorkflows/${args.site_id}`);
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'livefluence_site_workflows_set_enabled': {
+      const result = await api('POST', '/DatabaseTool/SiteWorkflows/SetEnabled', {
+        siteId: args.site_id, workflowIds: args.workflow_ids ?? [], names: args.names ?? [],
+        enabled: !!args.enabled, dryRun: !!args.dry_run, forcePartial: !!args.force_partial, v10SiteId: args.v10_site_id ?? null,
+      });
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'livefluence_site_workflow_create': {
+      const result = await api('POST', '/DatabaseTool/SiteWorkflows/Create', {
+        siteId: args.site_id, name: args.name, triggerType: args.trigger_type ?? 'conversation_opened',
+        nodesBlob: typeof args.nodes_blob === 'string' ? args.nodes_blob : JSON.stringify(args.nodes_blob),
+        enabled: !!args.enabled, dryRun: !!args.dry_run,
+      });
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'livefluence_site_workflow_set_action': {
+      const result = await api('POST', '/DatabaseTool/SiteWorkflows/SetAction', {
+        siteId: args.site_id, workflowId: args.workflow_id, actionType: args.action_type, targetId: args.target_id, dryRun: !!args.dry_run,
+      });
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'livefluence_site_rules_list': {
+      const result = await api('GET', `/DatabaseTool/SiteRules/${args.site_id}`);
+      return JSON.stringify(result, null, 2);
+    }
+
+    case 'livefluence_site_rules_set_enabled': {
+      const result = await api('POST', '/DatabaseTool/SiteRules/SetEnabled', {
+        siteId: args.site_id, ruleIds: args.rule_ids ?? [], trigger: args.trigger ?? null, enabled: !!args.enabled, dryRun: !!args.dry_run,
+      });
+      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,
@@ -7545,6 +7754,15 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    case 'index_create': {
+      if (!args.siteId || !args.indexName) return 'siteId and indexName are required.';
+      const body = { indexName: args.indexName, purpose: args.purpose ?? 'general' };
+      if (args.excludeFromAllSources !== undefined) body.excludeFromAllSources = args.excludeFromAllSources;
+      const idx = await messagingRequest('POST', `/KnowledgeSetup/Staff/${encodeURIComponent(args.siteId)}/create-index`, body);
+      if (idx?.error) return `Create index error: ${idx.error}`;
+      return `Index ready on site ${args.siteId}: ${idx?.name} (id=${idx?.id}, purpose=${idx?.purpose}, excludeFromAllSources=${!!idx?.excludeFromAllSources}).`;
+    }
+
     case 'uploaded_files_list': {
       const files = await messagingRequest('GET', '/uploadedFiles/list/AI');
       if (!Array.isArray(files) || !files.length) return 'No AI training files uploaded for this site.';
@@ -10678,9 +10896,72 @@ async function handleTool(name, args) {
     }
 
     case 'jobboard_move_application_stage': {
-      const app = await messagingPut(`/Recruiting/Applications/${args.applicationId}/Stage`, { stage: args.stage });
+      const id = Number(args.applicationId);
+      if (!Number.isInteger(id) || id <= 0) throw new Error('applicationId must be a positive integer.');
+      const stage = String(args.stage ?? '').trim();
+      if (!stage) throw new Error('stage is required.');
+      const body = { stage };
+      if (args.note !== undefined && String(args.note).trim()) {
+        if (String(args.note).length > 2000) throw new Error('note must be 2000 characters or fewer.');
+        body.note = String(args.note).trim();
+      }
+      const app = await messagingPut(`/Recruiting/Applications/${id}/Stage`, body);
       return JSON.stringify(app, null, 2);
     }
+    case 'jobboard_pipeline_get': {
+      return JSON.stringify(await messagingGet('/Recruiting/Pipeline'), null, 2);
+    }
+    case 'jobboard_pipeline_set': {
+      const stages = args.stages;
+      if (!Array.isArray(stages) || stages.length < 1 || stages.length > 12) throw new Error('stages must be an array of 1 to 12 stages.');
+      const keys = new Set();
+      for (const s of stages) {
+        if (!s || typeof s.key !== 'string' || !s.key.trim() || s.key.length > 64) throw new Error('every stage needs a key (up to 64 characters).');
+        if (typeof s.label !== 'string' || !s.label.trim()) throw new Error(`stage ${s.key} needs a label.`);
+        if (keys.has(s.key)) throw new Error(`duplicate stage key: ${s.key}.`);
+        keys.add(s.key);
+      }
+      return JSON.stringify(await messagingPut('/Recruiting/Pipeline', { stages }), null, 2);
+    }
+    case 'jobboard_application_history': {
+      const id = Number(args.applicationId);
+      if (!Number.isInteger(id) || id <= 0) throw new Error('applicationId must be a positive integer.');
+      return JSON.stringify(await messagingGet(`/Recruiting/Applications/${id}/History`), null, 2);
+    }
+    case 'jobboard_application_note': {
+      const id = Number(args.applicationId);
+      if (!Number.isInteger(id) || id <= 0) throw new Error('applicationId must be a positive integer.');
+      const note = String(args.note ?? '').trim();
+      if (!note || note.length > 2000) throw new Error('note must be 1 to 2000 characters.');
+      return JSON.stringify(await messagingPost(`/Recruiting/Applications/${id}/Notes`, { note }), null, 2);
+    }
+    case 'jobboard_application_assign': {
+      const id = Number(args.applicationId);
+      if (!Number.isInteger(id) || id <= 0) throw new Error('applicationId must be a positive integer.');
+      const who = String(args.assignedTo ?? '').trim();
+      if (who.length > 200) throw new Error('assignedTo must be 200 characters or fewer.');
+      return JSON.stringify(await messagingPut(`/Recruiting/Applications/${id}/Assign`, { assignedTo: who || null }), null, 2);
+    }
+    case 'jobboard_retention_get': {
+      return JSON.stringify(await messagingGet('/Recruiting/Retention'), null, 2);
+    }
+    case 'jobboard_retention_set': {
+      const body = {};
+      for (const k of ['enabled', 'dryRun', 'isFederalContractor', 'legalHold']) if (args[k] !== undefined) body[k] = Boolean(args[k]);
+      if (args.retentionDays !== undefined) {
+        const n = Number(args.retentionDays);
+        if (!Number.isInteger(n) || n < 1 || n > 36500) throw new Error('retentionDays must be a whole number from 1 to 36500.');
+        body.retentionDays = n;
+      }
+      if (!Object.keys(body).length) throw new Error('Specify at least one retention setting (use jobboard_retention_get to read).');
+      if ((body.dryRun === false || body.legalHold === false) && args.confirm !== true) throw new Error('dryRun=false or legalHold=false can start real deletion of applicant records or lift a legal hold. Preview with jobboard_retention_run first, then repeat with confirm=true.');
+      return JSON.stringify(await messagingPut('/Recruiting/Retention', body), null, 2);
+    }
+    case 'jobboard_retention_run': {
+      const dry = args.dryRun === undefined ? true : Boolean(args.dryRun);
+      if (!dry && args.confirm !== true) throw new Error('dryRun=false permanently deletes applicant records past retention. Preview first (dryRun=true), then repeat with confirm=true.');
+      return JSON.stringify(await messagingPost(`/Recruiting/Retention/Run?dryRun=${dry ? 'true' : 'false'}`, {}), null, 2);
+    }
 
     // -- Velaro Appointments --
     case 'appointments_manual_book': {