google-tools-mcp 1.0.7 → 1.0.8

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

@@ -0,0 +1,170 @@
+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.',
+        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/package.json

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