@velaro/mcp-server 2.0.60 → 2.0.61

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.60",
3
+ "version": "2.0.61",
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,150 @@
1
+ // MCP parity for `velaro crm` (cli/lib/commands/crm-studio.js). Backend: velaro-messaging CrmCustomFieldsController and
2
+ // CrmFormLayoutsController (docs/architecture/crm-studio-program.md). Site from the credential, never an argument.
3
+
4
+ const ENTITIES = ['deal', 'contact', 'company', 'ticket'];
5
+ const FIELD_TYPES = [
6
+ 'Text', 'Number', 'Date', 'Dropdown', 'Checkbox', 'Currency',
7
+ 'MultiSelect', 'LongText', 'Url', 'Email', 'Phone', 'Percent', 'DateTime', 'Lookup',
8
+ ];
9
+
10
+ const data = (r) => (r && typeof r === 'object' && 'data' in r ? r.data : r);
11
+ const q = (o) => {
12
+ const p = Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => `${k}=${encodeURIComponent(v)}`);
13
+ return p.length ? `?${p.join('&')}` : '';
14
+ };
15
+
16
+ export const tools = [
17
+ {
18
+ name: 'crm_field_list',
19
+ description: 'List the CRM custom field definitions for one record type (deal, contact, company or ticket): id, label, type, options, required, help text, default value, validation, and the roles that can read or change it.',
20
+ inputSchema: { type: 'object', properties: { entity: { type: 'string', enum: ENTITIES }, pipelineId: { type: 'number' } }, required: ['entity'] },
21
+ },
22
+ {
23
+ name: 'crm_field_define',
24
+ description: 'Create or update a CRM custom field. Administrator only. Pass id to update; on update send only the keys you want to change (an empty string, list or object clears that setting). label and fieldType are required when creating. The six basic types are on every plan; the extra types, validation and role security belong to the CRM Studio package (see your plan). Role lists are role names; empty means everyone.',
25
+ inputSchema: {
26
+ type: 'object',
27
+ properties: {
28
+ id: { type: 'number', description: 'Existing field id to update.' },
29
+ entity: { type: 'string', enum: ENTITIES },
30
+ label: { type: 'string' },
31
+ fieldType: { type: 'string', enum: FIELD_TYPES },
32
+ options: { type: 'array', items: { type: 'string' }, description: 'Choices for Dropdown and MultiSelect.' },
33
+ isRequired: { type: 'boolean' },
34
+ pipelineId: { type: 'number', description: 'Limit a deal field to one pipeline; omit for all.' },
35
+ sortOrder: { type: 'number' },
36
+ helpText: { type: 'string' },
37
+ defaultValue: { type: 'string' },
38
+ validation: { type: 'object', description: 'For example { "min": 0, "max": 100, "regex": "^[A-Z]{3}$" }.' },
39
+ readRoles: { type: 'array', items: { type: 'string' } },
40
+ writeRoles: { type: 'array', items: { type: 'string' } },
41
+ visibleWhen: { type: 'object', description: 'Rule { "ref": "<built-in field name or cf:<fieldId>>", "operator": "equals|not_equals|contains|starts_with|is_empty|is_not_empty", "value": "..." }, or a group { "all": [rules] } / { "any": [rules] }.' },
42
+ },
43
+ required: ['entity'],
44
+ },
45
+ },
46
+ {
47
+ name: 'crm_field_archive',
48
+ description: 'Archive a CRM custom field. Administrator only. Saved values are kept but stop showing.',
49
+ inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] },
50
+ },
51
+ {
52
+ name: 'crm_layout_list',
53
+ description: 'List the CRM form layouts (Form Designer) for one record type, with the pipeline, stage and role each one is for and which is the default.',
54
+ inputSchema: { type: 'object', properties: { entity: { type: 'string', enum: ENTITIES }, pipelineId: { type: 'number' } }, required: ['entity'] },
55
+ },
56
+ {
57
+ name: 'crm_layout_resolve',
58
+ description: 'Show which form layout the signed-in user would get for a record type, pipeline and stage (most specific match wins, then the default, then the current field order).',
59
+ inputSchema: { type: 'object', properties: { entity: { type: 'string', enum: ENTITIES }, pipelineId: { type: 'number' }, stageId: { type: 'string' } }, required: ['entity'] },
60
+ },
61
+ {
62
+ name: 'crm_layout_save',
63
+ description: 'Create or update a CRM form layout. Administrator only; part of the CRM Studio package (see your plan). layout is { sections:[{ key, title, columns, collapsed, visibleWhen, fields:[{ ref, span, readOnly, requiredWhen, visibleWhen }] }] } where ref is a built-in field name or cf:<customFieldId>. Pass id to update.',
64
+ inputSchema: {
65
+ type: 'object',
66
+ properties: {
67
+ id: { type: 'number' },
68
+ entity: { type: 'string', enum: ENTITIES },
69
+ name: { type: 'string' },
70
+ pipelineId: { type: 'number' },
71
+ stageId: { type: 'string' },
72
+ roles: { type: 'array', items: { type: 'string' }, description: 'Roles this layout is for: Admin, Manager, Agent, Viewer, Billing. Empty means everyone.' },
73
+ isDefault: { type: 'boolean' },
74
+ expectedVersion: { type: 'number', description: 'On update: the layout version your edit is based on. A stale value is rejected with a conflict; omit to use the current version.' },
75
+ layout: { type: 'object' },
76
+ },
77
+ required: ['entity', 'name', 'layout'],
78
+ },
79
+ },
80
+ {
81
+ name: 'crm_layout_delete',
82
+ description: 'Delete a CRM form layout. Administrator only. Field values are not touched.',
83
+ inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] },
84
+ },
85
+ {
86
+ name: 'crm_layout_versions',
87
+ description: 'List the saved versions of a CRM form layout.',
88
+ inputSchema: { type: 'object', properties: { id: { type: 'number' } }, required: ['id'] },
89
+ },
90
+ {
91
+ name: 'crm_layout_restore',
92
+ description: 'Restore a saved version of a CRM form layout. The replaced version is kept. Administrator only.',
93
+ inputSchema: { type: 'object', properties: { id: { type: 'number' }, version: { type: 'number' } }, required: ['id', 'version'] },
94
+ },
95
+ ];
96
+
97
+ // Update semantics (server): an absent or null key leaves the stored value alone; an empty string clears it.
98
+ // Only keys the caller passed are sent. An empty array or empty object clears the matching JSON setting.
99
+ const jsonArg = (v) => (v === undefined ? undefined : (Array.isArray(v) && v.length === 0) || (v && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).length === 0) || v === null ? '' : JSON.stringify(v));
100
+ const fieldBody = (a) => {
101
+ const body = { entity: a.entity };
102
+ const set = (k, v) => { if (v !== undefined) body[k] = v; };
103
+ set('label', a.label);
104
+ set('fieldType', a.fieldType);
105
+ set('optionsJson', jsonArg(a.options));
106
+ set('isRequired', a.isRequired);
107
+ set('pipelineId', a.pipelineId);
108
+ set('sortOrder', a.sortOrder);
109
+ set('helpText', a.helpText);
110
+ set('defaultValue', a.defaultValue);
111
+ set('validationJson', jsonArg(a.validation));
112
+ set('readRolesJson', jsonArg(a.readRoles));
113
+ set('writeRolesJson', jsonArg(a.writeRoles));
114
+ set('visibleWhenJson', jsonArg(a.visibleWhen));
115
+ return body;
116
+ };
117
+
118
+ const layoutBody = (a) => ({
119
+ entity: a.entity,
120
+ name: a.name,
121
+ pipelineId: a.pipelineId ?? null,
122
+ stageId: a.stageId ?? null,
123
+ roles: a.roles ?? [],
124
+ isDefault: !!a.isDefault,
125
+ layout: a.layout,
126
+ ...(a.expectedVersion !== undefined ? { expectedVersion: a.expectedVersion } : {}),
127
+ });
128
+
129
+ export const handlers = {
130
+ crm_field_list: async (a, ctx) => data(await ctx.messagingGet(`/CrmCustomFields${q({ entity: a.entity, pipelineId: a.pipelineId })}`)),
131
+ crm_field_define: async (a, ctx) =>
132
+ data(a.id ? await ctx.messagingPut(`/CrmCustomFields/${encodeURIComponent(a.id)}`, fieldBody(a)) : await ctx.messagingPost('/CrmCustomFields', fieldBody(a))),
133
+ crm_field_archive: async (a, ctx) => data(await ctx.messagingDel(`/CrmCustomFields/${encodeURIComponent(a.id)}`)),
134
+ crm_layout_list: async (a, ctx) => data(await ctx.messagingGet(`/CrmFormLayouts${q({ entity: a.entity, pipelineId: a.pipelineId })}`)),
135
+ crm_layout_resolve: async (a, ctx) =>
136
+ data(await ctx.messagingGet(`/CrmFormLayouts/resolve${q({ entity: a.entity, pipelineId: a.pipelineId, stageId: a.stageId })}`)),
137
+ crm_layout_save: async (a, ctx) => {
138
+ if (!a.id) return data(await ctx.messagingPost('/CrmFormLayouts', layoutBody(a)));
139
+ const body = layoutBody(a);
140
+ if (body.expectedVersion === undefined) {
141
+ const current = data(await ctx.messagingGet(`/CrmFormLayouts/${encodeURIComponent(a.id)}`));
142
+ if (current?.version !== undefined) body.expectedVersion = current.version;
143
+ }
144
+ return data(await ctx.messagingPut(`/CrmFormLayouts/${encodeURIComponent(a.id)}`, body));
145
+ },
146
+ crm_layout_delete: async (a, ctx) => data(await ctx.messagingDel(`/CrmFormLayouts/${encodeURIComponent(a.id)}`)),
147
+ crm_layout_versions: async (a, ctx) => data(await ctx.messagingGet(`/CrmFormLayouts/${encodeURIComponent(a.id)}/versions`)),
148
+ crm_layout_restore: async (a, ctx) =>
149
+ data(await ctx.messagingPost(`/CrmFormLayouts/${encodeURIComponent(a.id)}/versions/${encodeURIComponent(a.version)}/restore`, {})),
150
+ };