mcp-google-forms 1.0.0 → 1.2.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 +217 -145
- package/README.ru.md +293 -0
- package/dist/client.js +62 -14
- package/dist/config.js +41 -12
- package/dist/index.js +64 -13
- package/dist/telemetry.js +3 -3
- package/dist/tools/auth.js +39 -0
- package/dist/tools/forms.js +5 -6
- package/dist/tools/items.js +1 -1
- package/package.json +2 -1
- package/test/dist-smoke.test.js +83 -1
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { registerGoogleAuth, TokenProvider, unconfiguredPrefix, } from "@a1-x-tech/mcp-google-auth";
|
|
2
|
+
/**
|
|
3
|
+
* The scopes an in-chat login requests (the per-task table lives in
|
|
4
|
+
* docs/TOOLS.md). The component always adds the identity scopes on top.
|
|
5
|
+
*/
|
|
6
|
+
export const LOGIN_SCOPES = [
|
|
7
|
+
"https://www.googleapis.com/auth/forms.body",
|
|
8
|
+
"https://www.googleapis.com/auth/forms.responses.readonly",
|
|
9
|
+
];
|
|
10
|
+
/**
|
|
11
|
+
* The single source of the auth wiring: serverName "forms" puts the stored
|
|
12
|
+
* login in ~/.config/mcp-google-forms/credentials.json (the component
|
|
13
|
+
* prefixes "mcp-google-"), envPrefix keeps the provider reading the exact
|
|
14
|
+
* GOOGLE_FORMS_* variables config.ts documents — which is what preserves the
|
|
15
|
+
* env-beats-stored priority for existing installs.
|
|
16
|
+
*/
|
|
17
|
+
export const AUTH_OPTIONS = {
|
|
18
|
+
serverName: "forms",
|
|
19
|
+
envPrefix: "GOOGLE_FORMS",
|
|
20
|
+
scopes: LOGIN_SCOPES,
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* Registers the six onboarding tools (auth_status, setup_instructions,
|
|
24
|
+
* set_client, start_login, finish_login, logout) and returns the TokenProvider
|
|
25
|
+
* the client plugs in as its fallback token source — the same instance, so a
|
|
26
|
+
* login finished mid-session is visible to the very next API call without a
|
|
27
|
+
* restart.
|
|
28
|
+
*/
|
|
29
|
+
export function registerAuthTools(server) {
|
|
30
|
+
return registerGoogleAuth(server, AUTH_OPTIONS);
|
|
31
|
+
}
|
|
32
|
+
/** True when any token exists — env variables or a stored in-chat login. */
|
|
33
|
+
export function hasAuthToken() {
|
|
34
|
+
return new TokenProvider(AUTH_OPTIONS).hasToken();
|
|
35
|
+
}
|
|
36
|
+
/** The "NOT CONNECTED" prefix for the initialize instructions (names both fixes). */
|
|
37
|
+
export function authUnconfiguredPrefix() {
|
|
38
|
+
return unconfiguredPrefix(AUTH_OPTIONS);
|
|
39
|
+
}
|
package/dist/tools/forms.js
CHANGED
|
@@ -4,7 +4,7 @@ export function registerFormTools(server, client) {
|
|
|
4
4
|
server.registerTool("create_form", {
|
|
5
5
|
title: "Create a form",
|
|
6
6
|
annotations: WRITE,
|
|
7
|
-
description: "Creates a new Google Form and returns it (formId, revisionId, responderUri, publishSettings). The API only accepts a title and an optional document title at creation — add questions with add_question and change settings with update_form_settings afterwards. IMPORTANT: API-created forms are UNPUBLISHED by default and do not accept responses; pass publish=true to publish immediately, or call set_publish_settings later. Share the responderUri with respondents once published.",
|
|
7
|
+
description: "Creates a new Google Form and returns it (formId, revisionId, responderUri, publishSettings). The API only accepts a title and an optional document title at creation (the Drive file name — it cannot be changed later through this API) — add questions with add_question and change settings with update_form_settings afterwards. IMPORTANT: API-created forms are UNPUBLISHED by default and do not accept responses; pass publish=true to publish immediately, or call set_publish_settings later. If the chained publish step fails, the form still exists: the result carries formId with published:false and publish_error — finish with set_publish_settings, never create_form again. Share the responderUri with respondents once published.",
|
|
8
8
|
inputSchema: {
|
|
9
9
|
title: z.string().min(1).describe("The form title shown to respondents."),
|
|
10
10
|
document_title: z
|
|
@@ -40,16 +40,15 @@ export function registerFormTools(server, client) {
|
|
|
40
40
|
server.registerTool("update_form_info", {
|
|
41
41
|
title: "Update form info",
|
|
42
42
|
annotations: UPDATE,
|
|
43
|
-
description: "Changes the form's title
|
|
43
|
+
description: "Changes the form's title and/or description. Only the provided fields are touched (the updateMask is computed automatically); at least one field is required. The document title (the Drive file name) is set once at create_form and cannot be changed through the Forms API — renaming the file needs the Drive API, which this server does not cover. Returns the batchUpdate replies with the new revisionId.",
|
|
44
44
|
inputSchema: {
|
|
45
45
|
form_id: formIdSchema(),
|
|
46
46
|
title: z.string().optional().describe("New form title shown to respondents."),
|
|
47
47
|
description: z.string().optional().describe("New form description shown under the title."),
|
|
48
|
-
document_title: z.string().optional().describe("New document name in Google Drive."),
|
|
49
48
|
},
|
|
50
|
-
}, async ({ form_id, title, description
|
|
49
|
+
}, async ({ form_id, title, description }) => {
|
|
51
50
|
try {
|
|
52
|
-
return ok(await client.updateFormInfo({ formId: form_id, title, description
|
|
51
|
+
return ok(await client.updateFormInfo({ formId: form_id, title, description }));
|
|
53
52
|
}
|
|
54
53
|
catch (e) {
|
|
55
54
|
return fail(e);
|
|
@@ -58,7 +57,7 @@ export function registerFormTools(server, client) {
|
|
|
58
57
|
server.registerTool("update_form_settings", {
|
|
59
58
|
title: "Update form settings",
|
|
60
59
|
annotations: UPDATE,
|
|
61
|
-
description: "Toggles quiz mode (grading with points) and/or the email collection mode. email_collection_type: DO_NOT_COLLECT, VERIFIED (respondent must be signed in; email verified) or RESPONDER_INPUT (respondent types an email). At least one field is required; only the provided fields are touched.",
|
|
60
|
+
description: "Toggles quiz mode (grading with points) and/or the email collection mode. Quiz mode only enables grading — points, correct answers and feedback are set per question afterwards via update_question with the questionItem.question.grading mask (add_question cannot set them). email_collection_type: DO_NOT_COLLECT, VERIFIED (respondent must be signed in; email verified) or RESPONDER_INPUT (respondent types an email). At least one field is required; only the provided fields are touched.",
|
|
62
61
|
inputSchema: {
|
|
63
62
|
form_id: formIdSchema(),
|
|
64
63
|
is_quiz: z.boolean().optional().describe("Turn quiz mode on/off (enables per-question grading)."),
|
package/dist/tools/items.js
CHANGED
|
@@ -4,7 +4,7 @@ export function registerItemTools(server, client) {
|
|
|
4
4
|
server.registerTool("add_question", {
|
|
5
5
|
title: "Add a question",
|
|
6
6
|
annotations: WRITE,
|
|
7
|
-
description: "Adds a question to the form (a convenience wrapper over batchUpdate createItem). Types: text (short answer), paragraph (long answer), radio (single choice), checkbox (multiple choice), dropdown, scale (linear scale low..high), date, time, rating (stars/hearts/thumbs). Choice types require options[]. Returns the created itemId and questionId from the batchUpdate replies. index inserts at that 0-based position; omit it to append at the end (costs one extra read to count items). File-upload questions cannot be created via the API, and question grids (questionGroupItem) need raw_request with a batchUpdate body.",
|
|
7
|
+
description: "Adds a question to the form (a convenience wrapper over batchUpdate createItem). Types: text (short answer), paragraph (long answer), radio (single choice), checkbox (multiple choice), dropdown, scale (linear scale low..high), date, time, rating (stars/hearts/thumbs). Choice types require options[]. Returns the created itemId and questionId from the batchUpdate replies. index inserts at that 0-based position; omit it to append at the end (costs one extra read to count items). Quiz grading (points, correct answers, feedback) cannot be set here — after adding, use update_question with the questionItem.question.grading mask. File-upload questions cannot be created via the API, and question grids (questionGroupItem) need raw_request with a batchUpdate body.",
|
|
8
8
|
inputSchema: {
|
|
9
9
|
form_id: formIdSchema(),
|
|
10
10
|
title: z.string().min(1).describe("The question text shown to respondents."),
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "mcp-google-forms",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.2.0",
|
|
4
4
|
"description": "MCP server for the Google Forms API — create forms, manage questions, publish, read responses and watch for new submissions. For Claude, Cursor, Codex and other AI clients.",
|
|
5
5
|
"mcpName": "io.github.A1-x-Tech/mcp-google-forms",
|
|
6
6
|
"type": "module",
|
|
@@ -49,6 +49,7 @@
|
|
|
49
49
|
"url": "https://github.com/A1-x-Tech/mcp-google-forms/issues"
|
|
50
50
|
},
|
|
51
51
|
"dependencies": {
|
|
52
|
+
"@a1-x-tech/mcp-google-auth": "^0.1.0",
|
|
52
53
|
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
53
54
|
"zod": "^3.25.0"
|
|
54
55
|
},
|
package/test/dist-smoke.test.js
CHANGED
|
@@ -1,4 +1,7 @@
|
|
|
1
1
|
import assert from "node:assert/strict";
|
|
2
|
+
import { mkdtempSync, rmSync } from "node:fs";
|
|
3
|
+
import { tmpdir } from "node:os";
|
|
4
|
+
import { join } from "node:path";
|
|
2
5
|
import test from "node:test";
|
|
3
6
|
import { fileURLToPath } from "node:url";
|
|
4
7
|
|
|
@@ -11,23 +14,48 @@ import { registerItemTools } from "../dist/tools/items.js";
|
|
|
11
14
|
import { registerResponseTools } from "../dist/tools/responses.js";
|
|
12
15
|
import { registerWatchTools } from "../dist/tools/watches.js";
|
|
13
16
|
import { registerRawTool } from "../dist/tools/raw.js";
|
|
17
|
+
import { registerAuthTools } from "../dist/tools/auth.js";
|
|
14
18
|
|
|
19
|
+
/**
|
|
20
|
+
* Sorted, because every assertion compares it against a sorted tool list. The
|
|
21
|
+
* six onboarding tools come from @a1-x-tech/mcp-google-auth, so this list is
|
|
22
|
+
* also the check that the component is wired into the published binary.
|
|
23
|
+
*/
|
|
15
24
|
const ALL_TOOLS = [
|
|
16
25
|
"add_question",
|
|
26
|
+
"auth_status",
|
|
17
27
|
"create_form",
|
|
18
28
|
"delete_item",
|
|
29
|
+
"finish_login",
|
|
19
30
|
"get_form",
|
|
20
31
|
"get_response",
|
|
21
32
|
"list_responses",
|
|
33
|
+
"logout",
|
|
22
34
|
"manage_watches",
|
|
23
35
|
"move_item",
|
|
24
36
|
"raw_request",
|
|
37
|
+
"set_client",
|
|
25
38
|
"set_publish_settings",
|
|
39
|
+
"setup_instructions",
|
|
40
|
+
"start_login",
|
|
26
41
|
"update_form_info",
|
|
27
42
|
"update_form_settings",
|
|
28
43
|
"update_question",
|
|
29
44
|
];
|
|
30
45
|
|
|
46
|
+
/**
|
|
47
|
+
* A throwaway $XDG_CONFIG_HOME for the spawned server. The auth component
|
|
48
|
+
* re-reads $XDG_CONFIG_HOME/mcp-google-forms/credentials.json per call, so
|
|
49
|
+
* without this a real login on the developer's machine would make the
|
|
50
|
+
* "unconfigured" case pass for the wrong reason.
|
|
51
|
+
*/
|
|
52
|
+
function isolatedConfigDir(t) {
|
|
53
|
+
const dir = mkdtempSync(join(tmpdir(), "mcp-forms-dist-smoke-"));
|
|
54
|
+
t.after(() => rmSync(dir, { recursive: true, force: true }));
|
|
55
|
+
return dir;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
|
|
31
59
|
test("dist client rejects foreign-origin paths before sending the Bearer token", async () => {
|
|
32
60
|
const original = globalThis.fetch;
|
|
33
61
|
let called = false;
|
|
@@ -81,6 +109,7 @@ test("dist registers the expected tools", () => {
|
|
|
81
109
|
};
|
|
82
110
|
const client = {};
|
|
83
111
|
|
|
112
|
+
registerAuthTools(server, client);
|
|
84
113
|
registerFormTools(server, client);
|
|
85
114
|
registerItemTools(server, client);
|
|
86
115
|
registerResponseTools(server, client);
|
|
@@ -90,13 +119,14 @@ test("dist registers the expected tools", () => {
|
|
|
90
119
|
assert.deepEqual(names.sort(), ALL_TOOLS);
|
|
91
120
|
});
|
|
92
121
|
|
|
93
|
-
test("dist binary completes a real MCP handshake over stdio and lists every tool", async () => {
|
|
122
|
+
test("dist binary completes a real MCP handshake over stdio and lists every tool", async (t) => {
|
|
94
123
|
const transport = new StdioClientTransport({
|
|
95
124
|
command: process.execPath,
|
|
96
125
|
args: [fileURLToPath(new URL("../dist/index.js", import.meta.url))],
|
|
97
126
|
env: {
|
|
98
127
|
...process.env,
|
|
99
128
|
GOOGLE_FORMS_ACCESS_TOKEN: "test-token",
|
|
129
|
+
XDG_CONFIG_HOME: isolatedConfigDir(t),
|
|
100
130
|
ASKADS_TELEMETRY: "0", // keep the suite offline
|
|
101
131
|
},
|
|
102
132
|
stderr: "pipe",
|
|
@@ -108,6 +138,12 @@ test("dist binary completes a real MCP handshake over stdio and lists every tool
|
|
|
108
138
|
assert.equal(server?.name, "mcp-google-forms");
|
|
109
139
|
assert.match(String(server?.version), /^\d+\.\d+\.\d+$/);
|
|
110
140
|
|
|
141
|
+
// The instructions the calling model reads before it picks any tool.
|
|
142
|
+
const instructions = client.getInstructions();
|
|
143
|
+
assert.equal(typeof instructions, "string");
|
|
144
|
+
assert.ok(instructions.trim().length > 0, "initialize result carries no instructions");
|
|
145
|
+
assert.match(instructions, /Google Forms API v1/);
|
|
146
|
+
|
|
111
147
|
const { tools } = await client.listTools();
|
|
112
148
|
assert.deepEqual(tools.map((t) => t.name).sort(), ALL_TOOLS);
|
|
113
149
|
|
|
@@ -118,3 +154,49 @@ test("dist binary completes a real MCP handshake over stdio and lists every tool
|
|
|
118
154
|
await client.close();
|
|
119
155
|
}
|
|
120
156
|
});
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* The degraded-start contract: without any credentials the binary used to
|
|
160
|
+
* exit(1) before the handshake, leaving the client a dead server and no reason.
|
|
161
|
+
* It must now start, list every tool, open the instructions with the fix, and
|
|
162
|
+
* answer a tool call with the actionable error — offline: the CredentialsError
|
|
163
|
+
* fires before any fetch, so this test never touches the network.
|
|
164
|
+
*/
|
|
165
|
+
test("dist binary starts without credentials: handshake, tool list, actionable call error", async (t) => {
|
|
166
|
+
const env = Object.fromEntries(
|
|
167
|
+
Object.entries(process.env).filter(
|
|
168
|
+
([key, value]) => value !== undefined && !key.startsWith("GOOGLE_FORMS_"),
|
|
169
|
+
),
|
|
170
|
+
);
|
|
171
|
+
env.ASKADS_TELEMETRY = "0"; // keep the suite offline
|
|
172
|
+
env.XDG_CONFIG_HOME = isolatedConfigDir(t); // ignore any real login on this machine
|
|
173
|
+
const transport = new StdioClientTransport({
|
|
174
|
+
command: process.execPath,
|
|
175
|
+
args: [fileURLToPath(new URL("../dist/index.js", import.meta.url))],
|
|
176
|
+
env,
|
|
177
|
+
stderr: "pipe",
|
|
178
|
+
});
|
|
179
|
+
const client = new Client({ name: "dist-smoke-unconfigured", version: "0.0.0" });
|
|
180
|
+
await client.connect(transport);
|
|
181
|
+
try {
|
|
182
|
+
// The model must read the fix before it picks a tool.
|
|
183
|
+
const instructions = client.getInstructions() ?? "";
|
|
184
|
+
assert.match(instructions, /NOT CONNECTED/);
|
|
185
|
+
assert.match(instructions, /start_login/);
|
|
186
|
+
assert.match(instructions, /GOOGLE_FORMS_CLIENT_ID/);
|
|
187
|
+
assert.match(instructions, /restart/);
|
|
188
|
+
|
|
189
|
+
const { tools } = await client.listTools();
|
|
190
|
+
assert.deepEqual(tools.map((t) => t.name).sort(), ALL_TOOLS);
|
|
191
|
+
|
|
192
|
+
// A tool call fails with the exact message instead of killing the server.
|
|
193
|
+
const result = await client.callTool({ name: "get_form", arguments: { form_id: "smoke-form" } });
|
|
194
|
+
assert.equal(result.isError, true);
|
|
195
|
+
const text = result.content.map((c) => c.text ?? "").join(" ");
|
|
196
|
+
assert.match(text, /not connected/i);
|
|
197
|
+
assert.match(text, /start_login/);
|
|
198
|
+
assert.match(text, /restart the server/);
|
|
199
|
+
} finally {
|
|
200
|
+
await client.close();
|
|
201
|
+
}
|
|
202
|
+
});
|