@velaro/mcp-server 2.0.8 → 2.0.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/mcp-server",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "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/parity/product-match.customer.js

@@ -0,0 +1,66 @@
+// velaro product-match: the per-site Product Match matrix. Site scope comes from the credential only, never from arguments.
+// Parity module (CLI group `product-match` -> MCP tools). Needs the Product Match package (EnableProductMatch).
+
+const enc = encodeURIComponent;
+const need = (a, ...ks) => { for (const k of ks) if (a[k] === undefined || a[k] === null || a[k] === '') throw new Error(k + ' is required'); };
+const pid = (v, n = 'id') => { const x = Number(v); if (!Number.isInteger(x) || x <= 0) throw new Error(n + ' must be a positive integer'); return x; };
+
+export const tools = [
+  {
+    name: 'product_match_lookup',
+    description: 'Look up which of the site\'s OWN catalog products matches a part number, SKU, competitor model or discontinued part. Deterministic (no model decides it): only approved matrix rows, only SKUs that exist in the site catalog, never a deny-listed brand. Returns status (matched, own_product, no_match, unapproved, loop, not_in_catalog), the recommendations and whether to hand off to a person. Calls POST /BusinessActions/match_product/Execute.',
+    inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'The part number, SKU or model as the customer wrote it' } }, required: ['query'] },
+  },
+  {
+    name: 'product_match_list',
+    description: 'List the site\'s Product Match matrix rows (source, target SKU, match type, approved). Calls GET /ProductMatch/Entries.',
+    inputSchema: { type: 'object', properties: { q: { type: 'string' }, page: { type: 'number' } } },
+  },
+  {
+    name: 'product_match_import',
+    description: 'Import a cross-reference matrix from CSV text (header row with a source column such as "Competitor SKU" and a target column such as "Our SKU"; optional "Match Type" exact|equivalent|supersedes, "Approved" yes/no, "Notes"). Rows are NOT approved unless the Approved column says yes. Upserts by source and target. Calls POST /ProductMatch/ImportFile.',
+    inputSchema: { type: 'object', properties: { csv: { type: 'string', description: 'The CSV file content' } }, required: ['csv'] },
+  },
+  {
+    name: 'product_match_approve',
+    description: 'Approve or revoke one matrix row. Only approved rows are ever recommended. Calls PUT /ProductMatch/Entries/{id}/Approve.',
+    inputSchema: { type: 'object', properties: { id: { type: 'number' }, approved: { type: 'boolean', description: 'default true' } }, required: ['id'] },
+  },
+  {
+    name: 'product_match_remove',
+    description: 'Delete one matrix row. Calls DELETE /ProductMatch/Entries/{id}.',
+    inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] },
+  },
+  {
+    name: 'product_match_deny_terms',
+    description: 'Read, or replace (when terms is given), the brands and competitors the bot must never name in a Product Match reply. Calls GET or PUT /ProductMatch/DenyTerms.',
+    inputSchema: { type: 'object', properties: { terms: { type: 'array', items: { type: 'string' } } } },
+  },
+];
+
+export const handlers = {
+  product_match_lookup: async (a, ctx) => {
+    need(a, 'query');
+    return ctx.messagingPost('/BusinessActions/match_product/Execute', { query: String(a.query) });
+  },
+  product_match_list: async (a, ctx) => {
+    const p = new URLSearchParams();
+    if (a.q) p.set('q', String(a.q));
+    p.set('page', String(a.page ?? 1));
+    return ctx.messagingGet('/ProductMatch/Entries?' + p.toString());
+  },
+  product_match_import: async (a, ctx) => {
+    need(a, 'csv');
+    return ctx.messagingPost('/ProductMatch/ImportFile', { fileName: 'matrix.csv', contentBase64: Buffer.from(String(a.csv), 'utf8').toString('base64') });
+  },
+  product_match_approve: async (a, ctx) => {
+    return ctx.messagingPut('/ProductMatch/Entries/' + pid(a.id) + '/Approve', { approved: a.approved !== false });
+  },
+  product_match_remove: async (a, ctx) => {
+    return ctx.messagingDel('/ProductMatch/Entries/' + pid(a.id));
+  },
+  product_match_deny_terms: async (a, ctx) => {
+    if (Array.isArray(a.terms)) return ctx.messagingPut('/ProductMatch/DenyTerms', { terms: a.terms.map(String) });
+    return ctx.messagingGet('/ProductMatch/DenyTerms');
+  },
+};

