@mcp-z/mcp-sheets 1.0.0

package/dist/esm/mcp/prompts/a1-notation.d.ts

@@ -0,0 +1,19 @@
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';
+export default function createPrompt(): {
+    name: string;
+    config: {
+        description: string;
+    };
+    handler: (_args: {
+        [x: string]: unknown;
+    }, _extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => Promise<{
+        messages: {
+            role: "user";
+            content: {
+                type: "text";
+                text: string;
+            };
+        }[];
+    }>;
+};

package/dist/esm/mcp/prompts/a1-notation.js

@@ -0,0 +1,49 @@
+export default function createPrompt() {
+    const config = {
+        description: 'Reference guide for Google Sheets A1 notation syntax'
+    };
+    const handler = async (_args, _extra)=>{
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `# Google Sheets A1 Notation Reference
+
+A1 notation identifies cells and ranges in Google Sheets.
+
+## Cell References
+- \`B5\` - Single cell at column B, row 5
+- \`A1\` - Top-left cell
+
+## Range References
+- \`A1:D10\` - Rectangle from A1 to D10
+- \`A5:D5\` - Single row (columns A-D of row 5)
+- \`B1:B10\` - Single column segment (rows 1-10 of column B)
+
+## Full Row/Column References
+- \`5:5\` - Entire row 5
+- \`B:B\` - Entire column B
+- \`A:D\` - Columns A through D (all rows)
+- \`1:10\` - Rows 1 through 10 (all columns)
+
+## Common Patterns
+| Goal | Notation |
+|------|----------|
+| Get one cell | \`B5\` |
+| Get a row | \`A5:Z5\` or \`5:5\` |
+| Get a column | \`B:B\` or \`B1:B1000\` |
+| Get a data table | \`A1:F100\` |
+| Get headers | \`1:1\` or \`A1:Z1\` |`
+                    }
+                }
+            ]
+        };
+    };
+    return {
+        name: 'a1-notation',
+        config,
+        handler
+    };
+}

