@velaro/mcp-server 2.0.56 → 2.0.57

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -309,3 +309,8 @@ Velaro ships the MCP server, hosts it, auto-updates it, and publishes it to npm.
309
309
  - [npm package](https://www.npmjs.com/package/@velaro/mcp-server)
310
310
  - [Source](https://github.com/velaro/velaro-admin/tree/master/mcp)
311
311
  - [MCP Specification](https://modelcontextprotocol.io)
312
+
313
+ ## Loading fewer tools
314
+
315
+ Set `VELARO_MCP_TOOLSETS` to a comma-separated list (core, kb, conversations, workflows, reports, billing, integrations, misc) to list only those tool groups. Leave it unset for every tool.
316
+
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velaro/mcp-server",
3
- "version": "2.0.56",
3
+ "version": "2.0.57",
4
4
  "description": "Velaro MCP server — connect Claude and other AI agents directly to your Velaro account: KB, workflows, bots, conversations, contacts, routing, and more.",
5
5
  "type": "module",
6
6
  "bin": {
@@ -49,6 +49,7 @@
49
49
  "parity/loader.js",
50
50
  "parity/*.customer.js",
51
51
  "workflow-schedule.js",
52
+ "toolsets.js",
52
53
  "report-explain.json",
53
54
  "server.json",
54
55
  "README.md"
@@ -0,0 +1,49 @@
1
+ // MCP parity for `velaro teams-phone queues` (cli/lib/commands/teams-phone.js). Site from the credential only.
2
+ // Backend: velaro-messaging TeamsPhone/Queues (TeamsPhoneQueuesController -> TeamsPhoneQueueService). A queue is an extra
3
+ // Microsoft Teams resource account (for example "Service" or "Parts") that rings one Velaro team and is reported as its own
4
+ // queue in the speed to answer report. Needs the TeamsPhone entitlement and a finished Teams Phone setup.
5
+ export const tools = [
6
+ {
7
+ name: 'teams_phone_queue_list',
8
+ description: 'List the Microsoft Teams Phone queues for your site: id, resource account object id, phone number, queue name, the Velaro team it rings and the ring timeout.',
9
+ inputSchema: { type: 'object', properties: {} },
10
+ },
11
+ {
12
+ name: 'teams_phone_queue_set',
13
+ description: 'Add a Teams Phone queue, or update the one with the same resource account. Calls to that resource account ring the chosen Velaro team and are reported under the queue name.',
14
+ inputSchema: {
15
+ type: 'object',
16
+ properties: {
17
+ applicationInstanceObjectId: { type: 'string', description: 'Object id (GUID) of the queue\'s Teams resource account.' },
18
+ queueName: { type: 'string', description: 'Queue name shown in reports and on the call pop (1 to 128 characters).' },
19
+ assignedPhoneNumber: { type: 'string', description: 'The queue\'s phone number in E.164 (optional).' },
20
+ teamId: { type: 'number', description: 'Velaro team whose agents this queue rings (from team_list). Omit for any available agent.' },
21
+ ringTimeoutSeconds: { type: 'number', description: 'Seconds an agent is rung before the call moves on (5-120, default the main Teams setup).' },
22
+ },
23
+ required: ['applicationInstanceObjectId', 'queueName'],
24
+ },
25
+ },
26
+ {
27
+ name: 'teams_phone_queue_delete',
28
+ description: 'Remove a Teams Phone queue by id. Calls to its resource account are then rejected by Velaro.',
29
+ inputSchema: { type: 'object', properties: { id: { type: 'number', description: 'Queue id from teams_phone_queue_list.' } }, required: ['id'] },
30
+ },
31
+ ];
32
+
33
+ export const handlers = {
34
+ teams_phone_queue_list: async (_a, ctx) => ctx.messagingGet('/TeamsPhone/Queues'),
35
+ teams_phone_queue_set: async (a, ctx) => {
36
+ if (!a.applicationInstanceObjectId || !a.queueName) throw new Error('applicationInstanceObjectId and queueName are required.');
37
+ return ctx.messagingPost('/TeamsPhone/Queues', {
38
+ applicationInstanceObjectId: String(a.applicationInstanceObjectId).trim(),
39
+ queueName: String(a.queueName).trim(),
40
+ assignedPhoneNumber: a.assignedPhoneNumber ? String(a.assignedPhoneNumber).trim() : undefined,
41
+ teamId: a.teamId ?? undefined,
42
+ ringTimeoutSeconds: a.ringTimeoutSeconds ?? undefined,
43
+ });
44
+ },
45
+ teams_phone_queue_delete: async (a, ctx) => {
46
+ if (a.id == null) throw new Error('id is required.');
47
+ return ctx.messagingDel(`/TeamsPhone/Queues/${encodeURIComponent(a.id)}`);
48
+ },
49
+ };
package/server.js CHANGED
@@ -51,6 +51,7 @@ import {
51
51
  } from '@modelcontextprotocol/sdk/types.js';
52
52
  import { withAnnotations } from './tool-annotations.js';
53
53
  import { loadParity, runParity } from './parity/loader.js';
54
+ import { parseToolsets, filterTools, toolsetBlockedMessage } from './toolsets.js';
54
55
  import { resolveMessagingApi } from './messaging-base.js';
55
56
  import { buildResolvePath, buildTimelinePath, buildOverrideBody, buildValidateBody, buildBannerPath, buildOverrideListPath, tolerant, VALIDATE_PATH, OVERRIDE_PATH } from './workflow-schedule.js';
56
57
  import { applyEmailSubmissionsTo } from './survey-email.js';
@@ -2916,11 +2917,11 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
2916
2917
  },
2917
2918
  {
2918
2919
  name: 'enterprise_reports',
2919
- description: 'Enterprise Reports package (enterprise-internal, default OFF; every report returns 403 when the site does not hold that package item). report: program_breakdown (compare websites, teams, platforms, devices or entry pages: volume, missed, transfers, wait, first reply, QA score and coverage, sentiment), agent_scorecard (per agent by name: resolution, transfers, handle time, AI score, supervisor-reviewed score, sentiment impact), qa_coverage (share of resolved chats AI-scored and supervisor-reviewed by week and program), coaching_queue (low-scoring chats nobody reviewed, per agent), sentiment_breakdown (by website, team, agent or topic with change vs prior period), topic_radar (topics by volume, growth, transfer rate), weekly_brief (preview of the Monday brief sections), weekly_brief_send_test (emails this week\'s brief to the signed-in user), year_in_review (builds the 12-month Year in review document in the background: from/to yyyy-MM-dd inclusive, default the last 12 whole Pacific months, returns a build id; call again with buildId to get status and the download link). Scoped to the caller site.',
2920
+ description: 'Enterprise Reports package (default OFF; 403 when the site lacks the package item). Pick `report` from the enum: program_breakdown, agent_scorecard, qa_coverage, coaching_queue, sentiment_breakdown, topic_radar, weekly_brief, weekly_brief_send_test (emails the brief to the signed-in user), year_in_review (background 12-month build: from/to yyyy-MM-dd, returns a build id; call again with buildId for status and download link), plus the other enum values. Scoped to the caller site.',
2920
2921
  inputSchema: {
2921
2922
  type: 'object',
2922
2923
  properties: {
2923
- report: { type: 'string', enum: ['program_breakdown', 'agent_scorecard', 'qa_coverage', 'coaching_queue', 'sentiment_breakdown', 'topic_radar', 'weekly_brief', 'weekly_brief_send_test', 'repeat_contact', 'demand_coverage', 'bot_containment', 'effort_index', 'promise_ledger', 'promise_dismiss', 'new_agent_ramp', 'year_in_review', 'bonus_insights', 'operations_briefing', 'entitled'] },
2924
+ report: { type: 'string', enum: ['program_breakdown', 'agent_scorecard', 'qa_coverage', 'coaching_queue', 'sentiment_breakdown', 'topic_radar', 'weekly_brief', 'weekly_brief_send_test', 'repeat_contact', 'demand_coverage', 'bot_containment', 'effort_index', 'promise_ledger', 'promise_dismiss', 'new_agent_ramp', 'year_in_review', 'bonus_insights', 'operations_briefing', 'entitled', 'speed_to_answer'] },
2924
2925
  from: { type: 'string', description: 'yyyy-MM-dd start (default: 30 days ago).' },
2925
2926
  to: { type: 'string', description: 'yyyy-MM-dd end, inclusive (default: today).' },
2926
2927
  groupBy: { type: 'string', description: 'program_breakdown: website|team|platform|device|entrypage. sentiment_breakdown: website|team|agent|theme.' },
@@ -2944,6 +2945,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
2944
2945
  deflectionPct: { type: 'number', description: 'bonus_insights: assumed deflection percent (0-100).' },
2945
2946
  costPerChat: { type: 'number', description: 'bonus_insights: assumed cost per chat (0-1000).' },
2946
2947
  waitMinutes: { type: 'number', description: 'bonus_insights: wait minutes that counts as abandoned (1-1440).' },
2948
+ thresholdSeconds: { type: 'number', description: 'speed_to_answer: seconds that count as answered on target (5-600, default 20).' },
2947
2949
  promiseId: { type: 'string', description: 'promise_dismiss: the promise id to dismiss (managers only).' },
2948
2950
  buildId: { type: 'string', description: 'year_in_review: the build id returned by a start call; when given, returns that build\'s status (queued|building|completed|failed) and download link instead of starting a new build.' },
2949
2951
  },
@@ -2952,7 +2954,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
2952
2954
  },
2953
2955
  {
2954
2956
  name: 'report_backfill',
2955
- description: 'Backfill report data for the caller site. Preview by default (reports "would fill N", writes nothing); apply=true writes. Idempotent. type "csat" fills missing survey ratings (SurveySubmission.Rating) from existing data; it does NOT touch ticket CSAT. type "csat-demo" adds tagged demo CSAT assigned to the demo agents (allow-listed demo sites only); type "csat-demo-undo" over the same from/to deletes exactly those tagged rows and nothing else. type "history-classification-sample" tags 20 recent conversations and reports the line-of-business and intent mix it found (the proposed tags); type "history-classification" then tags and sentiment-scores past resolved conversations in the range (up to 100 per run, run again to continue) so Enterprise Reports and Year in Review show classified history instead of Unclassified / Insufficient data. For both history types, apply=true is QUEUED (the server returns 202 with a runId and runs it in the background; one run per site at a time, a repeat call returns the active run); pass status=true to read the latest run (queued, running, completed with result, or failed). Site managers only; scoped to the caller site.',
2957
+ description: 'Backfill report data for the caller site. Preview by default (writes nothing); apply=true writes. Idempotent. type: csat (fills missing survey ratings, not ticket CSAT), csat-demo / csat-demo-undo (tagged demo CSAT, allow-listed demo sites only), history-classification-sample (tags 20 recent conversations, reports the mix), history-classification (tags and sentiment-scores past resolved conversations, up to 100 per run; apply=true is queued, returns 202 with runId, one run per site; status=true reads the latest run). Site managers only.',
2956
2958
  inputSchema: {
2957
2959
  type: 'object',
2958
2960
  properties: {
@@ -7613,6 +7615,7 @@ reply: ${r?.reply}`;
7613
7615
  repeat_contact: 'repeat-contact', demand_coverage: 'demand-coverage', bot_containment: 'bot-containment',
7614
7616
  effort_index: 'effort-index', promise_ledger: 'promise-ledger', new_agent_ramp: 'new-agent-ramp',
7615
7617
  bonus_insights: 'bonus', operations_briefing: 'operations-briefing', entitled: 'entitled',
7618
+ speed_to_answer: 'speed-to-answer',
7616
7619
  };
7617
7620
  if (args.report === 'promise_dismiss') {
7618
7621
  if (!args.promiseId) throw new Error('promiseId is required for promise_dismiss');
@@ -7653,7 +7656,7 @@ reply: ${r?.reply}`;
7653
7656
  }
7654
7657
  if (args.report === 'weekly_brief_send_test') return JSON.stringify(await messagingPost('/api/enterprise-reports/' + seg, {}), null, 2);
7655
7658
  const qs = new URLSearchParams();
7656
- for (const k of ['from', 'to', 'groupBy', 'deploymentId', 'teamId', 'threshold', 'perAgent', 'limit', 'days', 'windowDays', 'weeks', 'handleMinutes', 'maxConcurrent', 'timeZone', 'lowScore', 'includeDemo', 'narrative', 'minutesPerReview', 'hourlyCost', 'deflectionPct', 'costPerChat', 'waitMinutes']) {
7659
+ for (const k of ['from', 'to', 'groupBy', 'deploymentId', 'teamId', 'threshold', 'perAgent', 'limit', 'days', 'windowDays', 'weeks', 'handleMinutes', 'maxConcurrent', 'timeZone', 'lowScore', 'includeDemo', 'narrative', 'minutesPerReview', 'hourlyCost', 'deflectionPct', 'costPerChat', 'waitMinutes', 'thresholdSeconds']) {
7657
7660
  if (args[k] != null && args[k] !== '') qs.set(k, String(args[k]));
7658
7661
  }
7659
7662
  const q = qs.toString();
@@ -9348,7 +9351,9 @@ const server = new Server(
9348
9351
 
9349
9352
  const PARITY = await loadParity('customer');
9350
9353
  TOOLS.push(...PARITY.tools);
9351
- server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS.map(withAnnotations) }));
9354
+ const TOOLSETS = parseToolsets(process.env.VELARO_MCP_TOOLSETS, (m) => process.stderr.write(`[velaro-mcp] ${m}
9355
+ `));
9356
+ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS.map(withAnnotations).filter((t) => !TOOLSETS || filterTools([t], TOOLSETS).length) }));
9352
9357
 
9353
9358
  server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: PROMPTS }));
