@mcp-z/mcp-sheets 1.0.0

package/dist/esm/mcp/tools/values-search.js

@@ -0,0 +1,229 @@
+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 { SheetCellSchema, SheetGidSchema, SpreadsheetIdSchema } from '../../schemas/index.js';
+// Helper to convert column index to letter (0 = A, 1 = B, etc.)
+function columnIndexToLetter(index) {
+    let letter = '';
+    let num = index + 1;
+    while(num > 0){
+        const remainder = (num - 1) % 26;
+        letter = String.fromCharCode(65 + remainder) + letter;
+        num = Math.floor((num - 1) / 26);
+    }
+    return letter;
+}
+const inputSchema = z.object({
+    id: SpreadsheetIdSchema,
+    gid: SheetGidSchema,
+    query: z.coerce.string().trim().optional().describe('Text to search for in sheet cells. If empty, returns all data at specified granularity.'),
+    select: z.enum([
+        'cells',
+        'rows',
+        'columns'
+    ]).describe('Granularity: cells (individual matches), rows (full matching rows), columns (columns with matching headers)'),
+    values: z.boolean().optional().describe('Include cell values in response'),
+    a1s: z.boolean().optional().describe('Include A1 notation references in response'),
+    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.'),
+    matchCase: z.boolean().optional().describe('Case-sensitive matching. Default is false (case-insensitive).')
+});
+const successBranchSchema = z.object({
+    type: z.literal('success'),
+    count: z.number().int().nonnegative().describe('Number of matches found'),
+    a1s: z.array(z.string()).optional().describe('A1 notation references for matches (e.g., "B5", "A5:D5", "B:B")'),
+    values: z.array(z.union([
+        z.array(SheetCellSchema),
+        SheetCellSchema
+    ])).optional().describe('Cell values for matches (arrays for rows/columns, single values for cells)')
+});
+const outputSchema = z.discriminatedUnion('type', [
+    successBranchSchema,
+    AuthRequiredBranchSchema
+]);
+const config = {
+    description: 'Search spreadsheet and return matches at cell, row, or column granularity. Use a1-notation prompt for range syntax.',
+    inputSchema,
+    outputSchema: z.object({
+        result: outputSchema
+    })
+};
+async function handler({ id, gid, query, select, values = false, a1s = false, render, matchCase = false }, extra) {
+    const logger = extra.logger;
+    logger.info('sheets.values-search called', {
+        id,
+        gid,
+        query,
+        select,
+        values,
+        a1s,
+        render,
+        matchCase
+    });
+    try {
+        var _ref, _ref1, _ref2;
+        var _spreadsheetResponse_data_sheets, _sheet_properties, _sheet_properties_gridProperties, _sheet_properties1, _sheet_properties_gridProperties1, _sheet_properties2, _logger_debug;
+        const sheets = google.sheets({
+            version: 'v4',
+            auth: extra.authContext.auth
+        });
+        // Get sheet details including grid dimensions
+        const spreadsheetResponse = await sheets.spreadsheets.get({
+            spreadsheetId: id,
+            fields: 'sheets.properties.sheetId,sheets.properties.title,sheets.properties.gridProperties'
+        });
+        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) {
+            logger.info('sheets.values-search sheet not found', {
+                id,
+                gid,
+                query
+            });
+            throw new McpError(ErrorCode.InvalidParams, 'Sheet not found');
+        }
+        const sheetTitle = (_ref = (_sheet_properties = sheet.properties) === null || _sheet_properties === void 0 ? void 0 : _sheet_properties.title) !== null && _ref !== void 0 ? _ref : '';
+        // Use actual sheet dimensions from gridProperties, with sensible defaults
+        // Google Sheets default for new sheets is 1000 rows x 26 columns
+        const rowCount = (_ref1 = (_sheet_properties1 = sheet.properties) === null || _sheet_properties1 === void 0 ? void 0 : (_sheet_properties_gridProperties = _sheet_properties1.gridProperties) === null || _sheet_properties_gridProperties === void 0 ? void 0 : _sheet_properties_gridProperties.rowCount) !== null && _ref1 !== void 0 ? _ref1 : 1000;
+        const columnCount = (_ref2 = (_sheet_properties2 = sheet.properties) === null || _sheet_properties2 === void 0 ? void 0 : (_sheet_properties_gridProperties1 = _sheet_properties2.gridProperties) === null || _sheet_properties_gridProperties1 === void 0 ? void 0 : _sheet_properties_gridProperties1.columnCount) !== null && _ref2 !== void 0 ? _ref2 : 26;
+        const endColumn = columnIndexToLetter(columnCount - 1);
+        const fullRange = `${sheetTitle}!A1:${endColumn}${rowCount}`;
+        (_logger_debug = logger.debug) === null || _logger_debug === void 0 ? void 0 : _logger_debug.call(logger, 'sheets.values-search fetching range', {
+            fullRange,
+            rowCount,
+            columnCount
+        });
+        const response = await sheets.spreadsheets.values.get({
+            spreadsheetId: id,
+            range: fullRange,
+            valueRenderOption: render || 'FORMATTED_VALUE'
+        });
+        const res = response.data;
+        const allRows = Array.isArray(res.values) ? res.values : [];
+        // Prepare query for matching (case-insensitive by default)
+        const searchQuery = query ? matchCase ? query : query.toLowerCase() : null;
+        let count = 0;
+        const a1Array = [];
+        const valuesArray = [];
+        // Helper to check if a cell matches the query
+        const cellMatches = (cell)=>{
+            if (!searchQuery) return true; // If no query, match all
+            if (typeof cell !== 'string') return false;
+            const cellValue = matchCase ? cell : cell.toLowerCase();
+            return cellValue.includes(searchQuery);
+        };
+        if (select === 'cells') {
+            for(let rowIdx = 0; rowIdx < allRows.length; rowIdx++){
+                const row = allRows[rowIdx];
+                if (!row) continue;
+                for(let colIdx = 0; colIdx < row.length; colIdx++){
+                    const cell = row[colIdx];
+                    if (cellMatches(cell)) {
+                        count++;
+                        if (a1s) {
+                            const colLetter = columnIndexToLetter(colIdx);
+                            const rowNum = rowIdx + 1;
+                            a1Array.push(`${colLetter}${rowNum}`);
+                        }
+                        if (values) {
+                            valuesArray.push(cell !== null && cell !== void 0 ? cell : null);
+                        }
+                    }
+                }
+            }
+        } else if (select === 'rows') {
+            const matchingRows = [];
+            for(let rowIdx = 0; rowIdx < allRows.length; rowIdx++){
+                const row = allRows[rowIdx];
+                if (!row) continue;
+                const matches = row.some((cell)=>cellMatches(cell));
+                if (matches) {
+                    matchingRows.push(rowIdx);
+                }
+            }
+            count = matchingRows.length;
+            for (const rowIdx of matchingRows){
+                const row = allRows[rowIdx];
+                if (!row) continue; // Skip if row is undefined
+                const rowNum = rowIdx + 1;
+                if (a1s) {
+                    const colEnd = columnIndexToLetter(Math.max(0, row.length - 1));
+                    a1Array.push(`A${rowNum}:${colEnd}${rowNum}`);
+                }
+                if (values) {
+                    valuesArray.push(row);
+                }
+            }
+        } else if (select === 'columns') {
+            const headerRow = allRows[0] || [];
+            const matchingCols = [];
+            for(let colIdx = 0; colIdx < headerRow.length; colIdx++){
+                const header = headerRow[colIdx];
+                if (cellMatches(header)) {
+                    matchingCols.push(colIdx);
+                }
+            }
+            count = matchingCols.length;
+            for (const colIdx of matchingCols){
+                const colLetter = columnIndexToLetter(colIdx);
+                if (a1s) {
+                    a1Array.push(`${colLetter}:${colLetter}`);
+                }
+                if (values) {
+                    const columnValues = allRows.map((row)=>row && row[colIdx] !== undefined ? row[colIdx] : null);
+                    valuesArray.push(columnValues);
+                }
+            }
+        }
+        logger.info('sheets.values-search results', {
+            count,
+            select,
+            hasA1s: a1s,
+            hasValues: values
+        });
+        const result = {
+            type: 'success',
+            count,
+            ...a1s && a1Array.length > 0 && {
+                a1s: a1Array
+            },
+            ...values && valuesArray.length > 0 && {
+                values: valuesArray
+            }
+        };
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result)
+                }
+            ],
+            structuredContent: {
+                result
+            }
+        };
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error('sheets.values-search error', {
+            error: message
+        });
+        throw new McpError(ErrorCode.InternalError, `Error searching spreadsheet: ${message}`, {
+            stack: error instanceof Error ? error.stack : undefined
+        });
+    }
+}
+export default function createTool() {
+    return {
+        name: 'values-search',
+        config,
+        handler
+    };
+}

