@mcp-z/mcp-sheets 1.0.0

package/dist/esm/mcp/tools/rows-append.js

@@ -0,0 +1,151 @@
+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 { appendRows, mapRowsToHeader } from '../../spreadsheet/data-operations.js';
+import { ensureTabAndHeaders } from '../../spreadsheet/sheet-operations.js';
+const inputSchema = z.object({
+    id: SpreadsheetIdSchema,
+    gid: SheetGidSchema,
+    rows: z.array(z.array(z.union([
+        z.string(),
+        z.number(),
+        z.boolean(),
+        z.null()
+    ])).min(1)).min(1).describe('Array of rows, where each row is an array of cell values. Use null to skip a cell (preserve existing value), empty string "" to clear it.'),
+    headers: z.array(z.string()).optional().describe('Column order/names - used for blank sheets or column mapping'),
+    deduplicateBy: z.array(z.string()).optional().describe('Column names to use as composite key for deduplication')
+});
+const successBranchSchema = z.object({
+    type: z.literal('success'),
+    id: SpreadsheetIdOutput,
+    gid: SheetGidOutput,
+    sheetTitle: z.string().describe('Sheet tab name'),
+    updatedRows: z.number().describe('Number of rows appended'),
+    rowsSkipped: z.number().optional().describe('Number of duplicate rows skipped'),
+    sheetUrl: z.string().optional().describe('URL to view the sheet')
+});
+const outputSchema = z.discriminatedUnion('type', [
+    successBranchSchema,
+    AuthRequiredBranchSchema
+]);
+const config = {
+    description: 'Add new rows to the bottom of an existing sheet with smart header handling and optional deduplication. BEST FOR: Structured database operations where spreadsheet has headers defining schema and rows represent records.',
+    inputSchema,
+    outputSchema: z.object({
+        result: outputSchema
+    })
+};
+async function handler({ id, gid, rows, headers, deduplicateBy }, extra) {
+    const logger = extra.logger;
+    logger.info('sheets.rows.append called', {
+        id,
+        gid,
+        rowCount: rows.length,
+        headers,
+        deduplicateBy
+    });
+    try {
+        var _ref;
+        var _spreadsheetResponse_data_sheets, _sheet_properties;
+        const sheets = google.sheets({
+            version: 'v4',
+            auth: extra.authContext.auth
+        });
+        // Get sheet details using the gid
+        const spreadsheetResponse = await sheets.spreadsheets.get({
+            spreadsheetId: id,
+            fields: 'sheets.properties.sheetId,sheets.properties.title'
+        });
+        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) {
+            throw new McpError(ErrorCode.InvalidParams, 'Sheet not found');
+        }
+        const sheetTitle = (_ref = sheet === null || sheet === void 0 ? void 0 : (_sheet_properties = sheet.properties) === null || _sheet_properties === void 0 ? void 0 : _sheet_properties.title) !== null && _ref !== void 0 ? _ref : '';
+        // Smart header handling and data processing
+        let processedRows = rows;
+        let currentHeaders = [];
+        let rowsSkipped = 0;
+        let existingKeySet = new Set();
+        if (headers && headers.length > 0) {
+            // Use ensureTabAndHeaders to handle header logic
+            const headerResult = await ensureTabAndHeaders(sheets, {
+                spreadsheetId: id,
+                sheetTitle,
+                requiredHeader: headers,
+                keyColumns: deduplicateBy || [],
+                logger
+            });
+            currentHeaders = headerResult.header;
+            existingKeySet = headerResult.keySet;
+            // Map data rows to match current header order
+            processedRows = mapRowsToHeader({
+                rows,
+                header: currentHeaders,
+                canonical: headers
+            });
+        }
+        // Append rows with optional deduplication
+        // If headers are empty but deduplication is requested, skip deduplication for empty spreadsheets
+        const effectiveKeyColumns = currentHeaders.length === 0 && deduplicateBy && deduplicateBy.length > 0 ? [] : deduplicateBy || [];
+        const appendResult = await appendRows(sheets, {
+            spreadsheetId: id,
+            sheetTitle,
+            rows: processedRows,
+            keySet: existingKeySet,
+            keyColumns: effectiveKeyColumns,
+            header: currentHeaders,
+            logger
+        });
+        rowsSkipped = appendResult.rowsSkipped || 0;
+        // Only count data rows, not headers - headers are metadata, not items
+        const updatedRows = appendResult.updatedRows || 0;
+        const sheetUrl = `https://docs.google.com/spreadsheets/d/${id}/edit#gid=${gid}`;
+        logger.info('sheets.rows.append completed', {
+            id,
+            gid,
+            updatedRows,
+            rowsSkipped
+        });
+        const result = {
+            type: 'success',
+            id,
+            gid,
+            sheetTitle,
+            updatedRows,
+            rowsSkipped,
+            sheetUrl
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result)
+                }
+            ],
+            structuredContent: {
+                result
+            }
+        };
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error('sheets.rows.append error', {
+            error: message
+        });
+        throw new McpError(ErrorCode.InternalError, `Error appending rows: ${message}`, {
+            stack: error instanceof Error ? error.stack : undefined
+        });
+    }
+}
+export default function createTool() {
+    return {
+        name: 'rows-append',
+        config,
+        handler
+    };
+}

