gogcli-mcp-docs 4.9.1 → 4.10.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gogcli-mcp-docs",
   "displayName": "gogcli (Docs)",
-  "version": "4.9.1",
+  "version": "4.10.0",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -79,6 +79,14 @@ These bugs live in gogcli's upstream markdown → Docs converter; the wrapper ju
 | Inline `**bold**` / `*italic*` / `` `code` `` inside table cells renders as literal characters | Insert plain cell text, then apply formatting via `gog_docs_format` | [openclaw/gogcli#608](https://github.com/openclaw/gogcli/issues/608) |
 | Tables with an empty header row leak the last data row as literal pipe text | Always supply a non-empty header row | [openclaw/gogcli#609](https://github.com/openclaw/gogcli/issues/609) |
 
+## Files on a hosted deployment
+
+When this server is hosted (remote), it cannot read paths on your machine. Call
+`gog_upload_slots` with `files: [{filename}]`, PUT each file to its `uploadUrl`
+with the slot's `curl` command, then pass the returned `blobKeys` to `gog_docs_insert_image` and `gog_docs_replace_image` (instead of `file`).
+Files up to 25 MiB; each is deleted from the upload store after the call succeeds
+and kept if it fails. On a local install, pass a path as before.
+
 ## License
 
 MIT

package/SKILL.md

@@ -62,3 +62,11 @@ Three bugs in gogcli's upstream markdown→Docs converter to be aware of:
 - **3+ tables in one call** reorders the trailing punctuation of the paragraph before the 3rd table — split into multiple calls with ≤2 tables each ([openclaw/gogcli#607](https://github.com/openclaw/gogcli/issues/607)).
 - **Inline `**bold**` / `*italic*` / `` `code` `` inside table cells** renders as literal characters — insert plain cell text, then apply formatting via `gog_docs_format` ([openclaw/gogcli#608](https://github.com/openclaw/gogcli/issues/608)).
 - **Empty-header tables** leak the last data row as literal pipe text — always supply a non-empty header row ([openclaw/gogcli#609](https://github.com/openclaw/gogcli/issues/609)).
+
+## Files on a hosted deployment
+
+When this server is hosted (remote), it cannot read paths on your machine. Call
+`gog_upload_slots` with `files: [{filename}]`, PUT each file to its `uploadUrl`
+with the slot's `curl` command, then pass the returned `blobKeys` to `gog_docs_insert_image` and `gog_docs_replace_image` (instead of `file`).
+Files up to 25 MiB; each is deleted from the upload store after the call succeeds
+and kept if it fails. On a local install, pass a path as before.

package/dist/index.js

@@ -14,6 +14,14 @@ function withCallSignal(signal, fn, request) {
 function currentCallSignal() {
   return storage.getStore()?.signal;
 }
+function withAmbientCancellation(own2) {
+  const ambient = currentCallSignal();
+  if (!ambient)
+    return own2;
+  if (!own2)
+    return ambient;
+  return AbortSignal.any([own2, ambient]);
+}
 function killOnCancel(child, signal = "SIGTERM") {
   const ambient = currentCallSignal();
   if (!ambient)
@@ -36309,9 +36317,158 @@ import { constants as fsConstants2, realpathSync as realpathSync2 } from "node:f
 var O_NOFOLLOW2 = fsConstants2.O_NOFOLLOW ?? 0;
 var O_NONBLOCK = fsConstants2.O_NONBLOCK ?? 0;
 
+// ../../node_modules/@chrischall/mcp-utils/dist/internal/headers.js
+function responseHeader(res, name) {
+  return getHeader(res?.headers, name);
+}
+function getHeader(headers, name) {
+  if (!headers || typeof headers.get !== "function")
+    return null;
+  const value = headers.get.call(headers, name);
+  return typeof value === "string" ? value : null;
+}
+
 // ../../node_modules/@chrischall/mcp-utils/dist/scrape/index.js
 var NEXT_DATA_MAX_CHARS = 16 * 1024 * 1024;
 
+// ../../node_modules/@chrischall/mcp-utils/dist/http/body-limit.js
+var ResponseTooLargeError = class extends McpToolError {
+  maxBytes;
+  constructor(service, maxBytes) {
+    super(`Response from ${service} is larger than the ${maxBytes}-byte limit.`, {
+      hint: "Raise maxBytes (or the client's maxResponseBytes) if a response this large is expected.",
+      kind: "too_large"
+    });
+    this.name = "ResponseTooLargeError";
+    this.maxBytes = maxBytes;
+  }
+};
+async function readBytesCapped(res, maxBytes, service, bounded) {
+  if (maxBytes !== void 0) {
+    const declared = Number(responseHeader(res, "content-length") ?? NaN);
+    if (Number.isFinite(declared) && declared > maxBytes) {
+      cancelStream(res.body);
+      throw new ResponseTooLargeError(service, maxBytes);
+    }
+  }
+  if (!res.body)
+    return new Uint8Array(0);
+  const reader = res.body.getReader();
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await bounded(reader.read());
+      if (done)
+        break;
+      total += value.byteLength;
+      if (maxBytes !== void 0 && total > maxBytes)
+        throw new ResponseTooLargeError(service, maxBytes);
+      chunks.push(value);
+    }
+  } catch (err) {
+    reader.cancel().catch(() => {
+    });
+    throw err;
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+function cancelStream(body) {
+  try {
+    body?.cancel().catch(() => {
+    });
+  } catch {
+  }
+}
+
+// ../../node_modules/@chrischall/mcp-utils/dist/http/fetch-bounded.js
+async function fetchBounded(url2, init, opts = {}) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const service = opts.service ?? hostOf(url2);
+  const read = opts.read ?? "text";
+  const timeoutMs = opts.timeoutMs === false ? 0 : opts.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+  const caller = withAmbientCancellation(init?.signal ?? void 0);
+  if (caller?.aborted)
+    throw reasonOf(caller);
+  const timer = timeoutMs > 0 ? new AbortController() : void 0;
+  const signal = combine(timer?.signal, caller);
+  let handle;
+  let detach = () => {
+  };
+  const stop = signal ? new Promise((_resolve, reject) => {
+    const onAbort = () => reject(timer?.signal.aborted ? new RequestTimeoutError(service, timeoutMs) : reasonOf(caller));
+    signal.addEventListener("abort", onAbort, { once: true });
+    detach = () => signal.removeEventListener("abort", onAbort);
+  }) : void 0;
+  stop?.catch(() => {
+  });
+  const bounded = (p) => stop ? Promise.race([p, stop]) : p;
+  if (timer)
+    handle = setTimeout(() => timer.abort(), timeoutMs);
+  try {
+    let res;
+    try {
+      res = await bounded(doFetch(url2, { ...init, ...signal ? { signal } : {} }));
+    } catch (err) {
+      if (timer?.signal.aborted)
+        throw new RequestTimeoutError(service, timeoutMs);
+      if (caller?.aborted)
+        throw reasonOf(caller);
+      throw err;
+    }
+    if (read === "none") {
+      cancelStream(res.body);
+      return done(res, void 0);
+    }
+    const bytes = await readBytesCapped(res, opts.maxBytes, service, bounded);
+    if (read === "bytes")
+      return done(res, bytes);
+    const text = new TextDecoder().decode(bytes);
+    if (read === "text")
+      return done(res, text);
+    if (text.length === 0)
+      return done(res, void 0);
+    try {
+      return done(res, JSON.parse(text));
+    } catch (cause) {
+      const type = res.headers.get("content-type") ?? "no content-type";
+      throw new McpToolError(`${service} returned a non-JSON response (HTTP ${res.status}, ${type}).`, {
+        hint: "The upstream may have served an error or sign-in page instead of data.",
+        cause,
+        status: res.status
+      });
+    }
+  } finally {
+    clearTimeout(handle);
+    detach();
+  }
+  function done(res, body) {
+    return { res, status: res.status, ok: res.ok, headers: res.headers, body };
+  }
+}
+function combine(a, b) {
+  if (a && b)
+    return AbortSignal.any([a, b]);
+  return a ?? b;
+}
+function reasonOf(signal) {
+  const reason = signal.reason;
+  return reason instanceof Error ? reason : new Error(String(reason));
+}
+function hostOf(url2) {
+  try {
+    return new URL(url2).host;
+  } catch {
+    return String(url2);
+  }
+}
+
 // ../../node_modules/@chrischall/mcp-utils/dist/netguard/address.js
 function parseIPv4(text) {
   if (!/^(?:0|[1-9]\d{0,2})(?:\.(?:0|[1-9]\d{0,2})){3}$/.test(text))
@@ -36395,6 +36552,18 @@ var NAT64 = V6("64:ff9b::");
 var SIX_TO_FOUR = V6("2002::");
 
 // ../../node_modules/@chrischall/mcp-utils/dist/http/index.js
+var DEFAULT_REQUEST_TIMEOUT_MS = 3e4;
+var RequestTimeoutError = class extends Error {
+  timeoutMs;
+  /** Always `'timeout'` unless a subclass says otherwise. */
+  kind = "timeout";
+  constructor(service, timeoutMs) {
+    super(`Request to ${service} timed out after ${timeoutMs}ms.`);
+    this.name = "RequestTimeoutError";
+    this.timeoutMs = timeoutMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
 var EDGE_BLOCK_SCAN_MAX = 8 * 1024;
 
 // ../../node_modules/@chrischall/mcp-utils/dist/zod/index.js
@@ -37508,6 +37677,445 @@ var attachInlineParam = external_exports.array(inlineAttachmentSchema).optional(
   `Attachments supplied as BYTES rather than as server-side paths \u2014 use this whenever you hold a file and the gog server does not, which is always the case on a hosted deployment (e.g. mcp-host). Each entry is {filename, contentBase64} (${INLINE_ATTACHMENT_LIMITS_TEXT}). Can be combined with \`attach\`: the two name disjoint files (paths read on the server vs. bytes sent with the call), and both end up as ordinary attachments on the message.`
 );
 
+// ../gogcli-mcp/src/upload-slots.ts
+import { createHash as createHash4 } from "node:crypto";
+import { existsSync as existsSync2 } from "node:fs";
+
+// ../../node_modules/@chrischall/mcp-utils/dist/export/blob.js
+import { createHmac as createHmac3 } from "node:crypto";
+var BLOB_DEFAULT_TTL_MS = 60 * 60 * 1e3;
+var BLOB_MAX_TTL_MS = 24 * 60 * 60 * 1e3;
+var BLOB_MAX_OBJECT_BYTES = 100 * 1024 * 1024;
+var MAX_KEY_LENGTH = 1024;
+var SAFE_SEGMENT = /^[A-Za-z0-9._~-]+$/;
+function configError(reason) {
+  return new McpToolError(`MCP_BLOB_BASE_URL is not usable: ${reason}.`, {
+    hint: "It should look like https://<host>/b/<registrationId> \u2014 check the deployment's environment.",
+    kind: "unknown"
+  });
+}
+function parseBase(baseUrl) {
+  let parsed;
+  try {
+    parsed = new URL(baseUrl);
+  } catch {
+    throw configError("not a valid URL");
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:")
+    throw configError("scheme must be http(s)");
+  if (parsed.username || parsed.password)
+    throw configError("must not contain credentials");
+  if (parsed.search || parsed.hash)
+    throw configError("must not contain a query or fragment");
+  const path = parsed.pathname.replace(/^\/+|\/+$/g, "");
+  const prefix = path.startsWith("b/") ? path.slice(2) : path;
+  if (!prefix || prefix === "b")
+    throw configError("has no registration path");
+  return { base: `${parsed.origin}/${path}`, prefix };
+}
+function badInput(message) {
+  return new McpToolError(message, { kind: "unknown" });
+}
+function encodeKey(key) {
+  if (typeof key !== "string" || key.length === 0)
+    throw badInput("Blob key must be a non-empty string.");
+  if (key.length > MAX_KEY_LENGTH)
+    throw badInput(`Blob key is longer than ${MAX_KEY_LENGTH} characters.`);
+  const segments = key.split("/");
+  for (const seg of segments) {
+    if (seg === "" || seg === "." || seg === ".." || !SAFE_SEGMENT.test(seg)) {
+      throw badInput('Blob key must be relative, slash-separated segments of [A-Za-z0-9._~-] with no empty, "." or ".." segment.');
+    }
+  }
+  return segments.map(encodeURIComponent).join("/");
+}
+function checkContentType(contentType) {
+  if (typeof contentType !== "string" || contentType.length === 0 || /[\x00-\x1f\x7f]/.test(contentType)) {
+    throw badInput("Blob content type must be a non-empty string without control characters.");
+  }
+}
+function expiry(opts) {
+  const ttl = opts?.ttlMs ?? BLOB_DEFAULT_TTL_MS;
+  if (!Number.isFinite(ttl) || ttl <= 0 || ttl > BLOB_MAX_TTL_MS) {
+    throw badInput(`Blob link TTL must be between 1 ms and ${BLOB_MAX_TTL_MS} ms (24h); the gateway refuses longer.`);
+  }
+  return Math.floor((opts?.now ?? Date.now()) + ttl);
+}
+function toArrayBuffer(view) {
+  const buf = view.buffer;
+  if (buf instanceof ArrayBuffer && view.byteOffset === 0 && view.byteLength === buf.byteLength)
+    return buf;
+  return view.slice().buffer;
+}
+function createBlobStore(opts) {
+  const { base, prefix } = parseBase(opts.baseUrl);
+  const signingKey = opts.signingKey;
+  const sign2 = (payload) => createHmac3("sha256", signingKey).update(payload).digest("base64url");
+  const link = (encodedKey, exp, sig) => `${base}/${encodedKey}?exp=${exp}&sig=${encodeURIComponent(sig)}`;
+  const signGetUrl = (key, o) => {
+    const encoded = encodeKey(key);
+    const exp = expiry(o);
+    return { url: link(encoded, exp, sign2(`${prefix}/${key}
+${exp}`)), expiresAtMs: exp };
+  };
+  const signPutUrl = (key, contentType, o) => {
+    const encoded = encodeKey(key);
+    checkContentType(contentType);
+    const exp = expiry(o);
+    return { url: link(encoded, exp, sign2(`put\0${prefix}/${key}\0${contentType}\0${exp}`)), expiresAtMs: exp };
+  };
+  const put = async (key, body, contentType, o = {}) => {
+    const { url: url2 } = signPutUrl(key, contentType, o);
+    const bytes = typeof body === "string" ? new TextEncoder().encode(body) : body;
+    const doFetch = o.fetchImpl ?? fetch;
+    let res;
+    try {
+      res = await doFetch(url2, {
+        method: "PUT",
+        headers: { "content-type": contentType },
+        body: toArrayBuffer(bytes),
+        ...o.signal ? { signal: o.signal } : {}
+      });
+    } catch (cause) {
+      if (o.signal?.aborted)
+        throw cause;
+      throw new McpToolError(`Blob store upload of ${key} did not complete (network error).`, {
+        kind: "transport"
+      });
+    }
+    if (!res.ok) {
+      throw new McpToolError(`Blob store upload of ${key} failed (HTTP ${res.status}).`, {
+        kind: "http",
+        status: res.status
+      });
+    }
+    return { key, bytes: bytes.byteLength };
+  };
+  const signDeleteUrl = (key, o) => {
+    const encoded = encodeKey(key);
+    const exp = expiry(o);
+    return { url: link(encoded, exp, sign2(`del\0${prefix}/${key}\0${exp}`)), expiresAtMs: exp };
+  };
+  const exchange = async (what, url2, method, read, o) => {
+    try {
+      return await fetchBounded(url2, { method, ...o.signal ? { signal: o.signal } : {} }, {
+        read,
+        service: "the blob store",
+        ...read === "bytes" ? { maxBytes: o.maxBytes ?? BLOB_MAX_OBJECT_BYTES } : {},
+        ...o.timeoutMs !== void 0 ? { timeoutMs: o.timeoutMs } : {},
+        ...o.fetchImpl ? { fetchImpl: o.fetchImpl } : {}
+      });
+    } catch (cause) {
+      if (o.signal?.aborted || cause instanceof McpToolError || cause instanceof RequestTimeoutError)
+        throw cause;
+      throw new McpToolError(`Blob store ${what} did not complete (network error).`, { kind: "transport" });
+    }
+  };
+  const get = async (key, o = {}) => {
+    const { url: url2 } = signGetUrl(key, o);
+    const res = await exchange(`read of ${key}`, url2, "GET", "bytes", o);
+    if (!res.ok) {
+      const why = res.status === 404 ? " \u2014 not found (never uploaded, expired, or already consumed)" : "";
+      throw new McpToolError(`Blob store read of ${key} failed (HTTP ${res.status})${why}.`, {
+        kind: "http",
+        status: res.status
+      });
+    }
+    const contentType = res.headers.get("content-type") ?? void 0;
+    return { key, bytes: res.body, ...contentType !== void 0 ? { contentType } : {} };
+  };
+  const del = async (key, o = {}) => {
+    const { url: url2 } = signDeleteUrl(key, o);
+    const res = await exchange(`delete of ${key}`, url2, "DELETE", "none", o);
+    if (!res.ok) {
+      throw new McpToolError(`Blob store delete of ${key} failed (HTTP ${res.status}).`, {
+        kind: "http",
+        status: res.status
+      });
+    }
+  };
+  const consume = async (key, use, o = {}) => {
+    const object2 = await get(key, o);
+    const result = await use(object2);
+    try {
+      await del(key, o);
+      return { result, deleted: true };
+    } catch (e) {
+      return { result, deleted: false, deleteError: e instanceof Error ? e.message : String(e) };
+    }
+  };
+  return { baseUrl: base, prefix, signGetUrl, signPutUrl, put, signDeleteUrl, get, delete: del, consume };
+}
+function blobStoreFromEnv(env = process.env) {
+  const baseUrl = readEnvVar("MCP_BLOB_BASE_URL", { env });
+  const signingKey = readEnvVar("MCP_BLOB_SIGNING_KEY", { env });
+  if (!baseUrl || !signingKey)
+    return void 0;
+  return createBlobStore({ baseUrl, signingKey });
+}
+
+// ../../node_modules/@chrischall/mcp-utils/dist/export/zip.js
+var CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++)
+      c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+// ../../node_modules/@chrischall/mcp-utils/dist/export/sink.js
+var EXPORT_BLOB_MAX_BYTES = 256 * 1024 * 1024;
+
+// ../../node_modules/@chrischall/mcp-utils/dist/export/upload.js
+import { randomUUID } from "node:crypto";
+var MAX_UPLOAD_FILES = 10;
+var UPLOAD_KEY_PREFIX = "uploads";
+var UPLOAD_SLOT_DEFAULT_TTL_MS = 30 * 60 * 1e3;
+var MIB = 1024 * 1024;
+var OCTET_STREAM = "application/octet-stream";
+var inlineFileSchema = external_exports.object({
+  filename: external_exports.string().describe("Filename the upstream will show \u2014 a bare name, no path, not starting with a dot. Its extension sets the MIME type when mimeType is omitted."),
+  contentBase64: external_exports.string().describe(`The file's bytes, standard base64 (line breaks and a "data:<type>;base64," prefix are tolerated).`),
+  mimeType: external_exports.string().describe('MIME type, e.g. "image/jpeg". Default: inferred from the filename extension.').optional()
+});
+var uploadSlotRequestSchema = external_exports.object({
+  filename: external_exports.string().describe("Filename the upstream will show \u2014 a bare name, no path, not starting with a dot."),
+  mimeType: external_exports.string().describe("MIME type. Default: inferred from the filename extension. The PUT must send exactly this Content-Type.").optional()
+});
+function sanitizeUploadFilename(raw) {
+  const name = raw.trim();
+  if (name.length === 0)
+    throw new Error("filename is empty.");
+  if (/[/\\]/.test(name)) {
+    throw new Error(`filename ${JSON.stringify(name)} must be a bare filename, not a path \u2014 pass just the name to show, e.g. "photo.jpg".`);
+  }
+  if (/[\x00-\x1f\x7f]/.test(name))
+    throw new Error(`filename ${JSON.stringify(name)} contains control characters.`);
+  if (name.startsWith(".")) {
+    throw new Error(`filename ${JSON.stringify(name)} must not start with a dot (hidden files are never uploaded).`);
+  }
+  if (name.length > 200)
+    throw new Error("filename is longer than 200 characters.");
+  return name;
+}
+var MIME_BY_EXT = {
+  pdf: "application/pdf",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  heic: "image/heic",
+  heif: "image/heif",
+  tif: "image/tiff",
+  tiff: "image/tiff",
+  svg: "image/svg+xml",
+  txt: "text/plain",
+  md: "text/markdown",
+  csv: "text/csv",
+  html: "text/html",
+  htm: "text/html",
+  json: "application/json",
+  xml: "application/xml",
+  ics: "text/calendar",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  zip: "application/zip",
+  mp3: "audio/mpeg",
+  m4a: "audio/mp4",
+  wav: "audio/wav",
+  mp4: "video/mp4",
+  mov: "video/quicktime",
+  webm: "video/webm"
+};
+function mimeFromFileName(name) {
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0)
+    return OCTET_STREAM;
+  return MIME_BY_EXT[name.slice(dot + 1).toLowerCase()] ?? OCTET_STREAM;
+}
+var MEDIA_TYPE = /^[a-z0-9!#$&^_.+-]+\/[a-z0-9!#$&^_.+-]+$/;
+function resolveUploadMime(fileName, mimeType) {
+  if (mimeType === void 0)
+    return mimeFromFileName(fileName);
+  const bare = (mimeType.split(";", 1)[0] ?? "").trim().toLowerCase();
+  if (!MEDIA_TYPE.test(bare)) {
+    throw new Error(`mimeType ${JSON.stringify(mimeType)} is not a type/subtype media type such as "image/jpeg".`);
+  }
+  return bare;
+}
+function limitText(maxBytes) {
+  return `${Math.floor(maxBytes / MIB)} MiB (${maxBytes} bytes)`;
+}
+function checkUploadSize(fileName, size, maxBytes) {
+  if (size === 0)
+    throw new Error(`${fileName} is empty (0 bytes); nothing to upload.`);
+  if (size > maxBytes)
+    throw new Error(`${fileName} is too large (${size} bytes); the upload limit is ${limitText(maxBytes)}.`);
+}
+var PREFIX2 = /^[A-Za-z0-9._~-]+$/;
+function checkPrefix(prefix) {
+  if (!PREFIX2.test(prefix) || prefix === "." || prefix === "..") {
+    throw new Error(`Upload key prefix ${JSON.stringify(prefix)} must be one key segment of [A-Za-z0-9._~-].`);
+  }
+}
+function mintUploadSlot(store, req, opts = {}) {
+  const prefix = opts.prefix ?? UPLOAD_KEY_PREFIX;
+  checkPrefix(prefix);
+  const filename = sanitizeUploadFilename(req.filename);
+  const mimeType = resolveUploadMime(filename, req.mimeType);
+  const blobKey = `${prefix}/${randomUUID()}/${Buffer.from(filename, "utf8").toString("base64url")}`;
+  const { url: url2, expiresAtMs } = store.signPutUrl(blobKey, mimeType, {
+    ttlMs: opts.ttlMs ?? UPLOAD_SLOT_DEFAULT_TTL_MS,
+    ...opts.now !== void 0 ? { now: opts.now } : {}
+  });
+  const shellName = filename.replace(/'/g, `'\\''`);
+  return {
+    filename,
+    mimeType,
+    blobKey,
+    method: "PUT",
+    uploadUrl: url2,
+    expiresAtMs,
+    expiresAt: new Date(expiresAtMs).toISOString(),
+    // --fail turns a refused PUT (expired, wrong Content-Type) into a non-zero exit.
+    curl: `curl -sS --fail -X PUT -H 'Content-Type: ${mimeType}' --data-binary @'<path to ${shellName}>' '${url2}'`
+  };
+}
+var UUID = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}";
+function uploadFileNameFromKey(key, opts = {}) {
+  const prefix = opts.prefix ?? UPLOAD_KEY_PREFIX;
+  checkPrefix(prefix);
+  const escaped = prefix.replace(/[.~-]/g, "\\$&");
+  const match = new RegExp(`^${escaped}/${UUID}/([A-Za-z0-9_-]+)$`).exec(key);
+  if (!match) {
+    throw new Error(`blobKey ${JSON.stringify(key)} is not an upload key. Pass the blobKey exactly as the upload slot returned it.`);
+  }
+  return sanitizeUploadFilename(Buffer.from(match[1], "base64url").toString("utf8"));
+}
+
+// ../gogcli-mcp/src/blob-urls.ts
+var BLOB_URL_MAX_TTL_MS = 24 * 60 * 60 * 1e3;
+var BLOB_URL_CEILING_MARGIN_MS = 60 * 1e3;
+var BLOB_URL_DEFAULT_TTL_MS = 60 * 60 * 1e3;
+function blobStoreFromEnv2() {
+  const baseUrl = readEnvVar("MCP_BLOB_BASE_URL");
+  const signingKey = readEnvVar("MCP_BLOB_SIGNING_KEY");
+  if (!baseUrl || !signingKey) return void 0;
+  return { baseUrl, signingKey };
+}
+
+// ../gogcli-mcp/src/upload-slots.ts
+var UPLOAD_SLOTS_TOOL = "gog_upload_slots";
+var MAX_BLOB_FILE_BYTES = 25 * 1024 * 1024;
+var ATTACH_INLINE_ALTERNATIVE = `or, for a small file, pass its bytes base64-encoded in \`attachInline\` (${INLINE_ATTACHMENT_LIMITS_TEXT})`;
+function isHostedDeployment() {
+  return readEnvVar("MCP_DATA_DIR") !== void 0 || blobStoreFromEnv2() !== void 0;
+}
+function requireUploadStore(what) {
+  const store = blobStoreFromEnv();
+  if (store) return store;
+  throw new Error(
+    `${what} needs the upload store a hosted (mcp-host) deployment provides, and this server has none \u2014 it is a local install, so gog can read your files directly. Pass a server path instead (attach / localPath / file / image, inside GOG_FILE_ROOTS), or for a small file the bytes with attachInline / content.`
+  );
+}
+function blobFileName(key) {
+  try {
+    return uploadFileNameFromKey(key, { prefix: UPLOAD_KEY_PREFIX });
+  } catch (e) {
+    const message = e.message;
+    if (!message.includes("is not an upload key")) throw e;
+    throw new Error(`blobKey ${JSON.stringify(key)} is not an upload key. Pass each blobKey exactly as ${UPLOAD_SLOTS_TOOL} returned it.`);
+  }
+}
+var blobKeysText = `Hosted deployments: blobKeys from ${UPLOAD_SLOTS_TOOL} for files you have ALREADY PUT to their uploadUrl. This is how to send a file you hold (a photo, a PDF) when this server is remote: no base64 in the call, up to ${MAX_BLOB_FILE_BYTES / (1024 * 1024)} MiB a file. Each file keeps the filename its slot was minted for. An uploaded file is deleted once this call succeeds and kept if it fails, so a retry can reuse the same keys.`;
+var blobKeysParam = external_exports.array(external_exports.string()).max(MAX_UPLOAD_FILES).optional().describe(
+  `${blobKeysText} Up to ${MAX_UPLOAD_FILES}; combine freely with attach / attachInline.`
+);
+var singleBlobKeyParam = external_exports.array(external_exports.string()).max(1).optional().describe(
+  `${blobKeysText} Exactly one key; use it INSTEAD of the path parameter.`
+);
+async function readBlobFiles(keys, flag, opts = {}) {
+  if (!keys?.length) return [];
+  if (new Set(keys).size !== keys.length) throw new Error("blobKeys lists the same blobKey twice; pass each uploaded file once.");
+  const names = keys.map(blobFileName);
+  const store = requireUploadStore("blobKeys");
+  const files = [];
+  for (const [i, blobKey] of keys.entries()) {
+    const filename = names[i];
+    let bytes;
+    try {
+      bytes = (await store.get(blobKey, { maxBytes: MAX_BLOB_FILE_BYTES })).bytes;
+    } catch (e) {
+      throw new Error(
+        `${filename} could not be read from the upload store: ${e.message} PUT the file to its uploadUrl before calling this tool (files over ${MAX_BLOB_FILE_BYTES} bytes are refused), and mint a new slot with ${UPLOAD_SLOTS_TOOL} if this key was already used by a call that succeeded.`
+      );
+    }
+    checkUploadSize(filename, bytes.length, MAX_BLOB_FILE_BYTES);
+    const arg = { kind: "file", flag, contents: Buffer.from(bytes).toString("base64"), encoding: "base64", filename };
+    if (opts.positional) arg.positional = true;
+    files.push({ blobKey, filename, size: bytes.length, sha256: createHash4("sha256").update(bytes).digest("hex"), arg, store });
+  }
+  return files;
+}
+async function releaseBlobs(result, files) {
+  if (files.length === 0) return result;
+  if (result.isError) {
+    return withNote(
+      result,
+      `The uploaded files (${files.map((f) => f.filename).join(", ")}) were kept in the upload store, so you can retry with the same blobKeys.`
+    );
+  }
+  const failed = [];
+  for (const file2 of files) {
+    try {
+      await file2.store.delete(file2.blobKey);
+    } catch (e) {
+      failed.push(`${file2.filename} (${e instanceof Error ? e.message : String(e)})`);
+    }
+  }
+  if (failed.length === 0) return result;
+  return withNote(
+    result,
+    `WARNING: the call succeeded, but these uploaded files could not be deleted from the upload store: ${failed.join("; ")}. They expire with the store's retention. Do NOT retry the call \u2014 it already happened.`
+  );
+}
+function withNote(result, text) {
+  return { ...result, content: [...result.content, { type: "text", text }] };
+}
+function hostedPathRefusal(path, param, alternative) {
+  return new Error(
+    `This server is remote (a hosted deployment), so \`${param}\` ${JSON.stringify(path)} names a file on the SERVER, not on your machine, and there is no such file here. Upload the bytes instead: call ${UPLOAD_SLOTS_TOOL} with files:[{filename}], PUT each file to its uploadUrl (the response includes a ready curl command), then call this tool again with those blobKeys in \`blobKeys\`` + (alternative ? ` \u2014 ${alternative}.` : ".")
+  );
+}
+function confineUploadPath(path, param, alternative) {
+  if (!isHostedDeployment()) return confinePath(path, param);
+  try {
+    confinePath(path, param);
+  } catch {
+    throw hostedPathRefusal(path, param, alternative);
+  }
+  if (!existsSync2(path)) throw hostedPathRefusal(path, param, alternative);
+  return path;
+}
+function assertOneFileSource(sources) {
+  const names = Object.keys(sources);
+  const given = names.filter((n) => {
+    const v = sources[n];
+    return Array.isArray(v) ? v.length > 0 : v !== void 0;
+  });
+  if (given.length === 1) return;
+  const list = `${names.slice(0, -1).join(", ")} or ${names[names.length - 1]}`;
+  throw new Error(`Pass exactly one of ${list}${given.length > 1 ? ` (got ${given.join(" and ")})` : ""}.`);
+}
+
 // ../gogcli-mcp/src/tools/docs.ts
 function vetDocsRun(subcommand, args) {
   return vetCommentsRun("docs", subcommand, args);
@@ -37650,8 +38258,9 @@ var replySchema = {
   remove: external_exports.array(external_exports.string()).optional().describe("Remove these recipients from all fields (repeatable) \u2014 e.g. to drop someone from a reply-all."),
   subject: external_exports.string().optional().describe('Override reply subject (default: "Re: <original>"). A changed subject starts a NEW Gmail thread.'),
   noQuote: external_exports.boolean().optional().describe("Do not include the original message quoted below the reply (default: the original is quoted)"),
-  attach: external_exports.array(external_exports.string()).optional().describe(`File paths to attach (repeatable), resolved ON THE GOG SERVER's filesystem \u2014 NOT this client's. Only usable when gog runs on the same machine you do (local stdio); on a hosted deployment (e.g. mcp-host) these paths do not exist and the call fails with "no such file or directory" \u2014 use attachInline there. Read on the server, base64-encoded with a MIME type inferred from the extension. Must be inside the server's GOG_FILE_ROOTS directories (default ~/gogcli-mcp-files).`),
+  attach: external_exports.array(external_exports.string()).optional().describe(`File paths to attach (repeatable), resolved ON THE GOG SERVER's filesystem \u2014 NOT this client's. Only usable when gog runs on the same machine you do (local stdio); on a hosted deployment (e.g. mcp-host) these paths do not exist and the call fails with "no such file or directory" \u2014 use blobKeys (gog_upload_slots) or, for a small file, attachInline there. Read on the server, base64-encoded with a MIME type inferred from the extension. Must be inside the server's GOG_FILE_ROOTS directories (default ~/gogcli-mcp-files).`),
   attachInline: attachInlineParam,
+  blobKeys: blobKeysParam,
   from: external_exports.string().optional().describe("Send from this email address (must be a verified send-as alias)"),
   autoFromAddressedAlias: external_exports.boolean().optional().describe("When from is omitted, send from the verified send-as alias the original message was addressed TO, instead of the account's primary address \u2014 so a reply to mail sent to an alias goes back out from that alias. Ignored when from is set."),
   ...signatureSchema,
@@ -37668,8 +38277,50 @@ 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.'
 );
 
+// ../gogcli-mcp/src/tools/uploads.ts
+var BLOB_KEY_TOOLS = [
+  "gog_gmail_send",
+  "gog_gmail_reply",
+  "gog_gmail_reply_all",
+  "gog_gmail_drafts_create",
+  "gog_gmail_drafts_update",
+  "gog_gmail_drafts_reply",
+  "gog_gmail_drafts_reply_all",
+  "gog_gmail_import",
+  "gog_chat_messages_send",
+  "gog_drive_upload",
+  "gog_slides_add_slide",
+  "gog_slides_insert_image",
+  "gog_slides_replace_slide",
+  "gog_docs_insert_image",
+  "gog_docs_replace_image"
+];
+var MIB2 = MAX_BLOB_FILE_BYTES / (1024 * 1024);
+function registerUploadTools(server) {
+  server.registerTool(UPLOAD_SLOTS_TOOL, {
+    description: `HOSTED DEPLOYMENTS: how to give this server a FILE you hold (a photo, a PDF, an .eml). This server runs remotely and cannot read paths on your machine, so call this first with the files' names: it returns one signed upload slot per file. PUT each file's bytes to its uploadUrl (each slot carries a ready \`curl\` command \u2014 replace the <path to \u2026> placeholder; the Content-Type must be exactly the slot's mimeType), then pass the slots' blobKeys in the \`blobKeys\` parameter of the tool that takes the file: ${BLOB_KEY_TOOLS.join(", ")}. Up to ${MAX_UPLOAD_FILES} files per call, ${MIB2} MiB each; the URLs expire after 30 minutes. Each uploaded file is deleted once the call that uses it succeeds, and kept if that call fails. Prefer this over attachInline for anything but a small file \u2014 no base64 in the call. Mints URLs only: nothing reaches Google until you use the keys. On a local install this refuses: pass a path, or attachInline.`,
+    annotations: { readOnlyHint: true, openWorldHint: false },
+    inputSchema: external_exports.object({
+      files: external_exports.array(uploadSlotRequestSchema).min(1).max(MAX_UPLOAD_FILES).describe(
+        "One entry per file: {filename, mimeType?}. The filename is the name the recipient / Drive will show, and its extension is how gog types an attachment \u2014 give it the right one."
+      )
+    })
+  }, async ({ files }) => {
+    const store = requireUploadStore(UPLOAD_SLOTS_TOOL);
+    const slots = files.map((file2) => {
+      const { expiresAtMs: _expiresAtMs, ...slot } = mintUploadSlot(store, file2);
+      return slot;
+    });
+    return minifiedResult({
+      slots,
+      maxBytesPerFile: MAX_BLOB_FILE_BYTES,
+      next: "PUT each file to its uploadUrl (run each slot's curl with the real path), check every PUT succeeded, then pass the blobKeys to the file-taking tool's blobKeys parameter."
+    });
+  });
+}
+
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "4.9.1" : "0.0.0";
+var VERSION = true ? "4.10.0" : "0.0.0";
 
 // ../gogcli-mcp/src/bootstrap-auth.ts
 import { join as join7 } from "node:path";
@@ -37706,12 +38357,12 @@ async function bootstrapGogAuth(env = process.env, options = {}) {
   const [clientId, clientSecret, refreshToken, account] = values;
   const { spawner } = options;
   try {
-    const { createHash: createHash4 } = await import("node:crypto");
+    const { createHash: createHash5 } = await import("node:crypto");
     const { mkdir, readFile, writeFile, chmod } = await import("node:fs/promises");
     const home = options.home ?? (await import("node:os")).homedir();
     const dir = join7(home, ".gogcli-mcp");
     const marker = join7(dir, AUTH_BOOTSTRAP_MARKER);
-    const fingerprint = createHash4("sha256").update(values.join("\0")).digest("hex");
+    const fingerprint = createHash5("sha256").update(values.join("\0")).digest("hex");
     const previous = await readFile(marker, "utf8").catch(() => void 0);
     if (previous === fingerprint && await accountListed(account, spawner)) return "present";
     await run(
@@ -37735,15 +38386,12 @@ async function bootstrapGogAuth(env = process.env, options = {}) {
   }
 }
 
-// ../gogcli-mcp/src/blob-urls.ts
-var BLOB_URL_MAX_TTL_MS = 24 * 60 * 60 * 1e3;
-var BLOB_URL_CEILING_MARGIN_MS = 60 * 1e3;
-var BLOB_URL_DEFAULT_TTL_MS = 60 * 60 * 1e3;
-
 // ../gogcli-mcp/src/blob-upload.ts
 var MAX_BLOB_UPLOAD_BYTES = 100 * 1024 * 1024;
 
 // src/tools/docs-extra.ts
+var URL_ALTERNATIVE = "or pass a public HTTPS image `url`";
+var IMAGE_BLOB_NOTE = " On a hosted deployment, where no path on your machine exists, upload the image with gog_upload_slots and pass blobKeys instead of file.";
 function docTitle(raw) {
   try {
     const parsed = JSON.parse(raw);
@@ -38755,12 +39403,13 @@ function registerExtraDocsTools(server) {
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_docs_insert_image", {
-    description: "Insert an image into a Google Doc from a local file or a public HTTPS URL. file: uploaded to Drive, temporarily shared so Docs can fetch it, inserted, then the public permission is revoked. url: inserted directly with no Drive upload or temporary sharing. Replaces placeholder text (at) or appends at end-of-doc.",
+    description: "Insert an image into a Google Doc from a local file or a public HTTPS URL. file: uploaded to Drive, temporarily shared so Docs can fetch it, inserted, then the public permission is revoked. url: inserted directly with no Drive upload or temporary sharing. Replaces placeholder text (at) or appends at end-of-doc." + IMAGE_BLOB_NOTE,
     annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       docId: external_exports.string().describe("Doc ID (from the URL)"),
-      file: external_exports.string().optional().describe("Local PNG, JPEG, or GIF image to upload and insert (exactly one of file or url)"),
-      url: external_exports.string().optional().describe("Public HTTPS image URL to insert directly \u2014 no Drive upload or temporary public sharing (exactly one of file or url)"),
+      file: external_exports.string().optional().describe("PNG, JPEG, or GIF image on the gog server to upload and insert (exactly one of file, url or blobKeys)"),
+      url: external_exports.string().optional().describe("Public HTTPS image URL to insert directly \u2014 no Drive upload or temporary public sharing (exactly one of file, url or blobKeys)"),
+      blobKeys: singleBlobKeyParam,
       at: external_exports.string().optional().describe('Placeholder text to replace, or "end" to append (default: end)'),
       before: external_exports.string().optional().describe("Insert the image immediately before the first literal text match (no text is deleted)"),
       after: external_exports.string().optional().describe("Insert the image immediately after the first literal text match (no text is deleted)"),
@@ -38772,10 +39421,13 @@ function registerExtraDocsTools(server) {
       tab: external_exports.string().optional().describe("Target a specific tab by title or ID"),
       account: accountParam
     })
-  }, async ({ docId, file: file2, url: url2, at, before, after, width, height, name, parent, onRestricted, tab, account }) => {
-    if (file2) confinePath(file2, "file");
+  }, async ({ docId, file: file2, url: url2, blobKeys, at, before, after, width, height, name, parent, onRestricted, tab, account }) => {
+    if (file2) confineUploadPath(file2, "file", URL_ALTERNATIVE);
+    assertOneFileSource({ file: file2, url: url2, blobKeys });
+    const blobs = await readBlobFiles(blobKeys, "file");
     const args = ["docs", "insert-image", pos(docId)];
     if (file2) args.push(`--file=${file2}`);
+    for (const blob of blobs) args.push(blob.arg);
     if (url2) args.push(`--url=${url2}`);
     if (at) args.push(`--at=${at}`);
     if (before) args.push(`--before=${before}`);
@@ -38786,8 +39438,8 @@ function registerExtraDocsTools(server) {
     if (parent) args.push(`--parent=${parent}`);
     if (onRestricted) args.push(`--on-restricted=${onRestricted}`);
     if (tab) args.push(`--tab=${tab}`);
-    if (file2) args.push("--force");
-    return runOrDiagnose(args, { account });
+    if (file2 || blobs.length > 0) args.push("--force");
+    return releaseBlobs(await runOrDiagnose(args, { account }), blobs);
   });
   server.registerTool("gog_docs_insert_person", {
     description: "Insert a native Google Docs person smart chip (the interactive @-mention chip) for an email address, at a character index or end-of-doc.",
@@ -39113,12 +39765,13 @@ function registerExtraDocsTools(server) {
     return runOrDiagnose(args, { account });
   });
   server.registerTool("gog_docs_replace_image", {
-    description: "Replace an existing image in a Google Doc in place \u2014 keeping its position and bounds \u2014 with a new image from a local file or public HTTPS URL. Target the image by exact object ID (from gog_docs_images_list), by alt-text substring, or leave both off to replace the only image in the doc/tab.",
+    description: "Replace an existing image in a Google Doc in place \u2014 keeping its position and bounds \u2014 with a new image from a local file or public HTTPS URL. Target the image by exact object ID (from gog_docs_images_list), by alt-text substring, or leave both off to replace the only image in the doc/tab." + IMAGE_BLOB_NOTE,
     annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: external_exports.object({
       docId: external_exports.string().describe("Doc ID (from the URL)"),
-      file: external_exports.string().optional().describe("Local PNG, JPEG, or GIF image to upload and use (exactly one of file or url)"),
-      url: external_exports.string().optional().describe("Public HTTPS image URL to use directly \u2014 no Drive upload (exactly one of file or url)"),
+      file: external_exports.string().optional().describe("PNG, JPEG, or GIF image on the gog server to upload and use (exactly one of file, url or blobKeys)"),
+      url: external_exports.string().optional().describe("Public HTTPS image URL to use directly \u2014 no Drive upload (exactly one of file, url or blobKeys)"),
+      blobKeys: singleBlobKeyParam,
       objectId: external_exports.string().optional().describe("Exact image object ID to replace (from gog_docs_images_list)"),
       matchAlt: external_exports.string().optional().describe("Select the image whose alt text contains this value (case-insensitive)"),
       name: external_exports.string().optional().describe("Override the uploaded Drive filename (file mode)"),
@@ -39126,18 +39779,21 @@ function registerExtraDocsTools(server) {
       tab: external_exports.string().optional().describe("Target a specific tab by title or ID"),
       account: accountParam
     })
-  }, async ({ docId, file: file2, url: url2, objectId, matchAlt, name, parent, tab, account }) => {
-    if (file2) confinePath(file2, "file");
+  }, async ({ docId, file: file2, url: url2, blobKeys, objectId, matchAlt, name, parent, tab, account }) => {
+    if (file2) confineUploadPath(file2, "file", URL_ALTERNATIVE);
+    assertOneFileSource({ file: file2, url: url2, blobKeys });
+    const blobs = await readBlobFiles(blobKeys, "file");
     const args = ["docs", "replace-image", pos(docId)];
     if (file2) args.push(`--file=${file2}`);
+    for (const blob of blobs) args.push(blob.arg);
     if (url2) args.push(`--url=${url2}`);
     if (objectId) args.push(`--object-id=${objectId}`);
     if (matchAlt) args.push(`--match-alt=${matchAlt}`);
     if (name) args.push(`--name=${name}`);
     if (parent) args.push(`--parent=${parent}`);
     if (tab) args.push(`--tab=${tab}`);
-    if (file2) args.push("--force");
-    return runOrDiagnose(args, { account });
+    if (file2 || blobs.length > 0) args.push("--force");
+    return releaseBlobs(await runOrDiagnose(args, { account }), blobs);
   });
   server.registerTool("gog_docs_table_row_pin_header", {
     description: "Pin (or unpin) leading rows of a native Google Docs table as repeating header rows. rows=N pins the first N rows; rows=0 unpins all header rows.",
@@ -39183,7 +39839,7 @@ await bootstrapGogAuth();
 await runMcp({
   name: "gogcli-docs",
   version: VERSION,
-  tools: [authToolsFor("docs"), registerDocsTools, registerExtraDocsTools]
+  tools: [authToolsFor("docs"), registerDocsTools, registerExtraDocsTools, registerUploadTools]
 });
 /*! Bundled license information:
 

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-docs",
   "display_name": "gogcli (Docs)",
-  "version": "4.9.1",
+  "version": "4.10.0",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",
@@ -414,6 +414,10 @@
     {
       "name": "gog_docs_insert_date_chip",
       "description": "Insert a native Google Docs date smart chip."
+    },
+    {
+      "name": "gog_upload_slots",
+      "description": "Get signed upload URLs so a hosted (remote) server can receive files you hold; pass the returned blobKeys to the tool that takes the file"
     }
   ],
   "compatibility": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-docs",
-  "version": "4.9.1",
+  "version": "4.10.0",
   "mcpName": "io.github.chrischall/gogcli-mcp-docs",
   "description": "Extended Google Docs MCP server via gogcli — all base tools plus full Docs support",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",
@@ -24,7 +24,7 @@
     "test:coverage": "vitest run --coverage"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^3.4.0",
+    "@chrischall/mcp-utils": "^3.6.0",
     "@modelcontextprotocol/server": "^2.3.1",
     "zod": "^4.6.1"
   },

package/server.json

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

package/src/index.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { runMcp } from '@chrischall/mcp-utils';
-import { VERSION, authToolsFor, registerDocsTools, bootstrapGogAuth } from '../../gogcli-mcp/src/lib.js';
+import { VERSION, authToolsFor, registerDocsTools, registerUploadTools, bootstrapGogAuth } from '../../gogcli-mcp/src/lib.js';
 import { registerExtraDocsTools } from './tools/docs-extra.js';
 
 
@@ -10,5 +10,5 @@ await bootstrapGogAuth();
 await runMcp({
   name: 'gogcli-docs',
   version: VERSION,
-  tools: [authToolsFor('docs'), registerDocsTools, registerExtraDocsTools],
+  tools: [authToolsFor('docs'), registerDocsTools, registerExtraDocsTools, registerUploadTools],
 });

package/src/tools/docs-extra.ts

@@ -8,6 +8,11 @@ import {
   payloadArg,
   pos,
   confinePath,
+  assertOneFileSource,
+  confineUploadPath,
+  readBlobFiles,
+  releaseBlobs,
+  singleBlobKeyParam,
   bodyPreview,
   commentMentions,
   commentSnapshot,
@@ -18,6 +23,9 @@ import {
 } from '../../../gogcli-mcp/src/lib.js';
 import type { GogArg } from '../../../gogcli-mcp/src/lib.js';
 
+const URL_ALTERNATIVE = 'or pass a public HTTPS image `url`';
+const IMAGE_BLOB_NOTE = ' On a hosted deployment, where no path on your machine exists, upload the image with gog_upload_slots and pass blobKeys instead of file.';
+
 /** A Doc's title from `gog docs info`, for a comment's prompt. Unreadable output names nothing. */
 export function docTitle(raw: string): string | undefined {
   try {
@@ -1135,12 +1143,13 @@ export function registerExtraDocsTools(server: McpServer): void {
   });
 
   server.registerTool('gog_docs_insert_image', {
-    description: 'Insert an image into a Google Doc from a local file or a public HTTPS URL. file: uploaded to Drive, temporarily shared so Docs can fetch it, inserted, then the public permission is revoked. url: inserted directly with no Drive upload or temporary sharing. Replaces placeholder text (at) or appends at end-of-doc.',
+    description: 'Insert an image into a Google Doc from a local file or a public HTTPS URL. file: uploaded to Drive, temporarily shared so Docs can fetch it, inserted, then the public permission is revoked. url: inserted directly with no Drive upload or temporary sharing. Replaces placeholder text (at) or appends at end-of-doc.' + IMAGE_BLOB_NOTE,
     annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: z.object({
       docId: z.string().describe('Doc ID (from the URL)'),
-      file: z.string().optional().describe('Local PNG, JPEG, or GIF image to upload and insert (exactly one of file or url)'),
-      url: z.string().optional().describe('Public HTTPS image URL to insert directly — no Drive upload or temporary public sharing (exactly one of file or url)'),
+      file: z.string().optional().describe('PNG, JPEG, or GIF image on the gog server to upload and insert (exactly one of file, url or blobKeys)'),
+      url: z.string().optional().describe('Public HTTPS image URL to insert directly — no Drive upload or temporary public sharing (exactly one of file, url or blobKeys)'),
+      blobKeys: singleBlobKeyParam,
       at: z.string().optional().describe('Placeholder text to replace, or "end" to append (default: end)'),
       before: z.string().optional().describe('Insert the image immediately before the first literal text match (no text is deleted)'),
       after: z.string().optional().describe('Insert the image immediately after the first literal text match (no text is deleted)'),
@@ -1152,10 +1161,13 @@ export function registerExtraDocsTools(server: McpServer): void {
       tab: z.string().optional().describe('Target a specific tab by title or ID'),
       account: accountParam,
     }),
-  }, async ({ docId, file, url, at, before, after, width, height, name, parent, onRestricted, tab, account }) => {
-    if (file) confinePath(file, 'file');
+  }, async ({ docId, file, url, blobKeys, at, before, after, width, height, name, parent, onRestricted, tab, account }) => {
+    if (file) confineUploadPath(file, 'file', URL_ALTERNATIVE);
+    assertOneFileSource({ file, url, blobKeys });
+    const blobs = await readBlobFiles(blobKeys, 'file');
     const args: GogArg[] = ['docs', 'insert-image', pos(docId)];
     if (file) args.push(`--file=${file}`);
+    for (const blob of blobs) args.push(blob.arg);
     if (url) args.push(`--url=${url}`);
     if (at) args.push(`--at=${at}`);
     if (before) args.push(`--before=${before}`);
@@ -1166,8 +1178,8 @@ export function registerExtraDocsTools(server: McpServer): void {
     if (parent) args.push(`--parent=${parent}`);
     if (onRestricted) args.push(`--on-restricted=${onRestricted}`);
     if (tab) args.push(`--tab=${tab}`);
-    if (file) args.push('--force'); // gog gates this op; without --force the runner's --no-input makes it refuse (local files upload via a temporary public share)
-    return runOrDiagnose(args, { account });
+    if (file || blobs.length > 0) args.push('--force'); // gog gates this op; without --force the runner's --no-input makes it refuse (local files upload via a temporary public share)
+    return releaseBlobs(await runOrDiagnose(args, { account }), blobs);
   });
 
   server.registerTool('gog_docs_insert_person', {
@@ -1517,12 +1529,13 @@ export function registerExtraDocsTools(server: McpServer): void {
   // --- gog 0.30 image replacement & table-row pin/style ---
 
   server.registerTool('gog_docs_replace_image', {
-    description: 'Replace an existing image in a Google Doc in place — keeping its position and bounds — with a new image from a local file or public HTTPS URL. Target the image by exact object ID (from gog_docs_images_list), by alt-text substring, or leave both off to replace the only image in the doc/tab.',
+    description: 'Replace an existing image in a Google Doc in place — keeping its position and bounds — with a new image from a local file or public HTTPS URL. Target the image by exact object ID (from gog_docs_images_list), by alt-text substring, or leave both off to replace the only image in the doc/tab.' + IMAGE_BLOB_NOTE,
     annotations: { destructiveHint: true, openWorldHint: true },
     inputSchema: z.object({
       docId: z.string().describe('Doc ID (from the URL)'),
-      file: z.string().optional().describe('Local PNG, JPEG, or GIF image to upload and use (exactly one of file or url)'),
-      url: z.string().optional().describe('Public HTTPS image URL to use directly — no Drive upload (exactly one of file or url)'),
+      file: z.string().optional().describe('PNG, JPEG, or GIF image on the gog server to upload and use (exactly one of file, url or blobKeys)'),
+      url: z.string().optional().describe('Public HTTPS image URL to use directly — no Drive upload (exactly one of file, url or blobKeys)'),
+      blobKeys: singleBlobKeyParam,
       objectId: z.string().optional().describe('Exact image object ID to replace (from gog_docs_images_list)'),
       matchAlt: z.string().optional().describe('Select the image whose alt text contains this value (case-insensitive)'),
       name: z.string().optional().describe('Override the uploaded Drive filename (file mode)'),
@@ -1530,18 +1543,21 @@ export function registerExtraDocsTools(server: McpServer): void {
       tab: z.string().optional().describe('Target a specific tab by title or ID'),
       account: accountParam,
     }),
-  }, async ({ docId, file, url, objectId, matchAlt, name, parent, tab, account }) => {
-    if (file) confinePath(file, 'file');
+  }, async ({ docId, file, url, blobKeys, objectId, matchAlt, name, parent, tab, account }) => {
+    if (file) confineUploadPath(file, 'file', URL_ALTERNATIVE);
+    assertOneFileSource({ file, url, blobKeys });
+    const blobs = await readBlobFiles(blobKeys, 'file');
     const args: GogArg[] = ['docs', 'replace-image', pos(docId)];
     if (file) args.push(`--file=${file}`);
+    for (const blob of blobs) args.push(blob.arg);
     if (url) args.push(`--url=${url}`);
     if (objectId) args.push(`--object-id=${objectId}`);
     if (matchAlt) args.push(`--match-alt=${matchAlt}`);
     if (name) args.push(`--name=${name}`);
     if (parent) args.push(`--parent=${parent}`);
     if (tab) args.push(`--tab=${tab}`);
-    if (file) args.push('--force'); // gog gates this op; without --force the runner's --no-input makes it refuse (local files upload via a temporary public share)
-    return runOrDiagnose(args, { account });
+    if (file || blobs.length > 0) args.push('--force'); // gog gates this op; without --force the runner's --no-input makes it refuse (local files upload via a temporary public share)
+    return releaseBlobs(await runOrDiagnose(args, { account }), blobs);
   });
 
   server.registerTool('gog_docs_table_row_pin_header', {

package/tests/tool-annotations.test.ts

@@ -1,10 +1,10 @@
-import { authToolsFor, registerDocsTools } from '../../gogcli-mcp/src/lib.js';
+import { authToolsFor, registerDocsTools, registerUploadTools } from '../../gogcli-mcp/src/lib.js';
 import { registerExtraDocsTools } from '../src/tools/docs-extra.js';
 import { describeToolAnnotations, LOCAL_AUTH_TOOLS } from '../../gogcli-mcp/tests/support/tool-annotations.js';
 
 // The same registrar list src/index.ts hands to runMcp.
-describeToolAnnotations([authToolsFor('docs'), registerDocsTools, registerExtraDocsTools] as never, {
-  tools: 83,
+describeToolAnnotations([authToolsFor('docs'), registerDocsTools, registerExtraDocsTools, registerUploadTools] as never, {
+  tools: 84,
   destructive: 52,
-  local: [...LOCAL_AUTH_TOOLS, 'gog_batch_abort', 'gog_batch_begin', 'gog_batch_list', 'gog_batch_prune', 'gog_batch_show'],
+  local: [...LOCAL_AUTH_TOOLS, 'gog_upload_slots', 'gog_batch_abort', 'gog_batch_begin', 'gog_batch_list', 'gog_batch_prune', 'gog_batch_show'],
 });

package/tests/tools/docs-blobkeys.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createTestHarness, type TestHarness } from '@chrischall/mcp-utils/test';
+import { rawTextResult, errorResult } from '@chrischall/mcp-utils';
+import { blobStoreFromEnv, mintUploadSlot } from '@chrischall/mcp-utils/export';
+import * as lib from '../../../gogcli-mcp/src/lib.js';
+import type { GogArg, GogFileArg } from '../../../gogcli-mcp/src/lib.js';
+import { registerExtraDocsTools } from '../../src/tools/docs-extra.js';
+import { installFakeBlobStore, type FakeBlobStore } from '../../../gogcli-mcp/tests/support/fake-blob-store.js';
+
+vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
+  const actual = await importOriginal<typeof lib>();
+  return { ...actual, runOrDiagnose: vi.fn() };
+});
+
+const ORIGINAL_ENV = { ...process.env };
+let fake: FakeBlobStore;
+let harness: TestHarness;
+let root: string;
+
+beforeEach(async () => {
+  vi.clearAllMocks();
+  process.env = { ...ORIGINAL_ENV };
+  delete process.env.MCP_DATA_DIR;
+  root = mkdtempSync(join(tmpdir(), 'docs-blobkeys-'));
+  process.env.GOG_FILE_ROOTS = root;
+  fake = installFakeBlobStore();
+  vi.mocked(lib.runOrDiagnose).mockResolvedValue(rawTextResult('{}'));
+  harness = await createTestHarness(registerExtraDocsTools, {
+    elicitation: async () => ({ action: 'accept', content: { confirmed: true } }),
+  });
+});
+
+afterEach(() => {
+  process.env = ORIGINAL_ENV;
+  vi.unstubAllGlobals();
+});
+
+function upload(filename: string, bytes: string): string {
+  const key = mintUploadSlot(blobStoreFromEnv()!, { filename }).blobKey;
+  fake.put(key, bytes);
+  return key;
+}
+
+const lastArgs = () => vi.mocked(lib.runOrDiagnose).mock.calls.at(-1)![0] as GogArg[];
+const fileArg = (args: GogArg[]) => args.find((a): a is GogFileArg => typeof a === 'object' && a.kind === 'file');
+
+describe('docs image tools + blobKeys', () => {
+  it.each(['gog_docs_insert_image', 'gog_docs_replace_image'])('%s passes the blob as --file, with --force, and deletes it after', async (tool) => {
+    const key = upload('logo.png', 'PNGBYTES');
+    const result = await harness.callTool(tool, { docId: 'd1', blobKeys: [key] });
+    expect(result.isError).toBeFalsy();
+    const args = lastArgs();
+    expect(fileArg(args)).toMatchObject({ flag: 'file', filename: 'logo.png', encoding: 'base64' });
+    expect(fileArg(args)!.positional).toBeUndefined();
+    expect(args.at(-1)).toBe('--force');
+    expect(fake.deleted).toEqual([key]);
+  });
+
+  it('keeps the blob when gog fails', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(errorResult('Error: restricted'));
+    const key = upload('logo.png', 'PNGBYTES');
+    await harness.callTool('gog_docs_insert_image', { docId: 'd1', blobKeys: [key] });
+    expect(fake.deleted).toEqual([]);
+  });
+
+  it('wants exactly one image source', async () => {
+    const result = await harness.callTool('gog_docs_replace_image', { docId: 'd1' });
+    expect(result.content[0]!.text).toMatch(/exactly one of file, url or blobKeys/);
+  });
+
+  it('url mode needs no --force', async () => {
+    await harness.callTool('gog_docs_insert_image', { docId: 'd1', url: 'https://x.test/i.png' });
+    expect(lastArgs()).not.toContain('--force');
+  });
+
+  it('on a hosted deployment, a file path that is not on the server points at the slot tool', async () => {
+    const result = await harness.callTool('gog_docs_insert_image', { docId: 'd1', file: '/Users/someone/a.png' });
+    expect(result.content[0]!.text).toMatch(/server is remote.*gog_upload_slots/s);
+  });
+});