@teamnetwork-nz/teamlink-mcp-server 0.6.7 → 0.7.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/.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,100 @@
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
+ Every tool accepts optional `outputFormat: "json"`. Set it when the result must be valid JSON text with no Markdown wrapper. When omitted, the existing result formatting is used. The option is handled by the MCP server and is never sent as a TEAMlink API parameter.
53
+
54
+ ## Development
55
+
56
+ ```powershell
57
+ npm run typecheck
58
+ npm test
59
+ ```
60
+
61
+ <!-- BEGIN MCP configuration reference -->
62
+ ## Environment variable reference
63
+
64
+ The server automatically loads `.env` from its working directory; environment variables already set by the client take precedence.
65
+
66
+ 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.
67
+
68
+ | Variable | Required | Default | Purpose and accepted values |
69
+ |---|---|---|---|
70
+ | `TEAMLINK_API_BASE` | No | `http://localhost:3100` | URL of the running teamlink-api service; trailing slash is removed. |
71
+ | `TEAMLINK_API_KEY` | Yes | `unset` | Staff-allocated CSCApiKey sent as X-API-Key; visibility is enforced by the API. |
72
+ | `TEAMLINK_HTTP_ALLOWED_HOSTS` | Conditional | `unset` | Comma-separated Host allowlist required for non-loopback HTTP; use the public hostnames accepted by the listener. |
73
+ | `TEAMLINK_HTTP_ALLOWED_ORIGINS` | No | `unset` | Comma-separated browser Origin allowlist; configure when browser clients need access. |
74
+ | `TEAMLINK_HTTP_BEARER_TOKEN` | Conditional | `unset` | Private bearer secret required for non-loopback HTTP; clients send Authorization: Bearer <secret>. |
75
+ | `TEAMLINK_HTTP_HOST` | No | `127.0.0.1` | Listener bind address. Non-loopback binding requires a bearer token and explicit allowed hosts. |
76
+ | `TEAMLINK_HTTP_MAX_BODY_BYTES` | No | `1048576` | Maximum HTTP request body; integer 1–16777216 bytes. |
77
+ | `TEAMLINK_HTTP_PORT` | No | `3000` | HTTP listener port; integer 1–65535. |
78
+ | `TEAMLINK_READWRITE` | No | `false` | Only true enables mutation tools; read-only is the default. Review each operation before use. |
79
+ | `TEAMLINK_TRANSPORT` | No | `stdio` | stdio or http; HTTP serves /mcp and GET /health. |
80
+
81
+ 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.
82
+
83
+ ### Agent first-use workflow
84
+
85
+ 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.
86
+
87
+ 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.
88
+
89
+ ### Repository and package privacy
90
+
91
+ 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.
92
+ <!-- END MCP configuration reference -->
93
+
94
+ 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.
95
+
96
+ ### Development and diagnostics
97
+
98
+ 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.
99
+
100
+ 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
@@ -121,8 +121,27 @@ function strictTool(name, description, inputSchema, callback) {
121
121
  registrations.push((server) => {
122
122
  server.registerTool(name, {
123
123
  description,
124
- inputSchema: z.object(inputSchema).strict(),
125
- }, callback);
124
+ inputSchema: z.object({
125
+ ...inputSchema,
126
+ outputFormat: z.enum(['json']).optional().describe('When set to "json", return the result as valid JSON text. Omit to keep the default response.'),
127
+ }).strict(),
128
+ }, async (args, extra) => {
129
+ const { outputFormat, ...toolArgs } = args;
130
+ const result = await callback(toolArgs, extra);
131
+ if (outputFormat !== 'json' || result.isError)
132
+ return result;
133
+ const formatted = result.content.map((item) => {
134
+ if (item.type !== 'text')
135
+ return item;
136
+ try {
137
+ return { ...item, text: JSON.stringify(JSON.parse(item.text), null, 2) };
138
+ }
139
+ catch {
140
+ return { ...item, text: JSON.stringify(item.text) };
141
+ }
142
+ });
143
+ return { ...result, content: formatted };
144
+ });
126
145
  });
127
146
  }
128
147
  const allowedQueryParams = {
@@ -164,20 +183,20 @@ strictTool('crm_search_accounts', 'Search CRM accounts, including customers, pro
164
183
  isBranch: z.boolean().optional(),
165
184
  branchId: z.string().optional(),
166
185
  teamId: z.number().optional(),
167
- page: z.number().optional(),
168
- pageSize: z.number().optional(),
186
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."),
187
+ pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
169
188
  }, async (args) => get('/accounts/search', args));
170
189
  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
190
  search: z.string().optional(), isActive: z.boolean().optional(), isCustomer: z.boolean().optional(), isProspect: z.boolean().optional(),
172
191
  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(),
192
+ 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
193
  }, async (args) => get('/accounts', args));
175
194
  // `accountId` (CSAID) is the absolute source-of-truth identity key for this account
