google-tools-mcp 1.2.12 → 2.0.0

package/dist/tools/threads.js

@@ -1,145 +1,145 @@
-// Gmail Thread tools
-import { z } from 'zod';
-import { getGmailClient } from '../clients.js';
-import { processMessagePart } from '../helpers.js';
-
-export function register(server) {
-    server.addTool({
-        name: 'get_thread',
-        description: 'Get a specific thread by ID',
-        parameters: z.object({
-            id: z.string().describe("The ID of the thread to retrieve"),
-            includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body"),
-        }),
-        execute: async (params) => {
-            const gmail = await getGmailClient();
-            const { data } = await gmail.users.threads.get({ userId: 'me', id: params.id, format: 'full' });
-            if (data.messages) {
-                data.messages = data.messages.map(message => {
-                    if (message.payload) {
-                        message.payload = processMessagePart(message.payload, params.includeBodyHtml);
-                    }
-                    return message;
-                });
-            }
-            return JSON.stringify(data);
-        },
-    });
-
-    server.addTool({
-        name: 'list_threads',
-        description: 'List threads in the user\'s mailbox',
-        parameters: z.object({
-            maxResults: z.number().optional().describe("Maximum number of threads to return"),
-            pageToken: z.string().optional().describe("Page token to retrieve a specific page of results"),
-            q: z.string().optional().describe("Only return threads matching the specified query"),
-            labelIds: z.array(z.string()).optional().describe("Only return threads with labels that match all specified label IDs"),
-            includeSpamTrash: z.boolean().optional().describe("Include threads from SPAM and TRASH"),
-            includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body"),
-        }),
-        execute: async (params) => {
-            const gmail = await getGmailClient();
-            const { data } = await gmail.users.threads.list({ userId: 'me', ...params });
-            if (data.threads) {
-                data.threads = data.threads.map(thread => {
-                    if (thread.messages) {
-                        thread.messages = thread.messages.map(message => {
-                            if (message.payload) {
-                                message.payload = processMessagePart(message.payload, params.includeBodyHtml);
-                            }
-                            return message;
-                        });
-                    }
-                    return thread;
-                });
-            }
-            return JSON.stringify(data);
-        },
-    });
-
-    server.addTool({
-        name: 'batch_get_threads',
-        description: 'Get multiple threads by ID in parallel. More efficient than calling get_thread multiple times.',
-        parameters: z.object({
-            ids: z.array(z.string()).describe("The IDs of the threads to retrieve"),
-            includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body"),
-        }),
-        execute: async (params) => {
-            const gmail = await getGmailClient();
-            const results = await Promise.all(
-                params.ids.map(async (id) => {
-                    try {
-                        const { data } = await gmail.users.threads.get({ userId: 'me', id, format: 'full' });
-                        if (data.messages) {
-                            data.messages = data.messages.map(message => {
-                                if (message.payload) {
-                                    message.payload = processMessagePart(message.payload, params.includeBodyHtml);
-                                }
-                                return message;
-                            });
-                        }
-                        return data;
-                    } catch (error) {
-                        return { id, error: error.message || 'Failed to retrieve thread' };
-                    }
-                })
-            );
-            return JSON.stringify(results);
-        },
-    });
-
-    server.addTool({
-        name: 'modify_thread',
-        description: 'Modify the labels applied to a thread',
-        parameters: z.object({
-            id: z.string().describe("The ID of the thread to modify"),
-            addLabelIds: z.array(z.string()).optional().describe("Label IDs to add"),
-            removeLabelIds: z.array(z.string()).optional().describe("Label IDs to remove"),
-        }),
-        execute: async (params) => {
-            const { id, ...threadData } = params;
-            const gmail = await getGmailClient();
-            const { data } = await gmail.users.threads.modify({ userId: 'me', id, requestBody: threadData });
-            return JSON.stringify(data);
-        },
-    });
-
-    server.addTool({
-        name: 'delete_thread',
-        description: 'Delete a thread',
-        parameters: z.object({
-            id: z.string().describe("The ID of the thread to delete"),
-        }),
-        execute: async (params) => {
-            const gmail = await getGmailClient();
-            const { data } = await gmail.users.threads.delete({ userId: 'me', id: params.id });
-            return JSON.stringify(data || { success: true });
-        },
-    });
-
-    server.addTool({
-        name: 'trash_thread',
-        description: 'Move a thread to the trash',
-        parameters: z.object({
-            id: z.string().describe("The ID of the thread to move to trash"),
-        }),
-        execute: async (params) => {
-            const gmail = await getGmailClient();
-            const { data } = await gmail.users.threads.trash({ userId: 'me', id: params.id });
-            return JSON.stringify(data);
-        },
-    });
-
-    server.addTool({
-        name: 'untrash_thread',
-        description: 'Remove a thread from the trash',
-        parameters: z.object({
-            id: z.string().describe("The ID of the thread to remove from trash"),
-        }),
-        execute: async (params) => {
-            const gmail = await getGmailClient();
-            const { data } = await gmail.users.threads.untrash({ userId: 'me', id: params.id });
-            return JSON.stringify(data);
-        },
-    });
-}
+// Gmail Thread tools
+import { z } from 'zod';
+import { getGmailClient } from '../clients.js';
+import { processMessagePart } from '../helpers.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'get_thread',
+        description: 'Get a specific thread by ID',
+        parameters: z.object({
+            id: z.string().describe("The ID of the thread to retrieve"),
+            includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body"),
+        }),
+        execute: async (params) => {
+            const gmail = await getGmailClient();
+            const { data } = await gmail.users.threads.get({ userId: 'me', id: params.id, format: 'full' });
+            if (data.messages) {
+                data.messages = data.messages.map(message => {
+                    if (message.payload) {
+                        message.payload = processMessagePart(message.payload, params.includeBodyHtml);
+                    }
+                    return message;
+                });
+            }
+            return JSON.stringify(data);
+        },
+    });
+
+    server.addTool({
+        name: 'list_threads',
+        description: 'List threads in the user\'s mailbox',
+        parameters: z.object({
+            maxResults: z.number().optional().describe("Maximum number of threads to return"),
+            pageToken: z.string().optional().describe("Page token to retrieve a specific page of results"),
+            q: z.string().optional().describe("Only return threads matching the specified query"),
+            labelIds: z.array(z.string()).optional().describe("Only return threads with labels that match all specified label IDs"),
+            includeSpamTrash: z.boolean().optional().describe("Include threads from SPAM and TRASH"),
+            includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body"),
+        }),
+        execute: async (params) => {
+            const gmail = await getGmailClient();
+            const { data } = await gmail.users.threads.list({ userId: 'me', ...params });
+            if (data.threads) {
+                data.threads = data.threads.map(thread => {
+                    if (thread.messages) {
+                        thread.messages = thread.messages.map(message => {
+                            if (message.payload) {
+                                message.payload = processMessagePart(message.payload, params.includeBodyHtml);
+                            }
+                            return message;
+                        });
+                    }
+                    return thread;
+                });
+            }
+            return JSON.stringify(data);
+        },
+    });
+
+    server.addTool({
+        name: 'batch_get_threads',
+        description: 'Get multiple threads by ID in parallel. More efficient than calling get_thread multiple times.',
+        parameters: z.object({
+            ids: z.array(z.string()).describe("The IDs of the threads to retrieve"),
+            includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body"),
+        }),
+        execute: async (params) => {
+            const gmail = await getGmailClient();
+            const results = await Promise.all(
+                params.ids.map(async (id) => {
+                    try {
+                        const { data } = await gmail.users.threads.get({ userId: 'me', id, format: 'full' });
+                        if (data.messages) {
+                            data.messages = data.messages.map(message => {
+                                if (message.payload) {
+                                    message.payload = processMessagePart(message.payload, params.includeBodyHtml);
+                                }
+                                return message;
+                            });
+                        }
+                        return data;
+                    } catch (error) {
+                        return { id, error: error.message || 'Failed to retrieve thread' };
+                    }
+                })
+            );
+            return JSON.stringify(results);
+        },
+    });
+
+    server.addTool({
+        name: 'modify_thread',
+        description: 'Modify the labels applied to a thread',
+        parameters: z.object({
+            id: z.string().describe("The ID of the thread to modify"),
+            addLabelIds: z.array(z.string()).optional().describe("Label IDs to add"),
+            removeLabelIds: z.array(z.string()).optional().describe("Label IDs to remove"),
+        }),
+        execute: async (params) => {
+            const { id, ...threadData } = params;
+            const gmail = await getGmailClient();
+            const { data } = await gmail.users.threads.modify({ userId: 'me', id, requestBody: threadData });
+            return JSON.stringify(data);
+        },
+    });
+
+    server.addTool({
+        name: 'delete_thread',
+        description: 'Delete a thread',
+        parameters: z.object({
+            id: z.string().describe("The ID of the thread to delete"),
+        }),
+        execute: async (params) => {
+            const gmail = await getGmailClient();
+            const { data } = await gmail.users.threads.delete({ userId: 'me', id: params.id });
+            return JSON.stringify(data || { success: true });
+        },
+    });
+
+    server.addTool({
+        name: 'trash_thread',
+        description: 'Move a thread to the trash',
+        parameters: z.object({
+            id: z.string().describe("The ID of the thread to move to trash"),
+        }),
+        execute: async (params) => {
+            const gmail = await getGmailClient();
+            const { data } = await gmail.users.threads.trash({ userId: 'me', id: params.id });
+            return JSON.stringify(data);
+        },
+    });
+
+    server.addTool({
+        name: 'untrash_thread',
+        description: 'Remove a thread from the trash',
+        parameters: z.object({
+            id: z.string().describe("The ID of the thread to remove from trash"),
+        }),
+        execute: async (params) => {
+            const gmail = await getGmailClient();
+            const { data } = await gmail.users.threads.untrash({ userId: 'me', id: params.id });
+            return JSON.stringify(data);
+        },
+    });
+}

