@triffon/google-docs-mcp 1.11.3-triffon

package/dist/tools/sheets/updateTableRange.js

@@ -0,0 +1,51 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'updateTableRange',
+        description: "Modifies a table's dimensions (add/remove rows and columns) by updating its range. The new range must include the original table range.",
+        parameters: z.strictObject({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            tableIdentifier: z
+                .string()
+                .describe('The table name or table ID to update. Use listTables to see available tables.'),
+            range: z
+                .string()
+                .describe('New A1 notation range for the table (e.g., "Sheet1!A1:F15"). Must include the original table range.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Updating table range for "${args.tableIdentifier}": ${args.range}`);
+            try {
+                // Resolve the table to get its current info
+                const { table, sheetName } = await SheetsHelpers.resolveTableIdentifier(sheets, args.spreadsheetId, args.tableIdentifier);
+                // Parse the new range
+                const { a1Range } = SheetsHelpers.parseRange(args.range);
+                const sheetId = await SheetsHelpers.resolveSheetId(sheets, args.spreadsheetId, sheetName || undefined);
+                const newRange = SheetsHelpers.parseA1ToGridRange(a1Range, sheetId);
+                // Update the table range
+                const updatedTable = await SheetsHelpers.updateTableRangeHelper(sheets, args.spreadsheetId, table.tableId || '', newRange);
+                return JSON.stringify({
+                    tableId: updatedTable.tableId,
+                    name: updatedTable.name,
+                    oldRange: table.range
+                        ? `${SheetsHelpers.rowColToA1(table.range.startRowIndex || 0, table.range.startColumnIndex || 0)}:${SheetsHelpers.rowColToA1((table.range.endRowIndex || 1) - 1, (table.range.endColumnIndex || 1) - 1)}`
+                        : 'Unknown',
+                    newRange: args.range,
+                    columnCount: updatedTable.columnProperties?.length || 0,
+                    message: `Table "${updatedTable.name}" range updated successfully.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error updating table range: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to update table range: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/sheets/writeSpreadsheet.js

@@ -0,0 +1,45 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getSheetsClient } from '../../clients.js';
+import * as SheetsHelpers from '../../googleSheetsApiHelpers.js';
+import { SpreadsheetCellValueSchema } from '../../types.js';
+export function register(server) {
+    server.addTool({
+        name: 'writeSpreadsheet',
+        description: 'Writes data to a range in a spreadsheet, overwriting existing values. Use appendRows to add data without overwriting.',
+        parameters: z.strictObject({
+            spreadsheetId: z
+                .string()
+                .describe('The spreadsheet ID — the long string between /d/ and /edit in a Google Sheets URL.'),
+            range: z
+                .string()
+                .describe('A1 notation range to write to (e.g., "A1:B2" or "Sheet1!A1:B2").'),
+            values: z
+                .array(z.array(SpreadsheetCellValueSchema).max(500))
+                .max(500)
+                .describe('2D array of values to write. Each inner array represents a row.'),
+            valueInputOption: z
+                .enum(['RAW', 'USER_ENTERED'])
+                .optional()
+                .default('USER_ENTERED')
+                .describe('How input data should be interpreted. RAW: values are stored as-is. USER_ENTERED: values are parsed as if typed by a user.'),
+        }),
+        execute: async (args, { log }) => {
+            const sheets = await getSheetsClient();
+            log.info(`Writing to spreadsheet ${args.spreadsheetId}, range: ${args.range}`);
+            try {
+                const response = await SheetsHelpers.writeRange(sheets, args.spreadsheetId, args.range, args.values, args.valueInputOption);
+                const updatedCells = response.updatedCells || 0;
+                const updatedRows = response.updatedRows || 0;
+                const updatedColumns = response.updatedColumns || 0;
+                return `Successfully wrote ${updatedCells} cells (${updatedRows} rows, ${updatedColumns} columns) to range ${args.range}.`;
+            }
+            catch (error) {
+                log.error(`Error writing to spreadsheet ${args.spreadsheetId}: ${error.message || error}`);
+                if (error instanceof UserError)
+                    throw error;
+                throw new UserError(`Failed to write to spreadsheet: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/utils/appendMarkdownToGoogleDoc.js

@@ -0,0 +1,95 @@
+import { UserError } from 'fastmcp';
+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 { TAB_BODY_END_INDEX_FIELDS } from '../docs/tabFieldMasks.js';
+export function register(server) {
+    server.addTool({
+        name: 'appendMarkdown',
+        description: 'Appends formatted content to the end of a document using markdown syntax. Supports headings, bold, italic, strikethrough, links, and bullet/numbered lists. Use this instead of appendText when you need formatting.',
+        parameters: DocumentIdParameter.extend({
+            markdown: z.string().min(1).describe('The markdown content to append.'),
+            addNewlineIfNeeded: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe('Add spacing before appended content if needed.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to append to. If not specified, appends to the first tab.'),
+            firstHeadingAsTitle: z
+                .boolean()
+                .optional()
+                .default(false)
+                .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 }) => {
+            const docs = await getDocsClient();
+            log.info(`Appending markdown to doc ${args.documentId} (${args.markdown.length} chars)${args.tabId ? ` in tab ${args.tabId}` : ''}`);
+            try {
+                // 1. Get document end index
+                const doc = await docs.documents.get({
+                    documentId: args.documentId,
+                    includeTabsContent: !!args.tabId,
+                    suggestionsViewMode: 'PREVIEW_WITHOUT_SUGGESTIONS',
+                    fields: args.tabId ? TAB_BODY_END_INDEX_FIELDS : 'body(content(endIndex))',
+                });
+                let bodyContent;
+                if (args.tabId) {
+                    const targetTab = GDocsHelpers.findTabById(doc.data, args.tabId);
+                    if (!targetTab) {
+                        throw new UserError(`Tab with ID "${args.tabId}" not found in document.`);
+                    }
+                    if (!targetTab.documentTab) {
+                        throw new UserError(`Tab "${args.tabId}" does not have content (may not be a document tab).`);
+                    }
+                    bodyContent = targetTab.documentTab.body?.content;
+                }
+                else {
+                    bodyContent = doc.data.body?.content;
+                }
+                if (!bodyContent) {
+                    throw new UserError('No content found in document/tab');
+                }
+                let startIndex = bodyContent[bodyContent.length - 1].endIndex - 1;
+                log.info(`Document end index: ${startIndex}`);
+                // 2. Add spacing if needed
+                if (args.addNewlineIfNeeded && startIndex > 1) {
+                    const location = { index: startIndex };
+                    if (args.tabId) {
+                        location.tabId = args.tabId;
+                    }
+                    await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [
+                        {
+                            insertText: {
+                                location,
+                                text: '\n\n',
+                            },
+                        },
+                    ]);
+                    startIndex += 2;
+                    log.info(`Added spacing, new start index: ${startIndex}`);
+                }
+                // 3. Convert and append markdown
+                const result = await insertMarkdown(docs, args.documentId, args.markdown, {
+                    startIndex,
+                    tabId: args.tabId,
+                    firstHeadingAsTitle: args.firstHeadingAsTitle,
+                });
+                const debugSummary = formatInsertResult(result);
+                log.info(debugSummary);
+                return `Successfully appended ${args.markdown.length} characters of markdown.\n\n${debugSummary}`;
+            }
+            catch (error) {
+                log.error(`Error appending markdown: ${error.message}`);
+                if (error instanceof UserError || error instanceof MarkdownConversionError) {
+                    throw error;
+                }
+                throw new UserError(`Failed to append markdown: ${error.message}`);
+            }
+        },
+    });
+}

package/dist/tools/utils/index.js

@@ -0,0 +1,8 @@
+import { register as replaceDocumentWithMarkdown } from './replaceDocumentWithMarkdown.js';
+import { register as appendMarkdownToGoogleDoc } from './appendMarkdownToGoogleDoc.js';
+import { register as replaceRangeWithMarkdown } from './replaceRangeWithMarkdown.js';
+export function registerUtilsTools(server) {
+    replaceDocumentWithMarkdown(server);
+    appendMarkdownToGoogleDoc(server);
+    replaceRangeWithMarkdown(server);
+}

package/dist/tools/utils/replaceDocumentWithMarkdown.js

@@ -0,0 +1,161 @@
+import { UserError } from 'fastmcp';
+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 { TAB_BODY_RANGE_FIELDS } from '../docs/tabFieldMasks.js';
+export function register(server) {
+    server.addTool({
+        name: 'replaceDocumentWithMarkdown',
+        description: "Replaces the entire document body with content parsed from markdown. Supports headings, bold, italic, strikethrough, links, and bullet/numbered lists. Use readDocument with format='markdown' first to get the current content, edit it, then call this tool to apply changes.",
+        parameters: DocumentIdParameter.extend({
+            markdown: z
+                .string()
+                .min(1)
+                .max(500000)
+                .describe('The markdown content to apply to the document.'),
+            preserveTitle: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, preserves the first heading/title and replaces content after it.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to replace content in. If not specified, replaces content in the first tab.'),
+            firstHeadingAsTitle: z
+                .boolean()
+                .optional()
+                .default(true)
+                .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 }) => {
+            const docs = await getDocsClient();
+            log.info(`Replacing doc ${args.documentId} with markdown (${args.markdown.length} chars)${args.tabId ? ` in tab ${args.tabId}` : ''}`);
+            try {
+                // 1. Get document structure
+                const doc = await docs.documents.get({
+                    documentId: args.documentId,
+                    includeTabsContent: !!args.tabId,
+                    suggestionsViewMode: 'PREVIEW_WITHOUT_SUGGESTIONS',
+                    fields: args.tabId ? TAB_BODY_RANGE_FIELDS : 'body(content(startIndex,endIndex))',
+                });
+                // 2. Calculate replacement range
+                let startIndex = 1;
+                let bodyContent;
+                if (args.tabId) {
+                    const targetTab = GDocsHelpers.findTabById(doc.data, args.tabId);
+                    if (!targetTab) {
+                        throw new UserError(`Tab with ID "${args.tabId}" not found in document.`);
+                    }
+                    if (!targetTab.documentTab) {
+                        throw new UserError(`Tab "${args.tabId}" does not have content (may not be a document tab).`);
+                    }
+                    bodyContent = targetTab.documentTab.body?.content;
+                }
+                else {
+                    bodyContent = doc.data.body?.content;
+                }
+                if (!bodyContent) {
+                    throw new UserError('No content found in document/tab');
+                }
+                let endIndex = bodyContent[bodyContent.length - 1].endIndex - 1;
+                if (args.preserveTitle) {
+                    // Find first content element that's a heading or paragraph
+                    for (const element of bodyContent) {
+                        if (element.paragraph && element.endIndex) {
+                            startIndex = element.endIndex;
+                            break;
+                        }
+                    }
+                }
+                // 3. Delete existing content
+                if (endIndex > startIndex) {
+                    const deleteRange = { startIndex, endIndex };
+                    if (args.tabId) {
+                        deleteRange.tabId = args.tabId;
+                    }
+                    log.info(`Deleting content from index ${startIndex} to ${endIndex}`);
+                    await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [
+                        {
+                            deleteContentRange: { range: deleteRange },
+                        },
+                    ]);
+                    log.info(`Delete complete.`);
+                }
+                // 4. Clean the surviving trailing paragraph.
+                //    deleteContentRange always leaves one trailing paragraph that cannot
+                //    be deleted. If it has bullet list membership or text formatting from
+                //    the old content, all subsequently inserted text inherits those
+                //    properties, corrupting the new document. We strip both bullets and
+                //    text styles from the survivor before inserting.
+                {
+                    // Re-read to get the survivor's endIndex (always a short document now)
+                    const docAfterDelete = await docs.documents.get({
+                        documentId: args.documentId,
+                        includeTabsContent: !!args.tabId,
+                        suggestionsViewMode: 'PREVIEW_WITHOUT_SUGGESTIONS',
+                        fields: args.tabId ? TAB_BODY_RANGE_FIELDS : 'body(content(startIndex,endIndex))',
+                    });
+                    let survivorContent;
+                    if (args.tabId) {
+                        const tab = GDocsHelpers.findTabById(docAfterDelete.data, args.tabId);
+                        survivorContent = tab?.documentTab?.body?.content;
+                    }
+                    else {
+                        survivorContent = docAfterDelete.data.body?.content;
+                    }
+                    const survivorEnd = survivorContent
+                        ? survivorContent[survivorContent.length - 1].endIndex
+                        : startIndex + 1;
+                    const survivorRange = { startIndex, endIndex: survivorEnd };
+                    if (args.tabId) {
+                        survivorRange.tabId = args.tabId;
+                    }
+                    const cleanupRequests = [
+                        { deleteParagraphBullets: { range: survivorRange } },
+                        {
+                            updateTextStyle: {
+                                range: survivorRange,
+                                textStyle: {
+                                    underline: false,
+                                    bold: false,
+                                    italic: false,
+                                    strikethrough: false,
+                                    foregroundColor: {},
+                                    backgroundColor: {},
+                                },
+                                fields: 'underline,bold,italic,strikethrough,foregroundColor,backgroundColor',
+                            },
+                        },
+                    ];
+                    try {
+                        await GDocsHelpers.executeBatchUpdate(docs, args.documentId, cleanupRequests);
+                        log.info(`Cleaned surviving paragraph (bullets + text style) at range ${startIndex}-${survivorEnd}`);
+                    }
+                    catch (e) {
+                        log.info(`Survivor cleanup skipped: ${e.message}`);
+                    }
+                }
+                // 5. Convert markdown and insert (indices calculated for empty document)
+                log.info(`Inserting markdown starting at index ${startIndex} (after delete, document should be empty)`);
+                const result = await insertMarkdown(docs, args.documentId, args.markdown, {
+                    startIndex,
+                    tabId: args.tabId,
+                    firstHeadingAsTitle: args.firstHeadingAsTitle,
+                });
+                const debugSummary = formatInsertResult(result);
+                log.info(debugSummary);
+                return `Successfully replaced document content with ${args.markdown.length} characters of markdown.\n\n${debugSummary}`;
+            }
+            catch (error) {
+                log.error(`Error replacing document with markdown: ${error.message}`);
+                if (error instanceof UserError || error instanceof MarkdownConversionError) {
+                    throw error;
+                }
+                throw new UserError(`Failed to apply markdown: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/utils/replaceRangeWithMarkdown.js

@@ -0,0 +1,72 @@
+import { UserError } from 'fastmcp';
+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';
+export function register(server) {
+    server.addTool({
+        name: 'replaceRangeWithMarkdown',
+        description: "Replaces a specific character range in a document with formatted markdown content. Use readDocument with format='json' to determine the start and end indices of the content you want to replace. Supports headings, bold, italic, strikethrough, links, bullet/numbered lists, code blocks, horizontal rules, and tables.",
+        parameters: DocumentIdParameter.extend({
+            startIndex: z
+                .number()
+                .int()
+                .min(1)
+                .describe("1-based character index where the replacement range begins (inclusive). Use readDocument with format='json' to find the correct index."),
+            endIndex: z
+                .number()
+                .int()
+                .min(1)
+                .describe("1-based character index where the replacement range ends (exclusive). Use readDocument with format='json' to find the correct index."),
+            markdown: z
+                .string()
+                .min(1)
+                .describe('The markdown content to insert in place of the deleted range.'),
+            tabId: z
+                .string()
+                .optional()
+                .describe('The ID of the specific tab to modify. If not specified, modifies the first tab.'),
+        }).refine((data) => data.endIndex > data.startIndex, {
+            message: 'endIndex must be greater than startIndex',
+            path: ['endIndex'],
+        }),
+        execute: async (args, { log }) => {
+            const docs = await getDocsClient();
+            log.info(`Replacing range ${args.startIndex}-${args.endIndex} in doc ${args.documentId} with markdown (${args.markdown.length} chars)${args.tabId ? ` in tab ${args.tabId}` : ''}`);
+            try {
+                // 1. Delete the existing content in the specified range
+                const deleteRange = {
+                    startIndex: args.startIndex,
+                    endIndex: args.endIndex,
+                };
+                if (args.tabId) {
+                    deleteRange.tabId = args.tabId;
+                }
+                log.info(`Deleting content from index ${args.startIndex} to ${args.endIndex}`);
+                await GDocsHelpers.executeBatchUpdate(docs, args.documentId, [
+                    {
+                        deleteContentRange: { range: deleteRange },
+                    },
+                ]);
+                log.info(`Delete complete.`);
+                // 2. Insert markdown at the start position (which is now where the deleted content was)
+                log.info(`Inserting markdown at index ${args.startIndex}`);
+                const result = await insertMarkdown(docs, args.documentId, args.markdown, {
+                    startIndex: args.startIndex,
+                    tabId: args.tabId,
+                });
+                const debugSummary = formatInsertResult(result);
+                log.info(debugSummary);
+                return `Successfully replaced range ${args.startIndex}-${args.endIndex} with ${args.markdown.length} characters of markdown.\n\n${debugSummary}`;
+            }
+            catch (error) {
+                log.error(`Error replacing range with markdown: ${error.message}`);
+                if (error instanceof UserError || error instanceof MarkdownConversionError) {
+                    throw error;
+                }
+                throw new UserError(`Failed to replace range with markdown: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/types.js

@@ -0,0 +1,208 @@
+// src/types.ts
+import { z } from 'zod';
+// --- Helper function for hex color validation ---
+export const hexColorRegex = /^#?([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/;
+export const validateHexColor = (color) => hexColorRegex.test(color);
+// --- Helper function for Hex to RGB conversion ---
+export function hexToRgbColor(hex) {
+    if (!hex)
+        return null;
+    let hexClean = hex.startsWith('#') ? hex.slice(1) : hex;
+    if (hexClean.length === 3) {
+        hexClean = hexClean[0] + hexClean[0] + hexClean[1] + hexClean[1] + hexClean[2] + hexClean[2];
+    }
+    if (hexClean.length !== 6)
+        return null;
+    const bigint = parseInt(hexClean, 16);
+    if (isNaN(bigint))
+        return null;
+    const r = ((bigint >> 16) & 255) / 255;
+    const g = ((bigint >> 8) & 255) / 255;
+    const b = (bigint & 255) / 255;
+    return { red: r, green: g, blue: b };
+}
+// --- Zod Schema Fragments for Reusability ---
+export const DocumentIdParameter = z.strictObject({
+    documentId: z
+        .string()
+        .describe('The document ID — the long string between /d/ and /edit in a Google Docs URL.'),
+});
+export const RangeParameters = z
+    .object({
+    startIndex: z
+        .number()
+        .int()
+        .min(1)
+        .describe('The starting index of the text range (inclusive, starts from 1).'),
+    endIndex: z.number().int().min(1).describe('The ending index of the text range (exclusive).'),
+})
+    .refine((data) => data.endIndex > data.startIndex, {
+    message: 'endIndex must be greater than startIndex',
+    path: ['endIndex'],
+});
+export const OptionalRangeParameters = z
+    .object({
+    startIndex: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Optional: The starting index of the text range (inclusive, starts from 1). If omitted, might apply to a found element or whole paragraph.'),
+    endIndex: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe('Optional: The ending index of the text range (exclusive). If omitted, might apply to a found element or whole paragraph.'),
+})
+    .refine((data) => !data.startIndex || !data.endIndex || data.endIndex > data.startIndex, {
+    message: 'If both startIndex and endIndex are provided, endIndex must be greater than startIndex',
+    path: ['endIndex'],
+});
+export const TextFindParameter = z.strictObject({
+    textToFind: z.string().min(1).describe('The exact text string to locate.'),
+    matchInstance: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .default(1)
+        .describe('Which instance of the text to target (1st, 2nd, etc.). Defaults to 1.'),
+});
+// --- Style Parameter Schemas ---
+export const TextStyleParameters = z
+    .object({
+    bold: z.boolean().optional().describe('Apply bold formatting.'),
+    italic: z.boolean().optional().describe('Apply italic formatting.'),
+    underline: z.boolean().optional().describe('Apply underline formatting.'),
+    strikethrough: z.boolean().optional().describe('Apply strikethrough formatting.'),
+    fontSize: z.number().min(1).optional().describe('Set font size (in points, e.g., 12).'),
+    fontFamily: z
+        .string()
+        .optional()
+        .describe('Set font family (e.g., "Arial", "Times New Roman").'),
+    foregroundColor: z
+        .string()
+        .refine(validateHexColor, { message: 'Invalid hex color format (e.g., #FF0000 or #F00)' })
+        .optional()
+        .describe('Set text color using hex format (e.g., "#FF0000").'),
+    backgroundColor: z
+        .string()
+        .refine(validateHexColor, { message: 'Invalid hex color format (e.g., #00FF00 or #0F0)' })
+        .optional()
+        .describe('Set text background color using hex format (e.g., "#FFFF00").'),
+    linkUrl: z
+        .string()
+        .url()
+        .refine((url) => /^https?:\/\//i.test(url), { message: 'Only http/https URLs are allowed.' })
+        .optional()
+        .describe('Make the text a hyperlink pointing to this URL (http or https only).'),
+    // clearDirectFormatting: z.boolean().optional().describe('If true, attempts to clear all direct text formatting within the range before applying new styles.') // Harder to implement perfectly
+})
+    .describe('Parameters for character-level text formatting.');
+export const ParagraphStyleParameters = z
+    .object({
+    alignment: z
+        .enum(['START', 'END', 'CENTER', 'JUSTIFIED'])
+        .optional()
+        .describe('Paragraph alignment. START=left for LTR languages, END=right for LTR languages.'),
+    indentStart: z.number().min(0).optional().describe('Left indentation in points.'),
+    indentEnd: z.number().min(0).optional().describe('Right indentation in points.'),
+    spaceAbove: z.number().min(0).optional().describe('Space before the paragraph in points.'),
+    spaceBelow: z.number().min(0).optional().describe('Space after the paragraph in points.'),
+    namedStyleType: z
+        .enum([
+        'NORMAL_TEXT',
+        'TITLE',
+        'SUBTITLE',
+        'HEADING_1',
+        'HEADING_2',
+        'HEADING_3',
+        'HEADING_4',
+        'HEADING_5',
+        'HEADING_6',
+    ])
+        .optional()
+        .describe('Apply a built-in named paragraph style (e.g., HEADING_1).'),
+    keepWithNext: z
+        .boolean()
+        .optional()
+        .describe('Keep this paragraph together with the next one on the same page.'),
+    // Borders are more complex, might need separate objects/tools
+    // clearDirectFormatting: z.boolean().optional().describe('If true, attempts to clear all direct paragraph formatting within the range before applying new styles.') // Harder to implement perfectly
+})
+    .describe('Parameters for paragraph-level formatting.');
+export const SpreadsheetCellValueSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+// --- Combination Schemas for Tools ---
+export const ApplyTextStyleToolParameters = DocumentIdParameter.extend({
+    // Target EITHER by range OR by finding text
+    target: z
+        .union([RangeParameters, TextFindParameter])
+        .describe('Specify the target range either by start/end indices or by finding specific text.'),
+    style: TextStyleParameters.refine((styleArgs) => Object.values(styleArgs).some((v) => v !== undefined), { message: 'At least one text style option must be provided.' }).describe('The text styling to apply.'),
+    tabId: z
+        .string()
+        .optional()
+        .describe('The ID of the specific tab to apply formatting in. Use listDocumentTabs to get tab IDs. If not specified, operates on the first tab.'),
+});
+export const BatchApplyTextStyleOperation = z.strictObject({
+    target: z
+        .union([RangeParameters, TextFindParameter])
+        .describe("This operation's target range, either by start/end indices or by finding specific text."),
+    style: TextStyleParameters.refine((styleArgs) => Object.values(styleArgs).some((v) => v !== undefined), { message: 'At least one text style option must be provided.' }).describe('The text styling to apply for this operation.'),
+});
+export const BatchApplyTextStyleToolParameters = DocumentIdParameter.extend({
+    operations: z
+        .array(BatchApplyTextStyleOperation)
+        .min(1)
+        .max(500)
+        .describe('List of {target, style} operations to apply in as few Docs API calls as possible. ' +
+        'Prefer startIndex/endIndex ranges (computed once from a single readDocument JSON pass) over textToFind ' +
+        '— each textToFind target is resolved with its own document read before the batch write, which adds ' +
+        'back the round-trips this tool exists to avoid.'),
+    tabId: z
+        .string()
+        .optional()
+        .describe('The ID of the specific tab to apply formatting in. Applies to every operation in this call. If not specified, operates on the first tab.'),
+});
+export const ApplyParagraphStyleToolParameters = DocumentIdParameter.extend({
+    // Target EITHER by range OR by finding text (tool logic needs to find paragraph boundaries)
+    target: z
+        .union([
+        RangeParameters, // User provides paragraph start/end (less likely)
+        TextFindParameter, // Find text within paragraph to apply style
+        z.strictObject({
+            // Target by specific index within the paragraph
+            indexWithinParagraph: z
+                .number()
+                .int()
+                .min(1)
+                .describe('An index located anywhere within the target paragraph.'),
+        }),
+    ])
+        .describe('Specify the target paragraph either by start/end indices, by finding text within it, or by providing an index within it.'),
+    style: ParagraphStyleParameters.refine((styleArgs) => Object.values(styleArgs).some((v) => v !== undefined), { message: 'At least one paragraph style option must be provided.' }).describe('The paragraph styling to apply.'),
+    tabId: z
+        .string()
+        .optional()
+        .describe('The ID of the specific tab to apply formatting in. Use listDocumentTabs to get tab IDs. If not specified, operates on the first tab.'),
+});
+// --- Error Classes ---
+// Use FastMCP's UserError for client-facing issues
+// Define custom errors for internal issues if needed
+export class NotImplementedError extends Error {
+    constructor(message = 'This feature is not yet implemented.') {
+        super(message);
+        this.name = 'NotImplementedError';
+    }
+}
+export class MarkdownConversionError extends Error {
+    markdownPosition;
+    tokenType;
+    constructor(message, markdownPosition, tokenType) {
+        super(message);
+        this.markdownPosition = markdownPosition;
+        this.tokenType = tokenType;
+        this.name = 'MarkdownConversionError';
+    }
+}