@velaro/mcp-server 0.6.70 → 0.6.71

package/package.json

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

@@ -2617,6 +2617,22 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
 
   // ── Support Tools (Velaro staff only) ────────────────────────────────────────
+  {
+    name: 'support_add_site_user',
+    description: 'Velaro staff only. Create or ensure a NORMAL user (role agent or administrator, never staff/superadmin) on ANY customer site with an explicit non-forcing password, usable immediately. Idempotent: an existing user just gets the password set. Password goes in the HTTPS body only and is never logged or returned. Composes velaro-messaging SuperAdmin users create + set-password (same staff-WorkspaceUser auth caveat as site_provision: an MCP-key-only session may 403; use `velaro support add-site-user` then).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId:    { type: 'number', description: 'Target customer site ID' },
+        email:     { type: 'string' },
+        password:  { type: 'string', description: 'Min 8 characters' },
+        role:      { type: 'string', enum: ['agent', 'administrator'], description: 'Default agent' },
+        firstName: { type: 'string' },
+        lastName:  { type: 'string' },
+      },
+      required: ['siteId', 'email', 'password'],
+    },
+  },
   {
     name: 'support_agent_lookup',
     description: 'Resolve a bare messaging WorkspaceUser.Id (AgentId, e.g. from an AgentPresenceFlapping WARN or AgentConnectionLog entry that carries no SiteId) to its Email/DisplayName/SiteId across ALL sites. Read-only, Velaro staff only. Different ID space from support_user_lookup (which searches ApplicationUsers/login identity, not the per-agent messaging record).',
@@ -2704,6 +2720,34 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId'],
     },
   },
+  {
+    name: 'support_connection_timeline',
+    description: 'Raw ordered connection events (connected, disconnected, reconnecting) for ONE agent at a site over a time window, from velaro-messaging AgentConnectionLogs. Velaro staff only, read-only. Defaults to the last 24 hours.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId:          { type: 'number', description: 'Target site ID' },
+        workspaceUserId: { type: 'number', description: 'WorkspaceUser.Id of the agent (see support_site_agents)' },
+        from:            { type: 'string', description: 'ISO start (default: 24h before "to")' },
+        to:              { type: 'string', description: 'ISO end (default: now)' },
+        limit:           { type: 'number', description: 'Max events, 1-5000 (default 2000)' },
+      },
+      required: ['siteId', 'workspaceUserId'],
+    },
+  },
+  {
+    name: 'support_connection_evidence',
+    description: 'Dispute-grade connection evidence for a site and window: Velaro independent probe uptime %, incidents (including ones excluded from uptime, with the reason), per-agent disconnect counts, and client-vs-server reconciliation (disconnects with no unhealthy Velaro probe within 5 minutes are client/network side). Velaro staff only, read-only. Defaults to the last 30 days.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Target site ID' },
+        from:   { type: 'string', description: 'ISO start (default: 30 days before "to")' },
+        to:     { type: 'string', description: 'ISO end (default: now)' },
+      },
+      required: ['siteId'],
+    },
+  },
   {
     name: 'support_site_health',
     description: 'Get a full health snapshot for a customer site: subscription status/expiry, active agent count, last login, 7-day activity count, and integration error count. Velaro staff only.',
@@ -2722,6 +2766,14 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId'],
     },
   },
