@velaro/mcp-server 2.0.0 → 2.0.2

package/fetch-retry.js

@@ -0,0 +1,23 @@
+// 429-aware fetch for the customer MCP (mcp/server.js). Same behavior as fetchRetry429 in
+// mcp/log-search.js, which is staff-only and not published (log-search.js must stay byte-identical
+// with cli/lib/log-search.js, so this small helper is a separate file rather than an import of it).
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * fetch that retries ONLY 429 (honouring Retry-After, seconds, capped at 30 s) for up to `retries` attempts and returns the final Response.
+ * `init` may be a function so each attempt gets a fresh AbortSignal.
+ */
+export async function fetchRetry429(url, init = {}, { retries = 3, fetchImpl = fetch, sleepImpl = sleep } = {}) {
+  for (let attempt = 0; ; attempt++) {
+    const res = await fetchImpl(url, typeof init === 'function' ? init() : init);
+    if (res.status === 429 && attempt < retries) {
+      // Number(null) is 0, which would turn a 429 without Retry-After into an immediate retry: a missing header means the 5 s default.
+      const raw = res.headers?.get?.('retry-after');
+      const ra = raw == null || raw === '' ? NaN : Number(raw);
+      await sleepImpl(Math.min(Number.isFinite(ra) && ra >= 0 ? ra : 5, 30) * 1000);
+      continue;
+    }
+    return res;
+  }
+}

package/messaging-base.js

@@ -1,7 +1,7 @@
 // Resolves the velaro-messaging API base for the MCP server.
 //
 // Incident 2026-10-23: the staging MCP was configured with VELARO_ADMIN_API only. Every tool that
-// lives in velaro-messaging (magento_diagnose, salesforce_diagnose, sap_diagnose, ...) either threw
+// lives in velaro-messaging (the integration diagnose tools, ...) either threw
 // "VELARO_MESSAGING_API is not configured" or, on older installs, called the ADMIN host and got a
 // bare 404 for /diagnostics/test-magento. The messaging base is fully determined by which admin
 // environment this process talks to, so derive it instead of requiring a second env var.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/mcp-server",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "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": {
@@ -43,11 +43,12 @@
   "files": [
     "server.js",
     "tool-annotations.js",
-    "log-search.js",
+    "fetch-retry.js",
     "messaging-base.js",
     "parity/loader.js",
     "parity/*.customer.js",
     "workflow-schedule.js",
+    "report-explain.json",
     "server.json",
     "README.md"
   ],

package/parity/activity.customer.js

@@ -1,4 +1,4 @@
-// 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.
+// velaro activity: integration activity logs and settings audit trail for the authenticated site. The CLI --site mode is staff-only and is not part of this package.
 // Parity module (CLI group -> MCP tools).
 
 const enc = encodeURIComponent;

package/report-explain.json

