@mcp-z/mcp-sheets 1.0.0

package/dist/cjs/mcp/tools/chart-create.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/mcp/tools/chart-create.ts"],"sourcesContent":["import type { EnrichedExtra } from '@mcp-z/oauth-google';\nimport { schemas } from '@mcp-z/oauth-google';\n\nconst { AuthRequiredBranchSchema } = schemas;\n\nimport type { ToolModule } from '@mcp-z/server';\nimport type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';\nimport { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';\nimport { google, type sheets_v4 } from 'googleapis';\nimport { z } from 'zod';\nimport { SheetGidOutput, SheetGidSchema, SpreadsheetIdOutput, SpreadsheetIdSchema } from '../../schemas/index.js';\nimport { parseA1Notation, rangeReferenceToGridRange } from '../../spreadsheet/range-operations.js';\n\n// Input schema for chart position\nconst ChartPositionSchema = z.object({\n  anchorCell: z.string().min(1).describe('A1 notation cell where chart top-left anchors (e.g., \"F2\")'),\n  offsetX: z.number().int().default(0).describe('Horizontal pixel offset from anchor'),\n  offsetY: z.number().int().default(0).describe('Vertical pixel offset from anchor'),\n});\n\nconst inputSchema = z.object({\n  id: SpreadsheetIdSchema,\n  gid: SheetGidSchema,\n  chartType: z.enum(['PIE', 'BAR', 'COLUMN', 'LINE']).describe('Type of chart to create'),\n  dataRange: z.string().min(1).describe('A1 notation range containing chart data including headers (e.g., \"A1:C10\")'),\n  title: z.string().optional().describe('Chart title displayed at top'),\n  position: ChartPositionSchema,\n  legend: z.enum(['BOTTOM', 'RIGHT', 'TOP', 'LEFT', 'NONE']).default('BOTTOM').describe('Legend position'),\n  is3D: z.boolean().default(false).describe('Render as 3D chart (PIE only)'),\n});\n\n// Success branch schema\nconst successBranchSchema = z.object({\n  type: z.literal('success'),\n  id: SpreadsheetIdOutput,\n  gid: SheetGidOutput,\n  sheetTitle: z.string().describe('Title of the sheet containing the chart'),\n  sheetUrl: z.string().describe('URL of the sheet containing the chart'),\n  chartId: z.number().int().describe('Unique chart ID for future updates/deletion'),\n  anchorCell: z.string().describe('Where chart was anchored'),\n});\n\n// Output schema with auth_required support\nconst outputSchema = z.discriminatedUnion('type', [successBranchSchema, AuthRequiredBranchSchema]);\n\nconst config = {\n  description: 'Create charts (pie, bar, column, line) from spreadsheet data ranges. Charts anchor to specific cells with optional pixel offsets. Data range should include headers. PIE charts use 2 columns (labels, values). BAR/COLUMN/LINE charts use first row as headers. Best for visualizing spreadsheet data.',\n  inputSchema,\n  outputSchema: z.object({\n    result: outputSchema,\n  }),\n} as const;\n\nexport type Input = z.infer<typeof inputSchema>;\nexport type Output = z.infer<typeof outputSchema>;\n\n// Parse A1 notation anchor cell to row/column indices\nfunction parseAnchorCell(anchorCell: string): { rowIndex: number; columnIndex: number } {\n  // Simple A1 notation parser for single cells\n  const match = anchorCell.match(/^([A-Z]+)(\\d+)$/);\n  if (!match || !match[1] || !match[2]) {\n    throw new Error(`Invalid anchor cell format: ${anchorCell}`);\n  }\n\n  const colLetters = match[1];\n  const rowNumber = match[2];\n\n  // Convert column letters to index (A=0, B=1, ..., Z=25, AA=26, etc.)\n  let columnIndex = 0;\n  for (let i = 0; i < colLetters.length; i++) {\n    columnIndex = columnIndex * 26 + (colLetters.charCodeAt(i) - 65 + 1);\n  }\n  columnIndex--; // Convert to 0-based\n\n  // Convert row number to index (1-based to 0-based)\n  const rowIndex = Number.parseInt(rowNumber, 10) - 1;\n\n  return { rowIndex, columnIndex };\n}\n\nasync function handler({ id, gid, chartType, dataRange, title, position, legend = 'BOTTOM', is3D = false }: Input, extra: EnrichedExtra): Promise<CallToolResult> {\n  const logger = extra.logger;\n  logger.info('sheets.chart.create called', {\n    id,\n    gid,\n    chartType,\n    dataRange,\n    title,\n    position,\n    legend,\n    is3D,\n  });\n\n  try {\n    const sheets = google.sheets({ version: 'v4', auth: extra.authContext.auth });\n\n    // Get spreadsheet and sheet info in single API call\n    const spreadsheetResponse = await sheets.spreadsheets.get({\n      spreadsheetId: id,\n      fields: 'sheets.properties.sheetId,sheets.properties.title',\n    });\n\n    // Find sheet by gid\n    const sheet = spreadsheetResponse.data.sheets?.find((s) => String(s.properties?.sheetId) === gid);\n    if (!sheet?.properties) {\n      logger.info('Sheet not found for chart create', { id, gid, chartType });\n      throw new McpError(ErrorCode.InvalidParams, `Sheet not found: ${gid}`);\n    }\n\n    const sheetTitle = sheet.properties.title ?? gid;\n    const sheetId = sheet.properties.sheetId;\n    const sheetUrl = `https://docs.google.com/spreadsheets/d/${id}/edit#gid=${sheetId}`;\n\n    // Validate 3D only for PIE charts\n    // Note: Google Sheets API only supports 3D for PIE charts, not COLUMN/BAR/LINE\n    if (is3D && chartType !== 'PIE') {\n      logger.info('3D mode not supported for this chart type', {\n        chartType,\n        is3D,\n      });\n      throw new McpError(ErrorCode.InvalidParams, `3D mode is only supported for PIE charts, not ${chartType}`);\n    }\n\n    // Parse anchor cell to row/column indices\n    let anchorRowIndex: number;\n    let anchorColumnIndex: number;\n    try {\n      const anchorIndices = parseAnchorCell(position.anchorCell);\n      anchorRowIndex = anchorIndices.rowIndex;\n      anchorColumnIndex = anchorIndices.columnIndex;\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error);\n      logger.info('Failed to parse anchor cell', {\n        anchorCell: position.anchorCell,\n        error: message,\n      });\n      throw new McpError(ErrorCode.InvalidParams, `Failed to parse anchor cell: ${message}`);\n    }\n\n    // Parse data range to grid range\n    let dataGridRange: sheets_v4.Schema$GridRange;\n    try {\n      const rangeRef = parseA1Notation(dataRange);\n      dataGridRange = rangeReferenceToGridRange(rangeRef, sheetId);\n\n      // Validate that required properties are defined for chart creation\n      if (dataGridRange.startColumnIndex === undefined || dataGridRange.startColumnIndex === null) {\n        throw new Error('Data range must include column information');\n      }\n      if (dataGridRange.endColumnIndex === undefined || dataGridRange.endColumnIndex === null) {\n        throw new Error('Data range must include column information');\n      }\n      if (dataGridRange.startRowIndex === undefined || dataGridRange.startRowIndex === null) {\n        throw new Error('Data range must include row information');\n      }\n      if (dataGridRange.endRowIndex === undefined || dataGridRange.endRowIndex === null) {\n        throw new Error('Data range must include row information');\n      }\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error);\n      logger.info('Failed to parse data range', {\n        dataRange,\n        error: message,\n      });\n      throw new McpError(ErrorCode.InvalidParams, `Failed to parse data range: ${message}`);\n    }\n\n    // Extract validated properties with defined types\n    const dataStartRowIndex = dataGridRange.startRowIndex as number;\n    const dataEndRowIndex = dataGridRange.endRowIndex as number;\n    const dataStartColumnIndex = dataGridRange.startColumnIndex as number;\n    const dataEndColumnIndex = dataGridRange.endColumnIndex as number;\n    const dataSheetId = dataGridRange.sheetId ?? sheetId;\n\n    // Build chart spec with properly split domain and series ranges\n    let chartSpec: sheets_v4.Schema$ChartSpec;\n\n    logger.info('Building chart spec', {\n      chartType,\n      dataGridRange,\n      sheetId,\n    });\n\n    // Map legend position to API format (add _LEGEND suffix)\n    const legendPositionMap: Record<string, string> = {\n      BOTTOM: 'BOTTOM_LEGEND',\n      RIGHT: 'RIGHT_LEGEND',\n      TOP: 'TOP_LEGEND',\n      LEFT: 'LEFT_LEGEND',\n      NONE: 'NO_LEGEND',\n    };\n    const apiLegendPosition = legendPositionMap[legend] || 'BOTTOM_LEGEND';\n\n    if (chartType === 'PIE') {\n      // PIE charts use a separate pieChart property, not basicChart\n      const baseSheetId = dataSheetId;\n\n      const domainRange = {\n        sheetId: baseSheetId,\n        startRowIndex: dataStartRowIndex,\n        endRowIndex: dataEndRowIndex,\n        startColumnIndex: dataStartColumnIndex,\n        endColumnIndex: dataStartColumnIndex + 1, // First column only (labels)\n      };\n\n      const seriesRange = {\n        sheetId: baseSheetId,\n        startRowIndex: dataStartRowIndex,\n        endRowIndex: dataEndRowIndex,\n        startColumnIndex: dataStartColumnIndex + 1, // Second column (values)\n        endColumnIndex: dataStartColumnIndex + 2,\n      };\n\n      logger.info('PIE chart ranges', {\n        dataGridRange,\n        domainRange,\n        seriesRange,\n        apiLegendPosition,\n      });\n\n      chartSpec = {\n        pieChart: {\n          // Use pieChart for PIE charts\n          legendPosition: legend === 'NONE' ? 'NO_LEGEND' : apiLegendPosition,\n          domain: {\n            // Note: domain/series are direct objects, not arrays\n            sourceRange: {\n              sources: [domainRange],\n            },\n          },\n          series: {\n            sourceRange: {\n              sources: [seriesRange],\n            },\n          },\n          threeDimensional: is3D, // 3D is directly on pieChart\n        },\n      };\n      if (title) {\n        chartSpec.title = title;\n      }\n    } else {\n      // For BAR, COLUMN, LINE charts: domain is first column, each subsequent column is a series\n      const baseSheetId = dataSheetId;\n\n      const domainRange = {\n        sheetId: baseSheetId,\n        startRowIndex: dataStartRowIndex,\n        endRowIndex: dataEndRowIndex,\n        startColumnIndex: dataStartColumnIndex,\n        endColumnIndex: dataStartColumnIndex + 1, // First column only\n      };\n\n      // Calculate number of data columns (excluding the first domain column)\n      const numDataColumns = dataEndColumnIndex - dataStartColumnIndex - 1;\n      const series = [];\n\n      // Create a series for each data column\n      for (let i = 0; i < numDataColumns; i++) {\n        const seriesRange = {\n          sheetId: baseSheetId,\n          startRowIndex: dataStartRowIndex,\n          endRowIndex: dataEndRowIndex,\n          startColumnIndex: dataStartColumnIndex + 1 + i,\n          endColumnIndex: dataStartColumnIndex + 2 + i,\n        };\n\n        series.push({\n          series: {\n            sourceRange: {\n              sources: [seriesRange],\n            },\n          },\n        });\n      }\n\n      // If no data columns were found, default to using the entire range as a fallback\n      if (series.length === 0) {\n        series.push({\n          series: {\n            sourceRange: {\n              sources: [dataGridRange],\n            },\n          },\n        });\n      }\n\n      const basicChart: sheets_v4.Schema$BasicChartSpec = {\n        chartType, // BAR, COLUMN, LINE are valid for basicChart\n        headerCount: 1, // First row is headers\n        // Note: Google Sheets API does not support threeDimensional for basicChart (BAR/COLUMN/LINE)\n        // threeDimensional is only supported for pieChart\n        domains: [\n          {\n            domain: {\n              sourceRange: {\n                sources: [domainRange],\n              },\n            },\n          },\n        ],\n        series,\n      };\n      if (legend !== 'NONE') {\n        basicChart.legendPosition = apiLegendPosition;\n      }\n\n      chartSpec = { basicChart };\n      if (title) {\n        chartSpec.title = title;\n      }\n    }\n\n    // Build embedded object position\n    const embeddedObjectPosition = {\n      overlayPosition: {\n        anchorCell: {\n          sheetId,\n          rowIndex: anchorRowIndex,\n          columnIndex: anchorColumnIndex,\n        },\n        offsetXPixels: position.offsetX,\n        offsetYPixels: position.offsetY,\n      },\n    };\n\n    const requestBody = {\n      requests: [\n        {\n          addChart: {\n            chart: {\n              spec: chartSpec,\n              position: embeddedObjectPosition,\n            },\n          },\n        },\n      ],\n    };\n\n    logger.info('sheets.chart.create executing addChart request', {\n      spreadsheetId: id,\n      sheetTitle,\n      chartType,\n      dataRange,\n      anchorCell: position.anchorCell,\n      requestBody: JSON.stringify(requestBody),\n    });\n\n    // Execute the addChart request\n    const response = await sheets.spreadsheets.batchUpdate({\n      spreadsheetId: id,\n      requestBody,\n    });\n\n    // Extract chart ID from response\n    const replies = response.data.replies || [];\n    if (replies.length === 0 || !replies[0]?.addChart?.chart?.chartId) {\n      logger.error('Chart creation failed - no chart ID returned', {\n        spreadsheetId: id,\n        sheetTitle,\n        chartType,\n      });\n      throw new McpError(ErrorCode.InternalError, 'Chart creation failed: no chart ID returned from Google Sheets API');\n    }\n\n    const chartId = replies[0].addChart.chart.chartId;\n\n    logger.info('sheets.chart.create completed successfully', {\n      chartId,\n      chartType,\n      anchorCell: position.anchorCell,\n    });\n\n    const result: Output = {\n      type: 'success' as const,\n      id,\n      gid: String(sheetId),\n      sheetTitle,\n      sheetUrl,\n      chartId,\n      anchorCell: position.anchorCell,\n    };\n\n    return {\n      content: [{ type: 'text' as const, text: JSON.stringify(result) }],\n      structuredContent: { result },\n    };\n  } catch (e) {\n    const error = e as Error & { response?: { data?: unknown; status?: number } };\n    const message = error.message || String(e);\n    logger.error('Chart create operation failed', {\n      id,\n      gid,\n      chartType,\n      dataRange,\n      error: message,\n      response: error.response?.data,\n      status: error.response?.status,\n    });\n\n    throw new McpError(ErrorCode.InternalError, `Error creating chart: ${message}`, {\n      stack: e instanceof Error ? e.stack : undefined,\n    });\n  }\n}\n\nexport default function createTool() {\n  return {\n    name: 'chart-create',\n    config,\n    handler,\n  } satisfies ToolModule;\n}\n"],"names":["createTool","AuthRequiredBranchSchema","schemas","ChartPositionSchema","z","object","anchorCell","string","min","describe","offsetX","number","int","default","offsetY","inputSchema","id","SpreadsheetIdSchema","gid","SheetGidSchema","chartType","enum","dataRange","title","optional","position","legend","is3D","boolean","successBranchSchema","type","literal","SpreadsheetIdOutput","SheetGidOutput","sheetTitle","sheetUrl","chartId","outputSchema","discriminatedUnion","config","description","result","parseAnchorCell","match","Error","colLetters","rowNumber","columnIndex","i","length","charCodeAt","rowIndex","Number","parseInt","handler","extra","logger","sheet","dataGridRange","spreadsheetResponse","replies","sheets","sheetId","anchorRowIndex","anchorColumnIndex","anchorIndices","message","rangeRef","dataStartRowIndex","dataEndRowIndex","dataStartColumnIndex","dataEndColumnIndex","dataSheetId","chartSpec","legendPositionMap","apiLegendPosition","baseSheetId","domainRange","seriesRange","numDataColumns","series","basicChart","embeddedObjectPosition","requestBody","response","e","error","info","google","version","auth","authContext","spreadsheets","get","spreadsheetId","fields","data","find","s","String","properties","McpError","ErrorCode","InvalidParams","parseA1Notation","rangeReferenceToGridRange","startColumnIndex","undefined","endColumnIndex","startRowIndex","endRowIndex","BOTTOM","RIGHT","TOP","LEFT","NONE","pieChart","legendPosition","domain","sourceRange","sources","threeDimensional","push","headerCount","domains","overlayPosition","offsetXPixels","offsetYPixels","requests","addChart","chart","spec","JSON","stringify","batchUpdate","InternalError","content","text","structuredContent","status","stack","name"],"mappings":"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"}

