@velaro/mcp-server 0.1.0 → 0.6.8
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 +225 -16
- package/package.json +15 -4
- package/server.js +7739 -287
- package/server.json +37 -0
package/README.md
CHANGED
|
@@ -1,20 +1,35 @@
|
|
|
1
1
|
# @velaro/mcp-server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**The only customer support platform with a native, self-updating MCP server.**
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Connect Claude, Claude Code, Claude Desktop, or any MCP-compatible AI agent directly to your Velaro account — knowledge base, workflows, conversation data, and 596 AI skills across 20+ commerce and CRM platforms.
|
|
6
6
|
|
|
7
7
|
```bash
|
|
8
8
|
npx @velaro/mcp-server
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
-
Set your
|
|
12
|
-
|
|
11
|
+
Set your key and go:
|
|
13
12
|
```bash
|
|
14
13
|
VELARO_MCP_KEY=vel_live_... npx @velaro/mcp-server
|
|
15
14
|
```
|
|
16
15
|
|
|
17
|
-
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Why Velaro MCP Is Different
|
|
19
|
+
|
|
20
|
+
Most chat platforms require webhooks, custom API wrappers, or point-to-point integrations to give an AI agent access to customer data. Velaro ships a published npm package that turns Claude into a first-class operator of your entire support infrastructure — no wrapper code, no custom authentication layer, no waiting for an API integration to be built.
|
|
21
|
+
|
|
22
|
+
- **One command install** — `npx @velaro/mcp-server` pulls the latest version automatically
|
|
23
|
+
- **Hosted HTTP endpoint** — no Node.js required; point Claude Desktop at `https://velaro-admin-staging.azurewebsites.net/mcp` with a Bearer token
|
|
24
|
+
- **Auto-updates** — the package is republished on every production deploy; `npx` always runs the latest
|
|
25
|
+
- **596 AI skills** — Shopify, BigCommerce, WooCommerce, Magento, HubSpot, Salesforce, NetSuite, ServiceNow, Dynamics 365, SAP, Square, QuickBooks, Jobber, and more — all callable from within Claude
|
|
26
|
+
- **25 built-in tools** — conversations, workflows, bots, contacts, agents, teams, routing rules, conversion tracking, and full KB management
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Quick Start
|
|
31
|
+
|
|
32
|
+
### Claude Code
|
|
18
33
|
|
|
19
34
|
Add to `~/.claude/settings.json`:
|
|
20
35
|
|
|
@@ -32,9 +47,9 @@ Add to `~/.claude/settings.json`:
|
|
|
32
47
|
}
|
|
33
48
|
```
|
|
34
49
|
|
|
35
|
-
|
|
50
|
+
### Claude Desktop
|
|
36
51
|
|
|
37
|
-
Add to `~/.claude/claude_desktop_config.json
|
|
52
|
+
Add to `~/.config/claude/claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
|
|
38
53
|
|
|
39
54
|
```json
|
|
40
55
|
{
|
|
@@ -50,24 +65,218 @@ Add to `~/.claude/claude_desktop_config.json`:
|
|
|
50
65
|
}
|
|
51
66
|
```
|
|
52
67
|
|
|
68
|
+
### Hosted HTTP Endpoint (No Node Required)
|
|
69
|
+
|
|
70
|
+
If you prefer not to run a local Node process, point directly at Velaro's hosted MCP endpoint:
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{
|
|
74
|
+
"mcpServers": {
|
|
75
|
+
"velaro": {
|
|
76
|
+
"url": "https://api-admin-us-east.velaro.com/mcp",
|
|
77
|
+
"headers": {
|
|
78
|
+
"Authorization": "Bearer vel_live_..."
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
This works with any MCP client that supports HTTP/SSE transport — including Claude Desktop 0.8+.
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
53
89
|
## Available Tools
|
|
54
90
|
|
|
55
|
-
|
|
91
|
+
### Knowledge Base
|
|
92
|
+
| Tool | What It Does |
|
|
56
93
|
|------|-------------|
|
|
57
|
-
| `kb_list_topics` | List all
|
|
58
|
-
| `kb_search_articles` | Search articles by
|
|
59
|
-
| `kb_get_article` |
|
|
60
|
-
| `kb_create_article` | Create a new article |
|
|
61
|
-
| `kb_update_article` | Update
|
|
94
|
+
| `kb_list_topics` | List all knowledge base topics |
|
|
95
|
+
| `kb_search_articles` | Search articles by keyword, topic, or publish status |
|
|
96
|
+
| `kb_get_article` | Retrieve full article content by ID |
|
|
97
|
+
| `kb_create_article` | Create and optionally publish a new article |
|
|
98
|
+
| `kb_update_article` | Update title, body, tags, or publish status |
|
|
62
99
|
| `kb_delete_article` | Delete an article |
|
|
63
100
|
|
|
64
|
-
|
|
101
|
+
### Conversations
|
|
102
|
+
| Tool | What It Does |
|
|
103
|
+
|------|-------------|
|
|
104
|
+
| `conversation_list` | List recent conversations filtered by channel, status, or agent |
|
|
105
|
+
| `conversation_get` | Get full details for a single conversation |
|
|
106
|
+
| `conversation_search` | Search conversations by phone number or call SID |
|
|
107
|
+
|
|
108
|
+
### Workflows
|
|
109
|
+
| Tool | What It Does |
|
|
110
|
+
|------|-------------|
|
|
111
|
+
| `workflow_list` | List all workflows with enabled state and trigger type |
|
|
112
|
+
| `workflow_get` | Get full workflow details by ID |
|
|
113
|
+
| `workflow_toggle` | Enable or disable a workflow |
|
|
114
|
+
|
|
115
|
+
### Bots & AI Configurations
|
|
116
|
+
| Tool | What It Does |
|
|
117
|
+
|------|-------------|
|
|
118
|
+
| `bot_list` | List all bot/AI configurations for this site |
|
|
119
|
+
| `bot_get` | Get full bot config including system prompt |
|
|
120
|
+
| `bot_update_prompt` | Update a bot's system prompt |
|
|
121
|
+
|
|
122
|
+
### Contacts
|
|
123
|
+
| Tool | What It Does |
|
|
124
|
+
|------|-------------|
|
|
125
|
+
| `contact_search` | Search contacts by name, email, phone, or company |
|
|
126
|
+
| `contact_get` | Get full contact details by ID |
|
|
127
|
+
|
|
128
|
+
### Team & Routing
|
|
129
|
+
| Tool | What It Does |
|
|
130
|
+
|------|-------------|
|
|
131
|
+
| `agent_list` | List agents with availability status; filter by team |
|
|
132
|
+
| `team_list` | List all teams for this site |
|
|
133
|
+
| `routing_list` | List all routing rules ordered by priority |
|
|
134
|
+
| `routing_get` | Get routing rule details including rule and value JSON |
|
|
135
|
+
|
|
136
|
+
### Site
|
|
137
|
+
| Tool | What It Does |
|
|
138
|
+
|------|-------------|
|
|
139
|
+
| `site_info` | Get site settings, active channels, subscription features, and resource counts |
|
|
140
|
+
|
|
141
|
+
### Live Operations
|
|
142
|
+
| Tool | What It Does |
|
|
143
|
+
|------|-------------|
|
|
144
|
+
| `kpi_snapshot` | Real-time ops dashboard — agents online/available/busy, open/queued conversations, bot-active count, resolved today, queue wait times, top agents, channel breakdown, per-team coverage status |
|
|
145
|
+
|
|
146
|
+
### Bot Diagnostics
|
|
147
|
+
| Tool | What It Does |
|
|
148
|
+
|------|-------------|
|
|
149
|
+
| `bot_analytics_summary` | AI bot health — total skill calls, error count, success rate, top skill, training count |
|
|
150
|
+
| `bot_skill_usage` | Per-skill call counts by integration + error counts — identifies over/underused skills and failing integrations |
|
|
151
|
+
| `bot_recent_errors` | Last N AI skill errors with integration, message, and timestamp — for active troubleshooting |
|
|
152
|
+
|
|
153
|
+
### Service Level
|
|
154
|
+
| Tool | What It Does |
|
|
155
|
+
|------|-------------|
|
|
156
|
+
| `service_level_report` | SLA compliance per period — % within threshold, avg response time, avg handle time. Granularity: hour/day/week/month |
|
|
157
|
+
|
|
158
|
+
### Reporting & Analytics
|
|
159
|
+
| Tool | What It Does |
|
|
160
|
+
|------|-------------|
|
|
161
|
+
| `report_roi_summary` | Full ROI report — bot deflections, hours saved, cost savings, AI skill executions, resolution rate, response time, trends vs prior period, monthly breakdown, top skills by call count, channel breakdown |
|
|
162
|
+
| `report_agent_utilization` | Per-agent stats — conversation count, avg handle time, active/away breakdown for any date range |
|
|
163
|
+
| `report_campaign_performance` | Email campaign KPIs — open rate, click rate, delivery rate, complaint rate per campaign + aggregate totals |
|
|
164
|
+
| `report_campaign_deliverability` | Deliverability health check — bounce rate, complaint rate, unsubscribe rate, open rate with traffic-light status and fix recommendations |
|
|
165
|
+
| `report_campaign_monthly` | Month-by-month email volume for the last 12 months |
|
|
166
|
+
| `report_audience_growth` | Total active contacts, net contacts (minus unsubscribes), month-by-month additions |
|
|
167
|
+
|
|
168
|
+
### Conversion Tracking
|
|
169
|
+
| Tool | What It Does |
|
|
170
|
+
|------|-------------|
|
|
171
|
+
| `conversion_list_goals` | List all conversion goals |
|
|
172
|
+
| `conversion_create_goal` | Create a new conversion goal (URL, Shopify, Square, custom event) |
|
|
173
|
+
| `conversion_get_report` | Get conversion attribution report — revenue, rates, timeline |
|
|
174
|
+
|
|
175
|
+
More tools are added on every production release. Run `tools/list` to see the current full list from your Claude client.
|
|
176
|
+
|
|
177
|
+
---
|
|
178
|
+
|
|
179
|
+
## Getting Your API Key
|
|
180
|
+
|
|
181
|
+
1. Log in to your Velaro admin at [admin.velaro.com](https://admin.velaro.com)
|
|
182
|
+
2. Go to **Settings → API → MCP Keys**
|
|
183
|
+
3. Click **Create Key** → give it a label (e.g. "Claude Code")
|
|
184
|
+
4. Copy the `vel_live_...` key — it's shown once
|
|
185
|
+
|
|
186
|
+
Keys are site-isolated: the key is bound to your Velaro account and can only read/write data for that account. You can create multiple keys and revoke them independently.
|
|
65
187
|
|
|
66
|
-
|
|
67
|
-
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
## Auth Options
|
|
191
|
+
|
|
192
|
+
| Variable | When to Use |
|
|
193
|
+
|----------|-------------|
|
|
194
|
+
| `VELARO_MCP_KEY=vel_live_...` | Production — create in Settings > API > MCP Keys |
|
|
195
|
+
| `VELARO_JWT=<token>` | Development only — short-lived JWT from `velaro login` |
|
|
196
|
+
|
|
197
|
+
---
|
|
68
198
|
|
|
69
199
|
## Staging / Custom API
|
|
70
200
|
|
|
71
201
|
```bash
|
|
72
202
|
VELARO_ADMIN_API=https://velaro-admin-staging.azurewebsites.net VELARO_MCP_KEY=vel_live_... npx @velaro/mcp-server
|
|
73
203
|
```
|
|
204
|
+
|
|
205
|
+
---
|
|
206
|
+
|
|
207
|
+
## HTTP Mode (Self-Hosted)
|
|
208
|
+
|
|
209
|
+
Run as an HTTP/SSE server instead of stdio — useful for shared deployments:
|
|
210
|
+
|
|
211
|
+
```bash
|
|
212
|
+
VELARO_MCP_MODE=http PORT=3000 VELARO_MCP_KEY=vel_live_... node server.js
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Clients connect via `GET /mcp` (SSE stream) and `POST /mcp` (JSON-RPC 2.0).
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
219
|
+
## What You Can Do with Velaro + Claude
|
|
220
|
+
|
|
221
|
+
Once connected, Claude has direct operator access to your support infrastructure:
|
|
222
|
+
|
|
223
|
+
**Knowledge Base Management**
|
|
224
|
+
> "Search my KB for any articles about refund policy and update them to reflect the new 30-day window we announced last week."
|
|
225
|
+
|
|
226
|
+
**Workflow Diagnostics**
|
|
227
|
+
> "List all my disabled workflows and tell me which ones are AI-enhanced so I can decide which to turn back on."
|
|
228
|
+
|
|
229
|
+
**Bot Prompt Tuning**
|
|
230
|
+
> "Read the current system prompt for bot #3 and rewrite it to be more concise and focus on checkout support."
|
|
231
|
+
|
|
232
|
+
**Live Operations**
|
|
233
|
+
> "Show me the last 20 open conversations on the SMS channel and tell me which agents have the most active chats right now."
|
|
234
|
+
|
|
235
|
+
**Contact Lookup**
|
|
236
|
+
> "Search for the contact with email orders@example.com and show me their full profile."
|
|
237
|
+
|
|
238
|
+
**Routing Audit**
|
|
239
|
+
> "List all routing rules in priority order — I want to review what fires before the 'Default Team' fallback."
|
|
240
|
+
|
|
241
|
+
**Conversion Tracking**
|
|
242
|
+
> "Create a conversion goal that fires when a customer hits /order-confirmed, with a 24-hour attribution window and $50 default value."
|
|
243
|
+
|
|
244
|
+
**ROI & Analytics**
|
|
245
|
+
> "Pull the last 30-day ROI report. How many conversations did the bot deflect, how many hours did that save, and which AI skills were called the most?"
|
|
246
|
+
|
|
247
|
+
**Deliverability Monitoring**
|
|
248
|
+
> "Check our email deliverability health — is our bounce rate or complaint rate in the red? What should we fix?"
|
|
249
|
+
|
|
250
|
+
**Site Health Check**
|
|
251
|
+
> "Give me a full site overview — active channels, agent count, workflow status, and which subscription features are enabled."
|
|
252
|
+
|
|
253
|
+
Claude handles these operations natively. No exports, no copy-paste, no waiting for a developer.
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## How It's Updated
|
|
258
|
+
|
|
259
|
+
This package is automatically published to npm on every Velaro production deploy. When Velaro ships new tools or improves existing ones, your next `npx` invocation pulls the latest version automatically. You don't need to update a package.json or run `npm install`.
|
|
260
|
+
|
|
261
|
+
If you want a pinned version for reproducible environments:
|
|
262
|
+
```bash
|
|
263
|
+
npx @velaro/mcp-server@0.1.0
|
|
264
|
+
```
|
|
265
|
+
|
|
266
|
+
---
|
|
267
|
+
|
|
268
|
+
## Competitive Context
|
|
269
|
+
|
|
270
|
+
Intercom, Zendesk, and Freshdesk do not publish MCP servers. Connecting Claude to those platforms requires building a custom MCP wrapper against their REST APIs, handling authentication yourself, and maintaining the integration as their APIs change.
|
|
271
|
+
|
|
272
|
+
Velaro ships the MCP server, hosts it, auto-updates it, and publishes it to npm. The integration is one `npx` command.
|
|
273
|
+
|
|
274
|
+
---
|
|
275
|
+
|
|
276
|
+
## Links
|
|
277
|
+
|
|
278
|
+
- [Velaro Admin](https://admin.velaro.com)
|
|
279
|
+
- [Documentation](https://help.velaro.com)
|
|
280
|
+
- [npm package](https://www.npmjs.com/package/@velaro/mcp-server)
|
|
281
|
+
- [Source](https://github.com/velaro/velaro-admin/tree/master/mcp)
|
|
282
|
+
- [MCP Specification](https://modelcontextprotocol.io)
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@velaro/mcp-server",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"description": "Velaro MCP server — connect Claude and other AI agents directly to your Velaro KB and
|
|
3
|
+
"version": "0.6.8",
|
|
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": {
|
|
7
7
|
"velaro-mcp": "server.js"
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
"node": ">=18.0.0"
|
|
11
11
|
},
|
|
12
12
|
"dependencies": {
|
|
13
|
-
"@modelcontextprotocol/sdk": "^1.
|
|
13
|
+
"@modelcontextprotocol/sdk": "^1.30.0"
|
|
14
14
|
},
|
|
15
15
|
"scripts": {
|
|
16
16
|
"start": "node server.js"
|
|
@@ -23,10 +23,21 @@
|
|
|
23
23
|
"type": "git",
|
|
24
24
|
"url": "https://github.com/velaro/velaro-admin"
|
|
25
25
|
},
|
|
26
|
-
"keywords": [
|
|
26
|
+
"keywords": [
|
|
27
|
+
"velaro",
|
|
28
|
+
"mcp",
|
|
29
|
+
"knowledge-base",
|
|
30
|
+
"claude",
|
|
31
|
+
"ai",
|
|
32
|
+
"model-context-protocol",
|
|
33
|
+
"customer-support",
|
|
34
|
+
"workflows",
|
|
35
|
+
"conversations"
|
|
36
|
+
],
|
|
27
37
|
"license": "MIT",
|
|
28
38
|
"files": [
|
|
29
39
|
"server.js",
|
|
40
|
+
"server.json",
|
|
30
41
|
"README.md"
|
|
31
42
|
]
|
|
32
43
|
}
|