gogcli-mcp-drive 2.21.1 → 2.22.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Extended Google Drive for Claude via gogcli — auth + full Drive support (upload, download, permissions, comments, shared drives)",
-    "version": "2.21.1"
+    "version": "2.22.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli (Drive)",
       "source": "./",
       "description": "Extended Google Drive for Claude via gogcli — auth + full Drive support (upload, download, permissions, comments, shared drives)",
-      "version": "2.21.1",
+      "version": "2.22.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp-drive",
   "displayName": "gogcli (Drive)",
-  "version": "2.21.1",
+  "version": "2.22.0",
   "description": "Extended Google Drive for Claude via gogcli — auth + full Drive support (upload, download, permissions, comments, shared drives)",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -51,7 +51,7 @@ Plus 5 auth tools and 9 base Drive tools (ls, search, get, mkdir, rename, move,
 | Tool | Description |
 |------|-------------|
 | `gog_drive_download` | Download a file (exports Google Docs formats: pdf, docx, xlsx, etc.) |
-| `gog_drive_upload` | Upload a local file, optionally replacing an existing file or converting to Google format |
+| `gog_drive_upload` | Upload a local file, optionally replacing an existing file (unconditionally or only at a given version) or converting to Google format |
 | `gog_drive_sync_push` | Recursively push a local directory's contents into a Drive folder (additive; no remote deletes) |
 | `gog_drive_copy` | Copy a file to a new file with the given name |
 | `gog_drive_url` | Print shareable web URLs for one or more files |

package/SKILL.md

@@ -35,7 +35,7 @@ Extended Google Drive MCP server via [gogcli](https://github.com/openclaw/gogcli
 | Tool | What it does |
 |------|-------------|
 | `gog_drive_download` | Download a file (Google Docs → pdf/docx/xlsx/etc.) |
-| `gog_drive_upload` | Upload a local file, replace existing, or convert to Google format |
+| `gog_drive_upload` | Upload a local file, replace existing (optionally only at a given version), or convert to Google format |
 | `gog_drive_sync_push` | Recursively push a local directory into a Drive folder (additive; no remote deletes) |
 | `gog_drive_copy` | Copy a file to a new file |
 | `gog_drive_url` | Print shareable URLs for one or more files |

package/dist/index.js

@@ -31440,6 +31440,13 @@ var TIMESTAMP_KEYS = /* @__PURE__ */ new Set([
   // Calendar event start/end
   "internalDate",
   // Gmail, epoch milliseconds (authoritative)
+  // gog >= 0.35.0 Gmail message AND thread listings. Already offset-bearing
+  // (RFC3339 from internalDate), so it needs no offset repair — it is
+  // allowlisted purely to gain a Display sibling, and to be re-rendered in
+  // DISPLAY_TZ like every other instant. Separately sourced from the sibling
+  // `date`, which is a naive re-format of the sender's Date header; the two may
+  // legitimately disagree. See docs/timestamps.md.
+  "internalDateIso",
   "modifiedTime",
   // Drive
   "createdTime",
@@ -31674,8 +31681,8 @@ function formatOneAccountHealth(a, now) {
   const age = ageInDays(a.created_at, now);
   const ageStr = age === null ? "" : ` Authorized ${age.toFixed(1)} day(s) ago.`;
   if (a.valid === false) {
-    const cause = INVALID_GRANT_PATTERN.test(a.error ?? "") ? 'refresh token expired or revoked \u2014 commonly the 7-day limit on OAuth consent screens still in "Testing" mode' : a.error?.trim() || "unknown error";
-    return `\u2717 ${email3}: NEEDS RE-AUTH \u2014 ${cause}.${ageStr} Re-authorize with gog_auth_add (browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless).`;
+    const cause2 = INVALID_GRANT_PATTERN.test(a.error ?? "") ? 'refresh token expired or revoked \u2014 commonly the 7-day limit on OAuth consent screens still in "Testing" mode' : a.error?.trim() || "unknown error";
+    return `\u2717 ${email3}: NEEDS RE-AUTH \u2014 ${cause2}.${ageStr} Re-authorize with gog_auth_add (browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless).`;
   }
   if (a.valid === true) {
     let line = `\u2713 ${email3}: token valid.${ageStr}`;
@@ -31717,7 +31724,7 @@ function registerAuthToolsWith(server, defaultServices) {
     }
   });
   server.registerTool("gog_auth_status", {
-    description: "Show gogcli auth configuration: keyring backend, credential files, and auth setup.",
+    description: "Show gogcli auth CONFIGURATION: keyring backend, credential files, and auth setup. Despite the name this is not a health check \u2014 it reads local setup and does not contact Google, so it says nothing about whether an account can still authenticate. Use gog_auth_health for that.",
     annotations: { readOnlyHint: true },
     inputSchema: {}
   }, async () => {
@@ -31728,7 +31735,7 @@ function registerAuthToolsWith(server, defaultServices) {
     }
   });
   server.registerTool("gog_auth_health", {
-    description: 'Check the LIVE health of each stored Google account. Unlike gog_auth_status (which only reports keyring/config setup), this performs a real token refresh against Google, so it detects expired or revoked (invalid_grant) refresh tokens \u2014 the account-wide sign-out that blocks every service. Reports per account: whether the token is currently valid, the mapped cause when it is not, how long ago it was authorized, and a warning as it approaches the 7-day refresh-token limit that applies to OAuth apps whose consent screen is still in "Testing" mode. Run it proactively to re-authorize on your own schedule instead of mid-task.',
+    description: 'Check the LIVE health of each stored Google account. Unlike gog_auth_status (which only reports keyring/config setup), this performs a real token refresh against Google, so it detects expired or revoked (invalid_grant) refresh tokens \u2014 the account-wide sign-out that blocks every service. Reports per account: whether the token is currently valid, the mapped cause when it is not, how long ago it was authorized, and a warning as it approaches the 7-day refresh-token limit that applies to OAuth apps whose consent screen is still in "Testing" mode. Run it proactively to re-authorize on your own schedule instead of mid-task. On the hosted connector this is the ONLY check that measures Google: a connector showing "connected" or "refreshed" has verified the connector key that reaches the gog machine, and nothing else \u2014 the Google credential lives on that machine and can be dead while the connection looks perfectly healthy.',
     annotations: { readOnlyHint: true },
     inputSchema: {}
   }, async () => {
@@ -32049,14 +32056,29 @@ var failIfNotEmptyParam = external_exports.boolean().optional().describe(
 );
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.21.1" : "0.0.0";
+var VERSION = true ? "2.22.0" : "0.0.0";
 
 // ../gogcli-mcp/src/auth-log.ts
 var FAILURES = /* @__PURE__ */ new Set([
   "token.mint-failed",
   "grant.dead",
   "replay.failed",
-  "runner.auth-failed"
+  "runner.auth-failed",
+  "connect.key-rejected",
+  // An enrolment that could not proceed is a failure even though nobody is at
+  // fault: it is the only trace a half-enrolled connector leaves behind, and
+  // the absence of exactly this record is why DEFECT 4 could not be explained.
+  "connect.runner-unreachable",
+  "connect.google-unhealthy",
+  "refusal.google-unhealthy",
+  // The loudest record on this branch, and the only one that means "we cannot
+  // explain this". Google refused a real call while a live check of the same
+  // credential, taken seconds later, succeeded — so neither the 7-day cliff nor
+  // a revoked grant accounts for it. It is filed as a failure precisely because
+  // it is the record nobody may scroll past: it is the only evidence that could
+  // ever justify building something on the hosted path, and its absence over
+  // time is what retires that theory for good.
+  "refusal.google-ok"
 ]);
 var PREFIX = "gog-auth ";
 var TAG_CHARS = 12;
@@ -32203,10 +32225,39 @@ async function exchange(refreshToken, clientId, clientSecret) {
   return { accessToken: body.access_token, expiresAt: Date.now() + expiresInMs };
 }
 
+// ../gogcli-mcp/src/google-probe.ts
+var bool = (value) => typeof value === "boolean" ? value : void 0;
+var cause = (value) => typeof value === "string" && value.length > 0 ? value : void 0;
+function readGoogleProbe(body) {
+  const record2 = typeof body === "object" && body !== null ? body : {};
+  const measured = bool(record2.measured);
+  const reported = cause(record2.error);
+  if (measured === false) {
+    return {
+      kind: "unmeasured",
+      reason: reported ?? "the runner reported it could not measure the Google layer"
+    };
+  }
+  if (measured === true) {
+    if (bool(record2.ok) === true) return { kind: "ok" };
+    return {
+      kind: "unhealthy",
+      reason: reported ?? "the runner reported the Google layer unhealthy with no cause"
+    };
+  }
+  return {
+    kind: "unmeasured",
+    reason: reported ? `the runner did not report whether it measured the Google layer; it said: ${reported}` : "the runner did not report whether it measured the Google layer"
+  };
+}
+
 // ../gogcli-mcp/src/connector-runtime.ts
 var DEFAULT_TIMEOUT_MS = 3e4;
 var DEADLINE_GRACE_MS = 5e3;
 var MIN_REPLAY_BUDGET_MS = 1e3;
+var REFUSAL_PROBE_TIMEOUT_MS = 4e3;
+var MIN_PROBE_BUDGET_MS = 1e3;
+var PROBE_INTERVAL_MS = 6e4;
 var RUNNER_GOG_FAILED = 422;
 var RUNNER_DRAINING = 503;
 var RUNNER_BAD_REQUEST = 400;
@@ -32253,7 +32304,7 @@ function gogTarget(args) {
   }
   return { service };
 }
-async function remintAfterGoogleRejection(err, used, args, readAccessToken, deadlineAt) {
+async function remintAfterGoogleRejection(err, used, args, readAccessToken, deadlineAt, probeGoogle) {
   if (!(err instanceof GogFailedError)) return void 0;
   const grantDead = REFRESH_TOKEN_DEAD_PATTERN.test(err.stderr);
   if (!grantDead && !GOOGLE_TOKEN_REJECTED_PATTERN.test(err.stderr)) return void 0;
@@ -32268,6 +32319,7 @@ async function remintAfterGoogleRejection(err, used, args, readAccessToken, dead
     return void 0;
   }
   if (!used) {
+    await probeGoogle(where);
     logAuthTransition("replay.declined", {
       ...where,
       reason: "no access token was supplied with the call, so gog acted as the backend volume\u2019s own identity"
@@ -32315,6 +32367,64 @@ async function remintAfterGoogleRejection(err, used, args, readAccessToken, dead
   return { token: fresh, budgetMs, invalidate: readAccessToken.invalidate, ...where };
 }
 function makeFlyExecutor(endpoint, key, readAccessToken) {
+  let lastProbeAt = Number.NEGATIVE_INFINITY;
+  const probeGoogleAfterRefusal = async (where, deadlineAt) => {
+    const record2 = { ...where, endpoint };
+    const now = Date.now();
+    const remainingMs = deadlineAt - now;
+    if (remainingMs < MIN_PROBE_BUDGET_MS) {
+      logAuthTransition("refusal.google-unmeasured", {
+        ...record2,
+        reason: `only ${remainingMs}ms of the call\u2019s deadline remained, so the Google layer was not measured rather than delay the caller\u2019s own error`
+      });
+      return;
+    }
+    if (now - lastProbeAt < PROBE_INTERVAL_MS) {
+      logAuthTransition("refusal.google-unmeasured", {
+        ...record2,
+        // "attempted", not "measured". `lastProbeAt` is stamped before the
+        // fetch and is deliberately NOT reset when the probe comes back with no
+        // verdict (a 404 from a runner too old to have the endpoint, a timeout,
+        // a dead socket) — the backend cost this throttle exists to bound was
+        // paid either way, and resetting it would let a retry loop storm a
+        // runner that is already unwell. So the timestamp stays and the sentence
+        // has to be the true one: on this branch a log line may not assert a
+        // measurement that never happened, and the previous probe may well have
+        // measured nothing at all.
+        reason: "a Google probe was attempted recently, so another was not sent: this probe spawns gog on the backend and takes the keyring\u2019s exclusive lock"
+      });
+      return;
+    }
+    lastProbeAt = now;
+    let event;
+    let reason;
+    try {
+      const res = await fetch(`${endpoint}/health/google`, {
+        headers: { Authorization: `Bearer ${key}` },
+        // Never more than the probe's own budget, never more than the call has
+        // left. `Math.min` rather than a plain constant because the second
+        // bound is the caller's, and it outranks ours.
+        signal: AbortSignal.timeout(Math.min(REFUSAL_PROBE_TIMEOUT_MS, remainingMs))
+      });
+      if (!res.ok) {
+        event = "refusal.google-unmeasured";
+        reason = `the runner did not answer the Google probe (HTTP ${res.status})`;
+      } else {
+        const verdict = readGoogleProbe(await res.json());
+        if (verdict.kind === "ok") {
+          event = "refusal.google-ok";
+          reason = "Google refused this call, yet a live token check on the same volume succeeded \u2014 so a dead or expired refresh token does not explain this refusal";
+        } else {
+          event = verdict.kind === "unhealthy" ? "refusal.google-unhealthy" : "refusal.google-unmeasured";
+          reason = verdict.reason;
+        }
+      }
+    } catch (err) {
+      event = "refusal.google-unmeasured";
+      reason = err instanceof Error ? err.message : String(err);
+    }
+    logAuthTransition(event, { ...record2, reason });
+  };
   return async (args, opts) => {
     const deadlineMs = (opts?.timeout ?? DEFAULT_TIMEOUT_MS) + DEADLINE_GRACE_MS;
     const accessToken = await readAccessToken?.();
@@ -32327,7 +32437,8 @@ function makeFlyExecutor(endpoint, key, readAccessToken) {
         accessToken,
         args,
         readAccessToken,
-        deadlineAt
+        deadlineAt,
+        (where2) => probeGoogleAfterRefusal(where2, deadlineAt)
       );
       if (replay === void 0) throw err;
       const where = { credential: replay.credential, service: replay.service, endpoint };
@@ -32451,24 +32562,31 @@ function registerExtraDriveTools(server) {
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_drive_upload", {
-    description: "Upload a local file to Drive. Use --replace to replace the content of an existing file (preserves link/permissions), or --convert to auto-convert to a Google format.",
+    description: 'Upload a local file to Drive. Use replace to replace the content of an existing file (preserves link/permissions), or convert to auto-convert to a Google format. Pair replace with ifVersion to make the overwrite conditional: gog sends an atomic If-Match precondition and reports a conflict \u2014 applying nothing \u2014 if the file changed since you read it, instead of silently clobbering a concurrent edit. No read tool surfaces the version number: fetch it immediately before uploading with gog_drive_run { subcommand: "raw", args: ["<fileId>", "--fields=version"] } \u2014 it comes back as a JSON string, so pass it on as a number. Conditional replacement refuses Google Workspace files (Docs/Sheets/Slides), which have no replaceable binary content.',
     annotations: { destructiveHint: true },
     inputSchema: {
       localPath: external_exports.string().describe("Path to the local file to upload"),
       name: external_exports.string().optional().describe("Override filename (create) or rename target (replace)"),
       parent: external_exports.string().optional().describe("Destination folder ID (create only)"),
-      replace: external_exports.string().optional().describe("Replace content of an existing Drive file ID (preserves link/permissions)"),
+      replace: external_exports.string().optional().describe("Replace content of an existing Drive file ID (preserves link/permissions). Unconditional unless ifVersion is set."),
+      ifVersion: external_exports.number().int().positive().optional().describe(
+        'Replace only if the Drive file is still at this version (requires replace). On mismatch nothing is written and gog reports a conflict \u2014 re-read the file and reapply your edit. Read the current version with gog_drive_run { subcommand: "raw", args: ["<fileId>", "--fields=version"] } \u2014 which answers {"version":"35"}, a JSON STRING (the Drive API serializes its int64 fields as strings). Convert it to a number before passing it here, or this param rejects it.'
+      ),
       mimeType: external_exports.string().optional().describe("Override MIME type inference"),
       keepRevisionForever: external_exports.boolean().optional().describe("Keep the new head revision forever (binary files only)"),
       convert: external_exports.boolean().optional().describe("Auto-convert to native Google format based on file extension (create only)"),
       convertTo: external_exports.string().optional().describe("Convert to a specific Google format: doc | sheet | slides (create only)"),
       account: accountParam
     }
-  }, async ({ localPath, name, parent, replace, mimeType, keepRevisionForever, convert, convertTo, account }) => {
+  }, async ({ localPath, name, parent, replace, ifVersion, mimeType, keepRevisionForever, convert, convertTo, account }) => {
+    if (ifVersion !== void 0 && !replace) {
+      throw new Error("ifVersion requires replace: a version precondition only applies when replacing an existing Drive file.");
+    }
     const args = ["drive", "upload", localPath];
     if (name) args.push(`--name=${name}`);
     if (parent) args.push(`--parent=${parent}`);
     if (replace) args.push(`--replace=${replace}`);
+    if (ifVersion !== void 0) args.push(`--if-version=${ifVersion}`);
     if (mimeType) args.push(`--mime-type=${mimeType}`);
     if (keepRevisionForever) args.push("--keep-revision-forever");
     if (convert) args.push("--convert");

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-drive",
   "display_name": "gogcli (Drive)",
-  "version": "2.21.1",
+  "version": "2.22.0",
   "description": "Extended Google Drive for Claude via gogcli — auth + full Drive support (upload, download, permissions, comments, shared drives)",
   "author": {
     "name": "Chris Hall",
@@ -139,7 +139,7 @@
     },
     {
       "name": "gog_drive_upload",
-      "description": "Upload a local file, optionally replacing an existing file or converting to Google format"
+      "description": "Upload a local file, optionally replacing an existing file (unconditionally, or only at a given version) or converting to Google format"
     },
     {
       "name": "gog_drive_sync_push",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-drive",
-  "version": "2.21.1",
+  "version": "2.22.0",
   "mcpName": "io.github.chrischall/gogcli-mcp-drive",
   "description": "Extended Google Drive MCP server via gogcli — auth + full Drive support (upload/download/permissions/comments/shared drives)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

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

package/src/tools/drive-extra.ts

@@ -22,24 +22,40 @@ export function registerExtraDriveTools(server: McpServer): void {
   });
 
   server.registerTool('gog_drive_upload', {
-    description: 'Upload a local file to Drive. Use --replace to replace the content of an existing file (preserves link/permissions), or --convert to auto-convert to a Google format.',
+    description:
+      'Upload a local file to Drive. Use replace to replace the content of an existing file (preserves link/permissions), ' +
+      'or convert to auto-convert to a Google format. ' +
+      'Pair replace with ifVersion to make the overwrite conditional: gog sends an atomic If-Match precondition and reports ' +
+      'a conflict — applying nothing — if the file changed since you read it, instead of silently clobbering a concurrent edit. ' +
+      'No read tool surfaces the version number: fetch it immediately before uploading with ' +
+      'gog_drive_run { subcommand: "raw", args: ["<fileId>", "--fields=version"] } — it comes back as a JSON string, so pass it on as a number. ' +
+      'Conditional replacement refuses Google Workspace files (Docs/Sheets/Slides), which have no replaceable binary content.',
     annotations: { destructiveHint: true },
     inputSchema: {
       localPath: z.string().describe('Path to the local file to upload'),
       name: z.string().optional().describe('Override filename (create) or rename target (replace)'),
       parent: z.string().optional().describe('Destination folder ID (create only)'),
-      replace: z.string().optional().describe('Replace content of an existing Drive file ID (preserves link/permissions)'),
+      replace: z.string().optional().describe('Replace content of an existing Drive file ID (preserves link/permissions). Unconditional unless ifVersion is set.'),
+      ifVersion: z.number().int().positive().optional().describe(
+        'Replace only if the Drive file is still at this version (requires replace). On mismatch nothing is written and gog reports a conflict — re-read the file and reapply your edit. ' +
+        'Read the current version with gog_drive_run { subcommand: "raw", args: ["<fileId>", "--fields=version"] } — which answers {"version":"35"}, '
+        + 'a JSON STRING (the Drive API serializes its int64 fields as strings). Convert it to a number before passing it here, or this param rejects it.',
+      ),
       mimeType: z.string().optional().describe('Override MIME type inference'),
       keepRevisionForever: z.boolean().optional().describe('Keep the new head revision forever (binary files only)'),
       convert: z.boolean().optional().describe('Auto-convert to native Google format based on file extension (create only)'),
       convertTo: z.string().optional().describe('Convert to a specific Google format: doc | sheet | slides (create only)'),
       account: accountParam,
     },
-  }, async ({ localPath, name, parent, replace, mimeType, keepRevisionForever, convert, convertTo, account }) => {
+  }, async ({ localPath, name, parent, replace, ifVersion, mimeType, keepRevisionForever, convert, convertTo, account }) => {
+    if (ifVersion !== undefined && !replace) {
+      throw new Error('ifVersion requires replace: a version precondition only applies when replacing an existing Drive file.');
+    }
     const args = ['drive', 'upload', localPath];
     if (name) args.push(`--name=${name}`);
     if (parent) args.push(`--parent=${parent}`);
     if (replace) args.push(`--replace=${replace}`);
+    if (ifVersion !== undefined) args.push(`--if-version=${ifVersion}`);
     if (mimeType) args.push(`--mime-type=${mimeType}`);
     if (keepRevisionForever) args.push('--keep-revision-forever');
     if (convert) args.push('--convert');

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

@@ -79,6 +79,50 @@ describe('gog_drive_upload', () => {
     await harness.callTool('gog_drive_upload', { localPath: '/tmp/x.txt', keepRevisionForever: false, convert: false });
     expect(lib.runOrDiagnose).toHaveBeenCalledWith(['drive', 'upload', '/tmp/x.txt'], { account: undefined });
   });
+
+  // gog 0.35.0 (openclaw/gogcli 1b26124) adds --if-version: an atomic
+  // If-Match precondition on --replace that turns a blind overwrite into a
+  // compare-and-swap.
+  it('passes --if-version alongside --replace for conditional replacement', async () => {
+    await harness.callTool('gog_drive_upload', { localPath: '/tmp/x.txt', replace: 'file2', ifVersion: 7 });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['drive', 'upload', '/tmp/x.txt', '--replace=file2', '--if-version=7'],
+      { account: undefined },
+    );
+  });
+
+  it('rejects ifVersion without replace instead of spending a gog call', async () => {
+    const result = await harness.callTool('gog_drive_upload', { localPath: '/tmp/x.txt', ifVersion: 7 });
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toMatch(/ifVersion requires replace/);
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+
+  it('rejects a non-positive ifVersion before it reaches gog', async () => {
+    const result = await harness.callTool('gog_drive_upload', { localPath: '/tmp/x.txt', replace: 'file2', ifVersion: 0 });
+    expect(result.isError).toBe(true);
+    expect(lib.runOrDiagnose).not.toHaveBeenCalled();
+  });
+
+  // No gog read command surfaces the Drive `version` int: driveFileGetFields
+  // and info_via_drive.go both omit it, and `drive upload` itself is the only
+  // caller that requests it. `drive raw` (fields=*) is the sole way to read it,
+  // and it is reachable only through the gog_drive_run escape hatch — so the
+  // description has to say so or the flag is unusable.
+  it('description explains how to obtain the current version', 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;
+    });
+    registerExtraDriveTools(server);
+    const desc = configs.get('gog_drive_upload')?.description ?? '';
+    expect(desc).toMatch(/gog_drive_run/);
+    expect(desc).toMatch(/raw/);
+    expect(desc).toMatch(/--fields=version/);
+  });
 });
 
 describe('gog_drive_sync_push', () => {
@@ -656,3 +700,24 @@ describe('gog_drive_shortcut_create', () => {
     );
   });
 });
+
+// `drive raw <id> --fields=version` returns {"version":"35"} — the Drive v3
+// `version` field is an int64, which Google's JSON encoding serializes as a
+// STRING. ifVersion is z.number().int().positive(), so a model that pastes the
+// value straight back through gets a zod validation error instead of a
+// conditional replace. The description has to say to convert it.
+describe('gog_drive_upload ifVersion description', () => {
+  it('warns that the version reads back as a JSON string', async () => {
+    const { McpServer } = await import('@modelcontextprotocol/sdk/server/mcp.js');
+    const server = new McpServer({ name: 'test', version: '0.0.0' });
+    const schemas = new Map<string, Record<string, { description?: string }>>();
+    vi.spyOn(server, 'registerTool').mockImplementation((name, config) => {
+      schemas.set(name, (config as { inputSchema: Record<string, { description?: string }> }).inputSchema);
+      return undefined as never;
+    });
+    registerExtraDriveTools(server);
+    const desc = schemas.get('gog_drive_upload')?.ifVersion?.description ?? '';
+    expect(desc).toMatch(/string/i);
+    expect(desc).toMatch(/number/i);
+  });
+});