@teamnetwork-nz/teamlink-mcp-server 0.6.1 → 0.6.4

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/dist/index.js +17 -13
  2. package/package.json +1 -1
package/dist/index.js CHANGED
@@ -127,35 +127,35 @@ function strictTool(name, description, inputSchema, callback) {
127
127
  }
128
128
  const allowedQueryParams = {
129
129
  '/accounts/search': new Set([
130
- 'mode', 'q', 'csaId', 'accountId', 'alphaId', 'name', 'address', 'phone', 'website',
130
+ 'mode', 'q', 'accountId', 'alphaId', 'name', 'address', 'phone', 'website', 'emailDomain',
131
131
  'exactWebsite', 'isActive', 'isCustomer', 'isProspect', 'isSupplier', 'isBranch',
132
132
  'branchId', 'teamId', 'page', 'pageSize',
133
133
  ]),
134
134
  '/accounts': new Set(['search', 'isActive', 'isCustomer', 'isProspect', 'isSupplier', 'isBranch', 'branchId', 'teamId', 'page', 'pageSize']),
135
135
  '/contacts/search': new Set([
136
136
  'mode', 'q', 'cscId', 'contactId', 'firstName', 'lastName', 'fullName', 'shortName',
137
- 'csaId', 'accountId', 'email', 'mobile', 'businessPhone', 'isActive', 'role', 'page', 'pageSize',
137
+ 'accountId', 'email', 'mobile', 'businessPhone', 'isActive', 'role', 'page', 'pageSize',
138
138
  ]),
139
139
  '/tasks/time-entries/search': new Set(['taskId', 'accountId', 'personId', 'type', 'q', 'dateFrom', 'dateTo', 'page', 'pageSize', 'includeCrm']),
140
140
  '/tasks/search': new Set(['q', 'accountId', 'loggedForUserId', 'assignedToUserId', 'enteredByUserId', 'callType', 'priority', 'status', 'dateFrom', 'dateTo', 'page', 'pageSize']),
141
141
  '/crm/activities/search': new Set(['q', 'accountId', 'assignedToUserId', 'targetContactId', 'enteredByUserId', 'completed', 'dateDueFrom', 'dateDueTo', 'page', 'pageSize']),
142
142
  '/crm/activities/time-entries/search': new Set(['activityId', 'accountId', 'personId', 'q', 'dateFrom', 'dateTo', 'page', 'pageSize']),
143
- '/orders/search': new Set(['q', 'advanced', 'accountId', 'branchId', 'enteredByUserId', 'authorisedByUserId', 'vendorId', 'receivedByUserId', 'approvedByUserId', 'invoicedByUserId', 'returnAuthorisedByUserId', 'creditedByUserId', 'orderType', 'dateFrom', 'dateTo', 'received', 'invoiced', 'returned', 'page', 'pageSize']),
143
+ '/orders/search': new Set(['q', 'advanced', 'invoiceNumber', 'creditReference', 'returnAuthorisationReference', 'customerOrderReference', 'accountId', 'branchId', 'enteredByUserId', 'authorisedByUserId', 'vendorId', 'receivedByUserId', 'approvedByUserId', 'invoicedByUserId', 'returnAuthorisedByUserId', 'creditedByUserId', 'orderType', 'dateFrom', 'dateTo', 'received', 'invoiced', 'returned', 'credited', 'page', 'pageSize']),
144
144
  '/orders/products/search': new Set(['q', 'supplierId', 'vendorId', 'manufacturer', 'category', 'inStock', 'page', 'pageSize']),
145
145
  };
146
146
  // --- Identity ---
147
147
  strictTool('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'));
148
148
  // --- CRM: accounts ---