package/dist/esm/mcp/tools/rows-append.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/mcp/tools/rows-append.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 } from 'googleapis';\nimport { z } from 'zod';\nimport { SheetGidOutput, SheetGidSchema, SpreadsheetIdOutput, SpreadsheetIdSchema } from '../../schemas/index.js';\nimport { appendRows, mapRowsToHeader } from '../../spreadsheet/data-operations.js';\nimport { ensureTabAndHeaders } from '../../spreadsheet/sheet-operations.js';\n\nconst inputSchema = z.object({\n  id: SpreadsheetIdSchema,\n  gid: SheetGidSchema,\n  rows: z\n    .array(z.array(z.union([z.string(), z.number(), z.boolean(), z.null()])).min(1))\n    .min(1)\n    .describe('Array of rows, where each row is an array of cell values. Use null to skip a cell (preserve existing value), empty string \"\" to clear it.'),\n  headers: z.array(z.string()).optional().describe('Column order/names - used for blank sheets or column mapping'),\n  deduplicateBy: z.array(z.string()).optional().describe('Column names to use as composite key for deduplication'),\n});\n\nconst successBranchSchema = z.object({\n  type: z.literal('success'),\n  id: SpreadsheetIdOutput,\n  gid: SheetGidOutput,\n  sheetTitle: z.string().describe('Sheet tab name'),\n  updatedRows: z.number().describe('Number of rows appended'),\n  rowsSkipped: z.number().optional().describe('Number of duplicate rows skipped'),\n  sheetUrl: z.string().optional().describe('URL to view the sheet'),\n});\n\nconst outputSchema = z.discriminatedUnion('type', [successBranchSchema, AuthRequiredBranchSchema]);\n\nconst config = {\n  description: 'Add new rows to the bottom of an existing sheet with smart header handling and optional deduplication. BEST FOR: Structured database operations where spreadsheet has headers defining schema and rows represent records.',\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, rows, headers, deduplicateBy }: Input, extra: EnrichedExtra): Promise<CallToolResult> {\n  const logger = extra.logger;\n  logger.info('sheets.rows.append called', { id, gid, rowCount: rows.length, headers, deduplicateBy });\n\n  try {\n    const sheets = google.sheets({ version: 'v4', auth: extra.authContext.auth });\n\n    // Get sheet details using the gid\n    const spreadsheetResponse = await sheets.spreadsheets.get({\n      spreadsheetId: id,\n      fields: 'sheets.properties.sheetId,sheets.properties.title',\n    });\n\n    const sheet = spreadsheetResponse.data.sheets?.find((s) => String(s.properties?.sheetId) === gid);\n\n    if (!sheet) {\n      throw new McpError(ErrorCode.InvalidParams, 'Sheet not found');\n    }\n\n    const sheetTitle = sheet?.properties?.title ?? '';\n\n    // Smart header handling and data processing\n    let processedRows = rows;\n    let currentHeaders: string[] = [];\n    let rowsSkipped = 0;\n    let existingKeySet: Set<string> = new Set();\n\n    if (headers && headers.length > 0) {\n      // Use ensureTabAndHeaders to handle header logic\n      const headerResult = await ensureTabAndHeaders(sheets, {\n        spreadsheetId: id,\n        sheetTitle,\n        requiredHeader: headers,\n        keyColumns: deduplicateBy || [],\n        logger,\n      });\n\n      currentHeaders = headerResult.header;\n      existingKeySet = headerResult.keySet;\n\n      // Map data rows to match current header order\n      processedRows = mapRowsToHeader({ rows, header: currentHeaders, canonical: headers }) as (string | number | boolean | null)[][];\n    }\n\n    // Append rows with optional deduplication\n    // If headers are empty but deduplication is requested, skip deduplication for empty spreadsheets\n    const effectiveKeyColumns = currentHeaders.length === 0 && deduplicateBy && deduplicateBy.length > 0 ? [] : deduplicateBy || [];\n\n    const appendResult = await appendRows(sheets, {\n      spreadsheetId: id,\n      sheetTitle,\n      rows: processedRows,\n      keySet: existingKeySet,\n      keyColumns: effectiveKeyColumns,\n      header: currentHeaders,\n      logger,\n    });\n\n    rowsSkipped = appendResult.rowsSkipped || 0;\n    // Only count data rows, not headers - headers are metadata, not items\n    const updatedRows = appendResult.updatedRows || 0;\n\n    const sheetUrl = `https://docs.google.com/spreadsheets/d/${id}/edit#gid=${gid}`;\n\n    logger.info('sheets.rows.append completed', { id, gid, updatedRows, rowsSkipped });\n\n    const result: Output = {\n      type: 'success' as const,\n      id,\n      gid,\n      sheetTitle,\n      updatedRows,\n      rowsSkipped, // Always include rowsSkipped, even when 0\n      sheetUrl,\n    };\n\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.rows.append error', { error: message });\n\n    throw new McpError(ErrorCode.InternalError, `Error appending rows: ${message}`, {\n      stack: error instanceof Error ? error.stack : undefined,\n    });\n  }\n}\n\nexport default function createTool() {\n  return {\n    name: 'rows-append',\n    config,\n    handler,\n  } satisfies ToolModule;\n}\n"],"names":["schemas","AuthRequiredBranchSchema","ErrorCode","McpError","google","z","SheetGidOutput","SheetGidSchema","SpreadsheetIdOutput","SpreadsheetIdSchema","appendRows","mapRowsToHeader","ensureTabAndHeaders","inputSchema","object","id","gid","rows","array","union","string","number","boolean","null","min","describe","headers","optional","deduplicateBy","successBranchSchema","type","literal","sheetTitle","updatedRows","rowsSkipped","sheetUrl","outputSchema","discriminatedUnion","config","description","result","handler","extra","logger","info","rowCount","length","spreadsheetResponse","sheet","sheets","version","auth","authContext","spreadsheets","get","spreadsheetId","fields","data","find","s","String","properties","sheetId","InvalidParams","title","processedRows","currentHeaders","existingKeySet","Set","headerResult","requiredHeader","keyColumns","header","keySet","canonical","effectiveKeyColumns","appendResult","content","text","JSON","stringify","structuredContent","error","message","Error","InternalError","stack","undefined","createTool","name"],"mappings":"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"}

package/dist/esm/mcp/tools/rows-csv-append.d.ts

@@ -0,0 +1,67 @@
+/** Import CSV data to Google Sheets with database-style row append and deduplication */
+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>;
+    sourceUri: z.ZodString;
+    sourceHasHeaders: z.ZodDefault<z.ZodBoolean>;
+    headerMap: z.ZodArray<z.ZodObject<{
+        source: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+        target: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    }, z.core.$strip>>;
+    deduplicateBy: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+}, z.core.$strip>;
+declare const outputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"success">;
+    id: z.ZodString;
+    gid: z.ZodString;
+    sheetTitle: z.ZodString;
+    updatedRows: z.ZodNumber;
+    rowsSkipped: z.ZodOptional<z.ZodNumber>;
+    sheetUrl: z.ZodOptional<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, sourceUri, sourceHasHeaders, headerMap, deduplicateBy }: Input, extra: EnrichedExtra): Promise<CallToolResult>;
+export default function createTool(): {
+    name: string;
+    config: {
+        readonly description: "Import CSV to Google Sheets with column mapping and optional deduplication. Streams data for large files.";
+        readonly inputSchema: z.ZodObject<{
+            id: z.ZodString;
+            gid: z.ZodCoercedString<unknown>;
+            sourceUri: z.ZodString;
+            sourceHasHeaders: z.ZodDefault<z.ZodBoolean>;
+            headerMap: z.ZodArray<z.ZodObject<{
+                source: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+                target: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+            }, z.core.$strip>>;
+            deduplicateBy: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        }, 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;
+                updatedRows: z.ZodNumber;
+                rowsSkipped: z.ZodOptional<z.ZodNumber>;
+                sheetUrl: z.ZodOptional<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/esm/mcp/tools/rows-csv-append.js

@@ -0,0 +1,342 @@
+/** Import CSV data to Google Sheets with database-style row append and deduplication */ import { schemas } from '@mcp-z/oauth-google';
+const { AuthRequiredBranchSchema } = schemas;
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { parse } from 'csv-parse';
+import { google } from 'googleapis';
+import { z } from 'zod';
+import { SheetGidOutput, SheetGidSchema, SpreadsheetIdOutput, SpreadsheetIdSchema } from '../../schemas/index.js';
+import { getCsvReadStream } from '../../spreadsheet/csv-streaming.js';
+import { buildDeduplicationKey } from '../../spreadsheet/deduplication-utils.js';
+import { ensureTabAndHeaders } from '../../spreadsheet/sheet-operations.js';
+// Header mapping schema: source/target can be string (name) or number (0-based index)
+const HeaderMapItemSchema = z.object({
+    source: z.union([
+        z.string(),
+        z.number().int().min(0)
+    ]).describe('CSV column: header name (string) or 0-based index (number)'),
+    target: z.union([
+        z.string(),
+        z.number().int().min(0)
+    ]).describe('Sheet column: header name (string) or 0-based index (number)')
+});
+const inputSchema = z.object({
+    id: SpreadsheetIdSchema,
+    gid: SheetGidSchema,
+    sourceUri: z.string().trim().min(1).describe('CSV file URI (file://, http://, https://)'),
+    sourceHasHeaders: z.boolean().default(true).describe('Source has header row for column name mapping. Set to false for data-only sources (numeric indices required).'),
+    headerMap: z.array(HeaderMapItemSchema).describe('Column mappings from CSV to sheet'),
+    deduplicateBy: z.array(z.union([
+        z.string(),
+        z.number().int().min(0)
+    ])).optional().describe('Sheet columns for deduplication (names or indices)')
+});
+const successBranchSchema = z.object({
+    type: z.literal('success'),
+    id: SpreadsheetIdOutput,
+    gid: SheetGidOutput,
+    sheetTitle: z.string().describe('Sheet tab name'),
+    updatedRows: z.number().describe('Number of rows appended'),
+    rowsSkipped: z.number().optional().describe('Number of duplicate rows skipped'),
+    sheetUrl: z.string().optional().describe('URL to view the sheet')
+});
+const outputSchema = z.discriminatedUnion('type', [
+    successBranchSchema,
+    AuthRequiredBranchSchema
+]);
+const config = {
+    description: 'Import CSV to Google Sheets with column mapping and optional deduplication. Streams data for large files.',
+    inputSchema,
+    outputSchema: z.object({
+        result: outputSchema
+    })
+};
+/** Batch size for Sheets API calls (1000 rows × 12 cols = 12K cells, well under 40K limit) */ const BATCH_SIZE = 1000;
+/**
+ * Resolve column reference to numeric index
+ * @param ref Column reference (string name or number index)
+ * @param headers Header row (null when sourceHasHeaders=false)
+ * @param sourceHasHeaders Whether headers are present
+ * @returns 0-based column index
+ */ function resolveColumnReference(ref, headers, sourceHasHeaders, context) {
+    // If number, use directly as 0-based index
+    if (typeof ref === 'number') {
+        if (ref < 0) {
+            throw new Error(`${context}: Column index must be >= 0, got ${ref}`);
+        }
+        return ref;
+    }
+    // If string, must be header name
+    if (!sourceHasHeaders || !headers) {
+        throw new Error(`${context}: String column reference "${ref}" requires sourceHasHeaders=true. Use numeric index when sourceHasHeaders=false.`);
+    }
+    const index = headers.indexOf(ref);
+    if (index === -1) {
+        throw new Error(`${context}: Header "${ref}" not found in [${headers.join(', ')}]`);
+    }
+    return index;
+}
+async function handler({ id, gid, sourceUri, sourceHasHeaders, headerMap, deduplicateBy }, extra) {
+    const logger = extra.logger;
+    logger.info('sheets.rows.csv-append called', {
+        id,
+        gid,
+        sourceUri,
+        sourceHasHeaders,
+        headerMap,
+        deduplicateBy
+    });
+    try {
+        var _ref;
+        var _spreadsheetResponse_data_sheets, _sheet_properties;
+        if (headerMap.length === 0) {
+            throw new McpError(ErrorCode.InvalidParams, 'headerMap cannot be empty');
+        }
+        // Validate: if sourceHasHeaders=false, all references must be numeric
+        if (!sourceHasHeaders) {
+            for (const { source, target } of headerMap){
+                if (typeof source === 'string') {
+                    throw new McpError(ErrorCode.InvalidParams, `sourceHasHeaders=false requires numeric indices. Got string source: "${source}"`);
+                }
+                if (typeof target === 'string') {
+                    throw new McpError(ErrorCode.InvalidParams, `sourceHasHeaders=false requires numeric indices. Got string target: "${target}"`);
+                }
+            }
+            if (deduplicateBy) {
+                for (const colRef of deduplicateBy){
+                    if (typeof colRef === 'string') {
+                        throw new McpError(ErrorCode.InvalidParams, `sourceHasHeaders=false requires numeric indices in deduplicateBy. Got string: "${colRef}"`);
+                    }
+                }
+            }
+        }
+        const sheets = google.sheets({
+            version: 'v4',
+            auth: extra.authContext.auth
+        });
+        // Get sheet details using the gid
+        const spreadsheetResponse = await sheets.spreadsheets.get({
+            spreadsheetId: id,
+            fields: 'sheets.properties.sheetId,sheets.properties.title'
+        });
+        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) {
+            throw new McpError(ErrorCode.InvalidParams, 'Sheet not found');
+        }
+        const sheetTitle = (_ref = sheet === null || sheet === void 0 ? void 0 : (_sheet_properties = sheet.properties) === null || _sheet_properties === void 0 ? void 0 : _sheet_properties.title) !== null && _ref !== void 0 ? _ref : '';
+        // Determine target headers (for sourceHasHeaders=true) or column count (for sourceHasHeaders=false)
+        let sheetHeaders = null;
+        let existingKeySet = new Set();
+        const keyColumns = deduplicateBy || [];
+        if (sourceHasHeaders) {
+            // Extract target header names from headerMap
+            const targetHeaderNames = headerMap.map(({ target })=>target).filter((t)=>typeof t === 'string');
+            // Use ensureTabAndHeaders to setup headers and fetch existing keys
+            const headerResult = await ensureTabAndHeaders(sheets, {
+                spreadsheetId: id,
+                sheetTitle,
+                requiredHeader: targetHeaderNames.length > 0 ? targetHeaderNames : null,
+                keyColumns: keyColumns.filter((k)=>typeof k === 'string'),
+                logger
+            });
+            sheetHeaders = headerResult.header;
+            existingKeySet = headerResult.keySet;
+        } else {
+            // sourceHasHeaders=false: Read existing data for deduplication (if needed)
+            if (deduplicateBy && deduplicateBy.length > 0) {
+                // Read data in chunks for memory efficiency with large sheets
+                const CHUNK_SIZE = 1000;
+                let startRow = 1;
+                let hasMore = true;
+                while(hasMore){
+                    const endRow = startRow + CHUNK_SIZE - 1;
+                    const chunkRange = `${sheetTitle}!A${startRow}:ZZZ${endRow}`;
+                    const response = await sheets.spreadsheets.values.get({
+                        spreadsheetId: id,
+                        range: chunkRange
+                    });
+                    const rows = response.data.values || [];
+                    for (const row of rows){
+                        const key = buildDeduplicationKey(row, keyColumns, null, false);
+                        if (key.replace(/::/g, '') !== '') {
+                            existingKeySet.add(key);
+                        }
+                    }
+                    // Check if there are more rows to read
+                    if (rows.length < CHUNK_SIZE) {
+                        hasMore = false;
+                    } else {
+                        startRow += CHUNK_SIZE;
+                    }
+                }
+                logger.info('sheets.rows.csv-append existing keys loaded', {
+                    keyCount: existingKeySet.size
+                });
+            }
+        }
+        // Streaming CSV processing state
+        let sourceHeaders = null;
+        let batch = [];
+        let totalRows = 0;
+        let rowsSkipped = 0;
+        // Get readable stream from CSV URI (no temp files!)
+        const readStream = await getCsvReadStream(sourceUri);
+        // Create CSV parser
+        const parser = readStream.pipe(parse({
+            columns: !!sourceHasHeaders,
+            skip_empty_lines: true,
+            trim: true,
+            cast: true,
+            relax_column_count: true
+        }));
+        // Helper to append batch to Sheets
+        const appendBatch = async (rows)=>{
+            if (rows.length === 0) return;
+            await sheets.spreadsheets.values.append({
+                spreadsheetId: id,
+                range: `${sheetTitle}!A:A`,
+                valueInputOption: 'USER_ENTERED',
+                requestBody: {
+                    values: rows,
+                    majorDimension: 'ROWS'
+                }
+            });
+            logger.info('sheets.rows.csv-append batch appended', {
+                batchSize: rows.length,
+                totalRows
+            });
+        };
+        // Resolve headerMap to numeric indices (do this after extracting CSV headers)
+        let resolvedMap = [];
+        // Stream and process records
+        for await (const record of parser){
+            if (sourceHasHeaders) {
+                // Extract source headers from first record
+                if (sourceHeaders === null) {
+                    sourceHeaders = Object.keys(record);
+                    logger.info('sheets.rows.csv-append source headers', {
+                        sourceHeaders
+                    });
+                    // Resolve headerMap now that we have both source and sheet headers
+                    resolvedMap = headerMap.map(({ source, target })=>({
+                            sourceIdx: resolveColumnReference(source, sourceHeaders, sourceHasHeaders, 'headerMap.source'),
+                            targetIdx: resolveColumnReference(target, sheetHeaders, sourceHasHeaders, 'headerMap.target')
+                        }));
+                }
+                // Map source record to sheet row
+                const sourceRow = sourceHeaders === null || sourceHeaders === void 0 ? void 0 : sourceHeaders.map((h)=>{
+                    var _record_h;
+                    return (_record_h = record[h]) !== null && _record_h !== void 0 ? _record_h : null;
+                });
+                const maxTargetIdx = Math.max(...resolvedMap.map((m)=>m.targetIdx));
+                const sheetRow = new Array(maxTargetIdx + 1).fill(null);
+                for (const { sourceIdx, targetIdx } of resolvedMap){
+                    if (sourceRow) {
+                        var _sourceRow_sourceIdx;
+                        sheetRow[targetIdx] = (_sourceRow_sourceIdx = sourceRow[sourceIdx]) !== null && _sourceRow_sourceIdx !== void 0 ? _sourceRow_sourceIdx : null;
+                    }
+                }
+                // Check deduplication
+                if (deduplicateBy && deduplicateBy.length > 0) {
+                    const key = buildDeduplicationKey(sheetRow, keyColumns, sheetHeaders, sourceHasHeaders);
+                    if (existingKeySet.has(key)) {
+                        rowsSkipped++;
+                        continue; // Skip duplicate
+                    }
+                    existingKeySet.add(key); // Add to set for future deduplication
+                }
+                // Add to batch
+                batch.push(sheetRow);
+                totalRows++;
+            } else {
+                // sourceHasHeaders=false: record is an array (not an object)
+                // Resolve map on first row
+                if (resolvedMap.length === 0) {
+                    resolvedMap = headerMap.map(({ source, target })=>({
+                            sourceIdx: resolveColumnReference(source, null, sourceHasHeaders, 'headerMap.source'),
+                            targetIdx: resolveColumnReference(target, null, sourceHasHeaders, 'headerMap.target')
+                        }));
+                }
+                const sourceRow = record;
+                const maxTargetIdx = Math.max(...resolvedMap.map((m)=>m.targetIdx));
+                const sheetRow = new Array(maxTargetIdx + 1).fill(null);
+                for (const { sourceIdx, targetIdx } of resolvedMap){
+                    if (sourceIdx < sourceRow.length) {
+                        var _sourceRow_sourceIdx1;
+                        sheetRow[targetIdx] = (_sourceRow_sourceIdx1 = sourceRow[sourceIdx]) !== null && _sourceRow_sourceIdx1 !== void 0 ? _sourceRow_sourceIdx1 : null;
+                    }
+                }
+                // Check deduplication
+                if (deduplicateBy && deduplicateBy.length > 0) {
+                    const key = buildDeduplicationKey(sheetRow, keyColumns, null, sourceHasHeaders);
+                    if (existingKeySet.has(key)) {
+                        rowsSkipped++;
+                        continue; // Skip duplicate
+                    }
+                    existingKeySet.add(key);
+                }
+                // Add to batch
+                batch.push(sheetRow);
+                totalRows++;
+            }
+            // Append batch when full
+            if (batch.length >= BATCH_SIZE) {
+                await appendBatch(batch);
+                batch = []; // Clear batch
+            }
+        }
+        // Flush remaining rows
+        if (batch.length > 0) {
+            await appendBatch(batch);
+        }
+        logger.info('sheets.rows.csv-append streaming complete', {
+            totalRows,
+            rowsSkipped
+        });
+        const updatedRows = totalRows;
+        logger.info('sheets.rows.csv-append completed', {
+            id,
+            gid,
+            updatedRows,
+            rowsSkipped,
+            sourceUri
+        });
+        const result = {
+            type: 'success',
+            id,
+            gid,
+            sheetTitle,
+            updatedRows,
+            rowsSkipped,
+            sheetUrl: `https://docs.google.com/spreadsheets/d/${id}/edit#gid=${gid}`
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result)
+                }
+            ],
+            structuredContent: {
+                result
+            }
+        };
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error('sheets.rows.csv-append error', {
+            error: message
+        });
+        throw new McpError(ErrorCode.InternalError, `Error appending CSV rows: ${message}`, {
+            stack: error instanceof Error ? error.stack : undefined
+        });
+    }
+}
+export default function createTool() {
+    return {
+        name: 'rows-csv-append',
+        config,
+        handler
+    };
+}

