google-tools-mcp 1.0.2 → 1.0.3

package/README.md

@@ -13,6 +13,7 @@ Most Google MCP servers split functionality across separate packages. This serve
 - **146 tools** across 8 categories, all available immediately
 - **Single auth token** — one OAuth flow covers Drive, Docs, Sheets, Gmail, and Calendar
 - **Lazy-loading auth** — no browser popup until your first tool call
+- **No lazy tool loading** — all 146 tools are registered eagerly at startup since most MCP clients (including Claude Code) don't support `notifications/tools/list_changed`
 - **Multi-profile support** — separate tokens per Google account
 - **No telemetry**
 

package/dist/auth.js

@@ -48,6 +48,10 @@ const SCOPES = [
     'https://www.googleapis.com/auth/gmail.settings.sharing',
     // Calendar
     'https://www.googleapis.com/auth/calendar',
+    // Forms
+    'https://www.googleapis.com/auth/forms.body',
+    'https://www.googleapis.com/auth/forms.body.readonly',
+    'https://www.googleapis.com/auth/forms.responses.readonly',
 ];
 
 // ---------------------------------------------------------------------------

package/dist/clients.js

@@ -12,6 +12,7 @@ let googleSheets = null;
 let googleScript = null;
 let gmailClient = null;
 let calendarClient = null;
