@velaro/mcp-server 1.0.2 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/mcp-server",
-  "version": "1.0.2",
+  "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": {
@@ -45,6 +45,8 @@
     "tool-annotations.js",
     "log-search.js",
     "messaging-base.js",
+    "parity/loader.js",
+    "parity/*.customer.js",
     "workflow-schedule.js",
     "server.json",
     "README.md"

package/parity/actions.customer.js

@@ -0,0 +1,39 @@
+// velaro actions: shared business actions. Site scope comes from the credential only.
+// Parity module (CLI group -> MCP tools).
+
+const enc = encodeURIComponent;
+const qs = (o) => { const p = new URLSearchParams(); for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v)); const s = p.toString(); return s ? '?' + s : ''; };
+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; };
+const need = (a, ...ks) => { for (const k of ks) if (a[k] === undefined || a[k] === null || a[k] === '') throw new Error(k + ' is required'); };
+
+export const tools = [
+  {
+    name: 'actions_list',
+    description: 'List registered business actions with kind (read or write), data class and AI skill tool names.',
+    inputSchema: {"type":"object","properties":{}},
+  },
+  {
+    name: 'actions_route',
+    description: 'Deterministically route a free-text request to the matching business action(s).',
+    inputSchema: {"type":"object","properties":{"text":{"type":"string","description":"The request text"},"max":{"type":"number","description":"Max matches (default 3)"}},"required":["text"]},
+  },
+  {
+    name: 'actions_run',
+    description: 'Execute a business action as the authenticated agent. Writes honour idempotencyKey: the same key returns the same result, never a duplicate.',
+    inputSchema: {"type":"object","properties":{"name":{"type":"string","description":"Action name from actions_list"},"request":{"type":"object","additionalProperties":true,"description":"Request body for the action"},"idempotencyKey":{"type":"string","description":"For writes, repeat the same key to get the same result"}},"required":["name"]},
+  },
+];
+
+export const handlers = {
+  actions_list: async (a, ctx) => {
+    return ctx.messagingGet('/BusinessActions');
+  },
+  actions_route: async (a, ctx) => {
+    return ctx.messagingPost('/BusinessActions/Route', { text: a.text, max: a.max ?? 3 });
+  },
+  actions_run: async (a, ctx) => {
+    need(a, 'name');
+    const h = a.idempotencyKey ? { 'Idempotency-Key': String(a.idempotencyKey) } : {};
+    return ctx.messagingRequest('POST', '/BusinessActions/' + enc(a.name) + '/Execute', a.request ?? {}, h);
+  },
+};

package/parity/activity.customer.js

@@ -0,0 +1,33 @@
+// velaro activity: integration activity logs and settings audit trail for the authenticated site. The CLI --site staff mode is the existing staff tool support_integration_logs.
+// Parity module (CLI group -> MCP tools).
+
+const enc = encodeURIComponent;
+const qs = (o) => { const p = new URLSearchParams(); for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v)); const s = p.toString(); return s ? '?' + s : ''; };
+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; };
+const need = (a, ...ks) => { for (const k of ks) if (a[k] === undefined || a[k] === null || a[k] === '') throw new Error(k + ' is required'); };
+
+export const tools = [
+  {
+    name: 'activity_logs',
+    description: 'Integration activity log for this site. slug is an integration name (HubSpot, Square), or skills for AI tool logs. Filter by severity, category, search; paged.',
+    inputSchema: {"type":"object","properties":{"slug":{"type":"string","description":"Integration name, or skills for AI tool logs"},"severity":{"type":"string","description":"Info, Warning, Error"},"category":{"type":"string","description":"Auth, Config, Request, Response, AiTool, Setup, Error"},"search":{"type":"string","description":"Message search"},"page":{"type":"integer","description":"Page number (default 1)"},"pageSize":{"type":"integer","description":"Results per page (max 100, default 25)"}}},
+  },
+  {
+    name: 'activity_audit_trail',
+    description: 'Who-changed-what settings history for this site, optionally filtered to one entity type or id. Full before/after detail needs a Compliance package.',
+    inputSchema: {"type":"object","properties":{"entityType":{"type":"string","description":"Entity type, e.g. Workflow"},"entityId":{"type":"string","description":"One specific entity id"},"take":{"type":"integer","description":"Max results (default 200, max 500)"}}},
+  },
+];
+
+export const handlers = {
+  activity_logs: async (a, ctx) => {
+    const skills = a.slug === 'skills';
+    const path = skills || !a.slug ? '/Integration/Logs' : '/Integration/Logs/' + enc(a.slug);
+    const q = qs({ severity: a.severity && a.severity !== 'All' ? a.severity : undefined, category: skills ? 'AiTool' : (a.category && a.category !== 'All' ? a.category : undefined), search: a.search, page: Math.max(1, a.page ?? 1), pageSize: Math.min(100, a.pageSize ?? 25) });
+    return ctx.api('GET', path + q);
+  },
+  activity_audit_trail: async (a, ctx) => {
+    const q = qs({ entityType: a.entityType, entityId: a.entityId, take: Math.min(500, a.take ?? 200) });
+    return ctx.api('GET', '/AuditTrail' + q);
+  },
+};

