@velaro/mcp-server 2.0.116 → 2.0.117
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.
|
|
3
|
+
"version": "2.0.117",
|
|
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,156 @@
|
|
|
1
|
+
// MCP parity for `velaro crm-order`, `velaro crm-fulfillment` and `velaro crm-return` (cli/lib/commands/crm-orders-returns.js).
|
|
2
|
+
// Backend: velaro-messaging CrmOrdersController, CrmFulfillmentsController and CrmReturnsController
|
|
3
|
+
// (docs/architecture/crm-orders-rma.md). The site always comes from the credential, never an argument. Needs the CRM Studio
|
|
4
|
+
// package (see your plan). Every create and refund takes an idempotencyKey: the same key again returns what the first call made.
|
|
5
|
+
|
|
6
|
+
const data = (r) => (r && typeof r === 'object' && 'data' in r ? r.data : r);
|
|
7
|
+
const q = (o) => {
|
|
8
|
+
const p = Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => `${k}=${encodeURIComponent(v)}`);
|
|
9
|
+
return p.length ? `?${p.join('&')}` : '';
|
|
10
|
+
};
|
|
11
|
+
const id = (v) => encodeURIComponent(v);
|
|
12
|
+
const num = { type: 'number' };
|
|
13
|
+
const str = { type: 'string' };
|
|
14
|
+
const ORDER_STATUSES = ['open', 'partially_fulfilled', 'fulfilled', 'cancelled'];
|
|
15
|
+
const RETURN_STATUSES = ['requested', 'approved', 'received', 'refunded', 'closed', 'denied'];
|
|
16
|
+
const REASONS = ['defective', 'wrong_item', 'damaged', 'not_as_described', 'no_longer_needed', 'other'];
|
|
17
|
+
const METHODS = ['original_payment', 'store_credit', 'adjustment_credit'];
|
|
18
|
+
const lineRef = { type: 'object', properties: { orderLineId: num, quantity: num }, required: ['orderLineId', 'quantity'] };
|
|
19
|
+
|
|
20
|
+
export const tools = [
|
|
21
|
+
{
|
|
22
|
+
name: 'crm_order_list',
|
|
23
|
+
description: 'List CRM orders, newest first, a page at a time. Filter by status, contact, company, deal or part of the order number. Part of the CRM Studio package (see your plan).',
|
|
24
|
+
inputSchema: { type: 'object', properties: { status: { type: 'string', enum: ORDER_STATUSES }, contactId: num, companyId: num, dealId: num, search: str, page: num, pageSize: num } },
|
|
25
|
+
},
|
|
26
|
+
{
|
|
27
|
+
name: 'crm_order_get',
|
|
28
|
+
description: 'Get one CRM order with its lines (ordered, shipped, returned), shipments with tracking, and returns.',
|
|
29
|
+
inputSchema: { type: 'object', properties: { id: num }, required: ['id'] },
|
|
30
|
+
},
|
|
31
|
+
{
|
|
32
|
+
name: 'crm_order_find',
|
|
33
|
+
description: 'Get a CRM order by its order number (for example ORD-1A2B3C4D).',
|
|
34
|
+
inputSchema: { type: 'object', properties: { orderNumber: str }, required: ['orderNumber'] },
|
|
35
|
+
},
|
|
36
|
+
{
|
|
37
|
+
name: 'crm_order_create',
|
|
38
|
+
description: 'Create a CRM order with lines, shipping and tax, optionally tied to a contact, company, deal or conversation. Idempotent per idempotencyKey. Mirrors to a connected store only through its existing business actions; with none connected it is kept in Velaro and says why.',
|
|
39
|
+
inputSchema: {
|
|
40
|
+
type: 'object',
|
|
41
|
+
properties: {
|
|
42
|
+
lines: { type: 'array', items: { type: 'object', properties: { sku: str, name: str, quantity: num, unitPrice: num, discount: num }, required: ['name', 'quantity', 'unitPrice'] } },
|
|
43
|
+
contactId: num, companyId: num, dealId: num, conversationId: num, orderNumber: str, currency: str, shippingAmount: num, taxAmount: num, notes: str,
|
|
44
|
+
externalSystem: str, externalId: str, idempotencyKey: str,
|
|
45
|
+
},
|
|
46
|
+
required: ['lines'],
|
|
47
|
+
},
|
|
48
|
+
},
|
|
49
|
+
{
|
|
50
|
+
name: 'crm_order_cancel',
|
|
51
|
+
description: 'Cancel a CRM order. Only an order that has not shipped and has no return can be cancelled.',
|
|
52
|
+
inputSchema: { type: 'object', properties: { id: num }, required: ['id'] },
|
|
53
|
+
},
|
|
54
|
+
{
|
|
55
|
+
name: 'crm_order_audit',
|
|
56
|
+
description: 'The history of a CRM order, its shipments and its returns: who did what and when, newest first.',
|
|
57
|
+
inputSchema: { type: 'object', properties: { id: num, page: num, pageSize: num }, required: ['id'] },
|
|
58
|
+
},
|
|
59
|
+
{
|
|
60
|
+
name: 'crm_fulfillment_list',
|
|
61
|
+
description: 'List the shipments of a CRM order with carrier, tracking number and the units in each.',
|
|
62
|
+
inputSchema: { type: 'object', properties: { orderId: num }, required: ['orderId'] },
|
|
63
|
+
},
|
|
64
|
+
{
|
|
65
|
+
name: 'crm_fulfillment_ship',
|
|
66
|
+
description: 'Ship some or all of a CRM order: carrier, tracking number and units per line, or shipAllRemaining. A line can never ship more than was ordered (400). Idempotent per idempotencyKey.',
|
|
67
|
+
inputSchema: {
|
|
68
|
+
type: 'object',
|
|
69
|
+
properties: { orderId: num, lines: { type: 'array', items: lineRef }, shipAllRemaining: { type: 'boolean' }, carrier: str, trackingNumber: str, trackingUrl: str, notes: str, idempotencyKey: str },
|
|
70
|
+
required: ['orderId'],
|
|
71
|
+
},
|
|
72
|
+
},
|
|
73
|
+
{
|
|
74
|
+
name: 'crm_fulfillment_delivered',
|
|
75
|
+
description: 'Mark a CRM shipment delivered.',
|
|
76
|
+
inputSchema: { type: 'object', properties: { id: num }, required: ['id'] },
|
|
77
|
+
},
|
|
78
|
+
{
|
|
79
|
+
name: 'crm_return_list',
|
|
80
|
+
description: 'List CRM return authorizations (RMA), newest first. Filter by order or status.',
|
|
81
|
+
inputSchema: { type: 'object', properties: { orderId: num, status: { type: 'string', enum: RETURN_STATUSES }, page: num, pageSize: num } },
|
|
82
|
+
},
|
|
83
|
+
{
|
|
84
|
+
name: 'crm_return_get',
|
|
85
|
+
description: 'Get one CRM return authorization with its lines, status and refund.',
|
|
86
|
+
inputSchema: { type: 'object', properties: { id: num }, required: ['id'] },
|
|
87
|
+
},
|
|
88
|
+
{
|
|
89
|
+
name: 'crm_return_find',
|
|
90
|
+
description: 'Get a CRM return authorization by its RMA number (for example RMA-1A2B3C4D).',
|
|
91
|
+
inputSchema: { type: 'object', properties: { rmaNumber: str }, required: ['rmaNumber'] },
|
|
92
|
+
},
|
|
93
|
+
{
|
|
94
|
+
name: 'crm_return_create',
|
|
95
|
+
description: 'Request a return (RMA) for shipped items of a CRM order. A line can return at most what shipped minus what other returns already hold (400). It moves no money. Idempotent per idempotencyKey.',
|
|
96
|
+
inputSchema: {
|
|
97
|
+
type: 'object',
|
|
98
|
+
properties: { orderId: num, lines: { type: 'array', items: lineRef }, reasonCode: { type: 'string', enum: REASONS }, reasonNote: str, idempotencyKey: str },
|
|
99
|
+
required: ['orderId', 'lines'],
|
|
100
|
+
},
|
|
101
|
+
},
|
|
102
|
+
{
|
|
103
|
+
name: 'crm_return_approve',
|
|
104
|
+
description: 'Approve a requested return. Manager or Administrator only.',
|
|
105
|
+
inputSchema: { type: 'object', properties: { id: num, comment: str }, required: ['id'] },
|
|
106
|
+
},
|
|
107
|
+
{
|
|
108
|
+
name: 'crm_return_deny',
|
|
109
|
+
description: 'Deny a requested return with a comment; its units go back to the order. Manager or Administrator only.',
|
|
110
|
+
inputSchema: { type: 'object', properties: { id: num, comment: str }, required: ['id', 'comment'] },
|
|
111
|
+
},
|
|
112
|
+
{
|
|
113
|
+
name: 'crm_return_receive',
|
|
114
|
+
description: 'Mark the items of an approved return received.',
|
|
115
|
+
inputSchema: { type: 'object', properties: { id: num }, required: ['id'] },
|
|
116
|
+
},
|
|
117
|
+
{
|
|
118
|
+
name: 'crm_return_close',
|
|
119
|
+
description: 'Close a return. Closing before the items arrived gives the held units back to the order. An illegal move is a 400 that names the legal next steps.',
|
|
120
|
+
inputSchema: { type: 'object', properties: { id: num, comment: str }, required: ['id'] },
|
|
121
|
+
},
|
|
122
|
+
{
|
|
123
|
+
name: 'crm_return_refund',
|
|
124
|
+
description: 'Refund a received return. It passes the approval rules (200 refunded, 202 waiting for a Manager) and the money policy (403 when it refuses); nothing is refunded twice for the same idempotencyKey. Amount defaults to the value of the returned items and can never be more.',
|
|
125
|
+
inputSchema: { type: 'object', properties: { id: num, amount: num, method: { type: 'string', enum: METHODS }, reason: str, idempotencyKey: str }, required: ['id'] },
|
|
126
|
+
},
|
|
127
|
+
];
|
|
128
|
+
|
|
129
|
+
export const handlers = {
|
|
130
|
+
crm_order_list: async (a, ctx) => data(await ctx.messagingGet(`/CrmOrders${q({ status: a.status, contactId: a.contactId, companyId: a.companyId, dealId: a.dealId, search: a.search, page: a.page, pageSize: a.pageSize })}`)),
|
|
131
|
+
crm_order_get: async (a, ctx) => data(await ctx.messagingGet(`/CrmOrders/${id(a.id)}`)),
|
|
132
|
+
crm_order_find: async (a, ctx) => data(await ctx.messagingGet(`/CrmOrders/by-number/${id(a.orderNumber)}`)),
|
|
133
|
+
crm_order_create: async (a, ctx) => data(await ctx.messagingPost('/CrmOrders', {
|
|
134
|
+
lines: a.lines, contactId: a.contactId, companyId: a.companyId, dealId: a.dealId, conversationId: a.conversationId, orderNumber: a.orderNumber, currency: a.currency,
|
|
135
|
+
shippingAmount: a.shippingAmount, taxAmount: a.taxAmount, notes: a.notes, externalSystem: a.externalSystem, externalId: a.externalId, idempotencyKey: a.idempotencyKey,
|
|
136
|
+
})),
|
|
137
|
+
crm_order_cancel: async (a, ctx) => data(await ctx.messagingPost(`/CrmOrders/${id(a.id)}/cancel`, {})),
|
|
138
|
+
crm_order_audit: async (a, ctx) => data(await ctx.messagingGet(`/CrmOrders/${id(a.id)}/audit${q({ page: a.page, pageSize: a.pageSize })}`)),
|
|
139
|
+
crm_fulfillment_list: async (a, ctx) => data(await ctx.messagingGet(`/CrmFulfillments?orderId=${id(a.orderId)}`)),
|
|
140
|
+
crm_fulfillment_ship: async (a, ctx) => data(await ctx.messagingPost('/CrmFulfillments', {
|
|
141
|
+
orderId: a.orderId, lines: a.lines, shipAllRemaining: a.shipAllRemaining === true, carrier: a.carrier, trackingNumber: a.trackingNumber, trackingUrl: a.trackingUrl,
|
|
142
|
+
notes: a.notes, idempotencyKey: a.idempotencyKey,
|
|
143
|
+
})),
|
|
144
|
+
crm_fulfillment_delivered: async (a, ctx) => data(await ctx.messagingPost(`/CrmFulfillments/${id(a.id)}/delivered`, {})),
|
|
145
|
+
crm_return_list: async (a, ctx) => data(await ctx.messagingGet(`/CrmReturns${q({ orderId: a.orderId, status: a.status, page: a.page, pageSize: a.pageSize })}`)),
|
|
146
|
+
crm_return_get: async (a, ctx) => data(await ctx.messagingGet(`/CrmReturns/${id(a.id)}`)),
|
|
147
|
+
crm_return_find: async (a, ctx) => data(await ctx.messagingGet(`/CrmReturns/by-number/${id(a.rmaNumber)}`)),
|
|
148
|
+
crm_return_create: async (a, ctx) => data(await ctx.messagingPost('/CrmReturns', {
|
|
149
|
+
orderId: a.orderId, lines: a.lines, reasonCode: a.reasonCode, reasonNote: a.reasonNote, idempotencyKey: a.idempotencyKey,
|
|
150
|
+
})),
|
|
151
|
+
crm_return_approve: async (a, ctx) => data(await ctx.messagingPost(`/CrmReturns/${id(a.id)}/approve`, { comment: a.comment })),
|
|
152
|
+
crm_return_deny: async (a, ctx) => data(await ctx.messagingPost(`/CrmReturns/${id(a.id)}/deny`, { comment: a.comment })),
|
|
153
|
+
crm_return_receive: async (a, ctx) => data(await ctx.messagingPost(`/CrmReturns/${id(a.id)}/receive`, {})),
|
|
154
|
+
crm_return_close: async (a, ctx) => data(await ctx.messagingPost(`/CrmReturns/${id(a.id)}/close`, { comment: a.comment })),
|
|
155
|
+
crm_return_refund: async (a, ctx) => data(await ctx.messagingPost(`/CrmReturns/${id(a.id)}/refund`, { amount: a.amount, method: a.method, reason: a.reason, idempotencyKey: a.idempotencyKey })),
|
|
156
|
+
};
|