+let formsClient = null;
 
 async function ensureAuth() {
     if (authClient) return;
@@ -58,6 +59,14 @@ export async function initializeCalendarClient() {
     return { authClient, calendarClient };
 }
 
+// --- Forms client ---
+export async function initializeFormsClient() {
+    if (formsClient) return { authClient, formsClient };
+    await ensureAuth();
+    if (!formsClient) formsClient = google.forms({ version: 'v1', auth: authClient });
+    return { authClient, formsClient };
+}
+
 // --- Reset all clients (used by logout) ---
 export function resetClients() {
     authClient = null;
@@ -67,6 +76,7 @@ export function resetClients() {
     googleScript = null;
     gmailClient = null;
     calendarClient = null;
+    formsClient = null;
 }
 
 // --- Individual client getters ---
@@ -111,3 +121,9 @@ export async function getCalendarClient() {
     if (!calendar) throw new UserError('Google Calendar client is not initialized.');
     return calendar;
 }
+
+export async function getFormsClient() {
+    const { formsClient: forms } = await initializeFormsClient();
+    if (!forms) throw new UserError('Google Forms client is not initialized.');
+    return forms;
+}

package/dist/tools/forms/batchUpdateForm.js

@@ -0,0 +1,80 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getFormsClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'batch_update_form',
+        description:
+            'Applies one or more updates to a Google Form. Supports creating, updating, deleting, and moving items, as well as updating form info and settings. ' +
+            'Each request in the array should be an object with exactly one key: createItem, updateItem, deleteItem, moveItem, updateFormInfo, or updateSettings. ' +
+            'See the Google Forms API batchUpdate documentation for the full request schema.',
+        parameters: z.object({
+            formId: z.string().describe('The ID of the Google Form to update'),
+            requests: z
+                .array(z.record(z.any()))
+                .min(1)
+                .describe(
+                    'Array of update requests. Each object should have one key: createItem, updateItem, deleteItem, moveItem, updateFormInfo, or updateSettings',
+                ),
+        }),
+        execute: async (args, { log }) => {
+            const forms = await getFormsClient();
+            log.info(`Batch updating form ${args.formId} with ${args.requests.length} request(s)`);
+
+            const validKeys = new Set([
+                'createItem',
+                'updateItem',
+                'deleteItem',
+                'moveItem',
+                'updateFormInfo',
+                'updateSettings',
+            ]);
+
+            for (const req of args.requests) {
+                const keys = Object.keys(req);
+                if (keys.length !== 1 || !validKeys.has(keys[0])) {
+                    throw new UserError(
+                        `Invalid request object. Each request must have exactly one key from: ${[...validKeys].join(', ')}. Got: ${keys.join(', ')}`,
+                    );
+                }
+            }
+
+            try {
+                const response = await forms.forms.batchUpdate({
+                    formId: args.formId,
+                    requestBody: { requests: args.requests },
+                });
+                const data = response.data;
+                const replies = data.replies || [];
+
+                const result = {
+                    requestsApplied: args.requests.length,
+                    repliesReceived: replies.length,
+                };
+
+                const createdItems = [];
+                for (const reply of replies) {
+                    if (reply.createItem) {
+                        const ci = reply.createItem;
+                        createdItems.push({
+                            itemId: ci.itemId,
+                            questionId: ci.questionId?.[0] || null,
+                        });
+                    }
+                }
+                if (createdItems.length > 0) {
+                    result.createdItems = createdItems;
+                }
+
+                return JSON.stringify(result, null, 2);
+            } catch (error) {
+                log.error(`Error batch updating form: ${error.message || error}`);
+                if (error.code === 401)
+                    throw new UserError('Authentication failed. Try logging out and re-authenticating.');
+                if (error.code === 404) throw new UserError(`Form not found: ${args.formId}`);
+                throw new UserError(`Failed to batch update form: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/forms/createForm.js

@@ -0,0 +1,54 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getFormsClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'create_form',
+        description:
+            'Creates a new Google Form with a title and optional description. Returns the form ID, edit URL, and responder URL.',
+        parameters: z.object({
+            title: z.string().describe('The title of the form (shown to respondents)'),
+            description: z.string().optional().describe('A description displayed at the top of the form'),
+            documentTitle: z
+                .string()
+                .optional()
+                .describe('The document title (shown in Drive). Defaults to the form title if not provided'),
+        }),
+        execute: async (args, { log }) => {
+            const forms = await getFormsClient();
+            log.info(`Creating form: ${args.title}`);
+
+            const body = {
+                info: {
+                    title: args.title,
+                    documentTitle: args.documentTitle || args.title,
+                },
+            };
+            if (args.description) {
+                body.info.description = args.description;
+            }
+
+            try {
+                const response = await forms.forms.create({ requestBody: body });
+                const form = response.data;
+
+                return JSON.stringify(
+                    {
+                        formId: form.formId,
+                        title: form.info?.title,
+                        editUrl: `https://docs.google.com/forms/d/${form.formId}/edit`,
+                        responderUrl: form.responderUri || `https://docs.google.com/forms/d/${form.formId}/viewform`,
+                    },
+                    null,
+                    2,
+                );
+            } catch (error) {
+                log.error(`Error creating form: ${error.message || error}`);
+                if (error.code === 401)
+                    throw new UserError('Authentication failed. Try logging out and re-authenticating.');
+                throw new UserError(`Failed to create form: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/forms/getForm.js

@@ -0,0 +1,118 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getFormsClient } from '../../clients.js';
+
+function extractOptionValues(options) {
+    if (!options) return [];
+    return options.filter((o) => o.value).map((o) => {
+        const opt = { value: o.value };
+        if (o.isOther) opt.isOther = true;
+        if (o.image) opt.image = o.image;
+        if (o.goToAction) opt.goToAction = o.goToAction;
+        if (o.goToSectionId) opt.goToSectionId = o.goToSectionId;
+        return opt;
+    });
+}
+
+function getQuestionType(question) {
+    if (question.choiceQuestion) return question.choiceQuestion.type || 'RADIO';
+    if (question.textQuestion) {
+        return question.textQuestion.paragraph ? 'PARAGRAPH' : 'TEXT';
+    }
+    if (question.scaleQuestion) return 'SCALE';
+    if (question.dateQuestion) return 'DATE';
+    if (question.timeQuestion) return 'TIME';
+    if (question.fileUploadQuestion) return 'FILE_UPLOAD';
+    if (question.ratingQuestion) return 'RATING';
+    if (question.rowQuestion) return 'GRID_ROW';
+    return 'QUESTION';
+}
+
+function serializeFormItem(item, index) {
+    const result = {
+        index,
+        itemId: item.itemId,
+        title: item.title || '',
+        description: item.description || '',
+    };
+
+    if (item.questionItem) {
+        const q = item.questionItem.question;
+        result.type = getQuestionType(q);
+        result.required = q.required || false;
+        result.questionId = q.questionId || null;
+        if (q.choiceQuestion) {
+            result.options = extractOptionValues(q.choiceQuestion.options);
+        }
+    } else if (item.questionGroupItem) {
+        const group = item.questionGroupItem;
+        result.type = 'GRID';
+        result.grid = {
+            columns: group.grid?.columns?.options
+                ? extractOptionValues(group.grid.columns.options)
+                : [],
+        };
+        if (group.questions) {
+            result.grid.rows = group.questions.map((q) => ({
+                questionId: q.questionId,
+                title: q.rowQuestion?.title || '',
+                required: q.required || false,
+            }));
+        }
+    } else if (item.pageBreakItem !== undefined) {
+        result.type = 'PAGE_BREAK';
+    } else if (item.textItem !== undefined) {
+        result.type = 'TEXT_ITEM';
+    } else if (item.imageItem) {
+        result.type = 'IMAGE';
+    } else if (item.videoItem) {
+        result.type = 'VIDEO';
+    } else {
+        result.type = 'UNKNOWN';
+    }
+
+    return result;
+}
+
+export function register(server) {
+    server.addTool({
+        name: 'get_form',
+        description:
+            'Retrieves a Google Form by ID. Returns the form title, description, URLs, and all items (questions, sections, images, etc.) with their types, options, and metadata.',
+        parameters: z.object({
+            formId: z.string().describe('The ID of the Google Form to retrieve'),
+        }),
+        execute: async (args, { log }) => {
+            const forms = await getFormsClient();
+            log.info(`Getting form: ${args.formId}`);
+
+            try {
+                const response = await forms.forms.get({ formId: args.formId });
+                const form = response.data;
+                const items = (form.items || []).map((item, i) => serializeFormItem(item, i));
+
+                return JSON.stringify(
+                    {
+                        formId: form.formId,
+                        title: form.info?.title || '',
+                        description: form.info?.description || '',
+                        documentTitle: form.info?.documentTitle || '',
+                        editUrl: `https://docs.google.com/forms/d/${form.formId}/edit`,
+                        responderUrl:
+                            form.responderUri || `https://docs.google.com/forms/d/${form.formId}/viewform`,
+                        itemCount: items.length,
+                        items,
+                    },
+                    null,
+                    2,
+                );
+            } catch (error) {
+                log.error(`Error getting form: ${error.message || error}`);
+                if (error.code === 401)
+                    throw new UserError('Authentication failed. Try logging out and re-authenticating.');
+                if (error.code === 404) throw new UserError(`Form not found: ${args.formId}`);
+                throw new UserError(`Failed to get form: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/forms/getFormResponse.js

@@ -0,0 +1,45 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getFormsClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'get_form_response',
+        description:
+            'Retrieves a single response from a Google Form by response ID. Returns the response timestamps and all answers keyed by question ID.',
+        parameters: z.object({
+            formId: z.string().describe('The ID of the Google Form'),
+            responseId: z.string().describe('The ID of the specific response to retrieve'),
+        }),
+        execute: async (args, { log }) => {
+            const forms = await getFormsClient();
+            log.info(`Getting response ${args.responseId} for form: ${args.formId}`);
+
+            try {
+                const response = await forms.forms.responses.get({
+                    formId: args.formId,
+                    responseId: args.responseId,
+                });
+                const r = response.data;
+
+                return JSON.stringify(
+                    {
+                        responseId: r.responseId,
+                        createTime: r.createTime,
+                        lastSubmittedTime: r.lastSubmittedTime,
+                        answers: r.answers || {},
+                    },
+                    null,
+                    2,
+                );
+            } catch (error) {
+                log.error(`Error getting form response: ${error.message || error}`);
+                if (error.code === 401)
+                    throw new UserError('Authentication failed. Try logging out and re-authenticating.');
+                if (error.code === 404)
+                    throw new UserError(`Form or response not found: ${args.formId} / ${args.responseId}`);
+                throw new UserError(`Failed to get form response: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/forms/index.js

@@ -0,0 +1,15 @@
+import { register as createForm } from './createForm.js';
+import { register as getForm } from './getForm.js';
+import { register as listFormResponses } from './listFormResponses.js';
+import { register as getFormResponse } from './getFormResponse.js';
+import { register as batchUpdateForm } from './batchUpdateForm.js';
+import { register as setPublishSettings } from './setPublishSettings.js';
+
+export function registerFormsTools(server) {
+    createForm(server);
+    getForm(server);
+    listFormResponses(server);
+    getFormResponse(server);
+    batchUpdateForm(server);
+    setPublishSettings(server);
+}

package/dist/tools/forms/listFormResponses.js

@@ -0,0 +1,56 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getFormsClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'list_form_responses',
+        description:
+            'Lists responses submitted to a Google Form. Returns a paginated list of responses with timestamps and answers.',
+        parameters: z.object({
+            formId: z.string().describe('The ID of the Google Form'),
+            pageSize: z
+                .number()
+                .min(1)
+                .max(5000)
+                .optional()
+                .describe('Number of responses to return per page (default 10, max 5000)'),
+            pageToken: z.string().optional().describe('Token for fetching the next page of results'),
+        }),
+        execute: async (args, { log }) => {
+            const forms = await getFormsClient();
+            log.info(`Listing responses for form: ${args.formId}`);
+
+            const params = { formId: args.formId };
+            if (args.pageSize) params.pageSize = args.pageSize;
+            if (args.pageToken) params.pageToken = args.pageToken;
+
+            try {
+                const response = await forms.forms.responses.list(params);
+                const data = response.data;
+                const responses = (data.responses || []).map((r) => ({
+                    responseId: r.responseId,
+                    createTime: r.createTime,
+                    lastSubmittedTime: r.lastSubmittedTime,
+                    answers: r.answers || {},
+                }));
+
+                return JSON.stringify(
+                    {
+                        totalResponses: responses.length,
+                        nextPageToken: data.nextPageToken || null,
+                        responses,
+                    },
+                    null,
+                    2,
+                );
+            } catch (error) {
+                log.error(`Error listing form responses: ${error.message || error}`);
+                if (error.code === 401)
+                    throw new UserError('Authentication failed. Try logging out and re-authenticating.');
+                if (error.code === 404) throw new UserError(`Form not found: ${args.formId}`);
+                throw new UserError(`Failed to list form responses: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/forms/setPublishSettings.js

@@ -0,0 +1,58 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getFormsClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'set_publish_settings',
+        description:
+            'Updates the publish settings of a Google Form. Controls whether the form is published as a template and whether respondents must be authenticated.',
+        parameters: z.object({
+            formId: z.string().describe('The ID of the Google Form'),
+            publishAsTemplate: z
+                .boolean()
+                .optional()
+                .describe('Whether to publish the form as a reusable template'),
+            requireAuthentication: z
+                .boolean()
+                .optional()
+                .describe('Whether respondents must sign in with a Google account to submit the form'),
+        }),
+        execute: async (args, { log }) => {
+            const forms = await getFormsClient();
+            log.info(`Setting publish settings for form: ${args.formId}`);
+
+            const body = {};
+            if (args.publishAsTemplate !== undefined) {
+                body.publishAsTemplate = args.publishAsTemplate;
+            }
+            if (args.requireAuthentication !== undefined) {
+                body.requireAuthentication = args.requireAuthentication;
+            }
+
+            if (Object.keys(body).length === 0) {
+                throw new UserError('At least one setting (publishAsTemplate or requireAuthentication) must be provided.');
+            }
+
+            try {
+                await forms.forms.setPublishSettings({
+                    formId: args.formId,
+                    requestBody: body,
+                });
+
+                return JSON.stringify({
+                    success: true,
+                    formId: args.formId,
+                    message: 'Publish settings updated successfully.',
+                    appliedSettings: body,
+                }, null, 2);
+            } catch (error) {
+                log.error(`Error setting publish settings: ${error.message || error}`);
+                if (error.code === 401)
+                    throw new UserError('Authentication failed. Try logging out and re-authenticating.');
+                if (error.code === 404) throw new UserError(`Form not found: ${args.formId}`);
+                throw new UserError(`Failed to set publish settings: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/index.js

@@ -63,6 +63,12 @@ const CATEGORIES = {
             registerCalendarTools(server);
         },
     },
+    forms: {
+        async loader(server) {
+            const { registerFormsTools } = await import('./forms/index.js');
+            registerFormsTools(server);
+        },
+    },
 };
 
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "google-tools-mcp",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Combined Google Workspace MCP server (Drive, Docs, Sheets, Gmail) with lazy-loaded tool categories",
   "type": "module",
   "bin": {