@teamnetwork-nz/teamlink-mcp-server 0.3.0 → 0.5.1

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.
Files changed (2) hide show
  1. package/build/index.js +81 -11
  2. 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
@@ -71,17 +83,21 @@ async function put(path, body) {
71
83
  return fail(e);
72
84
  }
73
85
  }
74
- const server = new McpServer({ name: 'teamlink-mcp', version: '0.2.0' });
86
+ const server = new McpServer({ name: 'teamlink-mcp', version: pkgVersion() });
75
87
  // --- Identity ---
76
- 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'));
77
89
  // --- CRM: accounts ---
78
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 }));
79
- server.tool('crm_list_accounts', 'List/filter accounts.', {
80
- 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(),
81
93
  isSupplier: z.boolean().optional(), branchId: z.string().optional(), page: z.number().optional(), pageSize: z.number().optional(),
82
94
  }, async (args) => get('/accounts', args));
83
- server.tool('crm_get_account', 'Get one account by id.', { accountId: z.number() }, async ({ accountId }) => get(`/accounts/${accountId}`));
84
- server.tool('crm_list_account_contacts', 'List active contacts linked to an account.', { accountId: z.number() }, async ({ accountId }) => get(`/accounts/${accountId}/contacts`));
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 }));
85
101
  if (READWRITE) {
86
102
  server.tool('crm_create_account', 'Create an account. Returns duplicate-candidate warnings unless createAnyway=true.', {
87
103
  name: z.string(), alphaId: z.string().optional(), website: z.string().optional(), phone: z.string().optional(),
@@ -89,14 +105,30 @@ if (READWRITE) {
89
105
  }, async (args) => post('/accounts', args));
90
106
  }
91
107
  // --- CRM: contacts ---
92
- server.tool('crm_search_contacts', 'Search contacts by name/email/phone.', { q: z.string().optional(), accountId: z.number().optional(), email: z.string().optional(), page: z.number().optional(), pageSize: z.number().optional() }, async (args) => get('/contacts/search', args));
93
- server.tool('crm_get_contact', 'Get one contact by id.', { contactId: z.number() }, async ({ contactId }) => get(`/contacts/${contactId}`));
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}`));
94
121
  if (READWRITE) {
95
122
  server.tool('crm_create_contact', 'Create a contact under an account (also creates the active account link).', {
96
123
  accountId: z.number(), firstName: z.string(), lastName: z.string(), email: z.string(),
97
- mobile: z.string().optional(), businessPhone: z.string().optional(), role: z.string().optional(),
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.'),
98
126
  }, async ({ accountId, ...body }) => post(`/accounts/${accountId}/contacts`, body));
99
- server.tool('crm_update_contact', 'Update a contact. Password only applied if supplied.', { contactId: z.number(), firstName: z.string(), lastName: z.string(), email: z.string(), mobile: z.string().optional(), role: z.string().optional(), active: z.boolean().optional() }, async ({ contactId, ...body }) => put(`/contacts/${contactId}`, 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));
100
132
  }
101
133
  // --- Lookups ---
102
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)}`));
@@ -104,10 +136,48 @@ server.tool('lookup_branches', 'List branches.', {}, async () => get('/lookups/b
104
136
  // --- Tasks / time (read) ---
105
137
  server.tool('task_get', 'Get a task by id.', { taskId: z.number() }, async ({ taskId }) => get(`/tasks/${taskId}`));
106
138
  server.tool('task_list_time_entries', 'List time/incidental entries + totals for a task.', { taskId: z.number(), type: z.enum(['time', 'incidentals', 'all']).optional() }, async ({ taskId, type }) => get(`/tasks/${taskId}/time-entries`, { type }));
139
+ server.tool('task_search', 'Search/filter tasks. Supports filtering by customer/account, assigned staff member, who requested it, who created it, call type, 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.', {
140
+ q: z.string().optional().describe('Free text: exact task ID match, or partial match on task name/description.'),
141
+ accountId: z.number().optional().describe('Filter by customer/account/company (CSAID). Maps to TMTask.TMT_CSAID — the account the task was logged for.'),
142
+ loggedForUserId: z.number().optional().describe('Filter by the customer contact who requested/is authorising the task (TMTask.TMTLoggedBy_CSCID).'),
143
+ assignedToUserId: z.number().optional().describe('Filter by the staff member currently assigned to the task (TMTask.TMTAssignedTo_CSCID).'),
144
+ enteredByUserId: z.number().optional().describe('Filter by the staff member who created/logged the task (TMTask.TMTEnteredBY_CSCID).'),
145
+ callType: z.string().optional().describe('Task/call type code: S=Support, P=T&A Project, F=FP Project, H=phoneSERVICE, I=siteSERVICE, A=Account Fee.'),
146
+ status: z.enum(['open', 'closed', 'all']).optional().describe('Task status (TMTStatus). Default: open.'),
147
+ dateFrom: z.string().optional().describe('Date-logged range start (inclusive), e.g. 2026-01-01.'),
148
+ dateTo: z.string().optional().describe('Date-logged range end (inclusive).'),
149
+ page: z.number().optional(), pageSize: z.number().optional(),
150
+ }, async (args) => get('/tasks/search', args));
107
151
  // --- Orders / PM (read) ---
108
152
  server.tool('order_get', 'Get an order header + totals.', { orderId: z.number() }, async ({ orderId }) => get(`/orders/${orderId}`));
109
153
  server.tool('order_list_items', 'List order line items.', { orderId: z.number() }, async ({ orderId }) => get(`/orders/${orderId}/items`));
110
- server.tool('product_search', 'Search the (read-only) product catalog.', { q: z.string(), vendorId: z.number().optional() }, async ({ q, vendorId }) => get('/orders/products/search', { q, vendorId }));
154
+ 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.', {
155
+ 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.'),
156
+ advanced: z.boolean().optional().describe('Widen `q` to also match order notes and line product code/OEM code/descriptions.'),
157
+ accountId: z.number().optional().describe('Filter by customer/account/company (CSAID). Maps to PMOrder.PMO_CSAID.'),
158
+ branchId: z.string().optional().describe('Filter by the branch that owns the order account (CSA_CSBID).'),
159
+ enteredByUserId: z.number().optional().describe('Filter by the staff member who entered/created the order (PMOrder.PMO_CSCID).'),
160
+ authorisedByUserId: z.number().optional().describe('Filter by who authorised the order (PMOrder.PMO_AuthBy_CSCID).'),
161
+ vendorId: z.number().optional().describe('Filter by supplier/vendor account on at least one order line (PMDetails.PMD_CSAID).'),
162
+ receivedByUserId: z.number().optional().describe('Filter by the staff member who received at least one line (PMDetails.PMDRecBy_CSCID).'),
163
+ approvedByUserId: z.number().optional().describe('Filter by the staff member who approved at least one line (PMDetails.PMDApprBy_CSCID).'),
164
+ invoicedByUserId: z.number().optional().describe('Filter by the staff member who recorded a supplier invoice on at least one line (PMDetails.PMDInvBy_CSCID).'),
165
+ returnAuthorisedByUserId: z.number().optional().describe('Filter by the staff member who authorised a return on at least one line (PMDetails.PMDRABy_CSCID).'),
166
+ creditedByUserId: z.number().optional().describe('Filter by the staff member who recorded a supplier credit on at least one line (PMDetails.PMDCdtBy_CSCID).'),
167
+ orderType: z.string().optional().describe('Order type selector code (PMOrder.PMOType).'),
168
+ dateFrom: z.string().optional().describe('Order-date range start (inclusive), e.g. 2026-01-01.'),
169
+ dateTo: z.string().optional().describe('Order-date range end (inclusive).'),
170
+ received: z.enum(['yes', 'no']).optional().describe('Whether at least one line has been received. Not mutually exclusive with `no` — an order can have both received and unreceived lines.'),
171
+ invoiced: z.enum(['yes', 'no']).optional().describe('Whether at least one line has been invoiced. Same "at least one line" semantics as `received`.'),
172
+ returned: z.enum(['yes', 'no']).optional().describe('Whether at least one line has a return reason set. Same "at least one line" semantics as `received`.'),
173
+ page: z.number().optional(), pageSize: z.number().optional(),
174
+ }, async (args) => get('/orders/search', args));
175
+ server.tool('product_search', 'Search the (read-only) product catalog. `q` splits on whitespace and requires every word to match description/code/OEM code.', {
176
+ q: z.string().optional(), vendorId: z.number().optional(),
177
+ manufacturer: z.string().optional().describe('Exact match on PMPManufacturer.'),
178
+ category: z.string().optional().describe('Exact match on PMPProductCategory_ID.'),
179
+ page: z.number().optional(), pageSize: z.number().optional(),
180
+ }, async (args) => get('/orders/products/search', args));
111
181
  async function main() {
112
182
  if (!API_KEY) {
113
183
  console.error('[teamlink-mcp] WARNING: TEAMLINK_API_KEY is not set; all tool calls will fail until it is configured.');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@teamnetwork-nz/teamlink-mcp-server",
3
- "version": "0.3.0",
3
+ "version": "0.5.1",
4
4
  "private": false,
5
5
  "description": "stdio MCP server exposing tools that proxy the TEAMlink REST API",
6
6
  "main": "build/index.js",