@teamnetwork-nz/teamlink-mcp-server 0.5.4 → 0.5.7
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 +47 -11
- package/package.json +1 -1
package/build/index.js
CHANGED
|
@@ -41,6 +41,12 @@ const http = axios.create({
|
|
|
41
41
|
function ok(data) {
|
|
42
42
|
return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
|
|
43
43
|
}
|
|
44
|
+
function usageError(message, details) {
|
|
45
|
+
return {
|
|
46
|
+
content: [{ type: 'text', text: `Tool argument error: ${JSON.stringify({ message, ...details })}` }],
|
|
47
|
+
isError: true,
|
|
48
|
+
};
|
|
49
|
+
}
|
|
44
50
|
function fail(err) {
|
|
45
51
|
if (!API_KEY) {
|
|
46
52
|
return {
|
|
@@ -57,6 +63,16 @@ function fail(err) {
|
|
|
57
63
|
};
|
|
58
64
|
}
|
|
59
65
|
async function get(path, params) {
|
|
66
|
+
const allowedParams = allowedQueryParams[path];
|
|
67
|
+
if (allowedParams && params) {
|
|
68
|
+
const unknownParams = Object.keys(params).filter((key) => !allowedParams.has(key));
|
|
69
|
+
if (unknownParams.length) {
|
|
70
|
+
return usageError(`Unknown query parameter(s): ${unknownParams.join(', ')}`, {
|
|
71
|
+
unknownParams,
|
|
72
|
+
allowedParams: [...allowedParams].sort(),
|
|
73
|
+
});
|
|
74
|
+
}
|
|
75
|
+
}
|
|
60
76
|
try {
|
|
61
77
|
const r = await http.get(path, { params });
|
|
62
78
|
return ok(r.data);
|
|
@@ -84,11 +100,26 @@ async function put(path, body) {
|
|
|
84
100
|
}
|
|
85
101
|
}
|
|
86
102
|
const server = new McpServer({ name: 'teamlink-mcp', version: pkgVersion() });
|
|
103
|
+
const allowedQueryParams = {
|
|
104
|
+
'/accounts/search': new Set(['q', 'phone', 'exactWebsite', 'page', 'pageSize']),
|
|
105
|
+
'/accounts': new Set(['search', 'isActive', 'isCustomer', 'isProspect', 'isSupplier', 'isBranch', 'branchId', 'teamId', 'page', 'pageSize']),
|
|
106
|
+
'/contacts/search': new Set(['q', 'accountId', 'email', 'mobile', 'businessPhone', 'isActive', 'role', 'page', 'pageSize']),
|
|
107
|
+
'/tasks/time-entries/search': new Set(['taskId', 'accountId', 'personId', 'type', 'q', 'dateFrom', 'dateTo', 'page', 'pageSize']),
|
|
108
|
+
'/tasks/search': new Set(['q', 'accountId', 'loggedForUserId', 'assignedToUserId', 'enteredByUserId', 'callType', 'priority', 'status', 'dateFrom', 'dateTo', 'page', 'pageSize']),
|
|
109
|
+
'/orders/search': new Set(['q', 'advanced', 'accountId', 'branchId', 'enteredByUserId', 'authorisedByUserId', 'vendorId', 'receivedByUserId', 'approvedByUserId', 'invoicedByUserId', 'returnAuthorisedByUserId', 'creditedByUserId', 'orderType', 'dateFrom', 'dateTo', 'received', 'invoiced', 'returned', 'page', 'pageSize']),
|
|
110
|
+
'/orders/products/search': new Set(['q', 'vendorId', 'manufacturer', 'category', 'page', 'pageSize']),
|
|
111
|
+
};
|
|
87
112
|
// --- Identity ---
|
|
88
113
|
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'));
|
|
89
114
|
// --- CRM: accounts ---
|
|
90
|
-
server.tool('crm_search_accounts', 'Search customer accounts by name, alpha id,
|
|
91
|
-
|
|
115
|
+
server.tool('crm_search_accounts', 'Search customer accounts by account id, name, alpha id, email domain, website, or normalized phone. Also accepts explicit phone and exactWebsite duplicate-detection style inputs. Results include selector objects for industry/source/salesStatus and named team/contact reference objects where available.', {
|
|
116
|
+
q: z.string().describe('Search text: account ID (CSAID), account name, alpha ID, email domain, website, or phone digits.'),
|
|
117
|
+
phone: z.string().optional().describe('Optional phone search; punctuation/spaces are ignored and partial digit matches are allowed against CSAccount.CSAPhone.'),
|
|
118
|
+
exactWebsite: z.string().optional().describe('Optional exact website match against CSAccount.CSAWebsite.'),
|
|
119
|
+
page: z.number().optional(),
|
|
120
|
+
pageSize: z.number().optional(),
|
|
121
|
+
}, async (args) => get('/accounts/search', args));
|
|
122
|
+
server.tool('crm_list_accounts', 'List/filter accounts. `isActive` filters on CSAActive — only active accounts are eligible for transactional activity (orders/tasks). Results include selector objects for industry/source/salesStatus and named team/contact reference objects where available.', {
|
|
92
123
|
search: z.string().optional(), isActive: z.boolean().optional(), isCustomer: z.boolean().optional(), isProspect: z.boolean().optional(),
|
|
93
124
|
isSupplier: z.boolean().optional(), branchId: z.string().optional(), page: z.number().optional(), pageSize: z.number().optional(),
|
|
94
125
|
}, async (args) => get('/accounts', args));
|
|
@@ -96,7 +127,7 @@ server.tool('crm_list_accounts', 'List/filter accounts. `isActive` filters on CS
|
|
|
96
127
|
// and everything linked to it (contacts, orders, tasks, ...) — see lookup_selectors
|
|
97
128
|
// and crm_search_accounts for how to resolve one. Response `isActive` = CSAActive:
|
|
98
129
|
// 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}`));
|
|
130
|
+
server.tool('crm_get_account', 'Get one account by id (CSAID). Response `isActive` (CSAActive) gates transactional eligibility for orders/tasks. Lookup-backed fields include industry/source/salesStatus {code,label}, team {teamId,name}, and accountManager/preferredEngineer/backupEngineer/bizDevManager {userId,name}.', { accountId: z.number() }, async ({ accountId }) => get(`/accounts/${accountId}`));
|
|
100
131
|
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
132
|
if (READWRITE) {
|
|
102
133
|
server.tool('crm_create_account', 'Create an account. Returns duplicate-candidate warnings unless createAnyway=true.', {
|
|
@@ -112,8 +143,11 @@ if (READWRITE) {
|
|
|
112
143
|
// TYPE) — typeFlags.isAdminContact means a client-side admin/accounts contact,
|
|
113
144
|
// NOT the application admin role (role="A").
|
|
114
145
|
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
|
|
146
|
+
server.tool('crm_search_contacts', 'Search contacts by contact id, names, email, mobile, business phone, account id, web-app role (CSCClass), and active pivot status.', {
|
|
116
147
|
q: z.string().optional(), accountId: z.number().optional(), email: z.string().optional(),
|
|
148
|
+
mobile: z.string().optional().describe('Filter by mobile phone (CSContact.CSCMobile); punctuation/spaces are ignored and partial digit matches are allowed.'),
|
|
149
|
+
businessPhone: z.string().optional().describe('Filter by business/DDI phone (CSContact.CSCBizPhone); punctuation/spaces are ignored and partial digit matches are allowed.'),
|
|
150
|
+
isActive: z.boolean().optional().describe('Filter by CSPivotContactAccount.CSPCA_Active when pivot context is joined.'),
|
|
117
151
|
role: z.string().optional().describe(roleDescription),
|
|
118
152
|
page: z.number().optional(), pageSize: z.number().optional(),
|
|
119
153
|
}, async (args) => get('/contacts/search', args));
|
|
@@ -134,22 +168,24 @@ if (READWRITE) {
|
|
|
134
168
|
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)}`));
|
|
135
169
|
server.tool('lookup_branches', 'List branches.', {}, async () => get('/lookups/branches'));
|
|
136
170
|
// --- Tasks / time (read) ---
|
|
137
|
-
server.tool('task_get', 'Get a task by id.', { taskId: z.number() }, async ({ taskId }) => get(`/tasks/${taskId}`));
|
|
171
|
+
server.tool('task_get', 'Get a task by id. Returns account/bill-to and contact actor fields as objects with IDs and names, while retaining raw ID fields.', { taskId: z.number() }, async ({ taskId }) => get(`/tasks/${taskId}`));
|
|
138
172
|
server.tool('task_list_time_entries', 'List time/incidental entries + totals for a task. Can filter by staff person who performed the work (TMActivity.TMA_CSCID).', {
|
|
139
173
|
taskId: z.number().describe('Task ID (TMTask.TMTID / TMActivity.TMA_TMTID).'),
|
|
140
174
|
personId: z.number().optional().describe('Filter by staff person who performed the work (TMActivity.TMA_CSCID).'),
|
|
141
175
|
type: z.enum(['time', 'incidentals', 'all']).optional().describe('Entry kind based on TMActivity.TMACost: time = TMACost 0, incidentals = TMACost non-zero.'),
|
|
142
176
|
}, async ({ taskId, personId, type }) => get(`/tasks/${taskId}/time-entries`, { personId, type }));
|
|
143
|
-
server.tool('task_search_time_entries', 'Search task activity/time and incidentals across tasks. Supports filtering by taskId, staff performer (TMActivity.TMA_CSCID), date range, and
|
|
177
|
+
server.tool('task_search_time_entries', 'Search task activity/time and incidentals across tasks. Supports filtering by account/customer (TMTask.TMT_CSAID), taskId, staff performer (TMActivity.TMA_CSCID), date range, entry kind, and text in public/internal descriptions. Date filters are `dateFrom`/`dateTo` only; do not use `fromDate`/`toDate`.', {
|
|
144
178
|
taskId: z.number().optional().describe('Filter by task ID (TMActivity.TMA_TMTID).'),
|
|
179
|
+
accountId: z.number().optional().describe('Filter by customer/account/company (CSAID). Maps through TMTask.TMT_CSAID for the task the entry belongs to.'),
|
|
145
180
|
personId: z.number().optional().describe('Filter by staff person who performed the work (TMActivity.TMA_CSCID).'),
|
|
146
181
|
type: z.enum(['time', 'incidentals', 'all']).optional().describe('Entry kind based on TMActivity.TMACost: time = TMACost 0, incidentals = TMACost non-zero.'),
|
|
147
|
-
|
|
148
|
-
|
|
182
|
+
q: z.string().optional().describe('Partial text match against TMActivity.TMADescription and TMActivity.TMAInternal.'),
|
|
183
|
+
dateFrom: z.string().optional().describe('Activity date range start (TMActivity.TMADate), e.g. 2026-01-01. Use this exact parameter name, not fromDate.'),
|
|
184
|
+
dateTo: z.string().optional().describe('Activity date range end (TMActivity.TMADate). Use this exact parameter name, not toDate.'),
|
|
149
185
|
page: z.number().optional(),
|
|
150
186
|
pageSize: z.number().optional(),
|
|
151
187
|
}, async (args) => get('/tasks/time-entries/search', args));
|
|
152
|
-
server.tool('task_search', 'Search/filter tasks. Supports filtering by customer/account, logged-for contact, assigned staff member, entered-by staff member, call type, priority/severity, open/closed status, a date-logged range, and/or free text. Defaults to open tasks only unless status is set. Every filter is optional and combinable.', {
|
|
188
|
+
server.tool('task_search', 'Search/filter tasks. Supports filtering by customer/account, logged-for contact, assigned staff member, entered-by staff member, call type, priority/severity, open/closed status, a date-logged range, and/or free text. Defaults to open tasks only unless status is set. Every filter is optional and combinable. Results include account/loggedFor/assignedTo/enteredBy objects with names, plus raw IDs.', {
|
|
153
189
|
q: z.string().optional().describe('Free text: exact task ID match, or partial match on task name/description.'),
|
|
154
190
|
accountId: z.number().optional().describe('Filter by customer/account/company (CSAID). Maps to TMTask.TMT_CSAID — the account the task was logged for.'),
|
|
155
191
|
loggedForUserId: z.number().optional().describe('Filter by the customer contact who requested/is authorising the task (TMTask.TMTLoggedBy_CSCID).'),
|
|
@@ -163,9 +199,9 @@ server.tool('task_search', 'Search/filter tasks. Supports filtering by customer/
|
|
|
163
199
|
page: z.number().optional(), pageSize: z.number().optional(),
|
|
164
200
|
}, async (args) => get('/tasks/search', args));
|
|
165
201
|
// --- Orders / PM (read) ---
|
|
166
|
-
server.tool('order_get', 'Get an order header + totals. `orderType` is returned as { code, label } from CSSelectors/OrderType.', { orderId: z.number() }, async ({ orderId }) => get(`/orders/${orderId}`));
|
|
202
|
+
server.tool('order_get', 'Get an order header + totals. Returns account/bill-to and contact actor fields as objects with IDs and names, while retaining raw ID fields. `orderType` is returned as { code, label } from CSSelectors/OrderType.', { orderId: z.number() }, async ({ orderId }) => get(`/orders/${orderId}`));
|
|
167
203
|
server.tool('order_list_items', 'List order line items.', { orderId: z.number() }, async ({ orderId }) => get(`/orders/${orderId}/items`));
|
|
168
|
-
server.tool('order_search', 'Search/filter orders. Supports filtering by customer/account, branch, order type, a date-raised range, who entered or authorised the order, who received/approved/invoiced/returned/credited a line, received/invoiced/returned status, and/or free text (order id, invoice/credit/RA reference, or with advanced=true also notes and product codes/descriptions). Every filter is optional and combinable. Returned `orderType` is { code, label } resolved from CSSelectors/OrderType.', {
|
|
204
|
+
server.tool('order_search', 'Search/filter orders. Supports filtering by customer/account, branch, order type, a date-raised range, who entered or authorised the order, who received/approved/invoiced/returned/credited a line, received/invoiced/returned status, and/or free text (order id, invoice/credit/RA reference, or with advanced=true also notes and product codes/descriptions). Every filter is optional and combinable. Results include account/enteredBy/authorisedBy objects with names, plus raw IDs. Returned `orderType` is { code, label } resolved from CSSelectors/OrderType.', {
|
|
169
205
|
q: z.string().optional().describe('Free text search — order id (exact), invoice/credit/RA reference (partial); with advanced=true also order notes and line product code/OEM code/descriptions.'),
|
|
170
206
|
advanced: z.boolean().optional().describe('Widen `q` to also match order notes and line product code/OEM code/descriptions.'),
|
|
171
207
|
accountId: z.number().optional().describe('Filter by customer/account/company (CSAID). Maps to PMOrder.PMO_CSAID.'),
|