package/dist/esm/mcp/tools/values-search.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/mcp/tools/values-search.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 { SheetCellSchema, SheetGidSchema, SpreadsheetIdSchema } from '../../schemas/index.js';\n\n// Helper to convert column index to letter (0 = A, 1 = B, etc.)\nfunction columnIndexToLetter(index: number): string {\n  let letter = '';\n  let num = index + 1;\n  while (num > 0) {\n    const remainder = (num - 1) % 26;\n    letter = String.fromCharCode(65 + remainder) + letter;\n    num = Math.floor((num - 1) / 26);\n  }\n  return letter;\n}\n\nconst inputSchema = z.object({\n  id: SpreadsheetIdSchema,\n  gid: SheetGidSchema,\n  query: z.coerce.string().trim().optional().describe('Text to search for in sheet cells. If empty, returns all data at specified granularity.'),\n  select: z.enum(['cells', 'rows', 'columns']).describe('Granularity: cells (individual matches), rows (full matching rows), columns (columns with matching headers)'),\n  values: z.boolean().optional().describe('Include cell values in response'),\n  a1s: z.boolean().optional().describe('Include A1 notation references in response'),\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  matchCase: z.boolean().optional().describe('Case-sensitive matching. Default is false (case-insensitive).'),\n});\n\nconst successBranchSchema = z.object({\n  type: z.literal('success'),\n  count: z.number().int().nonnegative().describe('Number of matches found'),\n  a1s: z.array(z.string()).optional().describe('A1 notation references for matches (e.g., \"B5\", \"A5:D5\", \"B:B\")'),\n  values: z\n    .array(z.union([z.array(SheetCellSchema), SheetCellSchema]))\n    .optional()\n    .describe('Cell values for matches (arrays for rows/columns, single values for cells)'),\n});\n\nconst outputSchema = z.discriminatedUnion('type', [successBranchSchema, AuthRequiredBranchSchema]);\n\nconst config = {\n  description: 'Search spreadsheet and return matches at cell, row, or column granularity. Use a1-notation prompt for range syntax.',\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, query, select, values = false, a1s = false, render, matchCase = false }: Input, extra: EnrichedExtra): Promise<CallToolResult> {\n  const logger = extra.logger;\n  logger.info('sheets.values-search called', { id, gid, query, select, values, a1s, render, matchCase });\n\n  try {\n    const sheets = google.sheets({ version: 'v4', auth: extra.authContext.auth });\n\n    // Get sheet details including grid dimensions\n    const spreadsheetResponse = await sheets.spreadsheets.get({\n      spreadsheetId: id,\n      fields: 'sheets.properties.sheetId,sheets.properties.title,sheets.properties.gridProperties',\n    });\n\n    const sheet = spreadsheetResponse.data.sheets?.find((s) => String(s.properties?.sheetId) === gid);\n\n    if (!sheet) {\n      logger.info('sheets.values-search sheet not found', { id, gid, query });\n      throw new McpError(ErrorCode.InvalidParams, 'Sheet not found');\n    }\n\n    const sheetTitle = sheet.properties?.title ?? '';\n\n    // Use actual sheet dimensions from gridProperties, with sensible defaults\n    // Google Sheets default for new sheets is 1000 rows x 26 columns\n    const rowCount = sheet.properties?.gridProperties?.rowCount ?? 1000;\n    const columnCount = sheet.properties?.gridProperties?.columnCount ?? 26;\n    const endColumn = columnIndexToLetter(columnCount - 1);\n    const fullRange = `${sheetTitle}!A1:${endColumn}${rowCount}`;\n\n    logger.debug?.('sheets.values-search fetching range', { fullRange, rowCount, columnCount });\n\n    const response = await sheets.spreadsheets.values.get({\n      spreadsheetId: id,\n      range: fullRange,\n      valueRenderOption: render || 'FORMATTED_VALUE',\n    });\n    const res = response.data;\n    const allRows = Array.isArray(res.values) ? (res.values as (string | number | boolean | null)[][]) : [];\n\n    // Prepare query for matching (case-insensitive by default)\n    const searchQuery = query ? (matchCase ? query : query.toLowerCase()) : null;\n\n    let count = 0;\n    const a1Array: string[] = [];\n    const valuesArray: (string | number | boolean | null | (string | number | boolean | null)[])[] = [];\n\n    // Helper to check if a cell matches the query\n    const cellMatches = (cell: string | number | boolean | null): boolean => {\n      if (!searchQuery) return true; // If no query, match all\n      if (typeof cell !== 'string') return false;\n      const cellValue = matchCase ? cell : cell.toLowerCase();\n      return cellValue.includes(searchQuery);\n    };\n\n    if (select === 'cells') {\n      for (let rowIdx = 0; rowIdx < allRows.length; rowIdx++) {\n        const row = allRows[rowIdx];\n        if (!row) continue;\n\n        for (let colIdx = 0; colIdx < row.length; colIdx++) {\n          const cell = row[colIdx];\n          if (cellMatches(cell)) {\n            count++;\n            if (a1s) {\n              const colLetter = columnIndexToLetter(colIdx);\n              const rowNum = rowIdx + 1;\n              a1Array.push(`${colLetter}${rowNum}`);\n            }\n            if (values) {\n              valuesArray.push(cell ?? null);\n            }\n          }\n        }\n      }\n    } else if (select === 'rows') {\n      const matchingRows: number[] = [];\n      for (let rowIdx = 0; rowIdx < allRows.length; rowIdx++) {\n        const row = allRows[rowIdx];\n        if (!row) continue;\n\n        const matches = row.some((cell) => cellMatches(cell));\n        if (matches) {\n          matchingRows.push(rowIdx);\n        }\n      }\n\n      count = matchingRows.length;\n      for (const rowIdx of matchingRows) {\n        const row = allRows[rowIdx];\n        if (!row) continue; // Skip if row is undefined\n        const rowNum = rowIdx + 1;\n\n        if (a1s) {\n          const colEnd = columnIndexToLetter(Math.max(0, row.length - 1));\n          a1Array.push(`A${rowNum}:${colEnd}${rowNum}`);\n        }\n        if (values) {\n          valuesArray.push(row);\n        }\n      }\n    } else if (select === 'columns') {\n      const headerRow = allRows[0] || [];\n      const matchingCols: number[] = [];\n\n      for (let colIdx = 0; colIdx < headerRow.length; colIdx++) {\n        const header = headerRow[colIdx];\n        if (cellMatches(header)) {\n          matchingCols.push(colIdx);\n        }\n      }\n\n      count = matchingCols.length;\n      for (const colIdx of matchingCols) {\n        const colLetter = columnIndexToLetter(colIdx);\n\n        if (a1s) {\n          a1Array.push(`${colLetter}:${colLetter}`);\n        }\n        if (values) {\n          const columnValues = allRows.map((row) => (row && row[colIdx] !== undefined ? row[colIdx] : null));\n          valuesArray.push(columnValues);\n        }\n      }\n    }\n\n    logger.info('sheets.values-search results', { count, select, hasA1s: a1s, hasValues: values });\n\n    const result: Output = {\n      type: 'success' as const,\n      count,\n      ...(a1s && a1Array.length > 0 && { a1s: a1Array }),\n      ...(values && valuesArray.length > 0 && { values: valuesArray }),\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.values-search error', { error: message });\n\n    throw new McpError(ErrorCode.InternalError, `Error searching spreadsheet: ${message}`, {\n      stack: error instanceof Error ? error.stack : undefined,\n    });\n  }\n}\n\nexport default function createTool() {\n  return {\n    name: 'values-search',\n    config,\n    handler,\n  } satisfies ToolModule;\n}\n"],"names":["schemas","AuthRequiredBranchSchema","ErrorCode","McpError","google","z","SheetCellSchema","SheetGidSchema","SpreadsheetIdSchema","columnIndexToLetter","index","letter","num","remainder","String","fromCharCode","Math","floor","inputSchema","object","id","gid","query","coerce","string","trim","optional","describe","select","enum","values","boolean","a1s","render","matchCase","successBranchSchema","type","literal","count","number","int","nonnegative","array","union","outputSchema","discriminatedUnion","config","description","result","handler","extra","logger","info","spreadsheetResponse","sheet","sheets","version","auth","authContext","spreadsheets","get","spreadsheetId","fields","data","find","s","properties","sheetId","InvalidParams","sheetTitle","title","rowCount","gridProperties","columnCount","endColumn","fullRange","debug","response","range","valueRenderOption","res","allRows","Array","isArray","searchQuery","toLowerCase","a1Array","valuesArray","cellMatches","cell","cellValue","includes","rowIdx","length","row","colIdx","colLetter","rowNum","push","matchingRows","matches","some","colEnd","max","headerRow","matchingCols","header","columnValues","map","undefined","hasA1s","hasValues","content","text","JSON","stringify","structuredContent","error","message","Error","InternalError","stack","createTool","name"],"mappings":"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"}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{ "type": "module" }

