@triffon/google-docs-mcp 1.11.3-triffon

package/dist/tools/gmail/trashMessage.js

@@ -0,0 +1,37 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getGmailClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'trashMessage',
+        description: 'Moves a Gmail message to Trash. This is the same as clicking Delete in the Gmail UI — reversible from the Trash folder for 30 days. Not a permanent delete.',
+        parameters: z.strictObject({
+            messageId: z.string().describe('The Gmail message ID to move to Trash.'),
+        }),
+        execute: async (args, { log }) => {
+            const gmail = await getGmailClient();
+            log.info(`Trashing Gmail message ${args.messageId}`);
+            try {
+                const response = await gmail.users.messages.trash({
+                    userId: 'me',
+                    id: args.messageId,
+                });
+                return JSON.stringify({
+                    success: true,
+                    id: response.data.id,
+                    threadId: response.data.threadId,
+                    labelIds: response.data.labelIds ?? [],
+                    message: `Message ${args.messageId} moved to Trash. Recoverable from the Trash folder in the Gmail UI.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error trashing Gmail message: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Gmail message not found (ID: ${args.messageId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the gmail.modify scope was granted.');
+                throw new UserError(`Failed to trash message: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/gmail/triageInbox.js

@@ -0,0 +1,147 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getGmailClient } from '../../clients.js';
+import { findHeaderValue, extractMessageBody, extractDomain } from './helpers.js';
+// "reschedul" is intentionally truncated to catch both "reschedule" and "rescheduling".
+const MEETING_KEYWORD_PATTERN = /\b(meeting|call|invite|invitation|calendar|schedule|reschedul|zoom|google meet|teams)\b/i;
+const QUESTION_PATTERN = /\?/;
+const ACTION_PATTERN = /\b(please|could you|can you|let me know|need|review|approve|sign|deadline|by (mon|tue|wed|thu|fri|sat|sun|today|tomorrow|next week|eod|cob))\b/i;
+function extractTextBody(payload) {
+    const { text, html } = extractMessageBody(payload);
+    if (text)
+        return text;
+    // No text/plain part — strip HTML tags as a best-effort fallback so the
+    // heuristic regexes still have something to match against.
+    return html.replace(/<style[\s\S]*?<\/style>|<script[\s\S]*?<\/script>|<[^>]+>/g, ' ');
+}
+function truncate(text, max) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    if (collapsed.length <= max)
+        return collapsed;
+    return collapsed.slice(0, max) + '…';
+}
+export function register(server) {
+    server.addTool({
+        name: 'triageInbox',
+        description: "Composite tool: fetches the user's most recent unread Gmail messages with full content and heuristic categorization in a single call. Returns headers, body excerpts, labels, plus per-message signals (newsletter, meeting reference, contains question, action requested) AND aggregate stats (total unread, top senders, breakdown by category). Designed for AI inbox triage workflows — use the returned data to decide which messages need a reply, can be archived, or warrant a draft response. Pairs naturally with createDraft, modifyMessageLabels, and trashMessage.",
+        parameters: z.strictObject({
+            maxResults: z
+                .number()
+                .int()
+                .min(1)
+                .max(50)
+                .optional()
+                .default(20)
+                .describe('How many unread messages to triage in one pass (1-50). Defaults to 20.'),
+            additionalQuery: z
+                .string()
+                .optional()
+                .describe('Optional Gmail query appended to "is:unread", e.g. "newer_than:2d" or "-from:notifications@".'),
+            bodyExcerptLength: z
+                .number()
+                .int()
+                .min(0)
+                .max(2000)
+                .optional()
+                .default(400)
+                .describe('Max characters of body text to include per message (0 to skip bodies).'),
+        }),
+        execute: async (args, { log }) => {
+            const gmail = await getGmailClient();
+            const query = ['is:unread', args.additionalQuery].filter(Boolean).join(' ');
+            log.info(`Triaging inbox (max=${args.maxResults}, q="${query}")`);
+            try {
+                const listResponse = await gmail.users.messages.list({
+                    userId: 'me',
+                    maxResults: args.maxResults,
+                    q: query,
+                });
+                const totalUnread = listResponse.data.resultSizeEstimate ?? 0;
+                const messageRefs = listResponse.data.messages ?? [];
+                if (messageRefs.length === 0) {
+                    return JSON.stringify({
+                        summary: {
+                            totalUnread,
+                            fetched: 0,
+                            topSenders: [],
+                            newsletterCount: 0,
+                            meetingReferenceCount: 0,
+                            questionCount: 0,
+                            actionRequestedCount: 0,
+                        },
+                        messages: [],
+                    }, null, 2);
+                }
+                // allSettled so a single failed message fetch doesn't kill the whole
+                // triage — partial results are still actionable for the agent.
+                const settled = await Promise.allSettled(messageRefs.map((ref) => gmail.users.messages.get({
+                    userId: 'me',
+                    id: ref.id,
+                    format: 'full',
+                })));
+                const failedFetches = settled.filter((r) => r.status === 'rejected').length;
+                const detailed = [];
+                for (const r of settled) {
+                    if (r.status === 'fulfilled')
+                        detailed.push(r.value.data);
+                }
+                const messages = detailed.map((msg) => {
+                    const headers = msg.payload?.headers;
+                    const from = findHeaderValue(headers, 'From');
+                    const subject = findHeaderValue(headers, 'Subject') ?? '(no subject)';
+                    // Standard newsletter headers per RFC 2369 (List-Unsubscribe) and RFC 2919 (List-Id).
+                    const hasUnsubscribe = findHeaderValue(headers, 'List-Unsubscribe') !== null ||
+                        findHeaderValue(headers, 'List-Id') !== null;
+                    const text = args.bodyExcerptLength > 0 ? extractTextBody(msg.payload) : '';
+                    const bodyExcerpt = args.bodyExcerptLength > 0 ? truncate(text, args.bodyExcerptLength) : '';
+                    const searchSurface = `${subject} ${text}`;
+                    return {
+                        id: msg.id,
+                        threadId: msg.threadId,
+                        from,
+                        domain: extractDomain(from),
+                        to: findHeaderValue(headers, 'To'),
+                        subject,
+                        date: findHeaderValue(headers, 'Date'),
+                        snippet: msg.snippet ?? '',
+                        bodyExcerpt,
+                        labels: msg.labelIds ?? [],
+                        isNewsletter: hasUnsubscribe,
+                        containsMeetingReference: MEETING_KEYWORD_PATTERN.test(searchSurface),
+                        containsQuestion: QUESTION_PATTERN.test(searchSurface),
+                        actionRequested: ACTION_PATTERN.test(searchSurface),
+                    };
+                });
+                const senderCounts = new Map();
+                for (const m of messages) {
+                    if (!m.from)
+                        continue;
+                    senderCounts.set(m.from, (senderCounts.get(m.from) ?? 0) + 1);
+                }
+                const topSenders = [...senderCounts.entries()]
+                    .sort((a, b) => b[1] - a[1])
+                    .slice(0, 5)
+                    .map(([from, count]) => ({ from, count }));
+                const summary = {
+                    totalUnread,
+                    fetched: messages.length,
+                    failedFetches,
+                    topSenders,
+                    newsletterCount: messages.filter((m) => m.isNewsletter).length,
+                    meetingReferenceCount: messages.filter((m) => m.containsMeetingReference).length,
+                    questionCount: messages.filter((m) => m.containsQuestion).length,
+                    actionRequestedCount: messages.filter((m) => m.actionRequested).length,
+                };
+                return JSON.stringify({ summary, messages }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error triaging inbox: ${error.message || error}`);
+                if (error.code === 401)
+                    throw new UserError('Gmail authorization failed. Re-authorize to grant the gmail.modify scope.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the gmail.modify scope was granted.');
+                throw new UserError(`Failed to triage inbox: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/gmail/updateDraft.js

@@ -0,0 +1,60 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getGmailClient } from '../../clients.js';
+import { prepareMimeRequest } from './helpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'updateDraft',
+        description: 'Replaces the contents of an existing Gmail draft. The new contents fully overwrite the old draft (this is a full replace, not a patch). Use this when iterating on an AI-composed draft before sending.',
+        parameters: z.strictObject({
+            draftId: z.string().describe('The Gmail draft ID to update.'),
+            to: z
+                .union([z.string(), z.array(z.string()).min(1)])
+                .describe('Recipient email address, or an array of recipient email addresses.'),
+            subject: z.string().describe('Email subject line.'),
+            body: z.string().describe('New plain-text body of the draft.'),
+            cc: z.array(z.string()).optional().describe('Optional list of Cc recipients.'),
+            bcc: z.array(z.string()).optional().describe('Optional list of Bcc recipients.'),
+            replyToMessageId: z
+                .string()
+                .optional()
+                .describe('Optional Gmail message ID to thread the draft with.'),
+        }),
+        execute: async (args, { log }) => {
+            const gmail = await getGmailClient();
+            log.info(`Updating Gmail draft ${args.draftId}`);
+            try {
+                const { raw, threadId, toList } = await prepareMimeRequest(gmail, args);
+                const response = await gmail.users.drafts.update({
+                    userId: 'me',
+                    id: args.draftId,
+                    requestBody: {
+                        message: {
+                            raw,
+                            ...(threadId ? { threadId } : {}),
+                        },
+                    },
+                });
+                return JSON.stringify({
+                    success: true,
+                    draftId: response.data.id,
+                    messageId: response.data.message?.id,
+                    threadId: response.data.message?.threadId,
+                    to: toList,
+                    subject: args.subject,
+                    message: `Draft ${args.draftId} updated.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error updating draft: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Draft not found (ID: ${args.draftId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the gmail.modify scope was granted.');
+                if (error.code === 400)
+                    throw new UserError(`Gmail rejected the draft update: ${error.message || 'Bad request'}`);
+                throw new UserError(`Failed to update draft: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/index.js

@@ -0,0 +1,64 @@
+import { registerDocsTools } from './docs/index.js';
+import { registerDriveTools } from './drive/index.js';
+import { registerSheetsTools } from './sheets/index.js';
+import { registerUtilsTools } from './utils/index.js';
+import { registerGmailTools } from './gmail/index.js';
+import { registerCalendarTools } from './calendar/index.js';
+import { registerScriptTools } from './script/index.js';
+export const TOOL_GROUPS = [
+    'docs',
+    'drive',
+    'sheets',
+    'utils',
+    'gmail',
+    'calendar',
+    'script',
+];
+const TOOL_GROUP_SET = new Set(TOOL_GROUPS);
+export function parseEnabledToolGroups(raw = process.env.MCP_TOOL_GROUPS) {
+    if (!raw?.trim())
+        return [...TOOL_GROUPS];
+    const requested = raw
+        .split(',')
+        .map((group) => group.trim().toLowerCase())
+        .filter(Boolean);
+    if (requested.length === 0 || requested.includes('all')) {
+        return [...TOOL_GROUPS];
+    }
+    const unknown = requested.filter((group) => !TOOL_GROUP_SET.has(group));
+    if (unknown.length > 0) {
+        throw new Error(`Unknown MCP_TOOL_GROUPS value(s): ${unknown.join(', ')}. Valid groups: ${TOOL_GROUPS.join(', ')}`);
+    }
+    const selected = new Set(requested);
+    return TOOL_GROUPS.filter((group) => selected.has(group));
+}
+/**
+ * Registers all tools with the FastMCP server.
+ */
+export function registerAllTools(server, enabledGroups = parseEnabledToolGroups()) {
+    for (const group of enabledGroups) {
+        switch (group) {
+            case 'docs':
+                registerDocsTools(server);
+                break;
+            case 'drive':
+                registerDriveTools(server);
+                break;
+            case 'sheets':
+                registerSheetsTools(server);
+                break;
+            case 'utils':
+                registerUtilsTools(server);
+                break;
+            case 'gmail':
+                registerGmailTools(server);
+                break;
+            case 'calendar':
+                registerCalendarTools(server);
+                break;
+            case 'script':
+                registerScriptTools(server);
+                break;
+        }
+    }
+}

package/dist/tools/script/appsScriptShared.js

@@ -0,0 +1,96 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+/** File types supported by an Apps Script project. */
+export const AppsScriptFileTypeSchema = z.enum(['SERVER_JS', 'HTML', 'JSON']);
+export const AppsScriptFileSchema = z.strictObject({
+    name: z
+        .string()
+        .min(1)
+        .describe('File name without extension, e.g. "Code" or "appsscript". The manifest file must be named "appsscript".'),
+    type: AppsScriptFileTypeSchema.optional().describe('File type. Inferred from the name when omitted: "appsscript" becomes JSON, names ending in .html become HTML, everything else becomes SERVER_JS.'),
+    source: z.string().describe('Full file content.'),
+});
+export const MANIFEST_FILE_NAME = 'appsscript';
+/** Minimal manifest used when a project has none and the caller did not supply one. */
+export const DEFAULT_MANIFEST_SOURCE = JSON.stringify({
+    timeZone: 'Etc/GMT',
+    dependencies: {},
+    exceptionLogging: 'STACKDRIVER',
+    runtimeVersion: 'V8',
+}, null, 2);
+/** Strips a trailing extension so callers may pass either "Code" or "Code.gs". */
+function stripExtension(name) {
+    return name.replace(/\.(gs|js|html|json)$/i, '');
+}
+/** Derives the Apps Script file type from a file name when the caller omitted it. */
+export function inferFileType(name) {
+    const lower = name.toLowerCase();
+    if (stripExtension(lower) === MANIFEST_FILE_NAME)
+        return 'JSON';
+    if (lower.endsWith('.html'))
+        return 'HTML';
+    return 'SERVER_JS';
+}
+/** Normalises caller input into the shape the Apps Script API expects. */
+export function toApiFiles(files) {
+    return files.map((file) => ({
+        name: stripExtension(file.name),
+        type: file.type ?? inferFileType(file.name),
+        source: file.source,
+    }));
+}
+/**
+ * Merges incoming files over the files already in the project.
+ * Files with the same name are replaced; every other existing file is kept.
+ */
+export function mergeFiles(existing, incoming) {
+    const byName = new Map();
+    for (const file of existing) {
+        if (file.name)
+            byName.set(file.name, file);
+    }
+    for (const file of incoming) {
+        if (file.name)
+            byName.set(file.name, file);
+    }
+    return [...byName.values()];
+}
+/**
+ * The API rejects an update whose payload has no manifest, so fall back to the
+ * project's current manifest and finally to a minimal default.
+ */
+export function ensureManifest(files, existing) {
+    if (files.some((file) => file.name === MANIFEST_FILE_NAME))
+        return files;
+    const currentManifest = existing.find((file) => file.name === MANIFEST_FILE_NAME);
+    return [
+        currentManifest ?? {
+            name: MANIFEST_FILE_NAME,
+            type: 'JSON',
+            source: DEFAULT_MANIFEST_SOURCE,
+        },
+        ...files,
+    ];
+}
+/** Turns raw Google API failures into messages that say what to do next. */
+export function toUserError(error, action) {
+    const message = error?.message ?? String(error);
+    const status = error?.code ?? error?.response?.status;
+    if (status === 403 && /Apps Script API/i.test(message)) {
+        return new UserError('The Apps Script API is turned off for this Google account. Enable it at https://script.google.com/home/usersettings and try again.');
+    }
+    if (status === 403) {
+        return new UserError(`Permission denied while ${action}. The account needs edit access to the project, and the OAuth token needs the script.projects scope - re-authorize if the token predates that scope.`);
+    }
+    if (status === 404) {
+        return new UserError(`Not found while ${action}. Check the script ID - it is the long ID in the /projects/<scriptId>/ part of the Apps Script editor URL, not the spreadsheet ID.`);
+    }
+    if (status === 400 && /parent/i.test(message)) {
+        return new UserError('Invalid parentId. It must be the file ID of an existing Doc, Sheet, Slides or Form that the account can edit.');
+    }
+    return new UserError(`Failed while ${action}: ${message || 'Unknown error'}`);
+}
+/** Editor URL for a script project. */
+export function scriptUrl(scriptId) {
+    return `https://script.google.com/d/${scriptId}/edit`;
+}

package/dist/tools/script/createAppsScriptProject.js

@@ -0,0 +1,74 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getScriptClient } from '../../clients.js';
+import { AppsScriptFileSchema, ensureManifest, scriptUrl, toApiFiles, toUserError, } from './appsScriptShared.js';
+export function register(server) {
+    server.addTool({
+        name: 'createAppsScriptProject',
+        description: 'Creates an Apps Script project, optionally bound to a Doc, Sheet, Slides or Form so its triggers and custom menus run inside that file. Optionally writes the initial files in the same call. Requires the Apps Script API to be enabled at https://script.google.com/home/usersettings.',
+        parameters: z.strictObject({
+            title: z.string().min(1).describe('Title of the new script project.'),
+            parentId: z
+                .string()
+                .optional()
+                .describe('File ID of the Doc, Sheet, Slides or Form to bind the project to (a container-bound script). Omit to create a standalone project in Drive.'),
+            files: z
+                .array(AppsScriptFileSchema)
+                .optional()
+                .describe('Initial files to write after the project is created. A manifest is added automatically when the list has none.'),
+        }),
+        execute: async (args, { log }) => {
+            const script = await getScriptClient();
+            log.info(`Creating Apps Script project "${args.title}"${args.parentId ? ` bound to ${args.parentId}` : ' (standalone)'}`);
+            let scriptId;
+            try {
+                const created = await script.projects.create({
+                    requestBody: {
+                        title: args.title,
+                        ...(args.parentId ? { parentId: args.parentId } : {}),
+                    },
+                });
+                if (!created.data.scriptId) {
+                    throw new UserError('Project was created but the API returned no scriptId.');
+                }
+                scriptId = created.data.scriptId;
+            }
+            catch (error) {
+                if (error instanceof UserError)
+                    throw error;
+                log.error(`Error creating Apps Script project: ${error.message || error}`);
+                throw toUserError(error, 'creating the Apps Script project');
+            }
+            let filesWritten;
+            if (args.files && args.files.length > 0) {
+                try {
+                    // A freshly created project already carries a default manifest; keep it
+                    // unless the caller supplied one of their own.
+                    const current = await script.projects.getContent({ scriptId });
+                    const existing = current.data.files ?? [];
+                    const payload = ensureManifest(toApiFiles(args.files), existing);
+                    await script.projects.updateContent({
+                        scriptId,
+                        requestBody: { files: payload },
+                    });
+                    filesWritten = payload.length;
+                }
+                catch (error) {
+                    log.warn(`Project created but writing files failed: ${error.message || error}`);
+                    return JSON.stringify({
+                        scriptId,
+                        url: scriptUrl(scriptId),
+                        filesWritten: 0,
+                        warning: `Project created, but writing the initial files failed: ${error.message || error}. Retry with updateAppsScriptContent.`,
+                    }, null, 2);
+                }
+            }
+            return JSON.stringify({
+                scriptId,
+                url: scriptUrl(scriptId),
+                bound: Boolean(args.parentId),
+                ...(filesWritten !== undefined ? { filesWritten } : {}),
+            }, null, 2);
+        },
+    });
+}

package/dist/tools/script/getAppsScriptContent.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { getScriptClient } from '../../clients.js';
+import { scriptUrl, toUserError } from './appsScriptShared.js';
+export function register(server) {
+    server.addTool({
+        name: 'getAppsScriptContent',
+        description: 'Reads the files of an Apps Script project. Use it before updateAppsScriptContent to see what is already there, or to review code that is currently deployed.',
+        parameters: z.strictObject({
+            scriptId: z
+                .string()
+                .min(1)
+                .describe('Script project ID - the long ID in the /projects/<scriptId>/ part of the Apps Script editor URL. This is not the spreadsheet ID.'),
+            versionNumber: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe('Read a specific saved version instead of the current draft.'),
+            includeSource: z
+                .boolean()
+                .default(true)
+                .describe('Set to false to list file names and types without their content.'),
+        }),
+        execute: async (args, { log }) => {
+            const script = await getScriptClient();
+            log.info(`Reading Apps Script project ${args.scriptId}`);
+            try {
+                const response = await script.projects.getContent({
+                    scriptId: args.scriptId,
+                    ...(args.versionNumber ? { versionNumber: args.versionNumber } : {}),
+                });
+                const files = (response.data.files ?? []).map((file) => ({
+                    name: file.name,
+                    type: file.type,
+                    ...(args.includeSource ? { source: file.source } : { lines: countLines(file.source) }),
+                }));
+                return JSON.stringify({
+                    scriptId: args.scriptId,
+                    url: scriptUrl(args.scriptId),
+                    ...(args.versionNumber ? { versionNumber: args.versionNumber } : {}),
+                    fileCount: files.length,
+                    files,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error reading Apps Script project: ${error.message || error}`);
+                throw toUserError(error, 'reading the Apps Script project');
+            }
+        },
+    });
+}
+function countLines(source) {
+    if (!source)
+        return 0;
+    return source.split('\n').length;
+}

package/dist/tools/script/index.js

@@ -0,0 +1,14 @@
+import { register as createAppsScriptProject } from './createAppsScriptProject.js';
+import { register as getAppsScriptContent } from './getAppsScriptContent.js';
+import { register as updateAppsScriptContent } from './updateAppsScriptContent.js';
+/**
+ * Registers Apps Script project tools.
+ *
+ * These require the Apps Script API to be enabled per account at
+ * https://script.google.com/home/usersettings and the script.projects OAuth scope.
+ */
+export function registerScriptTools(server) {
+    createAppsScriptProject(server);
+    getAppsScriptContent(server);
+    updateAppsScriptContent(server);
+}

package/dist/tools/script/updateAppsScriptContent.js

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+import { getScriptClient } from '../../clients.js';
+import { AppsScriptFileSchema, ensureManifest, mergeFiles, scriptUrl, toApiFiles, toUserError, } from './appsScriptShared.js';
+export function register(server) {
+    server.addTool({
+        name: 'updateAppsScriptContent',
+        description: 'Writes files into an existing Apps Script project. Default mode "merge" replaces same-named files and keeps the rest; mode "replace" makes the project contain exactly the files passed in. The manifest is preserved automatically.',
+        parameters: z.strictObject({
+            scriptId: z
+                .string()
+                .min(1)
+                .describe('Script project ID - the long ID in the /projects/<scriptId>/ part of the Apps Script editor URL.'),
+            files: z
+                .array(AppsScriptFileSchema)
+                .min(1)
+                .describe('Files to write. Each one replaces the file of the same name.'),
+            mode: z
+                .enum(['merge', 'replace'])
+                .default('merge')
+                .describe('merge: keep files that are not in this call (default, safe). replace: delete every file not listed here.'),
+        }),
+        execute: async (args, { log }) => {
+            const script = await getScriptClient();
+            log.info(`Updating Apps Script project ${args.scriptId} (${args.mode}, ${args.files.length} file(s))`);
+            try {
+                const current = await script.projects.getContent({ scriptId: args.scriptId });
+                const existing = current.data.files ?? [];
+                const incoming = toApiFiles(args.files);
+                const combined = args.mode === 'merge' ? mergeFiles(existing, incoming) : incoming;
+                const payload = ensureManifest(combined, existing);
+                const response = await script.projects.updateContent({
+                    scriptId: args.scriptId,
+                    requestBody: { files: payload },
+                });
+                const written = response.data.files ?? payload;
+                const removed = args.mode === 'replace'
+                    ? existing
+                        .map((file) => file.name)
+                        .filter((name) => name && !payload.some((file) => file.name === name))
+                    : [];
+                return JSON.stringify({
+                    scriptId: args.scriptId,
+                    url: scriptUrl(args.scriptId),
+                    mode: args.mode,
+                    filesInProject: written.length,
+                    updated: incoming.map((file) => file.name),
+                    ...(removed.length > 0 ? { removed } : {}),
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error updating Apps Script project: ${error.message || error}`);
+                throw toUserError(error, 'updating the Apps Script project');
+            }
+        },
+    });
+}