+  {
+    name: 'report_explain',
+    description: 'How to use and interpret a Velaro report: what it answers, data sources, setup prerequisites, how to read the numbers, why a value could be zero or empty, what to do, and related reports. Pass a report key (e.g. experience-impact, missed, surveys, schedule-adherence) or omit to list all keys. Static guidance, no site data.',
+    inputSchema: {
+      type: 'object',
+      properties: { report: { type: 'string', description: 'Report key. Omit to list all.' } },
+    },
+  },
   {
     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.',
@@ -7622,6 +7674,28 @@ async function handleTool(name, args) {
     }
 
     // ── Support Tools ─────────────────────────────────────────────────────────
+    case 'support_add_site_user': {
+      const roleMap = { agent: 'Agent', administrator: 'Administrator' };
+      const role = String(args.role || 'agent').toLowerCase();
+      if (!roleMap[role]) throw new Error('role must be agent or administrator.');
+      const email = String(args.email || '').trim().toLowerCase();
+      if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)) throw new Error('A valid email is required.');
+      if (typeof args.password !== 'string' || args.password.length < 8) throw new Error('password is required (min 8 characters).');
+      const listed = await messagingGet(`/SuperAdmin/users/${args.siteId}`);
+      const users = Array.isArray(listed) ? listed : (listed?.users || []);
+      let u = users.find(x => String(x.email || '').toLowerCase() === email);
+      let created = false;
+      if (!u) {
+        const c = await messagingPost(`/SuperAdmin/users/${args.siteId}`, { email, firstName: args.firstName || '', lastName: args.lastName || '', roles: [roleMap[role]], sendEmail: false });
+        if (!c?.success) throw new Error(`Create failed: ${c?.error || c?.message || 'unknown error'}`);
+        u = { id: c.user.id ?? c.user.Id };
+        created = true;
+      }
+      const sp = await messagingPost(`/SuperAdmin/users/${args.siteId}/${u.id}/set-password`, { newPassword: args.password });
+      if (sp && sp.success === false) throw new Error(`set-password failed: ${sp.error || 'unknown error'}`);
+      return JSON.stringify({ success: true, siteId: args.siteId, userId: u.id, email, created, passwordSet: true });
+    }
+
     case 'support_agent_lookup': {
       if (!args.id) return 'id is required (WorkspaceUser.Id / AgentId).';
       const res = await messagingApi(`/SuperAdmin/agents/${args.id}/lookup`);
@@ -7691,6 +7765,29 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    case 'support_connection_timeline': {
+      if (!args.siteId || !args.workspaceUserId) return 'siteId and workspaceUserId are required.';
+      const q = new URLSearchParams();
+      if (args.from) q.set('from', args.from);
+      if (args.to) q.set('to', args.to);
+      if (args.limit) q.set('limit', String(args.limit));
+      const qs = q.toString() ? `?${q}` : '';
+      const res = await messagingApi(`/SupportTools/sites/${args.siteId}/agents/${args.workspaceUserId}/connection-timeline${qs}`);
+      if (res?.error) return `Error: ${res.error}`;
+      return JSON.stringify(res, null, 2);
+    }
+
+    case 'support_connection_evidence': {
+      if (!args.siteId) return 'siteId is required.';
+      const q = new URLSearchParams();
+      if (args.from) q.set('from', args.from);
+      if (args.to) q.set('to', args.to);
+      const qs = q.toString() ? `?${q}` : '';
+      const res = await messagingApi(`/SupportTools/sites/${args.siteId}/connection-evidence${qs}`);
+      if (res?.error) return `Error: ${res.error}`;
+      return JSON.stringify(res, null, 2);
+    }
+
     case 'support_site_health': {
       const h = await api('GET', `/SupportTools/sites/${args.siteId}/health`);
       const sub = h.subscription;
@@ -7717,6 +7814,15 @@ async function handleTool(name, args) {
       ).join('\n');
     }
 
+    case 'report_explain': {
+      const all = JSON.parse(_readFileSync(_join(_dirname(_ftu(import.meta.url)), '..', 'cli', 'lib', 'report-explain.json'), 'utf8'));
+      const key = String(args.report ?? '').trim().toLowerCase();
+      if (!key) return Object.entries(all).map(([k, r]) => `${k}: ${r.name}`).join('\n');
+      const r = all[key];
+      if (!r) return `Unknown report "${key}". Valid keys: ${Object.keys(all).join(', ')}`;
+      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 '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]));
@@ -7739,6 +7845,12 @@ async function handleTool(name, args) {
           lines.push(`  ${label}: ${x.chats} chats | avg wait ${x.avgWaitSec}s | missed ${x.missed} | CSAT ${x.csatResponses ? x.csatAvg : '-'} (${x.csatResponses ?? 0})`);
         }
       }
+      // Additive fields from the rebuilt report (absent on older backends): CSAT coverage + per-KPI reasons.
+      if (r.coverage) {
+        const c = r.coverage;
+        lines.push(`CSAT coverage: ${(c.sources ?? []).map(x => `${x.label} ${x.responses} (avg ${x.avg ?? '-'})`).join(' | ')} | survey submissions ${c.surveySubmissions ?? 0}, rated ${c.surveyRated ?? 0}, response rate ${c.responseRatePct ?? 0}% | CSAT survey configured: ${c.csatSurveyConfigured ? 'yes' : 'no'}`);
+      }
+      for (const x of r.reasons ?? []) lines.push(`  Why ${x.kpi} is low/empty [${x.code}]: ${x.message}${x.action ? ' Action: ' + x.action : ''}`);
       for (const a of r.agents ?? []) lines.push(`  ${a.name}: index ${a.experienceIndex} | adherence ${a.adherencePct}% | CSAT ${a.csatAvg ?? '-'} | handled ${a.handled}`);
       return lines.join('\n');
     }