package/dist/esm/mcp/prompts/a1-notation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/mcp/prompts/a1-notation.ts"],"sourcesContent":["import type { PromptModule } from '@mcp-z/server';\nimport type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';\nimport type { ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';\n\nexport default function createPrompt() {\n  const config = {\n    description: 'Reference guide for Google Sheets A1 notation syntax',\n  };\n\n  const handler = async (_args: { [x: string]: unknown }, _extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => {\n    return {\n      messages: [\n        {\n          role: 'user' as const,\n          content: {\n            type: 'text' as const,\n            text: `# Google Sheets A1 Notation Reference\n\nA1 notation identifies cells and ranges in Google Sheets.\n\n## Cell References\n- \\`B5\\` - Single cell at column B, row 5\n- \\`A1\\` - Top-left cell\n\n## Range References\n- \\`A1:D10\\` - Rectangle from A1 to D10\n- \\`A5:D5\\` - Single row (columns A-D of row 5)\n- \\`B1:B10\\` - Single column segment (rows 1-10 of column B)\n\n## Full Row/Column References\n- \\`5:5\\` - Entire row 5\n- \\`B:B\\` - Entire column B\n- \\`A:D\\` - Columns A through D (all rows)\n- \\`1:10\\` - Rows 1 through 10 (all columns)\n\n## Common Patterns\n| Goal | Notation |\n|------|----------|\n| Get one cell | \\`B5\\` |\n| Get a row | \\`A5:Z5\\` or \\`5:5\\` |\n| Get a column | \\`B:B\\` or \\`B1:B1000\\` |\n| Get a data table | \\`A1:F100\\` |\n| Get headers | \\`1:1\\` or \\`A1:Z1\\` |`,\n          },\n        },\n      ],\n    };\n  };\n\n  return {\n    name: 'a1-notation',\n    config,\n    handler,\n  } satisfies PromptModule;\n}\n"],"names":["createPrompt","config","description","handler","_args","_extra","messages","role","content","type","text","name"],"mappings":"AAIA,eAAe,SAASA;IACtB,MAAMC,SAAS;QACbC,aAAa;IACf;IAEA,MAAMC,UAAU,OAAOC,OAAiCC;QACtD,OAAO;YACLC,UAAU;gBACR;oBACEC,MAAM;oBACNC,SAAS;wBACPC,MAAM;wBACNC,MAAM,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;sCA0BmB,CAAC;oBAC7B;gBACF;aACD;QACH;IACF;IAEA,OAAO;QACLC,MAAM;QACNV;QACAE;IACF;AACF"}

package/dist/esm/mcp/prompts/index.d.ts

@@ -0,0 +1 @@
+export { default as a1Notation } from './a1-notation.js';

package/dist/esm/mcp/prompts/index.js

@@ -0,0 +1 @@
+export { default as a1Notation } from './a1-notation.js';

package/dist/esm/mcp/prompts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/mcp/prompts/index.ts"],"sourcesContent":["export { default as a1Notation } from './a1-notation.js';\n"],"names":["default","a1Notation"],"mappings":"AAAA,SAASA,WAAWC,UAAU,QAAQ,mBAAmB"}

package/dist/esm/mcp/resources/index.d.ts

@@ -0,0 +1 @@
+export { default as spreadsheet } from './spreadsheet.js';

package/dist/esm/mcp/resources/index.js

@@ -0,0 +1 @@
+export { default as spreadsheet } from './spreadsheet.js';

package/dist/esm/mcp/resources/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/mcp/resources/index.ts"],"sourcesContent":["export { default as spreadsheet } from './spreadsheet.js';\n"],"names":["default","spreadsheet"],"mappings":"AAAA,SAASA,WAAWC,WAAW,QAAQ,mBAAmB"}

package/dist/esm/mcp/resources/spreadsheet.d.ts

@@ -0,0 +1,2 @@
+import type { ResourceModule } from '@mcp-z/server';
+export default function createResource(): ResourceModule;

package/dist/esm/mcp/resources/spreadsheet.js

@@ -0,0 +1,88 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { google } from 'googleapis';
+export default function createResource() {
+    const template = new ResourceTemplate('sheets://spreadsheets/{spreadsheetId}', {
+        list: undefined
+    });
+    const config = {
+        description: 'Sheets spreadsheet resource',
+        mimeType: 'application/json'
+    };
+    const handler = async (uri, variables, extra)=>{
+        const spreadsheetId = Array.isArray(variables.spreadsheetId) ? variables.spreadsheetId[0] : variables.spreadsheetId;
+        if (!spreadsheetId) {
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        text: JSON.stringify({
+                            error: 'spreadsheetId is required'
+                        })
+                    }
+                ]
+            };
+        }
+        try {
+            var _data_properties, _data_properties1;
+            // Safe type guard to access middleware-enriched extra
+            const { logger, authContext } = extra;
+            const sheets = google.sheets({
+                version: 'v4',
+                auth: authContext.auth
+            });
+            const resp = await sheets.spreadsheets.get({
+                spreadsheetId,
+                fields: 'spreadsheetId,properties.title,sheets.properties'
+            });
+            const data = resp.data;
+            logger.info('sheets-spreadsheet resource fetch success', {
+                spreadsheetId: data.spreadsheetId,
+                title: data === null || data === void 0 ? void 0 : (_data_properties = data.properties) === null || _data_properties === void 0 ? void 0 : _data_properties.title,
+                sheetCount: ((data === null || data === void 0 ? void 0 : data.sheets) || []).length
+            });
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        text: JSON.stringify({
+                            id: data === null || data === void 0 ? void 0 : data.spreadsheetId,
+                            title: data === null || data === void 0 ? void 0 : (_data_properties1 = data.properties) === null || _data_properties1 === void 0 ? void 0 : _data_properties1.title,
+                            sheets: ((data === null || data === void 0 ? void 0 : data.sheets) || []).map((s)=>{
+                                var _s_properties, _s_properties1, _s_properties_gridProperties, _s_properties2, _s_properties_gridProperties1, _s_properties3;
+                                return {
+                                    id: s === null || s === void 0 ? void 0 : (_s_properties = s.properties) === null || _s_properties === void 0 ? void 0 : _s_properties.sheetId,
+                                    title: s === null || s === void 0 ? void 0 : (_s_properties1 = s.properties) === null || _s_properties1 === void 0 ? void 0 : _s_properties1.title,
+                                    rowCount: s === null || s === void 0 ? void 0 : (_s_properties2 = s.properties) === null || _s_properties2 === void 0 ? void 0 : (_s_properties_gridProperties = _s_properties2.gridProperties) === null || _s_properties_gridProperties === void 0 ? void 0 : _s_properties_gridProperties.rowCount,
+                                    columnCount: s === null || s === void 0 ? void 0 : (_s_properties3 = s.properties) === null || _s_properties3 === void 0 ? void 0 : (_s_properties_gridProperties1 = _s_properties3.gridProperties) === null || _s_properties_gridProperties1 === void 0 ? void 0 : _s_properties_gridProperties1.columnCount
+                                };
+                            })
+                        })
+                    }
+                ]
+            };
+        } catch (error) {
+            var _ref;
+            const { logger } = extra;
+            logger.info('sheets-spreadsheet resource fetch failed', error);
+            return {
+                contents: [
+                    {
+                        uri: uri.href,
+                        mimeType: 'application/json',
+                        text: JSON.stringify({
+                            error: String((_ref = error === null || error === void 0 ? void 0 : error.message) !== null && _ref !== void 0 ? _ref : error)
+                        })
+                    }
+                ]
+            };
+        }
+    };
+    return {
+        name: 'spreadsheet',
+        template,
+        config,
+        handler
+    };
+}

