@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 +24 -0
- package/README.md +100 -0
- package/dist/index.js +47 -28
- 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,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(
|
|
125
|
-
|
|
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('
|
|
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
|
|
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
|
|
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.
|
|
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.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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"}
|