@velaro/mcp-server 2.0.92 → 2.0.94

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.92",
3
+ "version": "2.0.94",
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,113 @@
1
+ // MCP parity for `velaro crm-import`, `crm-tag`, `crm-dedupe` and `crm-audit` (cli/lib/commands/crm-import-dedupe-audit.js).
2
+ // Backend: velaro-messaging CrmImportController, CrmTagsController, CrmDealDuplicatesController and CrmAuditController
3
+ // (docs/architecture/crm-studio-program.md, features 11 to 14). Site from the credential, never an argument.
4
+
5
+ const ENTITIES = ['contact', 'company', 'deal'];
6
+ const TAG_ENTITIES = ['company', 'deal'];
7
+
8
+ const data = (r) => (r && typeof r === 'object' && 'data' in r ? r.data : r);
9
+ const q = (o) => {
10
+ const p = Object.entries(o).filter(([, v]) => v !== undefined && v !== null && v !== '').map(([k, v]) => `${k}=${encodeURIComponent(v)}`);
11
+ return p.length ? `?${p.join('&')}` : '';
12
+ };
13
+ const id = (v) => encodeURIComponent(v);
14
+
15
+ const importProps = {
16
+ entity: { type: 'string', enum: ENTITIES },
17
+ csv: { type: 'string', description: 'The CSV text; the first line is the header. Comma, semicolon or tab separated.' },
18
+ mapping: { type: 'object', description: 'Column header to field (built-in name or cf:<customFieldId>). Unlisted columns are matched by name, so an exported file needs no mapping.' },
19
+ duplicates: { type: 'string', enum: ['skip', 'update'], description: 'Existing contact (same email) or company (same name): skip it (default) or update only the filled-in cells.' },
20
+ pipelineId: { type: 'number', description: 'Deals: the pipeline for rows without a pipeline column.' },
21
+ };
22
+
23
+ export const tools = [
24
+ {
25
+ name: 'crm_import_meta',
26
+ description: 'List what a CRM CSV import supports: the record types, the built-in fields and custom fields a column can map to, and the file limits.',
27
+ inputSchema: { type: 'object', properties: {} },
28
+ },
29
+ {
30
+ name: 'crm_import_preview',
31
+ description: 'Dry run of a CRM CSV import for contacts, companies or deals. Nothing is written. Returns the mapped and ignored columns and, for every row, whether it would create, update, skip or fail and why. Always preview before committing. Part of the CRM Studio package (see your plan).',
32
+ inputSchema: { type: 'object', properties: importProps, required: ['entity', 'csv'] },
33
+ },
34
+ {
35
+ name: 'crm_import_commit',
36
+ description: 'Import a CSV of contacts, companies or deals into the CRM. Manager or Administrator only. Rows go through the same checks as a single create (field rules, field security, plan limits, stage rules). A tags column adds tags by name. Run crm_import_preview first. Part of the CRM Studio package (see your plan).',
37
+ inputSchema: { type: 'object', properties: importProps, required: ['entity', 'csv'] },
38
+ },
39
+ {
40
+ name: 'crm_import_export',
41
+ description: 'Export contacts, companies or deals as CSV text. The file imports back with no mapping. Custom fields the caller cannot read are left out. Manager or Administrator only. Part of the CRM Studio package (see your plan).',
42
+ inputSchema: {
43
+ type: 'object',
44
+ properties: { entity: { type: 'string', enum: ENTITIES }, skip: { type: 'number' }, take: { type: 'number' } },
45
+ required: ['entity'],
46
+ },
47
+ },
48
+ {
49
+ name: 'crm_tag_list',
50
+ description: 'List the tags on one CRM company or deal. Tags come from the same site tag list contacts use.',
51
+ inputSchema: { type: 'object', properties: { entity: { type: 'string', enum: TAG_ENTITIES }, id: { type: 'number' } }, required: ['entity', 'id'] },
52
+ },
53
+ {
54
+ name: 'crm_tag_add',
55
+ description: 'Tag a CRM company or deal. Adding the same tag twice keeps one tag.',
56
+ inputSchema: { type: 'object', properties: { entity: { type: 'string', enum: TAG_ENTITIES }, id: { type: 'number' }, tagId: { type: 'number' } }, required: ['entity', 'id', 'tagId'] },
57
+ },
58
+ {
59
+ name: 'crm_tag_remove',
60
+ description: 'Remove a tag from a CRM company or deal.',
61
+ inputSchema: { type: 'object', properties: { entity: { type: 'string', enum: TAG_ENTITIES }, id: { type: 'number' }, tagId: { type: 'number' } }, required: ['entity', 'id', 'tagId'] },
62
+ },
63
+ {
64
+ name: 'crm_dedupe_find',
65
+ description: 'Find groups of open CRM deals that look like duplicates: same title (case and punctuation ignored), same company, a shared contact, and amounts within a window. Part of the CRM Studio package (see your plan).',
66
+ inputSchema: {
67
+ type: 'object',
68
+ properties: {
69
+ pipelineId: { type: 'number' },
70
+ amountWindowPercent: { type: 'number', description: 'How close the amounts must be, in percent.' },
71
+ maxGroups: { type: 'number' },
72
+ },
73
+ },
74
+ },
75
+ {
76
+ name: 'crm_dedupe_merge',
77
+ description: 'Merge duplicate CRM deals into a survivor. Notes, activities, contacts, conversations, tickets, attachments and custom field values move to the survivor, blank survivor fields are filled, and each duplicate is archived (restorable with crm_bulk_run action restore). Manager or Administrator only. Use dryRun first. Part of the CRM Studio package (see your plan).',
78
+ inputSchema: {
79
+ type: 'object',
80
+ properties: { survivorId: { type: 'number' }, duplicateIds: { type: 'array', items: { type: 'number' } }, dryRun: { type: 'boolean' } },
81
+ required: ['survivorId', 'duplicateIds'],
82
+ },
83
+ },
84
+ {
85
+ name: 'crm_audit_list',
86
+ description: 'Show the field-change history of one CRM contact, company or deal, newest first: which field, the before and after value, who changed it and from where. Custom fields the caller cannot read are left out. Part of the CRM Studio package (see your plan).',
87
+ inputSchema: {
88
+ type: 'object',
89
+ properties: { entity: { type: 'string', enum: ENTITIES }, id: { type: 'number' }, page: { type: 'number' }, pageSize: { type: 'number' } },
90
+ required: ['entity', 'id'],
91
+ },
92
+ },
93
+ ];
94
+
95
+ const importBody = (a) => {
96
+ const body = { entity: a.entity, csv: a.csv, duplicates: a.duplicates ?? 'skip' };
97
+ if (a.mapping !== undefined) body.mapping = a.mapping;
98
+ if (a.pipelineId !== undefined) body.pipelineId = a.pipelineId;
99
+ return body;
100
+ };
101
+
102
+ export const handlers = {
103
+ crm_import_meta: async (_a, ctx) => data(await ctx.messagingGet('/CrmImport/meta')),
104
+ crm_import_preview: async (a, ctx) => data(await ctx.messagingPost('/CrmImport/preview', importBody(a))),
105
+ crm_import_commit: async (a, ctx) => data(await ctx.messagingPost('/CrmImport/commit', importBody(a))),
106
+ crm_import_export: async (a, ctx) => ctx.messagingText(`/CrmImport/export${q({ entity: a.entity, skip: a.skip, take: a.take })}`),
107
+ crm_tag_list: async (a, ctx) => data(await ctx.messagingGet(`/CrmTags/${id(a.entity)}/${id(a.id)}`)),
108
+ crm_tag_add: async (a, ctx) => data(await ctx.messagingPost(`/CrmTags/${id(a.entity)}/${id(a.id)}/${id(a.tagId)}`, {})),
109
+ crm_tag_remove: async (a, ctx) => data(await ctx.messagingDel(`/CrmTags/${id(a.entity)}/${id(a.id)}/${id(a.tagId)}`)),
110
+ crm_dedupe_find: async (a, ctx) => data(await ctx.messagingGet(`/CrmDealDuplicates${q({ pipelineId: a.pipelineId, amountWindowPercent: a.amountWindowPercent, maxGroups: a.maxGroups })}`)),
111
+ crm_dedupe_merge: async (a, ctx) => data(await ctx.messagingPost('/CrmDealDuplicates/merge', { survivorId: a.survivorId, duplicateIds: a.duplicateIds, dryRun: !!a.dryRun })),
112
+ crm_audit_list: async (a, ctx) => data(await ctx.messagingGet(`/CrmAudit${q({ entity: a.entity, id: a.id, page: a.page, pageSize: a.pageSize })}`)),
113
+ };
package/server.js CHANGED
@@ -160,6 +160,13 @@ async function messagingRequest(method, path, body) {
160
160
  }
