gogcli-mcp-sheets 2.0.12 → 2.2.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
-    "version": "2.0.12"
+    "version": "2.2.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli (Sheets)",
       "source": "./",
       "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
-      "version": "2.0.12",
+      "version": "2.2.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp-sheets",
   "displayName": "gogcli (Sheets)",
-  "version": "2.0.12",
+  "version": "2.2.0",
   "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
   "author": {
     "name": "Chris Hall",

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+## [2.3.0](https://github.com/chrischall/gogcli-mcp/compare/v2.2.0...v2.3.0) (2026-05-30)
+
+
+### Features
+
+* 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))
+* **sheets:** warn when DATE/DATE_TIME format applied to small integers ([#46](https://github.com/chrischall/gogcli-mcp/issues/46)) ([623c432](https://github.com/chrischall/gogcli-mcp/commit/623c432998d94875706733d4140b346de74ef9d8))
+* wrap new gog cli v0.18.0 tools ([173242a](https://github.com/chrischall/gogcli-mcp/commit/173242aafaa8c2f2d7282a2fbd8faedfc65a63bd))
+
+
+### Bug Fixes
+
+* add repository field to sub-packages for npm provenance ([3b56e4b](https://github.com/chrischall/gogcli-mcp/commit/3b56e4bb56617ad8381997176e6f60c932865454))
+* **mcpb:** add per-sub-package .mcpbignore to trim bundles ([e739d9e](https://github.com/chrischall/gogcli-mcp/commit/e739d9ec9ae8e4cc19b1189bb5bf7ac90481c943))
+* **sheets:** gog_sheets_insert with after:true now actually shifts the insertion point ([#44](https://github.com/chrischall/gogcli-mcp/issues/44)) ([a766d80](https://github.com/chrischall/gogcli-mcp/commit/a766d8065993e764a8ed35965e506af472eafa89))
+
+
+### 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))
+* 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))
+
+## [2.2.0](https://github.com/chrischall/gogcli-mcp/compare/v2.1.0...v2.2.0) (2026-05-26)
+
+
+### Features
+
+* **sheets:** warn when DATE/DATE_TIME format applied to small integers ([#46](https://github.com/chrischall/gogcli-mcp/issues/46)) ([623c432](https://github.com/chrischall/gogcli-mcp/commit/623c432998d94875706733d4140b346de74ef9d8))
+
+
+### Bug Fixes
+
+* **sheets:** gog_sheets_insert with after:true now actually shifts the insertion point ([#44](https://github.com/chrischall/gogcli-mcp/issues/44)) ([a766d80](https://github.com/chrischall/gogcli-mcp/commit/a766d8065993e764a8ed35965e506af472eafa89))
+
+## [2.1.0](https://github.com/chrischall/gogcli-mcp/compare/v2.0.13...v2.1.0) (2026-05-25)
+
+
+### Features
+
+* 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))
+* wrap new gog cli v0.18.0 tools ([173242a](https://github.com/chrischall/gogcli-mcp/commit/173242aafaa8c2f2d7282a2fbd8faedfc65a63bd))
+
+
+### Bug Fixes
+
+* add repository field to sub-packages for npm provenance ([3b56e4b](https://github.com/chrischall/gogcli-mcp/commit/3b56e4bb56617ad8381997176e6f60c932865454))
+* **mcpb:** add per-sub-package .mcpbignore to trim bundles ([e739d9e](https://github.com/chrischall/gogcli-mcp/commit/e739d9ec9ae8e4cc19b1189bb5bf7ac90481c943))
+
+
+### 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))
+* 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 = {}) {
 
 // ../gogcli-mcp/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);
   }
 }
 
@@ -31218,8 +31233,62 @@ function registerAuthTools(server2) {
   });
 }
 
+// ../gogcli-mcp/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;
+}
+
 // ../gogcli-mcp/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.',
@@ -31239,13 +31308,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.',
@@ -31254,13 +31341,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).",
@@ -31268,13 +31355,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"),
@@ -31309,7 +31399,7 @@ function registerSheetsTools(server2) {
 }
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.0.12" : "0.0.0";
+var VERSION = true ? "2.2.0" : "0.0.0";
 function createServer(options) {
   return new McpServer({
     name: options?.name ?? "gogcli",
@@ -31329,6 +31419,33 @@ function hexToRgb(hex3) {
     blue: (n & 255) / 255
   };
 }
+async function checkDateFormatTarget(spreadsheetId, range, account) {
+  const peek = await runOrDiagnose(
+    ["sheets", "get", spreadsheetId, range, "--render=UNFORMATTED_VALUE"],
+    { account }
+  );
+  let parsed;
+  try {
+    parsed = JSON.parse(peek.content[0].text);
+  } catch {
+    return null;
+  }
+  const rows = parsed.values;
+  if (!Array.isArray(rows) || rows.length === 0) return null;
+  let sawSmallInt = false;
+  for (const row of rows) {
+    for (const cell of row) {
+      if (cell === null || cell === void 0 || cell === "") continue;
+      if (typeof cell !== "number") return null;
+      if (!Number.isInteger(cell)) return null;
+      if (cell < 0) return null;
+      if (cell >= 1e4) return null;
+      sawSmallInt = true;
+    }
+  }
+  if (!sawSmallInt) return null;
+  return "Warning: applying DATE/DATE_TIME format to cells holding small integers (< 10000) will render them as dates near 1899-12-30 because Sheets interprets numeric values as day-serials from that epoch. If those integers are ordinals (1, 2, 3, ...) and not day offsets, this is almost certainly not what you want. Pass force:true to suppress this warning, or convert the cells to real dates / strings first.";
+}
 function registerExtraSheetsTools(server2) {
   server2.registerTool("gog_sheets_list_tabs", {
     description: "List tabs (sheets) in a spreadsheet with their titles, sheetIds, and indices. A friendlier view than gog_sheets_metadata when you only need the tab list \u2014 useful for restructuring a workbook over a long agent session without losing track of names.",
@@ -31422,7 +31539,7 @@ function registerExtraSheetsTools(server2) {
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_sheets_insert", {
-    description: "Insert rows or columns into a sheet.",
+    description: "Insert rows or columns into a sheet. With after:false (default), the new dimension lands at start. With after:true, the new dimension lands at start+1 (the existing dimension at start is preserved).",
     annotations: { destructiveHint: true },
     inputSchema: {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
@@ -31430,11 +31547,12 @@ function registerExtraSheetsTools(server2) {
       dimension: external_exports.string().describe("Dimension to insert: ROWS or COLUMNS"),
       start: external_exports.number().describe("Start index (0-based)"),
       count: external_exports.number().optional().describe("Number of rows/columns to insert (default: 1)"),
-      after: external_exports.boolean().optional().describe("Insert after the start index instead of before"),
+      after: external_exports.boolean().optional().describe("Insert after the start index instead of before. With after:true the new dimension lands at start+1, leaving the existing dimension at start untouched."),
       account: accountParam
     }
   }, async ({ spreadsheetId, sheet, dimension, start, count, after, account }) => {
-    const args = ["sheets", "insert", spreadsheetId, sheet, dimension, String(start)];
+    const effectiveStart = after ? start + 1 : start;
+    const args = ["sheets", "insert", spreadsheetId, sheet, dimension, String(effectiveStart)];
     if (count !== void 0) args.push(`--count=${count}`);
     if (after) args.push("--after");
     return runOrDiagnose(args, { account });
@@ -31553,20 +31671,29 @@ function registerExtraSheetsTools(server2) {
     return runOrDiagnose(args, { account: a.account });
   });
   server2.registerTool("gog_sheets_number_format", {
-    description: "Set number format on a range (currency, percentage, date, etc.).",
+    description: "Set number format on a range (currency, percentage, date, etc.). When type is DATE or DATE_TIME, the target range is peeked first; if every numeric cell is a small integer (< 10000), a warning is prepended to the response because Sheets will render those as 1899/1900 day-serials. Pass force:true to skip the check.",
     annotations: { destructiveHint: true },
     inputSchema: {
       spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
       range: external_exports.string().describe("Range to format (e.g. Sheet1!A1:A10)"),
-      type: external_exports.string().optional().describe("Format type: NUMBER, CURRENCY, PERCENT, DATE, TIME, SCIENTIFIC, etc."),
+      type: external_exports.string().optional().describe("Format type: NUMBER, CURRENCY, PERCENT, DATE, DATE_TIME, TIME, SCIENTIFIC, etc."),
       pattern: external_exports.string().optional().describe('Custom format pattern (e.g. "#,##0.00", "yyyy-mm-dd")'),
+      force: external_exports.boolean().optional().describe("Skip the DATE/DATE_TIME small-integer warning check"),
       account: accountParam
     }
-  }, async ({ spreadsheetId, range, type, pattern, account }) => {
+  }, async ({ spreadsheetId, range, type, pattern, force, account }) => {
+    const isDateType = type === "DATE" || type === "DATE_TIME";
+    const warning = isDateType && !force ? await checkDateFormatTarget(spreadsheetId, range, account) : null;
     const args = ["sheets", "number-format", spreadsheetId, range];
     if (type) args.push(`--type=${type}`);
     if (pattern) args.push(`--pattern=${pattern}`);
-    return runOrDiagnose(args, { account });
+    const result = await runOrDiagnose(args, { account });
+    if (warning) {
+      return { content: [{ type: "text", text: `${warning}
+
+${result.content[0].text}` }] };
+    }
+    return result;
   });
   server2.registerTool("gog_sheets_read_format", {
     description: "Read cell formatting for a range.",

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-sheets",
   "display_name": "gogcli (Sheets)",
-  "version": "2.0.12",
+  "version": "2.2.0",
   "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
   "author": {
     "name": "Chris Hall",
@@ -150,7 +150,7 @@
     },
     {
       "name": "gog_sheets_number_format",
-      "description": "Set number format on a range (currency, percentage, date, etc.)."
+      "description": "Set number format on a range (currency, percentage, date, etc.). When type is DATE or DATE_TIME, peeks the target range first and warns if every numeric cell is a small integer (< 10000) — Sheets would render those as 1899/1900 day-serials. Pass force:true to skip the check."
     },
     {
       "name": "gog_sheets_read_format",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-sheets",
-  "version": "2.0.12",
+  "version": "2.2.0",
   "mcpName": "io.github.chrischall/gogcli-mcp-sheets",
   "description": "Extended Google Sheets MCP server via gogcli — all base tools plus full Sheets support",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

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

package/src/tools/sheets-extra.ts

@@ -18,6 +18,55 @@ export function hexToRgb(hex: string): { red: number; green: number; blue: numbe
   };
 }
 
+// Issue #43: peek the target range before applying DATE / DATE_TIME number
+// formatting. If every numeric cell is a small integer (< 10000), Sheets will
+// render them as day-serials near 1899-12-30 — almost certainly not what the
+// caller intended. Return a warning string in that case, otherwise null.
+//
+// Returns null (no warning) when:
+//   - the peek fails / response isn't parseable JSON
+//   - the range is empty
+//   - any value is a non-integer number or a number >= 10000
+//   - any value is a string (other than empty), boolean, etc.
+// Nulls and empty strings are ignored.
+async function checkDateFormatTarget(
+  spreadsheetId: string,
+  range: string,
+  account: string | undefined,
+): Promise<string | null> {
+  const peek = await runOrDiagnose(
+    ['sheets', 'get', spreadsheetId, range, '--render=UNFORMATTED_VALUE'],
+    { account },
+  );
+  let parsed: { values?: unknown[][] };
+  try {
+    parsed = JSON.parse(peek.content[0].text) as { values?: unknown[][] };
+  } catch {
+    return null;
+  }
+  const rows = parsed.values;
+  if (!Array.isArray(rows) || rows.length === 0) return null;
+  let sawSmallInt = false;
+  for (const row of rows) {
+    for (const cell of row) {
+      if (cell === null || cell === undefined || cell === '') continue;
+      if (typeof cell !== 'number') return null;
+      if (!Number.isInteger(cell)) return null;
+      if (cell < 0) return null;
+      if (cell >= 10000) return null;
+      sawSmallInt = true;
+    }
+  }
+  if (!sawSmallInt) return null;
+  return (
+    'Warning: applying DATE/DATE_TIME format to cells holding small integers (< 10000) ' +
+    'will render them as dates near 1899-12-30 because Sheets interprets numeric values as ' +
+    'day-serials from that epoch. If those integers are ordinals (1, 2, 3, ...) and not ' +
+    'day offsets, this is almost certainly not what you want. Pass force:true to suppress ' +
+    'this warning, or convert the cells to real dates / strings first.'
+  );
+}
+
 export function registerExtraSheetsTools(server: McpServer): void {
 
   server.registerTool('gog_sheets_list_tabs', {
@@ -120,7 +169,7 @@ export function registerExtraSheetsTools(server: McpServer): void {
   });
 
   server.registerTool('gog_sheets_insert', {
-    description: 'Insert rows or columns into a sheet.',
+    description: 'Insert rows or columns into a sheet. With after:false (default), the new dimension lands at start. With after:true, the new dimension lands at start+1 (the existing dimension at start is preserved).',
     annotations: { destructiveHint: true },
     inputSchema: {
       spreadsheetId: z.string().describe('Spreadsheet ID'),
@@ -128,11 +177,16 @@ export function registerExtraSheetsTools(server: McpServer): void {
       dimension: z.string().describe('Dimension to insert: ROWS or COLUMNS'),
       start: z.number().describe('Start index (0-based)'),
       count: z.number().optional().describe('Number of rows/columns to insert (default: 1)'),
-      after: z.boolean().optional().describe('Insert after the start index instead of before'),
+      after: z.boolean().optional().describe('Insert after the start index instead of before. With after:true the new dimension lands at start+1, leaving the existing dimension at start untouched.'),
       account: accountParam,
     },
   }, async ({ spreadsheetId, sheet, dimension, start, count, after, account }) => {
-    const args = ['sheets', 'insert', spreadsheetId, sheet, dimension, String(start)];
+    // The underlying `gog sheets insert` treats `start` as 1-based with `--after` shifting +1.
+    // To honor our 0-based `start` and make `after:true` actually shift the insertion to start+1
+    // (issue #42), we send `start+1` when `after:true`. With after:false the CLI's `start-1`
+    // conversion lands the insertion at our 0-based start.
+    const effectiveStart = after ? start + 1 : start;
+    const args = ['sheets', 'insert', spreadsheetId, sheet, dimension, String(effectiveStart)];
     if (count !== undefined) args.push(`--count=${count}`);
     if (after) args.push('--after');
     return runOrDiagnose(args, { account });
@@ -255,20 +309,29 @@ export function registerExtraSheetsTools(server: McpServer): void {
   });
 
   server.registerTool('gog_sheets_number_format', {
-    description: 'Set number format on a range (currency, percentage, date, etc.).',
+    description: 'Set number format on a range (currency, percentage, date, etc.). When type is DATE or DATE_TIME, the target range is peeked first; if every numeric cell is a small integer (< 10000), a warning is prepended to the response because Sheets will render those as 1899/1900 day-serials. Pass force:true to skip the check.',
     annotations: { destructiveHint: true },
     inputSchema: {
       spreadsheetId: z.string().describe('Spreadsheet ID'),
       range: z.string().describe('Range to format (e.g. Sheet1!A1:A10)'),
-      type: z.string().optional().describe('Format type: NUMBER, CURRENCY, PERCENT, DATE, TIME, SCIENTIFIC, etc.'),
+      type: z.string().optional().describe('Format type: NUMBER, CURRENCY, PERCENT, DATE, DATE_TIME, TIME, SCIENTIFIC, etc.'),
       pattern: z.string().optional().describe('Custom format pattern (e.g. "#,##0.00", "yyyy-mm-dd")'),
+      force: z.boolean().optional().describe('Skip the DATE/DATE_TIME small-integer warning check'),
       account: accountParam,
     },
-  }, async ({ spreadsheetId, range, type, pattern, account }) => {
+  }, async ({ spreadsheetId, range, type, pattern, force, account }) => {
+    const isDateType = type === 'DATE' || type === 'DATE_TIME';
+    const warning = isDateType && !force
+      ? await checkDateFormatTarget(spreadsheetId, range, account)
+      : null;
     const args = ['sheets', 'number-format', spreadsheetId, range];
     if (type) args.push(`--type=${type}`);
     if (pattern) args.push(`--pattern=${pattern}`);
-    return runOrDiagnose(args, { account });
+    const result = await runOrDiagnose(args, { account });
+    if (warning) {
+      return { content: [{ type: 'text' as const, text: `${warning}\n\n${result.content[0].text}` }] };
+    }
+    return result;
   });
 
   server.registerTool('gog_sheets_read_format', {

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

@@ -119,11 +119,21 @@ describe('gog_sheets_insert', () => {
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['sheets', 'insert', 'sid', 'Sheet1', 'ROWS', '5'], { account: undefined });
   });
 
-  it('includes --count and --after when provided', async () => {
+  it('shifts start by +1 when after:true so the new dimension lands AFTER start', async () => {
+    // Issue #42: with after:true, start=0 means "insert after index 0" — i.e. land at index 1.
+    // The MCP must compensate for the CLI's 1-based interpretation by passing start+1.
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
     const handlers = setupHandlers();
     await handlers.get('gog_sheets_insert')!({ spreadsheetId: 'sid', sheet: 'S1', dimension: 'COLUMNS', start: 0, count: 3, after: true });
-    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['sheets', 'insert', 'sid', 'S1', 'COLUMNS', '0', '--count=3', '--after'], { account: undefined });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['sheets', 'insert', 'sid', 'S1', 'COLUMNS', '1', '--count=3', '--after'], { account: undefined });
+  });
+
+  it('issue #42 acceptance: start=28, after:true leaves column 28 untouched (insertion lands at 29)', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_sheets_insert')!({ spreadsheetId: 'sid', sheet: 'S1', dimension: 'COLUMNS', start: 28, after: true, count: 1 });
+    // CLI is 1-based; with --after CLI uses startIndex = c.Start, so passing 29 → API startIndex=29.
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['sheets', 'insert', 'sid', 'S1', 'COLUMNS', '29', '--count=1', '--after'], { account: undefined });
   });
 
   it('includes --count=0 when count is 0', async () => {
@@ -133,7 +143,7 @@ describe('gog_sheets_insert', () => {
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['sheets', 'insert', 'sid', 'S1', 'ROWS', '0', '--count=0'], { account: undefined });
   });
 
-  it('omits --after when false', async () => {
+  it('omits --after and does not shift start when after:false', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
     const handlers = setupHandlers();
     await handlers.get('gog_sheets_insert')!({ spreadsheetId: 'sid', sheet: 'S1', dimension: 'ROWS', start: 0, after: false });
@@ -314,6 +324,206 @@ describe('gog_sheets_number_format', () => {
     await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'A1', type: 'CURRENCY', pattern: '#,##0.00' });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['sheets', 'number-format', 'sid', 'A1', '--type=CURRENCY', '--pattern=#,##0.00'], { account: undefined });
   });
+
+  // Issue #43: warn when DATE/DATE_TIME format applied to small integers (silent 1899/1900 render).
+  describe('DATE/DATE_TIME small-integer warning', () => {
+    it('emits a warning when DATE applied to a range of small integers', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockImplementation(async (args: string[]) => {
+        if (args[1] === 'get') {
+          return toText(JSON.stringify({ range: 'Sheet1!A1:A3', values: [[1], [2], [3]] }));
+        }
+        return toText('{"ok":true}');
+      });
+      const result = await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'Sheet1!A1:A3', type: 'DATE' });
+      // Peek call goes out first.
+      expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+        ['sheets', 'get', 'sid', 'Sheet1!A1:A3', '--render=UNFORMATTED_VALUE'],
+        { account: undefined },
+      );
+      // The format call still happens (warning is non-blocking).
+      expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+        ['sheets', 'number-format', 'sid', 'Sheet1!A1:A3', '--type=DATE'],
+        { account: undefined },
+      );
+      const text = result.content[0].text;
+      expect(text).toMatch(/warning/i);
+      expect(text).toMatch(/1899|1900|day-serial|small integer/i);
+      expect(text).toMatch(/force/);
+    });
+
+    it('also warns for DATE_TIME', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockImplementation(async (args: string[]) => {
+        if (args[1] === 'get') {
+          return toText(JSON.stringify({ range: 'Sheet1!A1:A2', values: [[5], [7]] }));
+        }
+        return toText('{"ok":true}');
+      });
+      const result = await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'Sheet1!A1:A2', type: 'DATE_TIME' });
+      expect(result.content[0].text).toMatch(/warning/i);
+    });
+
+    it('does not peek or warn when force:true', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{"ok":true}'));
+      const result = await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'Sheet1!A1:A3', type: 'DATE', force: true });
+      // Only the format call should fire — no peek.
+      expect(lib.runOrDiagnose).toHaveBeenCalledTimes(1);
+      expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+        ['sheets', 'number-format', 'sid', 'Sheet1!A1:A3', '--type=DATE'],
+        { account: undefined },
+      );
+      expect(result.content[0].text).not.toMatch(/warning/i);
+    });
+
+    it('peeks and warns when force:false is passed explicitly (round-trips the no-force path)', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockImplementation(async (args: string[]) => {
+        if (args[1] === 'get') {
+          return toText(JSON.stringify({ range: 'A1:A3', values: [[1], [2], [3]] }));
+        }
+        return toText('{"ok":true}');
+      });
+      const result = await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'A1:A3', type: 'DATE', force: false });
+      expect(lib.runOrDiagnose).toHaveBeenCalledTimes(2);
+      expect(result.content[0].text).toMatch(/warning/i);
+    });
+
+    it('does not peek when type is not DATE/DATE_TIME', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{"ok":true}'));
+      await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'A1:A3', type: 'CURRENCY' });
+      expect(lib.runOrDiagnose).toHaveBeenCalledTimes(1);
+      expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+        ['sheets', 'number-format', 'sid', 'A1:A3', '--type=CURRENCY'],
+        { account: undefined },
+      );
+    });
+
+    it('does not warn when values include a large integer (>=10000)', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockImplementation(async (args: string[]) => {
+        if (args[1] === 'get') {
+          // 45000 is a real day-serial (year ~2023) — legitimate date value.
+          return toText(JSON.stringify({ range: 'A1:A2', values: [[1], [45000]] }));
+        }
+        return toText('{"ok":true}');
+      });
+      const result = await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'A1:A2', type: 'DATE' });
+      expect(result.content[0].text).not.toMatch(/warning/i);
+    });
+
+    it('does not warn when values include a negative integer (deltas/error codes, not day-serials)', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockImplementation(async (args: string[]) => {
+        if (args[1] === 'get') {
+          return toText(JSON.stringify({ range: 'A1:A3', values: [[1], [-5], [3]] }));
+        }
+        return toText('{"ok":true}');
+      });
+      const result = await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'A1:A3', type: 'DATE' });
+      expect(result.content[0].text).not.toMatch(/warning/i);
+    });
+
+    it('does not warn when values include non-integer numbers', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockImplementation(async (args: string[]) => {
+        if (args[1] === 'get') {
+          return toText(JSON.stringify({ range: 'A1:A2', values: [[1], [2.5]] }));
+        }
+        return toText('{"ok":true}');
+      });
+      const result = await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'A1:A2', type: 'DATE' });
+      expect(result.content[0].text).not.toMatch(/warning/i);
+    });
+
+    it('does not warn when range has no values (missing values key)', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockImplementation(async (args: string[]) => {
+        if (args[1] === 'get') {
+          return toText(JSON.stringify({ range: 'A1:A3' }));
+        }
+        return toText('{"ok":true}');
+      });
+      const result = await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'A1:A3', type: 'DATE' });
+      expect(result.content[0].text).not.toMatch(/warning/i);
+    });
+
+    it('does not warn when range has empty values array', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockImplementation(async (args: string[]) => {
+        if (args[1] === 'get') {
+          return toText(JSON.stringify({ range: 'A1:A3', values: [] }));
+        }
+        return toText('{"ok":true}');
+      });
+      const result = await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'A1:A3', type: 'DATE' });
+      expect(result.content[0].text).not.toMatch(/warning/i);
+    });
+
+    it('does not warn when values are strings', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockImplementation(async (args: string[]) => {
+        if (args[1] === 'get') {
+          return toText(JSON.stringify({ range: 'A1:A2', values: [['hello'], ['world']] }));
+        }
+        return toText('{"ok":true}');
+      });
+      const result = await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'A1:A2', type: 'DATE' });
+      expect(result.content[0].text).not.toMatch(/warning/i);
+    });
+
+    it('ignores null and empty cells when deciding to warn', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockImplementation(async (args: string[]) => {
+        if (args[1] === 'get') {
+          // Real-world: nulls/empty strings interspersed with the ordinal ints.
+          return toText(JSON.stringify({ range: 'A1:A4', values: [[1], [null], [''], [3]] }));
+        }
+        return toText('{"ok":true}');
+      });
+      const result = await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'A1:A4', type: 'DATE' });
+      expect(result.content[0].text).toMatch(/warning/i);
+    });
+
+    it('proceeds with format when peek fails (does not block)', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockImplementation(async (args: string[]) => {
+        if (args[1] === 'get') {
+          return toText('Error: something went wrong');
+        }
+        return toText('{"ok":true}');
+      });
+      const result = await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'A1:A3', type: 'DATE' });
+      // Format call should still happen.
+      expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+        ['sheets', 'number-format', 'sid', 'A1:A3', '--type=DATE'],
+        { account: undefined },
+      );
+      // No warning emitted when peek didn't yield clear evidence.
+      expect(result.content[0].text).not.toMatch(/warning/i);
+    });
+
+    it('forwards account on both peek and format calls', async () => {
+      const handlers = setupHandlers();
+      vi.mocked(lib.runOrDiagnose).mockImplementation(async (args: string[]) => {
+        if (args[1] === 'get') {
+          return toText(JSON.stringify({ range: 'A1', values: [[1]] }));
+        }
+        return toText('{}');
+      });
+      await handlers.get('gog_sheets_number_format')!({ spreadsheetId: 'sid', range: 'A1', type: 'DATE', account: 'a@b.com' });
+      expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+        ['sheets', 'get', 'sid', 'A1', '--render=UNFORMATTED_VALUE'],
+        { account: 'a@b.com' },
+      );
+      expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+        ['sheets', 'number-format', 'sid', 'A1', '--type=DATE'],
+        { account: 'a@b.com' },
+      );
+    });
+  });
 });
 
 // 12. read-format