mcp-google-forms 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 +221 -0
- package/dist/client.js +389 -0
- package/dist/config.js +54 -0
- package/dist/index.js +69 -0
- package/dist/telemetry.js +120 -0
- package/dist/tools/forms.js +106 -0
- package/dist/tools/items.js +131 -0
- package/dist/tools/raw.js +30 -0
- package/dist/tools/responses.js +51 -0
- package/dist/tools/util.js +64 -0
- package/dist/tools/watches.js +57 -0
- package/dist/types.js +44 -0
- package/package.json +60 -0
- package/test/dist-smoke.test.js +120 -0
package/dist/types.js
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The server talks to the Google Forms API v1 (https://forms.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).
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* Google APIs report failures as a non-2xx HTTP status with a JSON envelope
|
|
9
|
+
* ({ error: { code, message, status, details } }); the OAuth token endpoint
|
|
10
|
+
* uses { error, error_description }. The parsed body is kept alongside the
|
|
11
|
+
* status and a short readable message is derived.
|
|
12
|
+
*/
|
|
13
|
+
export class GoogleFormsError extends Error {
|
|
14
|
+
status;
|
|
15
|
+
body;
|
|
16
|
+
constructor(status, body) {
|
|
17
|
+
super(`HTTP ${status}: ${formatErrorBody(body)}`);
|
|
18
|
+
this.name = "GoogleFormsError";
|
|
19
|
+
this.status = status;
|
|
20
|
+
this.body = body;
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
/** Turns a parsed Google API error body into a short, readable message. */
|
|
24
|
+
function formatErrorBody(body) {
|
|
25
|
+
if (body == null)
|
|
26
|
+
return "(no body)";
|
|
27
|
+
if (typeof body === "string")
|
|
28
|
+
return body.slice(0, 500);
|
|
29
|
+
if (typeof body !== "object")
|
|
30
|
+
return String(body);
|
|
31
|
+
const obj = body;
|
|
32
|
+
// OAuth token endpoint style: { error: "invalid_grant", error_description: "..." }
|
|
33
|
+
if (typeof obj.error === "string") {
|
|
34
|
+
const description = typeof obj.error_description === "string" ? `: ${obj.error_description}` : "";
|
|
35
|
+
return `${obj.error}${description}`.slice(0, 500);
|
|
36
|
+
}
|
|
37
|
+
// Google API envelope: { error: { code, message, status, details } }
|
|
38
|
+
const err = (typeof obj.error === "object" && obj.error !== null ? obj.error : obj);
|
|
39
|
+
if (typeof err.message === "string") {
|
|
40
|
+
const status = typeof err.status === "string" ? `[${err.status}] ` : "";
|
|
41
|
+
return `${status}${err.message}`.slice(0, 500);
|
|
42
|
+
}
|
|
43
|
+
return JSON.stringify(obj).slice(0, 500);
|
|
44
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "mcp-google-forms",
|
|
3
|
+
"version": "0.1.0",
|
|
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
|
+
"mcpName": "io.github.A1-x-Tech/mcp-google-forms",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"bin": {
|
|
8
|
+
"mcp-google-forms": "dist/index.js"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"dist",
|
|
12
|
+
"test"
|
|
13
|
+
],
|
|
14
|
+
"engines": {
|
|
15
|
+
"node": ">=20"
|
|
16
|
+
},
|
|
17
|
+
"scripts": {
|
|
18
|
+
"build": "rm -rf dist && tsc",
|
|
19
|
+
"start": "node dist/index.js",
|
|
20
|
+
"dev": "tsx watch src/index.ts",
|
|
21
|
+
"typecheck": "tsc -p tsconfig.check.json",
|
|
22
|
+
"smoke": "node --import tsx src/smoke.ts",
|
|
23
|
+
"test": "npm run test:src && npm run test:dist",
|
|
24
|
+
"test:src": "node --import tsx --test $(find src -name '*.test.ts')",
|
|
25
|
+
"test:dist": "npm run build && node --test test/dist-smoke.test.js",
|
|
26
|
+
"prepare": "npm run build",
|
|
27
|
+
"prepublishOnly": "npm run typecheck && npm test"
|
|
28
|
+
},
|
|
29
|
+
"keywords": [
|
|
30
|
+
"mcp",
|
|
31
|
+
"model-context-protocol",
|
|
32
|
+
"google",
|
|
33
|
+
"google-forms",
|
|
34
|
+
"forms",
|
|
35
|
+
"surveys",
|
|
36
|
+
"quiz",
|
|
37
|
+
"claude",
|
|
38
|
+
"cursor",
|
|
39
|
+
"codex"
|
|
40
|
+
],
|
|
41
|
+
"license": "MIT",
|
|
42
|
+
"author": "gistrec <gistrec@gmail.com>",
|
|
43
|
+
"repository": {
|
|
44
|
+
"type": "git",
|
|
45
|
+
"url": "git+https://github.com/A1-x-Tech/mcp-google-forms.git"
|
|
46
|
+
},
|
|
47
|
+
"homepage": "https://github.com/A1-x-Tech/mcp-google-forms#readme",
|
|
48
|
+
"bugs": {
|
|
49
|
+
"url": "https://github.com/A1-x-Tech/mcp-google-forms/issues"
|
|
50
|
+
},
|
|
51
|
+
"dependencies": {
|
|
52
|
+
"@modelcontextprotocol/sdk": "^1.29.0",
|
|
53
|
+
"zod": "^3.25.0"
|
|
54
|
+
},
|
|
55
|
+
"devDependencies": {
|
|
56
|
+
"@types/node": "^25.9.3",
|
|
57
|
+
"tsx": "^4.22.4",
|
|
58
|
+
"typescript": "^5.7.0"
|
|
59
|
+
}
|
|
60
|
+
}
|
|
@@ -0,0 +1,120 @@
|
|
|
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 { GoogleFormsClient } from "../dist/client.js";
|
|
9
|
+
import { registerFormTools } from "../dist/tools/forms.js";
|
|
10
|
+
import { registerItemTools } from "../dist/tools/items.js";
|
|
11
|
+
import { registerResponseTools } from "../dist/tools/responses.js";
|
|
12
|
+
import { registerWatchTools } from "../dist/tools/watches.js";
|
|
13
|
+
import { registerRawTool } from "../dist/tools/raw.js";
|
|
14
|
+
|
|
15
|
+
const ALL_TOOLS = [
|
|
16
|
+
"add_question",
|
|
17
|
+
"create_form",
|
|
18
|
+
"delete_item",
|
|
19
|
+
"get_form",
|
|
20
|
+
"get_response",
|
|
21
|
+
"list_responses",
|
|
22
|
+
"manage_watches",
|
|
23
|
+
"move_item",
|
|
24
|
+
"raw_request",
|
|
25
|
+
"set_publish_settings",
|
|
26
|
+
"update_form_info",
|
|
27
|
+
"update_form_settings",
|
|
28
|
+
"update_question",
|
|
29
|
+
];
|
|
30
|
+
|
|
31
|
+
test("dist client rejects foreign-origin paths before sending the Bearer token", async () => {
|
|
32
|
+
const original = globalThis.fetch;
|
|
33
|
+
let called = false;
|
|
34
|
+
globalThis.fetch = async () => {
|
|
35
|
+
called = true;
|
|
36
|
+
return new Response("{}", { status: 200 });
|
|
37
|
+
};
|
|
38
|
+
try {
|
|
39
|
+
const client = new GoogleFormsClient({
|
|
40
|
+
accessToken: "SECRET",
|
|
41
|
+
apiBase: "https://forms.googleapis.com",
|
|
42
|
+
timeoutMs: 1000,
|
|
43
|
+
maxRetries: 0,
|
|
44
|
+
});
|
|
45
|
+
await assert.rejects(() => client.request("GET", "https://example.invalid/steal"), /foreign origin/);
|
|
46
|
+
assert.equal(called, false);
|
|
47
|
+
} finally {
|
|
48
|
+
globalThis.fetch = original;
|
|
49
|
+
}
|
|
50
|
+
});
|
|
51
|
+
|
|
52
|
+
test("dist client sends the Bearer token and JSON bodies", async () => {
|
|
53
|
+
const original = globalThis.fetch;
|
|
54
|
+
let seen;
|
|
55
|
+
globalThis.fetch = async (url, init) => {
|
|
56
|
+
seen = { url: String(url), auth: init.headers.Authorization, body: JSON.parse(init.body) };
|
|
57
|
+
return new Response('{"formId":"f-1"}', { status: 200 });
|
|
58
|
+
};
|
|
59
|
+
try {
|
|
60
|
+
const client = new GoogleFormsClient({
|
|
61
|
+
accessToken: "SECRET",
|
|
62
|
+
apiBase: "https://forms.googleapis.com",
|
|
63
|
+
timeoutMs: 1000,
|
|
64
|
+
maxRetries: 0,
|
|
65
|
+
});
|
|
66
|
+
await client.createForm({ title: "Smoke" });
|
|
67
|
+
assert.equal(seen.url, "https://forms.googleapis.com/v1/forms");
|
|
68
|
+
assert.equal(seen.auth, "Bearer SECRET");
|
|
69
|
+
assert.deepEqual(seen.body, { info: { title: "Smoke" } });
|
|
70
|
+
} finally {
|
|
71
|
+
globalThis.fetch = original;
|
|
72
|
+
}
|
|
73
|
+
});
|
|
74
|
+
|
|
75
|
+
test("dist registers the expected tools", () => {
|
|
76
|
+
const names = [];
|
|
77
|
+
const server = {
|
|
78
|
+
registerTool(name) {
|
|
79
|
+
names.push(name);
|
|
80
|
+
},
|
|
81
|
+
};
|
|
82
|
+
const client = {};
|
|
83
|
+
|
|
84
|
+
registerFormTools(server, client);
|
|
85
|
+
registerItemTools(server, client);
|
|
86
|
+
registerResponseTools(server, client);
|
|
87
|
+
registerWatchTools(server, client);
|
|
88
|
+
registerRawTool(server, client);
|
|
89
|
+
|
|
90
|
+
assert.deepEqual(names.sort(), ALL_TOOLS);
|
|
91
|
+
});
|
|
92
|
+
|
|
93
|
+
test("dist binary completes a real MCP handshake over stdio and lists every tool", async () => {
|
|
94
|
+
const transport = new StdioClientTransport({
|
|
95
|
+
command: process.execPath,
|
|
96
|
+
args: [fileURLToPath(new URL("../dist/index.js", import.meta.url))],
|
|
97
|
+
env: {
|
|
98
|
+
...process.env,
|
|
99
|
+
GOOGLE_FORMS_ACCESS_TOKEN: "test-token",
|
|
100
|
+
ASKADS_TELEMETRY: "0", // keep the suite offline
|
|
101
|
+
},
|
|
102
|
+
stderr: "pipe",
|
|
103
|
+
});
|
|
104
|
+
const client = new Client({ name: "dist-smoke", version: "0.0.0" });
|
|
105
|
+
await client.connect(transport);
|
|
106
|
+
try {
|
|
107
|
+
const server = client.getServerVersion();
|
|
108
|
+
assert.equal(server?.name, "mcp-google-forms");
|
|
109
|
+
assert.match(String(server?.version), /^\d+\.\d+\.\d+$/);
|
|
110
|
+
|
|
111
|
+
const { tools } = await client.listTools();
|
|
112
|
+
assert.deepEqual(tools.map((t) => t.name).sort(), ALL_TOOLS);
|
|
113
|
+
|
|
114
|
+
const getForm = tools.find((t) => t.name === "get_form");
|
|
115
|
+
assert.equal(getForm.annotations?.readOnlyHint, true);
|
|
116
|
+
assert.ok(getForm.inputSchema?.properties?.form_id, "input schema must reach the client");
|
|
117
|
+
} finally {
|
|
118
|
+
await client.close();
|
|
119
|
+
}
|
|
120
|
+
});
|