package/dist/esm/mcp/resources/spreadsheet.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/mcp/resources/spreadsheet.ts"],"sourcesContent":["import type { EnrichedExtra } from '@mcp-z/oauth-google';\nimport type { ResourceConfig, ResourceModule } from '@mcp-z/server';\nimport { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';\nimport type { ReadResourceResult, ServerNotification, ServerRequest } from '@modelcontextprotocol/sdk/types.js';\nimport { google, type sheets_v4 } from 'googleapis';\nimport type { GoogleApiError } from '../../types.js';\n\nexport default function createResource(): ResourceModule {\n  const template = new ResourceTemplate('sheets://spreadsheets/{spreadsheetId}', { list: undefined });\n  const config: ResourceConfig = {\n    description: 'Sheets spreadsheet resource',\n    mimeType: 'application/json',\n  };\n\n  const handler = async (uri: URL, variables: Record<string, string | string[]>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>): Promise<ReadResourceResult> => {\n    const spreadsheetId = Array.isArray(variables.spreadsheetId) ? variables.spreadsheetId[0] : variables.spreadsheetId;\n\n    if (!spreadsheetId) {\n      return {\n        contents: [\n          {\n            uri: uri.href,\n            mimeType: 'application/json',\n            text: JSON.stringify({ error: 'spreadsheetId is required' }),\n          },\n        ],\n      };\n    }\n\n    try {\n      // Safe type guard to access middleware-enriched extra\n      const { logger, authContext } = extra as unknown as EnrichedExtra;\n      const sheets = google.sheets({ version: 'v4', auth: authContext.auth });\n      const resp = await sheets.spreadsheets.get({\n        spreadsheetId,\n        fields: 'spreadsheetId,properties.title,sheets.properties',\n      });\n      const data = resp.data as sheets_v4.Schema$Spreadsheet;\n      logger.info('sheets-spreadsheet resource fetch success', {\n        spreadsheetId: data.spreadsheetId,\n        title: data?.properties?.title,\n        sheetCount: (data?.sheets || []).length,\n      });\n      return {\n        contents: [\n          {\n            uri: uri.href,\n            mimeType: 'application/json',\n            text: JSON.stringify({\n              id: data?.spreadsheetId,\n              title: data?.properties?.title,\n              sheets: (data?.sheets || []).map((s) => ({\n                id: s?.properties?.sheetId,\n                title: s?.properties?.title,\n                rowCount: s?.properties?.gridProperties?.rowCount,\n                columnCount: s?.properties?.gridProperties?.columnCount,\n              })),\n            }),\n          },\n        ],\n      };\n    } catch (error) {\n      const { logger } = extra as unknown as EnrichedExtra;\n      logger.info('sheets-spreadsheet resource fetch failed', error as Record<string, unknown>);\n      return {\n        contents: [\n          {\n            uri: uri.href,\n            mimeType: 'application/json',\n            text: JSON.stringify({\n              error: String((error as GoogleApiError)?.message ?? error),\n            }),\n          },\n        ],\n      };\n    }\n  };\n\n  return {\n    name: 'spreadsheet',\n    template,\n    config,\n    handler,\n  };\n}\n"],"names":["ResourceTemplate","google","createResource","template","list","undefined","config","description","mimeType","handler","uri","variables","extra","spreadsheetId","Array","isArray","contents","href","text","JSON","stringify","error","data","logger","authContext","sheets","version","auth","resp","spreadsheets","get","fields","info","title","properties","sheetCount","length","id","map","s","sheetId","rowCount","gridProperties","columnCount","String","message","name"],"mappings":"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"}

package/dist/esm/mcp/tools/cells-format.d.ts

@@ -0,0 +1,144 @@
+import type { EnrichedExtra } from '@mcp-z/oauth-google';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+declare const inputSchema: z.ZodObject<{
+    id: z.ZodString;
+    gid: z.ZodCoercedString<unknown>;
+    requests: z.ZodArray<z.ZodObject<{
+        range: z.ZodString;
+        backgroundColor: z.ZodOptional<z.ZodObject<{
+            red: z.ZodNumber;
+            green: z.ZodNumber;
+            blue: z.ZodNumber;
+        }, z.core.$strip>>;
+        textColor: z.ZodOptional<z.ZodObject<{
+            red: z.ZodNumber;
+            green: z.ZodNumber;
+            blue: z.ZodNumber;
+        }, z.core.$strip>>;
+        bold: z.ZodOptional<z.ZodBoolean>;
+        fontSize: z.ZodOptional<z.ZodNumber>;
+        horizontalAlignment: z.ZodOptional<z.ZodEnum<{
+            LEFT: "LEFT";
+            CENTER: "CENTER";
+            RIGHT: "RIGHT";
+        }>>;
+        numberFormat: z.ZodOptional<z.ZodObject<{
+            type: z.ZodEnum<{
+                TEXT: "TEXT";
+                NUMBER: "NUMBER";
+                PERCENT: "PERCENT";
+                CURRENCY: "CURRENCY";
+                DATE: "DATE";
+                TIME: "TIME";
+            }>;
+            pattern: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        borders: z.ZodOptional<z.ZodObject<{
+            style: z.ZodEnum<{
+                SOLID: "SOLID";
+                DASHED: "DASHED";
+                DOTTED: "DOTTED";
+            }>;
+            color: z.ZodObject<{
+                red: z.ZodNumber;
+                green: z.ZodNumber;
+                blue: z.ZodNumber;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const outputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"success">;
+    id: z.ZodString;
+    gid: z.ZodString;
+    sheetTitle: z.ZodString;
+    sheetUrl: z.ZodString;
+    successCount: z.ZodNumber;
+    failedRanges: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        range: z.ZodString;
+        error: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"auth_required">;
+    provider: z.ZodString;
+    message: z.ZodString;
+    url: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>], "type">;
+export type Input = z.infer<typeof inputSchema>;
+export type Output = z.infer<typeof outputSchema>;
+declare function handler({ id, gid, requests }: Input, extra: EnrichedExtra): Promise<CallToolResult>;
+export default function createTool(): {
+    name: string;
+    config: {
+        readonly description: "Apply formatting (colors, borders, fonts, alignment, number formats) to cell ranges without modifying data. Supports batch operations for efficiency. Colors use 0-1 RGB format. Best for creating professional, visually organized spreadsheets.";
+        readonly inputSchema: z.ZodObject<{
+            id: z.ZodString;
+            gid: z.ZodCoercedString<unknown>;
+            requests: z.ZodArray<z.ZodObject<{
+                range: z.ZodString;
+                backgroundColor: z.ZodOptional<z.ZodObject<{
+                    red: z.ZodNumber;
+                    green: z.ZodNumber;
+                    blue: z.ZodNumber;
+                }, z.core.$strip>>;
+                textColor: z.ZodOptional<z.ZodObject<{
+                    red: z.ZodNumber;
+                    green: z.ZodNumber;
+                    blue: z.ZodNumber;
+                }, z.core.$strip>>;
+                bold: z.ZodOptional<z.ZodBoolean>;
+                fontSize: z.ZodOptional<z.ZodNumber>;
+                horizontalAlignment: z.ZodOptional<z.ZodEnum<{
+                    LEFT: "LEFT";
+                    CENTER: "CENTER";
+                    RIGHT: "RIGHT";
+                }>>;
+                numberFormat: z.ZodOptional<z.ZodObject<{
+                    type: z.ZodEnum<{
+                        TEXT: "TEXT";
+                        NUMBER: "NUMBER";
+                        PERCENT: "PERCENT";
+                        CURRENCY: "CURRENCY";
+                        DATE: "DATE";
+                        TIME: "TIME";
+                    }>;
+                    pattern: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+                borders: z.ZodOptional<z.ZodObject<{
+                    style: z.ZodEnum<{
+                        SOLID: "SOLID";
+                        DASHED: "DASHED";
+                        DOTTED: "DOTTED";
+                    }>;
+                    color: z.ZodObject<{
+                        red: z.ZodNumber;
+                        green: z.ZodNumber;
+                        blue: z.ZodNumber;
+                    }, z.core.$strip>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        readonly outputSchema: z.ZodObject<{
+            result: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"success">;
+                id: z.ZodString;
+                gid: z.ZodString;
+                sheetTitle: z.ZodString;
+                sheetUrl: z.ZodString;
+                successCount: z.ZodNumber;
+                failedRanges: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    range: z.ZodString;
+                    error: z.ZodString;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"auth_required">;
+                provider: z.ZodString;
+                message: z.ZodString;
+                url: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>], "type">;
+        }, z.core.$strip>;
+    };
+    handler: typeof handler;
+};
+export {};

package/dist/esm/mcp/tools/cells-format.js

@@ -0,0 +1,288 @@
+import { schemas } from '@mcp-z/oauth-google';
+const { AuthRequiredBranchSchema } = schemas;
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { SheetGidOutput, SheetGidSchema, SpreadsheetIdOutput, SpreadsheetIdSchema } from '../../schemas/index.js';
+import { parseA1Notation, rangeReferenceToGridRange } from '../../spreadsheet/range-operations.js';
+// RGB color schema (0-1 range for Google Sheets API)
+const ColorSchema = z.object({
+    red: z.number().min(0).max(1).describe('Red component (0-1)'),
+    green: z.number().min(0).max(1).describe('Green component (0-1)'),
+    blue: z.number().min(0).max(1).describe('Blue component (0-1)')
+});
+// Number format schema
+const NumberFormatSchema = z.object({
+    type: z.enum([
+        'TEXT',
+        'NUMBER',
+        'PERCENT',
+        'CURRENCY',
+        'DATE',
+        'TIME'
+    ]).describe('Number format type'),
+    pattern: z.string().optional().describe('Custom format pattern (e.g., "$#,##0.00" for currency)')
+});
+// Border schema
+const BorderSchema = z.object({
+    style: z.enum([
+        'SOLID',
+        'DASHED',
+        'DOTTED'
+    ]).describe('Border line style'),
+    color: ColorSchema.describe('Border color')
+});
+// Input schema for format requests
+const FormatRequestSchema = z.object({
+    range: z.string().min(1).describe('A1 notation range to format (e.g., "A1:D10", "B:B", "5:5")'),
+    backgroundColor: ColorSchema.optional().describe('Cell background color'),
+    textColor: ColorSchema.optional().describe('Text color'),
+    bold: z.boolean().optional().describe('Bold text'),
+    fontSize: z.number().int().min(6).max(36).optional().describe('Font size in points'),
+    horizontalAlignment: z.enum([
+        'LEFT',
+        'CENTER',
+        'RIGHT'
+    ]).optional().describe('Horizontal text alignment'),
+    numberFormat: NumberFormatSchema.optional().describe('Number format pattern'),
+    borders: BorderSchema.optional().describe('Cell borders')
+});
+const inputSchema = z.object({
+    id: SpreadsheetIdSchema,
+    gid: SheetGidSchema,
+    requests: z.array(FormatRequestSchema).min(1).max(50).describe('Array of formatting requests. Batch multiple ranges for efficiency.')
+});
+const successBranchSchema = z.object({
+    type: z.literal('success'),
+    id: SpreadsheetIdOutput,
+    gid: SheetGidOutput,
+    sheetTitle: z.string().describe('Title of the formatted sheet'),
+    sheetUrl: z.string().describe('URL of the formatted sheet'),
+    successCount: z.number().int().nonnegative().describe('Number of format requests successfully applied'),
+    failedRanges: z.array(z.object({
+        range: z.string().describe('A1 notation of range that failed'),
+        error: z.string().describe('Why formatting failed for this range')
+    })).optional().describe('Only populated if some ranges failed to format')
+});
+const outputSchema = z.discriminatedUnion('type', [
+    successBranchSchema,
+    AuthRequiredBranchSchema
+]);
+const config = {
+    description: 'Apply formatting (colors, borders, fonts, alignment, number formats) to cell ranges without modifying data. Supports batch operations for efficiency. Colors use 0-1 RGB format. Best for creating professional, visually organized spreadsheets.',
+    inputSchema,
+    outputSchema: z.object({
+        result: outputSchema
+    })
+};
+async function handler({ id, gid, requests }, extra) {
+    const logger = extra.logger;
+    logger.info('sheets.cells.format called', {
+        id,
+        gid,
+        requestCount: requests.length
+    });
+    try {
+        var _sheet_properties_title;
+        var _spreadsheetResponse_data_sheets;
+        const sheets = google.sheets({
+            version: 'v4',
+            auth: extra.authContext.auth
+        });
+        // Get spreadsheet and sheet info in single API call
+        const spreadsheetResponse = await sheets.spreadsheets.get({
+            spreadsheetId: id,
+            fields: 'sheets.properties.sheetId,sheets.properties.title'
+        });
+        // Find sheet by gid
+        const sheet = (_spreadsheetResponse_data_sheets = spreadsheetResponse.data.sheets) === null || _spreadsheetResponse_data_sheets === void 0 ? void 0 : _spreadsheetResponse_data_sheets.find((s)=>{
+            var _s_properties;
+            return String((_s_properties = s.properties) === null || _s_properties === void 0 ? void 0 : _s_properties.sheetId) === gid;
+        });
+        if (!(sheet === null || sheet === void 0 ? void 0 : sheet.properties)) {
+            logger.info('Sheet not found for format cells', {
+                id,
+                gid,
+                requestCount: requests.length
+            });
+            throw new McpError(ErrorCode.InvalidParams, `Sheet not found: ${gid}`);
+        }
+        const sheetTitle = (_sheet_properties_title = sheet.properties.title) !== null && _sheet_properties_title !== void 0 ? _sheet_properties_title : gid;
+        const sheetId = sheet.properties.sheetId;
+        const sheetUrl = `https://docs.google.com/spreadsheets/d/${id}/edit#gid=${sheetId}`;
+        // Build batch update requests
+        const batchRequests = [];
+        const failedRanges = [];
+        for (const request of requests){
+            try {
+                // Parse A1 notation to range reference
+                const rangeRef = parseA1Notation(request.range);
+                // Build grid range from range reference using helper function
+                const gridRange = rangeReferenceToGridRange(rangeRef, sheetId);
+                // Build cell format object
+                const cellFormat = {};
+                const fields = [];
+                // Background color
+                if (request.backgroundColor) {
+                    cellFormat.backgroundColor = request.backgroundColor;
+                    fields.push('backgroundColor');
+                }
+                // Text format
+                if (request.textColor || request.bold !== undefined || request.fontSize !== undefined) {
+                    cellFormat.textFormat = {};
+                    if (request.textColor) {
+                        cellFormat.textFormat.foregroundColor = request.textColor;
+                        fields.push('textFormat.foregroundColor');
+                    }
+                    if (request.bold !== undefined) {
+                        cellFormat.textFormat.bold = request.bold;
+                        fields.push('textFormat.bold');
+                    }
+                    if (request.fontSize !== undefined) {
+                        cellFormat.textFormat.fontSize = request.fontSize;
+                        fields.push('textFormat.fontSize');
+                    }
+                }
+                // Horizontal alignment
+                if (request.horizontalAlignment) {
+                    cellFormat.horizontalAlignment = request.horizontalAlignment;
+                    fields.push('horizontalAlignment');
+                }
+                // Number format
+                if (request.numberFormat) {
+                    const numberFormat = {
+                        type: request.numberFormat.type
+                    };
+                    if (request.numberFormat.pattern !== undefined) {
+                        numberFormat.pattern = request.numberFormat.pattern;
+                    }
+                    cellFormat.numberFormat = numberFormat;
+                    fields.push('numberFormat');
+                }
+                // Add repeatCell request for this range
+                if (fields.length > 0) {
+                    batchRequests.push({
+                        repeatCell: {
+                            range: gridRange,
+                            cell: {
+                                userEnteredFormat: cellFormat
+                            },
+                            fields: `userEnteredFormat(${fields.join(',')})`
+                        }
+                    });
+                }
+                // Add border formatting if specified
+                if (request.borders) {
+                    batchRequests.push({
+                        updateBorders: {
+                            range: gridRange,
+                            top: {
+                                style: request.borders.style,
+                                color: request.borders.color
+                            },
+                            bottom: {
+                                style: request.borders.style,
+                                color: request.borders.color
+                            },
+                            left: {
+                                style: request.borders.style,
+                                color: request.borders.color
+                            },
+                            right: {
+                                style: request.borders.style,
+                                color: request.borders.color
+                            }
+                        }
+                    });
+                }
+            } catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                logger.info('Failed to parse range for formatting', {
+                    range: request.range,
+                    error: message
+                });
+                failedRanges.push({
+                    range: request.range,
+                    error: `Failed to parse range: ${message}`
+                });
+            }
+        }
+        // Early return if all ranges failed
+        if (batchRequests.length === 0) {
+            const result = {
+                type: 'success',
+                id,
+                gid: String(sheetId),
+                sheetTitle,
+                sheetUrl,
+                successCount: 0,
+                failedRanges: failedRanges.length > 0 ? failedRanges : undefined
+            };
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result)
+                    }
+                ],
+                structuredContent: {
+                    result
+                }
+            };
+        }
+        logger.info('sheets.cells.format executing batch request', {
+            spreadsheetId: id,
+            sheetTitle,
+            batchRequestsCount: batchRequests.length
+        });
+        // Execute the batch update
+        await sheets.spreadsheets.batchUpdate({
+            spreadsheetId: id,
+            requestBody: {
+                requests: batchRequests
+            }
+        });
+        logger.info('sheets.cells.format completed successfully', {
+            successCount: requests.length - failedRanges.length,
+            failedCount: failedRanges.length
+        });
+        const result = {
+            type: 'success',
+            id,
+            gid: String(sheetId),
+            sheetTitle,
+            sheetUrl,
+            successCount: requests.length - failedRanges.length,
+            failedRanges: failedRanges.length > 0 ? failedRanges : undefined
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result)
+                }
+            ],
+            structuredContent: {
+                result
+            }
+        };
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error('Format cells operation failed', {
+            id,
+            gid,
+            requestCount: requests.length,
+            error: message
+        });
+        throw new McpError(ErrorCode.InternalError, `Error formatting cells: ${message}`, {
+            stack: error instanceof Error ? error.stack : undefined
+        });
+    }
+}
+export default function createTool() {
+    return {
+        name: 'cells-format',
+        config,
+        handler
+    };
+}