176
195
  // and everything linked to it (contacts, orders, tasks, ...) — see lookup_selectors
177
196
  // and crm_search_accounts for how to resolve one. Response `isActive` = CSAActive:
178
197
  // only active accounts are eligible for transactional activity (orders/tasks).
179
198
  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 }));
199
+ 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
200
  if (READWRITE) {
182
201
  strictTool('crm_create_account', 'Create an account. Returns duplicate-candidate warnings unless createAnyway=true.', {
183
202
  name: z.string(), alphaId: z.string().optional(), website: z.string().optional(), phone: z.string().optional(),
@@ -192,7 +211,7 @@ if (READWRITE) {
192
211
  // TYPE) — typeFlags.isAdminContact means a client-side admin/accounts contact,
193
212
  // NOT the application admin role (role="A").
194
213
  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. `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.', {
214
+ strictTool('crm_search_contacts', 'Search contacts. Searches default to active account links (CSPCA_Active = 1), except an exact cscId/contactId lookup, which returns the contact regardless of link status and reports isActive. Account-scoped searches remain active-only by default. Set isActive=false to explicitly search inactive links. Related-object details (such as orders) can include inactive 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
215
  mode: z.enum(['standard', 'fuzzy']).optional().describe('Search mode. standard=exact case-insensitive matching; fuzzy=partial matching. Defaults to standard.'),
197
216
  q: z.string().optional().describe('General search value matched against cscId/contactId, names, email, mobile, and business phone.'),
198
217
  cscId: z.number().optional().describe('Canonical contact primary key (CSContact.CSCID).'),
@@ -205,18 +224,18 @@ strictTool('crm_search_contacts', 'Search contacts. `cscId` is canonical for CSC
205
224
  email: z.string().optional(),
206
225
  mobile: z.string().optional().describe('Mobile phone search; punctuation/spaces are ignored.'),
207
226
  businessPhone: z.string().optional().describe('Business/DDI phone search; punctuation/spaces are ignored.'),
208
- isActive: z.boolean().optional().describe('Filter by CSPivotContactAccount.CSPCA_Active when pivot context is joined.'),
227
+ isActive: z.boolean().optional().describe('Defaults to true for account or general searches. Exact cscId/contactId lookups include either status by default and report it. Set false to search inactive links explicitly.'),
209
228
  role: z.string().optional().describe(roleDescription),
210
- page: z.number().optional(), pageSize: z.number().optional(),
229
+ 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
230
  }, 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}`));
231
+ 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
232
  if (READWRITE) {
214
233
  strictTool('crm_create_contact', 'Create a contact under an account (also creates the active account link). Role is gated by a staff ' +
215
234
  'hierarchy (A > M > E > {S,T,P} > C): the calling key\'s own role must outrank the role being assigned, ' +
216
235
  'or the call 403s (role_hierarchy_violation) — Admin keys are unrestricted, everyone else can only assign ' +
217
236
  'a role strictly below their own tier (no same-tier assignment either, e.g. an Engineer key cannot create ' +
218
237
  'another Engineer contact).', {
219
- accountId: z.number(), firstName: z.string(), lastName: z.string(), email: z.string(),
238
+ 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
239
  mobile: z.string().optional(), businessPhone: z.string().optional(),
221
240
  role: z.string().optional().describe(roleDescription + ' Only settable for branch accounts; forced to C otherwise.'),
222
241
  }, async ({ accountId, ...body }) => post(`/accounts/${accountId}/contacts`, body));
@@ -225,14 +244,14 @@ if (READWRITE) {
225
244
  'by the same staff hierarchy as crm_create_contact (A > M > E > {S,T,P} > C, Admin unrestricted) — the call ' +
226
245
  '403s (role_hierarchy_violation) if the calling key cannot manage either one. Credentials are not settable ' +
227
246
  'through contact tools or endpoints.', {
228
- contactId: z.number(), firstName: z.string(), lastName: z.string(), email: z.string(), mobile: z.string().optional(),
247
+ 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
248
  role: z.string().optional().describe(roleDescription),
230
249
  active: z.boolean().optional().describe('Sets CSPCA_Active (pivot) for the account context, not CSCActive.'),
231
250
  }, async ({ contactId, ...body }) => put(`/contacts/${contactId}`, body));
232
251
  }
233
252
  // --- 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'));
253
+ 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)}`));
254
+ 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
255
  // --- Account fees (read) ---
237
256
  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
257
  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 +263,8 @@ strictTool('fee_search', 'Search the read-only account fee view (vw_CSFee). Filt
244
263
  actionType: z.string().optional().describe('Exact CSFee_ActionType value.'),
245
264
  dateFrom: z.string().optional().describe('Fee start-date range start (inclusive), e.g. 2026-01-01.'),
246
265
  dateTo: z.string().optional().describe('Fee start-date range end (inclusive).'),
247
- page: z.number().optional(),
248
- pageSize: z.number().optional(),
266
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."),
267
+ pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
249
268
  }, async (args) => get('/fees/search', args));
250
269
  // --- CRM: sales activities / time (read) ---
251
270
  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 +277,8 @@ strictTool('crm_activity_search', 'Search/filter CRM sales activities (CRMActivi
258
277
  completed: z.boolean().optional().describe('true = CRMADateCompleted is not null; false = CRMADateCompleted is null; omitted = all.'),
259
278
  dateDueFrom: z.string().optional().describe('Due-date range start (CRMActivity.CRMADateDue), e.g. 2026-01-01.'),
260
279
  dateDueTo: z.string().optional().describe('Due-date range end (CRMActivity.CRMADateDue).'),
261
- page: z.number().optional(),
262
- pageSize: z.number().optional(),
280
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."),
281
+ pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
263
282
  }, async (args) => get('/crm/activities/search', args));
264
283
  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
284
  activityId: z.number().describe('CRM activity ID (CRMActivity.CRMAID / TMActivity.TMA_CRMAID).'),
@@ -272,11 +291,11 @@ strictTool('crm_activity_search_time_entries', 'Search CRM sales activity time e
272
291
  q: z.string().optional().describe('Partial text match against TMActivity.TMADescription, TMActivity.TMAInternal, or CRMActivity.CRMADescription.'),
273
292
  dateFrom: z.string().optional().describe('Activity time-entry date range start (TMActivity.TMADate), e.g. 2026-01-01.'),
274
293
  dateTo: z.string().optional().describe('Activity time-entry date range end (TMActivity.TMADate).'),
275
- page: z.number().optional(),
276
- 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."),
277
296
  }, async (args) => get('/crm/activities/time-entries/search', args));
278
297
  // --- 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}`));
