@teamnetwork-nz/gosweetspot-mcp-server 0.1.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.
Files changed (66) hide show
  1. package/README.md +174 -0
  2. package/dist/client.d.ts +29 -0
  3. package/dist/client.d.ts.map +1 -0
  4. package/dist/client.js +95 -0
  5. package/dist/client.js.map +1 -0
  6. package/dist/config.d.ts +10 -0
  7. package/dist/config.d.ts.map +1 -0
  8. package/dist/config.js +33 -0
  9. package/dist/config.js.map +1 -0
  10. package/dist/datetime.d.ts +5 -0
  11. package/dist/datetime.d.ts.map +1 -0
  12. package/dist/datetime.js +65 -0
  13. package/dist/datetime.js.map +1 -0
  14. package/dist/format.d.ts +4 -0
  15. package/dist/format.d.ts.map +1 -0
  16. package/dist/format.js +58 -0
  17. package/dist/format.js.map +1 -0
  18. package/dist/index.d.ts +3 -0
  19. package/dist/index.d.ts.map +1 -0
  20. package/dist/index.js +77 -0
  21. package/dist/index.js.map +1 -0
  22. package/dist/schemas/models.d.ts +118 -0
  23. package/dist/schemas/models.d.ts.map +1 -0
  24. package/dist/schemas/models.js +43 -0
  25. package/dist/schemas/models.js.map +1 -0
  26. package/dist/tools/address.d.ts +3 -0
  27. package/dist/tools/address.d.ts.map +1 -0
  28. package/dist/tools/address.js +28 -0
  29. package/dist/tools/address.js.map +1 -0
  30. package/dist/tools/connection.d.ts +3 -0
  31. package/dist/tools/connection.d.ts.map +1 -0
  32. package/dist/tools/connection.js +42 -0
  33. package/dist/tools/connection.js.map +1 -0
  34. package/dist/tools/customerorders.d.ts +3 -0
  35. package/dist/tools/customerorders.d.ts.map +1 -0
  36. package/dist/tools/customerorders.js +87 -0
  37. package/dist/tools/customerorders.js.map +1 -0
  38. package/dist/tools/index.d.ts +3 -0
  39. package/dist/tools/index.d.ts.map +1 -0
  40. package/dist/tools/index.js +19 -0
  41. package/dist/tools/index.js.map +1 -0
  42. package/dist/tools/manifest.d.ts +3 -0
  43. package/dist/tools/manifest.d.ts.map +1 -0
  44. package/dist/tools/manifest.js +21 -0
  45. package/dist/tools/manifest.js.map +1 -0
  46. package/dist/tools/pickup.d.ts +3 -0
  47. package/dist/tools/pickup.d.ts.map +1 -0
  48. package/dist/tools/pickup.js +26 -0
  49. package/dist/tools/pickup.js.map +1 -0
  50. package/dist/tools/printing.d.ts +3 -0
  51. package/dist/tools/printing.d.ts.map +1 -0
  52. package/dist/tools/printing.js +64 -0
  53. package/dist/tools/printing.js.map +1 -0
  54. package/dist/tools/rates.d.ts +3 -0
  55. package/dist/tools/rates.d.ts.map +1 -0
  56. package/dist/tools/rates.js +34 -0
  57. package/dist/tools/rates.js.map +1 -0
  58. package/dist/tools/shipments.d.ts +3 -0
  59. package/dist/tools/shipments.d.ts.map +1 -0
  60. package/dist/tools/shipments.js +131 -0
  61. package/dist/tools/shipments.js.map +1 -0
  62. package/dist/types.d.ts +7 -0
  63. package/dist/types.d.ts.map +1 -0
  64. package/dist/types.js +5 -0
  65. package/dist/types.js.map +1 -0
  66. package/package.json +42 -0
