@velaro/mcp-server 0.6.73 → 0.6.75

package/package.json

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

@@ -179,8 +179,26 @@ function teamRoutingConfigPath(teamId) {
   return `/RoutingConfig?teamId=${n}`;
 }
 const messagingPatch = (path, body) => messagingRequest('PATCH', path, body);
+function execInsightsRange(days) {
+  const d = Math.min(Math.max(Number(days) || 7, 1), 92);
+  const to = new Date();
+  return new URLSearchParams({ from: new Date(to.getTime() - d * 86400000).toISOString(), to: to.toISOString() });
+}
+
 const messagingDel   = (path)       => messagingRequest('DELETE', path);
 
+// Skill-based routing CRUD helper for SkillRouting/{Skills|Assignments|Requirements}.
+async function skillRoutingCrud(resource, args, fields) {
+  const body = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
+  switch (args.action) {
+    case 'list': return await messagingGet('/SkillRouting/' + resource);
+    case 'create': return await messagingPost('/SkillRouting/' + resource, body);
+    case 'update': return await messagingPut('/SkillRouting/' + resource + '/' + args.id, body);
+    case 'delete': return await messagingDel('/SkillRouting/' + resource + '/' + args.id);
+    default: throw new Error('action must be list|create|update|delete');
+  }
+}
+
 async function api(method, path, body, base = API_BASE) {
   // Normalize: a path without a leading slash would glue onto the host ("...comScraperJobs/...") and fail as "fetch failed".
   if (!path.startsWith('/')) path = '/' + path;
@@ -765,6 +783,8 @@ const TOOLS = [
         startDate: { type: 'string', description: 'ISO date (defaults to 90 days ago)' },
         endDate:   { type: 'string', description: 'ISO date (defaults to today)' },
         groupBy:   { type: 'string', description: '"month" or "week" (default month)' },
+        deploymentId: { type: 'number', description: 'Optional website (deployment row id) filter' },
+        teamId:    { type: 'number', description: 'Optional team filter' },
       },
     },
   },
@@ -2801,6 +2821,46 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       properties: { report: { type: 'string', description: 'Report key. Omit to list all.' } },
     },
   },
+  {
+    name: 'friction_radar',
+    description: 'Friction Radar: conversation topics ranked by estimated agent cost (handle time plus a fixed penalty per escalation and abandoned chat), with volume, week-over-week growth versus the prior period of equal length and up to 3 example conversation ids per topic. Demo data excluded. Chat Intelligence entitlement required. Scoped to the caller site.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days:  { type: 'number', description: 'Look-back window in days, 1-92 (default 7).' },
+        limit: { type: 'number', description: 'Max topics, 1-100 (default 20).' },
+      },
+    },
+  },
+  {
+    name: 'executive_brief',
+    description: 'Executive brief for the last N days: conversation volume and growth, sentiment split, average QA rubric score, Experience Impact (index, CSAT, service level, missed chats), fastest rising keywords and top friction topics. Same data as the Monday executive-brief email. Chat Intelligence entitlement required.',
+    inputSchema: {
+      type: 'object',
+      properties: { days: { type: 'number', description: 'Look-back window in days, 1-92 (default 7).' } },
+    },
+  },
+  {
+    name: 'report_data_export',
+    description: 'Export conversations as CSV (sentiment, QA score, tag, escalations, handle seconds, abandoned, keywords) for the last N days; max 20,000 rows. To schedule it by email use executive_insights_subscribe with reportType data-export. Chat Intelligence entitlement required.',
+    inputSchema: {
+      type: 'object',
+      properties: { days: { type: 'number', description: 'Look-back window in days, 1-92 (default 7).' } },
+    },
+  },
+  {
+    name: 'executive_insights_subscribe',
+    description: 'Email the caller the executive-brief (weekly sends on Monday at deliveryHour site time, default 7 = 7:00 AM) or a scheduled data-export CSV. Creates or updates the caller report subscription.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        reportType:   { type: 'string', enum: ['executive-brief', 'data-export'] },
+        frequency:    { type: 'string', enum: ['daily', 'biweekly', 'weekly', 'monthly'], description: 'Default weekly.' },
+        deliveryHour: { type: 'number', description: 'Site-local hour 0-23 (default 7).' },
+      },
+      required: ['reportType'],
+    },
+  },
   {
     name: 'experience_impact_report',
     description: 'Experience Impact report: shows how staffing and schedule adherence affect customer experience. Returns a 0-100 experience index (adherence 25, service level 30, missed-chat rate 20, CSAT 25), per-interval staffing vs chat demand (scheduled vs actual agents, missed chats, wait time, CSAT), per-agent rows, a bot-vs-human breakdown (bot only, bot-to-human handoff, human only, with wait, missed, CSAT and bot containment rate), and plain-language insights. Scoped to the caller site.',
@@ -4940,6 +5000,21 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     description: 'Get the Focus Inbox draft-pregeneration usage/cap report for this site -- whether the "Always Learning" background draft-pregeneration addon is entitled (EnableFocusDraftPregeneration), plus the live usage snapshot (used/max/percent) against the site\'s monthly draft-pregeneration cap. Use to check whether the addon is active and how close the site is to its cap.',
     inputSchema: { type: 'object', properties: {} },
   },