@@ -0,0 +1,232 @@
+{
+  "experience-impact": {
+    "name": "Experience Impact",
+    "answers": "How staffing and adherence affect what customers feel, as a 0 to 100 Experience Index.",
+    "sources": "Work Schedules and presence, chat queue timing, missed chats, and CSAT from ticket replies and 1-5 survey ratings (questions tagged csat or star_rating).",
+    "prerequisites": "Work Schedules for agents; a survey with a 1-5 CSAT or star question attached to post-chat or a workflow, or ticket CSAT requests turned on; chat traffic in range.",
+    "interpret": "Weights: service level 30, adherence 25, CSAT 25, missed chats 20; a signal with no data drops out. CSAT needs 5+ responses to count. Response rate = rated survey submissions / all survey submissions. Actual agents below scheduled while missed chats rise = staffing gap.",
+    "whyZero": "CSAT empty: no CSAT survey configured; survey exists but nobody answered; answers came in with no 1-5 rating question; fewer than 5 responses; or the range predates the survey. Surveyed but unrated? Managers run the CSAT backfill (survey ratings only, not ticket CSAT): preview, then apply, via the report banner, `velaro report-backfill csat`, or MCP report_backfill. Adherence empty: no Work Schedules.",
+    "fix": "Add a 1-5 star or CSAT question to the post-chat survey, enable ticket CSAT requests, widen the range, then fix the weakest component.",
+    "related": "Schedule Adherence, Service Level, Missed Chats, Surveys & NPS, Sentiment, Agent Performance"
+  },
+  "conversations": {
+    "name": "Conversations",
+    "answers": "How many conversations came in, on which channels and when.",
+    "sources": "Every conversation record on your account, grouped by channel, team, bot or agent, and time.",
+    "prerequisites": "At least one deployed channel (chat widget, SMS, email, voice, social).",
+    "interpret": "Overview shows totals and trend; Breakdown splits by channel, team and handler. Look at peaks by hour and day to plan staffing. Rising volume with flat staffing predicts longer waits.",
+    "whyZero": "No channel deployed or no traffic; the date range or team filter is too narrow; or you lack access to that team's data.",
+    "fix": "Widen the range, clear filters, confirm the deployment is live and the widget loads on your site.",
+    "related": "Service Level, Missed Chats, Visitor Traffic"
+  },
+  "missed": {
+    "name": "Missed Chats",
+    "answers": "Visitors who asked for help and got no live answer, and why.",
+    "sources": "Chat requests that ended without an agent or bot response, plus offline or unanswered conversations.",
+    "prerequisites": "Live chat deployed with agents or routing configured.",
+    "interpret": "Overview gives the missed count and rate. Breakdown shows time of day and team. Analysis groups likely causes such as nobody online, queue timeout, or visitor left. A missed spike at one hour points to a coverage gap.",
+    "whyZero": "Genuinely none, no chat traffic, or a bot answers everything so nothing reaches an agent queue.",
+    "fix": "Add agents or schedules for peak hours, review routing and after-hours behavior, enable offline message capture.",
+    "related": "Service Level, Experience Impact, Agent Availability"
+  },
+  "agent-performance": {
+    "name": "Agent Performance",
+    "answers": "How each agent handles conversations: volume, handle time, response speed and quality.",
+    "sources": "Conversations assigned to and handled by each agent, message timestamps, and survey scores where collected.",
+    "prerequisites": "Agents added to the account and handling chats.",
+    "interpret": "Compare an agent against the team over several weeks, not one day. Pair handle time with CSAT: fast and unhappy is a quality problem, slow and happy may be complex work.",
+    "whyZero": "Agent has no assigned chats in range, was not online, or the filter excludes their team. Quality scores need survey data.",
+    "fix": "Check routing assigns chats to that agent and that they set themselves available.",
+    "related": "Response Time, Agent Utilization, Surveys & NPS"
+  },
+  "response-time": {
+    "name": "Response Time",
+    "answers": "How quickly customers get a first reply and how long replies take afterwards.",
+    "sources": "Message timestamps between the customer's message and the first agent or bot reply.",
+    "prerequisites": "Chats with at least one reply.",
+    "interpret": "Look at the median and the slow tail together. A fine average with a long tail means some customers wait far too long.",
+    "whyZero": "No replies in range, or chats were only bot-handled and excluded from agent timing.",
+    "fix": "Add coverage at slow hours, turn on auto-greeting, review the routing capacity limit.",
+    "related": "Service Level, Agent Performance"
+  },
+  "service-level": {
+    "name": "Service Level",
+    "answers": "The share of chats answered within your target time.",
+    "sources": "Queue entry and first-answer timestamps compared with your configured service level threshold.",
+    "prerequisites": "A service level threshold in report settings and chats that enter an agent queue.",
+    "interpret": "A common target is 80 percent answered in 30 seconds. Check the trend by hour to find breaches.",
+    "whyZero": "No chats were queued for agents in the range, or no threshold is set.",
+    "fix": "Set the threshold, then staff to the hours that breach it.",
+    "related": "Response Time, Missed Chats, Experience Impact"
+  },
+  "sentiment": {
+    "name": "Sentiment",
+    "answers": "The overall tone of customer messages, by contact and by agent.",
+    "sources": "AI sentiment scoring of conversation messages.",
+    "prerequisites": "Sentiment reporting enabled on your plan and enough conversations to score.",
+    "interpret": "Watch the trend and the share of negative conversations. Use By Agent for coaching, By Contact to spot at-risk customers. Sentiment is inferred from text, so treat single scores as hints.",
+    "whyZero": "Feature not enabled, conversations too short to score, or scoring has not run yet for recent chats.",
+    "fix": "Confirm the plan includes it, widen the range, check again after the next processing cycle.",
+    "related": "Customer Health, Surveys & NPS, Experience Impact"
+  },
+  "health": {
+    "name": "Customer Health",
+    "answers": "Which contacts look healthy or at risk based on recent interactions.",
+    "sources": "Conversation frequency, sentiment, unresolved issues and survey results per contact.",
+    "prerequisites": "Contacts with conversation history.",
+    "interpret": "Low scores with rising contact frequency are the first to act on. Scores are relative to your own customers.",
+    "whyZero": "New account with little history, or sentiment data is not yet available.",
+    "fix": "Allow history to accumulate and enable surveys to add a direct signal.",
+    "related": "Sentiment, Surveys & NPS, Intelligence Suite"
+  },
+  "surveys": {
+    "name": "Surveys & NPS",
+    "answers": "What customers say in surveys: CSAT, NPS and custom questions, and how many respond.",
+    "sources": "Survey answers collected after chats, through workflows, standalone links or email.",
+    "prerequisites": "At least one active survey (post-chat CSAT, NPS or custom) delivered on a channel.",
+    "interpret": "Read the average with the response count and response rate. NPS is promoters minus detractors. Under about 30 responses, trends are noisy.",
+    "whyZero": "No survey enabled, survey not attached to the channel or workflow, nobody responded, or the range predates the survey. The visitor may close the chat before the survey shows.",
+    "fix": "Enable a short post-chat survey on every staffed channel, test it yourself, and keep questions to one or two.",
+    "related": "Experience Impact, Sentiment, Missed Chats"
+  },
+  "tickets": {
+    "name": "Tickets",
+    "answers": "Ticket volume, status, age and resolution speed.",
+    "sources": "Tickets created from email, forms, chats and manual entry.",
+    "prerequisites": "Ticketing or an email inbox connected.",
+    "interpret": "Watch open backlog and time to resolve. A growing backlog with steady intake means capacity is short.",
+    "whyZero": "Ticketing not enabled, no inbox connected, or no tickets in range.",
+    "fix": "Connect an inbox or enable ticket creation from forms and chat.",
+    "related": "Conversations, Agent Performance"
+  },
+  "calls": {
+    "name": "Calls",
+    "answers": "Phone call volume, duration, answered and missed calls.",
+    "sources": "Call records from your connected phone line or voice integration.",
+    "prerequisites": "A provisioned phone line or connected voice integration.",
+    "interpret": "Compare answered against missed by hour. Long durations may signal complexity or unresolved issues.",
+    "whyZero": "No phone line connected or no calls in range.",
+    "fix": "Connect a number and confirm it routes into Velaro.",
+    "related": "IVR, Voice"
+  },
+  "ivr": {
+    "name": "IVR",
+    "answers": "How callers move through your phone menus and where they drop off.",
+    "sources": "IVR call events for each menu step and outcome.",
+    "prerequisites": "An IVR configured on a phone line.",
+    "interpret": "A high drop-off at one step suggests a confusing prompt. Many transfers to an agent from one option shows demand to automate.",
+    "whyZero": "No IVR configured or no calls reached it.",
+    "fix": "Complete IVR setup, place a test call, then re-check.",
+    "related": "Calls, Voice"
+  },
+  "account-utilization": {
+    "name": "Account Utilization",
+    "answers": "How much of your plan (agents, bots, AI usage, channels) you are using.",
+    "sources": "Plan limits compared with measured usage on your account.",
+    "prerequisites": "Administrator or manager access.",
+    "interpret": "Near 100 percent means you may need a higher limit; very low usage means features you pay for are idle.",
+    "whyZero": "Feature not enabled yet or no usage in range.",
+    "fix": "Turn on unused features or request a limit increase.",
+    "related": "Agent Utilization"
+  },
+  "agent-availability": {
+    "name": "Agent Availability",
+    "answers": "When agents were online, away or offline.",
+    "sources": "Agent presence and status changes.",
+    "prerequisites": "Agents logging in to the workspace.",
+    "interpret": "Compare online time with scheduled time and chat demand to find coverage gaps.",
+    "whyZero": "Agents did not log in or the selected agents are not in range.",
+    "fix": "Confirm agents sign in and set their status to available.",
+    "related": "Schedule Adherence, Agent Utilization, Missed Chats"
+  },
+  "agent-utilization": {
+    "name": "Agent Utilization",
+    "answers": "How busy agents are compared with their capacity.",
+    "sources": "Concurrent chat load and online time per agent.",
+    "prerequisites": "Administrator or manager access; agents handling chats.",
+    "interpret": "Around 60 to 80 percent is healthy. Above that risks long waits and burnout, well below means spare capacity.",
+    "whyZero": "Agents were not online or not given chats.",
+    "fix": "Rebalance routing and capacity limits.",
+    "related": "Agent Availability, Agent Performance"
+  },
+  "visitor-traffic": {
+    "name": "Visitor Traffic",
+    "answers": "Who is visiting pages that have the Velaro widget and how many start chats.",
+    "sources": "Visitor tracking from the widget script on your site.",
+    "prerequisites": "Visitor tracking enabled and the widget installed on your pages.",
+    "interpret": "Compare visits with chats started to find pages where engagement is low.",
+    "whyZero": "Widget not installed on those pages, tracking not enabled, or an ad blocker or consent setting blocks it.",
+    "fix": "Verify the embed code on the live page and the tracking setting.",
+    "related": "Conversations"
+  },
+  "schedule-adherence": {
+    "name": "Schedule Adherence",
+    "answers": "Whether agents were online when scheduled.",
+    "sources": "Work Schedules compared with agent presence, plus approved exceptions.",
+    "prerequisites": "Work Schedules assigned to agents; the site time zone set correctly.",
+    "interpret": "Adherence is minutes available during scheduled time divided by scheduled minutes. Approved exceptions are excluded. Use Intraday for now and Timeline for the day's detail.",
+    "whyZero": "No schedules assigned, agents not scheduled in range, or time zone mismatch.",
+    "fix": "Create and assign schedules and check the time zone.",
+    "related": "Experience Impact, Agent Availability, Service Level"
+  },
+  "chat-intelligence": {
+    "name": "Chat Intelligence",
+    "answers": "What topics customers ask about, trends, and where the bot or KB falls short.",
+    "sources": "AI topic grouping of conversations and missed topics.",
+    "prerequisites": "Enough conversations (typically dozens) and the feature enabled.",
+    "interpret": "Rising themes show new demand. Missed topics are KB gaps: write or ingest content for them. Recommendations can be applied or dismissed.",
+    "whyZero": "Too little traffic, feature not enabled, or analysis has not run.",
+    "fix": "Widen the range and allow the next analysis run.",
+    "related": "Intelligence Suite, Conversation Efficiency"
+  },
+  "conversation-efficiency": {
+    "name": "Conversation Efficiency",
+    "answers": "How efficiently conversations are resolved and where time is lost.",
+    "sources": "Message counts, handle time, transfers and outcomes.",
+    "prerequisites": "Conversations with agent involvement.",
+    "interpret": "Agents shows who is above or below the norm, Correlation shows what drives long chats, Recommendations suggests actions.",
+    "whyZero": "No handled conversations in range.",
+    "fix": "Widen the range or pick a team with traffic.",
+    "related": "Agent Performance, Chat Intelligence"
+  },
+  "intelligence": {
+    "name": "Intelligence Suite",
+    "answers": "AI analysis across agents, customers, knowledge gaps, volume forecasts, revenue impact, competitors and channels.",
+    "sources": "Conversation history, surveys, and connected commerce or CRM data where present.",
+    "prerequisites": "Feature enabled on the plan and a few weeks of data. Revenue Impact needs a commerce or CRM integration.",
+    "interpret": "Treat each tab as guidance. Predictive Volume is a forecast, not a guarantee. Revenue Impact is an estimate from connected data.",
+    "whyZero": "Not enough history, missing integration, or feature not enabled.",
+    "fix": "Connect the relevant integration and allow data to accumulate.",
+    "related": "Customer Health, Chat Intelligence"
+  },
+  "operations": {
+    "name": "Operations Center",
+    "answers": "Live view of queues, agents and conversations right now.",
+    "sources": "Real-time presence and queue state.",
+    "prerequisites": "Workforce management enabled.",
+    "interpret": "Use it for moment-to-moment staffing. A rising queue with idle agents suggests a routing problem.",
+    "whyZero": "No active conversations or agents online.",
+    "fix": "Confirm agents are online and routing is active.",
+    "related": "Agent Availability, Service Level"
+  },
+  "voice": {
+    "name": "Voice",
+    "answers": "Individual call history and voice usage and billing.",
+    "sources": "Call log and voice minute usage.",
+    "prerequisites": "Voice enabled with a phone number.",
+    "interpret": "Call Log for detail, Usage for minutes against your plan.",
+    "whyZero": "No voice line or no calls.",
+    "fix": "Set up a voice number.",
+    "related": "Calls, IVR"
+  },
+  "email-subscriptions": {
+    "name": "Email Reports",
+    "answers": "Scheduled report summaries emailed to you.",
+    "sources": "The same data as the reports, summarized on your schedule.",
+    "prerequisites": "Access to the underlying report; some are manager or admin only.",
+    "interpret": "Each email links back to the full report.",
+    "whyZero": "Subscription not saved, the report is not on your plan, or it had no data for the period.",
+    "fix": "Re-save the subscription and check spam filtering for noreply@velaro.com.",
+    "related": "All reports"
+  }
+}