package/README.md ADDED
@@ -0,0 +1,174 @@
1
+ # @teamnetwork-nz/gosweetspot-mcp-server
2
+
3
+ MCP server for the **[GoSweetSpot (GSS) Freight API](https://api-docs.gosweetspot.com/)** — New Zealand freight rating, shipment creation, customer order publishing, manifesting, printing and pickup booking.
4
+
5
+ Compatible with Claude Desktop, Claude Code, Cursor, Cline, and any MCP-capable client.
6
+
7
+ **Read-only by default.** Write operations (publish orders, create/delete shipments, manifest, print, book pickups) are hidden until you set `GSS_READWRITE=true`.
8
+
9
+ ## Requirements
10
+
11
+ - Node.js 20+
12
+ - A GoSweetSpot **access key**, generated in the GSS web portal at
13
+ [ship.gosweetspot.com](https://ship.gosweetspot.com) → Administration → Integrations & Apps → **API**.
14
+
15
+ ## Configuration
16
+
17
+ Set these environment variables before starting the server. Authentication is a single
18
+ `access_key` header carried on every request — there is no token exchange.
19
+
20
+ ### Required
21
+
22
+ | Variable | Description |
23
+ |---|---|
24
+ | `GSS_ACCESS_KEY` | API access key from the GSS portal (sent as the `access_key` header) |
25
+
26
+ ### Optional
27
+
28
+ | Variable | Default | Description |
29
+ |---|---|---|
30
+ | `GSS_SITE_ID` | *(none)* | Site id, required only if your access key has access to multiple sites (sent as the `site_id` header) |
31
+ | `GSS_SUPPORT_EMAIL` | *(none)* | IT-level contact email for your organisation (sent as the `support_email` header) |
32
+ | `GSS_BASE_URL` | `https://api.gosweetspot.com` | API base URL override |
33
+ | `GSS_READWRITE` | `false` | `true` exposes and enables write tools |
34
+ | `GSS_DATETIMEFORMAT` | `local` | Timezone for date display — `local`, an IANA name (e.g. `Pacific/Auckland`), or `UTC` |
35
+ | `GSS_PAGESIZE` | `100` | Default page size for list tools that paginate server-side (max 250) |
36
+
37
+ ## Claude Desktop configuration
38
+
39
+ ```json
40
+ {
41
+ "mcpServers": {
42
+ "gosweetspot": {
43
+ "command": "npx",
44
+ "args": ["-y", "@teamnetwork-nz/gosweetspot-mcp-server"],
45
+ "env": {
46
+ "GSS_ACCESS_KEY": "your-access-key"
47
+ }
48
+ }
49
+ }
50
+ }
51
+ ```
52
+
53
+ ## Claude Code configuration
54
+
55
+ ```bash
56
+ claude mcp add gosweetspot \
57
+ -e GSS_ACCESS_KEY=your-access-key \
58
+ -- npx -y @teamnetwork-nz/gosweetspot-mcp-server
59
+ ```
60
+
61
+ ## Read-only mode (default)
62
+
63
+ The gate is enforced in two layers:
64
+
65
+ 1. **Tool visibility** — in read-only mode the write tools are not listed at all, so an
66
+ agent never sees publish/create/delete/print/manifest/pickup operations.
67
+ 2. **Client guard** — even if invoked directly, the HTTP client's write helpers
68
+ (`post`/`put`/`delete`) throw before any request is sent.
69
+
70
+ Read-only queries that happen to use `POST` (rates, address validation, shipment status)
71
+ are treated as reads and remain available — they carry a request body but don't mutate data.
72
+
73
+ ## Available tools
74
+
75
+ Read tools are always available (10). Write tools (marked **[write]**, 7 more) require
76
+ `GSS_READWRITE=true`.
77
+
78
+ ### Connection & reference data
79
+ | Tool | Description |
80
+ |---|---|
81
+ | `gss_test_connection` | Verify credentials; report base URL, site id, mode and carrier count |
82
+ | `gss_get_available_services` | Carriers/services available to the access key |
83
+ | `gss_list_stock_sizes` | Pre-configured package/stock sizes for the account |
84
+
85
+ ### Rates
86
+ | Tool | Description |
87
+ |---|---|
88
+ | `gss_get_rates` | Price enquiry — available rates, rejected rates and validation errors for a destination + packages |
89
+
90
+ ### Shipments
91
+ | Tool | Description |
92
+ |---|---|
93
+ | `gss_list_shipments` | Historical shipments, filterable by consignment/order numbers or date range |
94
+ | `gss_get_shipment_status` | Current status + line-level tracking events by consignment number |
95
+ | `gss_create_shipment` | **[write]** create a shipment (optionally from a rate `QuoteId`) |
96
+ | `gss_delete_shipments` | **[write]** delete unprocessed shipments (max 50) |
97
+
98
+ ### Customer orders
99
+ | Tool | Description |
100
+ |---|---|
101
+ | `gss_list_customer_orders` | Orders already published to the GSS queue |
102
+ | `gss_publish_customer_orders` | **[write]** publish/update orders in the GSS queue |
103
+
104
+ ### Printing
105
+ | Tool | Description |
106
+ |---|---|
107
+ | `gss_list_printers` | Printers available to the account |
108
+ | `gss_get_label` | Download a shipment's label (base64 PNG/PDF/ZPL) |
109
+ | `gss_print_label` | **[write]** enqueue a shipment's label for printing |
110
+ | `gss_enqueue_print` | **[write]** enqueue a raw base64 image into the print queue |
111
+
112
+ ### Manifesting & pickup
113
+ | Tool | Description |
114
+ |---|---|
115
+ | `gss_publish_manifest` | **[write]** batch and manifest shipments for carrier collection |
116
+ | `gss_book_pickup` | **[write]** book a driver to collect parcels |
117
+
118
+ ### Address validation
119
+ | Tool | Description |
120
+ |---|---|
121
+ | `gss_validate_address` | Validate an address; for NZ, also reports rural/Saturday/residential delivery availability |
122
+
123
+ ## Agent guidance
124
+
125
+ ### Concepts
126
+ - A **customer order** maps one-to-one with an order from your e-commerce/ERP system.
127
+ Publishing one (`gss_publish_customer_orders`) lets a GSS operator search/scan it in the
128
+ portal to auto-populate delivery details — GSS still creates the shipment there.
129
+ - A **shipment** is one or more packages going to the same destination on the same
130
+ carrier, created directly via the API (`gss_create_shipment`) — used for specialised or
131
+ fully-automated dispatch workflows.
132
+
133
+ ### Typical flows
134
+ 1. **Bespoke e-commerce, GSS portal does the ticketing**: `gss_publish_customer_orders`
135
+ when an order is ready → operator tickets it in the GSS portal →
136
+ `gss_list_customer_orders` periodically to poll status.
137
+ 2. **Specialised/automated dispatch**: `gss_get_rates` to price the shipment →
138
+ `gss_create_shipment` (with the chosen `QuoteId`, or a `Carrier` name for auto-rating) →
139
+ optionally `gss_print_label` / `gss_book_pickup`.
140
+ 3. **Track a shipment**: `gss_get_shipment_status` or `gss_list_shipments` by consignment
141
+ or order number.
142
+ 4. Before shipping, `gss_validate_address` can check rural/Saturday/residential delivery
143
+ availability for NZ addresses.
144
+ 5. Some carriers (e.g. Mainstream Freight) require `gss_publish_manifest` before
145
+ `gss_book_pickup`; TIL Freight is booked automatically during manifesting.
146
+
147
+ ### IDs
148
+ Shipments are identified by **consignment number** ("connote"). Customer orders are
149
+ identified by **packing slip number**. Rates return a **QuoteId** that can be locked in
150
+ when creating a shipment.
151
+
152
+ ### Rate limiting
153
+ GSS does not currently enforce rate limits but asks integrations to stay under ~60
154
+ calls/minute or 1000/hour.
155
+
156
+ ## Development
157
+
158
+ ```bash
159
+ npm install
160
+ npm run build
161
+
162
+ GSS_ACCESS_KEY=... \
163
+ node dist/index.js
164
+ ```
165
+
166
+ Test with the MCP inspector:
167
+
168
+ ```bash
169
+ npx @modelcontextprotocol/inspector node dist/index.js
170
+ ```
171
+
172
+ ## License
173
+
174
+ MIT
@@ -0,0 +1,29 @@
1
+ import { GssConfig } from './config.js';
2
+ /**
3
+ * Thin HTTP client for the GoSweetSpot (GSS) Freight API.
4
+ *
5
+ * Authentication is a single `access_key` header carried on every request (plus an
6
+ * optional `site_id` for multi-site keys and a `support_email` contact). There is no
7
+ * OAuth / token exchange. Writes are gated behind GSS_READWRITE=true.
8
+ */
9
+ export declare class GssClient {
10
+ private http;
11
+ private config;
12
+ constructor(config: GssConfig);
13
+ getBaseUrl(): string;
14
+ getSiteId(): string | undefined;
15
+ getDefaultPageSize(): number;
16
+ isReadWrite(): boolean;
17
+ private request;
18
+ private assertWritePermitted;
19
+ get<T>(path: string, params?: Record<string, unknown>): Promise<T>;
20
+ /**
21
+ * A POST used purely to *query* data (rates, address validation, shipment status).
22
+ * These read endpoints happen to use POST for their request body, so they are NOT gated.
23
+ */
24
+ postQuery<T>(path: string, body: unknown): Promise<T>;
25
+ post<T>(path: string, body?: unknown): Promise<T>;
26
+ put<T>(path: string, body?: unknown): Promise<T>;
27
+ delete<T>(path: string, params?: Record<string, unknown>): Promise<T>;
28
+ }
29
+ //# sourceMappingURL=client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAExC;;;;;;GAMG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAgB;IAC5B,OAAO,CAAC,MAAM,CAAY;gBAEd,MAAM,EAAE,SAAS;IAgB7B,UAAU,IAAI,MAAM;IAIpB,SAAS,IAAI,MAAM,GAAG,SAAS;IAI/B,kBAAkB,IAAI,MAAM;IAI5B,WAAW,IAAI,OAAO;YAMR,OAAO;IAgCrB,OAAO,CAAC,oBAAoB;IAUtB,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAIxE;;;OAGG;IACG,SAAS,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAIrD,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAKjD,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAKhD,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAI5E"}
package/dist/client.js ADDED
@@ -0,0 +1,95 @@
1
+ import axios from 'axios';
2
+ /**
3
+ * Thin HTTP client for the GoSweetSpot (GSS) Freight API.
4
+ *
5
+ * Authentication is a single `access_key` header carried on every request (plus an
6
+ * optional `site_id` for multi-site keys and a `support_email` contact). There is no
7
+ * OAuth / token exchange. Writes are gated behind GSS_READWRITE=true.
8
+ */
9
+ export class GssClient {
10
+ http;
11
+ config;
12
+ constructor(config) {
13
+ this.config = config;
14
+ const headers = {
15
+ access_key: config.accessKey,
16
+ 'Content-Type': 'application/json',
17
+ Accept: 'application/json',
18
+ };
19
+ if (config.siteId)
20
+ headers['site_id'] = config.siteId;
21
+ if (config.supportEmail)
22
+ headers['support_email'] = config.supportEmail;
23
+ this.http = axios.create({
24
+ baseURL: config.baseUrl,
25
+ headers,
26
+ });
27
+ }
28
+ getBaseUrl() {
29
+ return this.config.baseUrl;
30
+ }
31
+ getSiteId() {
32
+ return this.config.siteId;
33
+ }
34
+ getDefaultPageSize() {
35
+ return this.config.pageSize;
36
+ }
37
+ isReadWrite() {
38
+ return this.config.readWrite;
39
+ }
40
+ // ---- Core request ---------------------------------------------------------
41
+ async request(method, path, data, params) {
42
+ const cfg = { method, url: path, params, data };
43
+ try {
44
+ const resp = await this.http.request(cfg);
45
+ return resp.data;
46
+ }
47
+ catch (err) {
48
+ if (axios.isAxiosError(err)) {
49
+ const respData = err.response?.data;
50
+ const msg = (typeof respData === 'object' && respData?.['Message']) ||
51
+ (typeof respData === 'object' && respData?.['message']) ||
52
+ (typeof respData === 'object' && respData?.['error']) ||
53
+ (typeof respData === 'string' ? respData : undefined) ||
54
+ err.message;
55
+ const status = err.response?.status;
56
+ const hint = status === 401 || status === 403
57
+ ? ' (check GSS_ACCESS_KEY, and GSS_SITE_ID if your key has multiple sites)'
58
+ : '';
59
+ throw new Error(`GoSweetSpot API error [${status ?? '?'}]: ${msg}${hint}`);
60
+ }
61
+ throw err;
62
+ }
63
+ }
64
+ // ---- Read-only gate -------------------------------------------------------
65
+ assertWritePermitted() {
66
+ if (!this.config.readWrite) {
67
+ throw new Error('This operation is a write and the server is running read-only. ' +
68
+ 'Set GSS_READWRITE=true to enable publishing orders, creating/deleting shipments, ' +
69
+ 'manifesting, printing and pickup bookings.');
70
+ }
71
+ }
72
+ async get(path, params) {
73
+ return this.request('GET', path, undefined, params);
74
+ }
75
+ /**
76
+ * A POST used purely to *query* data (rates, address validation, shipment status).
77
+ * These read endpoints happen to use POST for their request body, so they are NOT gated.
78
+ */
79
+ async postQuery(path, body) {
80
+ return this.request('POST', path, body);
81
+ }
82
+ async post(path, body) {
83
+ this.assertWritePermitted();
84
+ return this.request('POST', path, body ?? {});
85
+ }
86
+ async put(path, body) {
87
+ this.assertWritePermitted();
88
+ return this.request('PUT', path, body ?? {});
89
+ }
90
+ async delete(path, params) {
91
+ this.assertWritePermitted();
92
+ return this.request('DELETE', path, undefined, params);
93
+ }
94
+ }
95
+ //# sourceMappingURL=client.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,10 @@
1
+ export interface GssConfig {
2
+ baseUrl: string;
3
+ accessKey: string;
4
+ siteId?: string;
5
+ supportEmail?: string;
6
+ readWrite: boolean;
7
+ pageSize: number;
8
+ }
9
+ export declare function loadConfig(): GssConfig;
10
+ //# sourceMappingURL=config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAUD,wBAAgB,UAAU,IAAI,SAAS,CAsBtC"}
package/dist/config.js ADDED
@@ -0,0 +1,33 @@
1
+ const DEFAULT_BASE_URL = 'https://api.gosweetspot.com';
2
+ // Prepend https:// when the host is given without a protocol, and strip any trailing slash.
3
+ function normalizeBaseUrl(url) {
4
+ const withProto = /^https?:\/\//i.test(url) ? url : `https://${url}`;
5
+ return withProto.replace(/\/+$/, '');
6
+ }
7
+ export function loadConfig() {
8
+ const accessKey = process.env.GSS_ACCESS_KEY?.trim();
9
+ const siteId = process.env.GSS_SITE_ID?.trim();
10
+ const supportEmail = process.env.GSS_SUPPORT_EMAIL?.trim();
11
+ const baseUrlEnv = process.env.GSS_BASE_URL?.trim();
12
+ if (!accessKey) {
13
+ throw new Error('Missing required environment variable: GSS_ACCESS_KEY');
14
+ }
15
+ const baseUrl = baseUrlEnv ? normalizeBaseUrl(baseUrlEnv) : DEFAULT_BASE_URL;
16
+ const readWrite = process.env.GSS_READWRITE?.toLowerCase() === 'true';
17
+ const pageSize = clampPageSize(process.env.GSS_PAGESIZE);
18
+ return {
19
+ baseUrl,
20
+ accessKey,
21
+ siteId: siteId || undefined,
22
+ supportEmail: supportEmail || undefined,
23
+ readWrite,
24
+ pageSize,
25
+ };
26
+ }
27
+ function clampPageSize(raw) {
28
+ const n = raw ? Number(raw) : 100;
29
+ if (!Number.isFinite(n) || n <= 0)
30
+ return 100;
31
+ return Math.min(Math.floor(n), 250);
32
+ }
33
+ //# sourceMappingURL=config.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AASA,MAAM,gBAAgB,GAAG,6BAA6B,CAAC;AAEvD,4FAA4F;AAC5F,SAAS,gBAAgB,CAAC,GAAW;IACnC,MAAM,SAAS,GAAG,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,WAAW,GAAG,EAAE,CAAC;IACrE,OAAO,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,UAAU;IACxB,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,IAAI,EAAE,CAAC;IACrD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,EAAE,CAAC;IAC/C,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,EAAE,CAAC;IAC3D,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC;IAEpD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,CAAC,CAAC,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,gBAAgB,CAAC;IAC7E,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,EAAE,WAAW,EAAE,KAAK,MAAM,CAAC;IACtE,MAAM,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAEzD,OAAO;QACL,OAAO;QACP,SAAS;QACT,MAAM,EAAE,MAAM,IAAI,SAAS;QAC3B,YAAY,EAAE,YAAY,IAAI,SAAS;QACvC,SAAS;QACT,QAAQ;KACT,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,GAAuB;IAC5C,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAClC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,GAAG,CAAC;IAC9C,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;AACtC,CAAC"}
@@ -0,0 +1,5 @@
1
+ export declare function getConfiguredTz(): string;
2
+ export declare function fromUtc(value: string | number | null | undefined): string;
3
+ export declare function maybeFromUtc(val: unknown): unknown;
4
+ export declare function toUtcIso(value: string): string;
5
+ //# sourceMappingURL=datetime.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"datetime.d.ts","sourceRoot":"","sources":["../src/datetime.ts"],"names":[],"mappings":"AASA,wBAAgB,eAAe,IAAI,MAAM,CAGxC;AAID,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAuBzE;AAcD,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAGlD;AAGD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI9C"}
@@ -0,0 +1,65 @@
1
+ // Reads GSS_DATETIMEFORMAT (default: "local").
2
+ // "local" → system local timezone (Intl.DateTimeFormat default)
3
+ // <tz> → any IANA timezone name, e.g. "Pacific/Auckland", "America/New_York", "UTC"
4
+ //
5
+ // GSS timestamps are ISO-8601 strings (UTC on some endpoints, NZ time on others). This
6
+ // module renders them in the configured display timezone. Non-datetime values pass through.
7
+ const ISO_RE = /^\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?$/;
8
+ export function getConfiguredTz() {
9
+ const fmt = process.env.GSS_DATETIMEFORMAT ?? 'local';
10
+ return fmt === 'local' ? Intl.DateTimeFormat().resolvedOptions().timeZone : fmt;
11
+ }
12
+ // Convert a UTC/ISO datetime (or epoch seconds/millis number) into a display string
13
+ // in the configured timezone. Returns '' for null/undefined.
14
+ export function fromUtc(value) {
15
+ if (value === null || value === undefined || value === '')
16
+ return '';
17
+ try {
18
+ const d = toDate(value);
19
+ if (!d || isNaN(d.getTime()))
20
+ return String(value);
21
+ const tz = getConfiguredTz();
22
+ const parts = new Intl.DateTimeFormat('en-CA', {
23
+ timeZone: tz,
24
+ year: 'numeric',
25
+ month: '2-digit',
26
+ day: '2-digit',
27
+ hour: '2-digit',
28
+ minute: '2-digit',
29
+ second: '2-digit',
30
+ hour12: false,
31
+ timeZoneName: 'short',
32
+ }).formatToParts(d);
33
+ const get = (type) => parts.find((p) => p.type === type)?.value ?? '';
34
+ const h = get('hour') === '24' ? '00' : get('hour');
35
+ return `${get('year')}-${get('month')}-${get('day')} ${h}:${get('minute')}:${get('second')} ${get('timeZoneName')}`;
36
+ }
37
+ catch {
38
+ return String(value);
39
+ }
40
+ }
41
+ function toDate(value) {
42
+ if (typeof value === 'number') {
43
+ const ms = value < 1e12 ? value * 1000 : value;
44
+ return new Date(ms);
45
+ }
46
+ const s = value.trim();
47
+ if (/^\d+(\.\d+)?$/.test(s))
48
+ return toDate(Number(s));
49
+ return new Date(s);
50
+ }
51
+ // Apply fromUtc to any value that looks like an ISO datetime; pass everything else
52
+ // through unchanged.
53
+ export function maybeFromUtc(val) {
54
+ if (typeof val !== 'string')
55
+ return val;
56
+ return ISO_RE.test(val.trim()) ? fromUtc(val) : val;
57
+ }
58
+ // Format a Date as the UTC ISO string GSS date filters expect (yyyy-MM-ddTHH:mm:ssZ).
59
+ export function toUtcIso(value) {
60
+ const d = new Date(value);
61
+ if (isNaN(d.getTime()))
62
+ return value; // pass through; let the API validate
63
+ return d.toISOString();
64
+ }
65
+ //# sourceMappingURL=datetime.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"datetime.js","sourceRoot":"","sources":["../src/datetime.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,4 @@
1
+ export declare function jsonBlock(title: string, data: unknown): string;
2
+ export declare function table(title: string, headers: string[], rows: string[][]): string;
3
+ export declare function cell(v: unknown): string;
4
+ //# sourceMappingURL=format.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"AAmBA,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,MAAM,CAgB9D;AAGD,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,CAUhF;AAGD,wBAAgB,IAAI,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAIvC"}
package/dist/format.js ADDED
@@ -0,0 +1,58 @@
1
+ import { maybeFromUtc } from './datetime.js';
2
+ const MAX_OUTPUT_CHARS = 40_000;
3
+ // Recursively convert ISO datetime strings within any value to the configured timezone.
4
+ function convertDates(v) {
5
+ if (Array.isArray(v))
6
+ return v.map(convertDates);
7
+ if (v && typeof v === 'object') {
8
+ const out = {};
9
+ for (const [k, val] of Object.entries(v)) {
10
+ out[k] = convertDates(val);
11
+ }
12
+ return out;
13
+ }
14
+ return maybeFromUtc(v);
15
+ }
16
+ // Render an arbitrary API result as a titled, pretty-printed JSON block. Arrays get a
17
+ // count in the heading. Oversized payloads are truncated with a note.
18
+ export function jsonBlock(title, data) {
19
+ const converted = convertDates(data);
20
+ const count = Array.isArray(converted) ? ` (${converted.length})` : '';
21
+ let body;
22
+ try {
23
+ body = JSON.stringify(converted, null, 2);
24
+ }
25
+ catch {
26
+ body = String(converted);
27
+ }
28
+ if (body === undefined || body === 'undefined')
29
+ body = '(no content)';
30
+ let note = '';
31
+ if (body.length > MAX_OUTPUT_CHARS) {
32
+ body = body.slice(0, MAX_OUTPUT_CHARS);
33
+ note = '\n\n_Output truncated — narrow the query (filter, date range, or pagination) for the full record._';
34
+ }
35
+ return `**${title}${count}**\n\n\`\`\`json\n${body}\n\`\`\`${note}`;
36
+ }
37
+ // Render headers + rows as a Markdown table. Empty rows → "No records" line.
38
+ export function table(title, headers, rows) {
39
+ if (!rows.length)
40
+ return `**${title}**\n\nNo records found.`;
41
+ const sep = headers.map(() => '---');
42
+ const body = rows.map((r) => `| ${r.map((c) => c ?? '').join(' | ')} |`);
43
+ return [
44
+ `**${title} (${rows.length})**\n`,
45
+ `| ${headers.join(' | ')} |`,
46
+ `| ${sep.join(' | ')} |`,
47
+ ...body,
48
+ ].join('\n');
49
+ }
50
+ // Coerce anything to a short display string for table cells.
51
+ export function cell(v) {
52
+ if (v === null || v === undefined)
53
+ return '';
54
+ if (typeof v === 'object')
55
+ return JSON.stringify(v);
56
+ return String(maybeFromUtc(v));
57
+ }
58
+ //# sourceMappingURL=format.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"format.js","sourceRoot":"","sources":["../src/format.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
package/dist/index.js ADDED
@@ -0,0 +1,77 @@
1
+ #!/usr/bin/env node
2
+ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
3
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
4
+ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
5
+ import { zodToJsonSchema } from 'zod-to-json-schema';
6
+ import { loadConfig } from './config.js';
7
+ import { GssClient } from './client.js';
8
+ import { allTools } from './tools/index.js';
9
+ const config = loadConfig();
10
+ const client = new GssClient(config);
11
+ // In read-only mode, hide the write tools entirely so agents don't attempt them.
12
+ const isWriteTool = (name, description) => description.startsWith('[write]') ||
13
+ /^gss_(create|publish|delete|print|enqueue|book)/.test(name);
14
+ const activeTools = config.readWrite ? allTools : allTools.filter((t) => !isWriteTool(t.name, t.description));
15
+ const server = new Server({ name: 'gosweetspot-mcp-server', version: '0.1.0' }, {
16
+ capabilities: { tools: {} },
17
+ instructions: `
18
+ GoSweetSpot (GSS) Freight API MCP server — NZ freight rating, shipment creation, customer order publishing, manifesting, printing and pickup booking.
19
+
20
+ ## Mode
21
+ - Read-only by default. Write tools (publish orders, create/delete shipments, manifest, print, book pickups) are hidden unless GSS_READWRITE=true.
22
+ - Every write tool is described with a leading "[write]" tag.
23
+ - Check gss_test_connection for the active mode, base URL and site id.
24
+
25
+ ## Authentication
26
+ - A single access_key header authenticates every call. If the key has access to multiple sites, also set GSS_SITE_ID (sent as the site_id header). No per-request login.
27
+
28
+ ## Concepts
29
+ - A "customer order" maps one-to-one with an order from your e-commerce/ERP system. Publishing one (gss_publish_customer_orders) lets a GSS operator search/scan it in the portal to auto-populate delivery details for ticketing — GSS still creates the shipment.
30
+ - A "shipment" is one or more packages going to the same destination on the same carrier, created directly via the API (gss_create_shipment) — used for specialised/automated dispatch workflows.
31
+
32
+ ## Typical flows
33
+ 1. Bespoke e-commerce, GSS portal does the ticketing: gss_publish_customer_orders when an order is ready → operator tickets it in the GSS portal → gss_list_customer_orders periodically to poll status.
34
+ 2. Specialised/automated dispatch: gss_get_rates to price the shipment → gss_create_shipment (with the chosen QuoteId or a Carrier for auto-rating) → optionally gss_print_label / gss_book_pickup.
35
+ 3. Track a shipment: gss_get_shipment_status or gss_list_shipments by consignment/order number.
36
+ 4. Before shipping, gss_validate_address can check rural/Saturday/residential delivery availability for NZ addresses.
37
+ 5. Some carriers (e.g. Mainstream Freight) require gss_publish_manifest before gss_book_pickup; TIL Freight is booked automatically during manifesting.
38
+
39
+ ## IDs
40
+ - Shipments are identified by consignment number ("connote"). Customer orders are identified by packing slip number. Rates return a QuoteId that can be locked in when creating a shipment.
41
+ `.trim(),
42
+ });
43
+ server.setRequestHandler(ListToolsRequestSchema, async () => ({
44
+ tools: activeTools.map((t) => ({
45
+ name: t.name,
46
+ description: t.description,
47
+ inputSchema: zodToJsonSchema(t.inputSchema),
48
+ })),
49
+ }));
50
+ server.setRequestHandler(CallToolRequestSchema, async (request) => {
51
+ const tool = activeTools.find((t) => t.name === request.params.name);
52
+ if (!tool) {
53
+ // Distinguish "hidden because read-only" from genuinely unknown.
54
+ const hidden = allTools.find((t) => t.name === request.params.name);
55
+ const msg = hidden
56
+ ? `Tool ${request.params.name} is a write operation and the server is read-only. Set GSS_READWRITE=true to enable it.`
57
+ : `Unknown tool: ${request.params.name}`;
58
+ return { isError: true, content: [{ type: 'text', text: msg }] };
59
+ }
60
+ try {
61
+ const args = tool.inputSchema.parse(request.params.arguments ?? {});
62
+ const text = await tool.handler(client, args);
63
+ return { content: [{ type: 'text', text }] };
64
+ }
65
+ catch (err) {
66
+ const message = err instanceof Error ? err.message : String(err);
67
+ return {
68
+ isError: true,
69
+ content: [{ type: 'text', text: `Error in ${request.params.name}: ${message}` }],
70
+ };
71
+ }
72
+ });
73
+ const transport = new StdioServerTransport();
74
+ await server.connect(transport);
75
+ const mode = config.readWrite ? '✏️ read-write' : '🔒 read-only';
76
+ process.stderr.write(`GoSweetSpot MCP server started — ${activeTools.length}/${allTools.length} tools registered. Targeting: ${config.baseUrl} [${mode}]\n`);
77
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}