@velaro/mcp-server 1.0.2 → 2.0.1

package/parity/rule.customer.js

@@ -0,0 +1,48 @@
+// MCP parity for `velaro rule` (cli/lib/commands/rule.js). Site comes from the credential; no siteId argument.
+export const tools = [
+  {
+    name: 'rule_list',
+    description: 'List the routing rules for your site (id, name, priority, trigger), sorted by priority.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'rule_create',
+    description: 'Create an enabled routing rule that sends matching visitors to a team (trigger e.g. pageUrl or country; lower priority number wins).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        name: { type: 'string', description: 'Rule name' },
+        trigger: { type: 'string', description: 'Trigger type (e.g. pageUrl, country)' },
+        value: { type: 'string', description: 'Trigger value to match' },
+        teamId: { type: 'number', description: 'Team ID to route to' },
+        priority: { type: 'number', description: 'Rule priority (lower = higher priority). Default 0.' },
+      },
+      required: ['name', 'trigger', 'value', 'teamId'],
+    },
+  },
+  {
+    name: 'rule_delete',
+    description: 'Delete a routing rule by id.',
+    inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'Rule ID' } }, required: ['id'] },
+  },
+];
+
+export const handlers = {
+  rule_list: async (_a, ctx) => {
+    const rules = (await ctx.messagingGet('/Rules/List')) || [];
+    return [...rules].sort((a, b) => (a.priority ?? 0) - (b.priority ?? 0));
+  },
+  rule_create: async (a, ctx) => {
+    for (const k of ['name', 'trigger', 'value']) if (!a[k]) throw new Error(`${k} is required`);
+    if (!Number.isInteger(Number(a.teamId))) throw new Error('teamId is required');
+    return ctx.messagingPost('/Rules', {
+      name: a.name, trigger: a.trigger, value: a.value, teamId: Number(a.teamId), priority: Number(a.priority ?? 0), isEnabled: true,
+    });
+  },
+  rule_delete: async (a, ctx) => {
+    if (!Number.isInteger(Number(a.id))) throw new Error('id is required');
+    // RulesController.DeleteAsync takes the rule in the BODY (DELETE /Rules {id}); same as the CLI.
+    await ctx.messagingRequest('DELETE', '/Rules', { id: Number(a.id) });
+    return { deleted: Number(a.id) };
+  },
+};

package/parity/sentiment.customer.js