package/dist/esm/schemas/index.d.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+export declare const SpreadsheetRefSchema: z.ZodString;
+export declare const SheetRefSchema: z.ZodString;
+export declare const SpreadsheetIdSchema: z.ZodString;
+export declare const SheetGidSchema: z.ZodCoercedString<unknown>;
+export declare const SpreadsheetIdOutput: z.ZodString;
+export declare const SheetGidOutput: z.ZodString;
+export declare const SheetCellSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodLiteral<number>, z.ZodLiteral<number>, z.ZodBoolean, z.ZodNull]>;
+export declare const SheetRowSchema: z.ZodObject<{
+    rowIndex: z.ZodNumber;
+    values: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodLiteral<number>, z.ZodLiteral<number>, z.ZodBoolean, z.ZodNull]>>>;
+    range: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const A1NotationSchema: z.ZodString;

package/dist/esm/schemas/index.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+// Spreadsheet and sheet reference schemas
+export const SpreadsheetRefSchema = z.string().min(1).describe('Spreadsheet reference: full URL, exact name, or partial name (not ID - use spreadsheet-find to get ID)');
+export const SheetRefSchema = z.string().min(1).describe('Sheet reference: exact title or partial name match (not ID - use sheet-find to get ID)');
+// Shared descriptions for consistency
+const SPREADSHEET_ID_DESC = 'Spreadsheet ID (from URL d/{id})';
+const SHEET_ID_DESC = 'Sheet ID (from URL gid={gid})';
+// Input schemas (with validation)
+// Note: z.coerce.string() converts numbers to strings, handling cases where MCP clients
+// pass gid: 0 (number) instead of gid: "0" (string). This is critical for gid=0 which
+// is the default sheet ID in new spreadsheets.
+export const SpreadsheetIdSchema = z.string().min(1).describe(SPREADSHEET_ID_DESC);
+export const SheetGidSchema = z.coerce.string().min(1).describe(SHEET_ID_DESC);
+// Output schemas (for use in output/response schemas)
+export const SpreadsheetIdOutput = z.string().describe(SPREADSHEET_ID_DESC);
+export const SheetGidOutput = z.string().describe(SHEET_ID_DESC);
+// Schema for individual sheet cells (can be string, number, boolean, or null)
+// null represents empty cells - JSON cannot represent undefined, and Google API uses null for empty cells
+// Infinity values are allowed as Google Sheets can contain them, but NaN is still rejected
+export const SheetCellSchema = z.union([
+    z.string(),
+    z.number(),
+    z.literal(Infinity),
+    z.literal(-Infinity),
+    z.boolean(),
+    z.null()
+]);
+// Schema for a row in a sheet search result
+export const SheetRowSchema = z.object({
+    rowIndex: z.number().int().positive().describe('1-based row number in the sheet'),
+    values: z.array(SheetCellSchema).optional().describe('Cell values for this row (included when includeData=true)'),
+    range: z.string().optional().describe('A1 notation range for this row (e.g., A5:D5)')
+});
+// A1 notation validation - simplified for zod compatibility
+export const A1NotationSchema = z.string().min(1).describe('A1 notation for cell range (e.g., A1, A1:B2, A:B, 1:2)');

