@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.
- package/README.md +174 -0
- package/dist/client.d.ts +29 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +95 -0
- package/dist/client.js.map +1 -0
- package/dist/config.d.ts +10 -0
- package/dist/config.d.ts.map +1 -0
- package/dist/config.js +33 -0
- package/dist/config.js.map +1 -0
- package/dist/datetime.d.ts +5 -0
- package/dist/datetime.d.ts.map +1 -0
- package/dist/datetime.js +65 -0
- package/dist/datetime.js.map +1 -0
- package/dist/format.d.ts +4 -0
- package/dist/format.d.ts.map +1 -0
- package/dist/format.js +58 -0
- package/dist/format.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +77 -0
- package/dist/index.js.map +1 -0
- package/dist/schemas/models.d.ts +118 -0
- package/dist/schemas/models.d.ts.map +1 -0
- package/dist/schemas/models.js +43 -0
- package/dist/schemas/models.js.map +1 -0
- package/dist/tools/address.d.ts +3 -0
- package/dist/tools/address.d.ts.map +1 -0
- package/dist/tools/address.js +28 -0
- package/dist/tools/address.js.map +1 -0
- package/dist/tools/connection.d.ts +3 -0
- package/dist/tools/connection.d.ts.map +1 -0
- package/dist/tools/connection.js +42 -0
- package/dist/tools/connection.js.map +1 -0
- package/dist/tools/customerorders.d.ts +3 -0
- package/dist/tools/customerorders.d.ts.map +1 -0
- package/dist/tools/customerorders.js +87 -0
- package/dist/tools/customerorders.js.map +1 -0
- package/dist/tools/index.d.ts +3 -0
- package/dist/tools/index.d.ts.map +1 -0
- package/dist/tools/index.js +19 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/manifest.d.ts +3 -0
- package/dist/tools/manifest.d.ts.map +1 -0
- package/dist/tools/manifest.js +21 -0
- package/dist/tools/manifest.js.map +1 -0
- package/dist/tools/pickup.d.ts +3 -0
- package/dist/tools/pickup.d.ts.map +1 -0
- package/dist/tools/pickup.js +26 -0
- package/dist/tools/pickup.js.map +1 -0
- package/dist/tools/printing.d.ts +3 -0
- package/dist/tools/printing.d.ts.map +1 -0
- package/dist/tools/printing.js +64 -0
- package/dist/tools/printing.js.map +1 -0
- package/dist/tools/rates.d.ts +3 -0
- package/dist/tools/rates.d.ts.map +1 -0
- package/dist/tools/rates.js +34 -0
- package/dist/tools/rates.js.map +1 -0
- package/dist/tools/shipments.d.ts +3 -0
- package/dist/tools/shipments.d.ts.map +1 -0
- package/dist/tools/shipments.js +131 -0
- package/dist/tools/shipments.js.map +1 -0
- package/dist/types.d.ts +7 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +5 -0
- package/dist/types.js.map +1 -0
- 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
|
package/dist/client.d.ts
ADDED
|
@@ -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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"}
|
package/dist/config.d.ts
ADDED
|
@@ -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"}
|
package/dist/datetime.js
ADDED
|
@@ -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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"}
|
package/dist/format.d.ts
ADDED
|
@@ -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":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE7C,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEhC,wFAAwF;AACxF,SAAS,YAAY,CAAC,CAAU;IAC9B,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAAE,OAAO,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACjD,IAAI,CAAC,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,GAAG,GAA4B,EAAE,CAAC;QACxC,KAAK,MAAM,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAA4B,CAAC,EAAE,CAAC;YACpE,GAAG,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC,GAAG,CAAC,CAAC;QAC7B,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,YAAY,CAAC,CAAC,CAAC,CAAC;AACzB,CAAC;AAED,sFAAsF;AACtF,sEAAsE;AACtE,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,IAAa;IACpD,MAAM,SAAS,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACH,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC5C,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,WAAW;QAAE,IAAI,GAAG,cAAc,CAAC;IACtE,IAAI,IAAI,GAAG,EAAE,CAAC;IACd,IAAI,IAAI,CAAC,MAAM,GAAG,gBAAgB,EAAE,CAAC;QACnC,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,gBAAgB,CAAC,CAAC;QACvC,IAAI,GAAG,oGAAoG,CAAC;IAC9G,CAAC;IACD,OAAO,KAAK,KAAK,GAAG,KAAK,qBAAqB,IAAI,WAAW,IAAI,EAAE,CAAC;AACtE,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,KAAK,CAAC,KAAa,EAAE,OAAiB,EAAE,IAAgB;IACtE,IAAI,CAAC,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,KAAK,yBAAyB,CAAC;IAC7D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzE,OAAO;QACL,KAAK,KAAK,KAAK,IAAI,CAAC,MAAM,OAAO;QACjC,KAAK,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI;QAC5B,KAAK,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI;QACxB,GAAG,IAAI;KACR,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,IAAI,CAAC,CAAU;IAC7B,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IAC7C,IAAI,OAAO,CAAC,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;IACpD,OAAO,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;AACjC,CAAC"}
|
package/dist/index.d.ts
ADDED
|
@@ -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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"}
|