gogcli-mcp-sheets 2.25.0 → 2.26.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.25.0"
+    "version": "2.26.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli (Sheets)",
       "source": "./",
       "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
-      "version": "2.25.0",
+      "version": "2.26.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/README.md

@@ -44,9 +44,9 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 claude mcp add gogcli-sheets -- gogcli-mcp-sheets
 ```
 
-## Extra Sheets Tools (55)
+## Extra Sheets Tools (59)
 
-Plus 8 auth tools and 8 base Sheets tools (get, update, append, clear, metadata, create, find-replace, run) — 71 in all.
+Plus 8 auth tools and 8 base Sheets tools (get, update, append, clear, metadata, create, find-replace, run) — 75 in all.
 
 | Tool | Description |
 |------|-------------|
@@ -79,6 +79,10 @@ Plus 8 auth tools and 8 base Sheets tools (get, update, append, clear, metadata,
 | `gog_sheets_datasource_table_list` | List anchored data-source tables (extracts) and their A1 anchors |
 | `gog_sheets_datasource_table_describe` | Describe the extract anchored at an A1 cell |
 | `gog_sheets_datasource_table_read` | Read a bounded number of rows out of an extract |
+| `gog_sheets_datasource_add` | Add a BigQuery Connected Sheets data source (custom SQL or a native table) |
+| `gog_sheets_datasource_update` | Repoint a data source's SQL, table or billing project |
+| `gog_sheets_datasource_refresh` | Re-run a data source so its sheet and extracts pick up current data |
+| `gog_sheets_datasource_delete` | Delete a data source, its linked sheet, and unlink dependent objects |
 | `gog_sheets_list_tabs` | List tabs in a spreadsheet (sheetId, title, index, gridProperties) |
 | `gog_sheets_copy_paste` | Copy a range's values/formulas/format to another range (tiles to fill down/across). |
 | `gog_sheets_validation_get` | Read data-validation rules (dropdowns, checkboxes, conditions) on a range. |

package/SKILL.md

@@ -58,6 +58,10 @@ Extended Google Sheets MCP server via [gogcli](https://github.com/openclaw/gogcl
 | `gog_sheets_datasource_table_list` | List anchored data-source tables (extracts) and their A1 anchors |
 | `gog_sheets_datasource_table_describe` | Describe the extract anchored at an A1 cell |
 | `gog_sheets_datasource_table_read` | Read a bounded number of rows out of an extract |
+| `gog_sheets_datasource_add` | Add a BigQuery Connected Sheets data source (custom SQL or a native table) |
+| `gog_sheets_datasource_update` | Repoint a data source's SQL, table or billing project |
+| `gog_sheets_datasource_refresh` | Re-run a data source so its sheet and extracts pick up current data |
+| `gog_sheets_datasource_delete` | Delete a data source, its linked sheet, and unlink dependent objects |
 | `gog_sheets_named_ranges_list` | List named ranges |
 | `gog_sheets_named_ranges_get` | Get a named range |
 | `gog_sheets_named_ranges_add` | Create a named range |

package/dist/index.js

@@ -31000,9 +31000,82 @@ var StdioServerTransport = class {
   }
 };
 
+// ../../node_modules/@chrischall/mcp-utils/dist/errors/index.js
+var McpToolError = class extends Error {
+  /** Actionable remediation text, when one applies. */
+  hint;
+  constructor(message, opts) {
+    super(message, opts?.cause !== void 0 ? { cause: opts.cause } : void 0);
+    this.name = "McpToolError";
+    if (opts?.hint !== void 0)
+      this.hint = opts.hint;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var BEARER_RE = /(bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi;
+var JWT_RE = /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{8,}\b/g;
+var BASIC_AUTH_RE = /(authorization\s*:\s*basic\s+)[A-Za-z0-9+/=_-]{6,}/gi;
+var SET_COOKIE_RE = /(\bset-cookie\s*:\s*)([^=;,\s]+)=[^;,\s]*/gi;
+var COOKIE_HEADER_RE = /((?<!set-)\bcookie\s*:\s*)((?:[^=;,\s]+=[^;,\s]*)(?:;\s*[^=;,\s]+=[^;,\s]*)*)/gi;
+var API_KEY_RE = new RegExp([
+  "sk-[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])",
+  // OpenAI / Anthropic (incl. sk-ant-…)
+  "gh[pousr]_[A-Za-z0-9]{36,}\\b",
+  // GitHub ghp_/gho_/ghu_/ghs_/ghr_
+  "xox[baprs]-[A-Za-z0-9-]{10,}(?![A-Za-z0-9-])",
+  // Slack
+  "AIza[0-9A-Za-z_-]{35}(?![0-9A-Za-z_-])",
+  // Google API key (39 chars total)
+  "AKIA[0-9A-Z]{16}\\b",
+  // AWS access key id (20 chars total)
+  "whsec_[A-Za-z0-9]{16,}\\b"
+  // webhook signing secret (Stripe-style)
+].map((p) => `\\b${p}`).join("|"), "g");
+var QUERY_SECRET_RE = /([?&](?:access_token|refresh_token|client_secret|api_?key|signature|token|key|sig)=)[^&#\s"'<>`]+/gi;
+var AWS_SIGV4_RE = /([?&]X-Amz-(?:Signature|Security-Token|Credential)=)[^&#\s"'<>`]+/gi;
+var JSON_SECRET_KEYS = "access_token|refresh_token|client_secret|api_?key|password|passwd|secret|token";
+var JSON_SECRET_DQ_RE = new RegExp(`("(?:${JSON_SECRET_KEYS})"\\s*:\\s*")[^"]*(")`, "gi");
+var JSON_SECRET_SQ_RE = new RegExp(`('(?:${JSON_SECRET_KEYS})'\\s*:\\s*')[^']*(')`, "gi");
+function redactSecrets(text) {
+  return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(AWS_SIGV4_RE, "$1[REDACTED]").replace(JSON_SECRET_DQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_SQ_RE, "$1[REDACTED]$2").replace(JWT_RE, "[REDACTED]");
+}
+
+// ../../node_modules/@chrischall/mcp-utils/dist/response/index.js
+function rawTextResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+function errorResult(message) {
+  return {
+    content: [{ type: "text", text: redactSecrets(message) }],
+    isError: true
+  };
+}
+
 // ../../node_modules/@chrischall/mcp-utils/dist/server/index.js
+function hintResultOrRethrow(err) {
+  if (err instanceof McpToolError && err.hint) {
+    return errorResult(`${err.message}
+
+Hint: ${err.hint}`);
+  }
+  throw err;
+}
+function surfaceToolHints(server) {
+  const register = server.registerTool.bind(server);
+  server.registerTool = (name, config2, cb) => register(name, config2, (...args) => {
+    let result;
+    try {
+      result = cb(...args);
+    } catch (err) {
+      return hintResultOrRethrow(err);
+    }
+    return result instanceof Promise ? result.catch(hintResultOrRethrow) : result;
+  });
+}
 async function createMcpServer(opts) {
   const server = new McpServer({ name: opts.name, version: opts.version });
+  if (opts.surfaceHints !== false)
+    surfaceToolHints(server);
   if (opts.banner !== void 0) {
     console.error(opts.banner);
   }
@@ -31047,46 +31120,6 @@ async function runMcp(opts) {
   return server;
 }
 
-// ../../node_modules/@chrischall/mcp-utils/dist/errors/index.js
-var BEARER_RE = /(bearer\s+)[A-Za-z0-9._~+/=-]{8,}/gi;
-var JWT_RE = /\b[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{8,}\b/g;
-var BASIC_AUTH_RE = /(authorization\s*:\s*basic\s+)[A-Za-z0-9+/=_-]{6,}/gi;
-var SET_COOKIE_RE = /(\bset-cookie\s*:\s*)([^=;,\s]+)=[^;,\s]*/gi;
-var COOKIE_HEADER_RE = /((?<!set-)\bcookie\s*:\s*)((?:[^=;,\s]+=[^;,\s]*)(?:;\s*[^=;,\s]+=[^;,\s]*)*)/gi;
-var API_KEY_RE = new RegExp([
-  "sk-[A-Za-z0-9_-]{20,}(?![A-Za-z0-9_-])",
-  // OpenAI / Anthropic (incl. sk-ant-…)
-  "gh[pousr]_[A-Za-z0-9]{36,}\\b",
-  // GitHub ghp_/gho_/ghu_/ghs_/ghr_
-  "xox[baprs]-[A-Za-z0-9-]{10,}(?![A-Za-z0-9-])",
-  // Slack
-  "AIza[0-9A-Za-z_-]{35}(?![0-9A-Za-z_-])",
-  // Google API key (39 chars total)
-  "AKIA[0-9A-Z]{16}\\b",
-  // AWS access key id (20 chars total)
-  "whsec_[A-Za-z0-9]{16,}\\b"
-  // webhook signing secret (Stripe-style)
-].map((p) => `\\b${p}`).join("|"), "g");
-var QUERY_SECRET_RE = /([?&](?:access_token|refresh_token|client_secret|api_?key|signature|token|key|sig)=)[^&#\s"'<>`]+/gi;
-var AWS_SIGV4_RE = /([?&]X-Amz-(?:Signature|Security-Token|Credential)=)[^&#\s"'<>`]+/gi;
-var JSON_SECRET_KEYS = "access_token|refresh_token|client_secret|api_?key|password|passwd|secret|token";
-var JSON_SECRET_DQ_RE = new RegExp(`("(?:${JSON_SECRET_KEYS})"\\s*:\\s*")[^"]*(")`, "gi");
-var JSON_SECRET_SQ_RE = new RegExp(`('(?:${JSON_SECRET_KEYS})'\\s*:\\s*')[^']*(')`, "gi");
-function redactSecrets(text) {
-  return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(AWS_SIGV4_RE, "$1[REDACTED]").replace(JSON_SECRET_DQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_SQ_RE, "$1[REDACTED]$2").replace(JWT_RE, "[REDACTED]");
-}
-
-// ../../node_modules/@chrischall/mcp-utils/dist/response/index.js
-function rawTextResult(text) {
-  return { content: [{ type: "text", text }] };
-}
-function errorResult(message) {
-  return {
-    content: [{ type: "text", text: redactSecrets(message) }],
-    isError: true
-  };
-}
-
 // ../../node_modules/@chrischall/mcp-utils/dist/config/index.js
 var PLACEHOLDER_RE = /^\$\{[^}]*\}$/;
 function readEnvVar(key, opts = {}) {
@@ -31886,6 +31919,16 @@ function authToolsFor(defaultServices) {
   return (server) => registerAuthToolsWith(server, defaultServices);
 }
 
+// ../gogcli-mcp/src/tools/calendar.ts
+var reminderParams = {
+  reminders: external_exports.array(external_exports.string()).max(5).optional().describe(
+    `Reminders as method:duration, e.g. ["popup:30m", "email:1d"]. Method is popup or email; duration accepts m/h/d (max 40320 minutes = 4 weeks). Google allows at most 5. These REPLACE the event's reminders \u2014 on update, pass an EMPTY array to drop custom reminders and go back to the calendar's defaults. Cannot be combined with noReminders.`
+  ),
+  noReminders: external_exports.boolean().optional().describe(
+    "Give the event no reminders at all, overriding the calendar's defaults. Different from an empty reminders array, which RESTORES those defaults. Cannot be combined with reminders."
+  )
+};
+
 // ../gogcli-mcp/src/attachments.ts
 var MAX_INLINE_ATTACHMENT_BYTES = 8 * 1024 * 1024;
 var RUNNER_MAX_BODY_BYTES = 32 * 1024 * 1024;
@@ -32074,7 +32117,7 @@ function registerSheetsTools(server) {
 }
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.25.0" : "0.0.0";
+var VERSION = true ? "2.26.0" : "0.0.0";
 
 // ../gogcli-mcp/src/auth-log.ts
 var FAILURES = /* @__PURE__ */ new Set([
@@ -33509,6 +33552,86 @@ ${errorText(err)}`
     if (render) args.push(`--render=${render}`);
     return runOrDiagnose(args, { account });
   });
+  const bigQueryChargeNote = " COSTS MONEY AND RUNS ASYNCHRONOUSLY: this starts a BigQuery execution billed to the billing project, and returns once the execution has been REQUESTED \u2014 not once it has finished. Poll gog_sheets_datasource_describe until its dataExecutionStatus state is SUCCEEDED or FAILED before treating the data as current.";
+  server.registerTool("gog_sheets_datasource_add", {
+    description: "Add a BigQuery Connected Sheets data source to a spreadsheet, creating its linked DATA_SOURCE sheet. Point it at EITHER a custom SQL query (query) OR an existing native table (dataset + table) \u2014 never both. billingProject is the BigQuery project charged for the query; tableProject only names which project OWNS the table, and defaults to the billing project. Returns the new dataSourceId, which every other datasource tool takes." + bigQueryChargeNote + bigQueryScopeNote,
+    inputSchema: {
+      spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
+      billingProject: external_exports.string().describe("Billing-enabled BigQuery project charged for this source's queries"),
+      query: external_exports.string().optional().describe("BigQuery SQL to run. Mutually exclusive with dataset/table/tableProject."),
+      dataset: external_exports.string().optional().describe("BigQuery dataset ID of an existing table. Requires table; mutually exclusive with query."),
+      table: external_exports.string().optional().describe("BigQuery table ID. Requires dataset; mutually exclusive with query."),
+      tableProject: external_exports.string().optional().describe("BigQuery project that owns the table (default: the billing project). Only valid with dataset/table."),
+      account: accountParam
+    }
+  }, async ({ spreadsheetId, billingProject, query, dataset, table, tableProject, account }) => {
+    const tableFlags = tableProject !== void 0 || dataset !== void 0 || table !== void 0;
+    if (query !== void 0 && tableFlags) {
+      throw new Error("query and the table fields (dataset, table, tableProject) are mutually exclusive \u2014 a data source is backed by one or the other.");
+    }
+    if (query === void 0 && !(dataset && table)) {
+      throw new Error("Pass query, or both --dataset and --table (tableProject alone is not a table).");
+    }
+    const args = ["sheets", "datasource", "add", spreadsheetId, `--billing-project=${billingProject}`];
+    if (query !== void 0) args.push(`--query=${query}`);
+    if (tableProject) args.push(`--table-project=${tableProject}`);
+    if (dataset) args.push(`--dataset=${dataset}`);
+    if (table) args.push(`--table=${table}`);
+    return runOrDiagnose(args, { account });
+  });
+  server.registerTool("gog_sheets_datasource_update", {
+    description: "Repoint an existing BigQuery Connected Sheets data source: new SQL for a query-backed source, a new dataset/table for a table-backed one, or a new billing project for either. Only the fields you pass are changed. You cannot convert a source between the two kinds \u2014 gog refuses SQL on a table source and table fields on a query source \u2014 so read gog_sheets_datasource_describe first if you are unsure which kind it is. Replacing the SQL DISCARDS the source's current results." + bigQueryChargeNote + bigQueryScopeNote,
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
+      dataSourceId: external_exports.string().describe("Data source ID, as reported by gog_sheets_datasource_list"),
+      billingProject: external_exports.string().optional().describe("New billing-enabled BigQuery project to charge executions to"),
+      query: external_exports.string().optional().describe("Replacement SQL. Only valid on a query-backed source; mutually exclusive with the table fields."),
+      dataset: external_exports.string().optional().describe("Replacement dataset ID. Only valid on a table-backed source."),
+      table: external_exports.string().optional().describe("Replacement table ID. Only valid on a table-backed source."),
+      tableProject: external_exports.string().optional().describe("Replacement project owning the table. Only valid on a table-backed source."),
+      account: accountParam
+    }
+  }, async ({ spreadsheetId, dataSourceId, billingProject, query, dataset, table, tableProject, account }) => {
+    const tableFlags = tableProject !== void 0 || dataset !== void 0 || table !== void 0;
+    if (query !== void 0 && tableFlags) {
+      throw new Error("query and the table fields (dataset, table, tableProject) are mutually exclusive \u2014 a data source is backed by one or the other.");
+    }
+    if (billingProject === void 0 && query === void 0 && !tableFlags) {
+      throw new Error("nothing to update: pass billingProject, query, dataset, table or tableProject.");
+    }
+    const args = ["sheets", "datasource", "update", spreadsheetId, dataSourceId];
+    if (billingProject !== void 0) args.push(`--billing-project=${billingProject}`);
+    if (query !== void 0) args.push(`--query=${query}`);
+    if (tableProject !== void 0) args.push(`--table-project=${tableProject}`);
+    if (dataset !== void 0) args.push(`--dataset=${dataset}`);
+    if (table !== void 0) args.push(`--table=${table}`);
+    return runOrDiagnose(args, { account });
+  });
+  server.registerTool("gog_sheets_datasource_refresh", {
+    description: "Re-run a Connected Sheets data source so its sheet and extracts pick up current BigQuery data. Google refuses to refresh a source whose previous execution FAILED; forceRefresh overrides that, which is what you want after fixing the underlying query or permissions." + bigQueryChargeNote + bigQueryScopeNote,
+    inputSchema: {
+      spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
+      dataSourceId: external_exports.string().describe("Data source ID, as reported by gog_sheets_datasource_list"),
+      forceRefresh: external_exports.boolean().optional().describe("Refresh even when the previous execution failed"),
+      account: accountParam
+    }
+  }, async ({ spreadsheetId, dataSourceId, forceRefresh, account }) => {
+    const args = ["sheets", "datasource", "refresh", spreadsheetId, dataSourceId];
+    if (forceRefresh) args.push("--force-refresh");
+    return runOrDiagnose(args, { account });
+  });
+  server.registerTool("gog_sheets_datasource_delete", {
+    description: "Delete a Connected Sheets data source. This is WIDER than it sounds: it also deletes the source's linked DATA_SOURCE sheet, and unlinks every extract, chart and pivot table built on it elsewhere in the spreadsheet \u2014 objects on other tabs that the caller never named. Take gog_sheets_snapshot first if any of that matters. The BigQuery data itself is untouched; only the spreadsheet's connection to it goes away." + bigQueryScopeNote,
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      spreadsheetId: external_exports.string().describe("Spreadsheet ID"),
+      dataSourceId: external_exports.string().describe("Data source ID, as reported by gog_sheets_datasource_list"),
+      account: accountParam
+    }
+  }, async ({ spreadsheetId, dataSourceId, account }) => {
+    return runOrDiagnose(["sheets", "datasource", "delete", spreadsheetId, dataSourceId, "--force"], { account });
+  });
 }
 
 // src/index.ts

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-sheets",
   "display_name": "gogcli (Sheets)",
-  "version": "2.25.0",
+  "version": "2.26.0",
   "description": "Extended Google Sheets for Claude via gogcli — auth + full Sheets support",
   "author": {
     "name": "Chris Hall",
@@ -339,6 +339,22 @@
     {
       "name": "gog_sheets_datasource_table_read",
       "description": "Read a bounded number of rows out of a data-source table (extract)"
+    },
+    {
+      "name": "gog_sheets_datasource_add",
+      "description": "Add a BigQuery Connected Sheets data source (custom SQL or a native table)"
+    },
+    {
+      "name": "gog_sheets_datasource_update",
+      "description": "Repoint a Connected Sheets data source's SQL, table or billing project"
+    },
+    {
+      "name": "gog_sheets_datasource_refresh",
+      "description": "Re-run a Connected Sheets data source against current BigQuery data"
+    },
+    {
+      "name": "gog_sheets_datasource_delete",
+      "description": "Delete a Connected Sheets data source and its linked sheet"
     }
   ],
   "compatibility": {

package/mint.yaml

@@ -0,0 +1,107 @@
+version: 1
+name: Google Sheets (gogcli)
+slug: gogcli-mcp-sheets
+summary: >-
+  Extended Google Sheets MCP server via gogcli — all base tools plus full
+  Sheets support
+command:
+  # This package publishes a single bin; naming it keeps the install
+  # unambiguous alongside its eight sibling packages.
+  bin: gogcli-mcp-sheets
+env:
+  - name: GOG_CLIENT_ID
+    required: false
+    help: >-
+      Google OAuth client id. NOTE: on the local-spawn path the child `gog`
+      receives a sanitized env — runner.ts drops GOG_ACCESS_TOKEN and every
+      *_TOKEN / *_SECRET / *_API_KEY / *_PRIVATE_KEY variable — so the CLI
+      authenticates from its own stored credentials under $HOME (see
+      state.dataDir), not from these variables being passed through.
+  - name: GOG_CLIENT_SECRET
+    secret: true
+    required: false
+    help: >-
+      Google OAuth client secret. Stripped from the spawned CLI's environment
+      by runner.ts's *_SECRET rule — see GOG_CLIENT_ID.
+  - name: GOG_REFRESH_TOKEN
+    secret: true
+    required: false
+    help: >-
+      Google OAuth refresh token. Stripped from the spawned CLI's environment
+      by runner.ts's *_TOKEN rule — see GOG_CLIENT_ID. A hosted deployment must
+      therefore carry gog's authorised-account state in its persisted data dir,
+      or drive a remote runner via GOG_RUNNER_URL.
+  - name: GOG_ACCESS_TOKEN
+    secret: true
+    required: false
+    help: >-
+      Deliberately removed from the spawned CLI's environment by runner.ts, so
+      that a stale directly-passed token cannot shadow gog's stored refresh
+      credential. Leave unset.
+  - name: GOG_ACCOUNT
+    required: false
+    help: >-
+      Which configured Google account to act as, when more than one is
+      authorised. Defaults to the single/most recent account.
+  - name: GOG_READONLY
+    required: false
+    help: >-
+      Set to 1 to refuse every mutating operation. Recommended when the
+      connector is shared or you only need reads.
+  - name: GOG_PATH
+    required: false
+    help: >-
+      Path to the `gog` binary. Leave unset when the dependency below supplies
+      it; set it only to point at a binary you manage yourself.
+  - name: GOG_RUNNER_URL
+    required: false
+    help: >-
+      URL of a remote gog runner to execute against instead of spawning the
+      local binary. If you set this, add its host to egress.allow.
+  - name: GOG_RUNNER_KEY
+    secret: true
+    required: false
+    help: >-
+      Shared key authenticating calls to GOG_RUNNER_URL. Required whenever that
+      is set.
+  - name: GOG_TIMEZONE
+    required: false
+    help: >-
+      The IANA zone gog itself formats its naive timestamps in. The wrapper
+      reads it (naiveSourceTimeZone) to re-attach the correct offset, so it
+      should match gog's own configuration. Falls back to DISPLAY_TZ, then to
+      America/New_York.
+  - name: DISPLAY_TZ
+    required: false
+    help: >-
+      The IANA zone every rendered *Display field uses (displayTimeZone,
+      default America/New_York). It does not read GOG_TIMEZONE — the fallback
+      runs the other way, so this is also what GOG_TIMEZONE falls back to. An
+      invalid value degrades to the default rather than throwing.
+dependencies:
+  # Every tool shells out to the `gog` CLI; without it the server starts and
+  # then fails on the first call. This tag must track
+  # packages/gogcli-mcp/src/runner.ts's MIN_GOG_VERSION (the floor the tools
+  # assume) and the fly-gog-runner/Dockerfile GOG_VERSION build arg. See
+  # CLAUDE.md "Required gog version" — bumping the floor means bumping these
+  # nine pins too.
+  - kind: github-release
+    repo: openclaw/gogcli
+    tag: v0.38.1
+    asset: "gogcli_*_linux_amd64.tar.gz"
+    bin: [gog]
+state:
+  dataDir: true
+  reason: >-
+    `gog` keeps its authorised-account state and token cache under $HOME.
+    Without a persistent data dir every cold start has no account configured and
+    every tool call fails until the credentials are re-supplied.
+egress:
+  allow:
+    # Google OAuth token exchange and the Google REST APIs the CLI calls.
+    - oauth2.googleapis.com
+    - www.googleapis.com
+    - googleapis.com
+    #
+    # NOTE: if you set GOG_RUNNER_URL to run against a remote gog runner, add
+    # that host here too — it is supplied at runtime and cannot be declared.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-sheets",
-  "version": "2.25.0",
+  "version": "2.26.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>",
@@ -24,7 +24,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.14.0",
+    "@chrischall/mcp-utils": "^0.15.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   },

package/server.json

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

package/src/tools/sheets-extra.ts

@@ -1006,9 +1006,9 @@ export function registerExtraSheetsTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
-  // Connected Sheets (gog >= 0.37.0, openclaw/gogcli#938). Read-only by
-  // construction — gog exposes no create/update/refresh/delete here, so none of
-  // these can change a data source or trigger a query.
+  // Connected Sheets (gog >= 0.37.0 for the reads, openclaw/gogcli#938; >= 0.38.0
+  // for the writes further down, #1025-#1028). The five tools in this first
+  // group are read-only: none of them changes a data source or starts a query.
   //
   // The scope is the thing to know before calling any of them: Google requires
   // https://www.googleapis.com/auth/bigquery.readonly whenever a Sheets
@@ -1111,4 +1111,135 @@ export function registerExtraSheetsTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
+
+  // Connected Sheets WRITES (gog >= 0.38.0, openclaw/gogcli#1025-#1028). The
+  // 0.37.0 half of this surface could only look; these four change a source or
+  // start a query, and they carry two costs the read tools do not:
+  //
+  //   1. Money. Every one of them (delete excepted) starts a BigQuery execution
+  //      billed to --billing-project, so a careless refresh of a wide query is a
+  //      real charge on someone's account.
+  //   2. Asynchrony. add/update/refresh return a DataExecutionStatus, not data;
+  //      the query keeps running after the call returns. gog_sheets_datasource_describe
+  //      is how you find out whether it SUCCEEDED or FAILED.
+  //
+  // The BigQuery scope note applies here exactly as it does to the reads: the
+  // mutation is a Sheets write, but the response still carries Connected Sheets
+  // data, so Google demands bigquery.readonly for it too.
+  const bigQueryChargeNote =
+    ' COSTS MONEY AND RUNS ASYNCHRONOUSLY: this starts a BigQuery execution billed to the billing project, and returns ' +
+    'once the execution has been REQUESTED — not once it has finished. Poll gog_sheets_datasource_describe until its ' +
+    'dataExecutionStatus state is SUCCEEDED or FAILED before treating the data as current.';
+
+  server.registerTool('gog_sheets_datasource_add', {
+    description:
+      'Add a BigQuery Connected Sheets data source to a spreadsheet, creating its linked DATA_SOURCE sheet. Point it at ' +
+      'EITHER a custom SQL query (query) OR an existing native table (dataset + table) — never both. billingProject is the ' +
+      'BigQuery project charged for the query; tableProject only names which project OWNS the table, and defaults to the ' +
+      'billing project. Returns the new dataSourceId, which every other datasource tool takes.' +
+      bigQueryChargeNote + bigQueryScopeNote,
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      billingProject: z.string().describe('Billing-enabled BigQuery project charged for this source\'s queries'),
+      query: z.string().optional().describe('BigQuery SQL to run. Mutually exclusive with dataset/table/tableProject.'),
+      dataset: z.string().optional().describe('BigQuery dataset ID of an existing table. Requires table; mutually exclusive with query.'),
+      table: z.string().optional().describe('BigQuery table ID. Requires dataset; mutually exclusive with query.'),
+      tableProject: z.string().optional().describe('BigQuery project that owns the table (default: the billing project). Only valid with dataset/table.'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, billingProject, query, dataset, table, tableProject, account }) => {
+    const tableFlags = tableProject !== undefined || dataset !== undefined || table !== undefined;
+    if (query !== undefined && tableFlags) {
+      throw new Error('query and the table fields (dataset, table, tableProject) are mutually exclusive — a data source is backed by one or the other.');
+    }
+    if (query === undefined && !(dataset && table)) {
+      throw new Error('Pass query, or both --dataset and --table (tableProject alone is not a table).');
+    }
+    const args = ['sheets', 'datasource', 'add', spreadsheetId, `--billing-project=${billingProject}`];
+    if (query !== undefined) args.push(`--query=${query}`);
+    if (tableProject) args.push(`--table-project=${tableProject}`);
+    if (dataset) args.push(`--dataset=${dataset}`);
+    if (table) args.push(`--table=${table}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_sheets_datasource_update', {
+    description:
+      'Repoint an existing BigQuery Connected Sheets data source: new SQL for a query-backed source, a new dataset/table for ' +
+      'a table-backed one, or a new billing project for either. Only the fields you pass are changed. You cannot convert a ' +
+      'source between the two kinds — gog refuses SQL on a table source and table fields on a query source — so read ' +
+      'gog_sheets_datasource_describe first if you are unsure which kind it is. Replacing the SQL DISCARDS the source\'s ' +
+      'current results.' + bigQueryChargeNote + bigQueryScopeNote,
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      dataSourceId: z.string().describe('Data source ID, as reported by gog_sheets_datasource_list'),
+      billingProject: z.string().optional().describe('New billing-enabled BigQuery project to charge executions to'),
+      query: z.string().optional().describe('Replacement SQL. Only valid on a query-backed source; mutually exclusive with the table fields.'),
+      dataset: z.string().optional().describe('Replacement dataset ID. Only valid on a table-backed source.'),
+      table: z.string().optional().describe('Replacement table ID. Only valid on a table-backed source.'),
+      tableProject: z.string().optional().describe('Replacement project owning the table. Only valid on a table-backed source.'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, dataSourceId, billingProject, query, dataset, table, tableProject, account }) => {
+    const tableFlags = tableProject !== undefined || dataset !== undefined || table !== undefined;
+    if (query !== undefined && tableFlags) {
+      throw new Error('query and the table fields (dataset, table, tableProject) are mutually exclusive — a data source is backed by one or the other.');
+    }
+    if (billingProject === undefined && query === undefined && !tableFlags) {
+      throw new Error('nothing to update: pass billingProject, query, dataset, table or tableProject.');
+    }
+    const args = ['sheets', 'datasource', 'update', spreadsheetId, dataSourceId];
+    if (billingProject !== undefined) args.push(`--billing-project=${billingProject}`);
+    if (query !== undefined) args.push(`--query=${query}`);
+    if (tableProject !== undefined) args.push(`--table-project=${tableProject}`);
+    if (dataset !== undefined) args.push(`--dataset=${dataset}`);
+    if (table !== undefined) args.push(`--table=${table}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  // Refresh is why MIN_GOG_VERSION is 0.38.1 (openclaw/gogcli#1037). On 0.38.0
+  // a batchUpdate that came back with no RefreshDataSource reply produced an
+  // empty status list and exit 0 — this tool would report a clean success for a
+  // billable execution that may or may not have started, and the caller has no
+  // way to tell the two apart. 0.38.1 fails instead, telling the caller to
+  // inspect the source before retrying, which is the behaviour the description
+  // below promises.
+  server.registerTool('gog_sheets_datasource_refresh', {
+    description:
+      'Re-run a Connected Sheets data source so its sheet and extracts pick up current BigQuery data. Google refuses to ' +
+      'refresh a source whose previous execution FAILED; forceRefresh overrides that, which is what you want after fixing ' +
+      'the underlying query or permissions.' + bigQueryChargeNote + bigQueryScopeNote,
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      dataSourceId: z.string().describe('Data source ID, as reported by gog_sheets_datasource_list'),
+      forceRefresh: z.boolean().optional().describe('Refresh even when the previous execution failed'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, dataSourceId, forceRefresh, account }) => {
+    const args = ['sheets', 'datasource', 'refresh', spreadsheetId, dataSourceId];
+    if (forceRefresh) args.push('--force-refresh');
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_sheets_datasource_delete', {
+    description:
+      'Delete a Connected Sheets data source. This is WIDER than it sounds: it also deletes the source\'s linked ' +
+      'DATA_SOURCE sheet, and unlinks every extract, chart and pivot table built on it elsewhere in the spreadsheet — ' +
+      'objects on other tabs that the caller never named. Take gog_sheets_snapshot first if any of that matters. The ' +
+      'BigQuery data itself is untouched; only the spreadsheet\'s connection to it goes away.' + bigQueryScopeNote,
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      spreadsheetId: z.string().describe('Spreadsheet ID'),
+      dataSourceId: z.string().describe('Data source ID, as reported by gog_sheets_datasource_list'),
+      account: accountParam,
+    },
+  }, async ({ spreadsheetId, dataSourceId, account }) => {
+    // gog gates this delete behind a confirmation; the runner injects
+    // --no-input, so without --force it refuses at runtime. Verified live
+    // against gog 0.38.0: without --force it answers "refusing to delete
+    // Connected Sheets data source … without --force (non-interactive)".
+    return runOrDiagnose(['sheets', 'datasource', 'delete', spreadsheetId, dataSourceId, '--force'], { account });
+  });
+
 }

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

@@ -1611,3 +1611,182 @@ describe('gog_sheets_datasource_table_read', () => {
     expect(lib.runOrDiagnose).not.toHaveBeenCalled();
   });
 });
+
+describe('gog_sheets_datasource_add', () => {
+  it('adds a query-backed source', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_add', {
+      spreadsheetId: 'sid', billingProject: 'my-proj', query: 'SELECT 1',
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'add', 'sid', '--billing-project=my-proj', '--query=SELECT 1'],
+      { account: undefined },
+    );
+  });
+
+  it('adds a table-backed source, including the optional table project', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_add', {
+      spreadsheetId: 'sid', billingProject: 'billing', dataset: 'ds', table: 'tbl', tableProject: 'owner',
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'add', 'sid', '--billing-project=billing', '--table-project=owner', '--dataset=ds', '--table=tbl'],
+      { account: undefined },
+    );
+  });
+
+  it('refuses a call that mixes a query with table flags before spawning gog', async () => {
+    const harness = await setupHandlers();
+    const result = await harness.callTool('gog_sheets_datasource_add', {
+      spreadsheetId: 'sid', billingProject: 'p', query: 'SELECT 1', dataset: 'ds', table: 'tbl',
+    });
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('mutually exclusive');
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+
+  it('refuses a call that names neither a query nor a complete table', async () => {
+    const harness = await setupHandlers();
+    const result = await harness.callTool('gog_sheets_datasource_add', {
+      spreadsheetId: 'sid', billingProject: 'p', dataset: 'ds',
+    });
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('--dataset and --table');
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+});
+
+describe('gog_sheets_datasource_update', () => {
+  it('sends only the fields the caller supplied', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_update', {
+      spreadsheetId: 'sid', dataSourceId: 'ds1', query: 'SELECT 2',
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'update', 'sid', 'ds1', '--query=SELECT 2'],
+      { account: undefined },
+    );
+  });
+
+  it('updates the billing project and table fields together', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_update', {
+      spreadsheetId: 'sid', dataSourceId: 'ds1', billingProject: 'new-proj', dataset: 'ds2', table: 't2',
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'update', 'sid', 'ds1', '--billing-project=new-proj', '--dataset=ds2', '--table=t2'],
+      { account: undefined },
+    );
+  });
+
+  it('moves a table-backed source to another owning project', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_update', {
+      spreadsheetId: 'sid', dataSourceId: 'ds1', tableProject: 'other-owner',
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'update', 'sid', 'ds1', '--table-project=other-owner'],
+      { account: undefined },
+    );
+  });
+
+  it('refuses a call that mixes a query with table flags', async () => {
+    const harness = await setupHandlers();
+    const result = await harness.callTool('gog_sheets_datasource_update', {
+      spreadsheetId: 'sid', dataSourceId: 'ds1', query: 'SELECT 2', table: 't2',
+    });
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('mutually exclusive');
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+
+  it('refuses a call with nothing to update', async () => {
+    const harness = await setupHandlers();
+    const result = await harness.callTool('gog_sheets_datasource_update', { spreadsheetId: 'sid', dataSourceId: 'ds1' });
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain('nothing to update');
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+});
+
+describe('gog_sheets_datasource_refresh', () => {
+  it('requests a refresh', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_refresh', { spreadsheetId: 'sid', dataSourceId: 'ds1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'refresh', 'sid', 'ds1'],
+      { account: undefined },
+    );
+  });
+
+  it('passes --force-refresh after a failed execution', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_refresh', {
+      spreadsheetId: 'sid', dataSourceId: 'ds1', forceRefresh: true,
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'refresh', 'sid', 'ds1', '--force-refresh'],
+      { account: undefined },
+    );
+  });
+});
+
+describe('gog_sheets_datasource_delete', () => {
+  // Every tool a description NAMES has to exist in this package, and a name
+  // that does not is worse than no advice: the model calls it, gets "unknown
+  // tool", and may skip the step the description was insisting on — here, the
+  // backup before an unlink-everything delete. gog_sheets_backup was such a
+  // name; the snapshot tool is gog_sheets_snapshot. Checked across the WHOLE
+  // package (index.ts composes auth + base sheets + these extras), because a
+  // description may legitimately point at a tool another registrar supplies.
+  it('names only tools this package actually registers', async () => {
+    const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
+    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;
+    });
+    lib.authToolsFor('sheets')(server);
+    lib.registerSheetsTools(server);
+    registerExtraSheetsTools(server);
+    const names = [...configs.keys()];
+    for (const [tool, config] of configs) {
+      for (const [referenced] of (config.description ?? '').matchAll(/gog_[a-z_0-9]+/g)) {
+        expect(names, `${tool} references ${referenced}`).toContain(referenced);
+      }
+    }
+  });
+
+  // gog gates this behind a confirmation and the runner always injects
+  // --no-input, so a missing --force fails at runtime against a real gog while
+  // every mocked test still passes. Confirmed live on gog 0.38.0.
+  it('appends --force so the confirmation gate does not refuse it', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_delete', { spreadsheetId: 'sid', dataSourceId: 'ds1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'delete', 'sid', 'ds1', '--force'],
+      { account: undefined },
+    );
+  });
+
+  it('passes the account through', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+    const harness = await setupHandlers();
+    await harness.callTool('gog_sheets_datasource_delete', {
+      spreadsheetId: 'sid', dataSourceId: 'ds1', account: 'me@x.com',
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['sheets', 'datasource', 'delete', 'sid', 'ds1', '--force'],
+      { account: 'me@x.com' },
+    );
+  });
+});