package/parity/ai-field-extraction.customer.js

@@ -0,0 +1,78 @@
+// velaro ai-field-extraction: post-resolve AI field extraction settings and corrections. Site comes from the credential.
+// Parity module (CLI group -> MCP tools).
+
+const enc = encodeURIComponent;
+const qs = (o) => { const p = new URLSearchParams(); for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v)); const s = p.toString(); return s ? '?' + s : ''; };
+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; };
+const need = (a, ...ks) => { for (const k of ks) if (a[k] === undefined || a[k] === null || a[k] === '') throw new Error(k + ' is required'); };
+
+export const tools = [
+  {
+    name: 'ai_field_extraction_get',
+    description: 'Show the AI field extraction config for this site.',
+    inputSchema: {"type":"object","properties":{}},
+  },
+  {
+    name: 'ai_field_extraction_create',
+    description: 'Create the extraction config. Opt-in: extraction stays off until enabled is true.',
+    inputSchema: {"type":"object","properties":{"enabled":{"type":"boolean","description":"Opt-in switch (default off)"},"extractLineOfBusiness":{"type":"boolean","description":"Extract line of business"},"extractIntent":{"type":"boolean","description":"Extract intent"},"extractState":{"type":"boolean","description":"Extract state"},"extractIdentifiers":{"type":"boolean","description":"Extract identifiers"},"createThemeTags":{"type":"boolean","description":"Create theme tags"},"monthlyCap":{"type":"integer","description":"1 to 50000"},"minConfidence":{"type":"number","description":"0 to 1"}}},
+  },
+  {
+    name: 'ai_field_extraction_update',
+    description: 'Partial update of the extraction config; only passed fields change.',
+    inputSchema: {"type":"object","properties":{"enabled":{"type":"boolean","description":"Opt-in switch (default off)"},"extractLineOfBusiness":{"type":"boolean","description":"Extract line of business"},"extractIntent":{"type":"boolean","description":"Extract intent"},"extractState":{"type":"boolean","description":"Extract state"},"extractIdentifiers":{"type":"boolean","description":"Extract identifiers"},"createThemeTags":{"type":"boolean","description":"Create theme tags"},"monthlyCap":{"type":"integer","description":"1 to 50000"},"minConfidence":{"type":"number","description":"0 to 1"}}},
+  },
+  {
+    name: 'ai_field_extraction_delete',
+    description: 'Delete the extraction config for this site.',
+    inputSchema: {"type":"object","properties":{}},
+  },
+  {
+    name: 'ai_field_extraction_fields',
+    description: 'Show extracted fields for one conversation.',
+    inputSchema: {"type":"object","properties":{"conversationId":{"type":"integer","description":"Conversation id"}},"required":["conversationId"]},
+  },
+  {
+    name: 'ai_field_extraction_correct',
+    description: 'Agent correction of one extracted field on a conversation.',
+    inputSchema: {"type":"object","properties":{"conversationId":{"type":"integer","description":"Conversation id"},"fieldName":{"type":"string","description":"Field name"},"value":{"type":"string","description":"Corrected value"}},"required":["conversationId","fieldName","value"]},
+  },
+  {
+    name: 'ai_field_extraction_extract',
+    description: 'Run extraction now for one conversation.',
+    inputSchema: {"type":"object","properties":{"conversationId":{"type":"integer","description":"Conversation id"}},"required":["conversationId"]},
+  },
+];
+
+export const handlers = {
+  ai_field_extraction_get: async (a, ctx) => {
+    return ctx.messagingGet('/AiFieldExtraction/Config');
+  },
+  ai_field_extraction_create: async (a, ctx) => {
+    const b = {};
+    const K = { enabled: 'Enabled', extractLineOfBusiness: 'ExtractLineOfBusiness', extractIntent: 'ExtractIntent', extractState: 'ExtractState', extractIdentifiers: 'ExtractIdentifiers', createThemeTags: 'CreateThemeTags', monthlyCap: 'MonthlyCap', minConfidence: 'MinConfidence' };
+    for (const [k, p] of Object.entries(K)) if (a[k] !== undefined) b[p] = a[k];
+    return ctx.messagingPost('/AiFieldExtraction/Config', b);
+  },
+  ai_field_extraction_update: async (a, ctx) => {
+    const b = {};
+    const K = { enabled: 'Enabled', extractLineOfBusiness: 'ExtractLineOfBusiness', extractIntent: 'ExtractIntent', extractState: 'ExtractState', extractIdentifiers: 'ExtractIdentifiers', createThemeTags: 'CreateThemeTags', monthlyCap: 'MonthlyCap', minConfidence: 'MinConfidence' };
+    for (const [k, p] of Object.entries(K)) if (a[k] !== undefined) b[p] = a[k];
+    return ctx.messagingPut('/AiFieldExtraction/Config', b);
+  },
+  ai_field_extraction_delete: async (a, ctx) => {
+    await ctx.messagingDel('/AiFieldExtraction/Config');
+    return 'Deleted';
+  },
+  ai_field_extraction_fields: async (a, ctx) => {
+    return ctx.messagingGet('/AiFieldExtraction/Conversation/' + pid(a.conversationId, 'conversationId') + '/Fields');
+  },
+  ai_field_extraction_correct: async (a, ctx) => {
+    need(a, 'fieldName', 'value');
+    await ctx.messagingPut('/AiFieldExtraction/Conversation/' + pid(a.conversationId, 'conversationId') + '/Fields/' + enc(a.fieldName), { Value: a.value });
+    return 'Corrected';
+  },
+  ai_field_extraction_extract: async (a, ctx) => {
+    return ctx.messagingPost('/AiFieldExtraction/Conversation/' + pid(a.conversationId, 'conversationId') + '/Extract', {});
+  },
+};