+  {"name":"sentiment_report","description":"Sentiment report (v20). kind = overview | breakdown | conversation-overview | conversation-breakdown | contact-overview | agent-breakdown. Optional deploymentId (website) and teamId filters, verified server-side against your site.","inputSchema":{"type":"object","properties":{"kind":{"type":"string","description":"overview (default), breakdown, conversation-overview, conversation-breakdown, contact-overview, agent-breakdown"},"startDate":{"type":"string","description":"ISO date (default 30 days ago)"},"endDate":{"type":"string","description":"ISO date (default now)"},"groupBy":{"type":"string","description":"day (default), week, month"},"excludeBots":{"type":"boolean"},"deploymentId":{"type":"number","description":"Optional website (deployment row id) filter; must belong to your site"},"teamId":{"type":"number","description":"Optional team filter"}}}},
+  {"name":"quality_agent_performance","description":"Conversation Quality agent performance (AI scores per agent). Optional deploymentId (website) and teamId filters.","inputSchema":{"type":"object","properties":{"days":{"type":"number","description":"Window in days (default 30)"},"deploymentId":{"type":"number","description":"Optional website (deployment row id) filter; must belong to your site"},"teamId":{"type":"number","description":"Optional team filter"}}}},
+  {"name":"keyword_intelligence_top","description":"Top keywords/phrases customers use over a date range. Optional groupBy, ngram size, limit, teamId, agentId, website.","inputSchema":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"},"groupBy":{"type":"string","description":"none (default) or a grouping dimension"},"ngram":{"type":"number","description":"Phrase length 1-3 (default 3)"},"limit":{"type":"number","description":"Default 50"},"teamId":{"type":"number"},"agentId":{"type":"number"},"website":{"type":"string"}},"required":["from","to"]}},
+  {"name":"keyword_intelligence_conversations","description":"Drill-down: conversations containing a keyword in a date range.","inputSchema":{"type":"object","properties":{"keyword":{"type":"string"},"from":{"type":"string"},"to":{"type":"string"},"teamId":{"type":"number"},"agentId":{"type":"number"}},"required":["keyword","from","to"]}},
+  {"name":"skill_routing_skills","description":"Skill-based routing: manage the skill catalog. action = list | create | update | delete. Requires the EnableSkillBasedRouting entitlement (403 otherwise).","inputSchema":{"type":"object","properties":{"action":{"type":"string"},"id":{"type":"number"},"name":{"type":"string"},"description":{"type":"string"}},"required":["action"]}},
+  {"name":"skill_routing_assignments","description":"Skill-based routing: assign skills to agents with proficiency 1-5. action = list | create | update | delete.","inputSchema":{"type":"object","properties":{"action":{"type":"string"},"id":{"type":"number"},"workspaceUserId":{"type":"number"},"agentSkillId":{"type":"number"},"proficiency":{"type":"number"}},"required":["action"]}},
+  {"name":"skill_routing_requirements","description":"Skill-based routing: required/preferred skills per deployment and/or team. action = list | create | update | delete. Update is partial. Requirements are disabled by default; set isEnabled true to turn on.","inputSchema":{"type":"object","properties":{"action":{"type":"string"},"id":{"type":"number"},"deploymentId":{"type":"number"},"teamId":{"type":"number"},"requiredSkillIds":{"type":"array","items":{"type":"number"}},"preferredSkillIds":{"type":"array","items":{"type":"number"}},"overflowWaitSeconds":{"type":"number"},"isEnabled":{"type":"boolean"}},"required":["action"]}},
+  {"name":"skill_routing_simulate","description":"Dry-run skill routing for a team: shows which agents would be narrowed to and why. Never assigns a conversation or writes the decision log.","inputSchema":{"type":"object","properties":{"teamId":{"type":"number"},"waitedSeconds":{"type":"number"}}}},
+  {"name":"qa_rubric","description":"Conversation Quality QA rubrics. action = list | get | default | create | update | delete. Pass rubric fields in \"rubric\". Requires EnableConversationQuality.","inputSchema":{"type":"object","properties":{"action":{"type":"string"},"id":{"type":"number"},"rubric":{"type":"object"}},"required":["action"]}},
+  {"name":"qa_low_scores","description":"Conversations scoring below the rubric threshold, for QA review.","inputSchema":{"type":"object","properties":{"threshold":{"type":"number"},"days":{"type":"number"},"agentId":{"type":"number"},"skip":{"type":"number"},"take":{"type":"number"}}}},
+  {"name":"ai_field_extraction_get_config","description":"Get the AI field extraction config (opt-in, default off; monthly cap). Requires the ai_field_extraction entitlement.","inputSchema":{"type":"object","properties":{}}},
+  {"name":"ai_field_extraction_update_config","description":"Update AI field extraction config (partial). enabled, monthlyCap (null = 500 default, hard ceiling 50000), createThemeTags.","inputSchema":{"type":"object","properties":{"enabled":{"type":"boolean"},"monthlyCap":{"type":"number"},"createThemeTags":{"type":"boolean"}}}},
+  {"name":"ai_field_extraction_correct_field","description":"Agent correction of an extracted field on a conversation.","inputSchema":{"type":"object","properties":{"conversationId":{"type":"number"},"fieldName":{"type":"string"},"value":{"type":"string"}},"required":["conversationId","fieldName","value"]}},
+  {"name":"qa_calibration","description":"QA calibration report (AI score vs human review) for the last N days.","inputSchema":{"type":"object","properties":{"days":{"type":"number"}}}},
+  {"name":"qa_alert_settings","description":"Get or set quality alert settings. Omit \"settings\" to read; pass it to update.","inputSchema":{"type":"object","properties":{"settings":{"type":"object"}}}},
 ];
 
 // ── IVR business-hours helper ─────────────────────────────────────────────────