package/dist/cjs/mcp/tools/columns-get.d.cts

@@ -0,0 +1,55 @@
+/** Get column names from Google Sheet (peek at first row only) */
+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>;
+    render: z.ZodOptional<z.ZodEnum<{
+        FORMATTED_VALUE: "FORMATTED_VALUE";
+        UNFORMATTED_VALUE: "UNFORMATTED_VALUE";
+        FORMULA: "FORMULA";
+    }>>;
+}, z.core.$strip>;
+declare const outputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"success">;
+    columns: z.ZodArray<z.ZodString>;
+    isEmpty: z.ZodBoolean;
+}, 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, render }: Input, extra: EnrichedExtra): Promise<CallToolResult>;
+export default function createTool(): {
+    name: string;
+    config: {
+        readonly description: "Get first row from Google Sheet. Returns columns array and isEmpty flag.";
+        readonly inputSchema: z.ZodObject<{
+            id: z.ZodString;
+            gid: z.ZodCoercedString<unknown>;
+            render: z.ZodOptional<z.ZodEnum<{
+                FORMATTED_VALUE: "FORMATTED_VALUE";
+                UNFORMATTED_VALUE: "UNFORMATTED_VALUE";
+                FORMULA: "FORMULA";
+            }>>;
+        }, z.core.$strip>;
+        readonly outputSchema: z.ZodObject<{
+            result: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"success">;
+                columns: z.ZodArray<z.ZodString>;
+                isEmpty: z.ZodBoolean;
+            }, 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/cjs/mcp/tools/columns-get.d.ts

@@ -0,0 +1,55 @@
+/** Get column names from Google Sheet (peek at first row only) */
+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>;
+    render: z.ZodOptional<z.ZodEnum<{
+        FORMATTED_VALUE: "FORMATTED_VALUE";
+        UNFORMATTED_VALUE: "UNFORMATTED_VALUE";
+        FORMULA: "FORMULA";
+    }>>;
+}, z.core.$strip>;
+declare const outputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"success">;
+    columns: z.ZodArray<z.ZodString>;
+    isEmpty: z.ZodBoolean;
+}, 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, render }: Input, extra: EnrichedExtra): Promise<CallToolResult>;
+export default function createTool(): {
+    name: string;
+    config: {
+        readonly description: "Get first row from Google Sheet. Returns columns array and isEmpty flag.";
+        readonly inputSchema: z.ZodObject<{
+            id: z.ZodString;
+            gid: z.ZodCoercedString<unknown>;
+            render: z.ZodOptional<z.ZodEnum<{
+                FORMATTED_VALUE: "FORMATTED_VALUE";
+                UNFORMATTED_VALUE: "UNFORMATTED_VALUE";
+                FORMULA: "FORMULA";
+            }>>;
+        }, z.core.$strip>;
+        readonly outputSchema: z.ZodObject<{
+            result: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"success">;
+                columns: z.ZodArray<z.ZodString>;
+                isEmpty: z.ZodBoolean;
+            }, 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/cjs/mcp/tools/columns-get.js

@@ -0,0 +1,289 @@
+/** Get column names from Google Sheet (peek at first row only) */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "default", {
+    enumerable: true,
+    get: function() {
+        return createTool;
+    }
+});
+var _oauthgoogle = require("@mcp-z/oauth-google");
+var _types = require("@modelcontextprotocol/sdk/types.js");
+var _googleapis = require("googleapis");
+var _zod = require("zod");
+var _index = require("../../schemas/index.js");
+function asyncGeneratorStep(gen, resolve, reject, _next, _throw, key, arg) {
+    try {
+        var info = gen[key](arg);
+        var value = info.value;
+    } catch (error) {
+        reject(error);
+        return;
+    }
+    if (info.done) {
+        resolve(value);
+    } else {
+        Promise.resolve(value).then(_next, _throw);
+    }
+}
+function _async_to_generator(fn) {
+    return function() {
+        var self = this, args = arguments;
+        return new Promise(function(resolve, reject) {
+            var gen = fn.apply(self, args);
+            function _next(value) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "next", value);
+            }
+            function _throw(err) {
+                asyncGeneratorStep(gen, resolve, reject, _next, _throw, "throw", err);
+            }
+            _next(undefined);
+        });
+    };
+}
+function _instanceof(left, right) {
+    if (right != null && typeof Symbol !== "undefined" && right[Symbol.hasInstance]) {
+        return !!right[Symbol.hasInstance](left);
+    } else {
+        return left instanceof right;
+    }
+}
+function _ts_generator(thisArg, body) {
+    var f, y, t, _ = {
+        label: 0,
+        sent: function() {
+            if (t[0] & 1) throw t[1];
+            return t[1];
+        },
+        trys: [],
+        ops: []
+    }, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype), d = Object.defineProperty;
+    return d(g, "next", {
+        value: verb(0)
+    }), d(g, "throw", {
+        value: verb(1)
+    }), d(g, "return", {
+        value: verb(2)
+    }), typeof Symbol === "function" && d(g, Symbol.iterator, {
+        value: function() {
+            return this;
+        }
+    }), g;
+    function verb(n) {
+        return function(v) {
+            return step([
+                n,
+                v
+            ]);
+        };
+    }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while(g && (g = 0, op[0] && (_ = 0)), _)try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [
+                op[0] & 2,
+                t.value
+            ];
+            switch(op[0]){
+                case 0:
+                case 1:
+                    t = op;
+                    break;
+                case 4:
+                    _.label++;
+                    return {
+                        value: op[1],
+                        done: false
+                    };
+                case 5:
+                    _.label++;
+                    y = op[1];
+                    op = [
+                        0
+                    ];
+                    continue;
+                case 7:
+                    op = _.ops.pop();
+                    _.trys.pop();
+                    continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) {
+                        _ = 0;
+                        continue;
+                    }
+                    if (op[0] === 3 && (!t || op[1] > t[0] && op[1] < t[3])) {
+                        _.label = op[1];
+                        break;
+                    }
+                    if (op[0] === 6 && _.label < t[1]) {
+                        _.label = t[1];
+                        t = op;
+                        break;
+                    }
+                    if (t && _.label < t[2]) {
+                        _.label = t[2];
+                        _.ops.push(op);
+                        break;
+                    }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop();
+                    continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) {
+            op = [
+                6,
+                e
+            ];
+            y = 0;
+        } finally{
+            f = t = 0;
+        }
+        if (op[0] & 5) throw op[1];
+        return {
+            value: op[0] ? op[1] : void 0,
+            done: true
+        };
+    }
+}
+var AuthRequiredBranchSchema = _oauthgoogle.schemas.AuthRequiredBranchSchema;
+var inputSchema = _zod.z.object({
+    id: _index.SpreadsheetIdSchema,
+    gid: _index.SheetGidSchema,
+    render: _zod.z.enum([
+        'FORMATTED_VALUE',
+        'UNFORMATTED_VALUE',
+        'FORMULA'
+    ]).optional().describe('How to render cell values. FORMATTED_VALUE (default): calculated with formatting. UNFORMATTED_VALUE: calculated without formatting. FORMULA: show formula text instead of result.')
+});
+// Success branch schema - uses columns: for consistency with standard vocabulary
+var successBranchSchema = _zod.z.object({
+    type: _zod.z.literal('success'),
+    columns: _zod.z.array(_zod.z.string()).describe('First row values (column names) or empty if no rows'),
+    isEmpty: _zod.z.boolean().describe('True if sheet has zero rows')
+});
+var outputSchema = _zod.z.discriminatedUnion('type', [
+    successBranchSchema,
+    AuthRequiredBranchSchema
+]);
+var config = {
+    description: 'Get first row from Google Sheet. Returns columns array and isEmpty flag.',
+    inputSchema: inputSchema,
+    outputSchema: _zod.z.object({
+        result: outputSchema
+    })
+};
+function handler(_0, _1) {
+    return _async_to_generator(function(param, extra) {
+        var id, gid, render, _logger_debug, logger, _sheet_properties_title, _spreadsheetResponse_data_sheets, _logger_info, sheets, spreadsheetResponse, sheet, sheetTitle, range, response, rows, isEmpty, firstRow, columns, result, error, _logger_error, message;
+        return _ts_generator(this, function(_state) {
+            switch(_state.label){
+                case 0:
+                    id = param.id, gid = param.gid, render = param.render;
+                    logger = extra.logger;
+                    (_logger_debug = logger.debug) === null || _logger_debug === void 0 ? void 0 : _logger_debug.call(logger, 'sheets.columns.get called', {
+                        id: id,
+                        gid: gid,
+                        render: render
+                    });
+                    _state.label = 1;
+                case 1:
+                    _state.trys.push([
+                        1,
+                        4,
+                        ,
+                        5
+                    ]);
+                    sheets = _googleapis.google.sheets({
+                        version: 'v4',
+                        auth: extra.authContext.auth
+                    });
+                    return [
+                        4,
+                        sheets.spreadsheets.get({
+                            spreadsheetId: id,
+                            fields: 'sheets.properties.sheetId,sheets.properties.title'
+                        })
+                    ];
+                case 2:
+                    spreadsheetResponse = _state.sent();
+                    // Find sheet by gid
+                    sheet = (_spreadsheetResponse_data_sheets = spreadsheetResponse.data.sheets) === null || _spreadsheetResponse_data_sheets === void 0 ? void 0 : _spreadsheetResponse_data_sheets.find(function(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)) {
+                        throw new _types.McpError(_types.ErrorCode.InvalidParams, "Sheet not found: ".concat(gid));
+                    }
+                    sheetTitle = (_sheet_properties_title = sheet.properties.title) !== null && _sheet_properties_title !== void 0 ? _sheet_properties_title : '';
+                    // Read first row only (A1:ZZZ1 should cover most reasonable sheets)
+                    range = "'".concat(sheetTitle, "'!A1:ZZZ1");
+                    return [
+                        4,
+                        sheets.spreadsheets.values.get({
+                            spreadsheetId: id,
+                            range: range,
+                            valueRenderOption: render || 'FORMATTED_VALUE'
+                        })
+                    ];
+                case 3:
+                    response = _state.sent();
+                    rows = response.data.values || [];
+                    isEmpty = rows.length === 0;
+                    // Extract first row and convert to strings (column names)
+                    firstRow = rows[0] || [];
+                    columns = firstRow.map(function(value) {
+                        return String(value !== null && value !== void 0 ? value : '');
+                    });
+                    result = {
+                        type: 'success',
+                        columns: columns,
+                        isEmpty: isEmpty
+                    };
+                    (_logger_info = logger.info) === null || _logger_info === void 0 ? void 0 : _logger_info.call(logger, 'sheets.columns.get completed', {
+                        id: id,
+                        gid: gid,
+                        columnCount: columns.length,
+                        isEmpty: isEmpty
+                    });
+                    return [
+                        2,
+                        {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify(result)
+                                }
+                            ],
+                            structuredContent: {
+                                result: result
+                            }
+                        }
+                    ];
+                case 4:
+                    error = _state.sent();
+                    message = _instanceof(error, Error) ? error.message : String(error);
+                    (_logger_error = logger.error) === null || _logger_error === void 0 ? void 0 : _logger_error.call(logger, 'sheets.columns.get error', {
+                        error: message
+                    });
+                    throw new _types.McpError(_types.ErrorCode.InternalError, "Error getting sheet columns: ".concat(message), {
+                        stack: _instanceof(error, Error) ? error.stack : undefined
+                    });
+                case 5:
+                    return [
+                        2
+                    ];
+            }
+        });
+    }).apply(this, arguments);
+}
+function createTool() {
+    return {
+        name: 'columns-get',
+        config: config,
+        handler: handler
+    };
+}
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/mcp/tools/columns-get.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/mcp/tools/columns-get.ts"],"sourcesContent":["/** Get column names from Google Sheet (peek at first row only) */\n\nimport type { EnrichedExtra } from '@mcp-z/oauth-google';\nimport { schemas } from '@mcp-z/oauth-google';\n\nconst { AuthRequiredBranchSchema } = schemas;\n\nimport type { ToolModule } from '@mcp-z/server';\nimport type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';\nimport { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';\nimport { google } from 'googleapis';\nimport { z } from 'zod';\nimport { SheetGidSchema, SpreadsheetIdSchema } from '../../schemas/index.js';\n\nconst inputSchema = z.object({\n  id: SpreadsheetIdSchema,\n  gid: SheetGidSchema,\n  render: z.enum(['FORMATTED_VALUE', 'UNFORMATTED_VALUE', 'FORMULA']).optional().describe('How to render cell values. FORMATTED_VALUE (default): calculated with formatting. UNFORMATTED_VALUE: calculated without formatting. FORMULA: show formula text instead of result.'),\n});\n\n// Success branch schema - uses columns: for consistency with standard vocabulary\nconst successBranchSchema = z.object({\n  type: z.literal('success'),\n  columns: z.array(z.string()).describe('First row values (column names) or empty if no rows'),\n  isEmpty: z.boolean().describe('True if sheet has zero rows'),\n});\n\nconst outputSchema = z.discriminatedUnion('type', [successBranchSchema, AuthRequiredBranchSchema]);\n\nconst config = {\n  description: 'Get first row from Google Sheet. Returns columns array and isEmpty flag.',\n  inputSchema,\n  outputSchema: z.object({\n    result: outputSchema,\n  }),\n} as const;\n\nexport type Input = z.infer<typeof inputSchema>;\nexport type Output = z.infer<typeof outputSchema>;\n\nasync function handler({ id, gid, render }: Input, extra: EnrichedExtra): Promise<CallToolResult> {\n  const logger = extra.logger;\n  logger.debug?.('sheets.columns.get called', { id, gid, render });\n\n  try {\n    const sheets = google.sheets({ version: 'v4', auth: extra.authContext.auth });\n\n    // Get spreadsheet and sheet info in single API call\n    const spreadsheetResponse = await sheets.spreadsheets.get({\n      spreadsheetId: id,\n      fields: 'sheets.properties.sheetId,sheets.properties.title',\n    });\n\n    // Find sheet by gid\n    const sheet = spreadsheetResponse.data.sheets?.find((s) => String(s.properties?.sheetId) === gid);\n    if (!sheet?.properties) {\n      throw new McpError(ErrorCode.InvalidParams, `Sheet not found: ${gid}`);\n    }\n\n    const sheetTitle = sheet.properties.title ?? '';\n\n    // Read first row only (A1:ZZZ1 should cover most reasonable sheets)\n    const range = `'${sheetTitle}'!A1:ZZZ1`;\n    const response = await sheets.spreadsheets.values.get({\n      spreadsheetId: id,\n      range,\n      valueRenderOption: render || 'FORMATTED_VALUE',\n    });\n\n    const rows = response.data.values || [];\n    const isEmpty = rows.length === 0;\n\n    // Extract first row and convert to strings (column names)\n    const firstRow = rows[0] || [];\n    const columns = firstRow.map((value) => String(value ?? ''));\n\n    const result: Output = {\n      type: 'success' as const,\n      columns,\n      isEmpty,\n    };\n\n    logger.info?.('sheets.columns.get completed', { id, gid, columnCount: columns.length, isEmpty });\n    return {\n      content: [{ type: 'text' as const, text: JSON.stringify(result) }],\n      structuredContent: { result },\n    };\n  } catch (error) {\n    const message = error instanceof Error ? error.message : String(error);\n    logger.error?.('sheets.columns.get error', { error: message });\n    throw new McpError(ErrorCode.InternalError, `Error getting sheet columns: ${message}`, {\n      stack: error instanceof Error ? error.stack : undefined,\n    });\n  }\n}\n\nexport default function createTool() {\n  return {\n    name: 'columns-get',\n    config,\n    handler,\n  } satisfies ToolModule;\n}\n"],"names":["createTool","AuthRequiredBranchSchema","schemas","inputSchema","z","object","id","SpreadsheetIdSchema","gid","SheetGidSchema","render","enum","optional","describe","successBranchSchema","type","literal","columns","array","string","isEmpty","boolean","outputSchema","discriminatedUnion","config","description","result","handler","extra","logger","sheet","spreadsheetResponse","sheets","sheetTitle","range","response","rows","firstRow","error","message","debug","google","version","auth","authContext","spreadsheets","get","spreadsheetId","fields","data","find","s","String","properties","sheetId","McpError","ErrorCode","InvalidParams","title","values","valueRenderOption","length","map","value","info","columnCount","content","text","JSON","stringify","structuredContent","Error","InternalError","stack","undefined","name"],"mappings":"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"}

