@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 +24 -0
- package/README.md +98 -0
- package/dist/index.js +24 -24
- package/package.json +39 -34
- package/dist/index.js.map +0 -1
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
|
|
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
|
|
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.
|
|
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
|
-
|
|
15
|
-
"
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
"
|
|
19
|
-
"
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
"
|
|
23
|
-
"
|
|
24
|
-
"
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
"
|
|
29
|
-
"
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
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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"}
|