@@ -5423,6 +5498,8 @@ async function handleTool(name, args) {
       if (args.startDate) qs.set('startDate', args.startDate);
       if (args.endDate)   qs.set('endDate', args.endDate);
       qs.set('groupBy', args.groupBy ?? 'month');
+      if (args.deploymentId != null) qs.set('deploymentId', String(args.deploymentId));
+      if (args.teamId != null) qs.set('teamId', String(args.teamId));
       return await messagingGet(`/Reports/chat-intelligence/themes?${qs.toString()}`);
     }
     case 'chat_intelligence_recommendations':
@@ -7897,6 +7974,39 @@ async function handleTool(name, args) {
       return [`=== ${r.name} ===`, `Answers: ${r.answers}`, `Sources: ${r.sources}`, `Setup: ${r.prerequisites}`, `How to read: ${r.interpret}`, `Why zero/empty: ${r.whyZero}`, `What to do: ${r.fix}`, `Related: ${r.related}`].join('\n');
     }
 
+    case 'friction_radar': {
+      const qs = execInsightsRange(args.days);
+      qs.set('limit', String(Math.min(Math.max(Number(args.limit) || 20, 1), 100)));
+      const r = await messagingGet(`/executive-insights/friction-radar?${qs}`);
+      const lines = [`=== Friction Radar (${r.conversationsScanned} conversations${r.truncated ? ', truncated' : ''}) ===`];
+      for (const t of r.topics ?? []) {
+        const growth = t.isNew ? 'new' : t.growthPct == null ? 'n/a' : `${t.growthPct}%`;
+        lines.push(`#${t.costRank} ${t.topic}: ${t.volume} chats (volume rank ${t.volumeRank}, ${growth}), ${t.escalations} escalated, ${t.abandoned} abandoned, ~${Math.round(t.estimatedCostMinutes)} agent min, examples ${(t.exampleConversationIds ?? []).join(', ') || '-'}`);
+      }
+      if (!(r.topics ?? []).length) lines.push('No tagged topics in this period.');
+      return lines.join('\n');
+    }
+
+    case 'executive_brief': {
+      const r = await messagingGet(`/executive-insights/brief?${execInsightsRange(args.days)}`);
+      return JSON.stringify(r.brief, null, 2);
+    }
+
+    case 'report_data_export': {
+      const r = await messagingGet(`/executive-insights/export?${execInsightsRange(args.days)}`);
+      return `${r.rows} rows${r.truncated ? ' (truncated at the row cap)' : ''}\n${r.csv}`;
+    }
+
+    case 'executive_insights_subscribe': {
+      if (!['executive-brief', 'data-export'].includes(args.reportType)) return 'Error: reportType must be executive-brief or data-export.';
+      await messagingPost('/report-subscriptions', {
+        reportType: args.reportType,
+        frequency: args.frequency ?? 'weekly',
+        deliveryHour: args.deliveryHour ?? 7,
+      });
+      return `Subscribed to ${args.reportType} (${args.frequency ?? 'weekly'}, ${args.deliveryHour ?? 7}:00 site time).`;
+    }
+
     case 'experience_impact_report': {
       const qs = new URLSearchParams();
       for (const k of ['from', 'to', 'teamId']) if (args[k] != null && args[k] !== '') qs.set(k, String(args[k]));
@@ -9780,6 +9890,72 @@ async function handleTool(name, args) {
       return JSON.stringify(result, null, 2);
     }
 
+
+    // -- Wave: sentiment / quality / keyword intelligence / skill routing / QA rubric --
+    case 'sentiment_report': {
+      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' };
+      const kind = args.kind ?? 'overview';
+      if (!routes[kind]) throw new Error('kind must be one of: ' + Object.keys(routes).join(', '));
+      const end = args.endDate ? new Date(args.endDate) : new Date();
+      const start = args.startDate ? new Date(args.startDate) : new Date(end.getTime() - 30 * 86400000);
+      const body = { Start: start.toISOString(), End: end.toISOString(), GroupBy: args.groupBy ?? 'day', ExcludeBots: args.excludeBots === true };
+      if (args.deploymentId != null) body.DeploymentId = args.deploymentId;
+      if (args.teamId != null) body.TeamId = args.teamId;
+      return await messagingPost('/Reports/' + routes[kind], body);
+    }
+    case 'quality_agent_performance': {
+      const qs = new URLSearchParams({ days: String(args.days ?? 30) });
+      if (args.deploymentId != null) qs.set('deploymentId', String(args.deploymentId));
+      if (args.teamId != null) qs.set('teamId', String(args.teamId));
+      return await messagingGet('/api/admin/Reports/AgentPerformance?' + qs.toString());
+    }
+    case 'keyword_intelligence_top': {
+      const qs = new URLSearchParams({ from: args.from, to: args.to, groupBy: args.groupBy ?? 'none', ngram: String(args.ngram ?? 3), limit: String(args.limit ?? 50) });
+      for (const k of ['teamId', 'agentId', 'website']) if (args[k] != null) qs.set(k, String(args[k]));
+      return await messagingGet('/api/keyword-intelligence/top?' + qs.toString());
+    }
+    case 'keyword_intelligence_conversations': {
+      const qs = new URLSearchParams({ keyword: args.keyword, from: args.from, to: args.to });
+      for (const k of ['teamId', 'agentId']) if (args[k] != null) qs.set(k, String(args[k]));
+      return await messagingGet('/api/keyword-intelligence/conversations?' + qs.toString());
+    }
+    case 'skill_routing_skills':
+      return await skillRoutingCrud('Skills', args, { Name: args.name, Description: args.description });
+    case 'skill_routing_assignments':
+      return await skillRoutingCrud('Assignments', args, { WorkspaceUserId: args.workspaceUserId, AgentSkillId: args.agentSkillId, Proficiency: args.proficiency });
+    case 'skill_routing_requirements':
+      return await skillRoutingCrud('Requirements', args, { DeploymentId: args.deploymentId, TeamId: args.teamId, RequiredSkillIds: args.requiredSkillIds, PreferredSkillIds: args.preferredSkillIds, OverflowWaitSeconds: args.overflowWaitSeconds, IsEnabled: args.isEnabled });
+    case 'skill_routing_simulate':
+      return await messagingPost('/SkillRouting/Simulate', { TeamId: args.teamId ?? null, WaitedSeconds: args.waitedSeconds ?? null });
+    case 'qa_rubric': {
+      const a = args.action;
+      if (a === 'list') return await messagingGet('/api/admin/QualityQa/rubrics');
+      if (a === 'default') return await messagingGet('/api/admin/QualityQa/rubrics/default');
+      if (a === 'get') return await messagingGet('/api/admin/QualityQa/rubrics/' + args.id);
+      if (a === 'create') return await messagingPost('/api/admin/QualityQa/rubrics', args.rubric ?? {});
+      if (a === 'update') return await messagingPut('/api/admin/QualityQa/rubrics/' + args.id, args.rubric ?? {});
+      if (a === 'delete') return await messagingDel('/api/admin/QualityQa/rubrics/' + args.id);
+      throw new Error('action must be list|get|default|create|update|delete');
+    }
+    case 'qa_low_scores': {
+      const qs = new URLSearchParams({ days: String(args.days ?? 30), skip: String(args.skip ?? 0), take: String(args.take ?? 50) });
+      if (args.threshold != null) qs.set('threshold', String(args.threshold));
+      if (args.agentId != null) qs.set('agentId', String(args.agentId));
+      return await messagingGet('/api/admin/QualityQa/low-scores?' + qs.toString());
+    }
+    case 'ai_field_extraction_get_config':
+      return await messagingGet('/AiFieldExtraction/Config');
+    case 'ai_field_extraction_update_config': {
+      const body = Object.fromEntries(Object.entries({ Enabled: args.enabled, MonthlyCap: args.monthlyCap, CreateThemeTags: args.createThemeTags }).filter(([, v]) => v !== undefined));
+      return await messagingPut('/AiFieldExtraction/Config', body);
+    }
+    case 'ai_field_extraction_correct_field':
+      return await messagingPut('/AiFieldExtraction/Conversation/' + args.conversationId + '/Fields/' + encodeURIComponent(args.fieldName), { Value: args.value });
+    case 'qa_calibration':
+      return await messagingGet('/api/admin/QualityQa/calibration?days=' + (args.days ?? 90));
+    case 'qa_alert_settings':
+      return args.settings ? await messagingPut('/api/admin/QualityQa/alert-settings', args.settings) : await messagingGet('/api/admin/QualityQa/alert-settings');
+
     default:
       throw new Error(`Unknown tool: ${name}`);
   }