@velaro/mcp-server 2.0.55 → 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 +5 -0
- package/package.json +2 -1
- package/parity/teams-phone-queues.customer.js +49 -0
- package/server.js +21 -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.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';
|
|
@@ -1607,6 +1608,11 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
|
|
|
1607
1608
|
description: 'Reset a team to the Dynamics default (removes its override).',
|
|
1608
1609
|
inputSchema: { type: 'object', properties: { configId: { type: 'number' }, teamId: { type: 'number' } }, required: ['configId', 'teamId'] },
|
|
1609
1610
|
},
|
|
1611
|
+
{
|
|
1612
|
+
name: 'dynamics_copy_mappings',
|
|
1613
|
+
description: 'Copy field mappings and activity type from one Dynamics connection (sourceConfigId) to another (configId) on the same site, e.g. a QA org to a prod org. Never copies credentials, tenant or org URL. Set includeTeamOverrides to also replace the target\'s per-group overrides with the source\'s. Returns copiedMappings, copiedOverrides, previous (the replaced values, for undo) and unknownFields/unknownFieldsChecked.',
|
|
1614
|
+
inputSchema: { type: 'object', properties: { configId: { type: 'number', description: 'Target Dynamics config id' }, sourceConfigId: { type: 'number', description: 'Source Dynamics config id' }, includeTeamOverrides: { type: 'boolean' } }, required: ['configId', 'sourceConfigId'] },
|
|
1615
|
+
},
|
|
1610
1616
|
|
|
1611
1617
|
// ── Teams ─────────────────────────────────────────────────────────────────
|
|
1612
1618
|
{
|
|
@@ -2911,11 +2917,11 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
|
|
|
2911
2917
|
},
|
|
2912
2918
|
{
|
|
2913
2919
|
name: 'enterprise_reports',
|
|
2914
|
-
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.',
|
|
2915
2921
|
inputSchema: {
|
|
2916
2922
|
type: 'object',
|
|
2917
2923
|
properties: {
|
|
2918
|
-
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'] },
|
|
2919
2925
|
from: { type: 'string', description: 'yyyy-MM-dd start (default: 30 days ago).' },
|
|
2920
2926
|
to: { type: 'string', description: 'yyyy-MM-dd end, inclusive (default: today).' },
|
|
2921
2927
|
groupBy: { type: 'string', description: 'program_breakdown: website|team|platform|device|entrypage. sentiment_breakdown: website|team|agent|theme.' },
|
|
@@ -2939,6 +2945,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
|
|
|
2939
2945
|
deflectionPct: { type: 'number', description: 'bonus_insights: assumed deflection percent (0-100).' },
|
|
2940
2946
|
costPerChat: { type: 'number', description: 'bonus_insights: assumed cost per chat (0-1000).' },
|
|
2941
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).' },
|
|
2942
2949
|
promiseId: { type: 'string', description: 'promise_dismiss: the promise id to dismiss (managers only).' },
|
|
2943
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.' },
|
|
2944
2951
|
},
|
|
@@ -2947,7 +2954,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
|
|
|
2947
2954
|
},
|
|
2948
2955
|
{
|
|
2949
2956
|
name: 'report_backfill',
|
|
2950
|
-
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.',
|
|
2951
2958
|
inputSchema: {
|
|
2952
2959
|
type: 'object',
|
|
2953
2960
|
properties: {
|
|
@@ -6097,6 +6104,9 @@ reply: ${r?.reply}`;
|
|
|
6097
6104
|
return await api('PUT', `/Dynamics/Configs/${Number(args.configId)}/team-overrides/${Number(args.teamId)}`, body);
|
|
6098
6105
|
}
|
|
6099
6106
|
|
|
6107
|
+
case 'dynamics_copy_mappings':
|
|
6108
|
+
return await api('POST', `/Dynamics/Configs/${Number(args.configId)}/copy-mappings-from/${Number(args.sourceConfigId)}`, { includeTeamOverrides: args.includeTeamOverrides === true });
|
|
6109
|
+
|
|
6100
6110
|
case 'dynamics_team_overrides_reset':
|
|
6101
6111
|
return await api('DELETE', `/Dynamics/Configs/${Number(args.configId)}/team-overrides/${Number(args.teamId)}`);
|
|
6102
6112
|
|
|
@@ -7605,6 +7615,7 @@ reply: ${r?.reply}`;
|
|
|
7605
7615
|
repeat_contact: 'repeat-contact', demand_coverage: 'demand-coverage', bot_containment: 'bot-containment',
|
|
7606
7616
|
effort_index: 'effort-index', promise_ledger: 'promise-ledger', new_agent_ramp: 'new-agent-ramp',
|
|
7607
7617
|
bonus_insights: 'bonus', operations_briefing: 'operations-briefing', entitled: 'entitled',
|
|
7618
|
+
speed_to_answer: 'speed-to-answer',
|
|
7608
7619
|
};
|
|
7609
7620
|
if (args.report === 'promise_dismiss') {
|
|
7610
7621
|
if (!args.promiseId) throw new Error('promiseId is required for promise_dismiss');
|
|
@@ -7645,7 +7656,7 @@ reply: ${r?.reply}`;
|
|
|
7645
7656
|
}
|
|
7646
7657
|
if (args.report === 'weekly_brief_send_test') return JSON.stringify(await messagingPost('/api/enterprise-reports/' + seg, {}), null, 2);
|
|
7647
7658
|
const qs = new URLSearchParams();
|
|
7648
|
-
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']) {
|
|
7649
7660
|
if (args[k] != null && args[k] !== '') qs.set(k, String(args[k]));
|
|
7650
7661
|
}
|
|
7651
7662
|
const q = qs.toString();
|
|
@@ -9340,7 +9351,9 @@ const server = new Server(
|
|
|
9340
9351
|
|
|
9341
9352
|
const PARITY = await loadParity('customer');
|
|
9342
9353
|
TOOLS.push(...PARITY.tools);
|
|
9343
|
-
|
|
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) }));
|
|
9344
9357
|
|
|
9345
9358
|
server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: PROMPTS }));
|
|
9346
9359
|
|
|
@@ -9356,6 +9369,9 @@ server.setRequestHandler(GetPromptRequestSchema, async (request) => {
|
|
|
9356
9369
|
|
|
9357
9370
|
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
|
9358
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
|
+
}
|
|
9359
9375
|
try {
|
|
9360
9376
|
const parityResult = await runParity(PARITY, name, args ?? {}, { api, messagingGet, messagingPost, messagingPut, messagingDel, messagingPatch });
|
|
9361
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 };
|