package/parity/report-custom.customer.js

@@ -0,0 +1,37 @@
+// MCP parity for `velaro report custom-catalog | custom-run` (cli/lib/commands/report.js). Backend: velaro-messaging
+// CustomReportsController (api/v1/custom-reports). Managers and Administrators only. Site from the credential.
+
+export const tools = [
+  {
+    name: 'report_custom_catalog_get',
+    description: 'What the custom report builder offers per object (tickets, deals, contacts, companies): group-bys, measures, filters.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'report_custom_run',
+    description: 'Run a custom report: object, groupBy and measure from report_custom_catalog_get, optional filters and a day range (default 90, max 366).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        object: { type: 'string', enum: ['tickets', 'deals', 'contacts', 'companies'] },
+        groupBy: { type: 'string' },
+        measure: { type: 'string' },
+        days: { type: 'number' },
+        filters: { type: 'object', additionalProperties: { type: 'string' } },
+      },
+      required: ['object', 'groupBy'],
+    },
+  },
+];
+
+export const handlers = {
+  report_custom_catalog_get: async (_a, ctx) => (await ctx.messagingGet('/api/v1/custom-reports/catalog'))?.data,
+  report_custom_run: async (a, ctx) => {
+    const end = new Date();
+    const start = new Date(end.getTime() - Math.min(366, Math.max(1, a.days ?? 90)) * 86400000);
+    const r = await ctx.messagingPost('/api/v1/custom-reports/run', {
+      object: a.object, groupBy: a.groupBy, measure: a.measure ?? 'count', start: start.toISOString(), end: end.toISOString(), filters: a.filters ?? {},
+    });
+    return { rows: r?.data?.rows ?? [], meta: r?.meta ?? {} };
+  },
+};

package/parity/ticket.customer.js

