gogcli-mcp 2.0.12 → 2.3.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
-    "version": "2.0.12"
+    "version": "2.3.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli",
       "source": "./",
       "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
-      "version": "2.0.12",
+      "version": "2.3.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp",
   "displayName": "gogcli",
-  "version": "2.0.12",
+  "version": "2.3.0",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",

package/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+## [2.1.0](https://github.com/chrischall/gogcli-mcp/compare/v2.0.13...v2.1.0) (2026-05-25)
+
+
+### Features
+
+* add gogcli-mcp-slides and gogcli-mcp-classroom sub-packages ([cee8724](https://github.com/chrischall/gogcli-mcp/commit/cee872442240e52ae1cac9b9085eabce0c5ff9c3))
+* add manifest.json and SKILL.md to sub-packages for .mcpb and .skill builds ([d1339c6](https://github.com/chrischall/gogcli-mcp/commit/d1339c690b1eeee8221b7cc15fd9e4fa48c1e20a))
+* address open issues for docs + sheets ([7109253](https://github.com/chrischall/gogcli-mcp/commit/7109253b3eb4b3dcc17cda7a8dfb1b6969023bcf))
+* **deploy:** per-sub-package registry listings (MCP Registry, ClawHub, Claude plugins) ([6cc1798](https://github.com/chrischall/gogcli-mcp/commit/6cc1798320af6dd3af709790e6bec30f46c5f3d2))
+* **drive:** add gogcli-mcp-drive sub-package ([d8eef61](https://github.com/chrischall/gogcli-mcp/commit/d8eef61f16266209da70cd05ca0d2378bf3c4613))
+* fold People into contacts and Meet into calendar; add TODO.md ([f649119](https://github.com/chrischall/gogcli-mcp/commit/f64911902094f87ae31420913e9d1a5ba608441f))
+* wrap new gog cli v0.18.0 tools ([173242a](https://github.com/chrischall/gogcli-mcp/commit/173242aafaa8c2f2d7282a2fbd8faedfc65a63bd))
+
+
+### Bug Fixes
+
+* emit type declarations from base so sub-packages can resolve gogcli-mcp/lib ([9cee5ed](https://github.com/chrischall/gogcli-mcp/commit/9cee5ed97b0cc72dde81c7f8a01d71c95a0291b7))
+* **mcpb:** add per-sub-package .mcpbignore to trim bundles ([e739d9e](https://github.com/chrischall/gogcli-mcp/commit/e739d9ec9ae8e4cc19b1189bb5bf7ac90481c943))
+* **runner:** augment PATH + helpful ENOENT message for missing gog ([34e696f](https://github.com/chrischall/gogcli-mcp/commit/34e696f8c74c7003e6b1bb31991a05184a3b6094))
+* **runner:** fall back to PATH lookup when GOG_PATH is empty string ([a726592](https://github.com/chrischall/gogcli-mcp/commit/a726592c86e869fe27b176798a9b8909e7821f4c))
+* **runner:** treat unresolved .mcpb placeholders as unset env vars ([17a0363](https://github.com/chrischall/gogcli-mcp/commit/17a0363f7dffd2757667e0d1d9377e2e2cb6fbc7))
+* treat empty GOG_PATH as unset, fall back to 'gog' on PATH ([0204638](https://github.com/chrischall/gogcli-mcp/commit/020463813f941b1fa8ec2360346c55abc244675f))
+
+
+### Refactor
+
+* aggressive cleanup pass (audit findings) ([e635b39](https://github.com/chrischall/gogcli-mcp/commit/e635b391cf611e9c102a422ffbce5ebe28687b80))
+* make sub-packages focused (auth + service only) ([4301306](https://github.com/chrischall/gogcli-mcp/commit/4301306cecf12e66d67dbc4ce9debae8f3dcfabc))
+* rebalance base vs sub-package tool split (120 -> 84 base) ([1074953](https://github.com/chrischall/gogcli-mcp/commit/1074953833fc4766e85cc0b28cbcc08834f8dc47))
+* remove comments escape hatch from base docs tool ([a5364c6](https://github.com/chrischall/gogcli-mcp/commit/a5364c6df1948e57b185b9d753aa11b033edd0d0))
+* restructure into npm workspaces monorepo ([9645100](https://github.com/chrischall/gogcli-mcp/commit/9645100e8120c03956ee972023b12d2e99876cc5))
+* review-pass cleanup (enums, shared schemas, test harness) ([ea851de](https://github.com/chrischall/gogcli-mcp/commit/ea851deb30b9cfef3f07ed506a011fc363b34018))
+* use relative imports instead of workspace symlinks ([a278d6f](https://github.com/chrischall/gogcli-mcp/commit/a278d6fb31be480571481e9d87e199d261a3f031))
+
+
+### Documentation
+
+* add per-package READMEs, update root README and CLAUDE.md for monorepo ([19d547e](https://github.com/chrischall/gogcli-mcp/commit/19d547e5ceb14298a75ab297d0a9a11c6ea59e24))
+* fix tool counts and stale descriptions across all docs ([3558c72](https://github.com/chrischall/gogcli-mcp/commit/3558c72fa5c3ee3dbc8a06e9d7fb51bf73ef77c7))
+* update gogcli repo URLs to openclaw/gogcli (was steipete/gogcli) ([951a181](https://github.com/chrischall/gogcli-mcp/commit/951a1818ebc269f203aee723ccbea32c13817d8b))

package/dist/index.js

@@ -31074,7 +31074,7 @@ async function run(args, options = {}) {
 
 // src/tools/utils.ts
 var accountParam = external_exports.string().optional().describe(
-  "Google account email to use (overrides GOG_ACCOUNT env var)"
+  "Google account email to use, e.g. you@gmail.com \u2014 must be the full address, not a bare username. Overrides the GOG_ACCOUNT env var. Omit to use the single configured account."
 );
 var ids = {
   course: external_exports.string().describe("Course ID"),
@@ -31133,26 +31133,41 @@ function toError(err) {
 }
 var AUTH_ERROR_PATTERN = /\b(401|unauthorized|token.*(expired|revoked)|invalid_grant)\b/i;
 var TRANSIENT_ERROR_PATTERN = /\b429\b|\b5\d\d\b|\bquota\b|rateLimit|\bDEADLINE_EXCEEDED\b/i;
+var GRID_LIMIT_ERROR_PATTERN = /exceeds grid limits/i;
 var AUTH_HINT = "\n\nAuthentication may have expired. Use gog_auth_add to re-authorize the account. Ask the user if they would like to re-authenticate.";
 var TRANSIENT_HINT = "\n\nThis error is often transient. Retry the same call before trying a different approach (do not fall back to smaller writes or row-by-row operations).";
+var GRID_LIMIT_HINT = "\n\nThe target range is outside the sheet's current grid. Add the missing rows or columns first with gog_sheets_insert (dimension: rows or cols), then retry the write.";
+function formatAccountList(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed?.accounts)) {
+      return parsed.accounts.map((a) => a?.email).filter(Boolean).join("\n");
+    }
+  } catch {
+  }
+  return raw.trim();
+}
+async function diagnose(err) {
+  const errText = toError(err).content[0].text;
+  const isAuthError = AUTH_ERROR_PATTERN.test(errText);
+  const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
+  const isGridLimitError = GRID_LIMIT_ERROR_PATTERN.test(errText);
+  const hint = isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : isGridLimitError ? GRID_LIMIT_HINT : "";
+  try {
+    const accounts = formatAccountList(await run(["auth", "list"]));
+    return toText(`${errText}
+
+Configured accounts:
+${accounts || "(none)"}${hint}`);
+  } catch {
+    return toText(`${errText}${hint}`);
+  }
+}
 async function runOrDiagnose(args, options) {
   try {
     return toText(await run(args, options));
   } catch (err) {
-    const base = toError(err);
-    const errText = base.content[0].text;
-    const isAuthError = AUTH_ERROR_PATTERN.test(errText);
-    const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
-    const hint = isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : "";
-    try {
-      const accounts = await run(["auth", "list"]);
-      return toText(`${errText}
-
-Configured accounts:
-${accounts}${hint}`);
-    } catch {
-      return toText(`${errText}${hint}`);
-    }
+    return diagnose(err);
   }
 }
 
@@ -31941,7 +31956,7 @@ function registerDriveTools(server2) {
 // src/tools/gmail.ts
 function registerGmailTools(server2) {
   server2.registerTool("gog_gmail_search", {
-    description: 'Search Gmail threads using Gmail query syntax (e.g. "from:alice subject:invoice is:unread").',
+    description: `Search Gmail threads using Gmail query syntax (e.g. "from:alice subject:invoice is:unread"). The query is passed verbatim to Gmail; a bare name token (from:alison) matches per Gmail's own heuristics, a full address (from:alison@example.com) is exact. To match a contact across several addresses, OR them: from:(a@x.com OR b@y.com).`,
     annotations: { readOnlyHint: true },
     inputSchema: {
       query: external_exports.string().describe("Gmail search query"),
@@ -31990,8 +32005,62 @@ function registerGmailTools(server2) {
   registerRunTool(server2, { service: "gmail", examples: '"archive", "mark-read", "labels"' });
 }
 
+// src/tools/sheets-a1.ts
+function colToLetter(n) {
+  let s = "";
+  while (n > 0) {
+    const rem = (n - 1) % 26;
+    s = String.fromCharCode(65 + rem) + s;
+    n = Math.floor((n - 1) / 26);
+  }
+  return s;
+}
+function letterToCol(s) {
+  let n = 0;
+  for (const ch of s.toUpperCase()) {
+    n = n * 26 + (ch.charCodeAt(0) - 64);
+  }
+  return n;
+}
+function expandAnchorRange(range, rows, cols) {
+  const bang = range.lastIndexOf("!");
+  const sheet = bang >= 0 ? range.slice(0, bang + 1) : "";
+  const cell = bang >= 0 ? range.slice(bang + 1) : range;
+  const m = /^([A-Za-z]+)([0-9]+)$/.exec(cell);
+  if (!m) return range;
+  const startCol = letterToCol(m[1]);
+  const startRow = parseInt(m[2], 10);
+  const endCol = colToLetter(startCol + cols - 1);
+  const endRow = startRow + rows - 1;
+  return `${sheet}${m[1].toUpperCase()}${startRow}:${endCol}${endRow}`;
+}
+function countNonEmptyCells(getOutput) {
+  let parsed;
+  try {
+    parsed = JSON.parse(getOutput);
+  } catch {
+    return -1;
+  }
+  const values = parsed?.values;
+  if (!Array.isArray(values)) return 0;
+  let count = 0;
+  for (const row of values) {
+    if (!Array.isArray(row)) continue;
+    for (const cell of row) {
+      if (cell !== null && String(cell).trim() !== "") count++;
+    }
+  }
+  return count;
+}
+
 // src/tools/sheets.ts
 var cellValueParam = external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean(), external_exports.null()]);
+var dryRunParam = external_exports.boolean().optional().describe(
+  "Preview the operation without modifying the sheet (gog --dry-run): reports the intended actions and exits without writing."
+);
+var failIfNotEmptyParam = external_exports.boolean().optional().describe(
+  'Safety guard against silent overwrites: before writing, read the target range and refuse the write if any target cell already holds data. Costs one extra read. Anchor ranges (e.g. "Sheet1!A1") are expanded to the full area your values will cover; explicit and named ranges are checked as-is.'
+);
 function registerSheetsTools(server2) {
   server2.registerTool("gog_sheets_get", {
     description: 'Read values from a Google Sheets range. Returns a JSON object with a "values" array of rows.',
@@ -32011,13 +32080,31 @@ function registerSheetsTools(server2) {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID (from the URL)"),
       range: external_exports.string().describe("Top-left cell or range in A1 notation, e.g. Sheet1!A1"),
       values: external_exports.array(external_exports.array(cellValueParam)).describe('2D array of values (rows of columns). Cells may be string/number/boolean/null; strings starting with "=" are formulas.'),
+      dry_run: dryRunParam,
+      fail_if_not_empty: failIfNotEmptyParam,
       account: accountParam
     }
-  }, async ({ spreadsheetId, range, values, account }) => {
-    return runOrDiagnose(
-      ["sheets", "update", spreadsheetId, range, `--values-json=${JSON.stringify(values)}`],
-      { account }
-    );
+  }, async ({ spreadsheetId, range, values, account, dry_run, fail_if_not_empty }) => {
+    const cols = values.reduce((max, row) => Math.max(max, row.length), 0);
+    if (fail_if_not_empty && values.length > 0 && cols > 0) {
+      const readRange = expandAnchorRange(range, values.length, cols);
+      let existing;
+      try {
+        existing = await run(["sheets", "get", spreadsheetId, readRange], { account });
+      } catch (err) {
+        return diagnose(err);
+      }
+      const occupied = countNonEmptyCells(existing);
+      if (occupied !== 0) {
+        const detail = occupied < 0 ? "could not be verified as empty" : `already contains data in ${occupied} cell(s)`;
+        return toText(
+          `Write aborted (fail_if_not_empty): target range ${readRange} ${detail}. Re-run without fail_if_not_empty to overwrite, or clear it first with gog_sheets_clear.`
+        );
+      }
+    }
+    const args = ["sheets", "update", spreadsheetId, range, `--values-json=${JSON.stringify(values)}`];
+    if (dry_run) args.push("--dry-run");
+    return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_sheets_append", {
     description: 'Append rows to a Google Sheet after the last row with data in the given range. Values may be strings, numbers, booleans, or null. Strings starting with "=" are interpreted as formulas.',
@@ -32026,13 +32113,13 @@ function registerSheetsTools(server2) {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID (from the URL)"),
       range: external_exports.string().describe("Range indicating which sheet/columns to append to, e.g. Sheet1!A:C"),
       values: external_exports.array(external_exports.array(cellValueParam)).describe('2D array of rows to append. Cells may be string/number/boolean/null; strings starting with "=" are formulas.'),
+      dry_run: dryRunParam,
       account: accountParam
     }
-  }, async ({ spreadsheetId, range, values, account }) => {
-    return runOrDiagnose(
-      ["sheets", "append", spreadsheetId, range, `--values-json=${JSON.stringify(values)}`],
-      { account }
-    );
+  }, async ({ spreadsheetId, range, values, account, dry_run }) => {
+    const args = ["sheets", "append", spreadsheetId, range, `--values-json=${JSON.stringify(values)}`];
+    if (dry_run) args.push("--dry-run");
+    return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_sheets_clear", {
     description: "Clear all values in a Google Sheets range (formatting is preserved).",
@@ -32040,13 +32127,16 @@ function registerSheetsTools(server2) {
     inputSchema: {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
       range: external_exports.string().describe("Range in A1 notation to clear"),
+      dry_run: dryRunParam,
       account: accountParam
     }
-  }, async ({ spreadsheetId, range, account }) => {
-    return runOrDiagnose(["sheets", "clear", spreadsheetId, range], { account });
+  }, async ({ spreadsheetId, range, account, dry_run }) => {
+    const args = ["sheets", "clear", spreadsheetId, range];
+    if (dry_run) args.push("--dry-run");
+    return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_sheets_metadata", {
-    description: "Get spreadsheet metadata: title, sheet tabs, named ranges, and other properties.",
+    description: "Get spreadsheet metadata: title, named ranges, and per-tab properties including grid dimensions (gridProperties.rowCount / columnCount). Use this to learn a sheet's current size before writing \u2014 a write outside the grid fails.",
     annotations: { readOnlyHint: true },
     inputSchema: {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
@@ -32232,7 +32322,7 @@ function registerTasksTools(server2) {
 }
 
 // src/server.ts
-var VERSION = true ? "2.0.12" : "0.0.0";
+var VERSION = true ? "2.3.0" : "0.0.0";
 function createServer(options) {
   return new McpServer({
     name: options?.name ?? "gogcli",

package/dist/lib.js

@@ -30859,6 +30859,7 @@ var EMPTY_COMPLETION_RESULT = {
 import { spawn } from "node:child_process";
 import { delimiter } from "node:path";
 var TIMEOUT_MS = 3e4;
+var MIN_GOG_VERSION = "0.19.0";
 function envOrUndefined(key) {
   const value = process.env[key];
   if (!value || value.startsWith("${")) return void 0;
@@ -30981,7 +30982,7 @@ async function run(args, options = {}) {
 
 // src/tools/utils.ts
 var accountParam = external_exports.string().optional().describe(
-  "Google account email to use (overrides GOG_ACCOUNT env var)"
+  "Google account email to use, e.g. you@gmail.com \u2014 must be the full address, not a bare username. Overrides the GOG_ACCOUNT env var. Omit to use the single configured account."
 );
 var ids = {
   course: external_exports.string().describe("Course ID"),
@@ -31045,26 +31046,41 @@ function toError(err) {
 }
 var AUTH_ERROR_PATTERN = /\b(401|unauthorized|token.*(expired|revoked)|invalid_grant)\b/i;
 var TRANSIENT_ERROR_PATTERN = /\b429\b|\b5\d\d\b|\bquota\b|rateLimit|\bDEADLINE_EXCEEDED\b/i;
+var GRID_LIMIT_ERROR_PATTERN = /exceeds grid limits/i;
 var AUTH_HINT = "\n\nAuthentication may have expired. Use gog_auth_add to re-authorize the account. Ask the user if they would like to re-authenticate.";
 var TRANSIENT_HINT = "\n\nThis error is often transient. Retry the same call before trying a different approach (do not fall back to smaller writes or row-by-row operations).";
+var GRID_LIMIT_HINT = "\n\nThe target range is outside the sheet's current grid. Add the missing rows or columns first with gog_sheets_insert (dimension: rows or cols), then retry the write.";
+function formatAccountList(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (Array.isArray(parsed?.accounts)) {
+      return parsed.accounts.map((a) => a?.email).filter(Boolean).join("\n");
+    }
+  } catch {
+  }
+  return raw.trim();
+}
+async function diagnose(err) {
+  const errText = toError(err).content[0].text;
+  const isAuthError = AUTH_ERROR_PATTERN.test(errText);
+  const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
+  const isGridLimitError = GRID_LIMIT_ERROR_PATTERN.test(errText);
+  const hint = isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : isGridLimitError ? GRID_LIMIT_HINT : "";
+  try {
+    const accounts = formatAccountList(await run(["auth", "list"]));
+    return toText(`${errText}
+
+Configured accounts:
+${accounts || "(none)"}${hint}`);
+  } catch {
+    return toText(`${errText}${hint}`);
+  }
+}
 async function runOrDiagnose(args, options) {
   try {
     return toText(await run(args, options));
   } catch (err) {
-    const base = toError(err);
-    const errText = base.content[0].text;
-    const isAuthError = AUTH_ERROR_PATTERN.test(errText);
-    const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
-    const hint = isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : "";
-    try {
-      const accounts = await run(["auth", "list"]);
-      return toText(`${errText}
-
-Configured accounts:
-${accounts}${hint}`);
-    } catch {
-      return toText(`${errText}${hint}`);
-    }
+    return diagnose(err);
   }
 }
 
@@ -31853,7 +31869,7 @@ function registerDriveTools(server) {
 // src/tools/gmail.ts
 function registerGmailTools(server) {
   server.registerTool("gog_gmail_search", {
-    description: 'Search Gmail threads using Gmail query syntax (e.g. "from:alice subject:invoice is:unread").',
+    description: `Search Gmail threads using Gmail query syntax (e.g. "from:alice subject:invoice is:unread"). The query is passed verbatim to Gmail; a bare name token (from:alison) matches per Gmail's own heuristics, a full address (from:alison@example.com) is exact. To match a contact across several addresses, OR them: from:(a@x.com OR b@y.com).`,
     annotations: { readOnlyHint: true },
     inputSchema: {
       query: external_exports.string().describe("Gmail search query"),
@@ -31902,8 +31918,62 @@ function registerGmailTools(server) {
   registerRunTool(server, { service: "gmail", examples: '"archive", "mark-read", "labels"' });
 }
 
+// src/tools/sheets-a1.ts
+function colToLetter(n) {
+  let s = "";
+  while (n > 0) {
+    const rem = (n - 1) % 26;
+    s = String.fromCharCode(65 + rem) + s;
+    n = Math.floor((n - 1) / 26);
+  }
+  return s;
+}
+function letterToCol(s) {
+  let n = 0;
+  for (const ch of s.toUpperCase()) {
+    n = n * 26 + (ch.charCodeAt(0) - 64);
+  }
+  return n;
+}
+function expandAnchorRange(range, rows, cols) {
+  const bang = range.lastIndexOf("!");
+  const sheet = bang >= 0 ? range.slice(0, bang + 1) : "";
+  const cell = bang >= 0 ? range.slice(bang + 1) : range;
+  const m = /^([A-Za-z]+)([0-9]+)$/.exec(cell);
+  if (!m) return range;
+  const startCol = letterToCol(m[1]);
+  const startRow = parseInt(m[2], 10);
+  const endCol = colToLetter(startCol + cols - 1);
+  const endRow = startRow + rows - 1;
+  return `${sheet}${m[1].toUpperCase()}${startRow}:${endCol}${endRow}`;
+}
+function countNonEmptyCells(getOutput) {
+  let parsed;
+  try {
+    parsed = JSON.parse(getOutput);
+  } catch {
+    return -1;
+  }
+  const values = parsed?.values;
+  if (!Array.isArray(values)) return 0;
+  let count = 0;
+  for (const row of values) {
+    if (!Array.isArray(row)) continue;
+    for (const cell of row) {
+      if (cell !== null && String(cell).trim() !== "") count++;
+    }
+  }
+  return count;
+}
+
 // src/tools/sheets.ts
 var cellValueParam = external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean(), external_exports.null()]);
+var dryRunParam = external_exports.boolean().optional().describe(
+  "Preview the operation without modifying the sheet (gog --dry-run): reports the intended actions and exits without writing."
+);
+var failIfNotEmptyParam = external_exports.boolean().optional().describe(
+  'Safety guard against silent overwrites: before writing, read the target range and refuse the write if any target cell already holds data. Costs one extra read. Anchor ranges (e.g. "Sheet1!A1") are expanded to the full area your values will cover; explicit and named ranges are checked as-is.'
+);
 function registerSheetsTools(server) {
   server.registerTool("gog_sheets_get", {
     description: 'Read values from a Google Sheets range. Returns a JSON object with a "values" array of rows.',
@@ -31923,13 +31993,31 @@ function registerSheetsTools(server) {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID (from the URL)"),
       range: external_exports.string().describe("Top-left cell or range in A1 notation, e.g. Sheet1!A1"),
       values: external_exports.array(external_exports.array(cellValueParam)).describe('2D array of values (rows of columns). Cells may be string/number/boolean/null; strings starting with "=" are formulas.'),
+      dry_run: dryRunParam,
+      fail_if_not_empty: failIfNotEmptyParam,
       account: accountParam
     }
-  }, async ({ spreadsheetId, range, values, account }) => {
-    return runOrDiagnose(
-      ["sheets", "update", spreadsheetId, range, `--values-json=${JSON.stringify(values)}`],
-      { account }
-    );
+  }, async ({ spreadsheetId, range, values, account, dry_run, fail_if_not_empty }) => {
+    const cols = values.reduce((max, row) => Math.max(max, row.length), 0);
+    if (fail_if_not_empty && values.length > 0 && cols > 0) {
+      const readRange = expandAnchorRange(range, values.length, cols);
+      let existing;
+      try {
+        existing = await run(["sheets", "get", spreadsheetId, readRange], { account });
+      } catch (err) {
+        return diagnose(err);
+      }
+      const occupied = countNonEmptyCells(existing);
+      if (occupied !== 0) {
+        const detail = occupied < 0 ? "could not be verified as empty" : `already contains data in ${occupied} cell(s)`;
+        return toText(
+          `Write aborted (fail_if_not_empty): target range ${readRange} ${detail}. Re-run without fail_if_not_empty to overwrite, or clear it first with gog_sheets_clear.`
+        );
+      }
+    }
+    const args = ["sheets", "update", spreadsheetId, range, `--values-json=${JSON.stringify(values)}`];
+    if (dry_run) args.push("--dry-run");
+    return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_sheets_append", {
     description: 'Append rows to a Google Sheet after the last row with data in the given range. Values may be strings, numbers, booleans, or null. Strings starting with "=" are interpreted as formulas.',
@@ -31938,13 +32026,13 @@ function registerSheetsTools(server) {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID (from the URL)"),
       range: external_exports.string().describe("Range indicating which sheet/columns to append to, e.g. Sheet1!A:C"),
       values: external_exports.array(external_exports.array(cellValueParam)).describe('2D array of rows to append. Cells may be string/number/boolean/null; strings starting with "=" are formulas.'),
+      dry_run: dryRunParam,
       account: accountParam
     }
-  }, async ({ spreadsheetId, range, values, account }) => {
-    return runOrDiagnose(
-      ["sheets", "append", spreadsheetId, range, `--values-json=${JSON.stringify(values)}`],
-      { account }
-    );
+  }, async ({ spreadsheetId, range, values, account, dry_run }) => {
+    const args = ["sheets", "append", spreadsheetId, range, `--values-json=${JSON.stringify(values)}`];
+    if (dry_run) args.push("--dry-run");
+    return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_sheets_clear", {
     description: "Clear all values in a Google Sheets range (formatting is preserved).",
@@ -31952,13 +32040,16 @@ function registerSheetsTools(server) {
     inputSchema: {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
       range: external_exports.string().describe("Range in A1 notation to clear"),
+      dry_run: dryRunParam,
       account: accountParam
     }
-  }, async ({ spreadsheetId, range, account }) => {
-    return runOrDiagnose(["sheets", "clear", spreadsheetId, range], { account });
+  }, async ({ spreadsheetId, range, account, dry_run }) => {
+    const args = ["sheets", "clear", spreadsheetId, range];
+    if (dry_run) args.push("--dry-run");
+    return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_sheets_metadata", {
-    description: "Get spreadsheet metadata: title, sheet tabs, named ranges, and other properties.",
+    description: "Get spreadsheet metadata: title, named ranges, and per-tab properties including grid dimensions (gridProperties.rowCount / columnCount). Use this to learn a sheet's current size before writing \u2014 a write outside the grid fails.",
     annotations: { readOnlyHint: true },
     inputSchema: {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
@@ -32144,7 +32235,7 @@ function registerTasksTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "2.0.12" : "0.0.0";
+var VERSION = true ? "2.3.0" : "0.0.0";
 function createServer(options) {
   return new McpServer({
     name: options?.name ?? "gogcli",
@@ -32166,6 +32257,7 @@ function createBaseServer(options) {
   return server;
 }
 export {
+  MIN_GOG_VERSION,
   VERSION,
   accountParam,
   createBaseServer,

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "2.0.12",
+  "version": "2.3.0",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp",
-  "version": "2.0.12",
+  "version": "2.3.0",
   "mcpName": "io.github.chrischall/gogcli-mcp",
   "description": "MCP server wrapping gogcli for Google service access",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -45,8 +45,8 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^25.6.2",
-    "@vitest/coverage-v8": "^4.1.6",
+    "@types/node": "^25.9.1",
+    "@vitest/coverage-v8": "^4.1.7",
     "esbuild": "^0.28.0",
     "typescript": "^6.0.2",
     "vitest": "^4.1.6"

package/server.json

@@ -7,12 +7,12 @@
     "source": "github",
     "subfolder": "packages/gogcli-mcp"
   },
-  "version": "2.0.12",
+  "version": "2.3.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "gogcli-mcp",
-      "version": "2.0.12",
+      "version": "2.3.0",
       "transport": {
         "type": "stdio"
       },

package/src/lib.ts

@@ -13,7 +13,7 @@ export {
   registerSlidesTools,
   registerTasksTools,
 } from './server.js';
-export { run } from './runner.js';
+export { run, MIN_GOG_VERSION } from './runner.js';
 export type { RunOptions, Spawner } from './runner.js';
 export {
   accountParam,

package/src/runner.ts

@@ -17,6 +17,14 @@ export interface RunOptions {
 
 const TIMEOUT_MS = 30_000;
 
+// Minimum gogcli (`gog`) binary version this wrapper's tools assume. Some tools
+// pass flags/subcommands that only exist in newer gog, so bump this whenever a
+// change starts relying on a newer gog feature — and label that PR `gogcli-bump`
+// so the requirement change is surfaced in the release notes (see
+// .github/release.yml). This is the single source of truth for the required
+// version; keep the README/CLAUDE.md mention in sync.
+export const MIN_GOG_VERSION = '0.19.0';
+
 // Treat unresolved .mcpb placeholders ("${user_config.gog_path}") and empty
 // strings the same as an unset env var. When an optional .mcpb user_config
 // field is left blank, some clients pass the literal placeholder text through

package/src/tools/gmail.ts

@@ -4,7 +4,7 @@ import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
 
 export function registerGmailTools(server: McpServer): void {
   server.registerTool('gog_gmail_search', {
-    description: 'Search Gmail threads using Gmail query syntax (e.g. "from:alice subject:invoice is:unread").',
+    description: 'Search Gmail threads using Gmail query syntax (e.g. "from:alice subject:invoice is:unread"). The query is passed verbatim to Gmail; a bare name token (from:alison) matches per Gmail\'s own heuristics, a full address (from:alison@example.com) is exact. To match a contact across several addresses, OR them: from:(a@x.com OR b@y.com).',
     annotations: { readOnlyHint: true },
     inputSchema: {
       query: z.string().describe('Gmail search query'),

package/src/tools/sheets-a1.ts

@@ -0,0 +1,64 @@
+// A1-notation helpers for the fail_if_not_empty write guard. Kept separate
+// from sheets.ts so the pure range/value math is unit-testable in isolation.
+
+// 1 -> "A", 26 -> "Z", 27 -> "AA" (bijective base-26).
+function colToLetter(n: number): string {
+  let s = '';
+  while (n > 0) {
+    const rem = (n - 1) % 26;
+    s = String.fromCharCode(65 + rem) + s;
+    n = Math.floor((n - 1) / 26);
+  }
+  return s;
+}
+
+// "A" -> 1, "AA" -> 27.
+function letterToCol(s: string): number {
+  let n = 0;
+  for (const ch of s.toUpperCase()) {
+    n = n * 26 + (ch.charCodeAt(0) - 64);
+  }
+  return n;
+}
+
+// Given the target `range` of an update and the shape of the values being
+// written, return the range the guard should read to cover every written cell.
+//
+// A bare anchor cell ("Sheet1!A1") is expanded to the full written area
+// ("Sheet1!A1:D70"). An explicit range (contains ":") or a named range is
+// returned unchanged — the caller asked us to check exactly that span.
+export function expandAnchorRange(range: string, rows: number, cols: number): string {
+  const bang = range.lastIndexOf('!');
+  const sheet = bang >= 0 ? range.slice(0, bang + 1) : '';
+  const cell = bang >= 0 ? range.slice(bang + 1) : range;
+  const m = /^([A-Za-z]+)([0-9]+)$/.exec(cell);
+  if (!m) return range;
+  const startCol = letterToCol(m[1]);
+  const startRow = parseInt(m[2], 10);
+  const endCol = colToLetter(startCol + cols - 1);
+  const endRow = startRow + rows - 1;
+  return `${sheet}${m[1].toUpperCase()}${startRow}:${endCol}${endRow}`;
+}
+
+// Count cells holding data in the JSON output of `gog sheets get`
+// ({"values":[[...]]}). Empty strings and whitespace-only cells don't count;
+// numbers (including 0) and other primitives do. Returns -1 when the output
+// can't be parsed, so the caller can fail safe rather than assume "empty".
+export function countNonEmptyCells(getOutput: string): number {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(getOutput);
+  } catch {
+    return -1;
+  }
+  const values = (parsed as { values?: unknown })?.values;
+  if (!Array.isArray(values)) return 0;
+  let count = 0;
+  for (const row of values) {
+    if (!Array.isArray(row)) continue;
+    for (const cell of row) {
+      if (cell !== null && String(cell).trim() !== '') count++;
+    }
+  }
+  return count;
+}

package/src/tools/sheets.ts

@@ -1,12 +1,25 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
+import { run } from '../runner.js';
+import { accountParam, runOrDiagnose, registerRunTool, toText, diagnose } from './utils.js';
+import { expandAnchorRange, countNonEmptyCells } from './sheets-a1.js';
 
 // Cell value type: matches what gog sheets --values-json accepts (passed
 // straight to the Sheets API as userEnteredValue). Strings starting with
 // "=" are treated as formulas by gog's default --input=USER_ENTERED.
 const cellValueParam = z.union([z.string(), z.number(), z.boolean(), z.null()]);
 
+// gog sheets update/append/clear all support -n/--dry-run ("Do not make
+// changes; print intended actions and exit successfully"). Exposing it gives
+// agents a no-op preview before committing a write to a live sheet.
+const dryRunParam = z.boolean().optional().describe(
+  'Preview the operation without modifying the sheet (gog --dry-run): reports the intended actions and exits without writing.',
+);
+
+const failIfNotEmptyParam = z.boolean().optional().describe(
+  'Safety guard against silent overwrites: before writing, read the target range and refuse the write if any target cell already holds data. Costs one extra read. Anchor ranges (e.g. "Sheet1!A1") are expanded to the full area your values will cover; explicit and named ranges are checked as-is.',
+);
+
 export function registerSheetsTools(server: McpServer): void {
   server.registerTool('gog_sheets_get', {
     description: 'Read values from a Google Sheets range. Returns a JSON object with a "values" array of rows.',
@@ -27,13 +40,37 @@ export function registerSheetsTools(server: McpServer): void {
       spreadsheetId: z.string().describe('Spreadsheet ID (from the URL)'),
       range: z.string().describe('Top-left cell or range in A1 notation, e.g. Sheet1!A1'),
       values: z.array(z.array(cellValueParam)).describe('2D array of values (rows of columns). Cells may be string/number/boolean/null; strings starting with "=" are formulas.'),
+      dry_run: dryRunParam,
+      fail_if_not_empty: failIfNotEmptyParam,
       account: accountParam,
     },
-  }, async ({ spreadsheetId, range, values, account }) => {
-    return runOrDiagnose(
-      ['sheets', 'update', spreadsheetId, range, `--values-json=${JSON.stringify(values)}`],
-      { account },
-    );
+  }, async ({ spreadsheetId, range, values, account, dry_run, fail_if_not_empty }) => {
+    const cols = values.reduce((max, row) => Math.max(max, row.length), 0);
+    if (fail_if_not_empty && values.length > 0 && cols > 0) {
+      const readRange = expandAnchorRange(range, values.length, cols);
+      let existing: string;
+      try {
+        existing = await run(['sheets', 'get', spreadsheetId, readRange], { account });
+      } catch (err) {
+        // Couldn't read the target — refuse to write rather than risk an
+        // overwrite, and diagnose the read failure (auth/transient/etc.) the
+        // same way runOrDiagnose would, since this path bypasses it.
+        return diagnose(err);
+      }
+      const occupied = countNonEmptyCells(existing);
+      if (occupied !== 0) {
+        const detail = occupied < 0
+          ? 'could not be verified as empty'
+          : `already contains data in ${occupied} cell(s)`;
+        return toText(
+          `Write aborted (fail_if_not_empty): target range ${readRange} ${detail}. ` +
+          'Re-run without fail_if_not_empty to overwrite, or clear it first with gog_sheets_clear.',
+        );
+      }
+    }
+    const args = ['sheets', 'update', spreadsheetId, range, `--values-json=${JSON.stringify(values)}`];
+    if (dry_run) args.push('--dry-run');
+    return runOrDiagnose(args, { account });
   });
 
   server.registerTool('gog_sheets_append', {
@@ -43,13 +80,13 @@ export function registerSheetsTools(server: McpServer): void {
       spreadsheetId: z.string().describe('Spreadsheet ID (from the URL)'),
       range: z.string().describe('Range indicating which sheet/columns to append to, e.g. Sheet1!A:C'),
       values: z.array(z.array(cellValueParam)).describe('2D array of rows to append. Cells may be string/number/boolean/null; strings starting with "=" are formulas.'),
+      dry_run: dryRunParam,
       account: accountParam,
     },
-  }, async ({ spreadsheetId, range, values, account }) => {
-    return runOrDiagnose(
-      ['sheets', 'append', spreadsheetId, range, `--values-json=${JSON.stringify(values)}`],
-      { account },
-    );
+  }, async ({ spreadsheetId, range, values, account, dry_run }) => {
+    const args = ['sheets', 'append', spreadsheetId, range, `--values-json=${JSON.stringify(values)}`];
+    if (dry_run) args.push('--dry-run');
+    return runOrDiagnose(args, { account });
   });
 
   server.registerTool('gog_sheets_clear', {
@@ -58,14 +95,17 @@ export function registerSheetsTools(server: McpServer): void {
     inputSchema: {
       spreadsheetId: z.string().describe('Spreadsheet ID'),
       range: z.string().describe('Range in A1 notation to clear'),
+      dry_run: dryRunParam,
       account: accountParam,
     },
-  }, async ({ spreadsheetId, range, account }) => {
-    return runOrDiagnose(['sheets', 'clear', spreadsheetId, range], { account });
+  }, async ({ spreadsheetId, range, account, dry_run }) => {
+    const args = ['sheets', 'clear', spreadsheetId, range];
+    if (dry_run) args.push('--dry-run');
+    return runOrDiagnose(args, { account });
   });
 
   server.registerTool('gog_sheets_metadata', {
-    description: 'Get spreadsheet metadata: title, sheet tabs, named ranges, and other properties.',
+    description: 'Get spreadsheet metadata: title, named ranges, and per-tab properties including grid dimensions (gridProperties.rowCount / columnCount). Use this to learn a sheet\'s current size before writing — a write outside the grid fails.',
     annotations: { readOnlyHint: true },
     inputSchema: {
       spreadsheetId: z.string().describe('Spreadsheet ID'),

package/src/tools/utils.ts

@@ -5,7 +5,8 @@ import { run } from '../runner.js';
 export type ToolResult = { content: [{ type: 'text'; text: string }] };
 
 export const accountParam = z.string().optional().describe(
-  'Google account email to use (overrides GOG_ACCOUNT env var)',
+  'Google account email to use, e.g. you@gmail.com — must be the full address, not a bare username. ' +
+  'Overrides the GOG_ACCOUNT env var. Omit to use the single configured account.',
 );
 
 // Canonical ID descriptors. Use these instead of redefining the same
@@ -100,6 +101,11 @@ const AUTH_ERROR_PATTERN = /\b(401|unauthorized|token.*(expired|revoked)|invalid
 const TRANSIENT_ERROR_PATTERN =
   /\b429\b|\b5\d\d\b|\bquota\b|rateLimit|\bDEADLINE_EXCEEDED\b/i;
 
+// gogcli rejects writes whose range falls outside the sheet's current grid
+// (e.g. writing to column AP on a 41-column sheet) with a "exceeds grid limits"
+// error and no remediation. Point the caller at the tool that grows the grid.
+const GRID_LIMIT_ERROR_PATTERN = /exceeds grid limits/i;
+
 const AUTH_HINT =
   '\n\nAuthentication may have expired. Use gog_auth_add to re-authorize the account. ' +
   'Ask the user if they would like to re-authenticate.';
@@ -108,6 +114,57 @@ const TRANSIENT_HINT =
   '\n\nThis error is often transient. Retry the same call before trying a different approach ' +
   '(do not fall back to smaller writes or row-by-row operations).';
 
+const GRID_LIMIT_HINT =
+  '\n\nThe target range is outside the sheet\'s current grid. Add the missing rows or columns ' +
+  'first with gog_sheets_insert (dimension: rows or cols), then retry the write.';
+
+// Reduce `gog auth list --json` output to just the configured email addresses.
+// The raw JSON also carries OAuth scopes, the Google subject id, and creation
+// timestamps — none of which belong in an error surfaced to the model, and
+// which were previously echoed verbatim on every failure. Falls back to the
+// trimmed raw text if the output isn't the expected JSON shape (e.g. a plain
+// email string), so unexpected output still degrades gracefully.
+export function formatAccountList(raw: string): string {
+  try {
+    const parsed = JSON.parse(raw) as { accounts?: unknown };
+    if (Array.isArray(parsed?.accounts)) {
+      return parsed.accounts
+        .map((a) => (a as { email?: string })?.email)
+        .filter(Boolean)
+        .join('\n');
+    }
+  } catch {
+    // not JSON — fall through to the raw text
+  }
+  return raw.trim();
+}
+
+// Turn a thrown error into a diagnosed ToolResult: the error text, an
+// actionable hint when the failure class is recognised (auth / transient /
+// off-grid write), and the list of configured accounts. Callers that need to
+// surface a failure without going through runOrDiagnose (e.g. a pre-write
+// verification read that must abort) can reuse this so the error keeps the
+// same diagnostic quality as everywhere else.
+export async function diagnose(err: unknown): Promise<ToolResult> {
+  const errText = toError(err).content[0].text;
+  const isAuthError = AUTH_ERROR_PATTERN.test(errText);
+  const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
+  const isGridLimitError = GRID_LIMIT_ERROR_PATTERN.test(errText);
+  const hint = isAuthError
+    ? AUTH_HINT
+    : isTransientError
+      ? TRANSIENT_HINT
+      : isGridLimitError
+        ? GRID_LIMIT_HINT
+        : '';
+  try {
+    const accounts = formatAccountList(await run(['auth', 'list']));
+    return toText(`${errText}\n\nConfigured accounts:\n${accounts || '(none)'}${hint}`);
+  } catch {
+    return toText(`${errText}${hint}`);
+  }
+}
+
 export async function runOrDiagnose(
   args: string[],
   options: { account?: string },
@@ -115,16 +172,6 @@ export async function runOrDiagnose(
   try {
     return toText(await run(args, options));
   } catch (err) {
-    const base = toError(err);
-    const errText = base.content[0].text;
-    const isAuthError = AUTH_ERROR_PATTERN.test(errText);
-    const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
-    const hint = isAuthError ? AUTH_HINT : isTransientError ? TRANSIENT_HINT : '';
-    try {
-      const accounts = await run(['auth', 'list']);
-      return toText(`${errText}\n\nConfigured accounts:\n${accounts}${hint}`);
-    } catch {
-      return toText(`${errText}${hint}`);
-    }
+    return diagnose(err);
   }
 }

package/tests/tools/sheets-a1.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { expandAnchorRange, countNonEmptyCells } from '../../src/tools/sheets-a1.js';
+
+describe('expandAnchorRange', () => {
+  it('expands a bare anchor cell to the full written area', () => {
+    expect(expandAnchorRange('A1', 3, 2)).toBe('A1:B3');
+  });
+
+  it('preserves a sheet-name prefix when expanding', () => {
+    expect(expandAnchorRange('Sheet1!A1', 70, 4)).toBe('Sheet1!A1:D70');
+  });
+
+  it('generates multi-letter end columns past Z', () => {
+    expect(expandAnchorRange('A1', 1, 27)).toBe('A1:AA1');
+  });
+
+  it('parses multi-letter start columns', () => {
+    expect(expandAnchorRange('AA5', 1, 1)).toBe('AA5:AA5');
+  });
+
+  it('uppercases a lowercase anchor column', () => {
+    expect(expandAnchorRange('b2', 1, 1)).toBe('B2:B2');
+  });
+
+  it('leaves an explicit A1 range (with a colon) unchanged', () => {
+    expect(expandAnchorRange('Sheet1!A1:D70', 5, 5)).toBe('Sheet1!A1:D70');
+  });
+
+  it('leaves a named range unchanged', () => {
+    expect(expandAnchorRange('MyNamedRange', 5, 5)).toBe('MyNamedRange');
+  });
+});
+
+describe('countNonEmptyCells', () => {
+  it('counts cells that hold data across ragged rows', () => {
+    expect(countNonEmptyCells('{"values":[["a","b"],["c"]]}')).toBe(3);
+  });
+
+  it('treats empty strings as empty', () => {
+    expect(countNonEmptyCells('{"values":[["","",""]]}')).toBe(0);
+  });
+
+  it('treats whitespace-only cells as empty', () => {
+    expect(countNonEmptyCells('{"values":[["   "]]}')).toBe(0);
+  });
+
+  it('counts numbers and zero as data, skips nulls', () => {
+    expect(countNonEmptyCells('{"values":[[1,0,null,"x"]]}')).toBe(3);
+  });
+
+  it('returns 0 when there is no values key', () => {
+    expect(countNonEmptyCells('{}')).toBe(0);
+  });
+
+  it('returns 0 when values is not an array', () => {
+    expect(countNonEmptyCells('{"values":"foo"}')).toBe(0);
+  });
+
+  it('returns 0 when the parsed JSON is null', () => {
+    expect(countNonEmptyCells('null')).toBe(0);
+  });
+
+  it('skips non-array rows', () => {
+    expect(countNonEmptyCells('{"values":[null,["a"]]}')).toBe(1);
+  });
+
+  it('returns -1 when the output is not valid JSON', () => {
+    expect(countNonEmptyCells('not json')).toBe(-1);
+  });
+});

package/tests/tools/sheets.test.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { registerSheetsTools } from '../../src/tools/sheets.js';
 import * as runner from '../../src/runner.js';
 import { setupHandlers as setupHandlersBase, type ToolHandler } from '../helpers/test-harness.js';
@@ -84,6 +85,135 @@ describe('gog_sheets_update', () => {
     const result = await handlers.get('gog_sheets_update')!({ spreadsheetId: 'bad', range: 'A1', values: [['x']] });
     expect(result.content[0].text).toBe('Error: Update failed');
   });
+
+  it('appends --dry-run when dry_run is true', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"dryRun":true}');
+    const handlers = setupHandlers();
+    const values = [['x']];
+    await handlers.get('gog_sheets_update')!({ spreadsheetId: 'sid', range: 'A1', values, dry_run: true });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['sheets', 'update', 'sid', 'A1', `--values-json=${JSON.stringify(values)}`, '--dry-run'],
+      { account: undefined },
+    );
+  });
+
+  it('omits --dry-run when dry_run is false or unset', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_update')!({ spreadsheetId: 'sid', range: 'A1', values: [['x']], dry_run: false });
+    expect(vi.mocked(runner.run).mock.calls[0]![0]).not.toContain('--dry-run');
+  });
+});
+
+describe('gog_sheets_update fail_if_not_empty guard', () => {
+  it('aborts the write when the target range already holds data', async () => {
+    vi.mocked(runner.run).mockResolvedValueOnce('{"values":[["existing"]]}');
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_sheets_update')!({
+      spreadsheetId: 'sid', range: 'A1', values: [['new']], fail_if_not_empty: true,
+    });
+    // Only the read happened — no update call.
+    expect(runner.run).toHaveBeenCalledTimes(1);
+    expect(runner.run).toHaveBeenCalledWith(['sheets', 'get', 'sid', 'A1:A1'], { account: undefined });
+    expect(result.content[0].text).toContain('Write aborted');
+    expect(result.content[0].text).toContain('A1:A1');
+    expect(result.content[0].text).toContain('1 cell');
+  });
+
+  it('proceeds with the write when the target range is empty', async () => {
+    vi.mocked(runner.run)
+      .mockResolvedValueOnce('{}')
+      .mockResolvedValueOnce('{"updatedCells":1}');
+    const handlers = setupHandlers();
+    const values = [['new']];
+    const result = await handlers.get('gog_sheets_update')!({
+      spreadsheetId: 'sid', range: 'A1', values, fail_if_not_empty: true,
+    });
+    expect(runner.run).toHaveBeenCalledTimes(2);
+    expect(vi.mocked(runner.run).mock.calls[1]![0]).toEqual(
+      ['sheets', 'update', 'sid', 'A1', `--values-json=${JSON.stringify(values)}`],
+    );
+    expect(result.content[0].text).toBe('{"updatedCells":1}');
+  });
+
+  it('expands an anchor cell to the full written area before reading', async () => {
+    vi.mocked(runner.run)
+      .mockResolvedValueOnce('{}')
+      .mockResolvedValueOnce('{}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_update')!({
+      spreadsheetId: 'sid', range: 'Sheet1!A1',
+      values: [['a', 'b'], ['c', 'd'], ['e', 'f']], fail_if_not_empty: true,
+    });
+    expect(vi.mocked(runner.run).mock.calls[0]![0]).toEqual(['sheets', 'get', 'sid', 'Sheet1!A1:B3']);
+  });
+
+  it('aborts without writing and diagnoses the error when the verification read fails', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('read boom')) // the verification get
+      .mockResolvedValueOnce('{"accounts":[{"email":"u@x.com"}]}'); // diagnose -> auth list
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_sheets_update')!({
+      spreadsheetId: 'sid', range: 'A1', values: [['new']], fail_if_not_empty: true,
+    });
+    // get + auth list (for diagnosis), but the update is never attempted
+    expect(runner.run).toHaveBeenCalledTimes(2);
+    expect(vi.mocked(runner.run).mock.calls.some((c) => c[0][1] === 'update')).toBe(false);
+    expect(result.content[0].text).toContain('Error: read boom');
+    expect(result.content[0].text).toContain('Configured accounts:');
+  });
+
+  it('surfaces the re-auth hint when the verification read fails with an auth error', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('Request failed with status 401'))
+      .mockResolvedValueOnce('{"accounts":[{"email":"u@x.com"}]}');
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_sheets_update')!({
+      spreadsheetId: 'sid', range: 'A1', values: [['x']], fail_if_not_empty: true,
+    });
+    expect(result.content[0].text).toContain('gog_auth_add');
+  });
+
+  it('aborts when emptiness cannot be verified from unparseable output', async () => {
+    vi.mocked(runner.run).mockResolvedValueOnce('not json');
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_sheets_update')!({
+      spreadsheetId: 'sid', range: 'A1', values: [['new']], fail_if_not_empty: true,
+    });
+    expect(runner.run).toHaveBeenCalledTimes(1);
+    expect(result.content[0].text).toContain('could not be verified');
+  });
+
+  it('still honors dry_run after the guard passes', async () => {
+    vi.mocked(runner.run)
+      .mockResolvedValueOnce('{}')
+      .mockResolvedValueOnce('{"dryRun":true}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_update')!({
+      spreadsheetId: 'sid', range: 'A1', values: [['new']], fail_if_not_empty: true, dry_run: true,
+    });
+    expect(vi.mocked(runner.run).mock.calls[1]![0]).toContain('--dry-run');
+  });
+
+  it('skips the guard read when values has no rows', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_update')!({
+      spreadsheetId: 'sid', range: 'A1', values: [], fail_if_not_empty: true,
+    });
+    expect(runner.run).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(runner.run).mock.calls[0]![0]![1]).toBe('update');
+  });
+
+  it('skips the guard read when rows have no columns', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_update')!({
+      spreadsheetId: 'sid', range: 'A1', values: [[]], fail_if_not_empty: true,
+    });
+    expect(runner.run).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(runner.run).mock.calls[0]![0]![1]).toBe('update');
+  });
 });
 
 describe('gog_sheets_append', () => {
@@ -104,6 +234,17 @@ describe('gog_sheets_append', () => {
     const result = await handlers.get('gog_sheets_append')!({ spreadsheetId: 'bad', range: 'A1', values: [['x']] });
     expect(result.content[0].text).toBe('Error: Append failed');
   });
+
+  it('appends --dry-run when dry_run is true', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"dryRun":true}');
+    const handlers = setupHandlers();
+    const values = [['x']];
+    await handlers.get('gog_sheets_append')!({ spreadsheetId: 'sid', range: 'Sheet1!A:A', values, dry_run: true });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['sheets', 'append', 'sid', 'Sheet1!A:A', `--values-json=${JSON.stringify(values)}`, '--dry-run'],
+      { account: undefined },
+    );
+  });
 });
 
 describe('gog_sheets_clear', () => {
@@ -120,9 +261,30 @@ describe('gog_sheets_clear', () => {
     const result = await handlers.get('gog_sheets_clear')!({ spreadsheetId: 'bad', range: 'A1' });
     expect(result.content[0].text).toBe('Error: Clear failed');
   });
+
+  it('appends --dry-run when dry_run is true', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"dryRun":true}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_clear')!({ spreadsheetId: 'sid', range: 'Sheet1!A1:Z100', dry_run: true });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['sheets', 'clear', 'sid', 'Sheet1!A1:Z100', '--dry-run'],
+      { account: undefined },
+    );
+  });
 });
 
 describe('gog_sheets_metadata', () => {
+  it('advertises grid dimensions in its description', () => {
+    const server = new McpServer({ name: 'test', version: '0.0.0' });
+    const configs = new Map<string, { description?: string }>();
+    vi.spyOn(server, 'registerTool').mockImplementation((name, config) => {
+      configs.set(name, config as { description?: string });
+      return undefined as never;
+    });
+    registerSheetsTools(server);
+    expect(configs.get('gog_sheets_metadata')!.description).toMatch(/grid dimensions|rowCount|columnCount/i);
+  });
+
   it('calls run with spreadsheetId only', async () => {
     vi.mocked(runner.run).mockResolvedValue('{"title":"My Sheet","sheets":[{"title":"Sheet1"}]}');
     const handlers = setupHandlers();

package/tests/tools/utils.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import * as runner from '../../src/runner.js';
-import { runOrDiagnose, pushPaginationFlags } from '../../src/tools/utils.js';
+import { runOrDiagnose, pushPaginationFlags, formatAccountList } from '../../src/tools/utils.js';
 
 vi.mock('../../src/runner.js');
 
@@ -40,6 +40,53 @@ describe('pushPaginationFlags', () => {
   });
 });
 
+describe('formatAccountList', () => {
+  const AUTH_LIST_JSON = JSON.stringify({
+    accounts: [
+      {
+        email: 'chris.c.hall@gmail.com',
+        subject: '109876543210987654321',
+        client: 'default',
+        services: ['gmail', 'drive'],
+        scopes: ['https://www.googleapis.com/auth/gmail.modify', 'https://www.googleapis.com/auth/drive'],
+        created_at: '2026-01-02T03:04:05Z',
+      },
+    ],
+  });
+
+  it('reduces gog auth list JSON to email addresses only', () => {
+    const out = formatAccountList(AUTH_LIST_JSON);
+    expect(out).toBe('chris.c.hall@gmail.com');
+    // none of the sensitive fields leak through
+    expect(out).not.toContain('scopes');
+    expect(out).not.toContain('gmail.modify');
+    expect(out).not.toContain('109876543210987654321');
+    expect(out).not.toContain('created_at');
+  });
+
+  it('joins multiple account emails with newlines', () => {
+    const out = formatAccountList(JSON.stringify({ accounts: [{ email: 'a@x.com' }, { email: 'b@y.com' }] }));
+    expect(out).toBe('a@x.com\nb@y.com');
+  });
+
+  it('skips accounts with no email', () => {
+    const out = formatAccountList(JSON.stringify({ accounts: [{ email: 'a@x.com' }, { client: 'other' }] }));
+    expect(out).toBe('a@x.com');
+  });
+
+  it('falls back to the trimmed raw text when not parseable JSON', () => {
+    expect(formatAccountList('  user@gmail.com\n')).toBe('user@gmail.com');
+  });
+
+  it('falls back to raw text when JSON has no accounts array', () => {
+    expect(formatAccountList('{"foo":1}')).toBe('{"foo":1}');
+  });
+
+  it('falls back to raw text when parsed JSON is null', () => {
+    expect(formatAccountList('null')).toBe('null');
+  });
+});
+
 describe('runOrDiagnose', () => {
   it('returns output text on success', async () => {
     vi.mocked(runner.run).mockResolvedValue('{"ok":true}');
@@ -58,6 +105,35 @@ describe('runOrDiagnose', () => {
     expect(result.content[0].text).not.toContain('gog_auth_add');
   });
 
+  it('redacts scopes/subject/timestamps from the configured-accounts block', async () => {
+    const authListJson = JSON.stringify({
+      accounts: [{
+        email: 'chris.c.hall@gmail.com',
+        subject: '109876543210987654321',
+        scopes: ['https://www.googleapis.com/auth/gmail.modify'],
+        created_at: '2026-01-02T03:04:05Z',
+      }],
+    });
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('refusing to delete gmail draft r123 without --force (non-interactive)'))
+      .mockResolvedValueOnce(authListJson);
+    const result = await runOrDiagnose(['gmail', 'drafts', 'delete', 'r123'], {});
+    const text = result.content[0].text;
+    expect(text).toContain('Configured accounts:\nchris.c.hall@gmail.com');
+    expect(text).not.toContain('scopes');
+    expect(text).not.toContain('gmail.modify');
+    expect(text).not.toContain('109876543210987654321');
+    expect(text).not.toContain('created_at');
+  });
+
+  it('shows (none) when no accounts are configured', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('Doc not found'))
+      .mockResolvedValueOnce('{"accounts":[]}');
+    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    expect(result.content[0].text).toBe('Error: Doc not found\n\nConfigured accounts:\n(none)');
+  });
+
   it('appends re-auth hint on 401 error', async () => {
     vi.mocked(runner.run)
       .mockRejectedValueOnce(new Error('Request failed with status 401'))
@@ -175,4 +251,30 @@ describe('runOrDiagnose', () => {
     expect(result.content[0].text).toContain('transient');
     expect(result.content[0].text).not.toContain('Configured accounts');
   });
+
+  it('appends grid-limit hint pointing at gog_sheets_insert', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('Range (Sheet1!AP1:AW1) exceeds grid limits. Max rows: 1000, max columns: 41'))
+      .mockResolvedValueOnce('user@gmail.com');
+    const result = await runOrDiagnose(['sheets', 'update', 'abc', 'AP1'], {});
+    expect(result.content[0].text).toContain('exceeds grid limits');
+    expect(result.content[0].text).toContain('gog_sheets_insert');
+  });
+
+  it('does not append grid-limit hint on unrelated errors', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('Spreadsheet not found'))
+      .mockResolvedValueOnce('user@gmail.com');
+    const result = await runOrDiagnose(['sheets', 'update', 'abc', 'A1'], {});
+    expect(result.content[0].text).not.toContain('gog_sheets_insert');
+  });
+
+  it('keeps grid-limit hint when auth list also fails', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('exceeds grid limits. Max rows: 1000, max columns: 41'))
+      .mockRejectedValueOnce(new Error('auth list failed'));
+    const result = await runOrDiagnose(['sheets', 'update', 'abc', 'A1'], {});
+    expect(result.content[0].text).toContain('gog_sheets_insert');
+    expect(result.content[0].text).not.toContain('Configured accounts');
+  });
 });