package/parity/callback.customer.js

@@ -0,0 +1,22 @@
+// velaro callback report: Callback Scheduling supervisor report. Site comes from the credential.
+// Parity module (CLI group -> MCP tools).
+
+const enc = encodeURIComponent;
+const qs = (o) => { const p = new URLSearchParams(); for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v)); const s = p.toString(); return s ? '?' + s : ''; };
+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; };
+const need = (a, ...ks) => { for (const k of ks) if (a[k] === undefined || a[k] === null || a[k] === '') throw new Error(k + ' is required'); };
+
+export const tools = [
+  {
+    name: 'callback_report',
+    description: 'Callback Scheduling supervisor report: summary counts (requested, completed, missed, overdue, rescheduled) plus paged items.',
+    inputSchema: {"type":"object","properties":{"status":{"type":"string","description":"Pending, Scheduled, Fulfilled, Failed"},"mode":{"type":"string","description":"Fulfillment mode, e.g. AiCallback, AgentCallback"},"days":{"type":"integer","description":"Lookback days 1-365 (default 30)"},"page":{"type":"integer","description":"Page (default 1)"},"pageSize":{"type":"integer","description":"Per page, max 200 (default 50)"}}},
+  },
+];
+
+export const handlers = {
+  callback_report: async (a, ctx) => {
+    const q = qs({ status: a.status, fulfillmentMode: a.mode, dateRangeDays: a.days ?? 30, page: Math.max(1, a.page ?? 1), pageSize: Math.min(200, a.pageSize ?? 50) });
+    return ctx.messagingGet('/CallbackScheduling/report' + q);
+  },
+};

package/parity/check.customer.js

@@ -0,0 +1,31 @@
+// velaro check: read-only site health and configuration summary (counts per feature area).
+// Parity module (CLI group -> MCP tools).
+
+const enc = encodeURIComponent;
+const qs = (o) => { const p = new URLSearchParams(); for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v)); const s = p.toString(); return s ? '?' + s : ''; };
+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; };
+const need = (a, ...ks) => { for (const k of ks) if (a[k] === undefined || a[k] === null || a[k] === '') throw new Error(k + ' is required'); };
+
+export const tools = [
+  {
+    name: 'check_site_health',
+    description: 'Read-only health and configuration summary for this site: API health, websites, teams, AI configs, knowledge entries, workflows, rules, IVR config and agent count. Arrays are returned as counts.',
+    inputSchema: {"type":"object","properties":{}},
+  },
+];
+
+export const handlers = {
+  check_site_health: async (a, ctx) => {
+    const probes = { health: '/api/health', deployments: '/Deployment', teams: '/Teams/List', aiConfigs: '/AIConfiguration/list', botQnA: '/BotQnA', knowledgeOverrides: '/Ticket/knowledge-overrides', workflows: '/Workflows/List', rules: '/Rules/List', ivrConfig: '/api/ivr/config', agents: '/Users/List' };
+    const out = {};
+    await Promise.all(Object.entries(probes).map(async ([k, p]) => {
+      try {
+        const r = await ctx.messagingGet(p);
+        if (k === 'workflows') out[k] = { count: (r ?? []).filter((w) => !w.isTemplate).length };
+        else if (Array.isArray(r)) out[k] = { count: r.length };
+        else out[k] = r;
+      } catch (e) { out[k] = { error: String(e.message).slice(0, 200) }; }
+    }));
+    return out;
+  },
+};

