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/index.js
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { readFileSync } from "node:fs";
|
|
3
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
4
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
5
|
+
import { GoogleFormsClient } from "./client.js";
|
|
6
|
+
import { ConfigError, loadConfig } from "./config.js";
|
|
7
|
+
import { instrumentToolCalls, Telemetry } from "./telemetry.js";
|
|
8
|
+
import { registerFormTools } from "./tools/forms.js";
|
|
9
|
+
import { registerItemTools } from "./tools/items.js";
|
|
10
|
+
import { registerResponseTools } from "./tools/responses.js";
|
|
11
|
+
import { registerWatchTools } from "./tools/watches.js";
|
|
12
|
+
import { registerRawTool } from "./tools/raw.js";
|
|
13
|
+
/** Reads the package version so the server reports its real version to MCP clients. */
|
|
14
|
+
function readVersion() {
|
|
15
|
+
try {
|
|
16
|
+
const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
|
|
17
|
+
return typeof pkg.version === "string" ? pkg.version : "0.0.0";
|
|
18
|
+
}
|
|
19
|
+
catch {
|
|
20
|
+
return "0.0.0";
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
/**
|
|
24
|
+
* Loads the config, reporting the drop-off if it is missing. An unconfigured
|
|
25
|
+
* server dies before the MCP handshake, so this ping is the only trace such an
|
|
26
|
+
* install ever leaves — and it has to be awaited, or process.exit() below would
|
|
27
|
+
* kill the request in flight.
|
|
28
|
+
*/
|
|
29
|
+
async function loadConfigOrExit(telemetry) {
|
|
30
|
+
try {
|
|
31
|
+
return loadConfig();
|
|
32
|
+
}
|
|
33
|
+
catch (err) {
|
|
34
|
+
if (!(err instanceof ConfigError))
|
|
35
|
+
throw err;
|
|
36
|
+
console.error(`Error: ${err.message}`);
|
|
37
|
+
await telemetry.sendBlocking("startup_failed", { reason: err.reason });
|
|
38
|
+
process.exit(1);
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
async function main() {
|
|
42
|
+
// Anonymous usage pings (ids/names/versions only, never data or arguments);
|
|
43
|
+
// opt out with ASKADS_TELEMETRY=0. Built before the config so missing
|
|
44
|
+
// credentials can be reported; wired to the server before tools register.
|
|
45
|
+
const telemetry = new Telemetry(readVersion());
|
|
46
|
+
const config = await loadConfigOrExit(telemetry);
|
|
47
|
+
const client = new GoogleFormsClient(config);
|
|
48
|
+
const server = new McpServer({
|
|
49
|
+
name: "mcp-google-forms",
|
|
50
|
+
version: readVersion(),
|
|
51
|
+
});
|
|
52
|
+
instrumentToolCalls(server, telemetry);
|
|
53
|
+
server.server.oninitialized = () => {
|
|
54
|
+
telemetry.setClientInfo(server.server.getClientVersion());
|
|
55
|
+
telemetry.send("server_start");
|
|
56
|
+
};
|
|
57
|
+
registerFormTools(server, client);
|
|
58
|
+
registerItemTools(server, client);
|
|
59
|
+
registerResponseTools(server, client);
|
|
60
|
+
registerWatchTools(server, client);
|
|
61
|
+
registerRawTool(server, client);
|
|
62
|
+
const transport = new StdioServerTransport();
|
|
63
|
+
await server.connect(transport);
|
|
64
|
+
console.error("mcp-google-forms running on stdio");
|
|
65
|
+
}
|
|
66
|
+
main().catch((err) => {
|
|
67
|
+
console.error("Fatal error starting mcp-google-forms:", err);
|
|
68
|
+
process.exit(1);
|
|
69
|
+
});
|
|
@@ -0,0 +1,120 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Anonymous usage telemetry — fire-and-forget pings to usage.gistrec.cloud.
|
|
3
|
+
*
|
|
4
|
+
* Privacy contract (mirrored by the receiver): only an anonymous random
|
|
5
|
+
* instance id, event/tool names, a fixed-vocabulary failure reason and
|
|
6
|
+
* environment versions ever leave the machine. The OAuth credentials, form
|
|
7
|
+
* data, tool arguments, prompts and the names or values of environment
|
|
8
|
+
* variables are never read, serialized or sent. Sends are capped at 2 s and
|
|
9
|
+
* swallow every error — telemetry must never affect the server's operation.
|
|
10
|
+
* Opt out for every server of this line at once: ASKADS_TELEMETRY=0
|
|
11
|
+
* (also accepts false/off/no).
|
|
12
|
+
*/
|
|
13
|
+
import { randomUUID } from "node:crypto";
|
|
14
|
+
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
|
|
15
|
+
import { homedir } from "node:os";
|
|
16
|
+
import { join } from "node:path";
|
|
17
|
+
const ENDPOINT = "https://usage.gistrec.cloud/v1/events";
|
|
18
|
+
const APP = "mcp-google-forms";
|
|
19
|
+
const SEND_TIMEOUT_MS = 2000;
|
|
20
|
+
export function telemetryEnabled(env = process.env) {
|
|
21
|
+
const value = (env.ASKADS_TELEMETRY ?? "").trim().toLowerCase();
|
|
22
|
+
return !["0", "false", "off", "no"].includes(value);
|
|
23
|
+
}
|
|
24
|
+
/**
|
|
25
|
+
* Stable anonymous installation id, persisted under the user's config dir.
|
|
26
|
+
* Any filesystem failure degrades to an ephemeral id: the ping still counts
|
|
27
|
+
* today's activity, just not installation uniqueness across restarts.
|
|
28
|
+
*/
|
|
29
|
+
function loadInstanceId() {
|
|
30
|
+
try {
|
|
31
|
+
const base = process.env.XDG_CONFIG_HOME || join(homedir(), ".config");
|
|
32
|
+
const dir = join(base, APP);
|
|
33
|
+
const file = join(dir, "instance-id");
|
|
34
|
+
try {
|
|
35
|
+
const existing = readFileSync(file, "utf8").trim();
|
|
36
|
+
if (/^[0-9a-f]{8}-[0-9a-f-]{27}$/.test(existing))
|
|
37
|
+
return existing;
|
|
38
|
+
}
|
|
39
|
+
catch {
|
|
40
|
+
// first run — fall through and mint one
|
|
41
|
+
}
|
|
42
|
+
const id = randomUUID();
|
|
43
|
+
mkdirSync(dir, { recursive: true });
|
|
44
|
+
writeFileSync(file, `${id}\n`);
|
|
45
|
+
return id;
|
|
46
|
+
}
|
|
47
|
+
catch {
|
|
48
|
+
return randomUUID();
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
export class Telemetry {
|
|
52
|
+
appVersion;
|
|
53
|
+
enabled;
|
|
54
|
+
fetchImpl;
|
|
55
|
+
instanceId;
|
|
56
|
+
clientInfo;
|
|
57
|
+
constructor(appVersion, enabled = telemetryEnabled(), fetchImpl = fetch) {
|
|
58
|
+
this.appVersion = appVersion;
|
|
59
|
+
this.enabled = enabled;
|
|
60
|
+
this.fetchImpl = fetchImpl;
|
|
61
|
+
this.instanceId = enabled ? loadInstanceId() : "";
|
|
62
|
+
}
|
|
63
|
+
/** The MCP initialize handshake tells us which agent host is on the other side. */
|
|
64
|
+
setClientInfo(info) {
|
|
65
|
+
this.clientInfo = info;
|
|
66
|
+
}
|
|
67
|
+
/** Fire-and-forget: the server's own work never waits on a ping. */
|
|
68
|
+
send(event, fields = {}) {
|
|
69
|
+
void this.post(event, fields);
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* The same ping, awaited. Only for the startup_failed path: that caller
|
|
73
|
+
* calls process.exit() immediately after, which would kill an in-flight
|
|
74
|
+
* fire-and-forget request before it ever left the machine.
|
|
75
|
+
*/
|
|
76
|
+
async sendBlocking(event, fields = {}) {
|
|
77
|
+
await this.post(event, fields);
|
|
78
|
+
}
|
|
79
|
+
async post(event, fields) {
|
|
80
|
+
if (!this.enabled)
|
|
81
|
+
return;
|
|
82
|
+
const body = JSON.stringify({
|
|
83
|
+
app: APP,
|
|
84
|
+
event,
|
|
85
|
+
instance_id: this.instanceId,
|
|
86
|
+
app_version: this.appVersion,
|
|
87
|
+
client_name: this.clientInfo?.name,
|
|
88
|
+
client_version: this.clientInfo?.version,
|
|
89
|
+
tool: fields.tool,
|
|
90
|
+
reason: fields.reason,
|
|
91
|
+
node_version: process.version,
|
|
92
|
+
os: process.platform,
|
|
93
|
+
});
|
|
94
|
+
try {
|
|
95
|
+
await this.fetchImpl(ENDPOINT, {
|
|
96
|
+
method: "POST",
|
|
97
|
+
headers: { "Content-Type": "application/json" },
|
|
98
|
+
body,
|
|
99
|
+
signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
|
|
100
|
+
});
|
|
101
|
+
}
|
|
102
|
+
catch {
|
|
103
|
+
// network failure, timeout abort or a synchronous throw — all silent
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* Count every tool invocation by name. Wraps registerTool once, before the
|
|
109
|
+
* domain modules register their tools, so no per-tool wiring is needed.
|
|
110
|
+
* Only the tool *name* is recorded — arguments never reach telemetry.
|
|
111
|
+
*/
|
|
112
|
+
export function instrumentToolCalls(server, telemetry) {
|
|
113
|
+
const original = server.registerTool.bind(server);
|
|
114
|
+
// registerTool's generic signature does not survive a wrapper; the runtime
|
|
115
|
+
// shape (name, config, callback) is stable per SDK contract.
|
|
116
|
+
server.registerTool = ((name, config, callback) => original(name, config, ((...args) => {
|
|
117
|
+
telemetry.send("tool_call", { tool: name });
|
|
118
|
+
return callback(...args);
|
|
119
|
+
})));
|
|
120
|
+
}
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { fail, formIdSchema, ok, READ_ONLY, UPDATE, WRITE } from "./util.js";
|
|
3
|
+
export function registerFormTools(server, client) {
|
|
4
|
+
server.registerTool("create_form", {
|
|
5
|
+
title: "Create a form",
|
|
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.",
|
|
8
|
+
inputSchema: {
|
|
9
|
+
title: z.string().min(1).describe("The form title shown to respondents."),
|
|
10
|
+
document_title: z
|
|
11
|
+
.string()
|
|
12
|
+
.optional()
|
|
13
|
+
.describe("The document name in Google Drive (defaults to the title)."),
|
|
14
|
+
publish: z
|
|
15
|
+
.boolean()
|
|
16
|
+
.optional()
|
|
17
|
+
.describe("Publish the form right away so it accepts responses (default false — the form stays an unpublished draft)."),
|
|
18
|
+
},
|
|
19
|
+
}, async ({ title, document_title, publish }) => {
|
|
20
|
+
try {
|
|
21
|
+
return ok(await client.createForm({ title, documentTitle: document_title, publish }));
|
|
22
|
+
}
|
|
23
|
+
catch (e) {
|
|
24
|
+
return fail(e);
|
|
25
|
+
}
|
|
26
|
+
});
|
|
27
|
+
server.registerTool("get_form", {
|
|
28
|
+
title: "Get a form",
|
|
29
|
+
annotations: READ_ONLY,
|
|
30
|
+
description: "Returns the full form: info (title, description), settings (quiz mode, email collection), items[] with their itemId/questionId and question definitions, publishSettings, responderUri and linkedSheetId. Items are returned in order — their 0-based positions are the indexes that update_question, delete_item and move_item address, so call this before mutating items.",
|
|
31
|
+
inputSchema: { form_id: formIdSchema() },
|
|
32
|
+
}, async ({ form_id }) => {
|
|
33
|
+
try {
|
|
34
|
+
return ok(await client.getForm(form_id));
|
|
35
|
+
}
|
|
36
|
+
catch (e) {
|
|
37
|
+
return fail(e);
|
|
38
|
+
}
|
|
39
|
+
});
|
|
40
|
+
server.registerTool("update_form_info", {
|
|
41
|
+
title: "Update form info",
|
|
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.",
|
|
44
|
+
inputSchema: {
|
|
45
|
+
form_id: formIdSchema(),
|
|
46
|
+
title: z.string().optional().describe("New form title shown to respondents."),
|
|
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
|
+
},
|
|
50
|
+
}, async ({ form_id, title, description, document_title }) => {
|
|
51
|
+
try {
|
|
52
|
+
return ok(await client.updateFormInfo({ formId: form_id, title, description, documentTitle: document_title }));
|
|
53
|
+
}
|
|
54
|
+
catch (e) {
|
|
55
|
+
return fail(e);
|
|
56
|
+
}
|
|
57
|
+
});
|
|
58
|
+
server.registerTool("update_form_settings", {
|
|
59
|
+
title: "Update form settings",
|
|
60
|
+
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.",
|
|
62
|
+
inputSchema: {
|
|
63
|
+
form_id: formIdSchema(),
|
|
64
|
+
is_quiz: z.boolean().optional().describe("Turn quiz mode on/off (enables per-question grading)."),
|
|
65
|
+
email_collection_type: z
|
|
66
|
+
.enum(["DO_NOT_COLLECT", "VERIFIED", "RESPONDER_INPUT"])
|
|
67
|
+
.optional()
|
|
68
|
+
.describe("How respondent emails are collected."),
|
|
69
|
+
},
|
|
70
|
+
}, async ({ form_id, is_quiz, email_collection_type }) => {
|
|
71
|
+
try {
|
|
72
|
+
return ok(await client.updateFormSettings({
|
|
73
|
+
formId: form_id,
|
|
74
|
+
isQuiz: is_quiz,
|
|
75
|
+
emailCollectionType: email_collection_type,
|
|
76
|
+
}));
|
|
77
|
+
}
|
|
78
|
+
catch (e) {
|
|
79
|
+
return fail(e);
|
|
80
|
+
}
|
|
81
|
+
});
|
|
82
|
+
server.registerTool("set_publish_settings", {
|
|
83
|
+
title: "Publish or unpublish a form",
|
|
84
|
+
annotations: UPDATE,
|
|
85
|
+
description: "Publishes or unpublishes the form and opens/closes response collection. is_accepting_responses defaults to mirroring is_published (publish = start accepting, unpublish = stop). Use is_published=true with is_accepting_responses=false to keep a published form visible but closed. Fails on legacy forms created before the publish model existed — those are managed only in the Forms UI.",
|
|
86
|
+
inputSchema: {
|
|
87
|
+
form_id: formIdSchema(),
|
|
88
|
+
is_published: z.boolean().describe("true = published (respondents can open it), false = unpublished draft."),
|
|
89
|
+
is_accepting_responses: z
|
|
90
|
+
.boolean()
|
|
91
|
+
.optional()
|
|
92
|
+
.describe("Whether the form accepts new responses (defaults to the value of is_published)."),
|
|
93
|
+
},
|
|
94
|
+
}, async ({ form_id, is_published, is_accepting_responses }) => {
|
|
95
|
+
try {
|
|
96
|
+
return ok(await client.setPublishSettings({
|
|
97
|
+
formId: form_id,
|
|
98
|
+
isPublished: is_published,
|
|
99
|
+
isAcceptingResponses: is_accepting_responses,
|
|
100
|
+
}));
|
|
101
|
+
}
|
|
102
|
+
catch (e) {
|
|
103
|
+
return fail(e);
|
|
104
|
+
}
|
|
105
|
+
});
|
|
106
|
+
}
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { DESTRUCTIVE, fail, formIdSchema, itemIndexSchema, ok, UPDATE, WRITE } from "./util.js";
|
|
3
|
+
export function registerItemTools(server, client) {
|
|
4
|
+
server.registerTool("add_question", {
|
|
5
|
+
title: "Add a question",
|
|
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.",
|
|
8
|
+
inputSchema: {
|
|
9
|
+
form_id: formIdSchema(),
|
|
10
|
+
title: z.string().min(1).describe("The question text shown to respondents."),
|
|
11
|
+
type: z
|
|
12
|
+
.enum(["text", "paragraph", "radio", "checkbox", "dropdown", "scale", "date", "time", "rating"])
|
|
13
|
+
.describe("The question type."),
|
|
14
|
+
description: z.string().optional().describe("Help text shown under the question."),
|
|
15
|
+
required: z.boolean().optional().describe("Whether an answer is required to submit."),
|
|
16
|
+
index: z
|
|
17
|
+
.number()
|
|
18
|
+
.int()
|
|
19
|
+
.min(0)
|
|
20
|
+
.optional()
|
|
21
|
+
.describe("0-based position to insert at; omitted = append after the last item."),
|
|
22
|
+
options: z
|
|
23
|
+
.array(z.string().min(1))
|
|
24
|
+
.optional()
|
|
25
|
+
.describe("The choices — required for radio, checkbox and dropdown."),
|
|
26
|
+
shuffle: z.boolean().optional().describe("Shuffle option order per respondent (choice types)."),
|
|
27
|
+
low: z.number().int().optional().describe("Scale lower bound (default 1; scale type)."),
|
|
28
|
+
high: z.number().int().optional().describe("Scale upper bound (default 5; scale type)."),
|
|
29
|
+
low_label: z.string().optional().describe("Label for the lowest scale point."),
|
|
30
|
+
high_label: z.string().optional().describe("Label for the highest scale point."),
|
|
31
|
+
include_time: z.boolean().optional().describe("Date question also asks for a time of day."),
|
|
32
|
+
include_year: z.boolean().optional().describe("Date question includes the year."),
|
|
33
|
+
duration: z
|
|
34
|
+
.boolean()
|
|
35
|
+
.optional()
|
|
36
|
+
.describe("Time question asks for an elapsed duration instead of a time of day."),
|
|
37
|
+
rating_scale_level: z
|
|
38
|
+
.number()
|
|
39
|
+
.int()
|
|
40
|
+
.min(3)
|
|
41
|
+
.max(10)
|
|
42
|
+
.optional()
|
|
43
|
+
.describe("Number of rating icons (3..10; default 5; rating type)."),
|
|
44
|
+
rating_icon_type: z
|
|
45
|
+
.enum(["star", "heart", "thumb_up"])
|
|
46
|
+
.optional()
|
|
47
|
+
.describe("Rating icon (default star)."),
|
|
48
|
+
},
|
|
49
|
+
}, async (args) => {
|
|
50
|
+
try {
|
|
51
|
+
return ok(await client.addQuestion({
|
|
52
|
+
formId: args.form_id,
|
|
53
|
+
title: args.title,
|
|
54
|
+
type: args.type,
|
|
55
|
+
description: args.description,
|
|
56
|
+
required: args.required,
|
|
57
|
+
index: args.index,
|
|
58
|
+
options: args.options,
|
|
59
|
+
shuffle: args.shuffle,
|
|
60
|
+
low: args.low,
|
|
61
|
+
high: args.high,
|
|
62
|
+
lowLabel: args.low_label,
|
|
63
|
+
highLabel: args.high_label,
|
|
64
|
+
includeTime: args.include_time,
|
|
65
|
+
includeYear: args.include_year,
|
|
66
|
+
duration: args.duration,
|
|
67
|
+
ratingScaleLevel: args.rating_scale_level,
|
|
68
|
+
ratingIconType: args.rating_icon_type,
|
|
69
|
+
}));
|
|
70
|
+
}
|
|
71
|
+
catch (e) {
|
|
72
|
+
return fail(e);
|
|
73
|
+
}
|
|
74
|
+
});
|
|
75
|
+
server.registerTool("update_question", {
|
|
76
|
+
title: "Update an item",
|
|
77
|
+
annotations: UPDATE,
|
|
78
|
+
description: 'Updates an existing item (question or other) via batchUpdate updateItem. The item is addressed by its 0-based index — call get_form first to see current positions and the item\'s current shape. item is a raw Forms API Item object with the new values; update_mask names the fields to replace, e.g. "title" or "title,questionItem.question.required". Only masked fields change; masking a field the item object leaves unset clears it.',
|
|
79
|
+
inputSchema: {
|
|
80
|
+
form_id: formIdSchema(),
|
|
81
|
+
index: itemIndexSchema().describe("0-based position of the item to update (from get_form)."),
|
|
82
|
+
item: z
|
|
83
|
+
.record(z.any())
|
|
84
|
+
.describe('The Forms API Item object with the new values, e.g. {"title":"New title","questionItem":{"question":{"required":true}}}.'),
|
|
85
|
+
update_mask: z
|
|
86
|
+
.string()
|
|
87
|
+
.min(1)
|
|
88
|
+
.describe('Comma-separated field paths to replace, e.g. "title,questionItem.question.required".'),
|
|
89
|
+
},
|
|
90
|
+
}, async ({ form_id, index, item, update_mask }) => {
|
|
91
|
+
try {
|
|
92
|
+
return ok(await client.updateItem({ formId: form_id, index, item, updateMask: update_mask }));
|
|
93
|
+
}
|
|
94
|
+
catch (e) {
|
|
95
|
+
return fail(e);
|
|
96
|
+
}
|
|
97
|
+
});
|
|
98
|
+
server.registerTool("delete_item", {
|
|
99
|
+
title: "Delete an item",
|
|
100
|
+
annotations: DESTRUCTIVE,
|
|
101
|
+
description: "Deletes the item at the given 0-based index (question, page break, text block, ...). Deletion shifts every later item one position down — re-check indexes with get_form between successive deletes.",
|
|
102
|
+
inputSchema: {
|
|
103
|
+
form_id: formIdSchema(),
|
|
104
|
+
index: itemIndexSchema().describe("0-based position of the item to delete (from get_form)."),
|
|
105
|
+
},
|
|
106
|
+
}, async ({ form_id, index }) => {
|
|
107
|
+
try {
|
|
108
|
+
return ok(await client.deleteItem(form_id, index));
|
|
109
|
+
}
|
|
110
|
+
catch (e) {
|
|
111
|
+
return fail(e);
|
|
112
|
+
}
|
|
113
|
+
});
|
|
114
|
+
server.registerTool("move_item", {
|
|
115
|
+
title: "Move an item",
|
|
116
|
+
annotations: WRITE,
|
|
117
|
+
description: "Moves the item at from_index to to_index (both 0-based, to_index is the position after removal). Use get_form to see the current order first.",
|
|
118
|
+
inputSchema: {
|
|
119
|
+
form_id: formIdSchema(),
|
|
120
|
+
from_index: itemIndexSchema().describe("Current 0-based position of the item."),
|
|
121
|
+
to_index: itemIndexSchema().describe("Target 0-based position."),
|
|
122
|
+
},
|
|
123
|
+
}, async ({ form_id, from_index, to_index }) => {
|
|
124
|
+
try {
|
|
125
|
+
return ok(await client.moveItem(form_id, from_index, to_index));
|
|
126
|
+
}
|
|
127
|
+
catch (e) {
|
|
128
|
+
return fail(e);
|
|
129
|
+
}
|
|
130
|
+
});
|
|
131
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { DESTRUCTIVE, fail, ok } from "./util.js";
|
|
3
|
+
export function registerRawTool(server, client) {
|
|
4
|
+
server.registerTool("raw_request", {
|
|
5
|
+
title: "Raw Google Forms API call",
|
|
6
|
+
// Full API surface incl. batchUpdate and watch deletion — annotate for the
|
|
7
|
+
// worst case a call can do, not the average.
|
|
8
|
+
annotations: DESTRUCTIVE,
|
|
9
|
+
description: 'Escape hatch to call any Google Forms API v1 path directly, for requests the typed tools don\'t cover — e.g. a batchUpdate with questionGroupItem grids, writeControl/requiredRevisionId, includeFormInResponse, or several requests at once: path "v1/forms/<formId>:batchUpdate", method POST, body {"requests":[...]}. The path may carry a query string (e.g. "v1/forms/<id>/responses?filter=timestamp%20%3E%202026-08-01T00:00:00Z"). The Bearer token is added automatically; the method defaults to GET.',
|
|
10
|
+
inputSchema: {
|
|
11
|
+
path: z
|
|
12
|
+
.string()
|
|
13
|
+
.min(1)
|
|
14
|
+
.describe('API path relative to https://forms.googleapis.com, e.g. "v1/forms/<formId>:batchUpdate".'),
|
|
15
|
+
method: z
|
|
16
|
+
.enum(["GET", "POST", "DELETE"])
|
|
17
|
+
.optional()
|
|
18
|
+
.describe("HTTP method (the Forms API uses only these three). Defaults to GET."),
|
|
19
|
+
body: z.record(z.any()).optional().describe("JSON request body (POST only)."),
|
|
20
|
+
},
|
|
21
|
+
}, async ({ path, method, body }) => {
|
|
22
|
+
try {
|
|
23
|
+
const m = (method ?? "GET");
|
|
24
|
+
return ok(await client.request(m, path, body));
|
|
25
|
+
}
|
|
26
|
+
catch (e) {
|
|
27
|
+
return fail(e);
|
|
28
|
+
}
|
|
29
|
+
});
|
|
30
|
+
}
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { fail, formIdSchema, ok, READ_ONLY, rfc3339Timestamp } from "./util.js";
|
|
3
|
+
export function registerResponseTools(server, client) {
|
|
4
|
+
server.registerTool("list_responses", {
|
|
5
|
+
title: "List form responses",
|
|
6
|
+
annotations: READ_ONLY,
|
|
7
|
+
description: "Lists submitted responses: responseId, createTime, lastSubmittedTime, respondentEmail (only when email collection is on), answers keyed by questionId (map questionId → question via get_form), and totalScore for graded quizzes. submitted_after keeps only responses submitted strictly after that RFC3339 UTC timestamp — the API's only filter; there is no ordering or email filter, do that client-side. Paginate with page_token from nextPageToken. Note: this endpoint has a lower per-minute quota than other reads — poll incrementally with submitted_after rather than re-listing everything. The API is read-only for responses; submitting them programmatically is impossible.",
|
|
8
|
+
inputSchema: {
|
|
9
|
+
form_id: formIdSchema(),
|
|
10
|
+
submitted_after: rfc3339Timestamp()
|
|
11
|
+
.optional()
|
|
12
|
+
.describe("Only responses submitted after this RFC3339 UTC timestamp, e.g. 2026-08-01T00:00:00Z (exclusive)."),
|
|
13
|
+
page_size: z
|
|
14
|
+
.number()
|
|
15
|
+
.int()
|
|
16
|
+
.min(1)
|
|
17
|
+
.max(5000)
|
|
18
|
+
.optional()
|
|
19
|
+
.describe("Max responses per page (1..5000; the API's default and max is 5000)."),
|
|
20
|
+
page_token: z.string().optional().describe("nextPageToken from the previous page."),
|
|
21
|
+
},
|
|
22
|
+
}, async ({ form_id, submitted_after, page_size, page_token }) => {
|
|
23
|
+
try {
|
|
24
|
+
return ok(await client.listResponses({
|
|
25
|
+
formId: form_id,
|
|
26
|
+
submittedAfter: submitted_after,
|
|
27
|
+
pageSize: page_size,
|
|
28
|
+
pageToken: page_token,
|
|
29
|
+
}));
|
|
30
|
+
}
|
|
31
|
+
catch (e) {
|
|
32
|
+
return fail(e);
|
|
33
|
+
}
|
|
34
|
+
});
|
|
35
|
+
server.registerTool("get_response", {
|
|
36
|
+
title: "Get one response",
|
|
37
|
+
annotations: READ_ONLY,
|
|
38
|
+
description: "Fetches a single submission by its responseId (from list_responses): answers keyed by questionId, createTime, lastSubmittedTime, respondentEmail and totalScore when available. Map questionId to the question text via get_form.",
|
|
39
|
+
inputSchema: {
|
|
40
|
+
form_id: formIdSchema(),
|
|
41
|
+
response_id: z.string().min(1).describe("The response id from list_responses."),
|
|
42
|
+
},
|
|
43
|
+
}, async ({ form_id, response_id }) => {
|
|
44
|
+
try {
|
|
45
|
+
return ok(await client.getResponse(form_id, response_id));
|
|
46
|
+
}
|
|
47
|
+
catch (e) {
|
|
48
|
+
return fail(e);
|
|
49
|
+
}
|
|
50
|
+
});
|
|
51
|
+
}
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
/**
|
|
3
|
+
* Schema factories, not shared consts: reusing one zod object across two fields
|
|
4
|
+
* makes zod-to-json-schema dedupe them into a `$ref`, which some tool-schema
|
|
5
|
+
* consumers (OpenAI Apps review) don't dereference and flag as `any`. A fresh
|
|
6
|
+
* object per field keeps each one inlined with its type + pattern.
|
|
7
|
+
*/
|
|
8
|
+
export const formIdSchema = () => z
|
|
9
|
+
.string()
|
|
10
|
+
.min(1)
|
|
11
|
+
.describe("The form id — the long id from the form URL (docs.google.com/forms/d/<formId>/edit) or from create_form output.");
|
|
12
|
+
/** An RFC3339 UTC timestamp, e.g. 2026-08-01T00:00:00Z — the shape the responses filter accepts. */
|
|
13
|
+
export const rfc3339Timestamp = () => z
|
|
14
|
+
.string()
|
|
15
|
+
.regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/, "Must be an RFC3339 timestamp, e.g. 2026-08-01T00:00:00Z");
|
|
16
|
+
/** A 0-based item index — items are addressed by position, not by itemId. */
|
|
17
|
+
export const itemIndexSchema = () => z.number().int().min(0);
|
|
18
|
+
/** Wraps a value as a compact-JSON tool result (compact: the consumer is an LLM). */
|
|
19
|
+
export function ok(data) {
|
|
20
|
+
const text = typeof data === "string" ? data : JSON.stringify(data);
|
|
21
|
+
return { content: [{ type: "text", text: text ?? "null" }] };
|
|
22
|
+
}
|
|
23
|
+
export function fail(err) {
|
|
24
|
+
let message = err instanceof Error ? err.message : String(err);
|
|
25
|
+
// Surface the underlying cause (e.g. the network error behind a timeout) — no
|
|
26
|
+
// secrets live in cause, and it makes failures far easier to diagnose.
|
|
27
|
+
if (err instanceof Error && err.cause instanceof Error)
|
|
28
|
+
message += ` (${err.cause.message})`;
|
|
29
|
+
return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
|
|
30
|
+
}
|
|
31
|
+
/**
|
|
32
|
+
* MCP tool annotations — hints the consuming client can use to gate or label a
|
|
33
|
+
* tool. All four hints are set explicitly on every tool: some clients (OpenAI
|
|
34
|
+
* Apps review) require readOnlyHint, destructiveHint and openWorldHint on each.
|
|
35
|
+
*
|
|
36
|
+
* The Forms API mixes reads and writes, so each tool picks one of four presets:
|
|
37
|
+
* READ_ONLY (pure reads), WRITE (creates new state; replaying duplicates it),
|
|
38
|
+
* UPDATE (overwrites existing fields; replaying the same update converges) and
|
|
39
|
+
* DESTRUCTIVE (removes existing state; replaying hits different targets).
|
|
40
|
+
*/
|
|
41
|
+
export const READ_ONLY = {
|
|
42
|
+
readOnlyHint: true,
|
|
43
|
+
destructiveHint: false,
|
|
44
|
+
idempotentHint: true,
|
|
45
|
+
openWorldHint: true,
|
|
46
|
+
};
|
|
47
|
+
export const WRITE = {
|
|
48
|
+
readOnlyHint: false,
|
|
49
|
+
destructiveHint: false,
|
|
50
|
+
idempotentHint: false,
|
|
51
|
+
openWorldHint: true,
|
|
52
|
+
};
|
|
53
|
+
export const UPDATE = {
|
|
54
|
+
readOnlyHint: false,
|
|
55
|
+
destructiveHint: true,
|
|
56
|
+
idempotentHint: true,
|
|
57
|
+
openWorldHint: true,
|
|
58
|
+
};
|
|
59
|
+
export const DESTRUCTIVE = {
|
|
60
|
+
readOnlyHint: false,
|
|
61
|
+
destructiveHint: true,
|
|
62
|
+
idempotentHint: false,
|
|
63
|
+
openWorldHint: true,
|
|
64
|
+
};
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
import { DESTRUCTIVE, fail, formIdSchema, ok } from "./util.js";
|
|
3
|
+
export function registerWatchTools(server, client) {
|
|
4
|
+
server.registerTool("manage_watches", {
|
|
5
|
+
title: "Manage push-notification watches",
|
|
6
|
+
// One tool covers create/list/delete/renew; delete removes state, so the
|
|
7
|
+
// whole tool carries the destructive, non-idempotent hints.
|
|
8
|
+
annotations: DESTRUCTIVE,
|
|
9
|
+
description: "Manages Cloud Pub/Sub push-notification watches on a form. action=create needs event_type (RESPONSES = new submissions, SCHEMA = form structure changes) and topic_name; the topic must live in your Cloud project and grant the Pub/Sub Publisher role to forms-notifications@system.gserviceaccount.com. action=list shows your watches; delete and renew need watch_id. Watches expire after 7 days — renew extends 7 days from now and reactivates a SUSPENDED watch. Notifications carry only formId/watchId/eventType attributes (no payload): on RESPONSES call list_responses with submitted_after, on SCHEMA call get_form. Limits: 1 watch per user per form+event type, 20 per Cloud project.",
|
|
10
|
+
inputSchema: {
|
|
11
|
+
form_id: formIdSchema(),
|
|
12
|
+
action: z.enum(["create", "list", "delete", "renew"]).describe("What to do with the form's watches."),
|
|
13
|
+
event_type: z
|
|
14
|
+
.enum(["RESPONSES", "SCHEMA"])
|
|
15
|
+
.optional()
|
|
16
|
+
.describe("create only: RESPONSES (new submissions) or SCHEMA (form structure/settings changes)."),
|
|
17
|
+
topic_name: z
|
|
18
|
+
.string()
|
|
19
|
+
.regex(/^projects\/[^/]+\/topics\/[^/]+$/, "Must look like projects/<project>/topics/<topic>")
|
|
20
|
+
.optional()
|
|
21
|
+
.describe("create only: the Cloud Pub/Sub topic, e.g. projects/my-project/topics/forms-events."),
|
|
22
|
+
watch_id: z
|
|
23
|
+
.string()
|
|
24
|
+
.regex(/^[a-z0-9-]{4,63}$/, "4-63 chars of [a-z0-9-]")
|
|
25
|
+
.optional()
|
|
26
|
+
.describe("delete/renew: the watch to target. create: optional custom id (auto-generated if omitted)."),
|
|
27
|
+
},
|
|
28
|
+
}, async ({ form_id, action, event_type, topic_name, watch_id }) => {
|
|
29
|
+
try {
|
|
30
|
+
switch (action) {
|
|
31
|
+
case "create":
|
|
32
|
+
if (!event_type || !topic_name) {
|
|
33
|
+
return fail(new Error('action "create" requires event_type and topic_name.'));
|
|
34
|
+
}
|
|
35
|
+
return ok(await client.createWatch({
|
|
36
|
+
formId: form_id,
|
|
37
|
+
eventType: event_type,
|
|
38
|
+
topicName: topic_name,
|
|
39
|
+
watchId: watch_id,
|
|
40
|
+
}));
|
|
41
|
+
case "list":
|
|
42
|
+
return ok(await client.listWatches(form_id));
|
|
43
|
+
case "delete":
|
|
44
|
+
if (!watch_id)
|
|
45
|
+
return fail(new Error('action "delete" requires watch_id.'));
|
|
46
|
+
return ok(await client.deleteWatch(form_id, watch_id));
|
|
47
|
+
case "renew":
|
|
48
|
+
if (!watch_id)
|
|
49
|
+
return fail(new Error('action "renew" requires watch_id.'));
|
|
50
|
+
return ok(await client.renewWatch(form_id, watch_id));
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
catch (e) {
|
|
54
|
+
return fail(e);
|
|
55
|
+
}
|
|
56
|
+
});
|
|
57
|
+
}
|