package/dist/esm/mcp/tools/rows-csv-append.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/mcp/tools/rows-csv-append.ts"],"sourcesContent":["/** Import CSV data to Google Sheets with database-style row append and deduplication */\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 { parse } from 'csv-parse';\nimport { google } from 'googleapis';\nimport { z } from 'zod';\nimport { SheetGidOutput, SheetGidSchema, SpreadsheetIdOutput, SpreadsheetIdSchema } from '../../schemas/index.js';\nimport { getCsvReadStream } from '../../spreadsheet/csv-streaming.js';\nimport { buildDeduplicationKey } from '../../spreadsheet/deduplication-utils.js';\nimport { ensureTabAndHeaders } from '../../spreadsheet/sheet-operations.js';\n\n// Header mapping schema: source/target can be string (name) or number (0-based index)\nconst HeaderMapItemSchema = z.object({\n  source: z.union([z.string(), z.number().int().min(0)]).describe('CSV column: header name (string) or 0-based index (number)'),\n  target: z.union([z.string(), z.number().int().min(0)]).describe('Sheet column: header name (string) or 0-based index (number)'),\n});\n\nconst inputSchema = z.object({\n  id: SpreadsheetIdSchema,\n  gid: SheetGidSchema,\n  sourceUri: z.string().trim().min(1).describe('CSV file URI (file://, http://, https://)'),\n  sourceHasHeaders: z.boolean().default(true).describe('Source has header row for column name mapping. Set to false for data-only sources (numeric indices required).'),\n  headerMap: z.array(HeaderMapItemSchema).describe('Column mappings from CSV to sheet'),\n  deduplicateBy: z\n    .array(z.union([z.string(), z.number().int().min(0)]))\n    .optional()\n    .describe('Sheet columns for deduplication (names or indices)'),\n});\n\nconst successBranchSchema = z.object({\n  type: z.literal('success'),\n  id: SpreadsheetIdOutput,\n  gid: SheetGidOutput,\n  sheetTitle: z.string().describe('Sheet tab name'),\n  updatedRows: z.number().describe('Number of rows appended'),\n  rowsSkipped: z.number().optional().describe('Number of duplicate rows skipped'),\n  sheetUrl: z.string().optional().describe('URL to view the sheet'),\n});\n\nconst outputSchema = z.discriminatedUnion('type', [successBranchSchema, AuthRequiredBranchSchema]);\n\nconst config = {\n  description: 'Import CSV to Google Sheets with column mapping and optional deduplication. Streams data for large files.',\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/** Batch size for Sheets API calls (1000 rows × 12 cols = 12K cells, well under 40K limit) */\nconst BATCH_SIZE = 1000;\n\n/**\n * Resolve column reference to numeric index\n * @param ref Column reference (string name or number index)\n * @param headers Header row (null when sourceHasHeaders=false)\n * @param sourceHasHeaders Whether headers are present\n * @returns 0-based column index\n */\nfunction resolveColumnReference(ref: string | number, headers: string[] | null, sourceHasHeaders: boolean, context: string): number {\n  // If number, use directly as 0-based index\n  if (typeof ref === 'number') {\n    if (ref < 0) {\n      throw new Error(`${context}: Column index must be >= 0, got ${ref}`);\n    }\n    return ref;\n  }\n\n  // If string, must be header name\n  if (!sourceHasHeaders || !headers) {\n    throw new Error(`${context}: String column reference \"${ref}\" requires sourceHasHeaders=true. Use numeric index when sourceHasHeaders=false.`);\n  }\n\n  const index = headers.indexOf(ref);\n  if (index === -1) {\n    throw new Error(`${context}: Header \"${ref}\" not found in [${headers.join(', ')}]`);\n  }\n\n  return index;\n}\n\nasync function handler({ id, gid, sourceUri, sourceHasHeaders, headerMap, deduplicateBy }: Input, extra: EnrichedExtra): Promise<CallToolResult> {\n  const logger = extra.logger;\n  logger.info('sheets.rows.csv-append called', { id, gid, sourceUri, sourceHasHeaders, headerMap, deduplicateBy });\n\n  try {\n    if (headerMap.length === 0) {\n      throw new McpError(ErrorCode.InvalidParams, 'headerMap cannot be empty');\n    }\n\n    // Validate: if sourceHasHeaders=false, all references must be numeric\n    if (!sourceHasHeaders) {\n      for (const { source, target } of headerMap) {\n        if (typeof source === 'string') {\n          throw new McpError(ErrorCode.InvalidParams, `sourceHasHeaders=false requires numeric indices. Got string source: \"${source}\"`);\n        }\n        if (typeof target === 'string') {\n          throw new McpError(ErrorCode.InvalidParams, `sourceHasHeaders=false requires numeric indices. Got string target: \"${target}\"`);\n        }\n      }\n      if (deduplicateBy) {\n        for (const colRef of deduplicateBy) {\n          if (typeof colRef === 'string') {\n            throw new McpError(ErrorCode.InvalidParams, `sourceHasHeaders=false requires numeric indices in deduplicateBy. Got string: \"${colRef}\"`);\n          }\n        }\n      }\n    }\n\n    const sheets = google.sheets({ version: 'v4', auth: extra.authContext.auth });\n\n    // Get sheet details using the gid\n    const spreadsheetResponse = await sheets.spreadsheets.get({\n      spreadsheetId: id,\n      fields: 'sheets.properties.sheetId,sheets.properties.title',\n    });\n\n    const sheet = spreadsheetResponse.data.sheets?.find((s) => String(s.properties?.sheetId) === gid);\n\n    if (!sheet) {\n      throw new McpError(ErrorCode.InvalidParams, 'Sheet not found');\n    }\n\n    const sheetTitle = sheet?.properties?.title ?? '';\n\n    // Determine target headers (for sourceHasHeaders=true) or column count (for sourceHasHeaders=false)\n    let sheetHeaders: string[] | null = null;\n    let existingKeySet: Set<string> = new Set();\n    const keyColumns: (string | number)[] = deduplicateBy || [];\n\n    if (sourceHasHeaders) {\n      // Extract target header names from headerMap\n      const targetHeaderNames = headerMap.map(({ target }) => target).filter((t) => typeof t === 'string') as string[];\n\n      // Use ensureTabAndHeaders to setup headers and fetch existing keys\n      const headerResult = await ensureTabAndHeaders(sheets, {\n        spreadsheetId: id,\n        sheetTitle,\n        requiredHeader: targetHeaderNames.length > 0 ? targetHeaderNames : null,\n        keyColumns: keyColumns.filter((k) => typeof k === 'string') as string[],\n        logger,\n      });\n\n      sheetHeaders = headerResult.header;\n      existingKeySet = headerResult.keySet;\n    } else {\n      // sourceHasHeaders=false: Read existing data for deduplication (if needed)\n      if (deduplicateBy && deduplicateBy.length > 0) {\n        // Read data in chunks for memory efficiency with large sheets\n        const CHUNK_SIZE = 1000;\n        let startRow = 1;\n        let hasMore = true;\n\n        while (hasMore) {\n          const endRow = startRow + CHUNK_SIZE - 1;\n          const chunkRange = `${sheetTitle}!A${startRow}:ZZZ${endRow}`;\n\n          const response = await sheets.spreadsheets.values.get({\n            spreadsheetId: id,\n            range: chunkRange,\n          });\n\n          const rows = response.data.values || [];\n\n          for (const row of rows) {\n            const key = buildDeduplicationKey(row, keyColumns, null, false);\n            if (key.replace(/::/g, '') !== '') {\n              existingKeySet.add(key);\n            }\n          }\n\n          // Check if there are more rows to read\n          if (rows.length < CHUNK_SIZE) {\n            hasMore = false;\n          } else {\n            startRow += CHUNK_SIZE;\n          }\n        }\n\n        logger.info('sheets.rows.csv-append existing keys loaded', { keyCount: existingKeySet.size });\n      }\n    }\n\n    // Streaming CSV processing state\n    let sourceHeaders: string[] | null = null;\n    let batch: (string | number | boolean | null)[][] = [];\n    let totalRows = 0;\n    let rowsSkipped = 0;\n\n    // Get readable stream from CSV URI (no temp files!)\n    const readStream = await getCsvReadStream(sourceUri);\n\n    // Create CSV parser\n    const parser = readStream.pipe(\n      parse({\n        columns: !!sourceHasHeaders, // Parse first row as column names if source has headers\n        skip_empty_lines: true,\n        trim: true,\n        cast: true, // Auto-convert numbers/booleans\n        relax_column_count: true,\n      })\n    );\n\n    // Helper to append batch to Sheets\n    const appendBatch = async (rows: (string | number | boolean | null)[][]): Promise<void> => {\n      if (rows.length === 0) return;\n\n      await sheets.spreadsheets.values.append({\n        spreadsheetId: id,\n        range: `${sheetTitle}!A:A`,\n        valueInputOption: 'USER_ENTERED',\n        requestBody: { values: rows, majorDimension: 'ROWS' },\n      });\n\n      logger.info('sheets.rows.csv-append batch appended', { batchSize: rows.length, totalRows });\n    };\n\n    // Resolve headerMap to numeric indices (do this after extracting CSV headers)\n    let resolvedMap: Array<{ sourceIdx: number; targetIdx: number }> = [];\n\n    // Stream and process records\n    for await (const record of parser) {\n      if (sourceHasHeaders) {\n        // Extract source headers from first record\n        if (sourceHeaders === null) {\n          sourceHeaders = Object.keys(record as Record<string, unknown>);\n          logger.info('sheets.rows.csv-append source headers', { sourceHeaders });\n\n          // Resolve headerMap now that we have both source and sheet headers\n          resolvedMap = headerMap.map(({ source, target }) => ({\n            sourceIdx: resolveColumnReference(source, sourceHeaders, sourceHasHeaders, 'headerMap.source'),\n            targetIdx: resolveColumnReference(target, sheetHeaders, sourceHasHeaders, 'headerMap.target'),\n          }));\n        }\n\n        // Map source record to sheet row\n        const sourceRow = sourceHeaders?.map((h) => (record as Record<string, unknown>)[h] ?? null);\n        const maxTargetIdx = Math.max(...resolvedMap.map((m) => m.targetIdx));\n        const sheetRow = new Array(maxTargetIdx + 1).fill(null);\n\n        for (const { sourceIdx, targetIdx } of resolvedMap) {\n          if (sourceRow) {\n            sheetRow[targetIdx] = sourceRow[sourceIdx] ?? null;\n          }\n        }\n\n        // Check deduplication\n        if (deduplicateBy && deduplicateBy.length > 0) {\n          const key = buildDeduplicationKey(sheetRow, keyColumns, sheetHeaders, sourceHasHeaders);\n          if (existingKeySet.has(key)) {\n            rowsSkipped++;\n            continue; // Skip duplicate\n          }\n          existingKeySet.add(key); // Add to set for future deduplication\n        }\n\n        // Add to batch\n        batch.push(sheetRow);\n        totalRows++;\n      } else {\n        // sourceHasHeaders=false: record is an array (not an object)\n        // Resolve map on first row\n        if (resolvedMap.length === 0) {\n          resolvedMap = headerMap.map(({ source, target }) => ({\n            sourceIdx: resolveColumnReference(source, null, sourceHasHeaders, 'headerMap.source'),\n            targetIdx: resolveColumnReference(target, null, sourceHasHeaders, 'headerMap.target'),\n          }));\n        }\n\n        const sourceRow = record as unknown[];\n        const maxTargetIdx = Math.max(...resolvedMap.map((m) => m.targetIdx));\n        const sheetRow = new Array(maxTargetIdx + 1).fill(null);\n\n        for (const { sourceIdx, targetIdx } of resolvedMap) {\n          if (sourceIdx < sourceRow.length) {\n            sheetRow[targetIdx] = sourceRow[sourceIdx] ?? null;\n          }\n        }\n\n        // Check deduplication\n        if (deduplicateBy && deduplicateBy.length > 0) {\n          const key = buildDeduplicationKey(sheetRow, keyColumns, null, sourceHasHeaders);\n          if (existingKeySet.has(key)) {\n            rowsSkipped++;\n            continue; // Skip duplicate\n          }\n          existingKeySet.add(key);\n        }\n\n        // Add to batch\n        batch.push(sheetRow);\n        totalRows++;\n      }\n\n      // Append batch when full\n      if (batch.length >= BATCH_SIZE) {\n        await appendBatch(batch);\n        batch = []; // Clear batch\n      }\n    }\n\n    // Flush remaining rows\n    if (batch.length > 0) {\n      await appendBatch(batch);\n    }\n\n    logger.info('sheets.rows.csv-append streaming complete', { totalRows, rowsSkipped });\n\n    const updatedRows = totalRows;\n\n    logger.info('sheets.rows.csv-append completed', { id, gid, updatedRows, rowsSkipped, sourceUri });\n\n    const result: Output = {\n      type: 'success' as const,\n      id,\n      gid,\n      sheetTitle,\n      updatedRows,\n      rowsSkipped,\n      sheetUrl: `https://docs.google.com/spreadsheets/d/${id}/edit#gid=${gid}`,\n    };\n\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.rows.csv-append error', { error: message });\n\n    throw new McpError(ErrorCode.InternalError, `Error appending CSV rows: ${message}`, {\n      stack: error instanceof Error ? error.stack : undefined,\n    });\n  }\n}\n\nexport default function createTool() {\n  return {\n    name: 'rows-csv-append',\n    config,\n    handler,\n  } satisfies ToolModule;\n}\n"],"names":["schemas","AuthRequiredBranchSchema","ErrorCode","McpError","parse","google","z","SheetGidOutput","SheetGidSchema","SpreadsheetIdOutput","SpreadsheetIdSchema","getCsvReadStream","buildDeduplicationKey","ensureTabAndHeaders","HeaderMapItemSchema","object","source","union","string","number","int","min","describe","target","inputSchema","id","gid","sourceUri","trim","sourceHasHeaders","boolean","default","headerMap","array","deduplicateBy","optional","successBranchSchema","type","literal","sheetTitle","updatedRows","rowsSkipped","sheetUrl","outputSchema","discriminatedUnion","config","description","result","BATCH_SIZE","resolveColumnReference","ref","headers","context","Error","index","indexOf","join","handler","extra","logger","info","spreadsheetResponse","sheet","length","InvalidParams","colRef","sheets","version","auth","authContext","spreadsheets","get","spreadsheetId","fields","data","find","s","String","properties","sheetId","title","sheetHeaders","existingKeySet","Set","keyColumns","targetHeaderNames","map","filter","t","headerResult","requiredHeader","k","header","keySet","CHUNK_SIZE","startRow","hasMore","endRow","chunkRange","response","values","range","rows","row","key","replace","add","keyCount","size","sourceHeaders","batch","totalRows","readStream","parser","pipe","columns","skip_empty_lines","cast","relax_column_count","appendBatch","append","valueInputOption","requestBody","majorDimension","batchSize","resolvedMap","record","Object","keys","sourceIdx","targetIdx","sourceRow","h","maxTargetIdx","Math","max","m","sheetRow","Array","fill","has","push","content","text","JSON","stringify","structuredContent","error","message","InternalError","stack","undefined","createTool","name"],"mappings":"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"}