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.
@@ -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
+ }
@@ -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, description and/or document title (the Drive file name). Only the provided fields are touched (the updateMask is computed automatically); at least one field is required. Returns the batchUpdate replies with the new revisionId.",
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, document_title }) => {
49
+ }, async ({ form_id, title, description }) => {
51
50
  try {
52
- return ok(await client.updateFormInfo({ formId: form_id, title, description, documentTitle: document_title }));
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)."),
@@ -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.0.0",
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
  },
@@ -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
+ });