@@ -0,0 +1,41 @@
+// MCP parity for `velaro sentiment` (cli/lib/commands/quality-reports.js). Site from credential; deployment/team verified server-side.
+const ROUTES = {
+  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',
+};
+
+export const tools = [
+  {
+    name: 'sentiment_report',
+    description: 'Sentiment report for your site, optionally scoped to one website (deploymentId) or team. kind selects overview, breakdown, conversation-overview, conversation-breakdown, contact-overview or agent-breakdown. Defaults to the last 30 days.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: Object.keys(ROUTES), description: 'Report kind (default overview)' },
+        from: { type: 'string', description: 'Start date/time (ISO). Default 30 days before "to".' },
+        to: { type: 'string', description: 'End date/time (ISO). Default now.' },
+        groupBy: { type: 'string', description: 'Grouping (default day)' },
+        deploymentId: { type: 'number', description: 'Website (deployment row id)' },
+        teamId: { type: 'number', description: 'Team id' },
+      },
+    },
+  },
+];
+
+export const handlers = {
+  sentiment_report: async (a, ctx) => {
+    const kind = a.kind || 'overview';
+    if (!ROUTES[kind]) throw new Error(`kind must be one of ${Object.keys(ROUTES).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);
+    if (isNaN(start) || isNaN(end)) throw new Error('from/to must be valid dates');
+    const body = { Start: start.toISOString(), End: end.toISOString(), GroupBy: a.groupBy || 'day' };
+    if (a.deploymentId != null) body.DeploymentId = Number(a.deploymentId);
+    if (a.teamId != null) body.TeamId = Number(a.teamId);
+    return ctx.messagingPost(`/Reports/${ROUTES[kind]}`, body);
+  },
+};

package/parity/site-builder.customer.js

@@ -0,0 +1,12 @@
+// MCP parity for `velaro site-builder connect-info`. The site is the caller's own (credential), never an argument.
+export const tools = [
+  {
+    name: 'site_builder_connect_info',
+    description: 'Get your own site ID and chat snippet for pasting into a website builder.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+export const handlers = {
+  site_builder_connect_info: async (_a, ctx) => ctx.messagingGet('/integrations/site-builder/connect-info'),
+};

package/parity/skill-routing.customer.js

@@ -0,0 +1,79 @@
+// MCP parity for `velaro skill-routing` (cli/lib/commands/skill-routing.js). Site from the credential (velaro-messaging
+// /SkillRouting, gated by the EnableSkillBasedRouting entitlement). Requirements are disabled by default; PUT is partial.
+const RESOURCES = ['Skills', 'Assignments', 'Requirements'];
+const idList = (v) => (v == null ? undefined : (Array.isArray(v) ? v : String(v).split(',')).map((x) => Number(x)).filter((n) => !Number.isNaN(n)));
+const strip = (o) => Object.fromEntries(Object.entries(o).filter(([, v]) => v !== undefined));
+const resource = (a) => {
+  const r = RESOURCES.find((x) => x.toLowerCase() === String(a.resource || '').toLowerCase());
+  if (!r) throw new Error(`resource must be one of ${RESOURCES.join(', ')}`);
+  return r;
+};
+const bodyFor = (r, a) => {
+  if (r === 'Skills') return strip({ Name: a.name, Description: a.description });
+  if (r === 'Assignments') return strip({ WorkspaceUserId: a.agent, AgentSkillId: a.skill, Proficiency: a.proficiency });
+  return strip({
+    DeploymentId: a.deployment, TeamId: a.team, RequiredSkillIds: idList(a.required), PreferredSkillIds: idList(a.preferred),
+    OverflowWaitSeconds: a.overflowWait, IsEnabled: a.enabled,
+  });
+};
+const fieldProps = {
+  resource: { type: 'string', enum: RESOURCES, description: 'Skills (catalog), Assignments (agent skills) or Requirements (per deployment/team)' },
+};
+const props = () => ({
+  resource: fieldProps.resource,
+  name: { type: 'string', description: 'Skills: skill name' },
+  description: { type: 'string', description: 'Skills: description' },
+  agent: { type: 'number', description: 'Assignments: workspaceUserId' },
+  skill: { type: 'number', description: 'Assignments: agentSkillId' },
+  proficiency: { type: 'number', description: 'Assignments: 1-5' },
+  deployment: { type: 'number', description: 'Requirements: deployment id' },
+  team: { type: 'number', description: 'Requirements: team id' },
+  required: { type: 'string', description: 'Requirements: comma-separated required skill ids' },
+  preferred: { type: 'string', description: 'Requirements: comma-separated preferred skill ids' },
+  overflowWait: { type: 'number', description: 'Requirements: seconds before falling back to all agents' },
+  enabled: { type: 'boolean', description: 'Requirements: turn on/off (default off)' },
+});
+
+export const tools = [
+  {
+    name: 'skill_routing_list',
+    description: 'List skill-based routing rows for your site: the skill catalog, agent skill assignments, or per-deployment/team requirements.',
+    inputSchema: { type: 'object', properties: { resource: fieldProps.resource }, required: ['resource'] },
+  },
+  {
+    name: 'skill_routing_create',
+    description: 'Create a skill-based routing row (skill, agent skill assignment, or requirement). Requirements are created disabled unless enabled is true.',
+    inputSchema: { type: 'object', properties: props(), required: ['resource'] },
+  },
+  {
+    name: 'skill_routing_update',
+    description: 'Partially update a skill-based routing row by id (omitted fields are unchanged).',
+    inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'Row id' }, ...props() }, required: ['resource', 'id'] },
+  },
+  {
+    name: 'skill_routing_delete',
+    description: 'Delete a skill-based routing row by id.',
+    inputSchema: { type: 'object', properties: { resource: fieldProps.resource, id: { type: 'number', description: 'Row id' } }, required: ['resource', 'id'] },
+  },
+  {
+    name: 'skill_routing_simulate',
+    description: 'Dry-run skill routing for a team. Never assigns an agent and never writes the decision log.',
+    inputSchema: {
+      type: 'object',
+      properties: { team: { type: 'number', description: 'Team id' }, waited: { type: 'number', description: 'Seconds the conversation has waited' } },
+    },
+  },
+];
+
+const needId = (a) => {
+  if (!Number.isInteger(Number(a.id))) throw new Error('id is required');
+  return Number(a.id);
+};
+
+export const handlers = {
+  skill_routing_list: async (a, ctx) => ctx.messagingGet(`/SkillRouting/${resource(a)}`),
+  skill_routing_create: async (a, ctx) => { const r = resource(a); return ctx.messagingPost(`/SkillRouting/${r}`, bodyFor(r, a)); },
+  skill_routing_update: async (a, ctx) => { const r = resource(a); return ctx.messagingPut(`/SkillRouting/${r}/${needId(a)}`, bodyFor(r, a)); },
+  skill_routing_delete: async (a, ctx) => ctx.messagingDel(`/SkillRouting/${resource(a)}/${needId(a)}`),
+  skill_routing_simulate: async (a, ctx) => ctx.messagingPost('/SkillRouting/Simulate', { TeamId: a.team ?? null, WaitedSeconds: a.waited ?? null }),
+};

package/parity/squarespace.customer.js

@@ -0,0 +1,44 @@
+// MCP parity for `velaro squarespace` (cli/lib/commands/squarespace.js). Site from the credential. Read-only integration.
+export const tools = [
+  {
+    name: 'squarespace_get_status',
+    description: 'Show the Squarespace Commerce connection status for your site (connected, store URL, whether an API key is on file).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'squarespace_configure',
+    description: 'Connect a Squarespace store using a Commerce API key (storeUrl is optional, reference only). The key is stored server-side and never returned.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        apiKey: { type: 'string', description: 'Squarespace Commerce API key' },
+        storeUrl: { type: 'string', description: 'Store URL (optional)' },
+      },
+      required: ['apiKey'],
+    },
+  },
+  {
+    name: 'squarespace_disconnect',
+    description: 'Disconnect the Squarespace store from your site.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'squarespace_test_connection',
+    description: 'Test the current Squarespace connection without changing anything.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+export const handlers = {
+  squarespace_get_status: async (_a, ctx) => ctx.api('GET', '/Squarespace/Config'),
+  squarespace_configure: async (a, ctx) => {
+    if (!a.apiKey) throw new Error('apiKey is required');
+    return ctx.api('POST', '/Squarespace/Config', { apiKey: a.apiKey, storeUrl: a.storeUrl || '' });
+  },
+  squarespace_disconnect: async (_a, ctx) => {
+    const cfg = await ctx.api('GET', '/Squarespace/Config');
+    if (!cfg?.connected) return { success: true, message: 'Squarespace is not connected.' };
+    return ctx.api('DELETE', `/Squarespace/Config/${cfg.id}`);
+  },
+  squarespace_test_connection: async (_a, ctx) => ctx.api('POST', '/Squarespace/TestConnection', {}),
+};

package/parity/woocommerce.customer.js

@@ -0,0 +1,94 @@
+// MCP parity for `velaro woocommerce` (cli/lib/commands/woocommerce.js). Site from the credential; the CLI's optional --site
+// override is deliberately NOT exposed (tenant isolation).
+const lim = (v) => Math.min(50, Math.max(1, Number(v) || 10));
+
+export const tools = [
+  {
+    name: 'woocommerce_get_status',
+    description: 'Show the WooCommerce connection and billing status for your site.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'woocommerce_start_connect',
+    description: 'Start the WooCommerce store connection flow. Returns an authorization URL the store owner must open to approve Velaro.',
+    inputSchema: { type: 'object', properties: { storeUrl: { type: 'string', description: 'Store URL, e.g. https://mystore.com' } }, required: ['storeUrl'] },
+  },
+  {
+    name: 'woocommerce_disconnect',
+    description: 'Disconnect the WooCommerce store from your site.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'woocommerce_list_skills',
+    description: 'List the WooCommerce AI skills available to your site.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'woocommerce_search_orders',
+    description: 'Search WooCommerce orders by customer email or order ID.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        email: { type: 'string', description: 'Customer email address' },
+        orderId: { type: 'number', description: 'Order ID' },
+        limit: { type: 'number', description: 'Max results (default 10, max 50)' },
+      },
+    },
+  },
+  {
+    name: 'woocommerce_search_products',
+    description: 'Search the WooCommerce product catalog.',
+    inputSchema: {
+      type: 'object',
+      properties: { query: { type: 'string', description: 'Search term' }, limit: { type: 'number', description: 'Max results (default 10, max 50)' } },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'woocommerce_logs',
+    description: 'View WooCommerce integration activity logs for your site, optionally filtered by severity or text.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        severity: { type: 'string', description: 'Error, Warning or Info' },
+        search: { type: 'string', description: 'Text to find in messages' },
+        pageSize: { type: 'number', description: 'Entries to return (default 25, max 100)' },
+      },
+    },
+  },
+];
+
+export const handlers = {
+  woocommerce_get_status: async (_a, ctx) => (await ctx.messagingGet('/WooCommerce/billing/status')) ?? { connected: false },
+  woocommerce_start_connect: async (a, ctx) => {
+    if (!a.storeUrl) throw new Error('storeUrl is required');
+    const r = await ctx.messagingGet(`/WooCommerce/auth/start?storeUrl=${encodeURIComponent(a.storeUrl)}`);
+    if (!r?.authUrl) throw new Error('Server did not return an authUrl; check the store URL.');
+    return r;
+  },
+  woocommerce_disconnect: async (_a, ctx) => {
+    await ctx.messagingPost('/WooCommerce/auth/disconnect', {});
+    return { disconnected: true };
+  },
+  woocommerce_list_skills: async (_a, ctx) => {
+    const data = await ctx.api('GET', '/AI/Skills');
+    const skills = Array.isArray(data) ? data : (data?.skills ?? []);
+    return skills.filter((s) => s.category === 'WooCommerce');
+  },
+  woocommerce_search_orders: async (a, ctx) => {
+    const q = a.orderId ?? a.email;
+    if (!q) throw new Error('email or orderId is required');
+    return ctx.messagingGet(`/WooCommerce/data/orders?email=${encodeURIComponent(q)}&limit=${lim(a.limit)}`);
+  },
+  woocommerce_search_products: async (a, ctx) => {
+    if (!a.query) throw new Error('query is required');
+    return ctx.messagingGet(`/WooCommerce/data/products?query=${encodeURIComponent(a.query)}&limit=${lim(a.limit)}`);
+  },
+  woocommerce_logs: async (a, ctx) => {
+    const p = new URLSearchParams();
+    if (a.severity) p.set('severity', a.severity);
+    if (a.search) p.set('search', a.search);
+    p.set('pageSize', String(Math.min(100, Math.max(1, Number(a.pageSize) || 25))));
+    return ctx.api('GET', `/Integration/Logs/WooCommerce?${p}`);
+  },
+};

package/parity/zoom-phone.customer.js

@@ -0,0 +1,49 @@
+// MCP parity for `velaro zoom-phone` (cli/lib/commands/zoom-phone.js). Site from the credential.
+export const tools = [
+  {
+    name: 'zoom_phone_get_status',
+    description: 'Show the voice provider, Zoom account_id and whether a webhook secret is saved for your site (the secret is never returned).',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'zoom_phone_list_numbers',
+    description: 'List the Zoom Phone numbers assigned on the connected Zoom account.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'zoom_phone_set_config',
+    description: 'Save the Zoom account_id and/or webhook secret for Zoom Phone screen-pop. Refuses if the site already uses a different voice provider.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        accountId: { type: 'string', description: 'Zoom account_id (from a webhook payload or Account Profile)' },
+        webhookSecret: { type: 'string', description: 'Secret token from the Zoom Event Subscription' },
+      },
+    },
+  },
+];
+
+export const handlers = {
+  zoom_phone_get_status: async (_a, ctx) => {
+    const c = await ctx.messagingGet('/voice/admin/config');
+    if (!c?.configured) return { configured: false };
+    return { configured: true, providerSlug: c.providerSlug, zoomAccountId: c.zoomAccountId || null, hasWebhookSecret: !!c.hasWebhookSecret };
+  },
+  zoom_phone_list_numbers: async (_a, ctx) => {
+    const r = await ctx.messagingGet('/ZoomPhoneCti/numbers');
+    return { phoneNumbers: r?.phoneNumbers || [] };
+  },
+  zoom_phone_set_config: async (a, ctx) => {
+    if (!a.accountId && !a.webhookSecret) throw new Error('Pass accountId and/or webhookSecret.');
+    const current = await ctx.messagingGet('/voice/admin/config');
+    if (current?.configured && current.providerSlug && current.providerSlug !== 'zoom') {
+      throw new Error(`Site already uses voice provider "${current.providerSlug}". Switch providers in the admin UI before configuring Zoom Phone.`);
+    }
+    await ctx.messagingPost('/voice/admin/config', {
+      providerSlug: 'zoom',
+      zoomAccountId: a.accountId ? String(a.accountId).trim() : undefined,
+      webhookSecret: a.webhookSecret || undefined,
+    });
+    return handlers.zoom_phone_get_status({}, ctx);
+  },
+};