@teamnetwork-nz/teamlink-mcp-server 0.6.7 → 0.6.8

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/.env.example ADDED
@@ -0,0 +1,24 @@
1
+ # Sanitised template: no live credentials or identities.
2
+ # See README.md for requirements, defaults and .env loading behaviour.
3
+ # Replace required/alternative placeholders privately; uncomment optional settings only when needed.
4
+
5
+ # URL of the running teamlink-api service; trailing slash is removed.
6
+ # TEAMLINK_API_BASE=http://localhost:3100
7
+ # Staff-allocated CSCApiKey sent as X-API-Key; visibility is enforced by the API.
8
+ TEAMLINK_API_KEY=<set-privately>
9
+ # Comma-separated Host allowlist required for non-loopback HTTP; use the public hostnames accepted by the listener.
10
+ # TEAMLINK_HTTP_ALLOWED_HOSTS=<set-privately>
11
+ # Comma-separated browser Origin allowlist; configure when browser clients need access.
12
+ # TEAMLINK_HTTP_ALLOWED_ORIGINS=<set-privately>
13
+ # Private bearer secret required for non-loopback HTTP; clients send Authorization: Bearer <secret>.
14
+ # TEAMLINK_HTTP_BEARER_TOKEN=<set-privately>
15
+ # Listener bind address. Non-loopback binding requires a bearer token and explicit allowed hosts.
16
+ # TEAMLINK_HTTP_HOST=127.0.0.1
17
+ # Maximum HTTP request body; integer 1–16777216 bytes.
18
+ # TEAMLINK_HTTP_MAX_BODY_BYTES=1048576
19
+ # HTTP listener port; integer 1–65535.
20
+ # TEAMLINK_HTTP_PORT=3000
21
+ # Only true enables mutation tools; read-only is the default. Review each operation before use.
22
+ # TEAMLINK_READWRITE=false
23
+ # stdio or http; HTTP serves /mcp and GET /health.
24
+ # TEAMLINK_TRANSPORT=stdio
package/README.md ADDED
@@ -0,0 +1,98 @@
1
+ # TEAMlink MCP Server
2
+
3
+ `@teamnetwork-nz/teamlink-mcp-server` exposes the TEAMlink REST API to MCP agents over stdio or Streamable HTTP. It supports account/contact discovery, tasks, fees, CRM activities, orders, products and selector lookups. Reads are enabled by default; account/contact mutation tools require `TEAMLINK_READWRITE=true`.
4
+
5
+ ## Prerequisites and setup
6
+
7
+ Use Node.js 20 or later, a reachable `teamlink-api` deployment, and a staff-allocated API key with the intended permissions. The MCP server proxies API calls; the API controls visibility and business rules. The separate `teamlink-api` package must be configured and running first.
8
+
9
+ ```powershell
10
+ npm install
11
+ Copy-Item .env.example .env
12
+ # Configure required variables privately before starting.
13
+ npm run build
14
+ npm start
15
+ ```
16
+
17
+ The environment reference below lists every runtime setting. For an installed package, launch `npx -y @teamnetwork-nz/teamlink-mcp-server` with the same process environment.
18
+
19
+ ## MCP client configuration
20
+
21
+ ```json
22
+ {
23
+ "mcpServers": {
24
+ "teamlink": {
25
+ "command": "node",
26
+ "args": ["C:/path/to/TN-MCP-Servers/mcp/dist/index.js"],
27
+ "env": {
28
+ "TEAMLINK_API_BASE": "https://teamlink-api.example.invalid",
29
+ "TEAMLINK_API_KEY": "<set-privately>",
30
+ "TEAMLINK_READWRITE": "false"
31
+ }
32
+ }
33
+ }
34
+ }
35
+ ```
36
+
37
+ The example URL is deliberately non-routable. Configure your own service URL and key privately. For HTTP set `TEAMLINK_TRANSPORT=http`; connect the client to `/mcp` and use `/health` for probes.
38
+
39
+ ## Tools and identifiers
40
+
41
+ | Area | Tools and usage |
42
+ |---|---|
43
+ | Identity | `teamlink_whoami` verifies caller scope. |
44
+ | Accounts and contacts | Search first; use returned canonical `accountId` and contact IDs for detail and linked queries. |
45
+ | Lookups | `lookup_selectors`, `lookup_branches` discover accepted codes and branch IDs. |
46
+ | Tasks, fees and CRM activities | Filter search tools by account, person and date, then fetch details using returned IDs. |
47
+ | Orders and products | Search headers/products, then get an order and its line items. Supplier and resale-customer identities are distinct. |
48
+ | Writes | Create accounts/contacts and update contacts only when explicitly enabled. Account creation may report duplicate candidates. |
49
+
50
+ Do not substitute alpha IDs, person IDs or branch IDs for `accountId`. Preserve response warnings, pagination and status information; tool errors are not empty search results.
51
+
52
+ ## Development
53
+
54
+ ```powershell
55
+ npm run typecheck
56
+ npm test
57
+ ```
58
+
59
+ <!-- BEGIN MCP configuration reference -->
60
+ ## Environment variable reference
61
+
62
+ The server automatically loads `.env` from its working directory; environment variables already set by the client take precedence.
63
+
64
+ Copy `.env.example` for variable names and safe placeholders. Replace required placeholders privately. Optional variables should be omitted unless needed; an empty value may override a default. Never commit credentials, real identities, device profiles, exports, or logs.
65
+
66
+ | Variable | Required | Default | Purpose and accepted values |
67
+ |---|---|---|---|
68
+ | `TEAMLINK_API_BASE` | No | `http://localhost:3100` | URL of the running teamlink-api service; trailing slash is removed. |
69
+ | `TEAMLINK_API_KEY` | Yes | `unset` | Staff-allocated CSCApiKey sent as X-API-Key; visibility is enforced by the API. |
70
+ | `TEAMLINK_HTTP_ALLOWED_HOSTS` | Conditional | `unset` | Comma-separated Host allowlist required for non-loopback HTTP; use the public hostnames accepted by the listener. |
71
+ | `TEAMLINK_HTTP_ALLOWED_ORIGINS` | No | `unset` | Comma-separated browser Origin allowlist; configure when browser clients need access. |
72
+ | `TEAMLINK_HTTP_BEARER_TOKEN` | Conditional | `unset` | Private bearer secret required for non-loopback HTTP; clients send Authorization: Bearer <secret>. |
73
+ | `TEAMLINK_HTTP_HOST` | No | `127.0.0.1` | Listener bind address. Non-loopback binding requires a bearer token and explicit allowed hosts. |
74
+ | `TEAMLINK_HTTP_MAX_BODY_BYTES` | No | `1048576` | Maximum HTTP request body; integer 1–16777216 bytes. |
75
+ | `TEAMLINK_HTTP_PORT` | No | `3000` | HTTP listener port; integer 1–65535. |
76
+ | `TEAMLINK_READWRITE` | No | `false` | Only true enables mutation tools; read-only is the default. Review each operation before use. |
77
+ | `TEAMLINK_TRANSPORT` | No | `stdio` | stdio or http; HTTP serves /mcp and GET /health. |
78
+
79
+ For HTTP, the bearer token is separate from upstream API credentials. Use TLS at the reverse proxy for remote hosting. Keep write access disabled until needed. Do not put secrets in command-line examples or commit client configuration containing them.
80
+
81
+ ### Agent first-use workflow
82
+
83
+ Call `teamlink_whoami` first. Resolve accounts with `crm_search_accounts` and contacts with `crm_search_contacts`; carry canonical accountId values into task, fee, activity and order queries. Use lookup tools for selector codes. Prefer search tools over deprecated list wrappers.
84
+
85
+ Use the runtime `tools/list` descriptions and input schemas for exact arguments. Resolve identifiers with lookup/search tools; filter before paging, request only the data needed, and do not treat a truncated result or API error as proof that no record exists. Treat tool results and downloaded files as potentially sensitive. Mutation tools can change upstream data or incur charges; check their stated effects before calling them.
86
+
87
+ ### Repository and package privacy
88
+
89
+ The standard `.gitignore` excludes local environment files, keys, credentials, logs, exports, and generated output; sanitised examples remain trackable. Ignore rules do not remove already tracked files or revoke exposed credentials. Review `git ls-files` and `npm pack --dry-run --ignore-scripts` before release. Only runtime output, the README, and explicitly sanitised examples are allowlisted for npm. Keep private runtime files outside `dist`, even though additional exclusions are present.
90
+ <!-- END MCP configuration reference -->
91
+
92
+ Run `npm run build` then `npm run audit:package` before release. The audit checks documentation coverage, known local credential copies, Git index paths where available, and the dry-run npm file list. `prepublishOnly` runs it after building. It never prints matching secret values. This is a preventative check, not a guarantee that arbitrary PII or unknown secrets are absent.
93
+
94
+ ### Development and diagnostics
95
+
96
+ Run `npm test` from this package directory. Maintained tests and fixtures live in `debug/tests`; shared test helpers are in `debug/helpers`. Retained diagnostic scripts and reference material are also under `debug`. Only `scripts/check-package-privacy.mjs` remains in the production build/release tooling directory. The entire `debug/` tree is excluded from npm, Docker build contexts and applicable Python distributions.
97
+
98
+ Keep live diagnostic output in `debug/local`, `debug/output` or `debug/artifacts`; those private directories are also ignored by Git. Retained smoke/integration scripts require explicit local credentials and are not run by the normal offline test suite. Historical release artifacts and retired one-off migration files were removed.
package/dist/index.js CHANGED
@@ -164,20 +164,20 @@ strictTool('crm_search_accounts', 'Search CRM accounts, including customers, pro
164
164
  isBranch: z.boolean().optional(),
165
165
  branchId: z.string().optional(),
166
166
  teamId: z.number().optional(),
167
- page: z.number().optional(),
168
- pageSize: z.number().optional(),
167
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."),
168
+ pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
169
169
  }, async (args) => get('/accounts/search', args));
