@velaro/mcp-server 2.0.56 → 2.0.58
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 +5 -0
- package/package.json +2 -1
- package/parity/teams-phone-queues.customer.js +49 -0
- package/server.js +13 -5
- package/toolsets.js +79 -0
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.
|
|
3
|
+
"version": "2.0.58",
|
|
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 (
|
|
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 (
|
|
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
|
-
|
|
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 };
|