@@ -0,0 +1,229 @@
+// MCP parity for `velaro ticket` (cli/lib/commands/ticket.js). Backend: velaro-messaging help desk parity endpoints
+// (docs/architecture/ticketing-hubspot-parity-plan.md). Site from the credential, never an argument.
+
+const TYPES = ['contact', 'company', 'deal', 'call'];
+const ENTITIES = ['ticket', 'company'];
+const FIELD_TYPES = ['Text', 'Number', 'Date', 'Dropdown', 'Checkbox', 'Currency'];
+
+const data = (r) => (r && typeof r === 'object' && 'data' in r ? r.data : r);
+const entityBase = (e) => (e === 'company' ? '/api/v1/company-properties' : '/api/v1/ticket-properties');
+const recordBase = (e, id) => (e === 'company' ? `/api/v1/companies/${encodeURIComponent(id)}/properties` : `/api/v1/tickets/${encodeURIComponent(id)}/properties`);
+
+const ticketId = { type: 'number', description: 'Ticket id (the ticket conversation id).' };
+
+export const tools = [
+  {
+    name: 'ticket_association_list',
+    description: 'List the contacts, companies, deals and calls linked to a ticket. The ticket\'s own contact and that contact\'s company are always listed (primary / from contact). Calls include whether a recording exists.',
+    inputSchema: { type: 'object', properties: { ticketId }, required: ['ticketId'] },
+  },
+  {
+    name: 'ticket_association_add',
+    description: 'Link a contact, company, deal or call to a ticket (HubSpot-style association). targetId is the contact id, CRM company id, deal id or call record id. Optional label such as "Billing contact".',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ticketId,
+        type: { type: 'string', enum: TYPES },
+        targetId: { type: 'number' },
+        label: { type: 'string', description: 'Optional association label (64 characters max).' },
+      },
+      required: ['ticketId', 'type', 'targetId'],
+    },
+  },
+  {
+    name: 'ticket_association_remove',
+    description: 'Unlink a contact, company, deal or call from a ticket.',
+    inputSchema: { type: 'object', properties: { ticketId, type: { type: 'string', enum: TYPES }, targetId: { type: 'number' } }, required: ['ticketId', 'type', 'targetId'] },
+  },
+  {
+    name: 'ticket_company_list',
+    description: 'List the tickets of one company: tickets linked to it plus tickets of its contacts. openOnly limits to tickets that are not resolved or closed.',
+    inputSchema: { type: 'object', properties: { companyId: { type: 'number' }, openOnly: { type: 'boolean' } }, required: ['companyId'] },
+  },
+  {
+    name: 'ticket_property_list',
+    description: 'List the custom property definitions for tickets (or companies): id, label, type, dropdown options, and whether stages may require it.',
+    inputSchema: { type: 'object', properties: { entity: { type: 'string', enum: ENTITIES, description: 'Default ticket.' } } },
+  },
+  {
+    name: 'ticket_property_define',
+    description: 'Create or update a custom property for tickets (or companies). Administrator only. Pass id to update. Dropdown needs options.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        entity: { type: 'string', enum: ENTITIES },
+        id: { type: 'number', description: 'Existing property id to update.' },
+        label: { type: 'string' },
+        fieldType: { type: 'string', enum: FIELD_TYPES },
+        options: { type: 'array', items: { type: 'string' } },
+        isRequired: { type: 'boolean', description: 'Marks it as one pipeline stages can require.' },
+        sortOrder: { type: 'number' },
+      },
+      required: ['label', 'fieldType'],
+    },
+  },
+  {
+    name: 'ticket_property_archive',
+    description: 'Archive (remove) a ticket or company property definition. Administrator only. Saved values stay in the database but stop showing.',
+    inputSchema: { type: 'object', properties: { entity: { type: 'string', enum: ENTITIES }, id: { type: 'number' } }, required: ['id'] },
+  },
+  {
+    name: 'ticket_property_get',
+    description: 'Get the custom property values of one ticket (or company), with each property\'s label and type.',
+    inputSchema: { type: 'object', properties: { entity: { type: 'string', enum: ENTITIES }, recordId: { type: 'number' } }, required: ['recordId'] },
+  },
+  {
+    name: 'ticket_property_set',
+    description: 'Set custom property values on a ticket (or company). values maps property id to value; an empty string clears it. Values are type-checked (number, date yyyy-mm-dd, true/false, dropdown option).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        entity: { type: 'string', enum: ENTITIES },
+        recordId: { type: 'number' },
+        values: { type: 'object', additionalProperties: { type: 'string' } },
+      },
+      required: ['recordId', 'values'],
+    },
+  },
+  {
+    name: 'ticket_pipeline_list',
+    description: 'List ticket pipelines with their stages (stage id, name, the ticket status it stands for, required property ids).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'ticket_pipeline_save',
+    description: 'Create or update a ticket pipeline. Administrator only. Every pipeline needs at least one stage for each status (new, open, pending, resolved, closed). requiredPropertyIds must be ticket property ids.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Existing pipeline id to update.' },
+        name: { type: 'string' },
+        isDefault: { type: 'boolean', description: 'New tickets start in the default pipeline.' },
+        stages: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', description: 'Stable stage id; derived from the name when omitted.' },
+              name: { type: 'string' },
+              status: { type: 'string', enum: ['new', 'open', 'pending', 'resolved', 'closed'] },
+              requiredPropertyIds: { type: 'array', items: { type: 'number' } },
+            },
+            required: ['name', 'status'],
+          },
+        },
+      },
+      required: ['name', 'stages'],
+    },
+  },
+  {
+    name: 'ticket_pipeline_board_get',
+    description: 'Get a pipeline board: open tickets (and tickets resolved or closed in the last closedDays days) grouped by stage. Newest 500.',
+    inputSchema: { type: 'object', properties: { pipelineId: { type: 'number' }, closedDays: { type: 'number' } }, required: ['pipelineId'] },
+  },
+  {
+    name: 'ticket_pipeline_move',
+    description: 'Move a ticket to a pipeline stage. If the stage requires properties that are empty, the move is refused and the missing ones are listed. Moving to a resolved or closed stage resolves or closes the ticket.',
+    inputSchema: { type: 'object', properties: { ticketId, stageId: { type: 'string' }, pipelineId: { type: 'number' } }, required: ['ticketId', 'stageId'] },
+  },
+  {
+    name: 'ticket_view_list',
+    description: 'List Help Desk ticket views: built-in ones (My open, Unassigned, All open, Waiting on customer, SLA breached) and saved ones visible to you.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'ticket_view_save',
+    description: 'Create or update a saved ticket view. Sharing with a team or everyone needs a manager or administrator. Filters: status, priority, category, teamId, assignedUserId, assignedToMe, unassigned, overdue, slaBreached, tagId, search, propertyFieldId, propertyValue, sort.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number' },
+        name: { type: 'string' },
+        visibility: { type: 'string', enum: ['personal', 'team', 'everyone'] },
+        teamId: { type: 'number' },
+        filters: { type: 'object' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'ticket_view_delete',
+    description: 'Delete a saved ticket view you own (or a shared one, as a manager).',
+    inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] },
+  },
+  {
+    name: 'ticket_playbook_list',
+    description: 'List playbooks (guided scripts with questions) for tickets, calls or deals, with their steps. Step ids are the keys for ticket_playbook_respond answers.',
+    inputSchema: { type: 'object', properties: { appliesTo: { type: 'string', enum: ['ticket', 'call', 'deal'] } } },
+  },
+  {
+    name: 'ticket_playbook_respond',
+    description: 'Save playbook answers on a ticket, call or deal (answers keyed by step id). Answers mapped to ticket properties update them; an internal note records the answers.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        playbookId: { type: 'number' },
+        recordType: { type: 'string', enum: ['ticket', 'call', 'deal'] },
+        recordId: { type: 'number' },
+        answers: { type: 'object', additionalProperties: { type: 'string' } },
+      },
+      required: ['playbookId', 'recordType', 'recordId'],
+    },
+  },
+  {
+    name: 'ticket_portal_link_get',
+    description: 'Get the customer portal link (customers sign in with an email code, see all their requests, open new ones, search help articles).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'ticket_portal_link_rotate',
+    description: 'Replace the customer portal link with a new one; the old link stops working. Administrator only.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'ticket_sla_policy_list',
+    description: 'List SLA policies: priority, first response / next response / resolution minutes, business hours only, schedule, pause while waiting on the customer.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+export const handlers = {
+  ticket_association_list: async (a, ctx) => data(await ctx.messagingGet(`/api/v1/tickets/${encodeURIComponent(a.ticketId)}/associations`)),
+  ticket_association_add: async (a, ctx) =>
+    data(await ctx.messagingPost(`/api/v1/tickets/${encodeURIComponent(a.ticketId)}/associations`, { type: a.type, targetId: a.targetId, label: a.label ?? null })),
+  ticket_association_remove: async (a, ctx) =>
+    data(await ctx.messagingDel(`/api/v1/tickets/${encodeURIComponent(a.ticketId)}/associations/${encodeURIComponent(a.type)}/${encodeURIComponent(a.targetId)}`)),
+  ticket_company_list: async (a, ctx) =>
+    data(await ctx.messagingGet(`/api/v1/companies/${encodeURIComponent(a.companyId)}/tickets?openOnly=${a.openOnly ? 'true' : 'false'}`)),
+  ticket_property_list: async (a, ctx) => data(await ctx.messagingGet(entityBase(a.entity))),
+  ticket_property_define: async (a, ctx) => {
+    const body = { label: a.label, fieldType: a.fieldType, options: a.options ?? [], isRequired: !!a.isRequired, sortOrder: a.sortOrder ?? 0 };
+    return data(a.id ? await ctx.messagingPut(`${entityBase(a.entity)}/${encodeURIComponent(a.id)}`, body) : await ctx.messagingPost(entityBase(a.entity), body));
+  },
+  ticket_property_archive: async (a, ctx) => data(await ctx.messagingDel(`${entityBase(a.entity)}/${encodeURIComponent(a.id)}`)),
+  ticket_property_get: async (a, ctx) => data(await ctx.messagingGet(recordBase(a.entity, a.recordId))),
+  ticket_property_set: async (a, ctx) => data(await ctx.messagingPut(recordBase(a.entity, a.recordId), a.values ?? {})),
+  ticket_pipeline_list: async (_a, ctx) => data(await ctx.messagingGet('/api/v1/ticket-pipelines')),
+  ticket_pipeline_save: async (a, ctx) => {
+    const body = { name: a.name, isDefault: !!a.isDefault, stages: a.stages ?? [] };
+    return data(a.id ? await ctx.messagingPut(`/api/v1/ticket-pipelines/${encodeURIComponent(a.id)}`, body) : await ctx.messagingPost('/api/v1/ticket-pipelines', body));
+  },
+  ticket_pipeline_board_get: async (a, ctx) =>
+    data(await ctx.messagingGet(`/api/v1/ticket-pipelines/${encodeURIComponent(a.pipelineId)}/board?closedDays=${encodeURIComponent(a.closedDays ?? 14)}`)),
+  ticket_pipeline_move: async (a, ctx) =>
+    data(await ctx.messagingPut(`/api/v1/tickets/${encodeURIComponent(a.ticketId)}/stage`, { pipelineId: a.pipelineId ?? null, stageId: a.stageId })),
+  ticket_view_list: async (_a, ctx) => data(await ctx.messagingGet('/api/v1/ticket-views')),
+  ticket_view_save: async (a, ctx) => {
+    const body = { name: a.name, visibility: a.visibility ?? 'personal', teamId: a.teamId ?? null, filters: a.filters ?? {} };
+    return data(a.id ? await ctx.messagingPut(`/api/v1/ticket-views/${encodeURIComponent(a.id)}`, body) : await ctx.messagingPost('/api/v1/ticket-views', body));
+  },
+  ticket_view_delete: async (a, ctx) => data(await ctx.messagingDel(`/api/v1/ticket-views/${encodeURIComponent(a.id)}`)),
+  ticket_sla_policy_list: async (_a, ctx) => ({ policies: await ctx.messagingGet('/Ticket/sla-policies') }),
+  ticket_playbook_list: async (a, ctx) =>
+    data(await ctx.messagingGet(`/api/v1/playbooks${a.appliesTo ? `?appliesTo=${encodeURIComponent(a.appliesTo)}` : ''}`)),
+  ticket_playbook_respond: async (a, ctx) =>
+    data(await ctx.messagingPost(`/api/v1/playbooks/${encodeURIComponent(a.playbookId)}/responses`, { recordType: a.recordType, recordId: a.recordId, answers: a.answers ?? {} })),
+  ticket_portal_link_get: async (_a, ctx) => data(await ctx.messagingGet('/api/v1/ticket-portal')),
+  ticket_portal_link_rotate: async (_a, ctx) => data(await ctx.messagingPost('/api/v1/ticket-portal/rotate', {})),
+};