170
170
  strictTool('crm_list_accounts', 'Deprecated compatibility wrapper for listing/filtering accounts. Prefer crm_search_accounts for new work. `isActive` filters on CSAActive — only active accounts are eligible for transactional activity (orders/tasks).', {
171
171
  search: z.string().optional(), isActive: z.boolean().optional(), isCustomer: z.boolean().optional(), isProspect: z.boolean().optional(),
172
172
  isSupplier: z.boolean().optional(), isBranch: z.boolean().optional(), branchId: z.string().optional(), teamId: z.number().optional(),
173
- page: z.number().optional(), pageSize: z.number().optional(),
173
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."), pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
174
174
  }, async (args) => get('/accounts', args));
175
175
  // `accountId` (CSAID) is the absolute source-of-truth identity key for this account
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
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
- 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 }));
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().describe("Canonical account ID from crm_search_accounts; do not substitute an alpha ID or contact ID."), 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.', {
183
183
  name: z.string(), alphaId: z.string().optional(), website: z.string().optional(), phone: z.string().optional(),
@@ -207,16 +207,16 @@ strictTool('crm_search_contacts', 'Search contacts. `cscId` is canonical for CSC
207
207
  businessPhone: z.string().optional().describe('Business/DDI phone search; punctuation/spaces are ignored.'),
208
208
  isActive: z.boolean().optional().describe('Filter by CSPivotContactAccount.CSPCA_Active when pivot context is joined.'),
209
209
  role: z.string().optional().describe(roleDescription),
210
- page: z.number().optional(), pageSize: z.number().optional(),
210
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."), pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
211
211
  }, async (args) => get('/contacts/search', args));