package/parity/deployment.customer.js

@@ -0,0 +1,45 @@
+// velaro deployment: websites (deployments) for the authenticated site.
+// Parity module (CLI group -> MCP tools).
+
+const enc = encodeURIComponent;
+const qs = (o) => { const p = new URLSearchParams(); for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v)); const s = p.toString(); return s ? '?' + s : ''; };
+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; };
+const need = (a, ...ks) => { for (const k of ks) if (a[k] === undefined || a[k] === null || a[k] === '') throw new Error(k + ' is required'); };
+
+export const tools = [
+  {
+    name: 'deployment_list',
+    description: 'List this site websites (deployments) and teams so a website can be matched to its team.',
+    inputSchema: {"type":"object","properties":{}},
+  },
+  {
+    name: 'deployment_rename',
+    description: 'Rename a website (deployment) display name.',
+    inputSchema: {"type":"object","properties":{"id":{"type":"integer","description":"Deployment id"},"name":{"type":"string","description":"New display name"}},"required":["id","name"]},
+  },
+  {
+    name: 'deployment_assign_team',
+    description: 'Assign a team to a website (deployment). The team must exist on this site.',
+    inputSchema: {"type":"object","properties":{"id":{"type":"integer","description":"Deployment id"},"teamId":{"type":"integer","description":"Team id"}},"required":["id","teamId"]},
+  },
+];
+
+export const handlers = {
+  deployment_list: async (a, ctx) => {
+    const [deployments, teams] = await Promise.all([ctx.api('GET', '/Deployment'), ctx.api('GET', '/Teams/List')]);
+    return { deployments, teams };
+  },
+  deployment_rename: async (a, ctx) => {
+    need(a, 'name');
+    const id = pid(a.id);
+    const dep = await ctx.api('GET', '/Deployment/' + id);
+    return ctx.api('POST', '/Deployment', { ...dep, id, displayName: a.name });
+  },
+  deployment_assign_team: async (a, ctx) => {
+    const id = pid(a.id);
+    const teamId = pid(a.teamId, 'teamId');
+    const [dep, teams] = await Promise.all([ctx.api('GET', '/Deployment/' + id), ctx.api('GET', '/Teams/List')]);
+    if (!(teams ?? []).some((t) => t.id === teamId)) throw new Error('Team ' + teamId + ' not found on this site');
+    return ctx.api('POST', '/Deployment', { ...dep, id, teamId });
+  },
+};

package/parity/endpoints.customer.js

