@a1-x-tech/mcp-google-sheets 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/LICENSE +21 -0
- package/README.md +307 -0
- package/README.ru.md +307 -0
- package/dist/client.js +736 -0
- package/dist/config.js +83 -0
- package/dist/index.js +128 -0
- package/dist/telemetry.js +120 -0
- package/dist/tools/format.js +176 -0
- package/dist/tools/objects.js +127 -0
- package/dist/tools/raw.js +30 -0
- package/dist/tools/rules.js +175 -0
- package/dist/tools/sharing.js +86 -0
- package/dist/tools/sheets.js +79 -0
- package/dist/tools/spreadsheets.js +92 -0
- package/dist/tools/util.js +102 -0
- package/dist/tools/values.js +146 -0
- package/dist/types.js +46 -0
- package/package.json +63 -0
- package/test/dist-smoke.test.js +185 -0
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { a1RangeSchema, DESTRUCTIVE, fail, ok, READ_ONLY, spreadsheetIdSchema, UPDATE, valuesSchema, WRITE, } from "./util.js";
|
|
3
|
+
export function registerValueTools(server, client) {
|
|
4
|
+
server.registerTool("read_values", {
|
|
5
|
+
title: "Read values",
|
|
6
|
+
annotations: READ_ONLY,
|
|
7
|
+
description: "Reads one or more A1 ranges in a single call (one request against the quota, however many ranges) and returns valueRanges[] — each with its resolved range and a 2-D values array (outer = rows unless major_dimension=COLUMNS). Trailing empty rows/columns are omitted; a fully empty range has no values key at all. value_render_option: FORMATTED_VALUE (default, strings as displayed, honoring the cell's number format and locale), UNFORMATTED_VALUE (raw numbers/booleans), FORMULA (the formula text, e.g. \"=SUM(A1:A10)\" — the way to read formulas). With UNFORMATTED_VALUE, dates arrive as serial numbers unless date_time_render_option=FORMATTED_STRING.",
|
|
8
|
+
inputSchema: {
|
|
9
|
+
spreadsheet_id: spreadsheetIdSchema(),
|
|
10
|
+
ranges: z.array(a1RangeSchema()).min(1).describe("One or more A1 ranges to read in a single call."),
|
|
11
|
+
value_render_option: z
|
|
12
|
+
.enum(["FORMATTED_VALUE", "UNFORMATTED_VALUE", "FORMULA"])
|
|
13
|
+
.optional()
|
|
14
|
+
.describe("How values are rendered (default FORMATTED_VALUE); FORMULA returns formula text."),
|
|
15
|
+
major_dimension: z
|
|
16
|
+
.enum(["ROWS", "COLUMNS"])
|
|
17
|
+
.optional()
|
|
18
|
+
.describe("Whether the outer array is rows (default) or columns."),
|
|
19
|
+
date_time_render_option: z
|
|
20
|
+
.enum(["SERIAL_NUMBER", "FORMATTED_STRING"])
|
|
21
|
+
.optional()
|
|
22
|
+
.describe("How dates/times render with UNFORMATTED_VALUE (default SERIAL_NUMBER)."),
|
|
23
|
+
},
|
|
24
|
+
}, async ({ spreadsheet_id, ranges, value_render_option, major_dimension, date_time_render_option }) => {
|
|
25
|
+
try {
|
|
26
|
+
return ok(await client.getValues({
|
|
27
|
+
spreadsheetId: spreadsheet_id,
|
|
28
|
+
ranges,
|
|
29
|
+
valueRenderOption: value_render_option,
|
|
30
|
+
majorDimension: major_dimension,
|
|
31
|
+
dateTimeRenderOption: date_time_render_option,
|
|
32
|
+
}));
|
|
33
|
+
}
|
|
34
|
+
catch (e) {
|
|
35
|
+
return fail(e);
|
|
36
|
+
}
|
|
37
|
+
});
|
|
38
|
+
server.registerTool("write_values", {
|
|
39
|
+
title: "Write values to a range",
|
|
40
|
+
annotations: UPDATE,
|
|
41
|
+
description: "Overwrites one A1 range with a 2-D values matrix (rows first) and returns updatedRange/updatedRows/updatedColumns/updatedCells. The matrix is anchored at the range's top-left corner; cells beyond the matrix keep their old content, and a null entry skips (does not clear) that cell — use clear_values to empty cells. value_input_option USER_ENTERED (default) parses input like typing in the UI: \"=SUM(A1:A10)\" becomes a live formula, \"1,234\" and \"2026-01-15\" become number/date per the spreadsheet locale; RAW stores everything as literal values. For several ranges use batch_write_values (one quota unit instead of N).",
|
|
42
|
+
inputSchema: {
|
|
43
|
+
spreadsheet_id: spreadsheetIdSchema(),
|
|
44
|
+
range: a1RangeSchema(),
|
|
45
|
+
values: valuesSchema(),
|
|
46
|
+
value_input_option: z
|
|
47
|
+
.enum(["USER_ENTERED", "RAW"])
|
|
48
|
+
.optional()
|
|
49
|
+
.describe("USER_ENTERED (default) parses formulas/numbers/dates; RAW stores literal strings."),
|
|
50
|
+
include_values_in_response: z
|
|
51
|
+
.boolean()
|
|
52
|
+
.optional()
|
|
53
|
+
.describe("Return the written cells (as rendered) in the response."),
|
|
54
|
+
},
|
|
55
|
+
}, async ({ spreadsheet_id, range, values, value_input_option, include_values_in_response }) => {
|
|
56
|
+
try {
|
|
57
|
+
return ok(await client.updateValues({
|
|
58
|
+
spreadsheetId: spreadsheet_id,
|
|
59
|
+
range,
|
|
60
|
+
values,
|
|
61
|
+
valueInputOption: value_input_option,
|
|
62
|
+
includeValuesInResponse: include_values_in_response,
|
|
63
|
+
}));
|
|
64
|
+
}
|
|
65
|
+
catch (e) {
|
|
66
|
+
return fail(e);
|
|
67
|
+
}
|
|
68
|
+
});
|
|
69
|
+
server.registerTool("batch_write_values", {
|
|
70
|
+
title: "Write values to many ranges",
|
|
71
|
+
annotations: UPDATE,
|
|
72
|
+
description: "Overwrites several A1 ranges in ONE call — one write against the per-minute quota instead of one per range, so always prefer this over looping write_values. data is a list of {range, values} pairs; all are written with the same value_input_option (USER_ENTERED parses formulas/numbers/dates, RAW stores literally). Returns totalUpdatedCells and a per-range responses[] breakdown. Like write_values, null entries skip cells rather than clearing them.",
|
|
73
|
+
inputSchema: {
|
|
74
|
+
spreadsheet_id: spreadsheetIdSchema(),
|
|
75
|
+
data: z
|
|
76
|
+
.array(z.object({
|
|
77
|
+
range: a1RangeSchema(),
|
|
78
|
+
values: valuesSchema(),
|
|
79
|
+
}))
|
|
80
|
+
.min(1)
|
|
81
|
+
.describe("The ranges to write, each with its own 2-D values matrix."),
|
|
82
|
+
value_input_option: z
|
|
83
|
+
.enum(["USER_ENTERED", "RAW"])
|
|
84
|
+
.optional()
|
|
85
|
+
.describe("USER_ENTERED (default) parses formulas/numbers/dates; RAW stores literal strings."),
|
|
86
|
+
},
|
|
87
|
+
}, async ({ spreadsheet_id, data, value_input_option }) => {
|
|
88
|
+
try {
|
|
89
|
+
return ok(await client.batchUpdateValues({
|
|
90
|
+
spreadsheetId: spreadsheet_id,
|
|
91
|
+
data,
|
|
92
|
+
valueInputOption: value_input_option,
|
|
93
|
+
}));
|
|
94
|
+
}
|
|
95
|
+
catch (e) {
|
|
96
|
+
return fail(e);
|
|
97
|
+
}
|
|
98
|
+
});
|
|
99
|
+
server.registerTool("append_values", {
|
|
100
|
+
title: "Append rows",
|
|
101
|
+
annotations: WRITE,
|
|
102
|
+
description: "Appends rows after the last row of the data table that contains the given range — pass the table's region (e.g. \"Sheet1!A1:D1\" or just \"Sheet1\") and the API finds the first free row itself; the response's updates.updatedRange shows where the rows actually landed. insert_data_option INSERT_ROWS pushes existing data below down; OVERWRITE (default behaviour) writes into the free rows after the table. Never retried after an ambiguous failure — re-appending would duplicate the rows, so check the sheet first (read_values) before re-sending.",
|
|
103
|
+
inputSchema: {
|
|
104
|
+
spreadsheet_id: spreadsheetIdSchema(),
|
|
105
|
+
range: a1RangeSchema().describe("A1 range identifying the table to append to (the API scans it for the last data row)."),
|
|
106
|
+
values: valuesSchema(),
|
|
107
|
+
value_input_option: z
|
|
108
|
+
.enum(["USER_ENTERED", "RAW"])
|
|
109
|
+
.optional()
|
|
110
|
+
.describe("USER_ENTERED (default) parses formulas/numbers/dates; RAW stores literal strings."),
|
|
111
|
+
insert_data_option: z
|
|
112
|
+
.enum(["OVERWRITE", "INSERT_ROWS"])
|
|
113
|
+
.optional()
|
|
114
|
+
.describe("OVERWRITE writes after the table (default); INSERT_ROWS inserts new rows, shifting data below."),
|
|
115
|
+
},
|
|
116
|
+
}, async ({ spreadsheet_id, range, values, value_input_option, insert_data_option }) => {
|
|
117
|
+
try {
|
|
118
|
+
return ok(await client.appendValues({
|
|
119
|
+
spreadsheetId: spreadsheet_id,
|
|
120
|
+
range,
|
|
121
|
+
values,
|
|
122
|
+
valueInputOption: value_input_option,
|
|
123
|
+
insertDataOption: insert_data_option,
|
|
124
|
+
}));
|
|
125
|
+
}
|
|
126
|
+
catch (e) {
|
|
127
|
+
return fail(e);
|
|
128
|
+
}
|
|
129
|
+
});
|
|
130
|
+
server.registerTool("clear_values", {
|
|
131
|
+
title: "Clear values",
|
|
132
|
+
annotations: DESTRUCTIVE,
|
|
133
|
+
description: "Empties the VALUES of one or more A1 ranges in a single call — cell contents and formulas are gone (no undo through the API), while formatting, data validation, notes, conditional formats and merges all stay. To also remove formatting use format_cells or raw_request; to delete whole rows/columns (not just their content) use manage_dimensions action=delete.",
|
|
134
|
+
inputSchema: {
|
|
135
|
+
spreadsheet_id: spreadsheetIdSchema(),
|
|
136
|
+
ranges: z.array(a1RangeSchema()).min(1).describe("The A1 ranges to clear."),
|
|
137
|
+
},
|
|
138
|
+
}, async ({ spreadsheet_id, ranges }) => {
|
|
139
|
+
try {
|
|
140
|
+
return ok(await client.clearValues({ spreadsheetId: spreadsheet_id, ranges }));
|
|
141
|
+
}
|
|
142
|
+
catch (e) {
|
|
143
|
+
return fail(e);
|
|
144
|
+
}
|
|
145
|
+
});
|
|
146
|
+
}
|
package/dist/types.js
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The server talks to the Google Sheets API v4 (https://sheets.googleapis.com,
|
|
3
|
+
* REST over JSON). Auth is Google OAuth 2.0: a Bearer access token, minted
|
|
4
|
+
* on demand from a refresh token via https://oauth2.googleapis.com/token
|
|
5
|
+
* (or a static short-lived access token, mostly for testing). The Drive API v3
|
|
6
|
+
* (https://www.googleapis.com) is an internal dependency only — spreadsheet
|
|
7
|
+
* search and permission management have no Sheets API equivalent.
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* Google APIs report failures as a non-2xx HTTP status with a JSON envelope
|
|
11
|
+
* ({ error: { code, message, status, details } }); the OAuth token endpoint
|
|
12
|
+
* uses { error, error_description }. The parsed body is kept alongside the
|
|
13
|
+
* status and a short readable message is derived.
|
|
14
|
+
*/
|
|
15
|
+
export class GoogleSheetsError extends Error {
|
|
16
|
+
status;
|
|
17
|
+
body;
|
|
18
|
+
constructor(status, body) {
|
|
19
|
+
super(`HTTP ${status}: ${formatErrorBody(body)}`);
|
|
20
|
+
this.name = "GoogleSheetsError";
|
|
21
|
+
this.status = status;
|
|
22
|
+
this.body = body;
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
/** Turns a parsed Google API error body into a short, readable message. */
|
|
26
|
+
function formatErrorBody(body) {
|
|
27
|
+
if (body == null)
|
|
28
|
+
return "(no body)";
|
|
29
|
+
if (typeof body === "string")
|
|
30
|
+
return body.slice(0, 500);
|
|
31
|
+
if (typeof body !== "object")
|
|
32
|
+
return String(body);
|
|
33
|
+
const obj = body;
|
|
34
|
+
// OAuth token endpoint style: { error: "invalid_grant", error_description: "..." }
|
|
35
|
+
if (typeof obj.error === "string") {
|
|
36
|
+
const description = typeof obj.error_description === "string" ? `: ${obj.error_description}` : "";
|
|
37
|
+
return `${obj.error}${description}`.slice(0, 500);
|
|
38
|
+
}
|
|
39
|
+
// Google API envelope: { error: { code, message, status, details } }
|
|
40
|
+
const err = (typeof obj.error === "object" && obj.error !== null ? obj.error : obj);
|
|
41
|
+
if (typeof err.message === "string") {
|
|
42
|
+
const status = typeof err.status === "string" ? `[${err.status}] ` : "";
|
|
43
|
+
return `${status}${err.message}`.slice(0, 500);
|
|
44
|
+
}
|
|
45
|
+
return JSON.stringify(obj).slice(0, 500);
|
|
46
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@a1-x-tech/mcp-google-sheets",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "MCP server for the Google Sheets API — search spreadsheets, read and write ranges, manage sheets, formatting, validation, protected ranges, tables, charts and sharing. For Claude, Cursor, Codex and other AI clients.",
|
|
5
|
+
"mcpName": "io.github.A1-x-Tech/mcp-google-sheets",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"bin": {
|
|
8
|
+
"mcp-google-sheets": "dist/index.js"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"dist",
|
|
12
|
+
"test"
|
|
13
|
+
],
|
|
14
|
+
"engines": {
|
|
15
|
+
"node": ">=20"
|
|
16
|
+
},
|
|
17
|
+
"publishConfig": {
|
|
18
|
+
"access": "public"
|
|
19
|
+
},
|
|
20
|
+
"scripts": {
|
|
21
|
+
"build": "rm -rf dist && tsc",
|
|
22
|
+
"start": "node dist/index.js",
|
|
23
|
+
"dev": "tsx watch src/index.ts",
|
|
24
|
+
"typecheck": "tsc -p tsconfig.check.json",
|
|
25
|
+
"smoke": "node --import tsx src/smoke.ts",
|
|
26
|
+
"test": "npm run test:src && npm run test:dist",
|
|
27
|
+
"test:src": "node --import tsx --test $(find src -name '*.test.ts')",
|
|
28
|
+
"test:dist": "npm run build && node --test test/dist-smoke.test.js",
|
|
29
|
+
"prepare": "npm run build",
|
|
30
|
+
"prepublishOnly": "npm run typecheck && npm test"
|
|
31
|
+
},
|
|
32
|
+
"keywords": [
|
|
33
|
+
"mcp",
|
|
34
|
+
"model-context-protocol",
|
|
35
|
+
"google",
|
|
36
|
+
"google-sheets",
|
|
37
|
+
"sheets",
|
|
38
|
+
"spreadsheet",
|
|
39
|
+
"excel",
|
|
40
|
+
"claude",
|
|
41
|
+
"cursor",
|
|
42
|
+
"codex"
|
|
43
|
+
],
|
|
44
|
+
"license": "MIT",
|
|
45
|
+
"author": "gistrec <gistrec@gmail.com>",
|
|
46
|
+
"repository": {
|
|
47
|
+
"type": "git",
|
|
48
|
+
"url": "git+https://github.com/A1-x-Tech/mcp-google-sheets.git"
|
|
49
|
+
},
|
|
50
|
+
"homepage": "https://github.com/A1-x-Tech/mcp-google-sheets#readme",
|
|
51
|
+
"bugs": {
|
|
52
|
+
"url": "https://github.com/A1-x-Tech/mcp-google-sheets/issues"
|
|
53
|
+
},
|
|
54
|
+
"dependencies": {
|
|
55
|
+
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
56
|
+
"zod": "^3.25.0"
|
|
57
|
+
},
|
|
58
|
+
"devDependencies": {
|
|
59
|
+
"@types/node": "^25.9.3",
|
|
60
|
+
"tsx": "^4.22.4",
|
|
61
|
+
"typescript": "^5.7.0"
|
|
62
|
+
}
|
|
63
|
+
}
|
|
@@ -0,0 +1,185 @@
|
|
|
1
|
+
import assert from "node:assert/strict";
|
|
2
|
+
import test from "node:test";
|
|
3
|
+
import { fileURLToPath } from "node:url";
|
|
4
|
+
|
|
5
|
+
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
6
|
+
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
|
|
7
|
+
|
|
8
|
+
import { GoogleSheetsClient } from "../dist/client.js";
|
|
9
|
+
import { registerSpreadsheetTools } from "../dist/tools/spreadsheets.js";
|
|
10
|
+
import { registerValueTools } from "../dist/tools/values.js";
|
|
11
|
+
import { registerSheetTools } from "../dist/tools/sheets.js";
|
|
12
|
+
import { registerFormatTools } from "../dist/tools/format.js";
|
|
13
|
+
import { registerRuleTools } from "../dist/tools/rules.js";
|
|
14
|
+
import { registerObjectTools } from "../dist/tools/objects.js";
|
|
15
|
+
import { registerSharingTools } from "../dist/tools/sharing.js";
|
|
16
|
+
import { registerRawTool } from "../dist/tools/raw.js";
|
|
17
|
+
|
|
18
|
+
const ALL_TOOLS = [
|
|
19
|
+
"append_values",
|
|
20
|
+
"batch_write_values",
|
|
21
|
+
"clear_values",
|
|
22
|
+
"create_spreadsheet",
|
|
23
|
+
"format_cells",
|
|
24
|
+
"get_spreadsheet",
|
|
25
|
+
"manage_charts",
|
|
26
|
+
"manage_conditional_formats",
|
|
27
|
+
"manage_dimensions",
|
|
28
|
+
"manage_permissions",
|
|
29
|
+
"manage_protected_ranges",
|
|
30
|
+
"manage_sheets",
|
|
31
|
+
"manage_tables",
|
|
32
|
+
"raw_request",
|
|
33
|
+
"read_values",
|
|
34
|
+
"search_spreadsheets",
|
|
35
|
+
"set_borders",
|
|
36
|
+
"set_data_validation",
|
|
37
|
+
"set_frozen",
|
|
38
|
+
"write_values",
|
|
39
|
+
];
|
|
40
|
+
|
|
41
|
+
test("dist client rejects foreign-origin paths before sending the Bearer token", async () => {
|
|
42
|
+
const original = globalThis.fetch;
|
|
43
|
+
let called = false;
|
|
44
|
+
globalThis.fetch = async () => {
|
|
45
|
+
called = true;
|
|
46
|
+
return new Response("{}", { status: 200 });
|
|
47
|
+
};
|
|
48
|
+
try {
|
|
49
|
+
const client = new GoogleSheetsClient({
|
|
50
|
+
accessToken: "SECRET",
|
|
51
|
+
apiBase: "https://sheets.googleapis.com",
|
|
52
|
+
timeoutMs: 1000,
|
|
53
|
+
maxRetries: 0,
|
|
54
|
+
});
|
|
55
|
+
await assert.rejects(() => client.request("GET", "https://example.invalid/steal"), /foreign origin/);
|
|
56
|
+
assert.equal(called, false);
|
|
57
|
+
} finally {
|
|
58
|
+
globalThis.fetch = original;
|
|
59
|
+
}
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
test("dist client sends the Bearer token and JSON bodies", async () => {
|
|
63
|
+
const original = globalThis.fetch;
|
|
64
|
+
let seen;
|
|
65
|
+
globalThis.fetch = async (url, init) => {
|
|
66
|
+
seen = { url: String(url), auth: init.headers.Authorization, body: JSON.parse(init.body) };
|
|
67
|
+
return new Response('{"spreadsheetId":"s-1"}', { status: 200 });
|
|
68
|
+
};
|
|
69
|
+
try {
|
|
70
|
+
const client = new GoogleSheetsClient({
|
|
71
|
+
accessToken: "SECRET",
|
|
72
|
+
apiBase: "https://sheets.googleapis.com",
|
|
73
|
+
timeoutMs: 1000,
|
|
74
|
+
maxRetries: 0,
|
|
75
|
+
});
|
|
76
|
+
await client.createSpreadsheet({ title: "Smoke" });
|
|
77
|
+
assert.equal(seen.url, "https://sheets.googleapis.com/v4/spreadsheets");
|
|
78
|
+
assert.equal(seen.auth, "Bearer SECRET");
|
|
79
|
+
assert.deepEqual(seen.body, { properties: { title: "Smoke" } });
|
|
80
|
+
} finally {
|
|
81
|
+
globalThis.fetch = original;
|
|
82
|
+
}
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
test("dist registers the expected tools", () => {
|
|
86
|
+
const names = [];
|
|
87
|
+
const server = {
|
|
88
|
+
registerTool(name) {
|
|
89
|
+
names.push(name);
|
|
90
|
+
},
|
|
91
|
+
};
|
|
92
|
+
const client = {};
|
|
93
|
+
|
|
94
|
+
registerSpreadsheetTools(server, client);
|
|
95
|
+
registerValueTools(server, client);
|
|
96
|
+
registerSheetTools(server, client);
|
|
97
|
+
registerFormatTools(server, client);
|
|
98
|
+
registerRuleTools(server, client);
|
|
99
|
+
registerObjectTools(server, client);
|
|
100
|
+
registerSharingTools(server, client);
|
|
101
|
+
registerRawTool(server, client);
|
|
102
|
+
|
|
103
|
+
assert.deepEqual(names.sort(), ALL_TOOLS);
|
|
104
|
+
});
|
|
105
|
+
|
|
106
|
+
test("dist binary completes a real MCP handshake over stdio and lists every tool", async () => {
|
|
107
|
+
const transport = new StdioClientTransport({
|
|
108
|
+
command: process.execPath,
|
|
109
|
+
args: [fileURLToPath(new URL("../dist/index.js", import.meta.url))],
|
|
110
|
+
env: {
|
|
111
|
+
...process.env,
|
|
112
|
+
GOOGLE_SHEETS_ACCESS_TOKEN: "test-token",
|
|
113
|
+
ASKADS_TELEMETRY: "0", // keep the suite offline
|
|
114
|
+
},
|
|
115
|
+
stderr: "pipe",
|
|
116
|
+
});
|
|
117
|
+
const client = new Client({ name: "dist-smoke", version: "0.0.0" });
|
|
118
|
+
await client.connect(transport);
|
|
119
|
+
try {
|
|
120
|
+
const server = client.getServerVersion();
|
|
121
|
+
assert.equal(server?.name, "mcp-google-sheets");
|
|
122
|
+
assert.match(String(server?.version), /^\d+\.\d+\.\d+$/);
|
|
123
|
+
|
|
124
|
+
// The instructions the calling model reads before it picks any tool.
|
|
125
|
+
const instructions = client.getInstructions();
|
|
126
|
+
assert.equal(typeof instructions, "string");
|
|
127
|
+
assert.ok(instructions.trim().length > 0, "initialize result carries no instructions");
|
|
128
|
+
assert.match(instructions, /Google Sheets API v4/);
|
|
129
|
+
|
|
130
|
+
const { tools } = await client.listTools();
|
|
131
|
+
assert.deepEqual(tools.map((t) => t.name).sort(), ALL_TOOLS);
|
|
132
|
+
|
|
133
|
+
const getSpreadsheet = tools.find((t) => t.name === "get_spreadsheet");
|
|
134
|
+
assert.equal(getSpreadsheet.annotations?.readOnlyHint, true);
|
|
135
|
+
assert.ok(getSpreadsheet.inputSchema?.properties?.spreadsheet_id, "input schema must reach the client");
|
|
136
|
+
} finally {
|
|
137
|
+
await client.close();
|
|
138
|
+
}
|
|
139
|
+
});
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* The degraded-start contract: without any credentials the binary must not
|
|
143
|
+
* exit(1) before the handshake, leaving the client a dead server and no reason.
|
|
144
|
+
* It must start, list every tool, open the instructions with the fix, and
|
|
145
|
+
* answer a tool call with the actionable error — offline: the CredentialsError
|
|
146
|
+
* fires before any fetch, so this test never touches the network.
|
|
147
|
+
*/
|
|
148
|
+
test("dist binary starts without credentials: handshake, tool list, actionable call error", async () => {
|
|
149
|
+
const env = Object.fromEntries(
|
|
150
|
+
Object.entries(process.env).filter(
|
|
151
|
+
([key, value]) => value !== undefined && !key.startsWith("GOOGLE_SHEETS_"),
|
|
152
|
+
),
|
|
153
|
+
);
|
|
154
|
+
env.ASKADS_TELEMETRY = "0"; // keep the suite offline
|
|
155
|
+
const transport = new StdioClientTransport({
|
|
156
|
+
command: process.execPath,
|
|
157
|
+
args: [fileURLToPath(new URL("../dist/index.js", import.meta.url))],
|
|
158
|
+
env,
|
|
159
|
+
stderr: "pipe",
|
|
160
|
+
});
|
|
161
|
+
const client = new Client({ name: "dist-smoke-unconfigured", version: "0.0.0" });
|
|
162
|
+
await client.connect(transport);
|
|
163
|
+
try {
|
|
164
|
+
// The model must read the fix before it picks a tool.
|
|
165
|
+
const instructions = client.getInstructions() ?? "";
|
|
166
|
+
assert.match(instructions, /not connected/);
|
|
167
|
+
assert.match(instructions, /GOOGLE_SHEETS_CLIENT_ID/);
|
|
168
|
+
assert.match(instructions, /restart/);
|
|
169
|
+
|
|
170
|
+
const { tools } = await client.listTools();
|
|
171
|
+
assert.deepEqual(tools.map((t) => t.name).sort(), ALL_TOOLS);
|
|
172
|
+
|
|
173
|
+
// A tool call fails with the exact message instead of killing the server.
|
|
174
|
+
const result = await client.callTool({
|
|
175
|
+
name: "get_spreadsheet",
|
|
176
|
+
arguments: { spreadsheet_id: "smoke-spreadsheet" },
|
|
177
|
+
});
|
|
178
|
+
assert.equal(result.isError, true);
|
|
179
|
+
const text = result.content.map((c) => c.text ?? "").join(" ");
|
|
180
|
+
assert.match(text, /Google OAuth credentials are required: set GOOGLE_SHEETS_CLIENT_ID/);
|
|
181
|
+
assert.match(text, /restart the server/);
|
|
182
|
+
} finally {
|
|
183
|
+
await client.close();
|
|
184
|
+
}
|
|
185
|
+
});
|