@velaro/mcp-server 0.6.94 → 0.6.95

package/package.json

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

@@ -5281,16 +5281,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.
@@ -10678,9 +10759,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': {