@@ -0,0 +1,87 @@
+// Parity tools for tenant-scoped endpoints. siteId always comes from the credential, never from an argument.
+// Restore tools are tenant-scoped, take explicit numeric ids, and never act in bulk or by filter.
+const id = (d) => ({ type: 'integer', minimum: 1, description: d });
+
+export const tools = [
+  {
+    name: 'ai_usage_get_summary',
+    description: 'AI usage summary for your own site (GET /AiUsageReport/summary).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'ai_usage_update_budget_alert',
+    description: 'Update your site AI budget alert (enabled, threshold percent, recipient emails). Partial update; Admin/Manager only.',
+    inputSchema: { type: 'object', properties: { enabled: { type: 'boolean' }, thresholdPercent: { type: 'integer', minimum: 1, maximum: 1000 }, recipientEmails: { type: 'string', description: 'Comma-separated emails' } } },
+  },
+  {
+    name: 'ai_usage_delete_budget_alert',
+    description: 'Delete your site AI budget alert configuration (tenant-scoped, no arguments).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'contactlist_list_deleted',
+    description: 'List soft-deleted contact lists for your site that can be restored.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'contactlist_restore',
+    description: 'Restore ONE soft-deleted contact list by explicit numeric id. Tenant-scoped; no bulk or filter-based restore.',
+    inputSchema: { type: 'object', properties: { id: id('Contact list id') }, required: ['id'] },
+  },
+  {
+    name: 'contactlist_list_deleted_members',
+    description: 'List soft-deleted members of one contact list (explicit list id).',
+    inputSchema: { type: 'object', properties: { listId: id('Contact list id') }, required: ['listId'] },
+  },
+  {
+    name: 'contactlist_restore_member',
+    description: 'Restore ONE soft-deleted contact list member by explicit list id and member id. Tenant-scoped; no bulk restore.',
+    inputSchema: { type: 'object', properties: { listId: id('Contact list id'), memberId: id('Member id') }, required: ['listId', 'memberId'] },
+  },
+  {
+    name: 'contact_segment_list_deleted',
+    description: 'List soft-deleted contact segments for your site.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'kb_restore_deleted_article',
+    description: 'Restore ONE soft-deleted KB article by explicit numeric id. Tenant-scoped; no bulk or filter-based restore.',
+    inputSchema: { type: 'object', properties: { id: id('KB article id') }, required: ['id'] },
+  },
+  {
+    name: 'kb_restore_deleted_topic',
+    description: 'Restore ONE soft-deleted KB topic by explicit numeric id. Tenant-scoped; no bulk or filter-based restore.',
+    inputSchema: { type: 'object', properties: { id: id('KB topic id') }, required: ['id'] },
+  },
+  {
+    name: 'entitlements_get_mine',
+    description: 'Resolved feature entitlements for your own site (site comes from your credential).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'site_settings_get',
+    description: 'General settings for your own site (read-only).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'platform_uptime_get',
+    description: 'Platform uptime figures (read-only; site admins).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+export const handlers = {
+  ai_usage_get_summary: (_a, c) => c.api('GET', '/AiUsageReport/summary'),
+  ai_usage_update_budget_alert: (a, c) => c.api('PUT', '/AiUsageReport/budget-alert', { enabled: a.enabled, thresholdPercent: a.thresholdPercent, recipientEmails: a.recipientEmails }),
+  ai_usage_delete_budget_alert: (_a, c) => c.api('DELETE', '/AiUsageReport/budget-alert'),
+  contactlist_list_deleted: (_a, c) => c.api('GET', '/ContactLists/deleted'),
+  contactlist_restore: (a, c) => c.api('POST', `/ContactLists/${Number(a.id)}/restore`),
+  contactlist_list_deleted_members: (a, c) => c.api('GET', `/ContactLists/${Number(a.listId)}/Members/deleted`),
+  contactlist_restore_member: (a, c) => c.api('POST', `/ContactLists/${Number(a.listId)}/Members/${Number(a.memberId)}/restore`),
+  contact_segment_list_deleted: (_a, c) => c.api('GET', '/ContactSegments/deleted'),
+  kb_restore_deleted_article: (a, c) => c.api('POST', `/api/kb/articles/${Number(a.id)}/restore`),
+  kb_restore_deleted_topic: (a, c) => c.api('POST', `/api/kb/topics/${Number(a.id)}/restore`),
+  entitlements_get_mine: (_a, c) => c.api('GET', '/Entitlements/my'),
+  site_settings_get: (_a, c) => c.api('GET', '/api/SiteSettings'),
+  platform_uptime_get: (_a, c) => c.api('GET', '/PlatformUptime'),
+};

package/parity/ingest.customer.js

@@ -0,0 +1,22 @@
+// velaro ingest: trigger KB ingestion for a completed scraper job. Site comes from the credential.
+// Parity module (CLI group -> MCP tools).
+
+const enc = encodeURIComponent;
+const qs = (o) => { const p = new URLSearchParams(); for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v)); const s = p.toString(); return s ? '?' + s : ''; };
+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; };
+const need = (a, ...ks) => { for (const k of ks) if (a[k] === undefined || a[k] === null || a[k] === '') throw new Error(k + ' is required'); };
+
+export const tools = [
+  {
+    name: 'ingest_start',
+    description: 'Trigger knowledge base ingestion for a completed scraper job on this site. Embedding runs in the background.',
+    inputSchema: {"type":"object","properties":{"jobId":{"type":"string","description":"Scraper job id to ingest"}},"required":["jobId"]},
+  },
+];
+
+export const handlers = {
+  ingest_start: async (a, ctx) => {
+    need(a, 'jobId');
+    return ctx.messagingPost('/AzureIndexes/IngestJobDirect', { jobId: String(a.jobId) });
+  },
+};

package/parity/keyword-intelligence.customer.js