package/dist/cjs/mcp/tools/columns-update.d.cts

@@ -0,0 +1,86 @@
+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>;
+    rows: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodLiteral<number>, z.ZodLiteral<number>, z.ZodBoolean, z.ZodNull]>>>;
+    headers: z.ZodArray<z.ZodString>;
+    updateBy: z.ZodArray<z.ZodString>;
+    behavior: z.ZodDefault<z.ZodEnum<{
+        "add-or-update": "add-or-update";
+        "update-only": "update-only";
+        "add-only": "add-only";
+    }>>;
+    valueInputOption: z.ZodDefault<z.ZodEnum<{
+        RAW: "RAW";
+        USER_ENTERED: "USER_ENTERED";
+    }>>;
+}, z.core.$strip>;
+declare const outputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"success">;
+    id: z.ZodString;
+    gid: z.ZodString;
+    spreadsheetTitle: z.ZodString;
+    spreadsheetUrl: z.ZodString;
+    sheetTitle: z.ZodString;
+    sheetUrl: z.ZodString;
+    updatedRows: z.ZodNumber;
+    insertedKeys: z.ZodArray<z.ZodString>;
+    rowsSkipped: z.ZodNumber;
+    headersAdded: z.ZodArray<z.ZodString>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, 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, rows, headers, updateBy, behavior, valueInputOption }: Input, extra: EnrichedExtra): Promise<CallToolResult>;
+export default function createTool(): {
+    name: string;
+    config: {
+        readonly description: "Update spreadsheet data by column headers with intelligent upsert logic. Supports adding missing columns, flexible update behaviors, and robust error handling. Uses column names as keys for matching existing rows, enabling context-aware data synchronization workflows.";
+        readonly inputSchema: z.ZodObject<{
+            id: z.ZodString;
+            gid: z.ZodCoercedString<unknown>;
+            rows: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodLiteral<number>, z.ZodLiteral<number>, z.ZodBoolean, z.ZodNull]>>>;
+            headers: z.ZodArray<z.ZodString>;
+            updateBy: z.ZodArray<z.ZodString>;
+            behavior: z.ZodDefault<z.ZodEnum<{
+                "add-or-update": "add-or-update";
+                "update-only": "update-only";
+                "add-only": "add-only";
+            }>>;
+            valueInputOption: z.ZodDefault<z.ZodEnum<{
+                RAW: "RAW";
+                USER_ENTERED: "USER_ENTERED";
+            }>>;
+        }, z.core.$strip>;
+        readonly outputSchema: z.ZodObject<{
+            result: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"success">;
+                id: z.ZodString;
+                gid: z.ZodString;
+                spreadsheetTitle: z.ZodString;
+                spreadsheetUrl: z.ZodString;
+                sheetTitle: z.ZodString;
+                sheetUrl: z.ZodString;
+                updatedRows: z.ZodNumber;
+                insertedKeys: z.ZodArray<z.ZodString>;
+                rowsSkipped: z.ZodNumber;
+                headersAdded: z.ZodArray<z.ZodString>;
+                errors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, 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/cjs/mcp/tools/columns-update.d.ts

@@ -0,0 +1,86 @@
+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>;
+    rows: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodLiteral<number>, z.ZodLiteral<number>, z.ZodBoolean, z.ZodNull]>>>;
+    headers: z.ZodArray<z.ZodString>;
+    updateBy: z.ZodArray<z.ZodString>;
+    behavior: z.ZodDefault<z.ZodEnum<{
+        "add-or-update": "add-or-update";
+        "update-only": "update-only";
+        "add-only": "add-only";
+    }>>;
+    valueInputOption: z.ZodDefault<z.ZodEnum<{
+        RAW: "RAW";
+        USER_ENTERED: "USER_ENTERED";
+    }>>;
+}, z.core.$strip>;
+declare const outputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"success">;
+    id: z.ZodString;
+    gid: z.ZodString;
+    spreadsheetTitle: z.ZodString;
+    spreadsheetUrl: z.ZodString;
+    sheetTitle: z.ZodString;
+    sheetUrl: z.ZodString;
+    updatedRows: z.ZodNumber;
+    insertedKeys: z.ZodArray<z.ZodString>;
+    rowsSkipped: z.ZodNumber;
+    headersAdded: z.ZodArray<z.ZodString>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, 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, rows, headers, updateBy, behavior, valueInputOption }: Input, extra: EnrichedExtra): Promise<CallToolResult>;
+export default function createTool(): {
+    name: string;
+    config: {
+        readonly description: "Update spreadsheet data by column headers with intelligent upsert logic. Supports adding missing columns, flexible update behaviors, and robust error handling. Uses column names as keys for matching existing rows, enabling context-aware data synchronization workflows.";
+        readonly inputSchema: z.ZodObject<{
+            id: z.ZodString;
+            gid: z.ZodCoercedString<unknown>;
+            rows: z.ZodArray<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodLiteral<number>, z.ZodLiteral<number>, z.ZodBoolean, z.ZodNull]>>>;
+            headers: z.ZodArray<z.ZodString>;
+            updateBy: z.ZodArray<z.ZodString>;
+            behavior: z.ZodDefault<z.ZodEnum<{
+                "add-or-update": "add-or-update";
+                "update-only": "update-only";
+                "add-only": "add-only";
+            }>>;
+            valueInputOption: z.ZodDefault<z.ZodEnum<{
+                RAW: "RAW";
+                USER_ENTERED: "USER_ENTERED";
+            }>>;
+        }, z.core.$strip>;
+        readonly outputSchema: z.ZodObject<{
+            result: z.ZodDiscriminatedUnion<[z.ZodObject<{
+                type: z.ZodLiteral<"success">;
+                id: z.ZodString;
+                gid: z.ZodString;
+                spreadsheetTitle: z.ZodString;
+                spreadsheetUrl: z.ZodString;
+                sheetTitle: z.ZodString;
+                sheetUrl: z.ZodString;
+                updatedRows: z.ZodNumber;
+                insertedKeys: z.ZodArray<z.ZodString>;
+                rowsSkipped: z.ZodNumber;
+                headersAdded: z.ZodArray<z.ZodString>;
+                errors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, 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 {};