298
+ 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
299
  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
300
  taskId: z.number().describe('Task ID (TMTask.TMTID / TMActivity.TMA_TMTID).'),
282
301
  personId: z.number().optional().describe('Filter by staff person who performed the work (TMActivity.TMA_CSCID).'),
@@ -291,8 +310,8 @@ strictTool('task_search_time_entries', 'Search task activity/time and incidental
291
310
  dateFrom: z.string().optional().describe('Activity date range start (TMActivity.TMADate), e.g. 2026-01-01. Use this exact parameter name, not fromDate.'),
292
311
  dateTo: z.string().optional().describe('Activity date range end (TMActivity.TMADate). Use this exact parameter name, not toDate.'),
293
312
  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(),
313
+ page: z.number().optional().describe("Page number for the filtered search; follow API pagination metadata rather than assuming the first page is complete."),
314
+ pageSize: z.number().optional().describe("Maximum results requested per page; choose the smallest size needed and respect API response limits."),
296
315
  }, async (args) => get('/tasks/time-entries/search', args));
297
316
  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
317
  q: z.string().optional().describe('Free text: exact task ID match, or partial match on task name/description.'),
@@ -305,11 +324,11 @@ strictTool('task_search', 'Search/filter tasks. Supports filtering by customer/a
305
324
  status: z.enum(['open', 'closed', 'all']).optional().describe('Task status (TMTStatus). Default: open.'),
306
325
  dateFrom: z.string().optional().describe('Date-logged range start (inclusive), e.g. 2026-01-01.'),
307
326
  dateTo: z.string().optional().describe('Date-logged range end (inclusive).'),
308
- page: z.number().optional(), pageSize: z.number().optional(),
327
+ 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
328
  }, async (args) => get('/tasks/search', args));
310
329
  // --- 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`));
330
+ 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}`));
331
+ 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
332
  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
333
  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
334
  advanced: z.boolean().optional().describe('Widen `q` to also match order notes and line product code/OEM code/descriptions.'),
@@ -334,7 +353,7 @@ strictTool('order_search', 'Search/filter orders. Supports filtering by customer
334
353
  invoiced: z.enum(['yes', 'no']).optional().describe('Whether at least one line has been invoiced. Same "at least one line" semantics as `received`.'),
335
354
  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
355
  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(),
356
+ 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
357
  }, async (args) => get('/orders/search', args));
339
358
  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
359
  q: z.string().optional(),
@@ -343,7 +362,7 @@ strictTool('product_search', 'Search the read-only product catalog. `q` splits o
343
362
  manufacturer: z.string().optional().describe('Exact match on PMPManufacturer.'),
344
363
  category: z.string().optional().describe('Exact match on PMPProductCategory_ID.'),
345
364
  inStock: z.boolean().optional().describe('true = PMPOnHand > 0; false = no stock on hand.'),
346
- page: z.number().optional(), pageSize: z.number().optional(),
365
+ 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
366
  }, async (args) => get('/orders/products/search', args));
348
367
  function createConfiguredServer() {
349
368
  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.7.0",
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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"}