@velaro/mcp-server 2.0.42 → 2.0.44

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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velaro/mcp-server",
3
- "version": "2.0.42",
3
+ "version": "2.0.44",
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": {
@@ -0,0 +1,132 @@
1
+ // MCP parity for `velaro enterprise-reports <report>` items 18-34 (cli/lib/commands/enterprise-reports.js). Hosted in velaro-admin
2
+ // (EnterpriseReportsController, route EnterpriseReports/<report>). The site ALWAYS comes from the credential, never from an argument.
3
+ // Server-side gate: each report returns 403 naming the Enterprise Reports package unless its EnableEnterpriseReports<Key> entitlement is on.
4
+ const qs = (o) => { const p = new URLSearchParams(); for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== '') p.set(k, String(v)); const s = p.toString(); return s ? '?' + s : ''; };
5
+
6
+ const PATHS = {
7
+ handoff_map: 'handoff-map',
8
+ routing_performance: 'routing-performance',
9
+ skill_fit: 'skill-fit',
10
+ contact_drivers_by_page: 'contact-drivers-by-page',
11
+ lead_funnel: 'lead-funnel',
12
+ revenue_at_risk: 'revenue-at-risk',
13
+ after_hours_gap: 'after-hours-gap',
14
+ ai_answer_grounding: 'ai-answer-grounding',
15
+ ai_skills_actions: 'ai-skills-actions',
16
+ refunds_discounts: 'refunds-discounts',
17
+ kb_effectiveness: 'kb-effectiveness',
18
+ missed_call_recovery_ivr_funnel: 'missed-call-recovery-ivr-funnel',
19
+ voice_intelligence: 'voice-intelligence',
20
+ outreach_results: 'outreach-results',
21
+ workload_balance: 'workload-balance',
22
+ benchmarks: 'benchmarks',
23
+ commerce_sales_loss: 'commerce-sales-loss',
24
+ };
25
+
26
+ export const tools = [
27
+ {
28
+ name: 'enterprise_report_handoff_map',
29
+ description: 'Handoff map (Enterprise Reports item 18, key EnableEnterpriseReportsHandoffMap). Who hands conversations to whom: bot to agent, agent to agent, team to team and queue handoffs, with who started each one, the reasons given, bounce-backs and how long the chains get. Hosted in velaro-admin (GET /EnterpriseReports/handoff-map); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
30
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
31
+ },
32
+ {
33
+ name: 'enterprise_report_routing_performance',
34
+ description: 'Routing performance (Enterprise Reports item 19, key EnableEnterpriseReportsRoutingPerformance). How often routing rules and workflows decide, miss, fall back or send a chat back again, with queue wait by rule, kept beyond the short routing log. Hosted in velaro-admin (GET /EnterpriseReports/routing-performance); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
35
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
36
+ },
37
+ {
38
+ name: 'enterprise_report_skill_fit',
39
+ description: 'Skill fit (Enterprise Reports item 20, key EnableEnterpriseReportsSkillFit). How well AI skills fit what people ask: calls, success, error classes and what happened to the chat afterward, by theme and by skill. Hosted in velaro-admin (GET /EnterpriseReports/skill-fit); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
40
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
41
+ },
42
+ {
43
+ name: 'enterprise_report_contact_drivers_by_page',
44
+ description: 'Contact drivers by page (Enterprise Reports item 21, key EnableEnterpriseReportsContactDriversByPage). Which pages visitors start a chat from and why: chats, themes, missed and transferred rates per page. Hosted in velaro-admin (GET /EnterpriseReports/contact-drivers-by-page); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
45
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
46
+ },
47
+ {
48
+ name: 'enterprise_report_lead_funnel',
49
+ description: 'Lead funnel (Enterprise Reports item 22, key EnableEnterpriseReportsLeadFunnel). Lead stages from captured to converted, with drop-off between stages and the time it took. Hosted in velaro-admin (GET /EnterpriseReports/lead-funnel); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
50
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
51
+ },
52
+ {
53
+ name: 'enterprise_report_revenue_at_risk',
54
+ description: 'Revenue at risk (Enterprise Reports item 23, key EnableEnterpriseReportsRevenueAtRisk). Order value tied to abandoned carts and to chats that ended missed, abandoned or unhappy, from the commerce platforms you have connected. Hosted in velaro-admin (GET /EnterpriseReports/revenue-at-risk); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
55
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}, "platform": {"type": "string", "description": "Narrow to one connected platform: shopify, bigcommerce, woocommerce, magento or square."}}},
56
+ },
57
+ {
58
+ name: 'enterprise_report_after_hours_gap',
59
+ description: 'After-hours gap (Enterprise Reports item 24, key EnableEnterpriseReportsAfterHoursGap). How many chats arrive when nobody is scheduled, how they end, and how long they wait for a human. Hosted in velaro-admin (GET /EnterpriseReports/after-hours-gap); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
60
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
61
+ },
62
+ {
63
+ name: 'enterprise_report_ai_answer_grounding',
64
+ description: 'AI answer grounding (Enterprise Reports item 25, key EnableEnterpriseReportsAiAnswerGrounding). What bot answers were based on: knowledge base, documents, scraped pages or skills, with confidence and how the chat ended. Hosted in velaro-admin (GET /EnterpriseReports/ai-answer-grounding); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
65
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
66
+ },
67
+ {
68
+ name: 'enterprise_report_ai_skills_actions',
69
+ description: 'AI skills and actions (Enterprise Reports item 26, key EnableEnterpriseReportsAiSkillsActions). What AI skills and actions did: calls, success, failures by error class, duration, and who triggered them. Hosted in velaro-admin (GET /EnterpriseReports/ai-skills-actions); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
70
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
71
+ },
72
+ {
73
+ name: 'enterprise_report_refunds_discounts',
74
+ description: 'Refunds and discounts (Enterprise Reports item 27, key EnableEnterpriseReportsRefundsDiscounts). Refunds, discounts, credits and coupons issued from chats, who issued them, and how they compare with your configured caps. Hosted in velaro-admin (GET /EnterpriseReports/refunds-discounts); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
75
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}, "platform": {"type": "string", "description": "Narrow to one connected platform: shopify, bigcommerce, woocommerce, magento or square."}}},
76
+ },
77
+ {
78
+ name: 'enterprise_report_kb_effectiveness',
79
+ description: 'Knowledge base effectiveness (Enterprise Reports item 28, key EnableEnterpriseReportsKbEffectiveness). Which help articles are viewed, used by the bot and rated helpful, and where heavily used articles are rated poorly. Hosted in velaro-admin (GET /EnterpriseReports/kb-effectiveness); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
80
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
81
+ },
82
+ {
83
+ name: 'enterprise_report_missed_call_recovery_ivr_funnel',
84
+ description: 'Missed-call recovery and IVR funnel (Enterprise Reports item 29, key EnableEnterpriseReportsMissedCallRecoveryIvrFunnel). How many missed calls were recovered and how fast, and where callers drop off in the IVR menus. Hosted in velaro-admin (GET /EnterpriseReports/missed-call-recovery-ivr-funnel); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
85
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
86
+ },
87
+ {
88
+ name: 'enterprise_report_voice_intelligence',
89
+ description: 'Voice intelligence (Enterprise Reports item 30, key EnableEnterpriseReportsVoiceIntelligence). Why people call and how it went: call reasons by theme, call sentiment, duration and outcomes. No talk-to-silence ratio is shown. Hosted in velaro-admin (GET /EnterpriseReports/voice-intelligence); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
90
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
91
+ },
92
+ {
93
+ name: 'enterprise_report_outreach_results',
94
+ description: 'Outreach results (Enterprise Reports item 31, key EnableEnterpriseReportsOutreachResults). How email and SMS outreach performed: delivery, failures, replies, opt-outs and the chats that followed. Hosted in velaro-admin (GET /EnterpriseReports/outreach-results); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
95
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
96
+ },
97
+ {
98
+ name: 'enterprise_report_workload_balance',
99
+ description: 'Workload balance (Enterprise Reports item 32, key EnableEnterpriseReportsWorkloadBalance). How evenly chats are spread across agents against the hours they were available, flagging over- and under-loaded agents. Hosted in velaro-admin (GET /EnterpriseReports/workload-balance); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
100
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
101
+ },
102
+ {
103
+ name: 'enterprise_report_benchmarks',
104
+ description: 'Benchmarks (Enterprise Reports item 33, key EnableEnterpriseReportsBenchmarks). How your theme mix compares with other companies in your industry vertical, shown only at vertical level when enough sites contribute. Hosted in velaro-admin (GET /EnterpriseReports/benchmarks); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
105
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}}},
106
+ },
107
+ {
108
+ name: 'enterprise_report_commerce_sales_loss',
109
+ description: 'Why am I losing sales (Enterprise Reports item 34, key EnableEnterpriseReportsCommerceSalesLoss). Which support themes (returns, shipping, delivery, out of stock, pricing, cancellations) touch the most revenue, refunds and repeat purchases, by connected platform. Hosted in velaro-admin (GET /EnterpriseReports/commerce-sales-loss); returns 403 naming the Enterprise Reports package when the site does not hold it. The site comes from the credential only.',
110
+ inputSchema: {"type": "object", "properties": {"from": {"type": "string", "description": "yyyy-MM-dd or ISO instant (default: 30 days ago). Pacific calendar days."}, "to": {"type": "string", "description": "yyyy-MM-dd inclusive or ISO instant exclusive (default: today)."}, "teamId": {"type": "integer", "description": "Narrow to one team."}, "platform": {"type": "string", "description": "Narrow to one connected platform: shopify, bigcommerce, woocommerce, magento or square."}}},
111
+ },
112
+ ];
113
+
114
+ export const handlers = {
115
+ enterprise_report_handoff_map: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.handoff_map + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
116
+ enterprise_report_routing_performance: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.routing_performance + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
117
+ enterprise_report_skill_fit: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.skill_fit + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
118
+ enterprise_report_contact_drivers_by_page: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.contact_drivers_by_page + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
119
+ enterprise_report_lead_funnel: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.lead_funnel + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
120
+ enterprise_report_revenue_at_risk: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.revenue_at_risk + qs({ from: a?.from, to: a?.to, teamId: a?.teamId, platform: a?.platform })),
121
+ enterprise_report_after_hours_gap: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.after_hours_gap + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
122
+ enterprise_report_ai_answer_grounding: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.ai_answer_grounding + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
123
+ enterprise_report_ai_skills_actions: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.ai_skills_actions + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
124
+ enterprise_report_refunds_discounts: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.refunds_discounts + qs({ from: a?.from, to: a?.to, teamId: a?.teamId, platform: a?.platform })),
125
+ enterprise_report_kb_effectiveness: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.kb_effectiveness + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
126
+ enterprise_report_missed_call_recovery_ivr_funnel: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.missed_call_recovery_ivr_funnel + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
127
+ enterprise_report_voice_intelligence: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.voice_intelligence + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
128
+ enterprise_report_outreach_results: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.outreach_results + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
129
+ enterprise_report_workload_balance: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.workload_balance + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
130
+ enterprise_report_benchmarks: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.benchmarks + qs({ from: a?.from, to: a?.to, teamId: a?.teamId })),
131
+ enterprise_report_commerce_sales_loss: async (a, ctx) => ctx.api('GET', '/EnterpriseReports/' + PATHS.commerce_sales_loss + qs({ from: a?.from, to: a?.to, teamId: a?.teamId, platform: a?.platform })),
132
+ };
package/server.js CHANGED
@@ -690,6 +690,11 @@ const TOOLS = [
690
690
  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.',
691
691
  inputSchema: { type: 'object', properties: {} },
692
692
  },
