mcp-gsheets 1.7.0 → 1.7.1

package/README.md

@@ -9,7 +9,7 @@
 ![Coverage](https://codecov.io/gh/freema/mcp-gsheets/branch/main/graph/badge.svg)
 ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-007ACC?logo=typescript&logoColor=white)
-![Node](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)
+![Node](https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white)
 ![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?logo=prettier&logoColor=white)
 
 A Model Context Protocol (MCP) server for Google Sheets API integration. Enables reading, writing, and managing Google Sheets documents directly from your MCP client (e.g., Claude Code, Claude Desktop, Cursor, etc.).
@@ -23,7 +23,7 @@ A Model Context Protocol (MCP) server for Google Sheets API integration. Enables
 
 ## Requirements
 
-- [Node.js](https://nodejs.org/) v18 or higher
+- [Node.js](https://nodejs.org/) v20 or higher
 - [Google Cloud Project](https://console.cloud.google.com) with Sheets API enabled
 - Service Account with JSON key file
 - [npm](https://www.npmjs.com/)
@@ -375,6 +375,8 @@ npm run dev  # Watch mode with auto-reload
 | `sheets_get_sheet_structure` | Lightweight structural metadata only — no per-cell data. Returns dimensions, frozen rows/cols, tab colour, column widths, row heights, hidden columns/rows, and all merges in A1 notation. Single fast API call | `spreadsheetId`, `sheetName` |
 | `sheets_get_formatting_compact` | Read cell formatting for a range and return it as compact A1Range→format pairs (run-length encoded). Identical adjacent cells are collapsed into rectangular ranges — reduces output by 90 %+ compared to per-cell data | `spreadsheetId`, `sheetName`, `range`, `useEffectiveFormat`, `fields` |
 | `sheets_get_full_sheet_snapshot` | Master one-shot tool — returns all structural and formatting metadata (merges, dimensions, conditional formatting, and optionally cell formatting) in a single API call. Supports `fields` filter and `compactMode` to limit response size | `spreadsheetId`, `sheetName`, `includeFormattingRange`, `fields`, `compactMode` |
+| `sheets_get_basic_filter` | Read the Basic Filter (AutoFilter) configuration for a sheet, including filtered range, sort specs, and per-column filter criteria (hidden values, conditions, colour filters) | `spreadsheetId`, `sheetName` |
+| `sheets_get_data_validation` | Read data validation rules (checkboxes, dropdowns, custom formulas) from a sheet or range. Returns compact run-length-encoded list of unique rules grouped by cell ranges | `spreadsheetId`, `sheetName`, `range` |
 
 ## 🔧 Code Quality
 

package/dist/index.js

@@ -19472,6 +19472,21 @@ async function handleCopyTo(input) {
 }
 
 // src/utils/range-helpers.ts
+function findSheetOrThrow(sheets, sheetName) {
+  const sheet = sheets.find((s) => s.properties?.title === sheetName);
+  if (!sheet) {
+    const available = sheets.map((s) => s.properties?.title).filter(Boolean).join(", ");
+    throw new Error(`Sheet "${sheetName}" not found. Available: ${available}`);
+  }
+  return sheet;
+}
+function gridRangeToA1(range) {
+  const startCol = range.startColumnIndex ?? 0;
+  const startRow = (range.startRowIndex ?? 0) + 1;
+  const endCol = (range.endColumnIndex ?? startCol + 1) - 1;
+  const endRow = range.endRowIndex ?? startRow;
+  return `${colIndexToLetter(startCol)}${startRow}:${colIndexToLetter(endCol)}${endRow}`;
+}
 function columnToIndex(column) {
   let index = 0;
   for (let i = 0; i < column.length; i++) {
@@ -21402,23 +21417,6 @@ var getMergedCellsTool = {
     required: ["spreadsheetId", "sheetName"]
   }
 };
-function colIndexToLetter2(index) {
-  let result = "";
-  let n = index + 1;
-  while (n > 0) {
-    const rem = (n - 1) % 26;
-    result = String.fromCharCode(65 + rem) + result;
-    n = Math.floor((n - 1) / 26);
-  }
-  return result;
-}
-function gridRangeToA1(startRowIndex, endRowIndex, startColumnIndex, endColumnIndex) {
-  const startCol = colIndexToLetter2(startColumnIndex);
-  const endCol = colIndexToLetter2(endColumnIndex - 1);
-  const startRow = startRowIndex + 1;
-  const endRow = endRowIndex;
-  return `${startCol}${startRow}:${endCol}${endRow}`;
-}
 async function handleGetMergedCells(input) {
   try {
     const { spreadsheetId, sheetName } = inputSchema.parse(input);
@@ -21427,20 +21425,9 @@ async function handleGetMergedCells(input) {
       spreadsheetId,
       fields: "sheets.properties.title,sheets.properties.sheetId,sheets.merges"
     });
-    const sheetData = (response.data.sheets ?? []).find(
-      (s) => s.properties?.title === sheetName
-    );
-    if (!sheetData) {
-      const available = (response.data.sheets ?? []).map((s) => s.properties?.title).filter(Boolean).join(", ");
-      throw new Error(`Sheet "${sheetName}" not found. Available: ${available}`);
-    }
+    const sheetData = findSheetOrThrow(response.data.sheets ?? [], sheetName);
     const merges = (sheetData.merges ?? []).map((m) => ({
-      a1Notation: gridRangeToA1(
-        m.startRowIndex ?? 0,
-        m.endRowIndex ?? 0,
-        m.startColumnIndex ?? 0,
-        m.endColumnIndex ?? 0
-      ),
+      a1Notation: gridRangeToA1(m),
       startRowIndex: m.startRowIndex,
       endRowIndex: m.endRowIndex,
       startColumnIndex: m.startColumnIndex,
@@ -21491,13 +21478,7 @@ async function handleGetSheetDimensions(input) {
       spreadsheetId,
       fields: "sheets.properties,sheets.data.columnMetadata,sheets.data.rowMetadata"
     });
-    const sheetData = (response.data.sheets ?? []).find(
-      (s) => s.properties?.title === sheetName
-    );
-    if (!sheetData) {
-      const available = (response.data.sheets ?? []).map((s) => s.properties?.title).filter(Boolean).join(", ");
-      throw new Error(`Sheet "${sheetName}" not found. Available: ${available}`);
-    }
+    const sheetData = findSheetOrThrow(response.data.sheets ?? [], sheetName);
     const gridProps = sheetData.properties?.gridProperties ?? {};
     const gridData = sheetData.data?.[0] ?? {};
     const columns = (gridData.columnMetadata ?? []).map(
@@ -21650,13 +21631,7 @@ async function handleGetConditionalFormattingData(input) {
       spreadsheetId,
       fields: "sheets.properties.title,sheets.properties.sheetId,sheets.conditionalFormats,sheets.bandedRanges"
     });
-    const sheetData = (response.data.sheets ?? []).find(
-      (s) => s.properties?.title === sheetName
-    );
-    if (!sheetData) {
-      const available = (response.data.sheets ?? []).map((s) => s.properties?.title).filter(Boolean).join(", ");
-      throw new Error(`Sheet "${sheetName}" not found. Available: ${available}`);
-    }
+    const sheetData = findSheetOrThrow(response.data.sheets ?? [], sheetName);
     return formatSuccessResponse(
       {
         sheetName,
@@ -21849,9 +21824,6 @@ var getFullSheetSnapshotTool = {
     required: ["spreadsheetId", "sheetName"]
   }
 };
-function gridRangeToA12(startRowIndex, endRowIndex, startColumnIndex, endColumnIndex) {
-  return `${colIndexToLetter(startColumnIndex)}${startRowIndex + 1}:${colIndexToLetter(endColumnIndex - 1)}${endRowIndex}`;
-}
 async function handleGetFullSheetSnapshot(input) {
   try {
     const {
@@ -21879,23 +21851,12 @@ async function handleGetFullSheetSnapshot(input) {
       includeGridData: !!includeFormattingRange,
       fields: baseFields + cellFormattingFields
     });
-    const sheetData = (response.data.sheets ?? []).find(
-      (s) => s.properties?.title === sheetName
-    );
-    if (!sheetData) {
-      const available = (response.data.sheets ?? []).map((s) => s.properties?.title).filter(Boolean).join(", ");
-      throw new Error(`Sheet "${sheetName}" not found. Available: ${available}`);
-    }
+    const sheetData = findSheetOrThrow(response.data.sheets ?? [], sheetName);
     const props = sheetData.properties;
     const gridProps = props.gridProperties ?? {};
     const gridData = sheetData.data?.[0] ?? {};
     const merges = (sheetData.merges ?? []).map((m) => ({
-      a1Notation: gridRangeToA12(
-        m.startRowIndex ?? 0,
-        m.endRowIndex ?? 0,
-        m.startColumnIndex ?? 0,
-        m.endColumnIndex ?? 0
-      ),
+      a1Notation: gridRangeToA1(m),
       startRowIndex: m.startRowIndex,
       endRowIndex: m.endRowIndex,
       startColumnIndex: m.startColumnIndex,
@@ -22008,13 +21969,7 @@ async function handleGetSheetStructure(input) {
       fields: "sheets.properties,sheets.merges,sheets.data.columnMetadata,sheets.data.rowMetadata"
     });
     const allSheets = response.data.sheets ?? [];
-    const sheetData = allSheets.find(
-      (s) => s.properties?.title === sheetName
-    );
-    if (!sheetData) {
-      const available = allSheets.map((s) => s.properties?.title).filter(Boolean).join(", ");
-      throw new Error(`Sheet "${sheetName}" not found. Available: ${available}`);
-    }
+    const sheetData = findSheetOrThrow(allSheets, sheetName);
     const props = sheetData.properties;
     const gridProps = props.gridProperties ?? {};
     const gridData = sheetData.data?.[0] ?? {};
@@ -22029,13 +21984,9 @@ async function handleGetSheetStructure(input) {
       (row) => row.pixelSize ?? null
     );
     const hiddenRows = (gridData.rowMetadata ?? []).map((row, i) => row.hiddenByUser ? i : -1).filter((i) => i >= 0);
-    const merges = (sheetData.merges ?? []).map((m) => {
-      const sc = m.startColumnIndex ?? 0;
-      const ec = (m.endColumnIndex ?? 1) - 1;
-      const sr = (m.startRowIndex ?? 0) + 1;
-      const er = m.endRowIndex ?? 1;
-      return `${colIndexToLetter(sc)}${sr}:${colIndexToLetter(ec)}${er}`;
-    });
+    const merges = (sheetData.merges ?? []).map(
+      (m) => gridRangeToA1(m)
+    );
     return formatSuccessResponse(
       {
         sheetName,
@@ -22122,13 +22073,7 @@ async function handleGetFormattingCompact(input) {
       fields: `sheets.properties.title,${cellDataFields},sheets.data.startRow,sheets.data.startColumn`
     });
     const allSheets = response.data.sheets ?? [];
-    const sheetData = allSheets.find(
-      (s) => s.properties?.title === sheetName
-    );
-    if (!sheetData) {
-      const available = allSheets.map((s) => s.properties?.title).filter(Boolean).join(", ");
-      throw new Error(`Sheet "${sheetName}" not found. Available: ${available}`);
-    }
+    const sheetData = findSheetOrThrow(allSheets, sheetName);
     const gridData = sheetData.data?.[0];
     if (!gridData?.rowData) {
       return formatSuccessResponse(
@@ -22188,15 +22133,6 @@ var getDataValidationTool = {
     required: ["spreadsheetId", "sheetName"]
   }
 };
-function colToLetter(col) {
-  let letter = "";
-  let c = col;
-  while (c >= 0) {
-    letter = String.fromCharCode(c % 26 + 65) + letter;
-    c = Math.floor(c / 26) - 1;
-  }
-  return letter;
-}
 function validationKey(dv) {
   return JSON.stringify({
     type: dv.condition?.type ?? null,
@@ -22272,8 +22208,8 @@ function compactifyValidation(rowData, startRow, startCol) {
             }
           }
         }
-        const topLeft = `${colToLetter(c + minCol)}${r + minRow + 1}`;
-        const bottomRight = `${colToLetter(endC + minCol)}${endR + minRow + 1}`;
+        const topLeft = `${colIndexToLetter(c + minCol)}${r + minRow + 1}`;
+        const bottomRight = `${colIndexToLetter(endC + minCol)}${endR + minRow + 1}`;
         ranges.push(topLeft === bottomRight ? topLeft : `${topLeft}:${bottomRight}`);
       }
     }
@@ -22298,13 +22234,7 @@ async function handleGetDataValidation(input) {
       includeGridData: true,
       fields: "sheets.data.rowData.values.dataValidation,sheets.data.startRow,sheets.data.startColumn,sheets.properties.title,sheets.properties.sheetId"
     });
-    const sheetData = (response.data.sheets ?? []).find(
-      (s) => s.properties?.title === sheetName
-    );
-    if (!sheetData) {
-      const available = (response.data.sheets ?? []).map((s) => s.properties?.title).filter(Boolean).join(", ");
-      throw new Error(`Sheet "${sheetName}" not found. Available: ${available}`);
-    }
+    const sheetData = findSheetOrThrow(response.data.sheets ?? [], sheetName);
     const gridData = sheetData.data?.[0];
     if (!gridData?.rowData) {
       return formatSuccessResponse(
@@ -22314,11 +22244,7 @@ async function handleGetDataValidation(input) {
     }
     const startRow = gridData.startRow ?? 0;
     const startCol = gridData.startColumn ?? 0;
-    const validationRules = compactifyValidation(
-      gridData.rowData,
-      startRow,
-      startCol
-    );
+    const validationRules = compactifyValidation(gridData.rowData, startRow, startCol);
     return formatSuccessResponse(
       { sheetName, validationRules },
       `Data validation for sheet "${sheetName}" \u2014 ${validationRules.length} unique rule(s)`
@@ -22351,22 +22277,6 @@ var getBasicFilterTool = {
     required: ["spreadsheetId", "sheetName"]
   }
 };
-function colToLetter2(col) {
-  let letter = "";
-  let c = col;
-  while (c >= 0) {
-    letter = String.fromCharCode(c % 26 + 65) + letter;
-    c = Math.floor(c / 26) - 1;
-  }
-  return letter;
-}
-function gridRangeToA13(range) {
-  const startCol = range.startColumnIndex ?? 0;
-  const startRow = (range.startRowIndex ?? 0) + 1;
-  const endCol = (range.endColumnIndex ?? startCol + 1) - 1;
-  const endRow = range.endRowIndex ?? startRow;
-  return `${colToLetter2(startCol)}${startRow}:${colToLetter2(endCol)}${endRow}`;
-}
 async function handleGetBasicFilter(input) {
   try {
     const { spreadsheetId, sheetName } = inputSchema9.parse(input);
@@ -22375,13 +22285,7 @@ async function handleGetBasicFilter(input) {
       spreadsheetId,
       fields: "sheets.properties.title,sheets.properties.sheetId,sheets.basicFilter"
     });
-    const sheetData = (response.data.sheets ?? []).find(
-      (s) => s.properties?.title === sheetName
-    );
-    if (!sheetData) {
-      const available = (response.data.sheets ?? []).map((s) => s.properties?.title).filter(Boolean).join(", ");
-      throw new Error(`Sheet "${sheetName}" not found. Available: ${available}`);
-    }
+    const sheetData = findSheetOrThrow(response.data.sheets ?? [], sheetName);
     const bf = sheetData.basicFilter;
     if (!bf) {
       return formatSuccessResponse(
@@ -22396,7 +22300,7 @@ async function handleGetBasicFilter(input) {
         const fc = spec.filterCriteria;
         filterCriteria.push({
           columnIndex: colIdx,
-          columnLetter: colToLetter2(colIdx),
+          columnLetter: colIndexToLetter(colIdx),
           hiddenValues: fc?.hiddenValues ?? [],
           condition: fc?.condition ?? null,
           visibleBackgroundColor: fc?.visibleBackgroundColor ?? null,
@@ -22409,7 +22313,7 @@ async function handleGetBasicFilter(input) {
         const criteria = fc;
         filterCriteria.push({
           columnIndex: idx,
-          columnLetter: colToLetter2(idx),
+          columnLetter: colIndexToLetter(idx),
           hiddenValues: criteria.hiddenValues ?? [],
           condition: criteria.condition ?? null,
           visibleBackgroundColor: criteria.visibleBackgroundColor ?? null,
@@ -22417,7 +22321,7 @@ async function handleGetBasicFilter(input) {
         });
       }
     }
-    const rangeA1 = bf.range ? gridRangeToA13(bf.range) : null;
+    const rangeA1 = bf.range ? gridRangeToA1(bf.range) : null;
     return formatSuccessResponse(
       {
         sheetName,
@@ -22426,7 +22330,7 @@ async function handleGetBasicFilter(input) {
           range: rangeA1,
           sortSpecs: (bf.sortSpecs ?? []).map((s) => ({
             columnIndex: s.dimensionIndex,
-            columnLetter: s.dimensionIndex !== null && s.dimensionIndex !== void 0 ? colToLetter2(s.dimensionIndex) : null,
+            columnLetter: s.dimensionIndex !== null && s.dimensionIndex !== void 0 ? colIndexToLetter(s.dimensionIndex) : null,
             sortOrder: s.sortOrder ?? null
           })),
           filterCriteria
@@ -22935,7 +22839,7 @@ async function main() {
   const server = new Server(
     {
       name: "spreadsheet",
-      version: "1.6.0"
+      version: "1.7.1"
     },
     {
       capabilities: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-gsheets",
-  "version": "1.7.0",
+  "version": "1.7.1",
   "description": "Model Context Protocol (MCP) server for Google Sheets API integration",
   "author": "freema",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "ai"
   ],
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",