@teamnetwork-nz/teamlink-mcp-server 0.2.0 → 0.4.0
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/build/index.js +60 -17
- package/package.json +1 -1
package/build/index.js
CHANGED
|
@@ -1,9 +1,21 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
import 'dotenv/config';
|
|
3
|
+
import { readFileSync } from 'node:fs';
|
|
4
|
+
import { fileURLToPath } from 'node:url';
|
|
5
|
+
import { dirname, join } from 'node:path';
|
|
3
6
|
import axios from 'axios';
|
|
4
7
|
import { z } from 'zod';
|
|
5
8
|
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
6
9
|
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
|
|
10
|
+
const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
11
|
+
function pkgVersion() {
|
|
12
|
+
try {
|
|
13
|
+
return JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8')).version ?? '0.0.0';
|
|
14
|
+
}
|
|
15
|
+
catch {
|
|
16
|
+
return '0.0.0';
|
|
17
|
+
}
|
|
18
|
+
}
|
|
7
19
|
/**
|
|
8
20
|
* TEAMlink MCP server. Exposes read/write tools that proxy the TEAMlink REST API
|
|
9
21
|
* (teamlink-api). The API enforces auth (CSCApiKey) and all business rules — this
|
|
@@ -15,6 +27,12 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
|
|
|
15
27
|
*/
|
|
16
28
|
const API_BASE = (process.env.TEAMLINK_API_BASE ?? 'http://localhost:3100').replace(/\/$/, '');
|
|
17
29
|
const API_KEY = process.env.TEAMLINK_API_KEY ?? '';
|
|
30
|
+
/**
|
|
31
|
+
* Write-tool gate. Defaults to false (non-destructive/read-only) so this server
|
|
32
|
+
* is safe to point at production unless explicitly opted in. Accepts common
|
|
33
|
+
* truthy strings; anything else (including unset) is treated as false.
|
|
34
|
+
*/
|
|
35
|
+
const READWRITE = /^(1|true|yes|on)$/i.test(process.env.TEAMLINK_READWRITE ?? '');
|
|
18
36
|
const http = axios.create({
|
|
19
37
|
baseURL: API_BASE,
|
|
20
38
|
timeout: 20_000,
|
|
@@ -65,29 +83,53 @@ async function put(path, body) {
|
|
|
65
83
|
return fail(e);
|
|
66
84
|
}
|
|
67
85
|
}
|
|
68
|
-
const server = new McpServer({ name: 'teamlink-mcp', version:
|
|
86
|
+
const server = new McpServer({ name: 'teamlink-mcp', version: pkgVersion() });
|
|
69
87
|
// --- Identity ---
|
|
70
|
-
server.tool('teamlink_whoami', 'Return the authenticated TEAMlink user context for the configured API key.', {}, async () => get('/me'));
|
|
88
|
+
server.tool('teamlink_whoami', 'Return the authenticated TEAMlink user context for the configured API key, including `roleClass` (CSCClass) and `homeAccountId` (CSAID — the identity key scoping staff vs customer visibility).', {}, async () => get('/me'));
|
|
71
89
|
// --- CRM: accounts ---
|
|
72
90
|
server.tool('crm_search_accounts', 'Search customer accounts by name, alpha id, phone or website (priority search).', { q: z.string().describe('search text (name / alpha id)'), phone: z.string().optional(), exactWebsite: z.string().optional() }, async ({ q, phone, exactWebsite }) => get('/accounts/search', { q, phone, exactWebsite }));
|
|
73
|
-
server.tool('crm_list_accounts', 'List/filter accounts.', {
|
|
74
|
-
search: z.string().optional(), isCustomer: z.boolean().optional(), isProspect: z.boolean().optional(),
|
|
91
|
+
server.tool('crm_list_accounts', 'List/filter accounts. `isActive` filters on CSAActive — only active accounts are eligible for transactional activity (orders/tasks).', {
|
|
92
|
+
search: z.string().optional(), isActive: z.boolean().optional(), isCustomer: z.boolean().optional(), isProspect: z.boolean().optional(),
|
|
75
93
|
isSupplier: z.boolean().optional(), branchId: z.string().optional(), page: z.number().optional(), pageSize: z.number().optional(),
|
|
76
94
|
}, async (args) => get('/accounts', args));
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
}, async (
|
|
95
|
+
// `accountId` (CSAID) is the absolute source-of-truth identity key for this account
|
|
96
|
+
// and everything linked to it (contacts, orders, tasks, ...) — see lookup_selectors
|
|
97
|
+
// and crm_search_accounts for how to resolve one. Response `isActive` = CSAActive:
|
|
98
|
+
// only active accounts are eligible for transactional activity (orders/tasks).
|
|
99
|
+
server.tool('crm_get_account', 'Get one account by id (CSAID). Response `isActive` (CSAActive) gates transactional eligibility for orders/tasks.', { accountId: z.number() }, async ({ accountId }) => get(`/accounts/${accountId}`));
|
|
100
|
+
server.tool('crm_list_account_contacts', 'List contacts linked to an account. Defaults to active-only (CSPCA_Active); pass includeInactive=true to also return deactivated contacts for historical/reporting purposes — inactive does not mean deleted.', { accountId: z.number(), includeInactive: z.boolean().optional() }, async ({ accountId, includeInactive }) => get(`/accounts/${accountId}/contacts`, { includeInactive }));
|
|
101
|
+
if (READWRITE) {
|
|
102
|
+
server.tool('crm_create_account', 'Create an account. Returns duplicate-candidate warnings unless createAnyway=true.', {
|
|
103
|
+
name: z.string(), alphaId: z.string().optional(), website: z.string().optional(), phone: z.string().optional(),
|
|
104
|
+
isCustomer: z.boolean().optional(), isProspect: z.boolean().optional(), createAnyway: z.boolean().optional(),
|
|
105
|
+
}, async (args) => post('/accounts', args));
|
|
106
|
+
}
|
|
83
107
|
// --- CRM: contacts ---
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
108
|
+
// `role` (CSCClass) is the web-app role/access class: A=Administrator, C=Customer,
|
|
109
|
+
// E=Engineer, M=Business Manager, P=Partner, S=Sales, T=Account Manager. Labels
|
|
110
|
+
// are authoritative via the lookup_selectors tool with selectorClass="UserClass".
|
|
111
|
+
// This is DISTINCT from a contact's `typeFlags` (sales/technical/admin/etc. contact
|
|
112
|
+
// TYPE) — typeFlags.isAdminContact means a client-side admin/accounts contact,
|
|
113
|
+
// NOT the application admin role (role="A").
|
|
114
|
+
const roleDescription = 'CSCClass web-app role: A=Administrator, C=Customer, E=Engineer, M=Business Manager, P=Partner, S=Sales, T=Account Manager.';
|
|
115
|
+
server.tool('crm_search_contacts', 'Search contacts by name/email/phone/role.', {
|
|
116
|
+
q: z.string().optional(), accountId: z.number().optional(), email: z.string().optional(),
|
|
117
|
+
role: z.string().optional().describe(roleDescription),
|
|
118
|
+
page: z.number().optional(), pageSize: z.number().optional(),
|
|
119
|
+
}, async (args) => get('/contacts/search', args));
|
|
120
|
+
server.tool('crm_get_contact', 'Get one contact by id. Response includes `role` (CSCClass) and `typeFlags` (contact type, distinct from role), `homeAccountId` (the CSAID this contact belongs to), and `isActive` — sourced from the CSPivotContactAccount pivot (CSPCA_Active), NOT the legacy/unused CSCActive column. An inactive contact may still be returned for historical/reporting purposes.', { contactId: z.number() }, async ({ contactId }) => get(`/contacts/${contactId}`));
|
|
121
|
+
if (READWRITE) {
|
|
122
|
+
server.tool('crm_create_contact', 'Create a contact under an account (also creates the active account link).', {
|
|
123
|
+
accountId: z.number(), firstName: z.string(), lastName: z.string(), email: z.string(),
|
|
124
|
+
mobile: z.string().optional(), businessPhone: z.string().optional(),
|
|
125
|
+
role: z.string().optional().describe(roleDescription + ' Only settable for branch accounts; forced to C otherwise.'),
|
|
126
|
+
}, async ({ accountId, ...body }) => post(`/accounts/${accountId}/contacts`, body));
|
|
127
|
+
server.tool('crm_update_contact', 'Update a contact. Password only applied if supplied. `active` sets CSPivotContactAccount.CSPCA_Active for the account context (the legacy CSCActive column is never written).', {
|
|
128
|
+
contactId: z.number(), firstName: z.string(), lastName: z.string(), email: z.string(), mobile: z.string().optional(),
|
|
129
|
+
role: z.string().optional().describe(roleDescription),
|
|
130
|
+
active: z.boolean().optional().describe('Sets CSPCA_Active (pivot) for the account context, not CSCActive.'),
|
|
131
|
+
}, async ({ contactId, ...body }) => put(`/contacts/${contactId}`, body));
|
|
132
|
+
}
|
|
91
133
|
// --- Lookups ---
|
|
92
134
|
server.tool('lookup_selectors', 'Get options for a CSSelectors list (Industry, Source, SalesStatus, OrderType, IncomeCat, City, Country, ...).', { selectorClass: z.string() }, async ({ selectorClass }) => get(`/lookups/selectors/${encodeURIComponent(selectorClass)}`));
|
|
93
135
|
server.tool('lookup_branches', 'List branches.', {}, async () => get('/lookups/branches'));
|
|
@@ -102,6 +144,7 @@ async function main() {
|
|
|
102
144
|
if (!API_KEY) {
|
|
103
145
|
console.error('[teamlink-mcp] WARNING: TEAMLINK_API_KEY is not set; all tool calls will fail until it is configured.');
|
|
104
146
|
}
|
|
147
|
+
console.error(`[teamlink-mcp] mode: ${READWRITE ? 'READ-WRITE (write tools enabled)' : 'read-only (set TEAMLINK_READWRITE=true to enable write tools)'}`);
|
|
105
148
|
const transport = new StdioServerTransport();
|
|
106
149
|
await server.connect(transport);
|
|
107
150
|
console.error(`[teamlink-mcp] connected (stdio), proxying ${API_BASE}`);
|