@@ -0,0 +1,33 @@
+// velaro keyword-intelligence: keyword and phrase analytics over conversations.
+// Parity module (CLI group -> MCP tools).
+
+const enc = encodeURIComponent;
+const qs = (o) => { const p = new URLSearchParams(); for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v)); const s = p.toString(); return s ? '?' + s : ''; };
+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; };
+const need = (a, ...ks) => { for (const k of ks) if (a[k] === undefined || a[k] === null || a[k] === '') throw new Error(k + ' is required'); };
+
+export const tools = [
+  {
+    name: 'keyword_intelligence_top',
+    description: 'Top keywords/phrases in a date range, optionally grouped and filtered by team, agent or website.',
+    inputSchema: {"type":"object","properties":{"from":{"type":"string","description":"ISO start date"},"to":{"type":"string","description":"ISO end date"},"groupBy":{"type":"string","description":"Grouping (default none)"},"ngram":{"type":"integer","description":"N-gram size (default 3)"},"limit":{"type":"integer","description":"Max rows (default 50)"},"team":{"type":"integer","description":"Team id"},"agent":{"type":"integer","description":"Agent id"},"website":{"type":"string","description":"Website"}},"required":["from","to"]},
+  },
+  {
+    name: 'keyword_intelligence_conversations',
+    description: 'Conversations that contain a keyword in a date range, optionally filtered by team or agent.',
+    inputSchema: {"type":"object","properties":{"keyword":{"type":"string","description":"Keyword or phrase"},"from":{"type":"string","description":"ISO start date"},"to":{"type":"string","description":"ISO end date"},"team":{"type":"integer","description":"Team id"},"agent":{"type":"integer","description":"Agent id"}},"required":["keyword","from","to"]},
+  },
+];
+
+export const handlers = {
+  keyword_intelligence_top: async (a, ctx) => {
+    need(a, 'from', 'to');
+    const q = qs({ from: a.from, to: a.to, groupBy: a.groupBy ?? 'none', ngram: a.ngram ?? 3, limit: a.limit ?? 50, teamId: a.team, agentId: a.agent, website: a.website });
+    return ctx.messagingGet('/api/keyword-intelligence/top' + q);
+  },
+  keyword_intelligence_conversations: async (a, ctx) => {
+    need(a, 'keyword', 'from', 'to');
+    const q = qs({ keyword: a.keyword, from: a.from, to: a.to, teamId: a.team, agentId: a.agent });
+    return ctx.messagingGet('/api/keyword-intelligence/conversations' + q);
+  },
+};

package/parity/knowledge-advisor.customer.js

@@ -0,0 +1,26 @@
+// velaro knowledge-advisor advise: what to upload and how big the index will be.
+// Parity module (CLI group -> MCP tools).
+
+const enc = encodeURIComponent;
+const qs = (o) => { const p = new URLSearchParams(); for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v)); const s = p.toString(); return s ? '?' + s : ''; };
+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; };
+const need = (a, ...ks) => { for (const k of ks) if (a[k] === undefined || a[k] === null || a[k] === '') throw new Error(k + ' is required'); };
+
+export const tools = [
+  {
+    name: 'knowledge_advisor_advise',
+    description: 'Advise how to load knowledge sources: per-source recommendation, what to upload, chunk estimate and per-answer retrieval size. Pass sources, or a single source via kind.',
+    inputSchema: {"type":"object","properties":{"sources":{"type":"array","items":{"type":"string"},"description":"Array of source objects (name, kind, pages, rows, changeFrequency, hasExactIdentifiers, scanned, hasLiveSystem)"},"kind":{"type":"string","description":"manual_pdf, spec_sheet, policy_document, faq_or_help_pages, product_catalog, price_list, cross_reference_sheet, images_or_drawings, cad_files, other_documents"},"name":{"type":"string","description":"Source name"},"pages":{"type":"integer","description":"Page count"},"rows":{"type":"integer","description":"Row count"},"changeFrequency":{"type":"string","description":"static, monthly, weekly, daily, realtime"},"exactIds":{"type":"boolean","description":"Answers depend on exact part numbers or SKUs"},"scanned":{"type":"boolean","description":"PDF is scanned images"},"liveSystem":{"type":"boolean","description":"A connected store, ERP or CRM can be queried"}}},
+  },
+];
+
+export const handlers = {
+  knowledge_advisor_advise: async (a, ctx) => {
+    let sources = a.sources;
+    if (!Array.isArray(sources) || sources.length === 0) {
+      if (!a.kind) throw new Error('Give sources (array) or kind.');
+      sources = [{ name: a.name, kind: a.kind, pages: a.pages, rows: a.rows, changeFrequency: a.changeFrequency, hasExactIdentifiers: !!a.exactIds, scanned: !!a.scanned, hasLiveSystem: !!a.liveSystem }];
+    }
+    return ctx.messagingPost('/KnowledgeAdvisor/advise', { sources });
+  },
+};