161
161
  const MCP_SUBMISSION_LIMIT = 50;
162
162
  const messagingGet = (path) => messagingRequest('GET', path);
163
+ // Raw text reply (CSV export); the JSON helpers above would fail to parse it.
164
+ async function messagingText(path) {
165
+ if (!MESSAGING_API) throw new Error('VELARO_MESSAGING_API is not configured.');
166
+ const res = await fetch(`${MESSAGING_API}${path}`, { headers: { Authorization: authHeader() }, signal: AbortSignal.timeout(30000) });
167
+ if (!res.ok) throw new Error(`${path} -> ${res.status}: ${(await res.text().catch(() => '')).slice(0, 300)}`);
168
+ return await res.text();
169
+ }
163
170
  const messagingPost = (path, body) => messagingRequest('POST', path, body);
164
171
  const messagingPut = (path, body) => messagingRequest('PUT', path, body);
165
172
  function teamRoutingConfigPath(teamId) {
@@ -2556,6 +2563,21 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
2556
2563
  description: 'Set the order revenue attribution window in days (1-30). Applies to orders attributed from now on.',
2557
2564
  inputSchema: { type: 'object', properties: { windowDays: { type: 'number', description: '1 to 30' } }, required: ['windowDays'] },
2558
2565
  },
2566
+ {
2567
+ name: 'site_email_sender_get',
2568
+ description: "Get this account's default From name and address per mail source (campaign, ticket, notification), the effective sender and where it comes from (source, account, velaro-default, built-in), and the verified sending domains an address may use.",
2569
+ inputSchema: { type: 'object', properties: {} },
2570
+ },
2571
+ {
2572
+ name: 'site_email_sender_set',
2573
+ description: "Set this account's From name and/or address for a mail source. The address must be a plain email on one of the account's verified sending domains. A blank value clears that field.",
2574
+ inputSchema: { type: 'object', properties: { source: { type: 'string', description: 'Mail source: campaign, ticket or notification' }, fromName: { type: 'string' }, fromAddress: { type: 'string', description: 'Plain email, e.g. news@yourcompany.com' } }, required: ['source'] },
2575
+ },
2576
+ {
2577
+ name: 'site_email_sender_reset',
2578
+ description: 'Reset a mail source back to the account default sender.',
2579
+ inputSchema: { type: 'object', properties: { source: { type: 'string', description: 'Mail source: campaign, ticket or notification' } }, required: ['source'] },
2580
+ },
2559
2581
  {
2560
2582
  name: 'report_campaign_deliverability',
2561
2583
  description: 'Deliverability health check — bounce rate, complaint rate, unsubscribe rate, open rate. Each metric has a traffic-light status (green/yellow/red) and actionable recommendations.',
@@ -7479,6 +7501,25 @@ reply: ${r?.reply}`;
7479
7501
  return `Revenue attribution window set to ${r.windowDays} days.`;
7480
7502
  }
7481
7503
 
7504
+ case 'site_email_sender_get': {
7505
+ const r = await api('GET', '/SiteSenderSettings');
7506
+ const lines = (r.sources || []).map(s => `${s.source}: ${s.effective.fromName} <${s.effective.fromAddress}> (from ${s.effective.origin}${s.isOverridden ? ', overridden' : ''})`);
7507
+ return lines.join('\n') + `\nVerified sending domains: ${(r.verifiedDomains || []).join(', ') || 'none'}`;
7508
+ }
7509
+
7510
+ case 'site_email_sender_set': {
7511
+ const body = {};
7512
+ if (args.fromName !== undefined) body.fromName = args.fromName;
7513
+ if (args.fromAddress !== undefined) body.fromAddress = args.fromAddress;
7514
+ const r = await api('PUT', `/SiteSenderSettings/${encodeURIComponent(args.source)}`, body);
7515
+ return `Sender for ${r.source} is now ${r.effective.fromName} <${r.effective.fromAddress}>.`;
7516
+ }
7517
+
7518
+ case 'site_email_sender_reset': {
7519
+ const r = await api('DELETE', `/SiteSenderSettings/${encodeURIComponent(args.source)}`);
7520
+ return `Sender for ${r.source} reset to the account default (${r.effective.fromAddress}).`;
7521
+ }
7522
+
7482
7523
  case 'report_campaign_deliverability': {
7483
7524
  const days = args.days ?? 30;
7484
7525
  const r = await api('GET', `/CampaignReports/Deliverability?days=${days}`);
@@ -9871,7 +9912,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
9871
9912
  return { content: [{ type: 'text', text: `Error: ${toolsetBlockedMessage(name, TOOLSETS)}` }], isError: true };
9872
9913
  }
9873
9914
  try {
9874
- const parityResult = await runParity(PARITY, name, args ?? {}, { api, messagingGet, messagingPost, messagingPut, messagingDel, messagingPatch });
9915
+ const parityResult = await runParity(PARITY, name, args ?? {}, { api, messagingGet, messagingText, messagingPost, messagingPut, messagingDel, messagingPatch });
9875
9916
  const result = parityResult !== undefined ? parityResult : await handleTool(name, args ?? {});
9876
9917
  return { content: [{ type: 'text', text: String(result) }] };
9877
9918
  } catch (err) {