@velaro/mcp-server 0.6.98 → 0.6.100

package/package.json

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

@@ -40,6 +40,7 @@
  *   VELARO_MCP_MODE=http PORT=3000 node server.js
  */
 
+import { describeRawMeta, fetchRetry429 } from './log-search.js';
 import { Server }            from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import {
@@ -119,11 +120,12 @@ function parseDuration(s) {
   return n * 24 * 3600 * 1000;
 }
 
-async function messagingApi(path, opts = {}) {
+async function messagingApi(path, opts = {}) {  // opts.timeoutMs: log searches pass 40000 (server scan budget 12 s + 6 s AI search)
   if (!MESSAGING_API) throw new Error(
     'VELARO_MESSAGING_API is not configured. Add "VELARO_MESSAGING_API": "https://velaro-messaging-api-staging.azurewebsites.net" to your MCP env config.'
   );
-  const res = await fetch(`${MESSAGING_API}${path}`, {
+  // 429 = the server's per-instance scan gate is full: retry honouring Retry-After (GETs only; a retried POST could repeat a write).
+  const init = () => ({
     method: opts.method ?? 'GET',
     headers: {
       Authorization: authHeader(),
@@ -131,8 +133,9 @@ async function messagingApi(path, opts = {}) {
       ...(opts.body ? { 'Content-Type': 'application/json' } : {}),
     },
     body: opts.body ? JSON.stringify(opts.body) : undefined,
-    signal: AbortSignal.timeout(20000),
+    signal: AbortSignal.timeout(opts.timeoutMs ?? 20000),
   });
+  const res = (opts.method ?? 'GET') === 'GET' ? await fetchRetry429(`${MESSAGING_API}${path}`, init) : await fetch(`${MESSAGING_API}${path}`, init());
   if (!res.ok) {
     const text = await res.text().catch(() => '');
     throw new Error(`Velaro Logger ${path} -> ${res.status}: ${text.slice(0, 300)}`);
@@ -845,12 +848,12 @@ const TOOLS = [
   {
     name: 'canned_learning_suggestions',
     description: 'List AI-proposed canned message improvements awaiting human review (learned from low ratings and never-used messages). Each row shows currentText, proposedText, the reason, the signals it learned from, and a review state (pending_review, approved, rejected, rolled_back). Intelligence Suite entitlement required.',
-    inputSchema: { type: 'object', properties: { state: { type: 'string', description: 'pending_review (default), approved, rejected, rolled_back, or all' } } },
+    inputSchema: { type: 'object', properties: { state: { type: 'string', description: 'pending_review (default), approved, rejected, rolled_back, or all' }, teamId: { type: 'number', description: 'Only suggestions for canned responses on this team. Team managers only ever see their own teams.' } } },
   },
   {
     name: 'canned_learning_generate',
-    description: 'Analyze this site canned message usage and ratings and queue AI-proposed improvements for human review. Nothing changes until approved. Capped at 5 messages per run and one run per day; text is PII-redacted before it reaches the model.',
-    inputSchema: { type: 'object', properties: {} },
+    description: 'Analyze this site canned message usage and ratings and queue AI-proposed improvements for human review. Nothing changes until approved. Capped at 5 messages per run and one run per day (per team when teamId is given); text is PII-redacted before it reaches the model. Team managers must pass a teamId they manage.',
+    inputSchema: { type: 'object', properties: { teamId: { type: 'number', description: 'Only generate for canned responses on this team' } } },
   },
   {
     name: 'canned_learning_approve',
@@ -865,6 +868,11 @@ const TOOLS = [
   {
     name: 'canned_learning_edit_summary',
     description: 'Which canned messages agents edit most before sending (last 90 days): canned response id, shortcut, edit count and average similarity of the sent text to the original. This is the edited-before-send evidence the weekly canned message learning job uses. Intelligence Suite entitlement required.',
+    inputSchema: { type: 'object', properties: { teamId: { type: 'number', description: 'Only canned responses on this team' } } },
+  },
+  {
+    name: 'canned_learning_teams',
+    description: 'Teams the caller can review canned message learning for: every site team for a site supervisor, only managed teams for a team manager. Use the ids as teamId on the other canned_learning tools.',
     inputSchema: { type: 'object', properties: {} },
   },
   {
@@ -2152,6 +2160,62 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['fromIndex', 'toIndex'],
     },
   },
+  {
+    name: 'safety_events_list',
+    description: "List the site's safety events (emergency, emergency_unconfirmed, therapy_setting_change, fail_closed, output_guardrail_block, visitor_report, off_topic_attempt). Needs the EnableTroubleshootingKnowledge entitlement. Wraps GET SafetyEvents; the site comes from the caller auth, never an argument.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        from:   { type: 'string', description: 'ISO start date/time' },
+        to:     { type: 'string', description: 'ISO end date/time' },
+        type:   { type: 'string', description: 'One event type' },
+        status: { type: 'string', enum: ['open', 'acknowledged'] },
+        take:   { type: 'number', description: 'Page size, default 25' },
+        skip:   { type: 'number', description: 'Rows to skip, default 0' },
+      },
+    },
+  },
+  {
+    name: 'safety_events_summary',
+    description: 'Per-day and total safety event counts by type for the last N days (default 7). Wraps GET SafetyEvents/summary.',
+    inputSchema: { type: 'object', properties: { days: { type: 'number', description: 'Default 7, e.g. 30' } } },
+  },
+  {
+    name: 'safety_event_ack',
+    description: 'Mark one safety event as reviewed. Wraps POST SafetyEvents/{id}/acknowledge.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+  },
+  {
+    name: 'safety_settings_get',
+    description: 'Get the safety alert settings: enabled, emailRecipients, smsRecipients, immediateTypes, digest (off|daily|weekly), threshold {count, windowMinutes}. Wraps GET SafetyEvents/settings.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'safety_settings_set',
+    description: 'Change the safety alert settings. Only the fields you pass change; the rest keep their current value. Wraps PUT SafetyEvents/settings (reads the current settings first).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        enabled:         { type: 'boolean' },
+        emailRecipients: { type: 'array', items: { type: 'string' } },
+        smsRecipients:   { type: 'array', items: { type: 'string' }, description: 'E.164 numbers, e.g. +15551234567' },
+        immediateTypes:  { type: 'array', items: { type: 'string' }, description: 'Event types that alert right away' },
+        digest:          { type: 'string', enum: ['off', 'daily', 'weekly'] },
+        thresholdCount:  { type: 'number', description: 'Alert when this many events happen inside the window. 0 turns it off.' },
+        thresholdWindowMinutes: { type: 'number', description: '1 to 10080' },
+      },
+    },
+  },
+  {
+    name: 'safety_settings_test',
+    description: 'Send a test safety alert to the configured recipients. Wraps POST SafetyEvents/settings/test.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'safety_need_help',
+    description: 'Tell the Velaro team the bot is going off the rails and you need help now. Wraps POST SafetyEvents/need-help.',
+    inputSchema: { type: 'object', properties: { message: { type: 'string', description: 'What is happening' } }, required: ['message'] },
+  },
   {
     name: 'index_move_status',
     description: 'Status of one move (moveId) or the recent moves (omit moveId): status, per-document progress, canResume/canAbort/canUndo. Wraps GET IndexMove/Moves[/{id}].',
@@ -2864,6 +2928,25 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  // ── Chat Window launcher copy (per-page launcher label + greeting) ─────────
+  {
+    name: 'chat_window_list',
+    description: 'List chat windows for this site with the launcher label (launcherText) and greeting. Point a Select Chat Window workflow node or Determine Experience Bundle rule at a window to show its label and greeting on specific pages.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'chat_window_set_launcher_copy',
+    description: 'Set the launcher label (the text pill on the chat button, max 60 chars) and/or the opening greeting (max 256 chars) on one chat window. Omitted fields are left unchanged; an empty string clears the field and the widget falls back to its default. For per-page copy, create one chat window per page type (and per language) and select it with a Select Chat Window workflow node.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Chat window ID (see chat_window_list)' },
+        launcherText: { type: 'string', description: 'Launcher label, e.g. "Troubleshoot my device"' },
+        greeting: { type: 'string', description: 'Opening greeting shown when the window opens' },
+      },
+      required: ['id'],
+    },
+  },
   // ── Page Widget Containers ────────────────────────────────────────────────
   {
     name: 'widget_container_list',
@@ -6340,15 +6423,17 @@ async function handleTool(name, args) {
       if (args.confirm) return await messagingPost('/ChatIntelligenceTopics/analysis', { confirm: true });
       return { estimate: await messagingGet('/ChatIntelligenceTopics/analysis/estimate'), cached: await messagingGet('/ChatIntelligenceTopics/analysis') };
     case 'canned_learning_suggestions':
-      return await messagingGet(`/CannedLearning/suggestions?state=${encodeURIComponent(args.state ?? 'pending_review')}`);
+      return await messagingGet(`/CannedLearning/suggestions?state=${encodeURIComponent(args.state ?? 'pending_review')}${args.teamId != null ? `&teamId=${encodeURIComponent(args.teamId)}` : ''}`);
     case 'canned_learning_generate':
-      return await messagingPost('/CannedLearning/generate', {});
+      return await messagingPost('/CannedLearning/generate', { teamId: args.teamId ?? null });
+    case 'canned_learning_teams':
+      return await messagingGet('/CannedLearning/teams');
     case 'canned_learning_approve':
       return await messagingPost(`/CannedLearning/suggestions/${args.suggestionId}/approve`, { editedText: args.editedText ?? null });
     case 'canned_learning_reject':
       return await messagingPost(`/CannedLearning/suggestions/${args.suggestionId}/reject`, {});
     case 'canned_learning_edit_summary':
-      return await messagingGet('/CannedLearning/edit-events');
+      return await messagingGet(`/CannedLearning/edit-events${args.teamId != null ? `?teamId=${encodeURIComponent(args.teamId)}` : ''}`);
     case 'canned_learning_record_edit':
       return await messagingPost('/CannedLearning/edit-events', { cannedResponseId: args.cannedResponseId, finalText: args.finalText });
     case 'canned_learning_rollback':
@@ -7569,9 +7654,18 @@ async function handleTool(name, args) {
       const from1h = new Date(Date.now() - 3600000).toISOString();
       const velaroLoggerP = safeJson(async () => {
         if (!MESSAGING_API) return { _error: 'VELARO_MESSAGING_API not set — add it to MCP env config' };
-        const q = encodeURIComponent('ERROR|WF-AI-ROUTE|PERF-SLOW');
-        const res = await messagingApi(`/superadmin/logs/search?q=${q}&from=${encodeURIComponent(from1h)}&take=30&regex=true`);
-        return extractLogEntries(res);
+        // Two honest reads (Opus review 2026-10-14): ERRORS use the server-side level=ERROR filter; PATTERNS are the WF-AI-ROUTE / PERF-SLOW regex (no level).
+        const f = encodeURIComponent(from1h);
+        // One at a time: the server runs at most 2 exact scans per instance.
+        const errRes = await messagingApi(`/superadmin/logs/search?level=ERROR&from=${f}&take=30`, { timeoutMs: 40000 });
+        const patRes = await messagingApi(`/superadmin/logs/search?q=${encodeURIComponent('WF-AI-ROUTE|PERF-SLOW')}&regex=true&from=${f}&take=30`, { timeoutMs: 40000 });
+        const byId = new Map();
+        for (const e of [...extractLogEntries(errRes), ...extractLogEntries(patRes)]) byId.set(e.id ?? `${e.timestamp}|${e.message}`, e);
+        const found = [...byId.values()].sort((x, y) => (Date.parse(y.timestamp ?? y.LogTimestamp) || 0) - (Date.parse(x.timestamp ?? x.LogTimestamp) || 0));
+        const verified = (r) => !!(r && !Array.isArray(r) && r.truncated === false);
+        found._verified = verified(errRes) && verified(patRes);
+        found._note = `errors: ${describeRawMeta(errRes)} | patterns: ${describeRawMeta(patRes)}`;
+        return found;
       });
 
       // ── Layer 4b: Loggly ERROR + SLOW + AI-routing logs (last 1h) — SECONDARY (migrating away)
@@ -7647,9 +7741,11 @@ async function handleTool(name, args) {
       if (velaroLogs?._error) {
         out.push(section('Velaro Logger (1h) [PRIMARY]', [`  ⚠ ${velaroLogs._error}`]));
       } else if (!Array.isArray(velaroLogs) || !velaroLogs.length) {
-        out.push(section('Velaro Logger (1h) [PRIMARY]', ['  ✅ No errors, slow responses, or AI routing events']));
+        out.push(section('Velaro Logger (1h) [PRIMARY]', velaroLogs?._verified
+          ? [`  ✅ No errors, slow responses, or AI routing events (${velaroLogs._note})`]
+          : [`  ⚠ No matches, but the scan is NOT verified complete: ${velaroLogs?._note ?? 'no scan metadata'}. Use velaro_logs_search before concluding all is well.`]));
       } else {
-        out.push(section(`Velaro Logger (1h) [PRIMARY] — ${velaroLogs.length} entries`, velaroLogs.map(fmtVelaroEntry)));
+        out.push(section(`Velaro Logger (1h) [PRIMARY] — ${velaroLogs.length} entries${velaroLogs._verified ? '' : ` (scan not verified complete: ${velaroLogs._note})`}`, velaroLogs.map(fmtVelaroEntry)));
       }
 
       // ── Loggly (secondary — being phased out; check if Velaro Logger is empty/errored)
@@ -7755,6 +7851,35 @@ async function handleTool(name, args) {
       const r = await messagingPost('/IndexMove/Split/Execute', body);
       return JSON.stringify(r, null, 2);
     }
+    case 'safety_events_list': {
+      const q = new URLSearchParams();
+      for (const k of ['from', 'to', 'type', 'status']) if (args[k]) q.set(k, String(args[k]));
+      q.set('take', String(args.take ?? 25));
+      q.set('skip', String(args.skip ?? 0));
+      return JSON.stringify(await messagingGet(`/SafetyEvents?${q}`), null, 2);
+    }
+    case 'safety_events_summary':
+      return JSON.stringify(await messagingGet(`/SafetyEvents/summary?days=${Number(args.days) || 7}`), null, 2);
+    case 'safety_event_ack':
+      return JSON.stringify(await messagingPost(`/SafetyEvents/${encodeURIComponent(args.id)}/acknowledge`), null, 2);
+    case 'safety_settings_get':
+      return JSON.stringify(await messagingGet('/SafetyEvents/settings'), null, 2);
+    case 'safety_settings_set': {
+      const cur = (await messagingGet('/SafetyEvents/settings')) ?? {};
+      const next = { ...cur };
+      for (const k of ['enabled', 'emailRecipients', 'smsRecipients', 'immediateTypes', 'digest']) if (args[k] !== undefined) next[k] = args[k];
+      if (args.thresholdCount !== undefined || args.thresholdWindowMinutes !== undefined) {
+        next.threshold = {
+          count: args.thresholdCount ?? cur.threshold?.count ?? 0,
+          windowMinutes: args.thresholdWindowMinutes ?? cur.threshold?.windowMinutes ?? 60,
+        };
+      }
+      return JSON.stringify(await messagingPut('/SafetyEvents/settings', next), null, 2);
+    }
+    case 'safety_settings_test':
+      return JSON.stringify(await messagingPost('/SafetyEvents/settings/test'), null, 2);
+    case 'safety_need_help':
+      return JSON.stringify(await messagingPost('/SafetyEvents/need-help', { message: args.message }), null, 2);
     case 'index_move_status': {
       const r = await messagingGet(args.moveId
         ? `/IndexMove/Moves/${encodeURIComponent(args.moveId)}`
@@ -8611,9 +8736,11 @@ async function handleTool(name, args) {
       if (args.environment)   params.set('environment',   args.environment);
       if (args.correlationId) params.set('correlationId', args.correlationId);
       if (args.regex)         params.set('regex',         'true');
-      const entries = extractLogEntries(await messagingApi(`/superadmin/logs/search?${params}`));
-      if (!entries.length) return 'No results.';
-      const lines = [`${entries.length} result(s) from ${from.toISOString().slice(0, 16)} UTC\n`];
+      const resp = await messagingApi(`/superadmin/logs/search?${params}`, { timeoutMs: 40000 });
+      const entries = extractLogEntries(resp);
+      const meta = describeRawMeta(resp);   // searchPath/scannedRows/truncated: a 0 or short list is never ambiguous
+      if (!entries.length) return `No results. ${meta}`;
+      const lines = [`${entries.length} result(s) from ${from.toISOString().slice(0, 16)} UTC. ${meta}\n`];
       for (const e of entries) {
         const ts    = new Date(e.timestamp ?? e.LogTimestamp).toISOString().replace('T', ' ').slice(0, 19);
         const lvl   = (e.Level ?? e.level ?? '?').padEnd(5);
@@ -8707,6 +8834,23 @@ async function handleTool(name, args) {
       ).join('\n');
     }
 
+    case 'chat_window_list': {
+      const r = (await messagingGet('/ChatWindow/list')) ?? [];
+      return JSON.stringify(r.map((w) => ({
+        id: w.id, name: w.name, language: w.languageConfig?.language,
+        launcherText: w.styleConfig?.launcherText ?? null, greeting: w.languageConfig?.greeting ?? null,
+      })), null, 2);
+    }
+
+    case 'chat_window_set_launcher_copy': {
+      if (!args.id) throw new Error('id is required');
+      const body = {};
+      if (args.launcherText !== undefined) body.launcherText = args.launcherText;
+      if (args.greeting !== undefined) body.greeting = args.greeting;
+      if (!Object.keys(body).length) throw new Error('provide launcherText and/or greeting');
+      return JSON.stringify(await messagingPut(`/ChatWindow/${args.id}/launcher-copy`, body), null, 2);
+    }
+
     case 'widget_container_get': {
       const c = await api('GET', `/PageWidgetContainers/${args.id}`);
       return JSON.stringify(c, null, 2);