package/dist/esm/schemas/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/schemas/index.ts"],"sourcesContent":["import { z } from 'zod';\n\n// Spreadsheet and sheet reference schemas\nexport const SpreadsheetRefSchema = z.string().min(1).describe('Spreadsheet reference: full URL, exact name, or partial name (not ID - use spreadsheet-find to get ID)');\n\nexport const SheetRefSchema = z.string().min(1).describe('Sheet reference: exact title or partial name match (not ID - use sheet-find to get ID)');\n\n// Shared descriptions for consistency\nconst SPREADSHEET_ID_DESC = 'Spreadsheet ID (from URL d/{id})';\nconst SHEET_ID_DESC = 'Sheet ID (from URL gid={gid})';\n\n// Input schemas (with validation)\n// Note: z.coerce.string() converts numbers to strings, handling cases where MCP clients\n// pass gid: 0 (number) instead of gid: \"0\" (string). This is critical for gid=0 which\n// is the default sheet ID in new spreadsheets.\nexport const SpreadsheetIdSchema = z.string().min(1).describe(SPREADSHEET_ID_DESC);\nexport const SheetGidSchema = z.coerce.string().min(1).describe(SHEET_ID_DESC);\n\n// Output schemas (for use in output/response schemas)\nexport const SpreadsheetIdOutput = z.string().describe(SPREADSHEET_ID_DESC);\nexport const SheetGidOutput = z.string().describe(SHEET_ID_DESC);\n\n// Schema for individual sheet cells (can be string, number, boolean, or null)\n// null represents empty cells - JSON cannot represent undefined, and Google API uses null for empty cells\n// Infinity values are allowed as Google Sheets can contain them, but NaN is still rejected\nexport const SheetCellSchema = z.union([z.string(), z.number(), z.literal(Infinity), z.literal(-Infinity), z.boolean(), z.null()]);\n\n// Schema for a row in a sheet search result\nexport const SheetRowSchema = z.object({\n  rowIndex: z.number().int().positive().describe('1-based row number in the sheet'),\n  values: z.array(SheetCellSchema).optional().describe('Cell values for this row (included when includeData=true)'),\n  range: z.string().optional().describe('A1 notation range for this row (e.g., A5:D5)'),\n});\n\n// A1 notation validation - simplified for zod compatibility\nexport const A1NotationSchema = z.string().min(1).describe('A1 notation for cell range (e.g., A1, A1:B2, A:B, 1:2)');\n"],"names":["z","SpreadsheetRefSchema","string","min","describe","SheetRefSchema","SPREADSHEET_ID_DESC","SHEET_ID_DESC","SpreadsheetIdSchema","SheetGidSchema","coerce","SpreadsheetIdOutput","SheetGidOutput","SheetCellSchema","union","number","literal","Infinity","boolean","null","SheetRowSchema","object","rowIndex","int","positive","values","array","optional","range","A1NotationSchema"],"mappings":"AAAA,SAASA,CAAC,QAAQ,MAAM;AAExB,0CAA0C;AAC1C,OAAO,MAAMC,uBAAuBD,EAAEE,MAAM,GAAGC,GAAG,CAAC,GAAGC,QAAQ,CAAC,0GAA0G;AAEzK,OAAO,MAAMC,iBAAiBL,EAAEE,MAAM,GAAGC,GAAG,CAAC,GAAGC,QAAQ,CAAC,0FAA0F;AAEnJ,sCAAsC;AACtC,MAAME,sBAAsB;AAC5B,MAAMC,gBAAgB;AAEtB,kCAAkC;AAClC,wFAAwF;AACxF,sFAAsF;AACtF,+CAA+C;AAC/C,OAAO,MAAMC,sBAAsBR,EAAEE,MAAM,GAAGC,GAAG,CAAC,GAAGC,QAAQ,CAACE,qBAAqB;AACnF,OAAO,MAAMG,iBAAiBT,EAAEU,MAAM,CAACR,MAAM,GAAGC,GAAG,CAAC,GAAGC,QAAQ,CAACG,eAAe;AAE/E,sDAAsD;AACtD,OAAO,MAAMI,sBAAsBX,EAAEE,MAAM,GAAGE,QAAQ,CAACE,qBAAqB;AAC5E,OAAO,MAAMM,iBAAiBZ,EAAEE,MAAM,GAAGE,QAAQ,CAACG,eAAe;AAEjE,8EAA8E;AAC9E,0GAA0G;AAC1G,2FAA2F;AAC3F,OAAO,MAAMM,kBAAkBb,EAAEc,KAAK,CAAC;IAACd,EAAEE,MAAM;IAAIF,EAAEe,MAAM;IAAIf,EAAEgB,OAAO,CAACC;IAAWjB,EAAEgB,OAAO,CAAC,CAACC;IAAWjB,EAAEkB,OAAO;IAAIlB,EAAEmB,IAAI;CAAG,EAAE;AAEnI,4CAA4C;AAC5C,OAAO,MAAMC,iBAAiBpB,EAAEqB,MAAM,CAAC;IACrCC,UAAUtB,EAAEe,MAAM,GAAGQ,GAAG,GAAGC,QAAQ,GAAGpB,QAAQ,CAAC;IAC/CqB,QAAQzB,EAAE0B,KAAK,CAACb,iBAAiBc,QAAQ,GAAGvB,QAAQ,CAAC;IACrDwB,OAAO5B,EAAEE,MAAM,GAAGyB,QAAQ,GAAGvB,QAAQ,CAAC;AACxC,GAAG;AAEH,4DAA4D;AAC5D,OAAO,MAAMyB,mBAAmB7B,EAAEE,MAAM,GAAGC,GAAG,CAAC,GAAGC,QAAQ,CAAC,0DAA0D"}

package/dist/esm/setup/config.d.ts

@@ -0,0 +1,44 @@
+import type { ServerConfig } from '../types.js';
+/**
+ * Handle --version and --help flags before config parsing.
+ * These should work without requiring any configuration.
+ */
+export declare function handleVersionHelp(args: string[]): {
+    handled: boolean;
+    output?: string;
+};
+/**
+ * Parse Sheets server configuration from CLI arguments and environment.
+ *
+ * CLI Arguments (all optional):
+ * - --auth=<mode>          Authentication mode (default: loopback-oauth)
+ *                          Modes: loopback-oauth, service-account, dcr
+ * - --headless             Disable browser auto-open, return auth URL instead
+ * - --redirect-uri=<uri>   OAuth redirect URI (default: ephemeral loopback)
+ * - --dcr-mode=<mode>      DCR mode (self-hosted or external, default: self-hosted)
+ * - --dcr-verify-url=<url> External verification endpoint (required for external mode)
+ * - --dcr-store-uri=<uri>  DCR client storage URI (required for self-hosted mode)
+ * - --port=<port>          Enable HTTP transport on specified port
+ * - --stdio                Enable stdio transport (default if no port)
+ * - --log-level=<level>    Logging level (default: info)
+ *
+ * Environment Variables:
+ * - GOOGLE_CLIENT_ID       OAuth client ID (REQUIRED)
+ * - GOOGLE_CLIENT_SECRET   OAuth client secret (optional)
+ * - AUTH_MODE              Default authentication mode (optional)
+ * - HEADLESS               Disable browser auto-open (optional)
+ * - DCR_MODE               DCR mode (optional, same format as --dcr-mode)
+ * - DCR_VERIFY_URL         External verification URL (optional, same as --dcr-verify-url)
+ * - DCR_STORE_URI          DCR storage URI (optional, same as --dcr-store-uri)
+ * - PORT                   Default HTTP port (optional)
+ * - LOG_LEVEL              Default logging level (optional)
+ *
+ * OAuth Scopes (from constants.ts):
+ * openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive
+ */
+export declare function parseConfig(args: string[], env: Record<string, string | undefined>): ServerConfig;
+/**
+ * Build production configuration from process globals.
+ * Entry point for production server.
+ */
+export declare function createConfig(): ServerConfig;