212
- strictTool('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. Credentials are never returned.', { contactId: z.number() }, async ({ contactId }) => get(`/contacts/${contactId}`));
212
+ strictTool('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. Credentials are never returned.', { contactId: z.number().describe("Contact identifier returned by crm_search_contacts.") }, async ({ contactId }) => get(`/contacts/${contactId}`));
213
213
  if (READWRITE) {
214
214
  strictTool('crm_create_contact', 'Create a contact under an account (also creates the active account link). Role is gated by a staff ' +
215
215
  'hierarchy (A > M > E > {S,T,P} > C): the calling key\'s own role must outrank the role being assigned, ' +
216
216
  'or the call 403s (role_hierarchy_violation) — Admin keys are unrestricted, everyone else can only assign ' +
217
217
  'a role strictly below their own tier (no same-tier assignment either, e.g. an Engineer key cannot create ' +
218
218
  'another Engineer contact).', {
219
- accountId: z.number(), firstName: z.string(), lastName: z.string(), email: z.string(),
219
+ accountId: z.number().describe("Canonical account ID from crm_search_accounts; do not substitute an alpha ID or contact ID."), firstName: z.string(), lastName: z.string(), email: z.string(),
220
220
  mobile: z.string().optional(), businessPhone: z.string().optional(),
221
221
  role: z.string().optional().describe(roleDescription + ' Only settable for branch accounts; forced to C otherwise.'),
222
222
  }, async ({ accountId, ...body }) => post(`/accounts/${accountId}/contacts`, body));
@@ -225,14 +225,14 @@ if (READWRITE) {
225
225
  'by the same staff hierarchy as crm_create_contact (A > M > E > {S,T,P} > C, Admin unrestricted) — the call ' +
226
226
  '403s (role_hierarchy_violation) if the calling key cannot manage either one. Credentials are not settable ' +
227
227
  'through contact tools or endpoints.', {
228
- contactId: z.number(), firstName: z.string(), lastName: z.string(), email: z.string(), mobile: z.string().optional(),
228
+ contactId: z.number().describe("Contact identifier returned by crm_search_contacts."), firstName: z.string(), lastName: z.string(), email: z.string(), mobile: z.string().optional(),
229
229
  role: z.string().optional().describe(roleDescription),
230
230
  active: z.boolean().optional().describe('Sets CSPCA_Active (pivot) for the account context, not CSCActive.'),
231
231
  }, async ({ contactId, ...body }) => put(`/contacts/${contactId}`, body));
232
232
  }