package/parity/loader.js

@@ -0,0 +1,32 @@
+// Loads parity tool modules. Each module in this directory is named
+//   <area>.customer.js  -> tools exposed by the customer MCP (mcp/server.js), tenant-scoped only
+//   <area>.staff.js     -> tools exposed ONLY by velaro-staff (mcp/staff-server.js)
+// and exports:
+//   export const tools = [ { name, description, inputSchema }, ... ];
+//   export const handlers = { tool_name: async (args, ctx) => string|object, ... };
+// ctx carries the host server's authenticated HTTP helpers (api, messagingGet/Post/Put/Del when present).
+// A customer tool MUST NOT take siteId from its arguments: the site always comes from the credential.
+import { readdirSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { dirname, join } from 'node:path';
+
+export async function loadParity(kind /* 'customer' | 'staff' */) {
+  const dir = dirname(fileURLToPath(import.meta.url));
+  const out = { tools: [], handlers: {} };
+  for (const f of readdirSync(dir).filter((x) => x.endsWith(`.${kind}.js`)).sort()) {
+    const mod = await import(pathToFileURL(join(dir, f)).href);
+    for (const t of mod.tools || []) {
+      if (out.handlers[t.name] || !mod.handlers?.[t.name]) throw new Error(`parity module ${f}: tool ${t.name} duplicate or missing handler`);
+      out.tools.push(t);
+      out.handlers[t.name] = mod.handlers[t.name];
+    }
+  }
+  return out;
+}
+
+export async function runParity(parity, name, args, ctx) {
+  const h = parity.handlers[name];
+  if (!h) return undefined;
+  const r = await h(args, ctx);
+  return typeof r === 'string' ? r : JSON.stringify(r, null, 2);
+}

package/parity/quality.customer.js

@@ -0,0 +1,122 @@
+// velaro quality: sentiment, agent performance, QA scoring, rubrics and alert settings.
+// Parity module (CLI group -> MCP tools).
+
+const enc = encodeURIComponent;
+const qs = (o) => { const p = new URLSearchParams(); for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v)); const s = p.toString(); return s ? '?' + s : ''; };
+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; };
+const need = (a, ...ks) => { for (const k of ks) if (a[k] === undefined || a[k] === null || a[k] === '') throw new Error(k + ' is required'); };
+
+export const tools = [
+  {
+    name: 'quality_sentiment',
+    description: 'Sentiment report. kind: overview, breakdown, conversation-overview, conversation-breakdown, contact-overview, agent-breakdown. Defaults to the last 30 days.',
+    inputSchema: {"type":"object","properties":{"kind":{"type":"string","description":"Report kind (default overview)"},"from":{"type":"string","description":"ISO start"},"to":{"type":"string","description":"ISO end"},"groupBy":{"type":"string","description":"Grouping (default day)"},"deployment":{"type":"integer","description":"Website (deployment row id)"},"team":{"type":"integer","description":"Team id"}}},
+  },
+  {
+    name: 'quality_agent_performance',
+    description: 'Agent performance report for the last N days, optionally per website or team.',
+    inputSchema: {"type":"object","properties":{"days":{"type":"integer","description":"Lookback days (default 30)"},"deployment":{"type":"integer","description":"Website (deployment row id)"},"team":{"type":"integer","description":"Team id"}}},
+  },
+  {
+    name: 'quality_low_scores',
+    description: 'Lowest-scoring QA conversations in the last N days.',
+    inputSchema: {"type":"object","properties":{"threshold":{"type":"number","description":"Score threshold"},"days":{"type":"integer","description":"Lookback days (default 30)"},"agent":{"type":"integer","description":"Agent id"},"take":{"type":"integer","description":"Max rows (default 50)"}}},
+  },
+  {
+    name: 'quality_calibration',
+    description: 'QA calibration report (AI score versus human review) for the last N days.',
+    inputSchema: {"type":"object","properties":{"days":{"type":"integer","description":"Lookback days (default 90)"}}},
+  },
+  {
+    name: 'quality_rubric_list',
+    description: 'List QA rubrics.',
+    inputSchema: {"type":"object","properties":{}},
+  },
+  {
+    name: 'quality_rubric_get_default',
+    description: 'Get the default QA rubric.',
+    inputSchema: {"type":"object","properties":{}},
+  },
+  {
+    name: 'quality_rubric_get',
+    description: 'Get one QA rubric.',
+    inputSchema: {"type":"object","properties":{"id":{"type":"integer","description":"Rubric id"}},"required":["id"]},
+  },
+  {
+    name: 'quality_rubric_create',
+    description: 'Create a QA rubric from a rubric JSON body.',
+    inputSchema: {"type":"object","properties":{"rubric":{"type":"object","additionalProperties":true,"description":"Rubric body"}},"required":["rubric"]},
+  },
+  {
+    name: 'quality_rubric_update',
+    description: 'Update a QA rubric from a rubric JSON body.',
+    inputSchema: {"type":"object","properties":{"id":{"type":"integer","description":"Rubric id"},"rubric":{"type":"object","additionalProperties":true,"description":"Rubric body"}},"required":["id","rubric"]},
+  },
+  {
+    name: 'quality_rubric_delete',
+    description: 'Delete a QA rubric.',
+    inputSchema: {"type":"object","properties":{"id":{"type":"integer","description":"Rubric id"}},"required":["id"]},
+  },
+  {
+    name: 'quality_alerts_get',
+    description: 'Read the quality alert settings.',
+    inputSchema: {"type":"object","properties":{}},
+  },
+  {
+    name: 'quality_alerts_update',
+    description: 'Update the quality alert settings from a settings JSON body.',
+    inputSchema: {"type":"object","properties":{"settings":{"type":"object","additionalProperties":true,"description":"Alert settings body"}},"required":["settings"]},
+  },
+];
+
+export const handlers = {
+  quality_sentiment: async (a, ctx) => {
+    const R = { overview: 'sentiment-overview', breakdown: 'sentiment-breakdown', 'conversation-overview': 'conversation-sentiment-overview', 'conversation-breakdown': 'conversation-sentiment-breakdown', 'contact-overview': 'contact-sentiment-overview', 'agent-breakdown': 'agent-sentiment-breakdown' };
+    const route = R[a.kind ?? 'overview'];
+    if (!route) throw new Error('kind must be one of: ' + Object.keys(R).join(', '));
+    const end = a.to ? new Date(a.to) : new Date();
+    const start = a.from ? new Date(a.from) : new Date(end.getTime() - 30 * 86400000);
+    const body = { Start: start.toISOString(), End: end.toISOString(), GroupBy: a.groupBy ?? 'day' };
+    if (a.deployment != null) body.DeploymentId = a.deployment;
+    if (a.team != null) body.TeamId = a.team;
+    return ctx.messagingPost('/Reports/' + route, body);
+  },
+  quality_agent_performance: async (a, ctx) => {
+    const q = qs({ days: a.days ?? 30, deploymentId: a.deployment, teamId: a.team });
+    return ctx.messagingGet('/api/admin/Reports/AgentPerformance' + q);
+  },
+  quality_low_scores: async (a, ctx) => {
+    const q = qs({ days: a.days ?? 30, take: a.take ?? 50, threshold: a.threshold, agentId: a.agent });
+    return ctx.messagingGet('/api/admin/QualityQa/low-scores' + q);
+  },
+  quality_calibration: async (a, ctx) => {
+    return ctx.messagingGet('/api/admin/QualityQa/calibration' + qs({ days: a.days ?? 90 }));
+  },
+  quality_rubric_list: async (a, ctx) => {
+    return ctx.messagingGet('/api/admin/QualityQa/rubrics');
+  },
+  quality_rubric_get_default: async (a, ctx) => {
+    return ctx.messagingGet('/api/admin/QualityQa/rubrics/default');
+  },
+  quality_rubric_get: async (a, ctx) => {
+    return ctx.messagingGet('/api/admin/QualityQa/rubrics/' + pid(a.id));
+  },
+  quality_rubric_create: async (a, ctx) => {
+    need(a, 'rubric');
+    return ctx.messagingPost('/api/admin/QualityQa/rubrics', a.rubric);
+  },
+  quality_rubric_update: async (a, ctx) => {
+    need(a, 'rubric');
+    return ctx.messagingPut('/api/admin/QualityQa/rubrics/' + pid(a.id), a.rubric);
+  },
+  quality_rubric_delete: async (a, ctx) => {
+    return ctx.messagingDel('/api/admin/QualityQa/rubrics/' + pid(a.id));
+  },
+  quality_alerts_get: async (a, ctx) => {
+    return ctx.messagingGet('/api/admin/QualityQa/alert-settings');
+  },
+  quality_alerts_update: async (a, ctx) => {
+    need(a, 'settings');
+    return ctx.messagingPut('/api/admin/QualityQa/alert-settings', a.settings);
+  },
+};