google-tools-mcp 1.2.4 → 1.2.6

package/dist/auth.js

@@ -54,6 +54,8 @@ const SCOPES = [
     'https://www.googleapis.com/auth/forms.responses.readonly',
     // Slides
     'https://www.googleapis.com/auth/presentations',
+    // Tasks
+    'https://www.googleapis.com/auth/tasks',
 ];
 
 // ---------------------------------------------------------------------------

package/dist/clients.js

@@ -14,6 +14,7 @@ let gmailClient = null;
 let calendarClient = null;
 let formsClient = null;
 let slidesClient = null;
+let tasksClient = null;
 
 async function ensureAuth() {
     if (authClient) return;
@@ -46,6 +47,7 @@ async function reauthorize() {
     calendarClient = null;
     formsClient = null;
     slidesClient = null;
+    tasksClient = null;
     authClient = await authorize();
     logger.info('Re-authorization successful.');
 }
@@ -120,6 +122,7 @@ export function resetClients() {
     calendarClient = null;
     formsClient = null;
     slidesClient = null;
+    tasksClient = null;
 }
 
 /**
@@ -194,3 +197,17 @@ export async function getSlidesClient() {
     if (!slides) throw new UserError('Google Slides client is not initialized.');
     return slides;
 }
+
+// --- Tasks client ---
+export async function initializeTasksClient() {
+    if (tasksClient) return { authClient, tasksClient };
+    await ensureAuth();
+    if (!tasksClient) tasksClient = google.tasks({ version: 'v1', auth: authClient });
+    return { authClient, tasksClient };
+}
+
+export async function getTasksClient() {
+    const { tasksClient: tasks } = await initializeTasksClient();
+    if (!tasks) throw new UserError('Google Tasks client is not initialized.');
+    return tasks;
+}

package/dist/readTracker.js

@@ -1,84 +1,145 @@
-// 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);
-}
+// In-memory tracker for read-before-edit guards (issue #18) and diff-aware
+// reading/editing (issue #21).
+// Tracks which files have been read in this session, when, and optionally the
+// content snapshot at the time of the last read so blocked mutations can return
+// a unified diff instead of a bare "modified externally" error.
+import { UserError } from 'fastmcp';
+import { createPatch } from 'diff';
+import { getDriveClient } from './clients.js';
+import { logger } from './logger.js';
+
+// Map of fileId → { readAt: Date, modifiedTime: string|null, content: string|null }
+// content is only populated for file types that opt in (currently Google Docs).
+// Sheets and raw Drive files still track read/modifiedTime only.
+const readLog = new Map();
+
+/**
+ * Record that a file was read. Call from all read tools.
+ * @param fileId
+ * @param modifiedTime Drive API modifiedTime (ISO string) at read time, or null
+ * @param content Optional content snapshot (e.g. markdown for docs) used for diffs
+ */
+export function trackRead(fileId, modifiedTime, content) {
+    readLog.set(fileId, {
+        readAt: new Date(),
+        modifiedTime: modifiedTime || null,
+        content: typeof content === 'string' ? content : 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)
+ * @param opts.contentFetcher - Optional async () => string. If provided and an
+ *   external-change conflict is detected, the fetcher is used to grab current
+ *   content and the UserError message will include a unified diff plus rebase
+ *   instructions rather than a plain error.
+ */
+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();
+                // If we have a stored snapshot and the caller can fetch the
+                // current content, return a diff instead of a bare error so the
+                // model can rebase its edit on top of the new version.
+                if (entry.content && typeof opts?.contentFetcher === 'function') {
+                    let currentContent;
+                    try {
+                        currentContent = await opts.contentFetcher();
+                    } catch (fetchError) {
+                        logger.warn(`contentFetcher failed for ${fileId}: ${fetchError.message}`);
+                    }
+                    if (typeof currentContent === 'string') {
+                        const patch = createPatch(
+                            fileId,
+                            entry.content,
+                            currentContent,
+                            'last read',
+                            'current',
+                            { context: 3 }
+                        );
+                        // Refresh the snapshot so a subsequent read/mutation
+                        // works against the new baseline.
+                        entry.content = currentContent;
+                        entry.modifiedTime = currentModifiedTime;
+                        throw new UserError(
+                            `This file was modified externally since you last read it ` +
+                            `(last read: ${readAt}, last modified: ${currentModifiedTime}).\n\n` +
+                            'Do NOT re-apply your original edit blindly. Build your new edit on ' +
+                            'top of the current version. Below is a unified diff from your last ' +
+                            'read to the current document (old → current). If you need the full ' +
+                            'current content, call readDocument again.\n\n' +
+                            '--- DIFF (last read → current) ---\n' +
+                            patch +
+                            '--- END DIFF ---'
+                        );
+                    }
+                }
+                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;
+        // Content is also stale after our mutation; clear so a future diff
+        // doesn't show our own edits as "external" changes.
+        entry.content = null;
+    }
+}
+
+/**
+ * Check if a file has been read (without throwing).
+ */
+export function hasBeenRead(fileId) {
+    return readLog.has(fileId);
+}
+
+/**
+ * Return the content snapshot from the last read, or null if none stored.
+ */
+export function getLastReadContent(fileId) {
+    const entry = readLog.get(fileId);
+    return entry?.content ?? null;
+}

package/dist/tools/docs/appendToGoogleDoc.js

@@ -4,6 +4,7 @@ import { z } from 'zod';
 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';
 export function register(server) {
     server.addTool({
@@ -24,8 +25,13 @@ 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();
+            await guardMutation(args.documentId, {
+                contentFetcher: async () => {
+                    const current = await docs.documents.get({ documentId: args.documentId });
+                    return docsJsonToMarkdown(current.data);
+                },
+            });
             // Resolve text content from filePath or inline parameter
             let text = args.text;
             if (args.filePath) {

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 { docsJsonToMarkdown } from '../../markdown-transformer/index.js';
 import { guardMutation, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
@@ -28,8 +29,13 @@ export function register(server) {
             path: ['endIndex'],
         }),
         execute: async (args, { log }) => {
-            await guardMutation(args.documentId);
             const docs = await getDocsClient();
+            await guardMutation(args.documentId, {
+                contentFetcher: async () => {
+                    const current = await docs.documents.get({ documentId: args.documentId });
+                    return docsJsonToMarkdown(current.data);
+                },
+            });
             log.info(`Deleting range ${args.startIndex}-${args.endIndex} in doc ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
             if (args.endIndex <= args.startIndex) {
                 throw new UserError('End index must be greater than start index for deletion.');

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 { docsJsonToMarkdown } from '../../markdown-transformer/index.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.'),
@@ -25,8 +26,13 @@ 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();
+            await guardMutation(args.documentId, {
+                contentFetcher: async () => {
+                    const current = await docs.documents.get({ documentId: args.documentId });
+                    return docsJsonToMarkdown(current.data);
+                },
+            });
             log.info(`findAndReplace in doc ${args.documentId}: "${args.findText}" → "${args.replaceText}"` +
                 `${args.matchCase ? ' (case-sensitive)' : ''}` +
                 `${args.tabId ? ` (tab: ${args.tabId})` : ''}`);

package/dist/tools/docs/modifyText.js

@@ -3,6 +3,7 @@ import { z } from 'zod';
 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';
 const RangeTarget = z
     .object({
@@ -104,8 +105,13 @@ export function register(server) {
             'To add content to the end of a doc, use appendMarkdown or appendText.',
         parameters: ModifyTextParameters,
         execute: async (args, { log }) => {
-            await guardMutation(args.documentId);
             const docs = await getDocsClient();
+            await guardMutation(args.documentId, {
+                contentFetcher: async () => {
+                    const current = await docs.documents.get({ documentId: args.documentId });
+                    return docsJsonToMarkdown(current.data);
+                },
+            });
             log.info(`modifyText on doc ${args.documentId}: target=${JSON.stringify(args.target)}` +
                 `${args.text !== undefined ? `, text="${args.text.substring(0, 50)}"` : ''}` +
                 `${args.style ? `, style=${JSON.stringify(args.style)}` : ''}` +

package/dist/tools/docs/readGoogleDoc.js

@@ -1,14 +1,30 @@
 import { UserError } from 'fastmcp';
 import { z } from 'zod';
+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 { trackRead } from '../../readTracker.js';
+import { trackRead, getLastReadContent } from '../../readTracker.js';
+
+async function fetchModifiedTime(documentId) {
+    try {
+        const drive = await getDriveClient();
+        const res = await drive.files.get({
+            fileId: documentId,
+            fields: 'modifiedTime',
+            supportsAllDrives: true,
+        });
+        return res.data.modifiedTime || null;
+    } catch {
+        return null;
+    }
+}
+
 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.",
+        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.",
         parameters: DocumentIdParameter.extend({
             format: z
                 .enum(['text', 'json', 'markdown'])
@@ -23,6 +39,11 @@ export function register(server) {
                 .string()
                 .optional()
                 .describe('The ID of the specific tab to read. If not specified, reads the first tab (or legacy document.body for documents without tabs).'),
+            diffFromLastRead: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true and this document has already been read in this session (with format=markdown), returns a unified diff from the previous read to the current document instead of the full content. Ignored on first read or when format is not markdown.'),
         }),
         execute: async (args, { log }) => {
             const docs = await getDocsClient();
@@ -39,7 +60,7 @@ export function register(server) {
                     fields: needsTabsContent ? '*' : fields, // Get full document if using tabs
                 });
                 log.info(`Fetched doc: ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
-                trackRead(args.documentId);
+                const modifiedTime = await fetchModifiedTime(args.documentId);
                 // If tabId is specified, find the specific tab
                 let contentSource;
                 if (args.tabId) {
@@ -58,6 +79,10 @@ export function register(server) {
                     contentSource = res.data;
                 }
                 if (args.format === 'json') {
+                    if (args.diffFromLastRead) {
+                        log.info('diffFromLastRead ignored: only supported for format=markdown');
+                    }
+                    trackRead(args.documentId, modifiedTime);
                     const jsonContent = JSON.stringify(contentSource, null, 2);
                     // Apply length limit to JSON if specified
                     if (args.maxLength && jsonContent.length > args.maxLength) {
@@ -70,6 +95,23 @@ export function register(server) {
                     const markdownContent = docsJsonToMarkdown(contentSource);
                     const totalLength = markdownContent.length;
                     log.info(`Generated markdown: ${totalLength} characters`);
+                    if (args.diffFromLastRead) {
+                        const previous = getLastReadContent(args.documentId);
+                        if (previous !== null) {
+                            const patch = createPatch(
+                                args.documentId,
+                                previous,
+                                markdownContent,
+                                'last read',
+                                'current',
+                                { context: 3 }
+                            );
+                            trackRead(args.documentId, modifiedTime, markdownContent);
+                            return patch;
+                        }
+                        log.info('diffFromLastRead requested but no prior snapshot exists; returning full content');
+                    }
+                    trackRead(args.documentId, modifiedTime, markdownContent);
                     // Apply length limit to markdown if specified
                     if (args.maxLength && totalLength > args.maxLength) {
                         const truncatedContent = markdownContent.substring(0, args.maxLength);
@@ -78,6 +120,9 @@ export function register(server) {
                     return markdownContent;
                 }
                 // Default: Text format - extract all text content
+                if (args.diffFromLastRead) {
+                    log.info('diffFromLastRead ignored: only supported for format=markdown');
+                }
                 let textContent = '';
                 let elementCount = 0;
                 // Process all content elements from contentSource
@@ -106,6 +151,7 @@ export function register(server) {
                         });
                     }
                 });
+                trackRead(args.documentId, modifiedTime);
                 if (!textContent.trim())
                     return 'Document found, but appears empty.';
                 const totalLength = textContent.length;

package/dist/tools/drive/addPermission.js

@@ -0,0 +1,88 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'addPermission',
+        description: 'Shares a Drive file or folder by adding a new sharing permission. Supports sharing with a user, group, entire domain, or anyone with the link. Use listPermissions to see existing shares, updatePermission to change a role, or removePermission to revoke access.',
+        parameters: z.object({
+            fileId: z.string().describe('The ID of the file or folder to share.'),
+            type: z
+                .enum(['user', 'group', 'domain', 'anyone'])
+                .describe("Grantee type. 'user' and 'group' require emailAddress; 'domain' requires domain; 'anyone' is link sharing."),
+            role: z
+                .enum(['reader', 'commenter', 'writer', 'fileOrganizer', 'organizer', 'owner'])
+                .describe('Access level granted. Use owner only with transferOwnership=true.'),
+            emailAddress: z
+                .string()
+                .optional()
+                .describe("Email address of the user or group (required when type is 'user' or 'group')."),
+            domain: z
+                .string()
+                .optional()
+                .describe("Domain to share with (required when type is 'domain')."),
+            sendNotificationEmail: z
+                .boolean()
+                .optional()
+                .describe('Whether Google should send a notification email (default: true for user/group, false for domain/anyone).'),
+            emailMessage: z
+                .string()
+                .optional()
+                .describe('Custom message to include in the notification email (only applies when sendNotificationEmail is true).'),
+            transferOwnership: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Set to true when transferring ownership (role must be 'owner')."),
+            allowFileDiscovery: z
+                .boolean()
+                .optional()
+                .describe("For type 'domain' or 'anyone': whether the file can be discovered via search. Defaults to false (link-only)."),
+        }),
+        execute: async (args, { log }) => {
+            if ((args.type === 'user' || args.type === 'group') && !args.emailAddress) {
+                throw new UserError(`emailAddress is required when type is '${args.type}'.`);
+            }
+            if (args.type === 'domain' && !args.domain) {
+                throw new UserError("domain is required when type is 'domain'.");
+            }
+            if (args.role === 'owner' && !args.transferOwnership) {
+                throw new UserError("Role 'owner' requires transferOwnership=true.");
+            }
+            const drive = await getDriveClient();
+            log.info(`Adding permission to ${args.fileId}: type=${args.type}, role=${args.role}`);
+            const requestBody = {
+                type: args.type,
+                role: args.role,
+            };
+            if (args.emailAddress) requestBody.emailAddress = args.emailAddress;
+            if (args.domain) requestBody.domain = args.domain;
+            if (args.allowFileDiscovery !== undefined) {
+                requestBody.allowFileDiscovery = args.allowFileDiscovery;
+            }
+            const defaultNotify = args.type === 'user' || args.type === 'group';
+            const sendNotify = args.sendNotificationEmail ?? defaultNotify;
+            try {
+                const response = await drive.permissions.create({
+                    fileId: args.fileId,
+                    requestBody,
+                    sendNotificationEmail: sendNotify,
+                    emailMessage: sendNotify ? args.emailMessage : undefined,
+                    transferOwnership: args.transferOwnership,
+                    supportsAllDrives: true,
+                    fields: 'id,type,role,emailAddress,domain,displayName,allowFileDiscovery,pendingOwner',
+                });
+                return JSON.stringify(response.data, null, 2);
+            }
+            catch (error) {
+                log.error(`Error adding permission: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`File not found (ID: ${args.fileId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. You need writer+ access (or be the owner) to share this file.');
+                const apiMsg = error.response?.data?.error?.message || error.message || 'Unknown error';
+                throw new UserError(`Failed to add permission: ${apiMsg}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/index.js

@@ -15,6 +15,10 @@ import { register as listSharedWithMe } from './listSharedWithMe.js';
 import { register as downloadFile } from './downloadFile.js';
 import { register as getFilePath } from './getFilePath.js';
 import { register as uploadFile } from './uploadFile.js';
+import { register as listPermissions } from './listPermissions.js';
+import { register as addPermission } from './addPermission.js';
+import { register as removePermission } from './removePermission.js';
+import { register as updatePermission } from './updatePermission.js';
 export function registerDriveTools(server) {
     listDriveFiles(server);
     searchGoogleDocs(server);
@@ -33,4 +37,8 @@ export function registerDriveTools(server) {
     downloadFile(server);
     getFilePath(server);
     uploadFile(server);
+    listPermissions(server);
+    addPermission(server);
+    removePermission(server);
+    updatePermission(server);
 }

package/dist/tools/drive/listPermissions.js

@@ -0,0 +1,43 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'listPermissions',
+        description: 'Lists all sharing permissions on a Drive file or folder. Shows who the file is shared with (users, groups, domains, anyone) along with their roles (reader, commenter, writer, owner, etc.). Use addPermission/updatePermission/removePermission to change sharing.',
+        parameters: z.object({
+            fileId: z.string().describe('The ID of the file or folder whose permissions to list.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Listing permissions for file: ${args.fileId}`);
+            try {
+                const response = await drive.permissions.list({
+                    fileId: args.fileId,
+                    fields: 'permissions(id,type,role,emailAddress,domain,displayName,allowFileDiscovery,deleted,pendingOwner)',
+                    supportsAllDrives: true,
+                });
+                const permissions = (response.data.permissions || []).map((p) => ({
+                    id: p.id,
+                    type: p.type,
+                    role: p.role,
+                    emailAddress: p.emailAddress || null,
+                    domain: p.domain || null,
+                    displayName: p.displayName || null,
+                    allowFileDiscovery: p.allowFileDiscovery ?? null,
+                    deleted: p.deleted ?? false,
+                    pendingOwner: p.pendingOwner ?? false,
+                }));
+                return JSON.stringify({ fileId: args.fileId, permissions }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing permissions: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`File not found (ID: ${args.fileId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. You need access to the file to list its permissions.');
+                throw new UserError(`Failed to list permissions: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/removePermission.js

@@ -0,0 +1,40 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'removePermission',
+        description: 'Revokes a specific sharing permission from a Drive file or folder. Use listPermissions first to get the permissionId you want to remove.',
+        parameters: z.object({
+            fileId: z.string().describe('The ID of the file or folder.'),
+            permissionId: z
+                .string()
+                .describe('The ID of the permission to remove (from listPermissions).'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Removing permission ${args.permissionId} from file ${args.fileId}`);
+            try {
+                await drive.permissions.delete({
+                    fileId: args.fileId,
+                    permissionId: args.permissionId,
+                    supportsAllDrives: true,
+                });
+                return JSON.stringify({
+                    fileId: args.fileId,
+                    permissionId: args.permissionId,
+                    removed: true,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error removing permission: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Permission or file not found (fileId: ${args.fileId}, permissionId: ${args.permissionId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. You need writer+ access (or be the owner) to modify sharing.');
+                const apiMsg = error.response?.data?.error?.message || error.message || 'Unknown error';
+                throw new UserError(`Failed to remove permission: ${apiMsg}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/updatePermission.js

@@ -0,0 +1,50 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'updatePermission',
+        description: 'Changes the role (access level) of an existing sharing permission. Use listPermissions first to get the permissionId.',
+        parameters: z.object({
+            fileId: z.string().describe('The ID of the file or folder.'),
+            permissionId: z
+                .string()
+                .describe('The ID of the permission to update (from listPermissions).'),
+            role: z
+                .enum(['reader', 'commenter', 'writer', 'fileOrganizer', 'organizer', 'owner'])
+                .describe('New access level. Use owner only with transferOwnership=true.'),
+            transferOwnership: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Set to true when transferring ownership (role must be 'owner')."),
+        }),
+        execute: async (args, { log }) => {
+            if (args.role === 'owner' && !args.transferOwnership) {
+                throw new UserError("Role 'owner' requires transferOwnership=true.");
+            }
+            const drive = await getDriveClient();
+            log.info(`Updating permission ${args.permissionId} on ${args.fileId} to role=${args.role}`);
+            try {
+                const response = await drive.permissions.update({
+                    fileId: args.fileId,
+                    permissionId: args.permissionId,
+                    requestBody: { role: args.role },
+                    transferOwnership: args.transferOwnership,
+                    supportsAllDrives: true,
+                    fields: 'id,type,role,emailAddress,domain,displayName,allowFileDiscovery,pendingOwner',
+                });
+                return JSON.stringify(response.data, null, 2);
+            }
+            catch (error) {
+                log.error(`Error updating permission: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Permission or file not found (fileId: ${args.fileId}, permissionId: ${args.permissionId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. You need writer+ access (or be the owner) to modify sharing.');
+                const apiMsg = error.response?.data?.error?.message || error.message || 'Unknown error';
+                throw new UserError(`Failed to update permission: ${apiMsg}`);
+            }
+        },
+    });
+}

package/dist/tools/index.js

@@ -178,6 +178,12 @@ const CATEGORIES = {
             registerSlidesTools(server);
         },
     },
+    tasks: {
+        async loader(server) {
+            const { registerTasksTools } = await import('./tasks/index.js');
+            registerTasksTools(server);
+        },
+    },
 };
 
 // ---------------------------------------------------------------------------

package/dist/tools/tasks/completeTask.js

@@ -0,0 +1,43 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getTasksClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'completeTask',
+        description: 'Marks a task as completed.',
+        parameters: z.object({
+            taskListId: z.string().describe('ID of the task list containing the task'),
+            taskId: z.string().describe('ID of the task to complete'),
+        }),
+        execute: async (args, { log }) => {
+            const tasks = await getTasksClient();
+            log.info(`Completing task ${args.taskId} in list: ${args.taskListId}`);
+
+            try {
+                const response = await tasks.tasks.patch({
+                    tasklist: args.taskListId,
+                    task: args.taskId,
+                    requestBody: { status: 'completed', completed: new Date().toISOString() },
+                });
+                const t = response.data;
+                return JSON.stringify({
+                    id: t.id,
+                    taskListId: args.taskListId,
+                    title: t.title || '',
+                    notes: t.notes || null,
+                    status: t.status,
+                    due: t.due || null,
+                    completed: t.completed || null,
+                }, null, 2);
+            } catch (error) {
+                log.error(`Error completing task: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Task not found (taskId: ${args.taskId}, listId: ${args.taskListId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have access to this task.');
+                throw new UserError(`Failed to complete task: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/tasks/createTask.js

@@ -0,0 +1,53 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getTasksClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'createTask',
+        description: 'Creates a new task in a Google Tasks task list.',
+        parameters: z.object({
+            taskListId: z.string().describe('ID of the task list to add the task to'),
+            title: z.string().describe('Title of the task'),
+            notes: z.string().optional().describe('Optional notes or description for the task'),
+            due: z
+                .string()
+                .optional()
+                .describe('Optional due date in RFC 3339 or plain date format (e.g. "2025-04-30")'),
+        }),
+        execute: async (args, { log }) => {
+            const tasks = await getTasksClient();
+            log.info(`Creating task "${args.title}" in list: ${args.taskListId}`);
+
+            try {
+                const body = { title: args.title };
+                if (args.notes) body.notes = args.notes;
+                if (args.due) body.due = normalizeDate(args.due);
+
+                const response = await tasks.tasks.insert({ tasklist: args.taskListId, requestBody: body });
+                const t = response.data;
+                return JSON.stringify({
+                    id: t.id,
+                    taskListId: args.taskListId,
+                    title: t.title || '',
+                    notes: t.notes || null,
+                    status: t.status,
+                    due: t.due || null,
+                    completed: t.completed || null,
+                }, null, 2);
+            } catch (error) {
+                log.error(`Error creating task: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Task list not found (ID: ${args.taskListId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have access to this task list.');
+                throw new UserError(`Failed to create task: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}
+
+function normalizeDate(value) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) return `${value}T00:00:00.000Z`;
+    return value;
+}

package/dist/tools/tasks/createTaskList.js

@@ -0,0 +1,25 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getTasksClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'createTaskList',
+        description: 'Creates a new Google Tasks task list with the given title.',
+        parameters: z.object({
+            title: z.string().describe('Title for the new task list'),
+        }),
+        execute: async (args, { log }) => {
+            const tasks = await getTasksClient();
+            log.info(`Creating task list: ${args.title}`);
+
+            try {
+                const response = await tasks.tasklists.insert({ requestBody: { title: args.title } });
+                return JSON.stringify({ id: response.data.id, title: response.data.title }, null, 2);
+            } catch (error) {
+                log.error(`Error creating task list: ${error.message || error}`);
+                throw new UserError(`Failed to create task list: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/tasks/deleteTask.js

@@ -0,0 +1,30 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getTasksClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'deleteTask',
+        description: 'Permanently deletes a task.',
+        parameters: z.object({
+            taskListId: z.string().describe('ID of the task list containing the task'),
+            taskId: z.string().describe('ID of the task to delete'),
+        }),
+        execute: async (args, { log }) => {
+            const tasks = await getTasksClient();
+            log.info(`Deleting task ${args.taskId} from list: ${args.taskListId}`);
+
+            try {
+                await tasks.tasks.delete({ tasklist: args.taskListId, task: args.taskId });
+                return JSON.stringify({ deleted: true, taskId: args.taskId, taskListId: args.taskListId }, null, 2);
+            } catch (error) {
+                log.error(`Error deleting task: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Task not found (taskId: ${args.taskId}, listId: ${args.taskListId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have access to this task.');
+                throw new UserError(`Failed to delete task: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/tasks/deleteTaskList.js

@@ -0,0 +1,29 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getTasksClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'deleteTaskList',
+        description: 'Permanently deletes a task list and all tasks within it.',
+        parameters: z.object({
+            taskListId: z.string().describe('ID of the task list to delete'),
+        }),
+        execute: async (args, { log }) => {
+            const tasks = await getTasksClient();
+            log.info(`Deleting task list: ${args.taskListId}`);
+
+            try {
+                await tasks.tasklists.delete({ tasklist: args.taskListId });
+                return JSON.stringify({ deleted: true, taskListId: args.taskListId }, null, 2);
+            } catch (error) {
+                log.error(`Error deleting task list: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Task list not found (ID: ${args.taskListId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. You can only delete task lists you own.');
+                throw new UserError(`Failed to delete task list: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/tasks/index.js

@@ -0,0 +1,19 @@
+import { register as listTaskLists } from './listTaskLists.js';
+import { register as createTaskList } from './createTaskList.js';
+import { register as deleteTaskList } from './deleteTaskList.js';
+import { register as listTasks } from './listTasks.js';
+import { register as createTask } from './createTask.js';
+import { register as updateTask } from './updateTask.js';
+import { register as completeTask } from './completeTask.js';
+import { register as deleteTask } from './deleteTask.js';
+
+export function registerTasksTools(server) {
+    listTaskLists(server);
+    createTaskList(server);
+    deleteTaskList(server);
+    listTasks(server);
+    createTask(server);
+    updateTask(server);
+    completeTask(server);
+    deleteTask(server);
+}

package/dist/tools/tasks/listTaskLists.js

@@ -0,0 +1,26 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getTasksClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'listTaskLists',
+        description: 'Lists all Google Task lists for the authenticated user. Returns the id and title of each list.',
+        parameters: z.object({}),
+        execute: async (_args, { log }) => {
+            const tasks = await getTasksClient();
+            log.info('Listing task lists');
+
+            try {
+                const response = await tasks.tasklists.list();
+                const lists = response.data.items || [];
+                return JSON.stringify(lists.map((l) => ({ id: l.id, title: l.title })), null, 2);
+            } catch (error) {
+                log.error(`Error listing task lists: ${error.message || error}`);
+                if (error.code === 401)
+                    throw new UserError('Authentication failed. Try logging out and re-authenticating.');
+                throw new UserError(`Failed to list task lists: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/tasks/listTasks.js

@@ -0,0 +1,69 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getTasksClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'listTasks',
+        description:
+            'Lists tasks in a Google Tasks task list. Optionally filter by completion status or due date range.',
+        parameters: z.object({
+            taskListId: z.string().describe('ID of the task list to read from'),
+            showCompleted: z
+                .boolean()
+                .optional()
+                .describe('Whether to include completed tasks (default: true)'),
+            dueMin: z
+                .string()
+                .optional()
+                .describe('Lower bound for due date filter, RFC 3339 or plain date (e.g. "2025-04-01")'),
+            dueMax: z
+                .string()
+                .optional()
+                .describe('Upper bound for due date filter, RFC 3339 or plain date (e.g. "2025-04-30")'),
+        }),
+        execute: async (args, { log }) => {
+            const tasks = await getTasksClient();
+            const showCompleted = args.showCompleted ?? true;
+            log.info(`Listing tasks in list: ${args.taskListId}`);
+
+            try {
+                const params = {
+                    tasklist: args.taskListId,
+                    showCompleted,
+                    showHidden: showCompleted,
+                };
+                if (args.dueMin) params.dueMin = normalizeDate(args.dueMin);
+                if (args.dueMax) params.dueMax = normalizeDate(args.dueMax);
+
+                const response = await tasks.tasks.list(params);
+                const items = response.data.items || [];
+                return JSON.stringify(items.map((t) => formatTask(t, args.taskListId)), null, 2);
+            } catch (error) {
+                log.error(`Error listing tasks: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Task list not found (ID: ${args.taskListId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have access to this task list.');
+                throw new UserError(`Failed to list tasks: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}
+
+function formatTask(t, taskListId) {
+    return {
+        id: t.id,
+        taskListId,
+        title: t.title || '',
+        notes: t.notes || null,
+        status: t.status,
+        due: t.due || null,
+        completed: t.completed || null,
+    };
+}
+
+function normalizeDate(value) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) return `${value}T00:00:00.000Z`;
+    return value;
+}

package/dist/tools/tasks/updateTask.js

@@ -0,0 +1,68 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getTasksClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'updateTask',
+        description:
+            'Updates fields on an existing task. Only provided fields are changed; omitted fields are left as-is.',
+        parameters: z.object({
+            taskListId: z.string().describe('ID of the task list containing the task'),
+            taskId: z.string().describe('ID of the task to update'),
+            title: z.string().optional().describe('New title for the task'),
+            notes: z.string().optional().describe('New notes for the task'),
+            due: z
+                .string()
+                .optional()
+                .describe('New due date in RFC 3339 or plain date format (e.g. "2025-04-30")'),
+            status: z
+                .enum(['needsAction', 'completed'])
+                .optional()
+                .describe('New status for the task'),
+        }),
+        execute: async (args, { log }) => {
+            const tasks = await getTasksClient();
+            log.info(`Updating task ${args.taskId} in list: ${args.taskListId}`);
+
+            try {
+                const body = {};
+                if (args.title !== undefined) body.title = args.title;
+                if (args.notes !== undefined) body.notes = args.notes;
+                if (args.due !== undefined) body.due = normalizeDate(args.due);
+                if (args.status !== undefined) {
+                    body.status = args.status;
+                    if (args.status === 'completed') body.completed = new Date().toISOString();
+                }
+
+                const response = await tasks.tasks.patch({
+                    tasklist: args.taskListId,
+                    task: args.taskId,
+                    requestBody: body,
+                });
+                const t = response.data;
+                return JSON.stringify({
+                    id: t.id,
+                    taskListId: args.taskListId,
+                    title: t.title || '',
+                    notes: t.notes || null,
+                    status: t.status,
+                    due: t.due || null,
+                    completed: t.completed || null,
+                }, null, 2);
+            } catch (error) {
+                log.error(`Error updating task: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Task not found (taskId: ${args.taskId}, listId: ${args.taskListId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have access to this task.');
+                throw new UserError(`Failed to update task: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}
+
+function normalizeDate(value) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value)) return `${value}T00:00:00.000Z`;
+    return value;
+}

package/dist/tools/utils/appendMarkdownToGoogleDoc.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter, MarkdownConversionError } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
-import { insertMarkdown, formatInsertResult } from '../../markdown-transformer/index.js';
+import { insertMarkdown, formatInsertResult, docsJsonToMarkdown } from '../../markdown-transformer/index.js';
 import { guardMutation, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
@@ -32,8 +32,13 @@ export function register(server) {
                 .describe('If true, the first H1 heading (# ...) in the markdown is styled as a Google Docs TITLE instead of Heading 1. Useful when the markdown represents a full document whose first line is the document title.'),
         }),
         execute: async (args, { log }) => {
-            await guardMutation(args.documentId);
             const docs = await getDocsClient();
+            await guardMutation(args.documentId, {
+                contentFetcher: async () => {
+                    const current = await docs.documents.get({ documentId: args.documentId });
+                    return docsJsonToMarkdown(current.data);
+                },
+            });
             // Resolve markdown content from filePath or inline parameter
             let markdown = args.markdown;
             if (args.filePath) {

package/dist/tools/utils/replaceDocumentWithMarkdown.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { getDocsClient } from '../../clients.js';
 import { DocumentIdParameter, MarkdownConversionError } from '../../types.js';
 import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
-import { insertMarkdown, formatInsertResult } from '../../markdown-transformer/index.js';
+import { insertMarkdown, formatInsertResult, docsJsonToMarkdown } from '../../markdown-transformer/index.js';
 import { guardMutation, trackMutation } from '../../readTracker.js';
 export function register(server) {
     server.addTool({
@@ -33,8 +33,13 @@ export function register(server) {
                 .describe('If true (default), the first H1 heading (# ...) in the markdown is styled as a Google Docs TITLE instead of Heading 1. Useful when the markdown represents a full document whose first line is the document title. Set to false if the first H1 should remain a Heading 1.'),
         }),
         execute: async (args, { log }) => {
-            await guardMutation(args.documentId);
             const docs = await getDocsClient();
+            await guardMutation(args.documentId, {
+                contentFetcher: async () => {
+                    const current = await docs.documents.get({ documentId: args.documentId });
+                    return docsJsonToMarkdown(current.data);
+                },
+            });
             // Resolve markdown content from filePath or inline parameter
             let markdown = args.markdown;
             if (args.filePath) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "google-tools-mcp",
-  "version": "1.2.4",
+  "version": "1.2.6",
   "description": "The easiest MCP server for Google Workspace — Drive, Docs, Sheets, Gmail, Calendar, and Forms. 153 tools with one-click browser auth. Read Word docs, PDFs, and spreadsheets straight from Drive.",
   "type": "module",
   "bin": {
@@ -64,6 +64,7 @@
   "dependencies": {
     "@clack/prompts": "^1.2.0",
     "chalk": "^5.6.2",
+    "diff": "^7.0.0",
     "fastmcp": "^3.24.0",
     "google-auth-library": "^10.5.0",
     "googleapis": "^171.4.0",