149
- strictTool('crm_search_accounts', 'Search customer accounts. `csaId` is canonical for CSAccount.CSAID; `accountId` is accepted as a compatibility alias. Default mode is standard: exact case-insensitive matches. Fuzzy mode performs partial text/phone matching and name DIFFERENCE() matching. `isActive` defaults true unless explicitly set.', {
149
+ strictTool('crm_search_accounts', 'Search CRM accounts, including customers, prospects, and suppliers. `accountId` is the canonical public identity. Standard mode uses exact case-insensitive matching except `emailDomain`, which is always partial and domain-normalized. Fuzzy mode performs partial text/phone matching and name DIFFERENCE() matching. Boolean/account filters may be used without a text criterion. `isActive` defaults true unless explicitly set.', {
150
150
  mode: z.enum(['standard', 'fuzzy']).optional().describe('Search mode. standard=exact case-insensitive matching; fuzzy=partial matching plus DIFFERENCE() for names. Defaults to standard.'),
151
- q: z.string().optional().describe('General search value matched against csaId, alphaId, name, address, phone, and website.'),
152
- csaId: z.number().optional().describe('Canonical account primary key (CSAccount.CSAID).'),
153
- accountId: z.number().optional().describe('Compatibility alias for csaId. Prefer csaId.'),
151
+ q: z.string().optional().describe('General search value matched against accountId, alphaId, name, address, phone, website, and emailDomain.'),
152
+ accountId: z.number().optional().describe('Canonical public account identifier. Maps to CSAccount.CSAID in SQL.'),
154
153
  alphaId: z.string().optional(),
155
154
  name: z.string().optional(),
156
155
  address: z.string().optional(),
157
156
  phone: z.string().optional().describe('Phone search; punctuation/spaces are ignored.'),
158
157
  website: z.string().optional(),
158
+ emailDomain: z.string().optional().describe('Partial, case-insensitive domain search across emailDomain and website. Accepts a domain, email address, or URL; scheme and leading www are ignored.'),
159
159
  exactWebsite: z.string().optional().describe('Compatibility alias for website. Prefer website.'),
160
160
  isActive: z.boolean().optional().describe('Defaults to true if omitted.'),
161
161
  isCustomer: z.boolean().optional(),
@@ -176,7 +176,7 @@ strictTool('crm_list_accounts', 'Deprecated compatibility wrapper for listing/fi
176
176
  // and everything linked to it (contacts, orders, tasks, ...) — see lookup_selectors
177
177
  // and crm_search_accounts for how to resolve one. Response `isActive` = CSAActive:
178
178
  // only active accounts are eligible for transactional activity (orders/tasks).
179
- strictTool('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}`));
179
+ strictTool('crm_get_account', 'Get one account by `accountId` (stored as CSAccount.CSAID in SQL). 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().describe('Canonical public account identifier. Maps to CSAccount.CSAID in SQL.') }, async ({ accountId }) => get(`/accounts/${accountId}`));
180
180
  strictTool('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 }));
181
181
  if (READWRITE) {
182
182
  strictTool('crm_create_account', 'Create an account. Returns duplicate-candidate warnings unless createAnyway=true.', {
@@ -192,7 +192,7 @@ if (READWRITE) {
192
192
  // TYPE) — typeFlags.isAdminContact means a client-side admin/accounts contact,
193
193
  // NOT the application admin role (role="A").
194
194
  const roleDescription = 'CSCClass web-app role: A=Administrator, C=Customer, E=Engineer, M=Business Manager, P=Partner, S=Sales, T=Account Manager.';
195
- strictTool('crm_search_contacts', 'Search contacts. `cscId` is canonical for CSContact.CSCID; `contactId` is accepted as a compatibility alias. `csaId` is canonical for account linkage; `accountId` is accepted as a compatibility alias. Default mode is standard: exact case-insensitive matches. Fuzzy mode performs partial matching.', {
195
+ strictTool('crm_search_contacts', 'Search contacts. `cscId` is canonical for CSContact.CSCID; `contactId` is accepted as a compatibility alias. `accountId` is the canonical public name for account linkage and maps to CSAccount.CSAID / CSPivotContactAccount.CSPCA_CSAID in SQL. Default mode is standard: exact case-insensitive matches. Fuzzy mode performs partial matching.', {
196
196
  mode: z.enum(['standard', 'fuzzy']).optional().describe('Search mode. standard=exact case-insensitive matching; fuzzy=partial matching. Defaults to standard.'),
197
197
  q: z.string().optional().describe('General search value matched against cscId/contactId, names, email, mobile, and business phone.'),
198
198
  cscId: z.number().optional().describe('Canonical contact primary key (CSContact.CSCID).'),
@@ -201,8 +201,7 @@ strictTool('crm_search_contacts', 'Search contacts. `cscId` is canonical for CSC
201
201
  lastName: z.string().optional(),
202
202
  fullName: z.string().optional(),
203
203
  shortName: z.string().optional(),
204
- csaId: z.number().optional().describe('Canonical linked account primary key (CSAccount.CSAID / CSPivotContactAccount.CSPCA_CSAID).'),
205
- accountId: z.number().optional().describe('Compatibility alias for csaId. Prefer csaId.'),
204
+ accountId: z.number().optional().describe('Canonical public linked-account identifier. Maps to CSAccount.CSAID / CSPivotContactAccount.CSPCA_CSAID in SQL.'),
206
205
  email: z.string().optional(),
207
206
  mobile: z.string().optional().describe('Mobile phone search; punctuation/spaces are ignored.'),
208
207
  businessPhone: z.string().optional().describe('Business/DDI phone search; punctuation/spaces are ignored.'),
@@ -296,11 +295,15 @@ strictTool('task_search', 'Search/filter tasks. Supports filtering by customer/a
296
295
  page: z.number().optional(), pageSize: z.number().optional(),
297
296
  }, async (args) => get('/tasks/search', args));
298
297
  // --- Orders / PM (read) ---
299
- strictTool('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}`));
298
+ strictTool('order_get', 'Get an order header, totals, and statusFlags. `statusFlags` reports unapproved/unreceived lines, completion, and returns awaiting credit using the same semantics as order_search. `account` is the resale customer, not the supplier. `vendors` contains every distinct supplier from the order lines; `vendor` is populated only for a single-vendor order. Returns account/bill-to and contact actor fields as objects with IDs and names. `orderType` is returned as { code, label } from CSSelectors/OrderType.', { orderId: z.number() }, async ({ orderId }) => get(`/orders/${orderId}`));
300
299
  strictTool('order_list_items', 'List order line items.', { orderId: z.number() }, async ({ orderId }) => get(`/orders/${orderId}/items`));
301
300
  strictTool('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.', {
302
301
  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.'),
303
302
  advanced: z.boolean().optional().describe('Widen `q` to also match order notes and line product code/OEM code/descriptions.'),
303
+ invoiceNumber: z.union([z.string(), z.number()]).transform(String).optional().describe('Exact supplier invoice number. Numeric values are accepted and preserved as reference strings.'),
304
+ creditReference: z.union([z.string(), z.number()]).transform(String).optional().describe('Exact supplier credit reference.'),
305
+ returnAuthorisationReference: z.union([z.string(), z.number()]).transform(String).optional().describe('Exact return-authorisation reference.'),
306
+ customerOrderReference: z.union([z.string(), z.number()]).transform(String).optional().describe('Exact customer order reference.'),
304
307
  accountId: z.number().optional().describe('Filter by customer/account/company (CSAID). Maps to PMOrder.PMO_CSAID.'),
305
308
  branchId: z.string().optional().describe('Filter by the branch that owns the order account (CSA_CSBID).'),
306
309
  enteredByUserId: z.number().optional().describe('Filter by the staff member who entered/created the order (PMOrder.PMO_CSCID).'),
@@ -317,6 +320,7 @@ strictTool('order_search', 'Search/filter orders. Supports filtering by customer
317
320
  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.'),
318
321
  invoiced: z.enum(['yes', 'no']).optional().describe('Whether at least one line has been invoiced. Same "at least one line" semantics as `received`.'),
319
322
  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`.'),
323
+ credited: z.enum(['yes', 'no']).optional().describe('Whether at least one line has supplier credit recorded.'),
320
324
  page: z.number().optional(), pageSize: z.number().optional(),
321
325
  }, async (args) => get('/orders/search', args));
322
326
  strictTool('product_search', 'Search the read-only product catalog. `q` splits on whitespace and requires every word to match as a substring in code, OEM code, description, manufacturer, or category. Filter by supplier/vendor and stock availability.', {
@@ -330,7 +334,7 @@ strictTool('product_search', 'Search the read-only product catalog. `q` splits o
330
334
  }, async (args) => get('/orders/products/search', args));
331
335
  function createConfiguredServer() {
332
336
  const server = new McpServer({ name: '@teamnetwork-nz/teamlink-mcp-server', version: pkgVersion() }, {
333
- instructions: 'TEAMlink business operations MCP server supporting stdio and HTTP. Read-only by default; mutation tools are available only when TEAMLINK_READWRITE=true. Use the most specific search filters available and treat customer, order, invoice, and credential data as sensitive.',
337
+ instructions: 'TEAMlink business operations MCP server supporting stdio and HTTP. Read-only by default; mutation tools are available only when TEAMLINK_READWRITE=true. Always use `accountId` for the public account/customer identifier; it maps to CSAID and *_CSAID columns in SQL. Use the most specific search filters available and treat customer, order, invoice, and credential data as sensitive.',
334
338
  });
335
339
  for (const register of registrations)
336
340
  register(server);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@teamnetwork-nz/teamlink-mcp-server",
3
- "version": "0.6.1",
3
+ "version": "0.6.4",
4
4
  "private": false,
5
5
  "description": "MCP server exposing TEAMlink REST API tools over stdio and Streamable HTTP",
6
6
  "main": "dist/index.js",