google-tools-mcp 1.2.11 → 2.0.0

package/dist/tools/docs/addTab.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { getLastReadRevisionId, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'addTab',
@@ -52,19 +53,16 @@ export function register(server) {
                     tabProperties.index = args.index;
                 if (args.iconEmoji !== undefined)
                     tabProperties.iconEmoji = args.iconEmoji;
-                const response = await docs.documents.batchUpdate({
-                    documentId: args.documentId,
-                    requestBody: {
-                        requests: [
-                            {
-                                addDocumentTab: {
-                                    tabProperties,
-                                },
-                            },
-                        ],
+                const revisionId = getLastReadRevisionId(args.documentId);
+                const response = await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [
+                    {
+                        addDocumentTab: {
+                            tabProperties,
+                        },
                     },
-                });
-                const newTabProps = response.data.replies?.[0]?.addDocumentTab?.tabProperties;
+                ], revisionId ? { requiredRevisionId: revisionId } : undefined);
+                trackMutation(args.documentId, response?.writeControl?.requiredRevisionId);
+                const newTabProps = response.replies?.[0]?.addDocumentTab?.tabProperties;
                 if (newTabProps) {
                     return JSON.stringify({
                         url: `https://docs.google.com/document/d/${args.documentId}/edit`,

package/dist/tools/docs/appendToGoogleDoc.js

@@ -5,7 +5,7 @@ import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter, NotImplementedError } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
 import { docsJsonToMarkdown } from '../../markdown-transformer/index.js';
-import { guardMutation, trackMutation } from '../../readTracker.js';
+import { guardMutation, getLastReadRevisionId, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'appendText',
@@ -29,7 +29,11 @@ export function register(server) {
             await guardMutation(args.documentId, {
                 contentFetcher: async () => {
                     const current = await docs.documents.get({ documentId: args.documentId });
-                    return docsJsonToMarkdown(current.data);
+                    // Return the revision this content came from alongside the
+                    // content itself so guardMutation can refresh both together
+                    // instead of leaving revisionId stale after a diff (see
+                    // readTracker.js guardMutation for why that matters).
+                    return { content: docsJsonToMarkdown(current.data), revisionId: current.data.revisionId };
                 },
             });
             // Resolve text content from filePath or inline parameter
@@ -88,8 +92,9 @@ export function register(server) {
                 const request = {
                     insertText: { location, text: textToInsert },
                 };
-                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request]);
-                trackMutation(args.documentId);
+                const revisionId = getLastReadRevisionId(args.documentId);
+                const writeResponse = await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request], revisionId ? { requiredRevisionId: revisionId } : undefined);
+                trackMutation(args.documentId, writeResponse?.writeControl?.requiredRevisionId);
                 log.info(`Successfully appended to doc: ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
                 const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
                 return `${docUrl}\nSuccessfully appended text to ${args.tabId ? `tab ${args.tabId} in ` : ''}document ${args.documentId}.`;

package/dist/tools/docs/deleteRange.js

@@ -4,7 +4,7 @@ import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
 import { docsJsonToMarkdown } from '../../markdown-transformer/index.js';
-import { guardMutation, trackMutation } from '../../readTracker.js';
+import { guardMutation, getLastReadRevisionId, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'deleteRange',
@@ -33,7 +33,11 @@ export function register(server) {
             await guardMutation(args.documentId, {
                 contentFetcher: async () => {
                     const current = await docs.documents.get({ documentId: args.documentId });
-                    return docsJsonToMarkdown(current.data);
+                    // Return the revision this content came from alongside the
+                    // content itself so guardMutation can refresh both together
+                    // instead of leaving revisionId stale after a diff (see
+                    // readTracker.js guardMutation for why that matters).
+                    return { content: docsJsonToMarkdown(current.data), revisionId: current.data.revisionId };
                 },
             });
             log.info(`Deleting range ${args.startIndex}-${args.endIndex} in doc ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
@@ -66,8 +70,9 @@ export function register(server) {
                 const request = {
                     deleteContentRange: { range },
                 };
-                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request]);
-                trackMutation(args.documentId);
+                const revisionId = getLastReadRevisionId(args.documentId);
+                const writeResponse = await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request], revisionId ? { requiredRevisionId: revisionId } : undefined);
+                trackMutation(args.documentId, writeResponse?.writeControl?.requiredRevisionId);
                 const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
                 return `${docUrl}\nSuccessfully deleted content in range ${args.startIndex}-${args.endIndex}${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
             }

package/dist/tools/docs/findAndReplace.js

@@ -4,7 +4,7 @@ import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
 import { docsJsonToMarkdown } from '../../markdown-transformer/index.js';
-import { guardMutation, trackMutation } from '../../readTracker.js';
+import { guardMutation, getLastReadRevisionId, trackMutation } from '../../readTracker.js';
 const FindAndReplaceParameters = DocumentIdParameter.extend({
     findText: z.string().min(1).describe('The text to search for in the document.'),
     replaceText: z
@@ -30,7 +30,11 @@ export function register(server) {
             await guardMutation(args.documentId, {
                 contentFetcher: async () => {
                     const current = await docs.documents.get({ documentId: args.documentId });
-                    return docsJsonToMarkdown(current.data);
+                    // Return the revision this content came from alongside the
+                    // content itself so guardMutation can refresh both together
+                    // instead of leaving revisionId stale after a diff (see
+                    // readTracker.js guardMutation for why that matters).
+                    return { content: docsJsonToMarkdown(current.data), revisionId: current.data.revisionId };
                 },
             });
             log.info(`findAndReplace in doc ${args.documentId}: "${args.findText}" → "${args.replaceText}"` +
@@ -47,8 +51,9 @@ export function register(server) {
                         ...(args.tabId && { tabsCriteria: { tabIds: [args.tabId] } }),
                     },
                 };
-                const response = await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request]);
-                trackMutation(args.documentId);
+                const revisionId = getLastReadRevisionId(args.documentId);
+                const response = await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request], revisionId ? { requiredRevisionId: revisionId } : undefined);
+                trackMutation(args.documentId, response?.writeControl?.requiredRevisionId);
                 const changed = response.replies?.[0]?.replaceAllText?.occurrencesChanged ?? 0;
                 const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
                 return `${docUrl}\nReplaced ${changed} occurrence(s) of "${args.findText}" with "${args.replaceText}".`;

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

@@ -2,6 +2,7 @@ import { UserError } from 'fastmcp';
 import { getDocsClient } from '../../../clients.js';
 import { ApplyParagraphStyleToolParameters, NotImplementedError, } from '../../../types.js';
 import * as GDocsHelpers from '../../../googleDocsApiHelpers.js';
+import { getLastReadRevisionId, trackMutation } from '../../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'applyParagraphStyle',
@@ -64,7 +65,9 @@ export function register(server) {
                     return 'No valid paragraph styling options were provided.';
                 }
                 log.info(`Applying styles: ${requestInfo.fields.join(', ')}`);
-                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [requestInfo.request]);
+                const revisionId = getLastReadRevisionId(args.documentId);
+                const writeResponse = await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [requestInfo.request], revisionId ? { requiredRevisionId: revisionId } : undefined);
+                trackMutation(args.documentId, writeResponse?.writeControl?.requiredRevisionId);
                 const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
                 return `${docUrl}\nSuccessfully applied paragraph styles (${requestInfo.fields.join(', ')}) to the paragraph${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
             }

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

@@ -1,171 +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'}`);
-            }
-        },
-    });
-}
+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/insertImage.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { getDocsClient, getDriveClient, getScriptClient } from '../../clients.js';
 import { DocumentIdParameter } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { getLastReadRevisionId, requireRereadBeforeMutation, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'insertImage',
@@ -75,7 +76,17 @@ export function register(server) {
                     const driveFileId = await GDocsHelpers.uploadImageToDrive(drive, args.localImagePath, parentFolderId, true // skipPublicSharing
                     );
                     log.info(`[AppsScript] Inserting image via marker at index ${args.index} (fileId: ${driveFileId})`);
-                    await GDocsHelpers.insertImageViaAppsScript(docs, scriptClient, appsScriptDeploymentId, args.documentId, driveFileId, args.index, args.tabId);
+                    const appsScriptRevisionId = getLastReadRevisionId(args.documentId);
+                    await GDocsHelpers.insertImageViaAppsScript(docs, scriptClient, appsScriptDeploymentId, args.documentId, driveFileId, args.index, args.tabId, appsScriptRevisionId ? { requiredRevisionId: appsScriptRevisionId } : undefined);
+                    // The Apps Script call that replaces the marker with the image mutates
+                    // the document outside our batchUpdate visibility, so we have no way to
+                    // learn the true post-write revision here. trackMutation would clear the
+                    // revision and the modifiedTime, which leaves the next write with nothing
+                    // to check against and sends it out unguarded on a pre-image baseline.
+                    // Require a fresh read instead.
+                    log.warn(`Document ${args.documentId} must be read again before the next write ` +
+                        '(the Apps Script mutates the doc outside batchUpdate visibility, so no true post-write revision is available).');
+                    requireRereadBeforeMutation(args.documentId, 'an Apps Script inserted an image and its resulting revision is not visible to us.');
                     const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
                     return `${docUrl}\nSuccessfully inserted local image at index ${args.index} via Apps Script${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
                 }
@@ -105,7 +116,9 @@ export function register(server) {
                     resolvedUrl = args.imageUrl;
                     log.info(`Inserting image from URL ${resolvedUrl} at index ${args.index} in doc ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
                 }
-                await GDocsHelpers.insertInlineImage(docs, args.documentId, resolvedUrl, args.index, args.width, args.height, args.tabId);
+                const revisionId = getLastReadRevisionId(args.documentId);
+                const writeResponse = await GDocsHelpers.insertInlineImage(docs, args.documentId, resolvedUrl, args.index, args.width, args.height, args.tabId, revisionId ? { requiredRevisionId: revisionId } : undefined);
+                trackMutation(args.documentId, writeResponse?.writeControl?.requiredRevisionId);
                 let sizeInfo = '';
                 if (args.width && args.height) {
                     sizeInfo = ` with size ${args.width}x${args.height}pt`;

package/dist/tools/docs/insertPageBreak.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { getLastReadRevisionId, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'insertPageBreak',
@@ -44,7 +45,9 @@ export function register(server) {
                 const request = {
                     insertPageBreak: { location },
                 };
-                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request]);
+                const revisionId = getLastReadRevisionId(args.documentId);
+                const writeResponse = await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request], revisionId ? { requiredRevisionId: revisionId } : undefined);
+                trackMutation(args.documentId, writeResponse?.writeControl?.requiredRevisionId);
                 const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
                 return `${docUrl}\nSuccessfully inserted page break at index ${args.index}${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
             }

package/dist/tools/docs/insertTable.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { getLastReadRevisionId, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'insertTable',
@@ -39,7 +40,9 @@ export function register(server) {
                         throw new UserError(`Tab "${args.tabId}" does not have content (may not be a document tab).`);
                     }
                 }
-                await GDocsHelpers.createTable(docs, args.documentId, args.rows, args.columns, args.index, args.tabId);
+                const revisionId = getLastReadRevisionId(args.documentId);
+                const writeResponse = await GDocsHelpers.createTable(docs, args.documentId, args.rows, args.columns, args.index, args.tabId, revisionId ? { requiredRevisionId: revisionId } : undefined);
+                trackMutation(args.documentId, writeResponse?.writeControl?.requiredRevisionId);
                 const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
                 return `${docUrl}\nSuccessfully inserted a ${args.rows}x${args.columns} table at index ${args.index}${args.tabId ? ` in tab ${args.tabId}` : ''}.`;
             }

package/dist/tools/docs/insertTableWithData.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { getLastReadRevisionId, trackMutation } from '../../readTracker.js';
 // --- Table Index Math ---
 // Google Docs API table index layout for an R×C table inserted at T:
 //   cellContentIndex(T, r, c, C) = T + 4 + r * (1 + 2*C) + 2*c
@@ -118,7 +119,9 @@ export function register(server) {
                     }
                 }
                 const requests = buildInsertTableWithDataRequests(args.data, args.index, args.hasHeaderRow ?? false, args.tabId);
-                const metadata = await GDocsHelpers.executeBatchUpdateWithSplitting(docs, args.documentId, requests, log);
+                const revisionId = getLastReadRevisionId(args.documentId);
+                const metadata = await GDocsHelpers.executeBatchUpdateWithSplitting(docs, args.documentId, requests, log, revisionId ? { requiredRevisionId: revisionId } : undefined);
+                trackMutation(args.documentId, metadata?.finalWriteControl?.requiredRevisionId);
                 const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
                 return (`${docUrl}\nSuccessfully inserted a ${numRows}x${numCols} table with data at index ${args.index}` +
                     `${args.tabId ? ` in tab ${args.tabId}` : ''}. ` +