233
233
  // --- Lookups ---
234
- strictTool('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)}`));
235
- strictTool('lookup_branches', 'List branches.', {}, async () => get('/lookups/branches'));
234
+ strictTool('lookup_selectors', 'Get options for a CSSelectors list (Industry, Source, SalesStatus, OrderType, IncomeCat, City, Country, ...).', { selectorClass: z.string().describe("Selector category such as Industry, Source, SalesStatus or OrderType; use returned codes in related operations.") }, async ({ selectorClass }) => get(`/lookups/selectors/${encodeURIComponent(selectorClass)}`));
235
+ strictTool('lookup_branches', 'List branch identifiers and labels before filtering account, task or order searches by branchId. Use returned branch IDs; these are distinct from accountId.', {}, async () => get('/lookups/branches'));
236
236
  // --- Account fees (read) ---
237
237
  strictTool('fee_get', 'Get one account fee record from vw_CSFee by feeId. Returns the account, logged-by and assigned-to people, task snapshot, time/income details, quantity/unit cost, and action metadata.', { feeId: z.number().describe('Fee record ID (CSFee.CSFeeId).') }, async ({ feeId }) => get(`/fees/${feeId}`));
238
238
  strictTool('fee_search', 'Search the read-only account fee view (vw_CSFee). Filter by account, logged-by or assigned-to person, fee period, action type, start-date range, or free text. Results are newest-starting first.', {
@@ -244,8 +244,8 @@ strictTool('fee_search', 'Search the read-only account fee view (vw_CSFee). Filt
244
244
  actionType: z.string().optional().describe('Exact CSFee_ActionType value.'),
245
245
  dateFrom: z.string().optional().describe('Fee start-date range start (inclusive), e.g. 2026-01-01.'),
246
246
  dateTo: z.string().optional().describe('Fee start-date range end (inclusive).'),
247
- page: z.number().optional(),
248
- pageSize: z.number().optional(),
247
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."),
248
+ pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
249
249
  }, async (args) => get('/fees/search', args));
250
250
  // --- CRM: sales activities / time (read) ---
251
251
  strictTool('crm_activity_get', 'Get one CRM sales activity by id (CRMActivity.CRMAID). Returns account, enteredBy, assignedTo, targetContact, type/subType selector labels, due/completed dates, and completed boolean.', { activityId: z.number().describe('CRM activity ID (CRMActivity.CRMAID).') }, async ({ activityId }) => get(`/crm/activities/${activityId}`));
@@ -258,8 +258,8 @@ strictTool('crm_activity_search', 'Search/filter CRM sales activities (CRMActivi
258
258
  completed: z.boolean().optional().describe('true = CRMADateCompleted is not null; false = CRMADateCompleted is null; omitted = all.'),
259
259
  dateDueFrom: z.string().optional().describe('Due-date range start (CRMActivity.CRMADateDue), e.g. 2026-01-01.'),
260
260
  dateDueTo: z.string().optional().describe('Due-date range end (CRMActivity.CRMADateDue).'),
261
- page: z.number().optional(),
262
- pageSize: z.number().optional(),
261
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."),
262
+ pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
263
263
  }, async (args) => get('/crm/activities/search', args));
264
264
  strictTool('crm_activity_list_time_entries', 'List time entries + totals for a CRM sales activity. CRM activity time is TMActivity with TMAType=A and TMA_CRMAID=CRMActivity.CRMAID.', {
265
265
  activityId: z.number().describe('CRM activity ID (CRMActivity.CRMAID / TMActivity.TMA_CRMAID).'),
@@ -272,11 +272,11 @@ strictTool('crm_activity_search_time_entries', 'Search CRM sales activity time e
272
272
  q: z.string().optional().describe('Partial text match against TMActivity.TMADescription, TMActivity.TMAInternal, or CRMActivity.CRMADescription.'),
273
273
  dateFrom: z.string().optional().describe('Activity time-entry date range start (TMActivity.TMADate), e.g. 2026-01-01.'),
274
274
  dateTo: z.string().optional().describe('Activity time-entry date range end (TMActivity.TMADate).'),
275
- page: z.number().optional(),
276
- pageSize: z.number().optional(),
275
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."),
276
+ pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
277
277
  }, async (args) => get('/crm/activities/time-entries/search', args));
278
278
  // --- Tasks / time (read) ---
279
- strictTool('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}`));
279
+ strictTool('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().describe("Task identifier returned by task_search.") }, async ({ taskId }) => get(`/tasks/${taskId}`));
280
280
  strictTool('task_list_time_entries', 'List time/incidental entries + totals for a task. Can filter by staff person who performed the work (TMActivity.TMA_CSCID). Response `totals` (and each row) split chargeable/OT hours into a normal figure plus a `chargeableHoursBranch`/`otHoursBranch` (and per-row `isBranch`) subtotal when the task\'s account is branch-flagged (CSAccount.CSABranch=\'Y\'): that work is productive but never billed, so it\'s reported separately from the billable total rather than folded into it.', {
281
281
  taskId: z.number().describe('Task ID (TMTask.TMTID / TMActivity.TMA_TMTID).'),
282
282
  personId: z.number().optional().describe('Filter by staff person who performed the work (TMActivity.TMA_CSCID).'),
@@ -291,8 +291,8 @@ strictTool('task_search_time_entries', 'Search task activity/time and incidental
291
291
  dateFrom: z.string().optional().describe('Activity date range start (TMActivity.TMADate), e.g. 2026-01-01. Use this exact parameter name, not fromDate.'),
292
292
  dateTo: z.string().optional().describe('Activity date range end (TMActivity.TMADate). Use this exact parameter name, not toDate.'),
293
293
  includeCrm: z.boolean().optional().describe('Also include CRM sales-activity time entries (TMAType=A) in the results and totals, merged and sorted alongside task time. Ignored when taskId is set. Defaults to false (task time only).'),
294
- page: z.number().optional(),
295
- pageSize: z.number().optional(),
294
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."),
295
+ pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
296
296
  }, async (args) => get('/tasks/time-entries/search', args));
297
297
  strictTool('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.', {
298
298
  q: z.string().optional().describe('Free text: exact task ID match, or partial match on task name/description.'),
@@ -305,11 +305,11 @@ strictTool('task_search', 'Search/filter tasks. Supports filtering by customer/a
305
305
  status: z.enum(['open', 'closed', 'all']).optional().describe('Task status (TMTStatus). Default: open.'),
306
306
  dateFrom: z.string().optional().describe('Date-logged range start (inclusive), e.g. 2026-01-01.'),
307
307
  dateTo: z.string().optional().describe('Date-logged range end (inclusive).'),
308
- page: z.number().optional(), pageSize: z.number().optional(),
308
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."), pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
309
309
  }, async (args) => get('/tasks/search', args));
310
310
  // --- Orders / PM (read) ---
311
- 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}`));
312
- strictTool('order_list_items', 'List order line items.', { orderId: z.number() }, async ({ orderId }) => get(`/orders/${orderId}/items`));
311
+ 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().describe("Order identifier returned by order_search.") }, async ({ orderId }) => get(`/orders/${orderId}`));
312
+ strictTool('order_list_items', 'List line items for orderId returned by order_search. Use order_get for header totals/status and this tool for individual products, quantities and line-level details.', { orderId: z.number().describe("Order identifier returned by order_search.") }, async ({ orderId }) => get(`/orders/${orderId}/items`));
313
313
  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.', {
314
314
  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.'),
315
315
  advanced: z.boolean().optional().describe('Widen `q` to also match order notes and line product code/OEM code/descriptions.'),
@@ -334,7 +334,7 @@ strictTool('order_search', 'Search/filter orders. Supports filtering by customer
334
334
  invoiced: z.enum(['yes', 'no']).optional().describe('Whether at least one line has been invoiced. Same "at least one line" semantics as `received`.'),
335
335
  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`.'),
336
336
  credited: z.enum(['yes', 'no']).optional().describe('Whether at least one line has supplier credit recorded.'),
337
- page: z.number().optional(), pageSize: z.number().optional(),
337
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."), pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
338
338
  }, async (args) => get('/orders/search', args));
339
339
  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.', {
340
340
  q: z.string().optional(),
@@ -343,7 +343,7 @@ strictTool('product_search', 'Search the read-only product catalog. `q` splits o
343
343
  manufacturer: z.string().optional().describe('Exact match on PMPManufacturer.'),
344
344
  category: z.string().optional().describe('Exact match on PMPProductCategory_ID.'),
345
345
  inStock: z.boolean().optional().describe('true = PMPOnHand > 0; false = no stock on hand.'),
346
- page: z.number().optional(), pageSize: z.number().optional(),
346
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."), pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
347
347
  }, async (args) => get('/orders/products/search', args));
348
348
  function createConfiguredServer() {
349
349
  const server = new McpServer({ name: '@teamnetwork-nz/teamlink-mcp-server', version: pkgVersion() }, {
package/package.json CHANGED
@@ -1,34 +1,39 @@
1
- {
2
- "name": "@teamnetwork-nz/teamlink-mcp-server",
3
- "version": "0.6.7",
4
- "private": false,
5
- "description": "MCP server exposing TEAMlink REST API tools over stdio and Streamable HTTP",
6
- "main": "dist/index.js",
7
- "type": "module",
8
- "bin": {
9
- "teamlink-mcp-server": "dist/index.js"
10
- },
11
- "files": [
12
- "dist"
13
- ],
14
- "scripts": {
15
- "build": "tsc",
16
- "test": "npm run build && node --test tests/*.test.mjs",
17
- "start": "node dist/index.js",
18
- "dev": "tsc --watch",
19
- "typecheck": "tsc --noEmit"
20
- },
21
- "dependencies": {
22
- "@modelcontextprotocol/sdk": "^1.32.2",
23
- "axios": "^1.4.0",
24
- "dotenv": "^16.0.3",
25
- "zod": "^4.6.7"
26
- },
27
- "devDependencies": {
28
- "@types/node": "^20.4.2",
29
- "typescript": "^5.9.3"
30
- },
31
- "engines": {
32
- "node": ">=20"
33
- }
34
- }
1
+ {
2
+ "name": "@teamnetwork-nz/teamlink-mcp-server",
3
+ "version": "0.6.8",
4
+ "private": false,
5
+ "description": "MCP server exposing TEAMlink REST API tools over stdio and Streamable HTTP",
6
+ "main": "dist/index.js",
7
+ "type": "module",
8
+ "bin": {
9
+ "teamlink-mcp-server": "dist/index.js"
10
+ },
11
+ "files": [
12
+ "dist/**/*.js",
13
+ "dist/**/*.d.ts",
14
+ "README.md",
15
+ ".env.example"
16
+ ],
17
+ "scripts": {
18
+ "build": "tsc",
19
+ "test": "npm run build && node --test debug/tests/*.test.mjs",
20
+ "start": "node dist/index.js",
21
+ "dev": "tsc --watch",
22
+ "typecheck": "tsc --noEmit",
23
+ "audit:package": "node scripts/check-package-privacy.mjs",
24
+ "prepublishOnly": "npm run build && npm run audit:package"
25
+ },
26
+ "dependencies": {
27
+ "@modelcontextprotocol/sdk": "^1.32.2",
28
+ "axios": "^1.4.0",
29
+ "dotenv": "^16.0.3",
30
+ "zod": "^4.6.7"
31
+ },
32
+ "devDependencies": {
33
+ "@types/node": "^20.4.2",
34
+ "typescript": "^5.9.3"
35
+ },
36
+ "engines": {
37
+ "node": ">=20"
38
+ }
39
+ }
package/dist/index.js.map DELETED
@@ -1 +0,0 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}