@triffon/google-docs-mcp 1.11.3-triffon

package/dist/remoteWrapper.js

@@ -0,0 +1,72 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { getAuthSession, requireAuth, UserError } from 'fastmcp';
+import { google } from 'googleapis';
+import { OAuth2Client } from 'google-auth-library';
+import { logger } from './logger.js';
+export const requestClients = new AsyncLocalStorage();
+const allowedDomains = (process.env.ALLOWED_DOMAINS || '').split(',').filter(Boolean);
+function checkDomain(idToken) {
+    if (allowedDomains.length === 0)
+        return true;
+    if (!idToken)
+        return false;
+    const payload = idToken.split('.')[1];
+    if (!payload)
+        return false;
+    try {
+        const { hd } = JSON.parse(Buffer.from(payload, 'base64url').toString());
+        return hd ? allowedDomains.includes(hd) : false;
+    }
+    catch {
+        return false;
+    }
+}
+export function createClients(accessToken, refreshToken) {
+    const auth = new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET);
+    auth.setCredentials({
+        access_token: accessToken,
+        refresh_token: refreshToken,
+    });
+    return {
+        accessToken,
+        auth,
+        docs: google.docs({ version: 'v1', auth }),
+        sheets: google.sheets({ version: 'v4', auth }),
+        drive: google.drive({ version: 'v3', auth }),
+        script: google.script({ version: 'v1', auth }),
+        gmail: google.gmail({ version: 'v1', auth }),
+        calendar: google.calendar({ version: 'v3', auth }),
+    };
+}
+const wrappedServers = new WeakSet();
+/**
+ * Wraps server.addTool() so that in remote (httpStream) mode every tool
+ * automatically gets: auth enforcement, domain restriction, and per-request
+ * Google API clients via AsyncLocalStorage. Zero changes to tool files.
+ */
+export function wrapServerForRemote(server) {
+    if (wrappedServers.has(server))
+        return;
+    wrappedServers.add(server);
+    const previousAddTool = server.addTool.bind(server);
+    server.addTool = (toolDef) => {
+        const originalExecute = toolDef.execute;
+        previousAddTool({
+            ...toolDef,
+            canAccess: toolDef.canAccess
+                ? (auth) => requireAuth(auth) && toolDef.canAccess(auth)
+                : requireAuth,
+            execute: async (args, context) => {
+                const { accessToken, refreshToken, idToken } = getAuthSession(context.session);
+                if (!checkDomain(idToken)) {
+                    throw new UserError('Your Google account domain is not allowed on this server.');
+                }
+                const clients = createClients(accessToken, refreshToken);
+                return requestClients.run(clients, () => originalExecute(args, context));
+            },
+        });
+    };
+    if (allowedDomains.length > 0) {
+        logger.info(`Remote mode: domain restriction active for [${allowedDomains.join(', ')}]`);
+    }
+}

package/dist/tools/calendar/createEvent.js