package/dist/tools/utils/appendMarkdownToGoogleDoc.js

@@ -5,12 +5,13 @@ import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter, MarkdownConversionError } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
 import { insertMarkdown, formatInsertResult, 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: 'appendMarkdown',
         description: 'Best for adding new formatted content to the end of a document. ' +
             'Supports headings, bold, italic, strikethrough, links, tables, bullet/numbered lists, and rich markdown HTML extensions for underline, color, highlight, font, alignment, and blockquotes. ' +
+            'Does not support markdown images or raw HTML outside those listed extensions; unsupported content is omitted and reported as warnings in the result. Use insertImage for images. ' +
             'Use this instead of appendText when you need formatting. ' +
             'To edit existing content, use modifyText (single-location) or replaceDocumentWithMarkdown (section/full rewrite).',
         parameters: DocumentIdParameter.extend({
@@ -36,7 +37,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 markdown content from filePath or inline parameter
@@ -54,6 +59,13 @@ export function register(server) {
             }
             log.info(`Appending markdown to doc ${args.documentId} (${markdown.length} chars)${args.tabId ? ` in tab ${args.tabId}` : ''}`);
             try {
+                const revisionId = getLastReadRevisionId(args.documentId);
+                // Optimistic-concurrency guard. The first write carries the revision
+                // from our last read; each subsequent write advances to the revision the
+                // previous write produced (returned by batchUpdate). This keeps every
+                // write in the operation guarded against concurrent edits instead of
+                // dropping the guard after the first write (PR #42 review).
+                const writeControlChain = GDocsHelpers.createWriteControlChain(revisionId);
                 // 1. Get document end index
                 const doc = await docs.documents.get({
                     documentId: args.documentId,
@@ -85,14 +97,15 @@ export function register(server) {
                     if (args.tabId) {
                         location.tabId = args.tabId;
                     }
-                    await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [
+                    const spacingResult = await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [
                         {
                             insertText: {
                                 location,
                                 text: '\n\n',
                             },
                         },
-                    ]);
+                    ], writeControlChain.current);
+                    writeControlChain.advance(spacingResult);
                     startIndex += 2;
                     log.info(`Added spacing, new start index: ${startIndex}`);
                 }
@@ -101,12 +114,23 @@ export function register(server) {
                     startIndex,
                     tabId: args.tabId,
                     firstHeadingAsTitle: args.firstHeadingAsTitle,
+                    // Carries the current guard; insertMarkdown chains it across its own
+                    // split batches so the whole insert stays guarded.
+                    writeControl: writeControlChain.current,
                 });
                 const debugSummary = formatInsertResult(result);
                 log.info(debugSummary);
                 const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
-                trackMutation(args.documentId);
-                return `${docUrl}\nSuccessfully appended ${markdown.length} characters of markdown.\n\n${debugSummary}`;
+                // insertMarkdown chains the guard across its own internal split batches
+                // and returns the final revision as batchUpdate.finalWriteControl; fold
+                // that into our chain so trackMutation re-arms the guard against the
+                // TRUE post-write revision instead of the pre-insert (spacing-only) one.
+                writeControlChain.advance({ writeControl: result.batchUpdate?.finalWriteControl });
+                trackMutation(args.documentId, writeControlChain.current?.requiredRevisionId);
+                const warningNote = result.warnings?.length
+                    ? ` with ${result.warnings.length} warning${result.warnings.length === 1 ? '' : 's'} (content dropped — see below)`
+                    : '';
+                return `${docUrl}\nSuccessfully appended ${markdown.length} characters of markdown${warningNote}.\n\n${debugSummary}`;
             }
             catch (error) {
                 log.error(`Error appending markdown: ${error.message}`);

package/dist/tools/utils/replaceDocumentWithMarkdown.js

@@ -5,17 +5,20 @@ import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter, MarkdownConversionError } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
 import { insertMarkdown, formatInsertResult, docsJsonToMarkdown } from '../../markdown-transformer/index.js';
-import { guardMutation, trackMutation } from '../../readTracker.js';
+import { guardMutation, getLastReadRevisionId, trackMutation } from '../../readTracker.js';
+import { writeWorkspaceFile } from '../../workspace.js';
 export function register(server) {
     server.addTool({
         name: 'replaceDocumentWithMarkdown',
         description: "Best for rewriting entire sections or full documents. Replaces the entire document body with content parsed from markdown. " +
             "Supports headings, bold, italic, strikethrough, links, tables, bullet/numbered lists, and rich markdown HTML extensions for underline, color, highlight, font, alignment, and blockquotes. " +
+            "Does not support markdown images or raw HTML outside those listed extensions; unsupported content is omitted and reported as warnings in the result. Use insertImage for images. " +
             "Use readDocument with format='markdown' first to get the current content, edit it, then call this tool to apply changes. " +
+            "PREFERRED WORKFLOW for large edits: readDocument saves the content to a local working-copy file and returns its path — edit that file, then pass it here as filePath instead of inline markdown, to avoid truncation and get a reviewable diff before pushing. " +
             "For small single-location edits (one line or paragraph), use modifyText instead. " +
             "To add content without rewriting, use appendMarkdown.",
         parameters: DocumentIdParameter.extend({
-            markdown: z.string().optional().describe('The markdown content to apply to the document. For content longer than ~2000 characters, prefer writing to a local file first and passing filePath instead.'),
+            markdown: z.string().optional().describe('Inline markdown content. Prefer filePath instead for content longer than ~2000 characters — use the working-copy path returned by readDocument, edit that file, then pass it here.'),
             filePath: z.string().optional().describe('Path to a local markdown file to use as content. Takes precedence over the markdown parameter. Use this for large documents to avoid truncation.'),
             preserveTitle: z
                 .boolean()
@@ -37,7 +40,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 markdown content from filePath or inline parameter
@@ -55,6 +62,14 @@ export function register(server) {
             }
             log.info(`Replacing doc ${args.documentId} with markdown (${markdown.length} chars)${args.tabId ? ` in tab ${args.tabId}` : ''}`);
             try {
+                const revisionId = getLastReadRevisionId(args.documentId);
+                // Optimistic-concurrency guard. The first write carries the revision
+                // from our last read; each subsequent write advances to the revision the
+                // previous write produced (returned by batchUpdate). This keeps every
+                // write in the operation (delete → cleanup → insert) guarded against
+                // concurrent edits instead of dropping the guard after the first write
+                // (PR #42 review).
+                const writeControlChain = GDocsHelpers.createWriteControlChain(revisionId);
                 // 1. Get document structure
                 const doc = await docs.documents.get({
                     documentId: args.documentId,
@@ -97,11 +112,12 @@ export function register(server) {
                         deleteRange.tabId = args.tabId;
                     }
                     log.info(`Deleting content from index ${startIndex} to ${endIndex}`);
-                    await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [
+                    const deleteResult = await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [
                         {
                             deleteContentRange: { range: deleteRange },
                         },
-                    ]);
+                    ], writeControlChain.current);
+                    writeControlChain.advance(deleteResult);
                     log.info(`Delete complete.`);
                 }
                 // 4. Clean the surviving trailing paragraph.
@@ -149,11 +165,29 @@ export function register(server) {
                             },
                         },
                     ];
+                    // This cleanup is the operation's first write when the delete step
+                    // was skipped (empty document), so it must carry the current guard —
+                    // otherwise it bumps the revision and the insert below fails with a
+                    // spurious conflict against the revision from the read. Peek (don't
+                    // advance yet): the cleanup is best-effort, and only a SUCCESSFUL
+                    // cleanup changes the revision.
+                    const cleanupWriteControl = writeControlChain.current;
                     try {
-                        await GDocsHelpers.executeBatchUpdate(docs, args.documentId, cleanupRequests);
+                        const cleanupResult = await GDocsHelpers.executeBatchUpdate(docs, args.documentId, cleanupRequests, cleanupWriteControl);
+                        // Advance only after success, so the insert requires the revision
+                        // the cleanup produced.
+                        writeControlChain.advance(cleanupResult);
                         log.info(`Cleaned surviving paragraph (bullets + text style) at range ${startIndex}-${survivorEnd}`);
                     }
                     catch (e) {
+                        // A revision conflict is a genuine concurrent edit — surface it
+                        // instead of proceeding to clobber the document unguarded.
+                        if (cleanupWriteControl && e instanceof UserError && /changed since you last read/i.test(e.message)) {
+                            throw e;
+                        }
+                        // Non-conflict failure: the cleanup did not modify the document,
+                        // so the revision is unchanged and writeControlChain.current still
+                        // guards the insert below (we deliberately did NOT advance it).
                         log.info(`Survivor cleanup skipped: ${e.message}`);
                     }
                 }
@@ -163,12 +197,41 @@ export function register(server) {
                     startIndex,
                     tabId: args.tabId,
                     firstHeadingAsTitle: args.firstHeadingAsTitle,
+                    // Carries the current guard; insertMarkdown chains it across its own
+                    // split batches so the whole insert stays guarded.
+                    writeControl: writeControlChain.current,
                 });
                 const debugSummary = formatInsertResult(result);
                 log.info(debugSummary);
-                trackMutation(args.documentId);
+                // insertMarkdown chains the guard across its own internal split batches
+                // and returns the final revision as batchUpdate.finalWriteControl; fold
+                // that into our chain so trackMutation re-arms the guard against the
+                // TRUE post-write revision instead of the pre-insert (delete/cleanup) one.
+                writeControlChain.advance({ writeControl: result.batchUpdate?.finalWriteControl });
+                trackMutation(args.documentId, writeControlChain.current?.requiredRevisionId);
+                // Mirror the pushed markdown to the local workspace only now that the
+                // Docs mutation has actually succeeded and been tracked. Writing this
+                // earlier (before the fetch/delete/cleanup/insert sequence above)
+                // meant that if any of those steps failed, the local file held content
+                // that was never committed to the document; worse, if the delete
+                // succeeded but the insert failed, the workspace file would show the
+                // full intended result while the document itself was left partial.
+                // Scoped by tabId so it lines up with the per-tab file readDocument
+                // created. Non-fatal: a failure to save the mirror doesn't undo an
+                // already-successful Docs write, so we log and continue.
+                if (!args.filePath) {
+                    try {
+                        const workspacePath = await writeWorkspaceFile(args.documentId, markdown, args.tabId);
+                        log.info(`Saved working copy to ${workspacePath}`);
+                    } catch (e) {
+                        log.info(`Could not save working copy: ${e.message}`);
+                    }
+                }
                 const docUrl = `https://docs.google.com/document/d/${args.documentId}/edit`;
-                return `${docUrl}\nSuccessfully replaced document content with ${markdown.length} characters of markdown.\n\n${debugSummary}`;
+                const warningNote = result.warnings?.length
+                    ? ` with ${result.warnings.length} warning${result.warnings.length === 1 ? '' : 's'} (content dropped — see below)`
+                    : '';
+                return `${docUrl}\nSuccessfully replaced document content with ${markdown.length} characters of markdown${warningNote}.\n\n${debugSummary}`;
             }
             catch (error) {
                 log.error(`Error replacing document with markdown: ${error.message}`);