package/dist/esm/setup/config.js

@@ -0,0 +1,151 @@
+import { parseDcrConfig, parseConfig as parseOAuthConfig } from '@mcp-z/oauth-google';
+import { parseConfig as parseTransportConfig } from '@mcp-z/server';
+import * as fs from 'fs';
+import moduleRoot from 'module-root-sync';
+import { homedir } from 'os';
+import * as path from 'path';
+import * as url from 'url';
+import { parseArgs } from 'util';
+import { GOOGLE_SCOPE } from '../constants.js';
+const pkg = JSON.parse(fs.readFileSync(path.join(moduleRoot(url.fileURLToPath(import.meta.url)), 'package.json'), 'utf-8'));
+const HELP_TEXT = `
+Usage: mcp-sheets [options]
+
+MCP server for Google Sheets spreadsheet management with OAuth authentication.
+
+Options:
+  --version              Show version number
+  --help                 Show this help message
+  --auth=<mode>          Authentication mode (default: loopback-oauth)
+                         Modes: loopback-oauth, service-account, dcr
+  --headless             Disable browser auto-open, return auth URL instead
+  --redirect-uri=<uri>   OAuth redirect URI (default: ephemeral loopback)
+  --dcr-mode=<mode>      DCR mode (self-hosted or external, default: self-hosted)
+  --dcr-verify-url=<url> External verification endpoint (required for external mode)
+  --dcr-store-uri=<uri>  DCR client storage URI (required for self-hosted mode)
+  --port=<port>          Enable HTTP transport on specified port
+  --stdio                Enable stdio transport (default if no port)
+  --log-level=<level>    Logging level (default: info)
+
+Environment Variables:
+  GOOGLE_CLIENT_ID       OAuth client ID (REQUIRED)
+  GOOGLE_CLIENT_SECRET   OAuth client secret (optional)
+  AUTH_MODE              Default authentication mode (optional)
+  HEADLESS               Disable browser auto-open (optional)
+  DCR_MODE               DCR mode (optional, same format as --dcr-mode)
+  DCR_VERIFY_URL         External verification URL (optional, same as --dcr-verify-url)
+  DCR_STORE_URI          DCR storage URI (optional, same as --dcr-store-uri)
+  PORT                   Default HTTP port (optional)
+  LOG_LEVEL              Default logging level (optional)
+
+OAuth Scopes:
+  openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive
+
+Examples:
+  mcp-sheets                           # Use default settings
+  mcp-sheets --auth=service-account    # Use service account auth
+  mcp-sheets --port=3000               # HTTP transport on port 3000
+  GOOGLE_CLIENT_ID=xxx mcp-sheets      # Set client ID via env var
+`.trim();
+/**
+ * Handle --version and --help flags before config parsing.
+ * These should work without requiring any configuration.
+ */ export function handleVersionHelp(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            version: {
+                type: 'boolean'
+            },
+            help: {
+                type: 'boolean'
+            }
+        },
+        strict: false
+    });
+    if (values.version) return {
+        handled: true,
+        output: pkg.version
+    };
+    if (values.help) return {
+        handled: true,
+        output: HELP_TEXT
+    };
+    return {
+        handled: false
+    };
+}
+/**
+ * Parse Sheets server configuration from CLI arguments and environment.
+ *
+ * CLI Arguments (all optional):
+ * - --auth=<mode>          Authentication mode (default: loopback-oauth)
+ *                          Modes: loopback-oauth, service-account, dcr
+ * - --headless             Disable browser auto-open, return auth URL instead
+ * - --redirect-uri=<uri>   OAuth redirect URI (default: ephemeral loopback)
+ * - --dcr-mode=<mode>      DCR mode (self-hosted or external, default: self-hosted)
+ * - --dcr-verify-url=<url> External verification endpoint (required for external mode)
+ * - --dcr-store-uri=<uri>  DCR client storage URI (required for self-hosted mode)
+ * - --port=<port>          Enable HTTP transport on specified port
+ * - --stdio                Enable stdio transport (default if no port)
+ * - --log-level=<level>    Logging level (default: info)
+ *
+ * Environment Variables:
+ * - GOOGLE_CLIENT_ID       OAuth client ID (REQUIRED)
+ * - GOOGLE_CLIENT_SECRET   OAuth client secret (optional)
+ * - AUTH_MODE              Default authentication mode (optional)
+ * - HEADLESS               Disable browser auto-open (optional)
+ * - DCR_MODE               DCR mode (optional, same format as --dcr-mode)
+ * - DCR_VERIFY_URL         External verification URL (optional, same as --dcr-verify-url)
+ * - DCR_STORE_URI          DCR storage URI (optional, same as --dcr-store-uri)
+ * - PORT                   Default HTTP port (optional)
+ * - LOG_LEVEL              Default logging level (optional)
+ *
+ * OAuth Scopes (from constants.ts):
+ * openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive
+ */ export function parseConfig(args, env) {
+    var _ref, _ref1;
+    const transportConfig = parseTransportConfig(args, env);
+    const oauthConfig = parseOAuthConfig(args, env);
+    // Parse DCR configuration if DCR mode is enabled
+    const dcrConfig = oauthConfig.auth === 'dcr' ? parseDcrConfig(args, env, GOOGLE_SCOPE) : undefined;
+    // Parse application-level config (LOG_LEVEL)
+    const { values } = parseArgs({
+        args,
+        options: {
+            'log-level': {
+                type: 'string'
+            }
+        },
+        strict: false,
+        allowPositionals: true
+    });
+    const name = pkg.name.replace(/^@[^/]+\//, '');
+    // Parse repository URL from package.json, stripping git+ prefix and .git suffix
+    const rawRepoUrl = typeof pkg.repository === 'object' ? pkg.repository.url : pkg.repository;
+    const repositoryUrl = (_ref = rawRepoUrl === null || rawRepoUrl === void 0 ? void 0 : rawRepoUrl.replace(/^git\+/, '').replace(/\.git$/, '')) !== null && _ref !== void 0 ? _ref : `https://github.com/mcp-z/${name}`;
+    const rootDir = process.cwd() === '/' ? homedir() : process.cwd();
+    const baseDir = path.join(rootDir, '.mcp-z');
+    const cliLogLevel = typeof values['log-level'] === 'string' ? values['log-level'] : undefined;
+    const envLogLevel = env.LOG_LEVEL;
+    const logLevel = (_ref1 = cliLogLevel !== null && cliLogLevel !== void 0 ? cliLogLevel : envLogLevel) !== null && _ref1 !== void 0 ? _ref1 : 'info';
+    // Combine configs
+    return {
+        ...oauthConfig,
+        transport: transportConfig.transport,
+        logLevel,
+        baseDir,
+        name,
+        version: pkg.version,
+        repositoryUrl,
+        ...dcrConfig && {
+            dcrConfig
+        }
+    };
+}
+/**
+ * Build production configuration from process globals.
+ * Entry point for production server.
+ */ export function createConfig() {
+    return parseConfig(process.argv, process.env);
+}

package/dist/esm/setup/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/setup/config.ts"],"sourcesContent":["import { parseDcrConfig, parseConfig as parseOAuthConfig } from '@mcp-z/oauth-google';\nimport { parseConfig as parseTransportConfig } from '@mcp-z/server';\nimport * as fs from 'fs';\nimport moduleRoot from 'module-root-sync';\nimport { homedir } from 'os';\nimport * as path from 'path';\nimport * as url from 'url';\nimport { parseArgs } from 'util';\nimport { GOOGLE_SCOPE } from '../constants.ts';\nimport type { ServerConfig } from '../types.js';\n\nconst pkg = JSON.parse(fs.readFileSync(path.join(moduleRoot(url.fileURLToPath(import.meta.url)), 'package.json'), 'utf-8'));\n\nconst HELP_TEXT = `\nUsage: mcp-sheets [options]\n\nMCP server for Google Sheets spreadsheet management with OAuth authentication.\n\nOptions:\n  --version              Show version number\n  --help                 Show this help message\n  --auth=<mode>          Authentication mode (default: loopback-oauth)\n                         Modes: loopback-oauth, service-account, dcr\n  --headless             Disable browser auto-open, return auth URL instead\n  --redirect-uri=<uri>   OAuth redirect URI (default: ephemeral loopback)\n  --dcr-mode=<mode>      DCR mode (self-hosted or external, default: self-hosted)\n  --dcr-verify-url=<url> External verification endpoint (required for external mode)\n  --dcr-store-uri=<uri>  DCR client storage URI (required for self-hosted mode)\n  --port=<port>          Enable HTTP transport on specified port\n  --stdio                Enable stdio transport (default if no port)\n  --log-level=<level>    Logging level (default: info)\n\nEnvironment Variables:\n  GOOGLE_CLIENT_ID       OAuth client ID (REQUIRED)\n  GOOGLE_CLIENT_SECRET   OAuth client secret (optional)\n  AUTH_MODE              Default authentication mode (optional)\n  HEADLESS               Disable browser auto-open (optional)\n  DCR_MODE               DCR mode (optional, same format as --dcr-mode)\n  DCR_VERIFY_URL         External verification URL (optional, same as --dcr-verify-url)\n  DCR_STORE_URI          DCR storage URI (optional, same as --dcr-store-uri)\n  PORT                   Default HTTP port (optional)\n  LOG_LEVEL              Default logging level (optional)\n\nOAuth Scopes:\n  openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive\n\nExamples:\n  mcp-sheets                           # Use default settings\n  mcp-sheets --auth=service-account    # Use service account auth\n  mcp-sheets --port=3000               # HTTP transport on port 3000\n  GOOGLE_CLIENT_ID=xxx mcp-sheets      # Set client ID via env var\n`.trim();\n\n/**\n * Handle --version and --help flags before config parsing.\n * These should work without requiring any configuration.\n */\nexport function handleVersionHelp(args: string[]): { handled: boolean; output?: string } {\n  const { values } = parseArgs({\n    args,\n    options: {\n      version: { type: 'boolean' },\n      help: { type: 'boolean' },\n    },\n    strict: false,\n  });\n\n  if (values.version) return { handled: true, output: pkg.version };\n  if (values.help) return { handled: true, output: HELP_TEXT };\n  return { handled: false };\n}\n\n/**\n * Parse Sheets server configuration from CLI arguments and environment.\n *\n * CLI Arguments (all optional):\n * - --auth=<mode>          Authentication mode (default: loopback-oauth)\n *                          Modes: loopback-oauth, service-account, dcr\n * - --headless             Disable browser auto-open, return auth URL instead\n * - --redirect-uri=<uri>   OAuth redirect URI (default: ephemeral loopback)\n * - --dcr-mode=<mode>      DCR mode (self-hosted or external, default: self-hosted)\n * - --dcr-verify-url=<url> External verification endpoint (required for external mode)\n * - --dcr-store-uri=<uri>  DCR client storage URI (required for self-hosted mode)\n * - --port=<port>          Enable HTTP transport on specified port\n * - --stdio                Enable stdio transport (default if no port)\n * - --log-level=<level>    Logging level (default: info)\n *\n * Environment Variables:\n * - GOOGLE_CLIENT_ID       OAuth client ID (REQUIRED)\n * - GOOGLE_CLIENT_SECRET   OAuth client secret (optional)\n * - AUTH_MODE              Default authentication mode (optional)\n * - HEADLESS               Disable browser auto-open (optional)\n * - DCR_MODE               DCR mode (optional, same format as --dcr-mode)\n * - DCR_VERIFY_URL         External verification URL (optional, same as --dcr-verify-url)\n * - DCR_STORE_URI          DCR storage URI (optional, same as --dcr-store-uri)\n * - PORT                   Default HTTP port (optional)\n * - LOG_LEVEL              Default logging level (optional)\n *\n * OAuth Scopes (from constants.ts):\n * openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/spreadsheets https://www.googleapis.com/auth/drive\n */\nexport function parseConfig(args: string[], env: Record<string, string | undefined>): ServerConfig {\n  const transportConfig = parseTransportConfig(args, env);\n  const oauthConfig = parseOAuthConfig(args, env);\n\n  // Parse DCR configuration if DCR mode is enabled\n  const dcrConfig = oauthConfig.auth === 'dcr' ? parseDcrConfig(args, env, GOOGLE_SCOPE) : undefined;\n\n  // Parse application-level config (LOG_LEVEL)\n  const { values } = parseArgs({\n    args,\n    options: {\n      'log-level': { type: 'string' },\n    },\n    strict: false, // Allow other arguments\n    allowPositionals: true,\n  });\n\n  const name = pkg.name.replace(/^@[^/]+\\//, '');\n  // Parse repository URL from package.json, stripping git+ prefix and .git suffix\n  const rawRepoUrl = typeof pkg.repository === 'object' ? pkg.repository.url : pkg.repository;\n  const repositoryUrl = rawRepoUrl?.replace(/^git\\+/, '').replace(/\\.git$/, '') ?? `https://github.com/mcp-z/${name}`;\n  const rootDir = process.cwd() === '/' ? homedir() : process.cwd();\n  const baseDir = path.join(rootDir, '.mcp-z');\n  const cliLogLevel = typeof values['log-level'] === 'string' ? values['log-level'] : undefined;\n  const envLogLevel = env.LOG_LEVEL;\n  const logLevel = cliLogLevel ?? envLogLevel ?? 'info';\n\n  // Combine configs\n  return {\n    ...oauthConfig, // Includes clientId, auth, headless, redirectUri\n    transport: transportConfig.transport,\n    logLevel,\n    baseDir,\n    name,\n    version: pkg.version,\n    repositoryUrl,\n    ...(dcrConfig && { dcrConfig }),\n  };\n}\n\n/**\n * Build production configuration from process globals.\n * Entry point for production server.\n */\nexport function createConfig(): ServerConfig {\n  return parseConfig(process.argv, process.env);\n}\n"],"names":["parseDcrConfig","parseConfig","parseOAuthConfig","parseTransportConfig","fs","moduleRoot","homedir","path","url","parseArgs","GOOGLE_SCOPE","pkg","JSON","parse","readFileSync","join","fileURLToPath","HELP_TEXT","trim","handleVersionHelp","args","values","options","version","type","help","strict","handled","output","env","cliLogLevel","transportConfig","oauthConfig","dcrConfig","auth","undefined","allowPositionals","name","replace","rawRepoUrl","repository","repositoryUrl","rootDir","process","cwd","baseDir","envLogLevel","LOG_LEVEL","logLevel","transport","createConfig","argv"],"mappings":"AAAA,SAASA,cAAc,EAAEC,eAAeC,gBAAgB,QAAQ,sBAAsB;AACtF,SAASD,eAAeE,oBAAoB,QAAQ,gBAAgB;AACpE,YAAYC,QAAQ,KAAK;AACzB,OAAOC,gBAAgB,mBAAmB;AAC1C,SAASC,OAAO,QAAQ,KAAK;AAC7B,YAAYC,UAAU,OAAO;AAC7B,YAAYC,SAAS,MAAM;AAC3B,SAASC,SAAS,QAAQ,OAAO;AACjC,SAASC,YAAY,QAAQ,kBAAkB;AAG/C,MAAMC,MAAMC,KAAKC,KAAK,CAACT,GAAGU,YAAY,CAACP,KAAKQ,IAAI,CAACV,WAAWG,IAAIQ,aAAa,CAAC,YAAYR,GAAG,IAAI,iBAAiB;AAElH,MAAMS,YAAY,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCnB,CAAC,CAACC,IAAI;AAEN;;;CAGC,GACD,OAAO,SAASC,kBAAkBC,IAAc;IAC9C,MAAM,EAAEC,MAAM,EAAE,GAAGZ,UAAU;QAC3BW;QACAE,SAAS;YACPC,SAAS;gBAAEC,MAAM;YAAU;YAC3BC,MAAM;gBAAED,MAAM;YAAU;QAC1B;QACAE,QAAQ;IACV;IAEA,IAAIL,OAAOE,OAAO,EAAE,OAAO;QAAEI,SAAS;QAAMC,QAAQjB,IAAIY,OAAO;IAAC;IAChE,IAAIF,OAAOI,IAAI,EAAE,OAAO;QAAEE,SAAS;QAAMC,QAAQX;IAAU;IAC3D,OAAO;QAAEU,SAAS;IAAM;AAC1B;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GACD,OAAO,SAAS1B,YAAYmB,IAAc,EAAES,GAAuC;cAyBhEC;IAxBjB,MAAMC,kBAAkB5B,qBAAqBiB,MAAMS;IACnD,MAAMG,cAAc9B,iBAAiBkB,MAAMS;IAE3C,iDAAiD;IACjD,MAAMI,YAAYD,YAAYE,IAAI,KAAK,QAAQlC,eAAeoB,MAAMS,KAAKnB,gBAAgByB;IAEzF,6CAA6C;IAC7C,MAAM,EAAEd,MAAM,EAAE,GAAGZ,UAAU;QAC3BW;QACAE,SAAS;YACP,aAAa;gBAAEE,MAAM;YAAS;QAChC;QACAE,QAAQ;QACRU,kBAAkB;IACpB;IAEA,MAAMC,OAAO1B,IAAI0B,IAAI,CAACC,OAAO,CAAC,aAAa;IAC3C,gFAAgF;IAChF,MAAMC,aAAa,OAAO5B,IAAI6B,UAAU,KAAK,WAAW7B,IAAI6B,UAAU,CAAChC,GAAG,GAAGG,IAAI6B,UAAU;IAC3F,MAAMC,wBAAgBF,uBAAAA,iCAAAA,WAAYD,OAAO,CAAC,UAAU,IAAIA,OAAO,CAAC,UAAU,0CAAO,CAAC,yBAAyB,EAAED,MAAM;IACnH,MAAMK,UAAUC,QAAQC,GAAG,OAAO,MAAMtC,YAAYqC,QAAQC,GAAG;IAC/D,MAAMC,UAAUtC,KAAKQ,IAAI,CAAC2B,SAAS;IACnC,MAAMZ,cAAc,OAAOT,MAAM,CAAC,YAAY,KAAK,WAAWA,MAAM,CAAC,YAAY,GAAGc;IACpF,MAAMW,cAAcjB,IAAIkB,SAAS;IACjC,MAAMC,YAAWlB,QAAAA,wBAAAA,yBAAAA,cAAegB,yBAAfhB,mBAAAA,QAA8B;IAE/C,kBAAkB;IAClB,OAAO;QACL,GAAGE,WAAW;QACdiB,WAAWlB,gBAAgBkB,SAAS;QACpCD;QACAH;QACAR;QACAd,SAASZ,IAAIY,OAAO;QACpBkB;QACA,GAAIR,aAAa;YAAEA;QAAU,CAAC;IAChC;AACF;AAEA;;;CAGC,GACD,OAAO,SAASiB;IACd,OAAOjD,YAAY0C,QAAQQ,IAAI,EAAER,QAAQd,GAAG;AAC9C"}

package/dist/esm/setup/http.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { RuntimeOverrides, ServerConfig } from '../types.js';
+export declare function createHTTPServer(config: ServerConfig, overrides?: RuntimeOverrides): Promise<{
+    httpServer: import("node:http").Server<typeof import("node:http").IncomingMessage, typeof import("node:http").ServerResponse>;
+    mcpServer: McpServer;
+    logger: import("@mcp-z/server").Logger;
+    close: () => Promise<void>;
+}>;

package/dist/esm/setup/http.js

@@ -0,0 +1,54 @@
+import { composeMiddleware, connectHttp, registerPrompts, registerResources, registerTools } from '@mcp-z/server';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import cors from 'cors';
+import express from 'express';
+import { createDefaultRuntime } from './runtime.js';
+export async function createHTTPServer(config, overrides) {
+    const runtime = await createDefaultRuntime(config, overrides);
+    const modules = runtime.createDomainModules();
+    const layers = runtime.middlewareFactories.map((factory)=>factory(runtime.deps));
+    const composed = composeMiddleware(modules, layers);
+    const logger = runtime.deps.logger;
+    const port = config.transport.port;
+    if (!port) throw new Error('Port is required for HTTP transport');
+    const tools = [
+        ...composed.tools,
+        ...runtime.deps.oauthAdapters.accountTools
+    ];
+    const prompts = [
+        ...composed.prompts,
+        ...runtime.deps.oauthAdapters.accountPrompts
+    ];
+    const mcpServer = new McpServer({
+        name: config.name,
+        version: config.version
+    });
+    registerTools(mcpServer, tools);
+    registerResources(mcpServer, composed.resources);
+    registerPrompts(mcpServer, prompts);
+    const app = express();
+    app.use(cors());
+    app.use(express.json({
+        limit: '10mb'
+    }));
+    if (runtime.deps.oauthAdapters.dcrRouter) {
+        app.use('/', runtime.deps.oauthAdapters.dcrRouter);
+        logger.info('Mounted DCR router with OAuth endpoints');
+    }
+    logger.info(`Starting ${config.name} MCP server (http)`);
+    const { close, httpServer } = await connectHttp(mcpServer, {
+        logger,
+        app,
+        port
+    });
+    logger.info('http transport ready');
+    return {
+        httpServer,
+        mcpServer,
+        logger,
+        close: async ()=>{
+            await close();
+            await runtime.close();
+        }
+    };
+}

package/dist/esm/setup/http.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/servers/mcp-sheets/src/setup/http.ts"],"sourcesContent":["import { composeMiddleware, connectHttp, registerPrompts, registerResources, registerTools } from '@mcp-z/server';\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport cors from 'cors';\nimport express from 'express';\nimport type { RuntimeOverrides, ServerConfig } from '../types.js';\nimport { createDefaultRuntime } from './runtime.js';\n\nexport async function createHTTPServer(config: ServerConfig, overrides?: RuntimeOverrides) {\n  const runtime = await createDefaultRuntime(config, overrides);\n  const modules = runtime.createDomainModules();\n  const layers = runtime.middlewareFactories.map((factory) => factory(runtime.deps));\n  const composed = composeMiddleware(modules, layers);\n  const logger = runtime.deps.logger;\n  const port = config.transport.port;\n  if (!port) throw new Error('Port is required for HTTP transport');\n\n  const tools = [...composed.tools, ...runtime.deps.oauthAdapters.accountTools];\n  const prompts = [...composed.prompts, ...runtime.deps.oauthAdapters.accountPrompts];\n\n  const mcpServer = new McpServer({ name: config.name, version: config.version });\n  registerTools(mcpServer, tools);\n  registerResources(mcpServer, composed.resources);\n  registerPrompts(mcpServer, prompts);\n\n  const app = express();\n  app.use(cors());\n  app.use(express.json({ limit: '10mb' }));\n\n  if (runtime.deps.oauthAdapters.dcrRouter) {\n    app.use('/', runtime.deps.oauthAdapters.dcrRouter);\n    logger.info('Mounted DCR router with OAuth endpoints');\n  }\n\n  logger.info(`Starting ${config.name} MCP server (http)`);\n  const { close, httpServer } = await connectHttp(mcpServer, { logger, app, port });\n  logger.info('http transport ready');\n\n  return {\n    httpServer,\n    mcpServer,\n    logger,\n    close: async () => {\n      await close();\n      await runtime.close();\n    },\n  };\n}\n"],"names":["composeMiddleware","connectHttp","registerPrompts","registerResources","registerTools","McpServer","cors","express","createDefaultRuntime","createHTTPServer","config","overrides","runtime","modules","createDomainModules","layers","middlewareFactories","map","factory","deps","composed","logger","port","transport","Error","tools","oauthAdapters","accountTools","prompts","accountPrompts","mcpServer","name","version","resources","app","use","json","limit","dcrRouter","info","close","httpServer"],"mappings":"AAAA,SAASA,iBAAiB,EAAEC,WAAW,EAAEC,eAAe,EAAEC,iBAAiB,EAAEC,aAAa,QAAQ,gBAAgB;AAClH,SAASC,SAAS,QAAQ,0CAA0C;AACpE,OAAOC,UAAU,OAAO;AACxB,OAAOC,aAAa,UAAU;AAE9B,SAASC,oBAAoB,QAAQ,eAAe;AAEpD,OAAO,eAAeC,iBAAiBC,MAAoB,EAAEC,SAA4B;IACvF,MAAMC,UAAU,MAAMJ,qBAAqBE,QAAQC;IACnD,MAAME,UAAUD,QAAQE,mBAAmB;IAC3C,MAAMC,SAASH,QAAQI,mBAAmB,CAACC,GAAG,CAAC,CAACC,UAAYA,QAAQN,QAAQO,IAAI;IAChF,MAAMC,WAAWpB,kBAAkBa,SAASE;IAC5C,MAAMM,SAAST,QAAQO,IAAI,CAACE,MAAM;IAClC,MAAMC,OAAOZ,OAAOa,SAAS,CAACD,IAAI;IAClC,IAAI,CAACA,MAAM,MAAM,IAAIE,MAAM;IAE3B,MAAMC,QAAQ;WAAIL,SAASK,KAAK;WAAKb,QAAQO,IAAI,CAACO,aAAa,CAACC,YAAY;KAAC;IAC7E,MAAMC,UAAU;WAAIR,SAASQ,OAAO;WAAKhB,QAAQO,IAAI,CAACO,aAAa,CAACG,cAAc;KAAC;IAEnF,MAAMC,YAAY,IAAIzB,UAAU;QAAE0B,MAAMrB,OAAOqB,IAAI;QAAEC,SAAStB,OAAOsB,OAAO;IAAC;IAC7E5B,cAAc0B,WAAWL;IACzBtB,kBAAkB2B,WAAWV,SAASa,SAAS;IAC/C/B,gBAAgB4B,WAAWF;IAE3B,MAAMM,MAAM3B;IACZ2B,IAAIC,GAAG,CAAC7B;IACR4B,IAAIC,GAAG,CAAC5B,QAAQ6B,IAAI,CAAC;QAAEC,OAAO;IAAO;IAErC,IAAIzB,QAAQO,IAAI,CAACO,aAAa,CAACY,SAAS,EAAE;QACxCJ,IAAIC,GAAG,CAAC,KAAKvB,QAAQO,IAAI,CAACO,aAAa,CAACY,SAAS;QACjDjB,OAAOkB,IAAI,CAAC;IACd;IAEAlB,OAAOkB,IAAI,CAAC,CAAC,SAAS,EAAE7B,OAAOqB,IAAI,CAAC,kBAAkB,CAAC;IACvD,MAAM,EAAES,KAAK,EAAEC,UAAU,EAAE,GAAG,MAAMxC,YAAY6B,WAAW;QAAET;QAAQa;QAAKZ;IAAK;IAC/ED,OAAOkB,IAAI,CAAC;IAEZ,OAAO;QACLE;QACAX;QACAT;QACAmB,OAAO;YACL,MAAMA;YACN,MAAM5B,QAAQ4B,KAAK;QACrB;IACF;AACF"}

package/dist/esm/setup/index.d.ts

@@ -0,0 +1,5 @@
+export { createConfig, parseConfig } from './config.js';
+export { createHTTPServer } from './http.js';
+export { createOAuthAdapters } from './oauth-google.js';
+export * from './runtime.js';
+export { createStdioServer } from './stdio.js';

package/dist/esm/setup/index.js

@@ -0,0 +1,5 @@
+export { createConfig, parseConfig } from './config.js';
+export { createHTTPServer } from './http.js';
+export { createOAuthAdapters } from './oauth-google.js';
+export * from './runtime.js';
+export { createStdioServer } from './stdio.js';