@@ -0,0 +1,89 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { randomUUID } from 'node:crypto';
+import { getCalendarClient } from '../../clients.js';
+import { createEventDateTimeSchema } from './helpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'createEvent',
+        description: 'Creates a new event on a Google Calendar. Supports timed events (start/end with dateTime) and all-day events (start/end with date). Set sendUpdates to email invitations to attendees.',
+        parameters: z.strictObject({
+            calendarId: z
+                .string()
+                .optional()
+                .default('primary')
+                .describe('Calendar ID. Defaults to "primary".'),
+            summary: z.string().describe('Event title.'),
+            description: z.string().optional().describe('Event description / notes.'),
+            location: z.string().optional().describe('Physical address or location string.'),
+            start: createEventDateTimeSchema().describe('Event start. Provide dateTime or date.'),
+            end: createEventDateTimeSchema().describe('Event end. Provide dateTime or date. For all-day events, end.date is exclusive.'),
+            attendees: z
+                .array(z.strictObject({
+                email: z.string().describe('Attendee email address.'),
+                optional: z.boolean().optional().describe('Mark attendee as optional.'),
+            }))
+                .optional()
+                .describe('List of attendees to invite.'),
+            sendUpdates: z
+                .enum(['all', 'externalOnly', 'none'])
+                .optional()
+                .default('none')
+                .describe('Whether to send email invitations: "all" sends to everyone, "externalOnly" only to non-domain attendees, "none" sends nothing (default).'),
+            conferenceData: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, attaches an automatically generated Google Meet link to the event.'),
+        }),
+        execute: async (args, { log }) => {
+            const calendar = await getCalendarClient();
+            log.info(`Creating event "${args.summary}" on calendar ${args.calendarId}`);
+            try {
+                const response = await calendar.events.insert({
+                    calendarId: args.calendarId,
+                    sendUpdates: args.sendUpdates,
+                    conferenceDataVersion: args.conferenceData ? 1 : undefined,
+                    requestBody: {
+                        summary: args.summary,
+                        description: args.description,
+                        location: args.location,
+                        start: args.start,
+                        end: args.end,
+                        attendees: args.attendees,
+                        ...(args.conferenceData && {
+                            conferenceData: {
+                                createRequest: {
+                                    requestId: `mcp-${randomUUID()}`,
+                                    conferenceSolutionKey: { type: 'hangoutsMeet' },
+                                },
+                            },
+                        }),
+                    },
+                });
+                const event = response.data;
+                return JSON.stringify({
+                    success: true,
+                    id: event.id,
+                    summary: event.summary,
+                    start: event.start,
+                    end: event.end,
+                    htmlLink: event.htmlLink,
+                    hangoutLink: event.hangoutLink ?? null,
+                    attendees: event.attendees?.length ?? 0,
+                    message: `Event "${event.summary}" created.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error creating event: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Calendar not found (ID: ${args.calendarId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the calendar.events scope was granted.');
+                if (error.code === 400)
+                    throw new UserError(`Calendar rejected the event: ${error.message || 'Bad request'}. Check that start/end formats are valid RFC3339.`);
+                throw new UserError(`Failed to create event: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/calendar/deleteEvent.js

@@ -0,0 +1,49 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getCalendarClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'deleteEvent',
+        description: 'Deletes an event from a Google Calendar. This is permanent — the event is removed, not trashed. Use sendUpdates to email cancellations to attendees.',
+        parameters: z.strictObject({
+            calendarId: z
+                .string()
+                .optional()
+                .default('primary')
+                .describe('Calendar ID. Defaults to "primary".'),
+            eventId: z.string().describe('The event ID to delete (from listEvents).'),
+            sendUpdates: z
+                .enum(['all', 'externalOnly', 'none'])
+                .optional()
+                .default('none')
+                .describe('Whether to email cancellation notices to attendees.'),
+        }),
+        execute: async (args, { log }) => {
+            const calendar = await getCalendarClient();
+            log.info(`Deleting event ${args.eventId} from calendar ${args.calendarId}`);
+            try {
+                await calendar.events.delete({
+                    calendarId: args.calendarId,
+                    eventId: args.eventId,
+                    sendUpdates: args.sendUpdates,
+                });
+                return JSON.stringify({
+                    success: true,
+                    eventId: args.eventId,
+                    calendarId: args.calendarId,
+                    message: `Event ${args.eventId} deleted from calendar ${args.calendarId}.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error deleting event: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Event not found: ${args.eventId}.`);
+                if (error.code === 410)
+                    throw new UserError(`Event ${args.eventId} was already deleted.`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the calendar.events scope was granted.');
+                throw new UserError(`Failed to delete event: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/calendar/helpers.js

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+export const createEventDateTimeSchema = () => z
+    .object({
+    dateTime: z
+        .string()
+        .optional()
+        .describe('RFC3339 timestamp with timezone offset, e.g. "2026-04-15T14:00:00-08:00". Use this for timed events.'),
+    date: z
+        .string()
+        .optional()
+        .describe('ISO date "YYYY-MM-DD" for all-day events. Use instead of dateTime.'),
+    timeZone: z
+        .string()
+        .optional()
+        .describe('IANA timezone like "America/Los_Angeles". Optional when dateTime has an offset.'),
+})
+    .refine((v) => v.dateTime || v.date, {
+    message: 'Provide either dateTime (timed event) or date (all-day event).',
+});

package/dist/tools/calendar/index.js

@@ -0,0 +1,12 @@
+import { register as listEvents } from './listEvents.js';
+import { register as createEvent } from './createEvent.js';
+import { register as updateEvent } from './updateEvent.js';
+import { register as deleteEvent } from './deleteEvent.js';
+import { register as quickAddEvent } from './quickAddEvent.js';
+export function registerCalendarTools(server) {
+    listEvents(server);
+    createEvent(server);
+    updateEvent(server);
+    deleteEvent(server);
+    quickAddEvent(server);
+}

package/dist/tools/calendar/listEvents.js

@@ -0,0 +1,84 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getCalendarClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'listEvents',
+        description: "Lists or searches Google Calendar events. Defaults to the user's primary calendar starting now. Use timeMin/timeMax (RFC3339 timestamps) to bound the window, q for free-text search, and maxResults to cap the count. Returns event IDs needed for updateEvent and deleteEvent.",
+        parameters: z.strictObject({
+            calendarId: z
+                .string()
+                .optional()
+                .default('primary')
+                .describe('Calendar ID. Defaults to "primary" (the user\'s main calendar).'),
+            q: z
+                .string()
+                .optional()
+                .describe('Free-text search across summary, description, location, and attendees.'),
+            timeMin: z
+                .string()
+                .optional()
+                .describe('Lower bound (inclusive) as RFC3339 timestamp, e.g. "2026-04-10T00:00:00-08:00". Defaults to now.'),
+            timeMax: z.string().optional().describe('Upper bound (exclusive) as RFC3339 timestamp.'),
+            maxResults: z
+                .number()
+                .int()
+                .min(1)
+                .max(2500)
+                .optional()
+                .default(25)
+                .describe('Maximum number of events to return (1-2500). Defaults to 25.'),
+            singleEvents: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe('If true (default), expands recurring events into individual instances. Set false to receive recurring events as a single record.'),
+        }),
+        execute: async (args, { log }) => {
+            const calendar = await getCalendarClient();
+            const timeMin = args.timeMin ?? new Date().toISOString();
+            log.info(`Listing calendar events on ${args.calendarId} (timeMin=${timeMin}, q=${args.q ?? 'none'})`);
+            try {
+                const response = await calendar.events.list({
+                    calendarId: args.calendarId,
+                    q: args.q,
+                    timeMin,
+                    timeMax: args.timeMax,
+                    maxResults: args.maxResults,
+                    singleEvents: args.singleEvents,
+                    orderBy: args.singleEvents ? 'startTime' : undefined,
+                });
+                const events = (response.data.items ?? []).map((event) => ({
+                    id: event.id,
+                    status: event.status,
+                    summary: event.summary ?? null,
+                    description: event.description ?? null,
+                    location: event.location ?? null,
+                    start: event.start ?? null,
+                    end: event.end ?? null,
+                    attendees: event.attendees?.map((a) => ({
+                        email: a.email,
+                        responseStatus: a.responseStatus,
+                        optional: a.optional ?? false,
+                    })) ?? [],
+                    organizer: event.organizer?.email ?? null,
+                    htmlLink: event.htmlLink ?? null,
+                    recurringEventId: event.recurringEventId ?? null,
+                }));
+                return JSON.stringify({
+                    events,
+                    count: events.length,
+                    nextPageToken: response.data.nextPageToken ?? null,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing calendar events: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Calendar not found (ID: ${args.calendarId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the calendar.events scope was granted during consent.');
+                throw new UserError(`Failed to list events: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/calendar/quickAddEvent.js

@@ -0,0 +1,55 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getCalendarClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'quickAddEvent',
+        description: 'Creates a calendar event from a natural-language string using Google Calendar\'s quick-add parser. Examples: "Lunch with Sarah tomorrow at 12pm", "Dentist appointment next Tuesday 3-4pm", "Team standup every weekday 9am". Faster than createEvent when you don\'t need attendees, descriptions, or precise control over fields.',
+        parameters: z.strictObject({
+            calendarId: z
+                .string()
+                .optional()
+                .default('primary')
+                .describe('Calendar ID. Defaults to "primary".'),
+            text: z
+                .string()
+                .describe('Natural-language description of the event. Google parses the title and time from this string.'),
+            sendUpdates: z
+                .enum(['all', 'externalOnly', 'none'])
+                .optional()
+                .default('none')
+                .describe('Whether to email invitations (rarely useful for quick add).'),
+        }),
+        execute: async (args, { log }) => {
+            const calendar = await getCalendarClient();
+            log.info(`Quick-adding event on ${args.calendarId}: "${args.text}"`);
+            try {
+                const response = await calendar.events.quickAdd({
+                    calendarId: args.calendarId,
+                    text: args.text,
+                    sendUpdates: args.sendUpdates,
+                });
+                const event = response.data;
+                return JSON.stringify({
+                    success: true,
+                    id: event.id,
+                    summary: event.summary,
+                    start: event.start,
+                    end: event.end,
+                    htmlLink: event.htmlLink,
+                    message: `Event "${event.summary}" created from "${args.text}".`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error quick-adding event: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Calendar not found (ID: ${args.calendarId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the calendar.events scope was granted.');
+                if (error.code === 400)
+                    throw new UserError(`Calendar could not parse "${args.text}" as an event. Try a clearer time format.`);
+                throw new UserError(`Failed to quick-add event: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/calendar/updateEvent.js

@@ -0,0 +1,84 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getCalendarClient } from '../../clients.js';
+import { createEventDateTimeSchema } from './helpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'updateEvent',
+        description: 'Updates an existing Google Calendar event with PATCH semantics — only the fields you provide are changed; everything else stays the same. Common uses: reschedule (set start+end), retitle (set summary), add/remove attendees (set attendees array which fully replaces).',
+        parameters: z.strictObject({
+            calendarId: z
+                .string()
+                .optional()
+                .default('primary')
+                .describe('Calendar ID. Defaults to "primary".'),
+            eventId: z.string().describe('The event ID to update (from listEvents).'),
+            summary: z.string().optional().describe('New event title.'),
+            description: z.string().optional().describe('New event description.'),
+            location: z.string().optional().describe('New location.'),
+            start: createEventDateTimeSchema().optional().describe('New start time.'),
+            end: createEventDateTimeSchema().optional().describe('New end time.'),
+            attendees: z
+                .array(z.strictObject({
+                email: z.string(),
+                optional: z.boolean().optional(),
+            }))
+                .optional()
+                .describe('Replaces the entire attendee list. To add one, fetch the event first.'),
+            sendUpdates: z
+                .enum(['all', 'externalOnly', 'none'])
+                .optional()
+                .default('none')
+                .describe('Whether to email attendees about the change.'),
+        }),
+        execute: async (args, { log }) => {
+            const calendar = await getCalendarClient();
+            log.info(`Patching event ${args.eventId} on calendar ${args.calendarId}`);
+            const requestBody = {};
+            if (args.summary !== undefined)
+                requestBody.summary = args.summary;
+            if (args.description !== undefined)
+                requestBody.description = args.description;
+            if (args.location !== undefined)
+                requestBody.location = args.location;
+            if (args.start !== undefined)
+                requestBody.start = args.start;
+            if (args.end !== undefined)
+                requestBody.end = args.end;
+            if (args.attendees !== undefined)
+                requestBody.attendees = args.attendees;
+            if (Object.keys(requestBody).length === 0) {
+                throw new UserError('No fields provided to update. Pass at least one of summary, description, location, start, end, or attendees.');
+            }
+            try {
+                const response = await calendar.events.patch({
+                    calendarId: args.calendarId,
+                    eventId: args.eventId,
+                    sendUpdates: args.sendUpdates,
+                    requestBody,
+                });
+                const event = response.data;
+                return JSON.stringify({
+                    success: true,
+                    id: event.id,
+                    summary: event.summary,
+                    start: event.start,
+                    end: event.end,
+                    htmlLink: event.htmlLink,
+                    updated: event.updated,
+                    message: `Event ${event.id} updated.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error updating event: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Event not found: ${args.eventId} on calendar ${args.calendarId}.`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the calendar.events scope was granted.');
+                if (error.code === 400)
+                    throw new UserError(`Calendar rejected the update: ${error.message || 'Bad request'}.`);
+                throw new UserError(`Failed to update event: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/addTab.js

@@ -0,0 +1,84 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import { DocumentIdParameter } from '../../types.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'addTab',
+        description: "Adds a new tab to a Google Docs document. Optionally set the tab title, position, parent tab (for nesting), and icon emoji. Returns the new tab's ID and properties.",
+        parameters: DocumentIdParameter.extend({
+            title: z
+                .string()
+                .optional()
+                .describe('The title for the new tab. If not specified, Google Docs assigns a default name.'),
+            parentTabId: z
+                .string()
+                .optional()
+                .describe('The ID of an existing tab to nest this new tab under as a child. Use listDocumentTabs to get tab IDs. If not specified, the tab is created at the root level.'),
+            index: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('The zero-based position among sibling tabs (within the same parent). If not specified, the tab is added at the end.'),
+            iconEmoji: z
+                .string()
+                .optional()
+                .describe('An emoji to display as the tab icon (e.g., "📋").'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Adding new tab to doc ${args.documentId}`);
+            try {
+                // If parentTabId is provided, verify it exists
+                if (args.parentTabId) {
+                    await GDocsHelpers.getDocumentTab(docs, args.documentId, args.parentTabId);
+                }
+                const tabProperties = {};
+                if (args.title !== undefined)
+                    tabProperties.title = args.title;
+                if (args.parentTabId !== undefined)
+                    tabProperties.parentTabId = args.parentTabId;
+                if (args.index !== undefined)
+                    tabProperties.index = args.index;
+                if (args.iconEmoji !== undefined)
+                    tabProperties.iconEmoji = args.iconEmoji;
+                const response = await docs.documents.batchUpdate({
+                    documentId: args.documentId,
+                    requestBody: {
+                        requests: [
+                            {
+                                addDocumentTab: {
+                                    tabProperties,
+                                },
+                            },
+                        ],
+                    },
+                });
+                const newTabProps = response.data.replies?.[0]?.addDocumentTab?.tabProperties;
+                if (newTabProps) {
+                    return JSON.stringify({
+                        message: `Successfully added new tab "${newTabProps.title || '(untitled)'}"`,
+                        tabId: newTabProps.tabId,
+                        title: newTabProps.title,
+                        index: newTabProps.index,
+                        parentTabId: newTabProps.parentTabId,
+                        nestingLevel: newTabProps.nestingLevel,
+                    }, null, 2);
+                }
+                return 'Tab created successfully, but could not retrieve the new tab details.';
+            }
+            catch (error) {
+                log.error(`Error adding tab to doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                if (error.code === 404)
+                    throw new UserError(`Document not found (ID: ${args.documentId}).`);
+                if (error.code === 403)
+                    throw new UserError(`Permission denied for document (ID: ${args.documentId}).`);
+                throw new UserError(`Failed to add tab: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/docs/appendTableRows.js

@@ -0,0 +1,89 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDocsClient } from '../../clients.js';
+import * as GDocsHelpers from '../../googleDocsApiHelpers.js';
+import { DocumentIdParameter } from '../../types.js';
+import { getTableById } from './structureHelpers.js';
+import { replaceTableRowData as replaceTableRowDataInternal } from './tableRowDataHelpers.js';
+import { TABLE_CONTENT_INDEXED_BODY_FIELDS, buildDocumentGetFields } from './tabFieldMasks.js';
+export function register(server) {
+    server.addTool({
+        name: 'appendTableRows',
+        description: 'Appends one or more plain-text rows to the end of an existing Google Docs table while preserving the table structure.',
+        parameters: DocumentIdParameter.extend({
+            tableId: z
+                .string()
+                .min(1)
+                .describe('The MCP table ID returned by listDocumentTables, for example "table:body:0".'),
+            rows: z
+                .array(z.array(z.string()).max(50))
+                .min(1)
+                .max(200)
+                .describe('Rows to append. Each inner array is the plain-text cell values for one row.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab containing the table. If not specified, uses the first tab or legacy document body.'),
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Appending ${args.rows.length} row(s) to ${args.tableId} in doc ${args.documentId}${args.tabId ? ` (tab: ${args.tabId})` : ''}`);
+            try {
+                const tableRowFieldMask = buildDocumentGetFields(TABLE_CONTENT_INDEXED_BODY_FIELDS, args.tabId);
+                const res = await docs.documents.get({
+                    documentId: args.documentId,
+                    ...(args.tabId && { includeTabsContent: true }),
+                    fields: tableRowFieldMask,
+                });
+                const table = getTableById(res.data, args.tableId, args.tabId);
+                if (!table) {
+                    throw new UserError(`Table "${args.tableId}" not found in document.`);
+                }
+                if (table.startIndex == null) {
+                    throw new UserError(`Table "${args.tableId}" does not expose a valid table start index.`);
+                }
+                for (const [offset, rowValues] of args.rows.entries()) {
+                    if (rowValues.length > table.columnCount) {
+                        throw new UserError(`Row ${offset} has ${rowValues.length} values, but table ${args.tableId} only has ${table.columnCount} columns.`);
+                    }
+                }
+                const insertRequests = args.rows.map(() => GDocsHelpers.buildInsertTableRowRequest(table.startIndex, table.rowCount - 1, true, args.tabId));
+                await GDocsHelpers.executeBatchUpdateWithSplitting(docs, args.documentId, insertRequests, log);
+                const refreshed = await docs.documents.get({
+                    documentId: args.documentId,
+                    ...(args.tabId && { includeTabsContent: true }),
+                    fields: tableRowFieldMask,
+                });
+                const updatedTable = getTableById(refreshed.data, args.tableId, args.tabId);
+                if (!updatedTable) {
+                    throw new UserError(`Table "${args.tableId}" could not be found after appending rows.`);
+                }
+                const firstAppendedRowIndex = table.rowCount;
+                for (const [offset, rowValues] of args.rows.entries()) {
+                    const currentTable = offset === 0
+                        ? updatedTable
+                        : getTableById((await docs.documents.get({
+                            documentId: args.documentId,
+                            ...(args.tabId && { includeTabsContent: true }),
+                            fields: tableRowFieldMask,
+                        })).data, args.tableId, args.tabId);
+                    if (!currentTable) {
+                        throw new UserError(`Table "${args.tableId}" could not be re-fetched while populating appended rows.`);
+                    }
+                    await replaceTableRowDataInternal(docs, args.documentId, currentTable, firstAppendedRowIndex + offset, rowValues, args.tabId);
+                }
+                return `Successfully appended ${args.rows.length} row(s) to table ${args.tableId}.`;
+            }
+            catch (error) {
+                log.error(`Error appending rows to ${args.tableId} in doc ${args.documentId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                if (error.code === 404)
+                    throw new UserError(`Document not found (ID: ${args.documentId}).`);
+                if (error.code === 403)
+                    throw new UserError(`Permission denied for document (ID: ${args.documentId}).`);
+                throw new UserError(`Failed to append table rows: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}