mcp-gsheets 1.8.1 → 1.9.0

package/README.md

@@ -360,6 +360,15 @@ npm run dev  # Watch mode with auto-reload
 | `sheets_unmerge_cells` | Unmerge previously merged cells in a range | `spreadsheetId`, `range` |
 | `sheets_add_conditional_formatting` | Add a conditional formatting rule (gradient or boolean) to a range | `spreadsheetId`, `range`, `rule` |
 
+### Native Tables
+
+| Tool | Description | Key Parameters |
+|------|-------------|----------------|
+| `sheets_add_table` | Create a native Google Sheets table with typed columns and optional dropdown values | `spreadsheetId`, `sheetName`, `range`, `name`, `columns` |
+| `sheets_update_table` | Update an existing native Google Sheets table by table ID using an explicit field mask | `spreadsheetId`, `tableId`, `fields`, `name`, `range`, `columns` |
+| `sheets_delete_table` | Delete a native Google Sheets table by table ID | `spreadsheetId`, `tableId` |
+| `sheets_get_tables` | Read native tables for a spreadsheet or a specific sheet | `spreadsheetId`, `sheetName` |
+
 ### Charts
 
 | Tool | Description | Key Parameters |

package/dist/index.js

@@ -18319,7 +18319,7 @@ async function getSheetId(sheets, spreadsheetId, sheetName) {
   const sheetsData = response.data.sheets || [];
   if (sheetName) {
     const sheet = sheetsData.find((s) => s.properties?.title === sheetName);
-    if (!sheet?.properties?.sheetId) {
+    if (sheet?.properties?.sheetId === void 0 || sheet.properties.sheetId === null) {
       const availableSheets = sheetsData.map((s) => s.properties?.title).filter((title) => title).join(", ");
       throw new Error(`Sheet "${sheetName}" not found. Available sheets: ${availableSheets}`);
     }
@@ -20130,6 +20130,480 @@ async function addConditionalFormattingHandler(input) {
   }
 }
 
+// src/utils/table-helpers.ts
+var TABLE_COLUMN_TYPES = [
+  "COLUMN_TYPE_UNSPECIFIED",
+  "DOUBLE",
+  "CURRENCY",
+  "PERCENT",
+  "DATE",
+  "TIME",
+  "DATE_TIME",
+  "TEXT",
+  "BOOLEAN",
+  "DROPDOWN",
+  "FILES_CHIP",
+  "PEOPLE_CHIP",
+  "FINANCE_CHIP",
+  "PLACE_CHIP",
+  "RATINGS_CHIP"
+];
+function resolveTableRangeInput(sheetName, range) {
+  const extracted = extractSheetName(range);
+  if (extracted.sheetName && extracted.sheetName !== sheetName) {
+    throw new Error(`Range sheet "${extracted.sheetName}" does not match sheetName "${sheetName}"`);
+  }
+  return {
+    sheetName: extracted.sheetName ?? sheetName,
+    range: extracted.range
+  };
+}
+function buildTableColumnProperties(columns) {
+  return columns.map((column, index) => {
+    const columnProperties = {
+      columnIndex: index,
+      columnName: column.name,
+      columnType: column.columnType
+    };
+    if (column.dropdownValues && column.dropdownValues.length > 0) {
+      columnProperties.dataValidationRule = {
+        condition: {
+          type: "ONE_OF_LIST",
+          values: column.dropdownValues.map((value) => ({ userEnteredValue: value }))
+        }
+      };
+    }
+    return columnProperties;
+  });
+}
+function getRangeColumnCount(range) {
+  if (range.startColumnIndex === void 0 || range.startColumnIndex === null || range.endColumnIndex === void 0 || range.endColumnIndex === null) {
+    return void 0;
+  }
+  return range.endColumnIndex - range.startColumnIndex;
+}
+function validateTableGridRange(range, rangeText) {
+  const startRow = range.startRowIndex;
+  const endRow = range.endRowIndex;
+  const startColumn = range.startColumnIndex;
+  const endColumn = range.endColumnIndex;
+  if (startRow === void 0 || startRow === null || endRow === void 0 || endRow === null || startColumn === void 0 || startColumn === null || endColumn === void 0 || endColumn === null || startRow < 0 || startColumn < 0 || endRow <= startRow || endColumn <= startColumn) {
+    throw new Error(`Invalid table range: ${rangeText}. Use a rectangular A1 range like "A1:D20".`);
+  }
+}
+function validateColumnCount(range, columns, rangeText) {
+  const columnCount = getRangeColumnCount(range);
+  if (columnCount !== void 0 && columnCount !== columns.length) {
+    throw new Error(
+      `Column count mismatch: range ${rangeText} spans ${columnCount} column(s), but ${columns.length} column definition(s) were provided`
+    );
+  }
+}
+function rangesOverlap(first, second) {
+  if (first.sheetId !== void 0 && first.sheetId !== null && second.sheetId !== void 0 && second.sheetId !== null && first.sheetId !== second.sheetId) {
+    return false;
+  }
+  const firstStartRow = first.startRowIndex ?? 0;
+  const firstEndRow = first.endRowIndex ?? Number.POSITIVE_INFINITY;
+  const firstStartColumn = first.startColumnIndex ?? 0;
+  const firstEndColumn = first.endColumnIndex ?? Number.POSITIVE_INFINITY;
+  const secondStartRow = second.startRowIndex ?? 0;
+  const secondEndRow = second.endRowIndex ?? Number.POSITIVE_INFINITY;
+  const secondStartColumn = second.startColumnIndex ?? 0;
+  const secondEndColumn = second.endColumnIndex ?? Number.POSITIVE_INFINITY;
+  return firstStartRow < secondEndRow && firstEndRow > secondStartRow && firstStartColumn < secondEndColumn && firstEndColumn > secondStartColumn;
+}
+function ensureNoOverlappingTable(tables, range, sheetName, excludeTableId) {
+  const overlappingTable = tables.find(
+    (table) => table.tableId !== excludeTableId && table.range && rangesOverlap(table.range, range)
+  );
+  if (!overlappingTable) {
+    return;
+  }
+  const existingRange = overlappingTable.range ? gridRangeToA1(overlappingTable.range) : "unknown";
+  const requestedRange = gridRangeToA1(range);
+  const tableLabel = overlappingTable.name || overlappingTable.tableId || "unnamed table";
+  throw new Error(
+    `Table range ${sheetName}!${requestedRange} overlaps existing table "${tableLabel}" (${sheetName}!${existingRange}). Choose a non-overlapping range or update/delete the existing table.`
+  );
+}
+function formatTableForResponse(table, sheetName) {
+  const range = table.range ? gridRangeToA1(table.range) : null;
+  return {
+    tableId: table.tableId ?? null,
+    name: table.name ?? null,
+    range: range && sheetName ? `${sheetName}!${range}` : range,
+    gridRange: table.range ?? null,
+    columnProperties: table.columnProperties ?? []
+  };
+}
+
+// src/tools/add-table.ts
+var columnSchema = external_exports.object({
+  name: external_exports.string().min(1),
+  columnType: external_exports.enum(TABLE_COLUMN_TYPES),
+  dropdownValues: external_exports.array(external_exports.string()).optional()
+});
+var addTableInputSchema = external_exports.object({
+  spreadsheetId: external_exports.string().min(1),
+  sheetName: external_exports.string().min(1),
+  range: external_exports.string().min(1),
+  name: external_exports.string().min(1),
+  columns: external_exports.array(columnSchema).min(1)
+});
+var addTableTool = {
+  name: "sheets_add_table",
+  description: "Create a native Google Sheets table with typed columns and optional dropdown values",
+  inputSchema: {
+    type: "object",
+    properties: {
+      spreadsheetId: {
+        type: "string",
+        description: "The ID of the spreadsheet (found in the URL after /d/)"
+      },
+      sheetName: {
+        type: "string",
+        description: "Name of the sheet (tab) where the table will be created"
+      },
+      range: {
+        type: "string",
+        description: 'A1 notation range for the table, e.g. "A1:D20" or "Sheet1!A1:D20"'
+      },
+      name: {
+        type: "string",
+        description: "Unique table name within the spreadsheet"
+      },
+      columns: {
+        type: "array",
+        description: "Column definitions for the table",
+        items: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Column name" },
+            columnType: {
+              type: "string",
+              enum: [...TABLE_COLUMN_TYPES],
+              description: "Google Sheets table column type"
+            },
+            dropdownValues: {
+              type: "array",
+              items: { type: "string" },
+              description: "Allowed values for DROPDOWN columns"
+            }
+          },
+          required: ["name", "columnType"]
+        }
+      }
+    },
+    required: ["spreadsheetId", "sheetName", "range", "name", "columns"]
+  }
+};
+async function addTableHandler(input) {
+  try {
+    const validatedInput = addTableInputSchema.parse(input);
+    const sheets = await getAuthenticatedClient();
+    const { sheetName, range } = resolveTableRangeInput(
+      validatedInput.sheetName,
+      validatedInput.range
+    );
+    const sheetId = await getSheetId(sheets, validatedInput.spreadsheetId, sheetName);
+    const gridRange = parseRange(range, sheetId);
+    validateTableGridRange(gridRange, `${sheetName}!${range}`);
+    validateColumnCount(gridRange, validatedInput.columns, `${sheetName}!${range}`);
+    const metadataResponse = await sheets.spreadsheets.get({
+      spreadsheetId: validatedInput.spreadsheetId,
+      fields: "sheets.properties.title,sheets.properties.sheetId,sheets.tables"
+    });
+    const sheetData = findSheetOrThrow(metadataResponse.data.sheets ?? [], sheetName);
+    ensureNoOverlappingTable(sheetData.tables ?? [], gridRange, sheetName);
+    const table = {
+      name: validatedInput.name,
+      range: gridRange,
+      columnProperties: buildTableColumnProperties(validatedInput.columns)
+    };
+    const response = await sheets.spreadsheets.batchUpdate({
+      spreadsheetId: validatedInput.spreadsheetId,
+      requestBody: {
+        requests: [
+          {
+            addTable: {
+              table
+            }
+          }
+        ]
+      }
+    });
+    const addedTable = response.data.replies?.[0]?.addTable?.table ?? table;
+    return formatToolResponse(`Successfully created table "${validatedInput.name}"`, {
+      spreadsheetId: response.data.spreadsheetId,
+      table: formatTableForResponse(addedTable, sheetName)
+    });
+  } catch (error2) {
+    return handleError(error2);
+  }
+}
+
+// src/tools/update-table.ts
+var columnSchema2 = external_exports.object({
+  name: external_exports.string().min(1),
+  columnType: external_exports.enum(TABLE_COLUMN_TYPES),
+  dropdownValues: external_exports.array(external_exports.string()).optional()
+});
+var updateTableInputSchema = external_exports.object({
+  spreadsheetId: external_exports.string().min(1),
+  tableId: external_exports.string().min(1),
+  fields: external_exports.string().min(1),
+  sheetName: external_exports.string().min(1).optional(),
+  range: external_exports.string().min(1).optional(),
+  name: external_exports.string().min(1).optional(),
+  columns: external_exports.array(columnSchema2).min(1).optional()
+}).refine((value) => value.name || value.range || value.columns, {
+  message: "At least one of name, range, or columns must be provided"
+});
+var updateTableTool = {
+  name: "sheets_update_table",
+  description: "Update an existing native Google Sheets table by tableId",
+  inputSchema: {
+    type: "object",
+    properties: {
+      spreadsheetId: {
+        type: "string",
+        description: "The ID of the spreadsheet (found in the URL after /d/)"
+      },
+      tableId: {
+        type: "string",
+        description: "The ID of the table to update"
+      },
+      fields: {
+        type: "string",
+        description: 'Required field mask for the table update, e.g. "name", "range", "columnProperties", or "name,range"'
+      },
+      sheetName: {
+        type: "string",
+        description: "Name of the target sheet when updating the table range"
+      },
+      range: {
+        type: "string",
+        description: 'Optional new A1 notation range for the table, e.g. "A1:D20"'
+      },
+      name: {
+        type: "string",
+        description: "Optional new table name"
+      },
+      columns: {
+        type: "array",
+        description: "Optional replacement column definitions for the table",
+        items: {
+          type: "object",
+          properties: {
+            name: { type: "string", description: "Column name" },
+            columnType: {
+              type: "string",
+              enum: [...TABLE_COLUMN_TYPES],
+              description: "Google Sheets table column type"
+            },
+            dropdownValues: {
+              type: "array",
+              items: { type: "string" },
+              description: "Allowed values for DROPDOWN columns"
+            }
+          },
+          required: ["name", "columnType"]
+        }
+      }
+    },
+    required: ["spreadsheetId", "tableId", "fields"]
+  }
+};
+async function updateTableHandler(input) {
+  try {
+    const validatedInput = updateTableInputSchema.parse(input);
+    const sheets = await getAuthenticatedClient();
+    const metadataResponse = await sheets.spreadsheets.get({
+      spreadsheetId: validatedInput.spreadsheetId,
+      fields: "sheets.properties.title,sheets.properties.sheetId,sheets.tables"
+    });
+    const allSheets = metadataResponse.data.sheets ?? [];
+    const existingTable = allSheets.flatMap((sheet) => sheet.tables ?? []).find((table2) => table2.tableId === validatedInput.tableId);
+    if (!existingTable) {
+      throw new Error(`Table "${validatedInput.tableId}" not found`);
+    }
+    const table = {
+      tableId: validatedInput.tableId
+    };
+    if (validatedInput.name) {
+      table.name = validatedInput.name;
+    }
+    if (validatedInput.columns) {
+      table.columnProperties = buildTableColumnProperties(validatedInput.columns);
+    }
+    let responseSheetName;
+    if (validatedInput.range) {
+      const extracted = extractSheetName(validatedInput.range);
+      const sheetName = validatedInput.sheetName ?? extracted.sheetName;
+      if (!sheetName) {
+        throw new Error("sheetName is required when updating a table range");
+      }
+      const resolvedRange = resolveTableRangeInput(sheetName, validatedInput.range);
+      responseSheetName = resolvedRange.sheetName;
+      const sheetId = await getSheetId(
+        sheets,
+        validatedInput.spreadsheetId,
+        resolvedRange.sheetName
+      );
+      const gridRange = parseRange(resolvedRange.range, sheetId);
+      validateTableGridRange(gridRange, `${resolvedRange.sheetName}!${resolvedRange.range}`);
+      if (validatedInput.columns) {
+        validateColumnCount(
+          gridRange,
+          validatedInput.columns,
+          `${resolvedRange.sheetName}!${resolvedRange.range}`
+        );
+      }
+      const sheetData = findSheetOrThrow(allSheets, resolvedRange.sheetName);
+      ensureNoOverlappingTable(
+        sheetData.tables ?? [],
+        gridRange,
+        resolvedRange.sheetName,
+        validatedInput.tableId
+      );
+      table.range = gridRange;
+    }
+    const response = await sheets.spreadsheets.batchUpdate({
+      spreadsheetId: validatedInput.spreadsheetId,
+      requestBody: {
+        requests: [
+          {
+            updateTable: {
+              table,
+              fields: validatedInput.fields
+            }
+          }
+        ]
+      }
+    });
+    return formatToolResponse(`Successfully updated table "${validatedInput.tableId}"`, {
+      spreadsheetId: response.data.spreadsheetId,
+      table: formatTableForResponse({ ...existingTable, ...table }, responseSheetName),
+      fields: validatedInput.fields
+    });
+  } catch (error2) {
+    return handleError(error2);
+  }
+}
+
+// src/tools/delete-table.ts
+var deleteTableInputSchema = external_exports.object({
+  spreadsheetId: external_exports.string().min(1),
+  tableId: external_exports.string().min(1)
+});
+var deleteTableTool = {
+  name: "sheets_delete_table",
+  description: "Delete a native Google Sheets table by tableId",
+  inputSchema: {
+    type: "object",
+    properties: {
+      spreadsheetId: {
+        type: "string",
+        description: "The ID of the spreadsheet (found in the URL after /d/)"
+      },
+      tableId: {
+        type: "string",
+        description: "The ID of the table to delete"
+      }
+    },
+    required: ["spreadsheetId", "tableId"]
+  }
+};
+async function deleteTableHandler(input) {
+  try {
+    const validatedInput = deleteTableInputSchema.parse(input);
+    const sheets = await getAuthenticatedClient();
+    const metadataResponse = await sheets.spreadsheets.get({
+      spreadsheetId: validatedInput.spreadsheetId,
+      fields: "sheets.tables.tableId"
+    });
+    const tableExists = (metadataResponse.data.sheets ?? []).flatMap((sheet) => sheet.tables ?? []).some((table) => table.tableId === validatedInput.tableId);
+    if (!tableExists) {
+      throw new Error(`Table "${validatedInput.tableId}" not found`);
+    }
+    const response = await sheets.spreadsheets.batchUpdate({
+      spreadsheetId: validatedInput.spreadsheetId,
+      requestBody: {
+        requests: [
+          {
+            deleteTable: {
+              tableId: validatedInput.tableId
+            }
+          }
+        ]
+      }
+    });
+    return formatToolResponse(`Successfully deleted table "${validatedInput.tableId}"`, {
+      spreadsheetId: response.data.spreadsheetId,
+      tableId: validatedInput.tableId
+    });
+  } catch (error2) {
+    return handleError(error2);
+  }
+}
+
+// src/tools/get-tables.ts
+var getTablesInputSchema = external_exports.object({
+  spreadsheetId: external_exports.string().min(1),
+  sheetName: external_exports.string().min(1).optional()
+});
+var getTablesTool = {
+  name: "sheets_get_tables",
+  description: "Read native Google Sheets tables for a spreadsheet or a specific sheet",
+  inputSchema: {
+    type: "object",
+    properties: {
+      spreadsheetId: {
+        type: "string",
+        description: "The ID of the spreadsheet (found in the URL after /d/)"
+      },
+      sheetName: {
+        type: "string",
+        description: "Optional name of the sheet (tab) to inspect"
+      }
+    },
+    required: ["spreadsheetId"]
+  }
+};
+async function getTablesHandler(input) {
+  try {
+    const validatedInput = getTablesInputSchema.parse(input);
+    const sheets = await getAuthenticatedClient();
+    const response = await sheets.spreadsheets.get({
+      spreadsheetId: validatedInput.spreadsheetId,
+      fields: "sheets.properties.title,sheets.properties.sheetId,sheets.tables"
+    });
+    const spreadsheetSheets = response.data.sheets ?? [];
+    const targetSheets = validatedInput.sheetName ? [findSheetOrThrow(spreadsheetSheets, validatedInput.sheetName)] : spreadsheetSheets;
+    const tables = targetSheets.flatMap((sheet) => {
+      const sheetName = sheet.properties?.title ?? void 0;
+      return (sheet.tables ?? []).map((table) => ({
+        sheetName: sheetName ?? null,
+        sheetId: sheet.properties?.sheetId ?? null,
+        ...formatTableForResponse(table, sheetName)
+      }));
+    });
+    const context = validatedInput.sheetName ? ` in sheet "${validatedInput.sheetName}"` : " in spreadsheet";
+    return formatSuccessResponse(
+      {
+        spreadsheetId: validatedInput.spreadsheetId,
+        sheetName: validatedInput.sheetName,
+        tableCount: tables.length,
+        tables
+      },
+      `Found ${tables.length} table(s)${context}`
+    );
+  } catch (error2) {
+    return handleError(error2);
+  }
+}
+
 // src/tools/check-access.ts
 var CheckAccessSchema = external_exports.object({
   spreadsheetId: external_exports.string().describe("The ID of the spreadsheet to check access for")
@@ -23366,6 +23840,10 @@ var toolHandlers = /* @__PURE__ */ new Map([
   ["sheets_merge_cells", mergeCellsHandler],
   ["sheets_unmerge_cells", unmergeCellsHandler],
   ["sheets_add_conditional_formatting", addConditionalFormattingHandler],
+  ["sheets_add_table", addTableHandler],
+  ["sheets_update_table", updateTableHandler],
+  ["sheets_delete_table", deleteTableHandler],
+  ["sheets_get_tables", getTablesHandler],
   // Batch operations
   ["sheets_batch_delete_sheets", handleBatchDeleteSheets],
   ["sheets_batch_format_cells", handleBatchFormatCells],
@@ -23414,6 +23892,10 @@ var allTools = [
   mergeCellsTool,
   unmergeCellsTool,
   addConditionalFormattingTool,
+  addTableTool,
+  updateTableTool,
+  deleteTableTool,
+  getTablesTool,
   batchDeleteSheetsTool,
   batchFormatCellsTool,
   createChartTool,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-gsheets",
-  "version": "1.8.1",
+  "version": "1.9.0",
   "mcpName": "io.github.freema/mcp-gsheets",
   "description": "Model Context Protocol (MCP) server for Google Sheets API integration",
   "author": "freema",