9354
9359
 
@@ -9364,6 +9369,9 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
9364
9369
 
9365
9370
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
9366
9371
  const { name, arguments: args } = request.params;
9372
+ if (TOOLSETS && !filterTools([{ name }], TOOLSETS).length) {
9373
+ return { content: [{ type: 'text', text: `Error: ${toolsetBlockedMessage(name, TOOLSETS)}` }], isError: true };
9374
+ }
9367
9375
  try {
9368
9376
  const parityResult = await runParity(PARITY, name, args ?? {}, { api, messagingGet, messagingPost, messagingPut, messagingDel, messagingPatch });
9369
9377
  const result = parityResult !== undefined ? parityResult : await handleTool(name, args ?? {});
package/toolsets.js ADDED
@@ -0,0 +1,79 @@
1
+ // Toolset filter shared by the customer MCP server (server.js) and the staff MCP server (staff-server.js).
2
+ //
3
+ // Why: the customer server exposes ~630 tools and the staff server ~380. Even with Claude Code tool search
4
+ // (names only at start), the name list and server instructions are resent every turn, and a client without
5
+ // tool search loads every schema (~400 KB of JSON). VELARO_MCP_TOOLSETS lets a user load only the feature
6
+ // groups they use.
7
+ //
8
+ // Default (env unset, empty, or "all") = every tool, exactly as before, so existing keys and configs never break.
9
+ // Example: VELARO_MCP_TOOLSETS=core,kb,conversations
10
+ // A tool outside the selected toolsets is not listed and a direct call returns a clear error naming the toolset.
11
+
12
+ // Group by the tool-name prefix (text before the first underscore, or the full-name match for exact entries).
13
+ const GROUPS = {
14
+ core: [
15
+ 'velaro', 'logs', 'site', 'support', 'integration', 'entitlement', 'entitlements', 'admin', 'check', 'hangfire',
16
+ 'signalr', 'platform', 'usage', 'audit', 'activity', 'capability', 'staff', 'bot', 'agent', 'team', 'notifications',
17
+ 'provision', 'oauth', 'billing_plan_status', 'tour', 'triage', 'v10',
18
+ ],
19
+ kb: ['kb', 'knowledge', 'index', 'ingest', 'uploaded', 'scraper', 'backfill'],
20
+ conversations: [
21
+ 'conversation', 'contact', 'contacts', 'contactlist', 'contactsegment', 'outbound', 'canned', 'visitor', 'case',
22
+ 'ticket', 'deal', 'appointments', 'booking', 'callback', 'call', 'callpresence', 'sms', 'whatsapp',
23
+ ],
24
+ workflows: [
25
+ 'workflow', 'automation', 'routing', 'ivr', 'focus', 'widget', 'inline', 'page', 'avatar', 'survey', 'copilot',
26
+ 'ai', 'safety', 'skill', 'quality', 'qa', 'sentiment', 'friction', 'rule', 'deployment', 'business', 'actions',
27
+ ],
28
+ reports: [
29
+ 'report', 'enterprise', 'chat', 'keyword', 'kpi', 'experience', 'conversion', 'executive', 'csat', 'service',
30
+ 'campaign', 'email', 'sender', 'conversation_efficiency',
31
+ ],
32
+ billing: ['billing', 'bundle', 'pricing', 'package', 'payment', 'signature', 'compliance', 'coupon', 'feature', 'force'],
33
+ integrations: [
34
+ 'jobboard', 'teams', 'netsuite', 'magento', 'woocommerce', 'shopify', 'bigcommerce', 'apple', 'monday', 'dynamics',
35
+ 'zoom', 'notion', 'klaviyo', 'outlook', 'slack', 'webflow', 'squarespace', 'callrail', 'recruiting', 'product',
36
+ 'commerce', 'pickup', 'ms', 'linked', 'part', 'acuity', 'calendly', 'telephony', 'livefluence', 'sitesync',
37
+ 'code', 'mobile', 'copilot_studio', 'sse', 'missed', 'page_widget',
38
+ ],
39
+ };
40
+ const GROUP_NAMES = [...Object.keys(GROUPS), 'misc'];
41
+
42
+ // Longest-match lookup: "billing_plan_status" (core) beats the "billing" prefix (billing group).
43
+ const LOOKUP = new Map();
44
+ for (const [group, keys] of Object.entries(GROUPS)) for (const k of keys) LOOKUP.set(k, group);
45
+
46
+ export function toolsetFor(toolName) {
47
+ const parts = String(toolName).split('_');
48
+ for (let n = parts.length; n >= 1; n--) {
49
+ const g = LOOKUP.get(parts.slice(0, n).join('_'));
50
+ if (g) return g;
51
+ }
52
+ return 'misc';
53
+ }
54
+
55
+ // Returns null for "everything" or a Set of selected toolset names. Unknown names are reported via onWarn.
56
+ export function parseToolsets(raw, onWarn = () => {}) {
57
+ const value = (raw ?? '').trim().toLowerCase();
58
+ if (value === '' || value === 'all') return null;
59
+ const wanted = value.split(',').map((s) => s.trim()).filter(Boolean);
60
+ if (wanted.includes('all')) return null;
61
+ const valid = new Set();
62
+ for (const w of wanted) {
63
+ if (GROUP_NAMES.includes(w)) valid.add(w);
64
+ else onWarn(`unknown toolset "${w}" ignored (valid: ${GROUP_NAMES.join(', ')}, all)`);
65
+ }
66
+ // A typo-only value must not silently hide every tool: fall back to everything.
67
+ if (valid.size === 0) { onWarn('no valid toolsets in VELARO_MCP_TOOLSETS; loading all tools'); return null; }
68
+ return valid;
69
+ }
70
+
71
+ export function filterTools(tools, selected) {
72
+ return selected ? tools.filter((t) => selected.has(toolsetFor(t.name))) : tools;
73
+ }
74
+
75
+ export function toolsetBlockedMessage(toolName, selected) {
76
+ return `Tool "${toolName}" is in toolset "${toolsetFor(toolName)}", which is not enabled (VELARO_MCP_TOOLSETS=${[...selected].join(',')}). Add it to VELARO_MCP_TOOLSETS or set it to "all".`;
77
+ }
78
+
79
+ export { GROUP_NAMES };