google-tools-mcp 1.0.7 → 1.0.9

package/README.md

@@ -1,6 +1,6 @@
 # google-tools-mcp
 
-A unified MCP server for Google Workspace — Drive, Docs, Sheets, Gmail, and Calendar — with **146 tools** across 8 categories.
+A unified MCP server for Google Workspace — Drive, Docs, Sheets, Gmail, Calendar, and Forms — with **152 tools** across 9 categories.
 
 All tools are loaded at startup so they're immediately available to your AI agent. No discovery step needed.
 
@@ -10,10 +10,10 @@ Most Google MCP servers split functionality across separate packages. This serve
 
 ## Features
 
-- **146 tools** across 8 categories, all available immediately
-- **Single auth token** — one OAuth flow covers Drive, Docs, Sheets, Gmail, and Calendar
+- **152 tools** across 9 categories, all available immediately
+- **Single auth token** — one OAuth flow covers Drive, Docs, Sheets, Gmail, Calendar, and Forms
 - **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`
+- **No lazy tool loading** — all 150 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**
 
@@ -23,10 +23,11 @@ Most Google MCP servers split functionality across separate packages. This serve
 
 1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
 2. Create a project (or use an existing one)
-3. Enable the **Google Docs API**, **Google Sheets API**, **Google Drive API**, **Gmail API**, and **Google Calendar API**
-4. Go to **Credentials** → **Create Credentials** → **OAuth Client ID**
-5. Select **Desktop application** as the application type
-6. Download the credentials or note your **Client ID** and **Client Secret**
+3. Enable the **Google Docs API**, **Google Sheets API**, **Google Drive API**, **Gmail API**, **Google Calendar API**, and **Google Forms API**
+4. Go to **OAuth consent screen** and configure it (External is fine for personal use). If your app's publishing status is **Testing** (the default), you must add your Google account as a test user — go to **OAuth consent screen** → **Test users** → **Add users** and enter your email. Without this, Google will block the OAuth flow with an "Access denied" or "app not verified" error.
+5. Go to **Credentials** → **Create Credentials** → **OAuth Client ID**
+6. Select **Desktop application** as the application type
+7. Download the credentials or note your **Client ID** and **Client Secret**
 
 ### Step 2: Provide Your Credentials
 
@@ -168,20 +169,20 @@ This stores tokens in `~/.config/google-tools-mcp/work/` instead of the default
 
 ## Tool Categories
 
-### `files` (16 tools)
+### `files` (17 tools)
 Google Drive file management and content reading.
 
-`listDocuments`, `searchDocuments`, `getDocumentInfo`, `createFolder`, `listFolderContents`, `getFolderInfo`, `moveFile`, `copyFile`, `renameFile`, `deleteFile`, `createDocument`, `createDocumentFromTemplate`, `listSharedDrives`, `listSharedWithMe`, `readFile`, `searchFileContents`
+`listDriveFiles`, `searchDocuments`, `getFileInfo`, `createFolder`, `listFolderContents`, `getFolderInfo`, `moveFile`, `copyFile`, `renameFile`, `deleteFile`, `createDocument`, `createDocumentFromTemplate`, `listSharedDrives`, `listSharedWithMe`, `downloadFile`, `readFile`, `searchFileContents`
 
-### `documents` (23 tools)
+### `documents` (22 tools)
 Google Docs read/write/format with markdown support.
 
-`readDocument`, `appendText`, `insertText`, `deleteRange`, `modifyText`, `findAndReplace`, `insertTable`, `insertTableWithData`, `insertPageBreak`, `insertImage`, `listTabs`, `addTab`, `renameTab`, `applyTextStyle`, `applyParagraphStyle`, `addComment`, `deleteComment`, `getComment`, `listComments`, `replyToComment`, `resolveComment`, `appendMarkdown`, `replaceDocumentWithMarkdown`
+`readDocument`, `appendText`, `deleteRange`, `modifyText`, `findAndReplace`, `insertTable`, `insertTableWithData`, `insertPageBreak`, `insertImage`, `listTabs`, `addTab`, `renameTab`, `applyParagraphStyle`, `getFormatting`, `addComment`, `deleteComment`, `getComment`, `listComments`, `replyToComment`, `resolveComment`, `appendMarkdown`, `replaceDocumentWithMarkdown`
 
-### `spreadsheets` (30 tools)
+### `spreadsheets` (29 tools)
 Google Sheets operations.
 
-`readSpreadsheet`, `writeSpreadsheet`, `batchWrite`, `appendRows`, `clearRange`, `createSpreadsheet`, `getSpreadsheetInfo`, `addSheet`, `deleteSheet`, `duplicateSheet`, `renameSheet`, `formatCells`, `readCellFormat`, `autoResizeColumns`, `freezeRowsAndColumns`, `setColumnWidths`, `addConditionalFormatting`, `copyFormatting`, `setDropdownValidation`, `createTable`, `deleteTable`, `getTable`, `listTables`, `appendTableRows`, `updateTableRange`, `insertChart`, `deleteChart`, `groupRows`, `ungroupAllRows`, `listSpreadsheets`
+`readSpreadsheet`, `writeSpreadsheet`, `batchWrite`, `appendRows`, `clearRange`, `createSpreadsheet`, `getSpreadsheetInfo`, `addSheet`, `deleteSheet`, `duplicateSheet`, `renameSheet`, `formatCells`, `readCellFormat`, `autoResizeColumns`, `freezeRowsAndColumns`, `setColumnWidths`, `addConditionalFormatting`, `copyFormatting`, `setDropdownValidation`, `createTable`, `deleteTable`, `getTable`, `listTables`, `appendTableRows`, `updateTableRange`, `insertChart`, `deleteChart`, `groupRows`, `ungroupAllRows`
 
 ### `email` (19 tools)
 Gmail messages and drafts.
@@ -208,6 +209,11 @@ Google Calendar — events, availability, and calendar management.
 
 `list_calendars`, `get_events`, `manage_event`, `get_busy`, `get_free`, `move_event`, `list_recurring_event_instances`, `manage_calendar`
 
+### `forms` (6 tools)
+Google Forms — create/read forms, manage responses, and publish settings.
+
+`create_form`, `get_form`, `batch_update_form`, `get_form_response`, `list_form_responses`, `set_publish_settings`
+
 ## Environment Variables
 
 | Variable | Required | Description |

package/dist/tools/docs/formatting/getFormatting.js

@@ -0,0 +1,171 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../../clients.js';
+import { DocumentIdParameter, TextFindParameter } from '../../../types.js';
+import * as GDocsHelpers from '../../../googleDocsApiHelpers.js';
+
+const RangeTarget = z.object({
+    startIndex: z.number().int().min(1).describe('Start of range (inclusive, 1-based).'),
+    endIndex: z.number().int().min(1).describe('End of range (exclusive).'),
+}).refine((d) => d.endIndex > d.startIndex, {
+    message: 'endIndex must be greater than startIndex',
+    path: ['endIndex'],
+});
+
+const GetFormattingParameters = DocumentIdParameter.extend({
+    target: z
+        .union([RangeTarget, TextFindParameter])
+        .describe('Target by range indices or text search.'),
+    tabId: z
+        .string()
+        .optional()
+        .describe('The ID of the specific tab to read from. If not specified, reads from the first tab.'),
+});
+
+/**
+ * Extracts text style and paragraph style info from document elements
+ * that overlap the given range.
+ */
+function extractFormattingFromContent(bodyContent, startIndex, endIndex) {
+    const textStyles = [];
+    const paragraphStyles = [];
+
+    for (const element of bodyContent) {
+        if (!element.paragraph) continue;
+
+        const para = element.paragraph;
+        // Check if this paragraph overlaps our range
+        const paraElements = para.elements || [];
+        let paragraphOverlaps = false;
+
+        for (const pe of paraElements) {
+            const elStart = pe.startIndex ?? 0;
+            const elEnd = pe.endIndex ?? 0;
+
+            // Check overlap with our target range
+            if (elEnd > startIndex && elStart < endIndex) {
+                paragraphOverlaps = true;
+                if (pe.textRun) {
+                    const text = pe.textRun.content || '';
+                    const style = pe.textRun.textStyle || {};
+                    // Only include non-empty style properties
+                    const cleanStyle = {};
+                    if (style.bold) cleanStyle.bold = true;
+                    if (style.italic) cleanStyle.italic = true;
+                    if (style.underline) cleanStyle.underline = true;
+                    if (style.strikethrough) cleanStyle.strikethrough = true;
+                    if (style.fontSize) cleanStyle.fontSize = style.fontSize;
+                    if (style.foregroundColor?.color?.rgbColor) cleanStyle.foregroundColor = style.foregroundColor.color.rgbColor;
+                    if (style.backgroundColor?.color?.rgbColor) cleanStyle.backgroundColor = style.backgroundColor.color.rgbColor;
+                    if (style.weightedFontFamily) cleanStyle.fontFamily = style.weightedFontFamily.fontFamily;
+                    if (style.link) cleanStyle.link = style.link;
+                    if (style.baselineOffset && style.baselineOffset !== 'BASELINE_OFFSET_UNSPECIFIED') cleanStyle.baselineOffset = style.baselineOffset;
+
+                    textStyles.push({
+                        startIndex: elStart,
+                        endIndex: elEnd,
+                        text: text.replace(/\n$/, ''),
+                        style: cleanStyle,
+                    });
+                }
+            }
+        }
+
+        if (paragraphOverlaps && para.paragraphStyle) {
+            const ps = para.paragraphStyle;
+            const cleanStyle = {};
+            if (ps.namedStyleType && ps.namedStyleType !== 'NORMAL_TEXT') cleanStyle.namedStyleType = ps.namedStyleType;
+            if (ps.alignment && ps.alignment !== 'START') cleanStyle.alignment = ps.alignment;
+            if (ps.indentStart?.magnitude) cleanStyle.indentStart = ps.indentStart.magnitude;
+            if (ps.indentEnd?.magnitude) cleanStyle.indentEnd = ps.indentEnd.magnitude;
+            if (ps.spaceAbove?.magnitude) cleanStyle.spaceAbove = ps.spaceAbove.magnitude;
+            if (ps.spaceBelow?.magnitude) cleanStyle.spaceBelow = ps.spaceBelow.magnitude;
+            if (ps.keepWithNext) cleanStyle.keepWithNext = true;
+            if (ps.lineSpacing) cleanStyle.lineSpacing = ps.lineSpacing;
+            if (ps.direction && ps.direction !== 'LEFT_TO_RIGHT') cleanStyle.direction = ps.direction;
+
+            // Always include namedStyleType even if NORMAL_TEXT for clarity
+            if (!cleanStyle.namedStyleType) cleanStyle.namedStyleType = 'NORMAL_TEXT';
+
+            paragraphStyles.push({
+                paragraphStartIndex: element.startIndex,
+                paragraphEndIndex: element.endIndex,
+                style: cleanStyle,
+            });
+        }
+    }
+
+    return { textStyles, paragraphStyles };
+}
+
+export function register(server) {
+    server.addTool({
+        name: 'getFormatting',
+        description: 'Returns the text styling (bold, italic, font, colors, etc.) and paragraph styling ' +
+            '(alignment, headings, spacing, indentation) for a specific range or found text in a Google Doc. ' +
+            'Returns per-run text styles and per-paragraph styles, so mixed formatting (e.g. bold + italic spans) is fully represented.',
+        parameters: GetFormattingParameters,
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`getFormatting on doc ${args.documentId}: target=${JSON.stringify(args.target)}` +
+                `${args.tabId ? `, tab=${args.tabId}` : ''}`);
+            try {
+                // Resolve target to numeric indices
+                let startIndex;
+                let endIndex;
+
+                if ('textToFind' in args.target) {
+                    const range = await GDocsHelpers.findTextRange(
+                        docs, args.documentId, args.target.textToFind,
+                        args.target.matchInstance, args.tabId
+                    );
+                    if (!range) {
+                        throw new UserError(
+                            `Could not find instance ${args.target.matchInstance ?? 1} of text "${args.target.textToFind}"${args.tabId ? ` in tab ${args.tabId}` : ''}.`
+                        );
+                    }
+                    startIndex = range.startIndex;
+                    endIndex = range.endIndex;
+                } else {
+                    startIndex = args.target.startIndex;
+                    endIndex = args.target.endIndex;
+                }
+
+                // Fetch document with full content
+                const needsTabsContent = !!args.tabId;
+                const res = await docs.documents.get({
+                    documentId: args.documentId,
+                    ...(needsTabsContent && { includeTabsContent: true }),
+                    fields: needsTabsContent ? '*' : 'body(content)',
+                });
+
+                let bodyContent;
+                if (args.tabId) {
+                    const targetTab = GDocsHelpers.findTabById(res.data, args.tabId);
+                    if (!targetTab) {
+                        throw new UserError(`Tab with ID "${args.tabId}" not found in document.`);
+                    }
+                    bodyContent = targetTab.documentTab?.body?.content;
+                } else {
+                    bodyContent = res.data.body?.content;
+                }
+
+                if (!bodyContent) {
+                    throw new UserError('Document has no content.');
+                }
+
+                const result = extractFormattingFromContent(bodyContent, startIndex, endIndex);
+
+                return JSON.stringify({
+                    range: { startIndex, endIndex },
+                    textStyles: result.textStyles,
+                    paragraphStyles: result.paragraphStyles,
+                }, null, 2);
+            } catch (error) {
+                log.error(`Error in getFormatting for doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError) throw error;
+                throw new UserError(`Failed to get formatting: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/formatting/index.js

@@ -1,4 +1,6 @@
 import { register as applyParagraphStyle } from './applyParagraphStyle.js';
+import { register as getFormatting } from './getFormatting.js';
 export function registerFormattingTools(server) {
     applyParagraphStyle(server);
+    getFormatting(server);
 }

package/dist/tools/docs/modifyText.js

@@ -1,7 +1,7 @@
 import { UserError } from 'fastmcp';
 import { z } from 'zod';
 import { getDocsClient } from '../../clients.js';
-import { DocumentIdParameter, TextFindParameter, TextStyleParameters } from '../../types.js';
+import { DocumentIdParameter, TextFindParameter, TextStyleParameters, ParagraphStyleParameters } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
 const RangeTarget = z
     .object({
@@ -20,14 +20,15 @@ const ModifyTextParameters = DocumentIdParameter.extend({
         .union([RangeTarget, TextFindParameter, InsertionTarget])
         .describe('Target by range indices, text search, or insertion index.'),
     text: z.string().optional().describe('New text to insert or replace with.'),
-    style: TextStyleParameters.optional().describe('Text formatting to apply.'),
+    style: TextStyleParameters.optional().describe('Text formatting to apply (bold, italic, font size, etc.).'),
+    paragraphStyle: ParagraphStyleParameters.optional().describe('Paragraph formatting to apply (alignment, indentation, headings, spacing, etc.).'),
     tabId: z
         .string()
         .optional()
         .describe('The ID of the specific tab to operate on. If not specified, operates on the first tab.'),
 })
-    .refine((args) => args.text !== undefined || args.style !== undefined, {
-    message: 'At least one of text or style must be provided.',
+    .refine((args) => args.text !== undefined || args.style !== undefined || args.paragraphStyle !== undefined, {
+    message: 'At least one of text, style, or paragraphStyle must be provided.',
 })
     .refine((args) => {
     if ('insertionIndex' in args.target && args.text === undefined)
@@ -39,9 +40,9 @@ const ModifyTextParameters = DocumentIdParameter.extend({
  * modifyText operation. Indices must already be resolved (no text-search here).
  */
 export function buildModifyTextRequests(opts) {
-    const { startIndex, endIndex, text, style, tabId } = opts;
+    const { startIndex, endIndex, text, style, paragraphStyle, tabId } = opts;
     const requests = [];
-    if (!text && !style)
+    if (!text && !style && !paragraphStyle)
         return requests;
     // 1. Delete existing content (only when replacing, not insert-only)
     if (endIndex !== undefined && text !== undefined) {
@@ -57,7 +58,7 @@ export function buildModifyTextRequests(opts) {
             location.tabId = tabId;
         requests.push({ insertText: { location, text } });
     }
-    // 3. Apply formatting
+    // 3. Apply text formatting
     if (style) {
         const formatStart = startIndex;
         const formatEnd = text !== undefined
@@ -72,20 +73,36 @@ export function buildModifyTextRequests(opts) {
             }
         }
     }
+    // 4. Apply paragraph formatting
+    if (paragraphStyle) {
+        const formatStart = startIndex;
+        const formatEnd = text !== undefined
+            ? startIndex + text.length
+            : endIndex !== undefined
+                ? endIndex
+                : startIndex;
+        if (formatEnd > formatStart) {
+            const requestInfo = GDocsHelpers.buildUpdateParagraphStyleRequest(formatStart, formatEnd, paragraphStyle, tabId);
+            if (requestInfo) {
+                requests.push(requestInfo.request);
+            }
+        }
+    }
     return requests;
 }
 export function register(server) {
     server.addTool({
         name: 'modifyText',
         description: 'Combines text replacement/insertion and formatting in one atomic operation. ' +
-            'Can insert text at a position, replace a range or found text, apply formatting, ' +
-            "or any combination. Use readGoogleDoc with format='json' to determine indices.",
+            'Can insert text at a position, replace a range or found text, apply text styling (bold, italic, etc.), ' +
+            "apply paragraph styling (alignment, headings, spacing, etc.), or any combination. Use readGoogleDoc with format='json' to determine indices.",
         parameters: ModifyTextParameters,
         execute: async (args, { log }) => {
             const docs = await getDocsClient();
             log.info(`modifyText on doc ${args.documentId}: target=${JSON.stringify(args.target)}` +
                 `${args.text !== undefined ? `, text="${args.text.substring(0, 50)}"` : ''}` +
                 `${args.style ? `, style=${JSON.stringify(args.style)}` : ''}` +
+                `${args.paragraphStyle ? `, paragraphStyle=${JSON.stringify(args.paragraphStyle)}` : ''}` +
                 `${args.tabId ? `, tab=${args.tabId}` : ''}`);
             try {
                 // Verify tab exists if specified
@@ -131,6 +148,7 @@ export function register(server) {
                     endIndex,
                     text: args.text,
                     style: args.style,
+                    paragraphStyle: args.paragraphStyle,
                     tabId: args.tabId,
                 });
                 if (requests.length === 0) {
@@ -144,7 +162,9 @@ export function register(server) {
                 else if (args.text !== undefined)
                     actions.push('inserted text');
                 if (args.style)
-                    actions.push('applied formatting');
+                    actions.push('applied text formatting');
+                if (args.paragraphStyle)
+                    actions.push('applied paragraph formatting');
                 return `Successfully ${actions.join(' and ')} at range ${startIndex}-${endIndex ?? startIndex + (args.text?.length ?? 0)}${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
             }
             catch (error) {

package/dist/tools/index.js

@@ -3,6 +3,8 @@
 //  so lazy-loading doesn't work.)
 import { z } from 'zod';
 import * as fs from 'fs/promises';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
 import { getTokenPath } from '../auth.js';
 import { resetClients } from '../clients.js';
 import { logger } from '../logger.js';
@@ -81,6 +83,23 @@ export async function registerAllTools(server) {
     }
     logger.info(`Loaded all ${Object.keys(CATEGORIES).length} categories at startup.`);
 
+    // --- Help tool (always available) ---
+    server.addTool({
+        name: 'help',
+        description:
+            'Show documentation for google-tools-mcp: setup instructions, available tool categories, environment variables, and troubleshooting. Call this when you need guidance on how to use the Google Workspace tools.',
+        parameters: z.object({}),
+        execute: async () => {
+            const __dirname = path.dirname(fileURLToPath(import.meta.url));
+            const readmePath = path.resolve(__dirname, '..', '..', 'README.md');
+            try {
+                return await fs.readFile(readmePath, 'utf-8');
+            } catch {
+                return 'README not found. Visit https://www.npmjs.com/package/google-tools-mcp for documentation.';
+            }
+        },
+    });
+
     // --- Logout tool (always available) ---
     server.addTool({
         name: 'logout',

package/package.json

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