mcp-gsheets 1.8.1 → 1.10.0

package/README.md

@@ -312,6 +312,62 @@ cp .env.example .env
 npm run dev  # Watch mode with auto-reload
 ```
 
+## 🎚️ Reducing context cost with toolsets
+
+All 44 tools together cost about **9,900 tokens of context in every session**,
+before the model does anything. Most workflows need a fraction of that.
+`GSHEETS_TOOLSETS` limits which tools the server exposes:
+
+```json
+{
+  "mcpServers": {
+    "gsheets": {
+      "command": "npx",
+      "args": ["mcp-gsheets"],
+      "env": {
+        "GOOGLE_PROJECT_ID": "your-project-id",
+        "GOOGLE_APPLICATION_CREDENTIALS": "/path/to/key.json",
+        "GSHEETS_TOOLSETS": "core,charts"
+      }
+    }
+  }
+}
+```
+
+| Toolset | Tools | What it covers |
+|---|---|---|
+| `core` | 11 | Read/write values, metadata, sheet structure, create spreadsheet |
+| `sheets` | 9 | Sheet lifecycle, rows and columns |
+| `formatting` | 15 | Colours, borders, merges, conditional rules, links, dates |
+| `charts` | 3 | Create, update, delete charts |
+| `tables` | 4 | Native tables |
+| `analysis` | 2 | Full-sheet snapshot, range comparison |
+
+Measured `tools/list` cost:
+
+| Configuration | Tools | ≈ Tokens |
+|---|---|---|
+| _unset_ (default, all toolsets) | 44 | 9,875 |
+| `GSHEETS_TOOLSETS=core` | 11 | 1,986 |
+| `GSHEETS_TOOLSETS=core,sheets` | 20 | 3,548 |
+| `GSHEETS_READ_ONLY=true` | 16 | 3,599 |
+| `GSHEETS_TOOLSETS=core` + read-only | 6 | 912 |
+
+Notes:
+
+- **The default is unchanged** — leave `GSHEETS_TOOLSETS` unset and you get
+  every tool, exactly as before.
+- **`core` is always included.** `GSHEETS_TOOLSETS=charts` means "charts as
+  well as core", not "charts only" — without core the server cannot read a cell.
+- **A typo is a startup error**, not a silently smaller tool list.
+- `GSHEETS_READ_ONLY=true` drops every writing tool and can be combined with
+  `GSHEETS_TOOLSETS`. It is enforced when a tool is called, not just when the
+  list is built, so a client cannot write by naming a hidden tool.
+
+All tools also carry MCP annotations (`readOnlyHint`, `destructiveHint`,
+`idempotentHint`), so clients can skip confirmation prompts on reads and warn
+before destructive operations.
+
 ## 📋 Available Tools
 
 ### Reading Data
@@ -360,6 +416,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

@@ -18036,6 +18036,141 @@ function validateAuth() {
   }
 }
 
+// src/config/toolsets.ts
+var TOOLSET_NAMES = [
+  "core",
+  "sheets",
+  "formatting",
+  "charts",
+  "tables",
+  "analysis"
+];
+var TOOLSETS = {
+  /** Reading and writing cells, plus the metadata needed to do it safely. */
+  core: [
+    "sheets_check_access",
+    "sheets_get_metadata",
+    "sheets_get_sheet_structure",
+    "sheets_get_sheet_dimensions",
+    "sheets_get_values",
+    "sheets_batch_get_values",
+    "sheets_update_values",
+    "sheets_batch_update_values",
+    "sheets_append_values",
+    "sheets_clear_values",
+    "sheets_create_spreadsheet"
+  ],
+  /** Sheet lifecycle and row/column structure. */
+  sheets: [
+    "sheets_insert_sheet",
+    "sheets_delete_sheet",
+    "sheets_duplicate_sheet",
+    "sheets_copy_to",
+    "sheets_update_sheet_properties",
+    "sheets_batch_delete_sheets",
+    "sheets_insert_rows",
+    "sheets_delete_rows",
+    "sheets_delete_columns"
+  ],
+  /** Cell appearance: colours, borders, merges, conditional rules, links. */
+  formatting: [
+    "sheets_format_cells",
+    "sheets_batch_format_cells",
+    "sheets_update_borders",
+    "sheets_get_border_map",
+    "sheets_merge_cells",
+    "sheets_unmerge_cells",
+    "sheets_get_merged_cells",
+    "sheets_get_sheet_formatting",
+    "sheets_get_formatting_compact",
+    "sheets_add_conditional_formatting",
+    "sheets_get_conditional_formatting",
+    "sheets_get_data_validation",
+    "sheets_get_basic_filter",
+    "sheets_insert_link",
+    "sheets_insert_date"
+  ],
+  charts: ["sheets_create_chart", "sheets_update_chart", "sheets_delete_chart"],
+  tables: ["sheets_add_table", "sheets_update_table", "sheets_delete_table", "sheets_get_tables"],
+  /** Whole-sheet reads and diffing — powerful, but the heaviest schemas. */
+  analysis: ["sheets_get_full_sheet_snapshot", "sheets_compare_ranges"]
+};
+var READ_ONLY_TOOLS = /* @__PURE__ */ new Set([
+  "sheets_check_access",
+  "sheets_get_metadata",
+  "sheets_get_sheet_structure",
+  "sheets_get_sheet_dimensions",
+  "sheets_get_values",
+  "sheets_batch_get_values",
+  "sheets_get_border_map",
+  "sheets_get_merged_cells",
+  "sheets_get_sheet_formatting",
+  "sheets_get_formatting_compact",
+  "sheets_get_conditional_formatting",
+  "sheets_get_data_validation",
+  "sheets_get_basic_filter",
+  "sheets_get_tables",
+  "sheets_get_full_sheet_snapshot",
+  "sheets_compare_ranges"
+]);
+var DESTRUCTIVE_TOOLS = /* @__PURE__ */ new Set([
+  "sheets_clear_values",
+  "sheets_delete_sheet",
+  "sheets_batch_delete_sheets",
+  "sheets_delete_rows",
+  "sheets_delete_columns",
+  "sheets_delete_chart",
+  "sheets_delete_table",
+  "sheets_unmerge_cells"
+]);
+var ToolsetConfigError = class extends Error {
+};
+function parseList(raw) {
+  return raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+}
+function resolveToolsets(env = process.env) {
+  const raw = env.GSHEETS_TOOLSETS?.trim();
+  const readOnly = env.GSHEETS_READ_ONLY?.trim().toLowerCase() === "true";
+  let enabled;
+  if (!raw || raw.toLowerCase() === "all") {
+    enabled = [...TOOLSET_NAMES];
+  } else {
+    const requested = parseList(raw);
+    const unknown2 = requested.filter((n) => !TOOLSET_NAMES.includes(n));
+    if (unknown2.length > 0) {
+      throw new ToolsetConfigError(
+        `Unknown toolset${unknown2.length > 1 ? "s" : ""}: ${unknown2.join(", ")}. Valid toolsets: ${TOOLSET_NAMES.join(", ")}, all.`
+      );
+    }
+    const set = new Set(requested);
+    set.add("core");
+    enabled = TOOLSET_NAMES.filter((n) => set.has(n));
+  }
+  const allowed = /* @__PURE__ */ new Set();
+  for (const name of enabled) {
+    for (const tool of TOOLSETS[name]) {
+      if (readOnly && !READ_ONLY_TOOLS.has(tool)) {
+        continue;
+      }
+      allowed.add(tool);
+    }
+  }
+  return { enabled, readOnly, allowed };
+}
+function annotationsFor(toolName) {
+  if (READ_ONLY_TOOLS.has(toolName)) {
+    return { readOnlyHint: true, idempotentHint: true };
+  }
+  const annotations = {};
+  if (!DESTRUCTIVE_TOOLS.has(toolName)) {
+    annotations.destructiveHint = false;
+  }
+  if (toolName !== "sheets_append_values") {
+    annotations.idempotentHint = true;
+  }
+  return annotations;
+}
+
 // src/utils/error-handler.ts
 function handleError(error2) {
   console.error("Error in Google Sheets operation:", error2);
@@ -18319,7 +18454,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 +20265,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 +23975,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 +24027,10 @@ var allTools = [
   mergeCellsTool,
   unmergeCellsTool,
   addConditionalFormattingTool,
+  addTableTool,
+  updateTableTool,
+  deleteTableTool,
+  getTablesTool,
   batchDeleteSheetsTool,
   batchFormatCellsTool,
   createChartTool,
@@ -23443,6 +24060,23 @@ async function main() {
     console.error("Authentication Error:", error2.message);
     process.exit(1);
   }
+  let toolsetConfig;
+  try {
+    toolsetConfig = resolveToolsets();
+  } catch (error2) {
+    if (error2 instanceof ToolsetConfigError) {
+      console.error(`Configuration Error: ${error2.message}`);
+      process.exit(1);
+    }
+    throw error2;
+  }
+  const { enabled, readOnly, allowed } = toolsetConfig;
+  const exposedTools = allTools.filter((tool) => allowed.has(tool.name)).map((tool) => ({ ...tool, annotations: annotationsFor(tool.name) }));
+  if (enabled.length < Object.keys(TOOLSETS).length || readOnly) {
+    console.error(
+      `Toolsets: ${enabled.join(", ")}${readOnly ? " (read-only)" : ""} \u2014 ${exposedTools.length}/${allTools.length} tools`
+    );
+  }
   const server = new Server(
     {
       name: "spreadsheet",
@@ -23458,11 +24092,16 @@ async function main() {
   );
   server.setRequestHandler(ListToolsRequestSchema, async () => {
     return {
-      tools: allTools
+      tools: exposedTools
     };
   });
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    if (!allowed.has(name)) {
+      throw new Error(
+        toolHandlers.has(name) ? `Tool ${name} is disabled by the current GSHEETS_TOOLSETS/GSHEETS_READ_ONLY configuration` : `Unknown tool: ${name}`
+      );
+    }
     const handler = toolHandlers.get(name);
     if (!handler) {
       throw new Error(`Unknown tool: ${name}`);

package/package.json

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