google-tools-mcp 1.0.17 → 1.1.2

package/dist/googleDocsApiHelpers.js

@@ -160,127 +160,239 @@ export async function executeBatchUpdateWithSplitting(docs, documentId, requests
 }
 // --- Text Finding Helper ---
 // This improved version is more robust in handling various text structure scenarios
-export async function findTextRange(docs, documentId, textToFind, instance = 1, tabId) {
-    try {
-        // Request more detailed information about the document structure
-        // When tabId is specified, we need to use includeTabsContent to access tab-specific content
-        const needsTabsContent = !!tabId;
-        const res = await docs.documents.get({
-            documentId,
-            ...(needsTabsContent && { includeTabsContent: true }),
-            // Request more fields to handle various container types (not just paragraphs)
-            fields: needsTabsContent
-                ? 'tabs(tabProperties(tabId),documentTab(body(content(paragraph(elements(startIndex,endIndex,textRun(content))),table,sectionBreak,tableOfContents,startIndex,endIndex))))'
-                : 'body(content(paragraph(elements(startIndex,endIndex,textRun(content))),table,sectionBreak,tableOfContents,startIndex,endIndex))',
-        });
-        // Get body content from the correct tab or default
-        let bodyContent;
-        if (tabId) {
-            const targetTab = findTabById(res.data, tabId);
-            if (!targetTab) {
-                throw new UserError(`Tab with ID "${tabId}" not found in document.`);
+/**
+ * Fetches document content and builds a flat text representation with segment mappings.
+ * Shared by findTextRange and other text-search utilities.
+ */
+async function getDocumentTextAndSegments(docs, documentId, tabId) {
+    const needsTabsContent = !!tabId;
+    const res = await docs.documents.get({
+        documentId,
+        ...(needsTabsContent && { includeTabsContent: true }),
+        fields: needsTabsContent
+            ? 'tabs(tabProperties(tabId),documentTab(body(content(paragraph(elements(startIndex,endIndex,textRun(content))),table,sectionBreak,tableOfContents,startIndex,endIndex))))'
+            : 'body(content(paragraph(elements(startIndex,endIndex,textRun(content))),table,sectionBreak,tableOfContents,startIndex,endIndex))',
+    });
+    let bodyContent;
+    if (tabId) {
+        const targetTab = findTabById(res.data, tabId);
+        if (!targetTab) {
+            throw new UserError(`Tab with ID "${tabId}" not found in document.`);
+        }
+        if (!targetTab.documentTab?.body?.content) {
+            throw new UserError(`Tab "${tabId}" does not have content (may not be a document tab).`);
+        }
+        bodyContent = targetTab.documentTab.body.content;
+    }
+    else {
+        bodyContent = res.data.body?.content;
+    }
+    if (!bodyContent) {
+        return null;
+    }
+    let fullText = '';
+    const segments = [];
+    const collectTextFromContent = (content) => {
+        content.forEach((element) => {
+            if (element.paragraph?.elements) {
+                element.paragraph.elements.forEach((pe) => {
+                    if (pe.textRun?.content && pe.startIndex !== undefined && pe.endIndex !== undefined) {
+                        const content = pe.textRun.content;
+                        fullText += content;
+                        segments.push({
+                            text: content,
+                            start: pe.startIndex,
+                            end: pe.endIndex,
+                        });
+                    }
+                });
             }
-            if (!targetTab.documentTab?.body?.content) {
-                throw new UserError(`Tab "${tabId}" does not have content (may not be a document tab).`);
+            if (element.table && element.table.tableRows) {
+                element.table.tableRows.forEach((row) => {
+                    if (row.tableCells) {
+                        row.tableCells.forEach((cell) => {
+                            if (cell.content) {
+                                collectTextFromContent(cell.content);
+                            }
+                        });
+                    }
+                });
             }
-            bodyContent = targetTab.documentTab.body.content;
+        });
+    };
+    collectTextFromContent(bodyContent);
+    segments.sort((a, b) => a.start - b.start);
+    return { fullText, segments };
+}
+/**
+ * Maps a position in the concatenated fullText back to the actual document index.
+ */
+function mapFullTextPositionToDocIndex(posInFullText, segments) {
+    let currentPos = 0;
+    for (const seg of segments) {
+        const segStart = currentPos;
+        const segEnd = segStart + seg.text.length;
+        if (posInFullText >= segStart && posInFullText < segEnd) {
+            return seg.start + (posInFullText - segStart);
         }
-        else {
-            bodyContent = res.data.body?.content;
+        // Also handle the position being exactly at segEnd (for end indices)
+        if (posInFullText === segEnd) {
+            return seg.start + seg.text.length;
         }
-        if (!bodyContent) {
+        currentPos = segEnd;
+    }
+    return -1;
+}
+/**
+ * Character-level Unicode normalization rules.
+ * Maps typographic characters to their ASCII equivalents.
+ */
+const NORMALIZE_MAP = {
+    '\u2018': "'", '\u2019': "'", '\u201A': "'", '\u201B': "'", '\u2032': "'", '\u2035': "'",  // smart single quotes
+    '\u201C': '"', '\u201D': '"', '\u201E': '"', '\u201F': '"', '\u2033': '"', '\u2036': '"',  // smart double quotes
+    '\u2014': '--',  // em dash
+    '\u2013': '-',   // en dash
+    '\u2026': '...', // ellipsis
+    '\u00A0': ' ',   // non-breaking space
+    '\u000B': '\n',  // vertical tab (Google Docs soft return)
+};
+/**
+ * Normalizes a string for search, returning both the normalized text
+ * and a position map from normalized-index → original-index.
+ */
+function normalizeWithPositionMap(text) {
+    let normalized = '';
+    const posMap = []; // posMap[normalizedIdx] = originalIdx
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        const replacement = NORMALIZE_MAP[ch];
+        if (replacement) {
+            for (let j = 0; j < replacement.length; j++) {
+                posMap.push(i);
+                normalized += replacement[j];
+            }
+        } else {
+            posMap.push(i);
+            normalized += ch;
+        }
+    }
+    // Sentinel for end-of-string mapping
+    posMap.push(text.length);
+    return { normalized, posMap };
+}
+/**
+ * Simple normalization without position map (for normalizing the search query).
+ */
+function normalizeForSearch(text) {
+    let result = '';
+    for (let i = 0; i < text.length; i++) {
+        const replacement = NORMALIZE_MAP[text[i]];
+        result += replacement ?? text[i];
+    }
+    return result;
+}
+/**
+ * Finds all occurrences of textToFind in the document and returns them with
+ * surrounding context and mapped document indices.
+ */
+function findAllOccurrences(fullText, segments, textToFind) {
+    const CONTEXT_CHARS = 30;
+    const occurrences = [];
+    let searchFrom = 0;
+    while (true) {
+        const idx = fullText.indexOf(textToFind, searchFrom);
+        if (idx === -1)
+            break;
+        const docStart = mapFullTextPositionToDocIndex(idx, segments);
+        const docEnd = mapFullTextPositionToDocIndex(idx + textToFind.length, segments);
+        // Extract surrounding context
+        const contextStart = Math.max(0, idx - CONTEXT_CHARS);
+        const contextEnd = Math.min(fullText.length, idx + textToFind.length + CONTEXT_CHARS);
+        const before = fullText.slice(contextStart, idx).replace(/\n/g, '\\n');
+        const match = fullText.slice(idx, idx + textToFind.length).replace(/\n/g, '\\n');
+        const after = fullText.slice(idx + textToFind.length, contextEnd).replace(/\n/g, '\\n');
+        const context = `${contextStart > 0 ? '...' : ''}${before}[${match}]${after}${contextEnd < fullText.length ? '...' : ''}`;
+        occurrences.push({
+            instance: occurrences.length + 1,
+            startIndex: docStart,
+            endIndex: docEnd,
+            context,
+        });
+        searchFrom = idx + 1;
+    }
+    return occurrences;
+}
+export async function findTextRange(docs, documentId, textToFind, instance, tabId) {
+    try {
+        const result = await getDocumentTextAndSegments(docs, documentId, tabId);
+        if (!result) {
             logger.warn(`No content found in document ${documentId}${tabId ? ` (tab: ${tabId})` : ''}`);
             return null;
         }
-        // More robust text collection and index tracking
-        let fullText = '';
-        const segments = [];
-        // Process all content elements, including structural ones
-        const collectTextFromContent = (content) => {
-            content.forEach((element) => {
-                // Handle paragraph elements
-                if (element.paragraph?.elements) {
-                    element.paragraph.elements.forEach((pe) => {
-                        if (pe.textRun?.content && pe.startIndex !== undefined && pe.endIndex !== undefined) {
-                            const content = pe.textRun.content;
-                            fullText += content;
-                            segments.push({
-                                text: content,
-                                start: pe.startIndex,
-                                end: pe.endIndex,
-                            });
-                        }
-                    });
-                }
-                // Handle table elements - this is simplified and might need expansion
-                if (element.table && element.table.tableRows) {
-                    element.table.tableRows.forEach((row) => {
-                        if (row.tableCells) {
-                            row.tableCells.forEach((cell) => {
-                                if (cell.content) {
-                                    collectTextFromContent(cell.content);
-                                }
-                            });
-                        }
-                    });
-                }
-                // Add handling for other structural elements as needed
-            });
-        };
-        collectTextFromContent(bodyContent);
-        // Sort segments by starting position to ensure correct ordering
-        segments.sort((a, b) => a.start - b.start);
+        const { fullText, segments } = result;
         logger.debug(`Document ${documentId} contains ${segments.length} text segments and ${fullText.length} characters in total.`);
-        // Find the specified instance of the text
-        let startIndex = -1;
-        let endIndex = -1;
-        let foundCount = 0;
-        let searchStartIndex = 0;
-        while (foundCount < instance) {
-            const currentIndex = fullText.indexOf(textToFind, searchStartIndex);
-            if (currentIndex === -1) {
-                logger.debug(`Search text "${textToFind}" not found for instance ${foundCount + 1} (requested: ${instance})`);
-                break;
-            }
-            foundCount++;
-            logger.debug(`Found instance ${foundCount} of "${textToFind}" at position ${currentIndex} in full text`);
-            if (foundCount === instance) {
-                const targetStartInFullText = currentIndex;
-                const targetEndInFullText = currentIndex + textToFind.length;
-                let currentPosInFullText = 0;
-                logger.debug(`Target text range in full text: ${targetStartInFullText}-${targetEndInFullText}`);
-                for (const seg of segments) {
-                    const segStartInFullText = currentPosInFullText;
-                    const segTextLength = seg.text.length;
-                    const segEndInFullText = segStartInFullText + segTextLength;
-                    // Map from reconstructed text position to actual document indices
-                    if (startIndex === -1 &&
-                        targetStartInFullText >= segStartInFullText &&
-                        targetStartInFullText < segEndInFullText) {
-                        startIndex = seg.start + (targetStartInFullText - segStartInFullText);
-                        logger.debug(`Mapped start to segment ${seg.start}-${seg.end}, position ${startIndex}`);
-                    }
-                    if (targetEndInFullText > segStartInFullText && targetEndInFullText <= segEndInFullText) {
-                        endIndex = seg.start + (targetEndInFullText - segStartInFullText);
-                        logger.debug(`Mapped end to segment ${seg.start}-${seg.end}, position ${endIndex}`);
-                        break;
-                    }
-                    currentPosInFullText = segEndInFullText;
-                }
-                if (startIndex === -1 || endIndex === -1) {
-                    logger.warn(`Failed to map text "${textToFind}" instance ${instance} to actual document indices`);
-                    return { startIndex, endIndex };
+        let allOccurrences = findAllOccurrences(fullText, segments, textToFind);
+        // Fallback: try normalized matching if exact match fails (issue #11)
+        if (allOccurrences.length === 0) {
+            const normalizedSearch = normalizeForSearch(textToFind);
+            const { normalized: normalizedFull, posMap } = normalizeWithPositionMap(fullText);
+            if (normalizedSearch !== textToFind || normalizedFull !== fullText) {
+                logger.debug(`Exact match failed, trying normalized match`);
+                // Find in normalized text, then map positions back to original
+                const CONTEXT_CHARS = 30;
+                let searchFrom = 0;
+                while (true) {
+                    const idx = normalizedFull.indexOf(normalizedSearch, searchFrom);
+                    if (idx === -1) break;
+                    // Map normalized positions back to original fullText positions
+                    const origStart = posMap[idx];
+                    const origEnd = posMap[idx + normalizedSearch.length];
+                    const docStart = mapFullTextPositionToDocIndex(origStart, segments);
+                    const docEnd = mapFullTextPositionToDocIndex(origEnd, segments);
+                    const contextStart = Math.max(0, origStart - CONTEXT_CHARS);
+                    const contextEnd = Math.min(fullText.length, origEnd + CONTEXT_CHARS);
+                    const before = fullText.slice(contextStart, origStart).replace(/\n/g, '\\n');
+                    const match = fullText.slice(origStart, origEnd).replace(/\n/g, '\\n');
+                    const after = fullText.slice(origEnd, contextEnd).replace(/\n/g, '\\n');
+                    const context = `${contextStart > 0 ? '...' : ''}${before}[${match}]${after}${contextEnd < fullText.length ? '...' : ''}`;
+                    allOccurrences.push({
+                        instance: allOccurrences.length + 1,
+                        startIndex: docStart,
+                        endIndex: docEnd,
+                        context,
+                    });
+                    searchFrom = idx + 1;
                 }
-                logger.debug(`Successfully mapped "${textToFind}" to document range ${startIndex}-${endIndex}`);
-                return { startIndex, endIndex };
             }
-            // Prepare for next search iteration
-            searchStartIndex = currentIndex + 1;
         }
-        logger.warn(`Could not find instance ${instance} of text "${textToFind}" in document ${documentId}`);
-        return null; // Instance not found or mapping failed for all attempts
+        if (allOccurrences.length === 0) {
+            logger.warn(`Text "${textToFind}" not found in document ${documentId}`);
+            return null;
+        }
+        // If instance is not specified and there are multiple matches, return all of them
+        // so the caller can disambiguate
+        if (instance === undefined && allOccurrences.length > 1) {
+            const listing = allOccurrences.map((o) => `  ${o.instance}. index ${o.startIndex}-${o.endIndex}: ${o.context}`).join('\n');
+            throw new UserError(`Found ${allOccurrences.length} instances of "${textToFind}". ` +
+                `Specify matchInstance to target the correct one:\n${listing}`);
+        }
+        // Use instance 1 if not specified (single match case)
+        const targetInstance = instance ?? 1;
+        if (targetInstance > allOccurrences.length) {
+            logger.warn(`Requested instance ${targetInstance} but only ${allOccurrences.length} found`);
+            return null;
+        }
+        const match = allOccurrences[targetInstance - 1];
+        if (match.startIndex === -1 || match.endIndex === -1) {
+            logger.warn(`Failed to map text "${textToFind}" instance ${targetInstance} to actual document indices`);
+            return { startIndex: match.startIndex, endIndex: match.endIndex };
+        }
+        logger.debug(`Successfully mapped "${textToFind}" instance ${targetInstance} to document range ${match.startIndex}-${match.endIndex}`);
+        return { startIndex: match.startIndex, endIndex: match.endIndex };
     }
     catch (error) {
+        if (error instanceof UserError)
+            throw error;
         logger.error(`Error finding text "${textToFind}" in doc ${documentId}: ${error.message || 'Unknown error'}`);
         if (error.code === 404)
             throw new UserError(`Document not found while searching text (ID: ${documentId}).`);

package/dist/markdown-transformer/index.js

@@ -85,10 +85,30 @@ export async function insertMarkdown(docs, documentId, markdown, options) {
     const overallStart = performance.now();
     const startIndex = options?.startIndex ?? 1;
     const tabId = options?.tabId;
+    // Fetch the document's default text style so we can explicitly set
+    // foreground color on inserted text (fixes issue #14 — text without
+    // explicit color shows "no color selected" in the Docs color picker).
+    let defaultForegroundColor;
+    try {
+        const styleRes = await docs.documents.get({
+            documentId,
+            fields: 'namedStyles',
+        });
+        const normalTextStyle = styleRes.data.namedStyles?.styles?.find(
+            (s) => s.namedStyleType === 'NORMAL_TEXT'
+        );
+        const fg = normalTextStyle?.textStyle?.foregroundColor?.color?.rgbColor;
+        if (fg) {
+            defaultForegroundColor = fg;
+        }
+    } catch {
+        // Non-fatal — if we can't read styles, proceed without explicit color
+    }
     const parseStart = performance.now();
-    const conversionOptions = options?.firstHeadingAsTitle
-        ? { firstHeadingAsTitle: true }
-        : undefined;
+    const conversionOptions = {
+        ...(options?.firstHeadingAsTitle && { firstHeadingAsTitle: true }),
+        ...(defaultForegroundColor && { defaultForegroundColor }),
+    };
     const requests = convertMarkdownToRequests(markdown, startIndex, tabId, conversionOptions);
     const parseElapsedMs = Math.round(performance.now() - parseStart);
     // Count requests by type

package/dist/markdown-transformer/markdownToDocs.js

@@ -70,6 +70,7 @@ export function convertMarkdownToRequests(markdown, startIndex = 1, tabId, optio
     const parser = createParser();
     const tokens = parser.parse(markdown, {});
     const context = {
+        startIndex,
         currentIndex: startIndex,
         insertRequests: [],
         formatRequests: [],
@@ -88,6 +89,7 @@ export function convertMarkdownToRequests(markdown, startIndex = 1, tabId, optio
         tabId,
         titleConsumed: false,
         firstHeadingAsTitle: options?.firstHeadingAsTitle ?? false,
+        defaultForegroundColor: options?.defaultForegroundColor ?? null,
     };
     try {
         for (const token of tokens) {
@@ -624,6 +626,29 @@ function popFormatting(context, type) {
 }
 // --- Finalization ---
 function finalizeFormatting(context) {
+    // Apply the document's default foreground color to the entire inserted range
+    // so text has an explicit color value in Google Docs (fixes issue #14).
+    // This goes first so intentional colors (code blocks, links) override it.
+    if (context.defaultForegroundColor && context.currentIndex > context.startIndex) {
+        const baseRange = {
+            startIndex: context.startIndex,
+            endIndex: context.currentIndex,
+        };
+        if (context.tabId) {
+            baseRange.tabId = context.tabId;
+        }
+        context.formatRequests.push({
+            updateTextStyle: {
+                range: baseRange,
+                textStyle: {
+                    foregroundColor: {
+                        color: { rgbColor: context.defaultForegroundColor },
+                    },
+                },
+                fields: 'foregroundColor',
+            },
+        });
+    }
     // Character-level formatting (bold, italic, strikethrough, code, links)
     for (const range of context.textRanges) {
         const rangeLocation = {

package/dist/readTracker.js

@@ -0,0 +1,84 @@
+// In-memory tracker for read-before-edit guards (issue #18).
+// Tracks which files have been read in this session and when.
+import { UserError } from 'fastmcp';
+import { getDriveClient } from './clients.js';
+import { logger } from './logger.js';
+
+// Map of fileId → { readAt: Date, modifiedTime: string (ISO) }
+const readLog = new Map();
+
+/**
+ * Record that a file was read. Call from all read tools.
+ */
+export function trackRead(fileId, modifiedTime) {
+    readLog.set(fileId, {
+        readAt: new Date(),
+        modifiedTime: modifiedTime || null,
+    });
+}
+
+/**
+ * Guard a mutation. Call from all mutating tools before making changes.
+ * Throws UserError if the file hasn't been read, or if it was modified externally.
+ *
+ * @param fileId - The file/document/spreadsheet ID
+ * @param opts.skipExternalCheck - If true, skip the Drive API modifiedTime check (for performance)
+ */
+export async function guardMutation(fileId, opts) {
+    const entry = readLog.get(fileId);
+    if (!entry) {
+        throw new UserError(
+            `This file (${fileId}) has not been read in this session. ` +
+            'Read it first before making changes to ensure you have current content. ' +
+            'Use readDocument, readSpreadsheet, readFile, or readDriveFile.'
+        );
+    }
+
+    // Optionally check if file was modified externally since last read
+    if (!opts?.skipExternalCheck) {
+        try {
+            const drive = await getDriveClient();
+            const res = await drive.files.get({
+                fileId,
+                fields: 'modifiedTime',
+                supportsAllDrives: true,
+            });
+            const currentModifiedTime = res.data.modifiedTime;
+            if (entry.modifiedTime && currentModifiedTime !== entry.modifiedTime) {
+                const readAt = entry.readAt.toISOString();
+                throw new UserError(
+                    `This file was modified externally since you last read it ` +
+                    `(last read: ${readAt}, last modified: ${currentModifiedTime}). ` +
+                    'Read the file again before editing to ensure you have current content.'
+                );
+            }
+            // Update modifiedTime on successful check
+            entry.modifiedTime = currentModifiedTime;
+        } catch (error) {
+            if (error instanceof UserError) throw error;
+            // If we can't check, log warning but allow the mutation
+            logger.warn(`Could not verify modifiedTime for ${fileId}: ${error.message}`);
+        }
+    }
+}
+
+/**
+ * Update the read tracker after a successful mutation (so subsequent mutations
+ * don't fail the external-change check against our own changes).
+ */
+export function trackMutation(fileId) {
+    const entry = readLog.get(fileId);
+    if (entry) {
+        entry.readAt = new Date();
+        // Clear modifiedTime — it will be stale after our mutation.
+        // The next guardMutation call will fetch fresh modifiedTime.
+        entry.modifiedTime = null;
+    }
+}
+
+/**
+ * Check if a file has been read (without throwing).
+ */
+export function hasBeenRead(fileId) {
+    return readLog.has(fileId);
+}

package/dist/tools/docs/appendToGoogleDoc.js

@@ -1,14 +1,18 @@
+import * as fs from 'fs/promises';
 import { UserError } from 'fastmcp';
 import { z } from 'zod';
 import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter, NotImplementedError } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { guardMutation, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'appendText',
-        description: 'Appends plain text to the end of a document. For formatted content, use appendMarkdown instead.',
+        description: 'Appends plain text to the end of a document. For formatted content, use appendMarkdown instead. ' +
+            'To edit existing content, use modifyText (single-location) or replaceDocumentWithMarkdown (section/full rewrite).',
         parameters: DocumentIdParameter.extend({
-            text: z.string().min(1).describe('The plain text to append to the end of the document.'),
+            text: z.string().optional().describe('The plain text to append to the end of the document. For content longer than ~2000 characters, prefer writing to a local file first and passing filePath instead.'),
+            filePath: z.string().optional().describe('Path to a local text file to use as content. Takes precedence over the text parameter.'),
             addNewlineIfNeeded: z
                 .boolean()
                 .optional()
@@ -20,7 +24,21 @@ export function register(server) {
                 .describe('The ID of the specific tab to append to. If not specified, appends to the first tab (or legacy document.body for documents without tabs).'),
         }),
         execute: async (args, { log }) => {
+            await guardMutation(args.documentId);
             const docs = await getDocsClient();
+            // Resolve text content from filePath or inline parameter
+            let text = args.text;
+            if (args.filePath) {
+                try {
+                    text = await fs.readFile(args.filePath, 'utf-8');
+                    log.info(`Read ${text.length} chars from file: ${args.filePath}`);
+                } catch (err) {
+                    throw new UserError(`Failed to read file at "${args.filePath}": ${err.message}`);
+                }
+            }
+            if (!text || text.length === 0) {
+                throw new UserError('Either text or filePath must be provided with non-empty content.');
+            }
             log.info(`Appending to Google Doc: ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
             try {
                 // Determine if we need tabs content
@@ -54,7 +72,7 @@ export function register(server) {
                     }
                 }
                 // Simpler approach: Always assume insertion is needed unless explicitly told not to add newline
-                const textToInsert = (args.addNewlineIfNeeded && endIndex > 1 ? '\n' : '') + args.text;
+                const textToInsert = (args.addNewlineIfNeeded && endIndex > 1 ? '\n' : '') + text;
                 if (!textToInsert)
                     return 'Nothing to append.';
                 const location = { index: endIndex };
@@ -65,6 +83,7 @@ export function register(server) {
                     insertText: { location, text: textToInsert },
                 };
                 await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request]);
+                trackMutation(args.documentId);
                 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

@@ -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 { guardMutation, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
         name: 'deleteRange',
@@ -27,6 +28,7 @@ export function register(server) {
             path: ['endIndex'],
         }),
         execute: async (args, { log }) => {
+            await guardMutation(args.documentId);
             const docs = await getDocsClient();
             log.info(`Deleting range ${args.startIndex}-${args.endIndex} in doc ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
             if (args.endIndex <= args.startIndex) {
@@ -59,6 +61,7 @@ export function register(server) {
                     deleteContentRange: { range },
                 };
                 await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request]);
+                trackMutation(args.documentId);
                 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

@@ -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 { guardMutation, trackMutation } from '../../readTracker.js';
 const FindAndReplaceParameters = DocumentIdParameter.extend({
     findText: z.string().min(1).describe('The text to search for in the document.'),
     replaceText: z
@@ -24,6 +25,7 @@ export function register(server) {
             'Returns the number of replacements made. Use an empty replaceText to delete all matches.',
         parameters: FindAndReplaceParameters,
         execute: async (args, { log }) => {
+            await guardMutation(args.documentId);
             const docs = await getDocsClient();
             log.info(`findAndReplace in doc ${args.documentId}: "${args.findText}" → "${args.replaceText}"` +
                 `${args.matchCase ? ' (case-sensitive)' : ''}` +
@@ -40,6 +42,7 @@ export function register(server) {
                     },
                 };
                 const response = await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [request]);
+                trackMutation(args.documentId);
                 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

@@ -18,8 +18,8 @@ export function register(server) {
                 // STEP 1: Determine the target paragraph's range based on the targeting method
                 if ('textToFind' in args.target) {
                     // Find the text first
-                    log.info(`Finding text "${args.target.textToFind}" (instance ${args.target.matchInstance || 1})${args.tabId ? ` in tab ${args.tabId}` : ''}`);
-                    const textRange = await GDocsHelpers.findTextRange(docs, args.documentId, args.target.textToFind, args.target.matchInstance || 1, args.tabId);
+                    log.info(`Finding text "${args.target.textToFind}" (instance ${args.target.matchInstance ?? 'auto'})${args.tabId ? ` in tab ${args.tabId}` : ''}`);
+                    const textRange = await GDocsHelpers.findTextRange(docs, args.documentId, args.target.textToFind, args.target.matchInstance, args.tabId);
                     if (!textRange) {
                         throw new UserError(`Could not find "${args.target.textToFind}" in the document${args.tabId ? ` (tab: ${args.tabId})` : ''}.`);
                     }