google-tools-mcp 1.2.12 → 2.0.0

package/dist/tools/docs/modifyText.js

@@ -4,7 +4,7 @@ import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter, TextFindParameter, TextStyleParameters, ParagraphStyleParameters } 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 RangeTarget = z
     .object({
     startIndex: z.number().int().min(1).describe('Start of range (inclusive, 1-based).'),
@@ -110,7 +110,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(`modifyText on doc ${args.documentId}: target=${JSON.stringify(args.target)}` +
@@ -173,8 +177,14 @@ export function register(server) {
                 if (requests.length === 0) {
                     return 'No operations to perform.';
                 }
-                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, requests);
-                trackMutation(args.documentId);
+                const revisionId = getLastReadRevisionId(args.documentId);
+                const writeResponse = await GDocsHelpers.executeBatchUpdate(
+                    docs,
+                    args.documentId,
+                    requests,
+                    revisionId ? { requiredRevisionId: revisionId } : undefined
+                );
+                trackMutation(args.documentId, writeResponse?.writeControl?.requiredRevisionId);
                 // Build descriptive result
                 const actions = [];
                 if (endIndex !== undefined && normalizedText === '')

package/dist/tools/docs/modifyText.test.js

@@ -2,91 +2,91 @@ import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { buildModifyTextRequests } from './modifyText.js';
 import { stripMarkdownListMarkersForSearch } from '../../googleDocsApiHelpers.js';
-
-describe('buildModifyTextRequests', () => {
-  it('generates deleteContentRange + insertText for a replacement', () => {
-    const reqs = buildModifyTextRequests({
-      startIndex: 5,
-      endIndex: 10,
-      text: 'hello',
-    });
-    assert.equal(reqs.length, 2);
-    assert.deepEqual(reqs[0], {
-      deleteContentRange: { range: { startIndex: 5, endIndex: 10 } },
-    });
-    assert.deepEqual(reqs[1], {
-      insertText: { location: { index: 5 }, text: 'hello' },
-    });
-  });
-
-  it('generates only insertText for an insertion (no endIndex)', () => {
-    const reqs = buildModifyTextRequests({
-      startIndex: 3,
-      endIndex: undefined,
-      text: 'hi',
-    });
-    assert.equal(reqs.length, 1);
-    assert.deepEqual(reqs[0], {
-      insertText: { location: { index: 3 }, text: 'hi' },
-    });
-  });
-
-  it('returns empty array when no text/style/paragraphStyle given', () => {
-    const reqs = buildModifyTextRequests({
-      startIndex: 1,
-      endIndex: 5,
-    });
-    assert.equal(reqs.length, 0);
-  });
-
-  it('includes tabId in range and location when provided', () => {
-    const reqs = buildModifyTextRequests({
-      startIndex: 1,
-      endIndex: 4,
-      text: 'x',
-      tabId: 'tab1',
-    });
-    assert.deepEqual(reqs[0].deleteContentRange.range.tabId, 'tab1');
-    assert.deepEqual(reqs[1].insertText.location.tabId, 'tab1');
-  });
-});
-
+
+describe('buildModifyTextRequests', () => {
+  it('generates deleteContentRange + insertText for a replacement', () => {
+    const reqs = buildModifyTextRequests({
+      startIndex: 5,
+      endIndex: 10,
+      text: 'hello',
+    });
+    assert.equal(reqs.length, 2);
+    assert.deepEqual(reqs[0], {
+      deleteContentRange: { range: { startIndex: 5, endIndex: 10 } },
+    });
+    assert.deepEqual(reqs[1], {
+      insertText: { location: { index: 5 }, text: 'hello' },
+    });
+  });
+
+  it('generates only insertText for an insertion (no endIndex)', () => {
+    const reqs = buildModifyTextRequests({
+      startIndex: 3,
+      endIndex: undefined,
+      text: 'hi',
+    });
+    assert.equal(reqs.length, 1);
+    assert.deepEqual(reqs[0], {
+      insertText: { location: { index: 3 }, text: 'hi' },
+    });
+  });
+
+  it('returns empty array when no text/style/paragraphStyle given', () => {
+    const reqs = buildModifyTextRequests({
+      startIndex: 1,
+      endIndex: 5,
+    });
+    assert.equal(reqs.length, 0);
+  });
+
+  it('includes tabId in range and location when provided', () => {
+    const reqs = buildModifyTextRequests({
+      startIndex: 1,
+      endIndex: 4,
+      text: 'x',
+      tabId: 'tab1',
+    });
+    assert.deepEqual(reqs[0].deleteContentRange.range.tabId, 'tab1');
+    assert.deepEqual(reqs[1].insertText.location.tabId, 'tab1');
+  });
+});
+
 describe('escape sequence normalization (issue #9)', () => {
-  // Simulate the normalization that happens in the execute handler
-  function normalize(text) {
-    return text?.replace(/\\n/g, '\n').replace(/\\t/g, '\t');
-  }
-
-  it('converts literal \\n to real newline', () => {
-    const input = 'line one\\nline two\\nline three';
-    const result = normalize(input);
-    assert.equal(result, 'line one\nline two\nline three');
-  });
-
-  it('converts literal \\t to real tab', () => {
-    const input = 'col1\\tcol2\\tcol3';
-    const result = normalize(input);
-    assert.equal(result, 'col1\tcol2\tcol3');
-  });
-
-  it('handles mixed \\n and \\t', () => {
-    const input = 'row1\\tcol2\\nrow2\\tcol2';
-    const result = normalize(input);
-    assert.equal(result, 'row1\tcol2\nrow2\tcol2');
-  });
-
-  it('leaves text without escape sequences unchanged', () => {
-    const input = 'no escapes here';
-    assert.equal(normalize(input), 'no escapes here');
-  });
-
-  it('preserves real newlines that are already in the string', () => {
-    const input = 'already\nreal';
-    assert.equal(normalize(input), 'already\nreal');
-  });
-
-  it('returns undefined for undefined input', () => {
-    assert.equal(normalize(undefined), undefined);
+  // Simulate the normalization that happens in the execute handler
+  function normalize(text) {
+    return text?.replace(/\\n/g, '\n').replace(/\\t/g, '\t');
+  }
+
+  it('converts literal \\n to real newline', () => {
+    const input = 'line one\\nline two\\nline three';
+    const result = normalize(input);
+    assert.equal(result, 'line one\nline two\nline three');
+  });
+
+  it('converts literal \\t to real tab', () => {
+    const input = 'col1\\tcol2\\tcol3';
+    const result = normalize(input);
+    assert.equal(result, 'col1\tcol2\tcol3');
+  });
+
+  it('handles mixed \\n and \\t', () => {
+    const input = 'row1\\tcol2\\nrow2\\tcol2';
+    const result = normalize(input);
+    assert.equal(result, 'row1\tcol2\nrow2\tcol2');
+  });
+
+  it('leaves text without escape sequences unchanged', () => {
+    const input = 'no escapes here';
+    assert.equal(normalize(input), 'no escapes here');
+  });
+
+  it('preserves real newlines that are already in the string', () => {
+    const input = 'already\nreal';
+    assert.equal(normalize(input), 'already\nreal');
+  });
+
+  it('returns undefined for undefined input', () => {
+    assert.equal(normalize(undefined), undefined);
   });
 });
 

package/dist/tools/docs/readGoogleDoc.js

@@ -4,8 +4,9 @@ import { createPatch } from 'diff';
 import { getDocsClient, getDriveClient } from '../../clients.js';
 import { DocumentIdParameter, NotImplementedError } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
-import { docsJsonToMarkdown } from '../../markdown-transformer/index.js';
+import { docsJsonToMarkdown, checkMarkdownFidelity } from '../../markdown-transformer/index.js';
 import { trackRead, getLastReadContent } from '../../readTracker.js';
+import { writeWorkspaceFile } from '../../workspace.js';
 
 async function fetchModifiedTime(documentId) {
     try {
@@ -24,7 +25,10 @@ async function fetchModifiedTime(documentId) {
 export function register(server) {
     server.addTool({
         name: 'readDocument',
-        description: "Reads the content of a Google Document. Returns markdown by default (formatted content suitable for editing and re-uploading with replaceDocumentWithMarkdown). Use format='text' for plain text, or format='json' for the raw document structure. Set diffFromLastRead=true (markdown only) to get a unified diff from your previous read in this session instead of the full content.",
+        description: "Reads the content of a Google Document. Returns markdown by default (formatted content suitable for editing and re-uploading with replaceDocumentWithMarkdown) and saves it to a local working-copy file (path included in the response). " +
+            "PREFERRED EDITING WORKFLOW for large edits: (1) readDocument to get the local file path, (2) edit that file locally, (3) call replaceDocumentWithMarkdown with filePath pointing to it. This avoids inline content truncation and gives you a reviewable working copy before pushing changes. " +
+            "If the document contains content markdown cannot represent (images, footnotes), a warning is appended listing what replaceDocumentWithMarkdown would permanently remove — prefer modifyText or appendMarkdown for those documents. " +
+            "Use format='text' for plain text, or format='json' for the raw document structure. Set diffFromLastRead=true (markdown only) to get a unified diff from your previous read in this session instead of the full content.",
         parameters: DocumentIdParameter.extend({
             format: z
                 .enum(['text', 'json', 'markdown'])
@@ -53,7 +57,7 @@ export function register(server) {
                 const needsTabsContent = !!args.tabId;
                 const fields = args.format === 'json' || args.format === 'markdown'
                     ? '*' // Get everything for structure analysis
-                    : 'body(content(paragraph(elements(textRun(content)))))'; // Just text content
+                    : 'revisionId,body(content(paragraph(elements(textRun(content)))))'; // Just text content
                 const res = await docs.documents.get({
                     documentId: args.documentId,
                     includeTabsContent: needsTabsContent,
@@ -71,7 +75,12 @@ export function register(server) {
                     if (!targetTab.documentTab) {
                         throw new UserError(`Tab "${args.tabId}" does not have content (may not be a document tab).`);
                     }
-                    contentSource = { body: targetTab.documentTab.body };
+                    // List definitions are scoped to the document tab. Without them,
+                    // docsJsonToMarkdown cannot distinguish ordered lists from bullets.
+                    contentSource = {
+                        body: targetTab.documentTab.body,
+                        lists: targetTab.documentTab.lists,
+                    };
                     log.info(`Using content from tab: ${targetTab.tabProperties?.title || 'Untitled'}`);
                 }
                 else {
@@ -82,7 +91,7 @@ export function register(server) {
                     if (args.diffFromLastRead) {
                         log.info('diffFromLastRead ignored: only supported for format=markdown');
                     }
-                    trackRead(args.documentId, modifiedTime);
+                    trackRead(args.documentId, modifiedTime, undefined, res.data.revisionId);
                     const jsonContent = JSON.stringify(contentSource, null, 2);
                     // Apply length limit to JSON if specified
                     if (args.maxLength && jsonContent.length > args.maxLength) {
@@ -95,6 +104,18 @@ export function register(server) {
                     const markdownContent = docsJsonToMarkdown(contentSource);
                     const totalLength = markdownContent.length;
                     log.info(`Generated markdown: ${totalLength} characters`);
+                    // Derive fidelity warnings from EXACTLY the body that will be replaced
+                    // (contentSource.body is the active tab's body in tab mode, the document
+                    // body otherwise). This scopes image/footnote detection to the content
+                    // the replacement mutates and never over-reports images or footnotes
+                    // living in other tabs or in headers/footers a body replacement leaves
+                    // untouched.
+                    const fidelityWarnings = checkMarkdownFidelity(contentSource.body?.content);
+                    const fidelityNotice = fidelityWarnings.length > 0
+                        ? '\n\n---\n⚠️ FORMATTING LOSS WARNING: This document contains content that cannot be represented in markdown. Calling replaceDocumentWithMarkdown will permanently lose:\n' +
+                            fidelityWarnings.map(w => `  • ${w}`).join('\n') +
+                            '\nConsider using modifyText or appendMarkdown for targeted edits instead.\n---'
+                        : '';
                     if (args.diffFromLastRead) {
                         const previous = getLastReadContent(args.documentId);
                         if (previous !== null) {
@@ -106,18 +127,57 @@ export function register(server) {
                                 'current',
                                 { context: 3 }
                             );
-                            trackRead(args.documentId, modifiedTime, markdownContent);
-                            return patch;
+                            trackRead(args.documentId, modifiedTime, markdownContent, res.data.revisionId);
+                            // Keep the on-disk working copy in sync even on diff reads, so a
+                            // subsequent edit-and-push starts from the current document state.
+                            try {
+                                await writeWorkspaceFile(args.documentId, markdownContent, args.tabId);
+                            } catch (e) {
+                                log.info(`Could not update workspace on diff read: ${e.message}`);
+                            }
+                            // The diff can be silent about content the converter has no
+                            // representation for: an image or footnote another editor added
+                            // since the last read simply is not in either markdown snapshot,
+                            // so it never shows up as a change. The workspace file was still
+                            // refreshed above, and pushing it back would delete that content.
+                            // Carry the same warning the full read gives.
+                            return patch + fidelityNotice;
                         }
                         log.info('diffFromLastRead requested but no prior snapshot exists; returning full content');
                     }
-                    trackRead(args.documentId, modifiedTime, markdownContent);
+                    // Store clean markdown (without warning) for future diffs and guardMutation
+                    trackRead(args.documentId, modifiedTime, markdownContent, res.data.revisionId);
+                    // Save to local workspace file so the AI can edit it and push with filePath.
+                    // Scoped by tabId so two tabs of the same document keep separate copies.
+                    let localPath = null;
+                    try {
+                        localPath = await writeWorkspaceFile(args.documentId, markdownContent, args.tabId);
+                        log.info(`Saved to ${localPath}`);
+                    } catch (e) {
+                        log.info(`Could not save to workspace: ${e.message}`);
+                        localPath = null;
+                    }
                     // Apply length limit to markdown if specified
+                    let output;
                     if (args.maxLength && totalLength > args.maxLength) {
                         const truncatedContent = markdownContent.substring(0, args.maxLength);
-                        return `${truncatedContent}\n\n... [Markdown truncated to ${args.maxLength} chars of ${totalLength} total. Use maxLength parameter to adjust limit or remove it to get full content.]`;
+                        output = `${truncatedContent}\n\n... [Markdown truncated to ${args.maxLength} chars of ${totalLength} total. Use maxLength parameter to adjust limit or remove it to get full content.]`;
+                    } else {
+                        output = markdownContent;
+                    }
+                    // Append fidelity warning after the markdown so the AI knows what
+                    // replaceDocumentWithMarkdown would permanently destroy.
+                    output += fidelityNotice;
+                    if (localPath) {
+                        // Use forward slashes in the advice string so the path is valid JSON
+                        // regardless of OS (backslashes in Windows paths break JSON encoding).
+                        const jsonSafePath = localPath.replace(/\\/g, '/');
+                        // If this was a tab read, the file holds only that tab's content, so the
+                        // push must target the same tab to avoid writing it into the wrong tab.
+                        const tabAdvice = args.tabId ? ` tabId="${args.tabId}"` : '';
+                        output += `\n\n📄 Local file: ${localPath}\nEdit this file, then call replaceDocumentWithMarkdown with filePath="${jsonSafePath}"${tabAdvice} to push changes.`;
                     }
-                    return markdownContent;
+                    return output;
                 }
                 // Default: Text format - extract all text content
                 if (args.diffFromLastRead) {
@@ -151,7 +211,7 @@ export function register(server) {
                         });
                     }
                 });
-                trackRead(args.documentId, modifiedTime);
+                trackRead(args.documentId, modifiedTime, undefined, res.data.revisionId);
                 if (!textContent.trim())
                     return 'Document found, but appears empty.';
                 const totalLength = textContent.length;

package/dist/tools/docs/renameTab.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: 'renameTab',
@@ -28,22 +29,19 @@ export function register(server) {
                     throw new UserError(`Tab with ID "${args.tabId}" not found in document.`);
                 }
                 const oldTitle = targetTab.tabProperties?.title || '(untitled)';
-                await docs.documents.batchUpdate({
-                    documentId: args.documentId,
-                    requestBody: {
-                        requests: [
-                            {
-                                updateDocumentTabProperties: {
-                                    tabProperties: {
-                                        tabId: args.tabId,
-                                        title: args.newTitle,
-                                    },
-                                    fields: 'title',
-                                },
+                const revisionId = getLastReadRevisionId(args.documentId);
+                const response = await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [
+                    {
+                        updateDocumentTabProperties: {
+                            tabProperties: {
+                                tabId: args.tabId,
+                                title: args.newTitle,
                             },
-                        ],
+                            fields: 'title',
+                        },
                     },
-                });
+                ], revisionId ? { requiredRevisionId: revisionId } : undefined);
+                trackMutation(args.documentId, response?.writeControl?.requiredRevisionId);
                 const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
                 return `${docUrl}\nSuccessfully renamed tab from "${oldTitle}" to "${args.newTitle}".`;
             }