693
+ {
694
+ name: 'canned_learning_usage',
695
+ description: 'Canned message analyses used this month out of the amount included in the plan, and when the allowance resets. Each AI rewrite suggestion counts as one analysis; canned_learning_generate stops at the limit.',
696
+ inputSchema: { type: 'object', properties: {} },
697
+ },
693
698
  {
694
699
  name: 'canned_learning_record_edit',
695
700
  description: 'Record that an agent edited a canned response before sending. The sent text is PII-redacted and length-capped server-side; the site comes from the session. Rows are capped per site and expire after 90 days.',
@@ -5353,6 +5358,8 @@ async function handleTool(name, args) {
5353
5358
  return await messagingPost('/CannedLearning/generate', { teamId: args.teamId ?? null });
5354
5359
  case 'canned_learning_teams':
5355
5360
  return await messagingGet('/CannedLearning/teams');
5361
+ case 'canned_learning_usage':
5362
+ return await messagingGet('/CannedLearning/usage');
5356
5363
  case 'canned_learning_approve':
5357
5364
  return await messagingPost(`/CannedLearning/suggestions/${args.suggestionId}/approve`, { editedText: args.editedText ?? null });
5358
5365
  case 'canned_learning_reject':
@@ -48,12 +48,14 @@ const READ_ONLY_EXPLICIT = new Set([
48
48
  'focus_get_draft_pregeneration_report', 'teams_push_settings_get', 'call_center_team_breakdown',
49
49
  'call_center_channel_breakdown', 'outbound_activity_for_contact', 'integration_skill_logs',
50
50
  'magento_activity_logs', 'chat_intelligence_themes', 'chat_intelligence_recommendations',
51
- 'index_move_preview', 'index_split_preview', 'canned_learning_suggestions', 'canned_learning_teams',
51
+ 'index_move_preview', 'index_split_preview', 'canned_learning_suggestions', 'canned_learning_teams', 'canned_learning_usage',
52
52
  'canned_learning_edit_summary', 'chat_topics_group_suggestions', 'chat_topics_suggestions',
53
53
  'enterprise_reports', 'recruiting_ats_failures', 'jobboard_application_history',
54
54
  'recruiting_download_resume', 'routing_inactivity_transfers', 'compliance_attestation',
55
55
  'copilot_studio_ask', 'skill_routing_simulate', 'squarespace_test_connection', 'woocommerce_logs',
56
56
  'site_builder_connect_info',
57
+ // Enterprise Reports items 18-34 (admin-hosted, read-only GET)
58
+ 'enterprise_report_handoff_map', 'enterprise_report_routing_performance', 'enterprise_report_skill_fit', 'enterprise_report_contact_drivers_by_page', 'enterprise_report_lead_funnel', 'enterprise_report_revenue_at_risk', 'enterprise_report_after_hours_gap', 'enterprise_report_ai_answer_grounding', 'enterprise_report_ai_skills_actions', 'enterprise_report_refunds_discounts', 'enterprise_report_kb_effectiveness', 'enterprise_report_missed_call_recovery_ivr_funnel', 'enterprise_report_voice_intelligence', 'enterprise_report_outreach_results', 'enterprise_report_workload_balance', 'enterprise_report_benchmarks', 'enterprise_report_commerce_sales_loss',
57
59
  ]);
58
60
 
59
61
  // Write tools that are additive even though their name carries a destructive-looking token.