gogcli-mcp-docs 2.0.8 → 2.0.10

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": "2.0.8"
+    "version": "2.0.10"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "gogcli (Docs)",
       "source": "./",
       "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
-      "version": "2.0.8",
+      "version": "2.0.10",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/dist/index.js

@@ -3105,6 +3105,9 @@ var require_utils = __commonJS({
     "use strict";
     var isUUID = RegExp.prototype.test.bind(/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iu);
     var isIPv4 = RegExp.prototype.test.bind(/^(?:(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)$/u);
+    var isHexPair = RegExp.prototype.test.bind(/^[\da-f]{2}$/iu);
+    var isUnreserved = RegExp.prototype.test.bind(/^[\da-z\-._~]$/iu);
+    var isPathCharacter = RegExp.prototype.test.bind(/^[\da-z\-._~!$&'()*+,;=:@/]$/iu);
     function stringArrayToHexStripped(input) {
       let acc = "";
       let code = 0;
@@ -3297,27 +3300,77 @@ var require_utils = __commonJS({
       }
       return output.join("");
     }
-    function normalizeComponentEncoding(component, esc2) {
-      const func = esc2 !== true ? escape : unescape;
-      if (component.scheme !== void 0) {
-        component.scheme = func(component.scheme);
-      }
-      if (component.userinfo !== void 0) {
-        component.userinfo = func(component.userinfo);
-      }
-      if (component.host !== void 0) {
-        component.host = func(component.host);
+    var HOST_DELIMS = { "@": "%40", "/": "%2F", "?": "%3F", "#": "%23", ":": "%3A" };
+    var HOST_DELIM_RE = /[@/?#:]/g;
+    var HOST_DELIM_NO_COLON_RE = /[@/?#]/g;
+    function reescapeHostDelimiters(host, isIP) {
+      const re = isIP ? HOST_DELIM_NO_COLON_RE : HOST_DELIM_RE;
+      re.lastIndex = 0;
+      return host.replace(re, (ch) => HOST_DELIMS[ch]);
+    }
+    function normalizePercentEncoding(input, decodeUnreserved = false) {
+      if (input.indexOf("%") === -1) {
+        return input;
       }
-      if (component.path !== void 0) {
-        component.path = func(component.path);
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        if (input[i] === "%" && i + 2 < input.length) {
+          const hex3 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex3)) {
+            const normalizedHex = hex3.toUpperCase();
+            const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
+            if (decodeUnreserved && isUnreserved(decoded)) {
+              output += decoded;
+            } else {
+              output += "%" + normalizedHex;
+            }
+            i += 2;
+            continue;
+          }
+        }
+        output += input[i];
       }
-      if (component.query !== void 0) {
-        component.query = func(component.query);
+      return output;
+    }
+    function normalizePathEncoding(input) {
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        if (input[i] === "%" && i + 2 < input.length) {
+          const hex3 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex3)) {
+            const normalizedHex = hex3.toUpperCase();
+            const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
+            if (decoded !== "." && isUnreserved(decoded)) {
+              output += decoded;
+            } else {
+              output += "%" + normalizedHex;
+            }
+            i += 2;
+            continue;
+          }
+        }
+        if (isPathCharacter(input[i])) {
+          output += input[i];
+        } else {
+          output += escape(input[i]);
+        }
       }
-      if (component.fragment !== void 0) {
-        component.fragment = func(component.fragment);
+      return output;
+    }
+    function escapePreservingEscapes(input) {
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        if (input[i] === "%" && i + 2 < input.length) {
+          const hex3 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex3)) {
+            output += "%" + hex3.toUpperCase();
+            i += 2;
+            continue;
+          }
+        }
+        output += escape(input[i]);
       }
-      return component;
+      return output;
     }
     function recomposeAuthority(component) {
       const uriTokens = [];
@@ -3332,7 +3385,7 @@ var require_utils = __commonJS({
           if (ipV6res.isIPV6 === true) {
             host = `[${ipV6res.escapedHost}]`;
           } else {
-            host = component.host;
+            host = reescapeHostDelimiters(host, false);
           }
         }
         uriTokens.push(host);
@@ -3346,7 +3399,10 @@ var require_utils = __commonJS({
     module.exports = {
       nonSimpleDomain,
       recomposeAuthority,
-      normalizeComponentEncoding,
+      reescapeHostDelimiters,
+      normalizePercentEncoding,
+      normalizePathEncoding,
+      escapePreservingEscapes,
       removeDotSegments,
       isIPv4,
       isUUID,
@@ -3570,12 +3626,12 @@ var require_schemes = __commonJS({
 var require_fast_uri = __commonJS({
   "../../node_modules/fast-uri/index.js"(exports, module) {
     "use strict";
-    var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizeComponentEncoding, isIPv4, nonSimpleDomain } = require_utils();
+    var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, escapePreservingEscapes, reescapeHostDelimiters, isIPv4, nonSimpleDomain } = require_utils();
     var { SCHEMES, getSchemeHandler } = require_schemes();
     function normalize(uri, options) {
       if (typeof uri === "string") {
         uri = /** @type {T} */
-        serialize(parse3(uri, options), options);
+        normalizeString(uri, options);
       } else if (typeof uri === "object") {
         uri = /** @type {T} */
         parse3(serialize(uri, options), options);
@@ -3642,19 +3698,9 @@ var require_fast_uri = __commonJS({
       return target;
     }
     function equal(uriA, uriB, options) {
-      if (typeof uriA === "string") {
-        uriA = unescape(uriA);
-        uriA = serialize(normalizeComponentEncoding(parse3(uriA, options), true), { ...options, skipEscape: true });
-      } else if (typeof uriA === "object") {
-        uriA = serialize(normalizeComponentEncoding(uriA, true), { ...options, skipEscape: true });
-      }
-      if (typeof uriB === "string") {
-        uriB = unescape(uriB);
-        uriB = serialize(normalizeComponentEncoding(parse3(uriB, options), true), { ...options, skipEscape: true });
-      } else if (typeof uriB === "object") {
-        uriB = serialize(normalizeComponentEncoding(uriB, true), { ...options, skipEscape: true });
-      }
-      return uriA.toLowerCase() === uriB.toLowerCase();
+      const normalizedA = normalizeComparableURI(uriA, options);
+      const normalizedB = normalizeComparableURI(uriB, options);
+      return normalizedA !== void 0 && normalizedB !== void 0 && normalizedA.toLowerCase() === normalizedB.toLowerCase();
     }
     function serialize(cmpts, opts) {
       const component = {
@@ -3679,12 +3725,12 @@ var require_fast_uri = __commonJS({
       if (schemeHandler && schemeHandler.serialize) schemeHandler.serialize(component, options);
       if (component.path !== void 0) {
         if (!options.skipEscape) {
-          component.path = escape(component.path);
+          component.path = escapePreservingEscapes(component.path);
           if (component.scheme !== void 0) {
             component.path = component.path.split("%3A").join(":");
           }
         } else {
-          component.path = unescape(component.path);
+          component.path = normalizePercentEncoding(component.path);
         }
       }
       if (options.reference !== "suffix" && component.scheme) {
@@ -3719,7 +3765,16 @@ var require_fast_uri = __commonJS({
       return uriTokens.join("");
     }
     var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
-    function parse3(uri, opts) {
+    function getParseError(parsed, matches) {
+      if (matches[2] !== void 0 && parsed.path && parsed.path[0] !== "/") {
+        return 'URI path must start with "/" when authority is present.';
+      }
+      if (typeof parsed.port === "number" && (parsed.port < 0 || parsed.port > 65535)) {
+        return "URI port is malformed.";
+      }
+      return void 0;
+    }
+    function parseWithStatus(uri, opts) {
       const options = Object.assign({}, opts);
       const parsed = {
         scheme: void 0,
@@ -3730,6 +3785,7 @@ var require_fast_uri = __commonJS({
         query: void 0,
         fragment: void 0
       };
+      let malformedAuthorityOrPort = false;
       let isIP = false;
       if (options.reference === "suffix") {
         if (options.scheme) {
@@ -3750,6 +3806,11 @@ var require_fast_uri = __commonJS({
         if (isNaN(parsed.port)) {
           parsed.port = matches[5];
         }
+        const parseError = getParseError(parsed, matches);
+        if (parseError !== void 0) {
+          parsed.error = parsed.error || parseError;
+          malformedAuthorityOrPort = true;
+        }
         if (parsed.host) {
           const ipv4result = isIPv4(parsed.host);
           if (ipv4result === false) {
@@ -3788,14 +3849,18 @@ var require_fast_uri = __commonJS({
               parsed.scheme = unescape(parsed.scheme);
             }
             if (parsed.host !== void 0) {
-              parsed.host = unescape(parsed.host);
+              parsed.host = reescapeHostDelimiters(unescape(parsed.host), isIP);
             }
           }
           if (parsed.path) {
-            parsed.path = escape(unescape(parsed.path));
+            parsed.path = normalizePathEncoding(parsed.path);
           }
           if (parsed.fragment) {
-            parsed.fragment = encodeURI(decodeURIComponent(parsed.fragment));
+            try {
+              parsed.fragment = encodeURI(decodeURIComponent(parsed.fragment));
+            } catch {
+              parsed.error = parsed.error || "URI malformed";
+            }
           }
         }
         if (schemeHandler && schemeHandler.parse) {
@@ -3804,7 +3869,29 @@ var require_fast_uri = __commonJS({
       } else {
         parsed.error = parsed.error || "URI can not be parsed.";
       }
-      return parsed;
+      return { parsed, malformedAuthorityOrPort };
+    }
+    function parse3(uri, opts) {
+      return parseWithStatus(uri, opts).parsed;
+    }
+    function normalizeString(uri, opts) {
+      return normalizeStringWithStatus(uri, opts).normalized;
+    }
+    function normalizeStringWithStatus(uri, opts) {
+      const { parsed, malformedAuthorityOrPort } = parseWithStatus(uri, opts);
+      return {
+        normalized: malformedAuthorityOrPort ? uri : serialize(parsed, opts),
+        malformedAuthorityOrPort
+      };
+    }
+    function normalizeComparableURI(uri, opts) {
+      if (typeof uri === "string") {
+        const { normalized, malformedAuthorityOrPort } = normalizeStringWithStatus(uri, opts);
+        return malformedAuthorityOrPort ? void 0 : normalized;
+      }
+      if (typeof uri === "object") {
+        return serialize(uri, opts);
+      }
     }
     var fastUri = {
       SCHEMES,
@@ -9886,14 +9973,14 @@ var $ZodObjectJIT = /* @__PURE__ */ $constructor("$ZodObjectJIT", (inst, def) =>
       return `shape[${k}]._zod.run({ value: input[${k}], issues: [] }, ctx)`;
     };
     doc.write(`const input = payload.value;`);
-    const ids = /* @__PURE__ */ Object.create(null);
+    const ids2 = /* @__PURE__ */ Object.create(null);
     let counter = 0;
     for (const key of normalized.keys) {
-      ids[key] = `key_${counter++}`;
+      ids2[key] = `key_${counter++}`;
     }
     doc.write(`const newResult = {};`);
     for (const key of normalized.keys) {
-      const id = ids[key];
+      const id = ids2[key];
       const k = esc(key);
       const schema = shape[key];
       const isOptionalIn = schema?._zod?.optin === "optional";
@@ -30870,6 +30957,32 @@ function envOrUndefined(key) {
   if (!value || value.startsWith("${")) return void 0;
   return value;
 }
+function sanitizedEnv() {
+  const result = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key === "GOG_ACCESS_TOKEN") continue;
+    if (key === "GOOGLE_APPLICATION_CREDENTIALS") continue;
+    if (/(_TOKEN|_SECRET|_API_KEY|_PRIVATE_KEY)$/.test(key)) continue;
+    result[key] = value;
+  }
+  return result;
+}
+var TOKEN_PATTERNS = [
+  /Bearer\s+[A-Za-z0-9._\-+/=]+/gi,
+  /ya29\.[A-Za-z0-9._\-]+/g,
+  // OAuth2 access tokens
+  /1\/\/[A-Za-z0-9._\-]+/g,
+  // OAuth2 refresh tokens
+  /AIza[A-Za-z0-9_\-]{35}/g
+  // Google API keys
+];
+function redactSecrets(text) {
+  let redacted = text;
+  for (const re of TOKEN_PATTERNS) {
+    redacted = redacted.replace(re, "[REDACTED]");
+  }
+  return redacted;
+}
 function augmentedPath() {
   const home = process.env.HOME;
   const candidates = [
@@ -30912,8 +31025,7 @@ async function run(args, options = {}) {
   fullArgs.push(...args);
   const effectiveTimeout = timeout ?? TIMEOUT_MS;
   return new Promise((resolve, reject) => {
-    const { GOG_ACCESS_TOKEN: _, ...cleanEnv } = process.env;
-    const childEnv = { ...cleanEnv, PATH: augmentedPath() };
+    const childEnv = { ...sanitizedEnv(), PATH: augmentedPath() };
     const child = spawner(envOrUndefined("GOG_PATH") ?? "gog", fullArgs, { env: childEnv });
     const stdoutChunks = [];
     const stderrChunks = [];
@@ -30942,7 +31054,7 @@ async function run(args, options = {}) {
           resolve(stdout);
         }
       } else {
-        reject(new Error(stderr || `gog exited with code ${code}`));
+        reject(new Error(redactSecrets(stderr || `gog exited with code ${code}`)));
       }
     });
     child.on("error", (err) => {
@@ -30964,6 +31076,55 @@ async function run(args, options = {}) {
 var accountParam = external_exports.string().optional().describe(
   "Google account email to use (overrides GOG_ACCOUNT env var)"
 );
+var ids = {
+  course: external_exports.string().describe("Course ID"),
+  coursework: external_exports.string().describe("Coursework ID"),
+  submission: external_exports.string().describe("Submission ID"),
+  announcement: external_exports.string().describe("Announcement ID"),
+  topic: external_exports.string().describe("Topic ID"),
+  invitation: external_exports.string().describe("Invitation ID"),
+  spreadsheet: external_exports.string().describe("Spreadsheet ID (from the URL)"),
+  doc: external_exports.string().describe("Doc ID (from the URL)"),
+  presentation: external_exports.string().describe("Presentation ID"),
+  slide: external_exports.string().describe("Slide ID"),
+  file: external_exports.string().describe("File ID"),
+  message: external_exports.string().describe("Message ID"),
+  thread: external_exports.string().describe("Thread ID"),
+  draft: external_exports.string().describe("Draft ID"),
+  label: external_exports.string().describe("Label ID or name"),
+  attachment: external_exports.string().describe("Attachment ID"),
+  comment: external_exports.string().describe("Comment ID"),
+  meetingCode: external_exports.string().describe("Meeting code (e.g. abc-defg-hij)"),
+  permission: external_exports.string().describe("Permission ID"),
+  user: external_exports.string().describe("User ID"),
+  // People API uses fully-qualified resource names ("people/c123") not bare IDs.
+  person: external_exports.string().describe("Person resource name (people/...) or email")
+};
+var paginationParams = {
+  max: external_exports.number().int().optional().describe("Max results"),
+  page: external_exports.string().optional().describe("Page token"),
+  all: external_exports.boolean().optional().describe("Fetch all pages")
+};
+function registerRunTool(server2, options) {
+  const { service, examples, omitAccount = false, note } = options;
+  const baseDescription = `Run any gog ${service} subcommand not covered by the other tools. Run \`gog ${service} --help\` for the full list of subcommands, or \`gog ${service} <subcommand> --help\` for flags on a specific subcommand.`;
+  const description = note ? `${baseDescription} ${note}` : baseDescription;
+  const inputSchema = {
+    subcommand: external_exports.string().describe(`The gog ${service} subcommand to run, e.g. ${examples}`),
+    args: external_exports.array(external_exports.string()).describe("Additional positional args and flags")
+  };
+  if (!omitAccount) {
+    inputSchema.account = accountParam;
+  }
+  server2.registerTool(`gog_${service}_run`, {
+    description,
+    annotations: { destructiveHint: true },
+    inputSchema
+  }, async (rawArgs) => {
+    const { subcommand, args, account } = rawArgs;
+    return runOrDiagnose([service, subcommand, ...args], { account });
+  });
+}
 function toText(output) {
   return { content: [{ type: "text", text: output }] };
 }
@@ -31049,15 +31210,11 @@ function registerAuthTools(server2) {
       return toError(err);
     }
   });
-  server2.registerTool("gog_auth_run", {
-    description: "Run any gog auth subcommand. Run `gog auth --help` to see all available subcommands and flags. Note: for browser-based authorization, use gog_auth_add instead.",
-    annotations: { destructiveHint: true },
-    inputSchema: {
-      subcommand: external_exports.string().describe('The gog auth subcommand, e.g. "remove", "alias", "tokens"'),
-      args: external_exports.array(external_exports.string()).describe("Additional positional args and flags")
-    }
-  }, async ({ subcommand, args }) => {
-    return runOrDiagnose(["auth", subcommand, ...args], {});
+  registerRunTool(server2, {
+    service: "auth",
+    examples: '"remove", "alias", "tokens"',
+    omitAccount: true,
+    note: "For browser-based authorization, use gog_auth_add instead."
   });
 }
 
@@ -31128,21 +31285,14 @@ function registerDocsTools(server2) {
   }, async ({ docId, account }) => {
     return runOrDiagnose(["docs", "structure", docId], { account });
   });
-  server2.registerTool("gog_docs_run", {
-    description: "Run any gog docs subcommand not covered by the other tools. Run `gog docs --help` for the full list of subcommands, or `gog docs <subcommand> --help` for flags on a specific subcommand.",
-    annotations: { destructiveHint: true },
-    inputSchema: {
-      subcommand: external_exports.string().describe('The gog docs subcommand to run, e.g. "copy", "clear", "insert", "sed", "export"'),
-      args: external_exports.array(external_exports.string()).describe("Additional positional args and flags"),
-      account: accountParam
-    }
-  }, async ({ subcommand, args, account }) => {
-    return runOrDiagnose(["docs", subcommand, ...args], { account });
-  });
+  registerRunTool(server2, { service: "docs", examples: '"copy", "clear", "insert", "sed", "export"' });
 }
 
+// ../gogcli-mcp/src/tools/sheets.ts
+var cellValueParam = external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean(), external_exports.null()]);
+
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.0.8" : "0.0.0";
+var VERSION = true ? "2.0.10" : "0.0.0";
 function createServer(options) {
   return new McpServer({
     name: options?.name ?? "gogcli",
@@ -31166,7 +31316,7 @@ function registerExtraDocsTools(server2) {
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_docs_delete", {
-    description: "Delete content within a Google Doc by character index range.",
+    description: "Delete content within a Google Doc by character index range. To remove the entire document (move to Drive trash), use gog_docs_trash.",
     annotations: { destructiveHint: true },
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
@@ -31180,6 +31330,16 @@ function registerExtraDocsTools(server2) {
     if (tabId) args.push(`--tab-id=${tabId}`);
     return runOrDiagnose(args, { account });
   });
+  server2.registerTool("gog_docs_trash", {
+    description: "Move an entire Google Doc to Drive trash. Convenience wrapper around `gog drive delete` so docs-only users can clean up without installing gogcli-mcp-drive. The doc remains recoverable from Drive trash for ~30 days.",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: external_exports.string().describe("Doc ID to move to trash"),
+      account: accountParam
+    }
+  }, async ({ docId, account }) => {
+    return runOrDiagnose(["drive", "delete", docId], { account });
+  });
   server2.registerTool("gog_docs_edit", {
     description: "Edit a Google Doc by finding and replacing text (stream-edit style).",
     annotations: { destructiveHint: true },
@@ -31195,6 +31355,75 @@ function registerExtraDocsTools(server2) {
     if (matchCase) args.push("--match-case");
     return runOrDiagnose(args, { account });
   });
+  server2.registerTool("gog_docs_read", {
+    description: 'Read the content of a Google Doc. Default: plain text body. Use format="json" for the raw Google Docs API response (lossless, includes character indices needed for index-based gog_docs_insert / gog_docs_delete calls). For markdown output, use gog_docs_export with format="md" \u2014 it writes to a file. Use gog_docs_structure to see paragraph-by-paragraph layout with indices.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      docId: external_exports.string().describe("Doc ID (from the URL)"),
+      format: external_exports.enum(["text", "json"]).optional().describe("Output format (default: text)"),
+      tab: external_exports.string().optional().describe("Target tab title or ID (text mode only)"),
+      allTabs: external_exports.boolean().optional().describe("Show all tabs with headers (text mode only)"),
+      maxBytes: external_exports.number().optional().describe("Max bytes to read in text mode (0 = unlimited; default 2000000)"),
+      account: accountParam
+    }
+  }, async ({ docId, format, tab, allTabs, maxBytes, account }) => {
+    if (format === "json") {
+      return runOrDiagnose(["docs", "raw", docId, "--pretty"], { account });
+    }
+    const args = ["docs", "cat", docId];
+    if (tab) args.push(`--tab=${tab}`);
+    if (allTabs) args.push("--all-tabs");
+    if (maxBytes !== void 0) args.push(`--max-bytes=${maxBytes}`);
+    return runOrDiagnose(args, { account });
+  });
+  server2.registerTool("gog_docs_format", {
+    description: "Apply text or paragraph formatting to a Google Doc. Use `match` to format a specific text occurrence, `matchAll` to format every occurrence, or omit both to format the whole doc. Boolean flags (bold/italic/etc.) set the attribute; negated flags (noBold/noItalic/etc.) clear it.",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: external_exports.string().describe("Doc ID (from the URL)"),
+      match: external_exports.string().optional().describe("Format only the first text match"),
+      matchAll: external_exports.boolean().optional().describe("Format all matches instead of only the first"),
+      matchCase: external_exports.boolean().optional().describe("Case-sensitive matching"),
+      tab: external_exports.string().optional().describe("Target tab title or ID"),
+      fontFamily: external_exports.string().optional().describe("Font family (e.g. Arial, Georgia)"),
+      fontSize: external_exports.number().optional().describe("Font size in points"),
+      textColor: external_exports.string().optional().describe("Text color as #RRGGBB or #RGB"),
+      bgColor: external_exports.string().optional().describe("Text background color as #RRGGBB or #RGB"),
+      bold: external_exports.boolean().optional().describe("Set bold"),
+      noBold: external_exports.boolean().optional().describe("Clear bold"),
+      italic: external_exports.boolean().optional().describe("Set italic"),
+      noItalic: external_exports.boolean().optional().describe("Clear italic"),
+      underline: external_exports.boolean().optional().describe("Set underline"),
+      noUnderline: external_exports.boolean().optional().describe("Clear underline"),
+      strikethrough: external_exports.boolean().optional().describe("Set strikethrough"),
+      noStrikethrough: external_exports.boolean().optional().describe("Clear strikethrough"),
+      alignment: external_exports.enum(["left", "center", "right", "justify", "start", "end", "justified"]).optional().describe("Paragraph alignment"),
+      lineSpacing: external_exports.number().optional().describe("Line spacing percentage (e.g. 100 for single, 150 for 1.5x, 200 for double)"),
+      account: accountParam
+    }
+  }, async (args) => {
+    const a = args;
+    const argv = ["docs", "format", a.docId];
+    if (a.match) argv.push(`--match=${a.match}`);
+    if (a.matchAll) argv.push("--match-all");
+    if (a.matchCase) argv.push("--match-case");
+    if (a.tab) argv.push(`--tab=${a.tab}`);
+    if (a.fontFamily) argv.push(`--font-family=${a.fontFamily}`);
+    if (a.fontSize !== void 0) argv.push(`--font-size=${a.fontSize}`);
+    if (a.textColor) argv.push(`--text-color=${a.textColor}`);
+    if (a.bgColor) argv.push(`--bg-color=${a.bgColor}`);
+    if (a.bold) argv.push("--bold");
+    if (a.noBold) argv.push("--no-bold");
+    if (a.italic) argv.push("--italic");
+    if (a.noItalic) argv.push("--no-italic");
+    if (a.underline) argv.push("--underline");
+    if (a.noUnderline) argv.push("--no-underline");
+    if (a.strikethrough) argv.push("--strikethrough");
+    if (a.noStrikethrough) argv.push("--no-strikethrough");
+    if (a.alignment) argv.push(`--alignment=${a.alignment}`);
+    if (a.lineSpacing !== void 0) argv.push(`--line-spacing=${a.lineSpacing}`);
+    return runOrDiagnose(argv, { account: a.account });
+  });
   server2.registerTool("gog_docs_export", {
     description: "Export a Google Doc as PDF, plain text, HTML, DOCX, or other format.",
     annotations: { readOnlyHint: true },
@@ -31211,12 +31440,12 @@ function registerExtraDocsTools(server2) {
     return runOrDiagnose(args, { account });
   });
   server2.registerTool("gog_docs_insert", {
-    description: "Insert text at a specific position in a Google Doc.",
+    description: "Insert text at a specific character index in a Google Doc. When `index` is omitted, gog defaults to 1 (the very beginning), NOT the end \u2014 sequential inserts without an explicit index produce reversed output. To append at the end of the doc, use gog_docs_append (which uses `gog docs write --append` and is the right tool for iterative document construction). To find a valid index for mid-document inserts, call gog_docs_structure or gog_docs_read first.",
     annotations: { destructiveHint: true },
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
       content: external_exports.string().optional().describe("Text content to insert"),
-      index: external_exports.number().optional().describe("Character index to insert at (default: end of document)"),
+      index: external_exports.number().optional().describe("Character index to insert at (1-based; default: 1 = start of doc). Prefer gog_docs_append when you want to add at the end."),
       file: external_exports.string().optional().describe("Path to a file whose content to insert"),
       tabId: external_exports.string().optional().describe("Tab ID to insert into (for multi-tab docs)"),
       account: accountParam
@@ -31229,6 +31458,25 @@ function registerExtraDocsTools(server2) {
     if (tabId) args.push(`--tab-id=${tabId}`);
     return runOrDiagnose(args, { account });
   });
+  server2.registerTool("gog_docs_append", {
+    description: "Append text to the end of a Google Doc. This is the right tool for iterative document construction \u2014 multiple sequential calls produce content in the order they were called. Use gog_docs_insert only when you need to insert at a specific character position.",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: external_exports.string().describe("Doc ID (from the URL)"),
+      text: external_exports.string().optional().describe("Text content to append"),
+      file: external_exports.string().optional().describe('Path to a text file to append (use "-" for stdin)'),
+      markdown: external_exports.boolean().optional().describe("Convert markdown to Google Docs formatting (headings, bold, lists, etc.)"),
+      tab: external_exports.string().optional().describe("Target tab title or ID (for multi-tab docs)"),
+      account: accountParam
+    }
+  }, async ({ docId, text, file: file2, markdown, tab, account }) => {
+    const args = ["docs", "write", docId, "--append"];
+    if (text) args.push(`--text=${text}`);
+    if (file2) args.push(`--file=${file2}`);
+    if (markdown) args.push("--markdown");
+    if (tab) args.push(`--tab=${tab}`);
+    return runOrDiagnose(args, { account });
+  });
   server2.registerTool("gog_docs_list_tabs", {
     description: "List all tabs in a Google Doc.",
     annotations: { readOnlyHint: true },

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-docs",
   "display_name": "gogcli (Docs)",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",
@@ -158,6 +158,22 @@
     {
       "name": "gog_docs_comments_delete",
       "description": "Delete a comment from a Google Doc. This action is permanent."
+    },
+    {
+      "name": "gog_docs_append",
+      "description": "Append text to the end of a Google Doc (the right tool for iterative construction; sequential calls produce in-order content)"
+    },
+    {
+      "name": "gog_docs_read",
+      "description": "Read a Google Doc as plain text or as raw Docs API JSON"
+    },
+    {
+      "name": "gog_docs_format",
+      "description": "Apply text/paragraph formatting (bold, italic, font size, color, alignment, line spacing) — supports match, matchAll, matchCase"
+    },
+    {
+      "name": "gog_docs_trash",
+      "description": "Move an entire Google Doc to Drive trash (convenience wrapper around gog drive delete)"
     }
   ],
   "compatibility": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp-docs",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "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>",

package/server.json

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

package/src/tools/docs-extra.ts

@@ -18,7 +18,7 @@ export function registerExtraDocsTools(server: McpServer): void {
   });
 
   server.registerTool('gog_docs_delete', {
-    description: 'Delete content within a Google Doc by character index range.',
+    description: 'Delete content within a Google Doc by character index range. To remove the entire document (move to Drive trash), use gog_docs_trash.',
     annotations: { destructiveHint: true },
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
@@ -33,6 +33,17 @@ export function registerExtraDocsTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
+  server.registerTool('gog_docs_trash', {
+    description: 'Move an entire Google Doc to Drive trash. Convenience wrapper around `gog drive delete` so docs-only users can clean up without installing gogcli-mcp-drive. The doc remains recoverable from Drive trash for ~30 days.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID to move to trash'),
+      account: accountParam,
+    },
+  }, async ({ docId, account }) => {
+    return runOrDiagnose(['drive', 'delete', docId], { account });
+  });
+
   server.registerTool('gog_docs_edit', {
     description: 'Edit a Google Doc by finding and replacing text (stream-edit style).',
     annotations: { destructiveHint: true },
@@ -49,6 +60,94 @@ export function registerExtraDocsTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
+  server.registerTool('gog_docs_read', {
+    description: 'Read the content of a Google Doc. Default: plain text body. Use format="json" for the raw Google Docs API response (lossless, includes character indices needed for index-based gog_docs_insert / gog_docs_delete calls). For markdown output, use gog_docs_export with format="md" — it writes to a file. Use gog_docs_structure to see paragraph-by-paragraph layout with indices.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      format: z.enum(['text', 'json']).optional().describe('Output format (default: text)'),
+      tab: z.string().optional().describe('Target tab title or ID (text mode only)'),
+      allTabs: z.boolean().optional().describe('Show all tabs with headers (text mode only)'),
+      maxBytes: z.number().optional().describe('Max bytes to read in text mode (0 = unlimited; default 2000000)'),
+      account: accountParam,
+    },
+  }, async ({ docId, format, tab, allTabs, maxBytes, account }) => {
+    if (format === 'json') {
+      return runOrDiagnose(['docs', 'raw', docId, '--pretty'], { account });
+    }
+    const args = ['docs', 'cat', docId];
+    if (tab) args.push(`--tab=${tab}`);
+    if (allTabs) args.push('--all-tabs');
+    if (maxBytes !== undefined) args.push(`--max-bytes=${maxBytes}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_docs_format', {
+    description: 'Apply text or paragraph formatting to a Google Doc. Use `match` to format a specific text occurrence, `matchAll` to format every occurrence, or omit both to format the whole doc. Boolean flags (bold/italic/etc.) set the attribute; negated flags (noBold/noItalic/etc.) clear it.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      match: z.string().optional().describe('Format only the first text match'),
+      matchAll: z.boolean().optional().describe('Format all matches instead of only the first'),
+      matchCase: z.boolean().optional().describe('Case-sensitive matching'),
+      tab: z.string().optional().describe('Target tab title or ID'),
+      fontFamily: z.string().optional().describe('Font family (e.g. Arial, Georgia)'),
+      fontSize: z.number().optional().describe('Font size in points'),
+      textColor: z.string().optional().describe('Text color as #RRGGBB or #RGB'),
+      bgColor: z.string().optional().describe('Text background color as #RRGGBB or #RGB'),
+      bold: z.boolean().optional().describe('Set bold'),
+      noBold: z.boolean().optional().describe('Clear bold'),
+      italic: z.boolean().optional().describe('Set italic'),
+      noItalic: z.boolean().optional().describe('Clear italic'),
+      underline: z.boolean().optional().describe('Set underline'),
+      noUnderline: z.boolean().optional().describe('Clear underline'),
+      strikethrough: z.boolean().optional().describe('Set strikethrough'),
+      noStrikethrough: z.boolean().optional().describe('Clear strikethrough'),
+      alignment: z.enum(['left', 'center', 'right', 'justify', 'start', 'end', 'justified']).optional().describe('Paragraph alignment'),
+      lineSpacing: z.number().optional().describe('Line spacing percentage (e.g. 100 for single, 150 for 1.5x, 200 for double)'),
+      account: accountParam,
+    },
+  }, async (args) => {
+    const a = args as {
+      docId: string;
+      match?: string;
+      matchAll?: boolean;
+      matchCase?: boolean;
+      tab?: string;
+      fontFamily?: string;
+      fontSize?: number;
+      textColor?: string;
+      bgColor?: string;
+      bold?: boolean; noBold?: boolean;
+      italic?: boolean; noItalic?: boolean;
+      underline?: boolean; noUnderline?: boolean;
+      strikethrough?: boolean; noStrikethrough?: boolean;
+      alignment?: string;
+      lineSpacing?: number;
+      account?: string;
+    };
+    const argv = ['docs', 'format', a.docId];
+    if (a.match) argv.push(`--match=${a.match}`);
+    if (a.matchAll) argv.push('--match-all');
+    if (a.matchCase) argv.push('--match-case');
+    if (a.tab) argv.push(`--tab=${a.tab}`);
+    if (a.fontFamily) argv.push(`--font-family=${a.fontFamily}`);
+    if (a.fontSize !== undefined) argv.push(`--font-size=${a.fontSize}`);
+    if (a.textColor) argv.push(`--text-color=${a.textColor}`);
+    if (a.bgColor) argv.push(`--bg-color=${a.bgColor}`);
+    if (a.bold) argv.push('--bold');
+    if (a.noBold) argv.push('--no-bold');
+    if (a.italic) argv.push('--italic');
+    if (a.noItalic) argv.push('--no-italic');
+    if (a.underline) argv.push('--underline');
+    if (a.noUnderline) argv.push('--no-underline');
+    if (a.strikethrough) argv.push('--strikethrough');
+    if (a.noStrikethrough) argv.push('--no-strikethrough');
+    if (a.alignment) argv.push(`--alignment=${a.alignment}`);
+    if (a.lineSpacing !== undefined) argv.push(`--line-spacing=${a.lineSpacing}`);
+    return runOrDiagnose(argv, { account: a.account });
+  });
+
   server.registerTool('gog_docs_export', {
     description: 'Export a Google Doc as PDF, plain text, HTML, DOCX, or other format.',
     annotations: { readOnlyHint: true },
@@ -66,12 +165,12 @@ export function registerExtraDocsTools(server: McpServer): void {
   });
 
   server.registerTool('gog_docs_insert', {
-    description: 'Insert text at a specific position in a Google Doc.',
+    description: 'Insert text at a specific character index in a Google Doc. When `index` is omitted, gog defaults to 1 (the very beginning), NOT the end — sequential inserts without an explicit index produce reversed output. To append at the end of the doc, use gog_docs_append (which uses `gog docs write --append` and is the right tool for iterative document construction). To find a valid index for mid-document inserts, call gog_docs_structure or gog_docs_read first.',
     annotations: { destructiveHint: true },
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
       content: z.string().optional().describe('Text content to insert'),
-      index: z.number().optional().describe('Character index to insert at (default: end of document)'),
+      index: z.number().optional().describe('Character index to insert at (1-based; default: 1 = start of doc). Prefer gog_docs_append when you want to add at the end.'),
       file: z.string().optional().describe('Path to a file whose content to insert'),
       tabId: z.string().optional().describe('Tab ID to insert into (for multi-tab docs)'),
       account: accountParam,
@@ -85,6 +184,26 @@ export function registerExtraDocsTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
+  server.registerTool('gog_docs_append', {
+    description: 'Append text to the end of a Google Doc. This is the right tool for iterative document construction — multiple sequential calls produce content in the order they were called. Use gog_docs_insert only when you need to insert at a specific character position.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      text: z.string().optional().describe('Text content to append'),
+      file: z.string().optional().describe('Path to a text file to append (use "-" for stdin)'),
+      markdown: z.boolean().optional().describe('Convert markdown to Google Docs formatting (headings, bold, lists, etc.)'),
+      tab: z.string().optional().describe('Target tab title or ID (for multi-tab docs)'),
+      account: accountParam,
+    },
+  }, async ({ docId, text, file, markdown, tab, account }) => {
+    const args = ['docs', 'write', docId, '--append'];
+    if (text) args.push(`--text=${text}`);
+    if (file) args.push(`--file=${file}`);
+    if (markdown) args.push('--markdown');
+    if (tab) args.push(`--tab=${tab}`);
+    return runOrDiagnose(args, { account });
+  });
+
   server.registerTool('gog_docs_list_tabs', {
     description: 'List all tabs in a Google Doc.',
     annotations: { readOnlyHint: true },
@@ -142,8 +261,7 @@ export function registerExtraDocsTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
-  // --- Dedicated comment tools (replacing the generic escape hatch in base) ---
-
+  // Comment-thread tools
   server.registerTool('gog_docs_comments_list', {
     description:
       'List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments.',

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

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { registerExtraDocsTools } from '../../src/tools/docs-extra.js';
 import * as lib from '../../../gogcli-mcp/src/lib.js';
-import { setupExtrasHandlers, toText } from '../../../gogcli-mcp/tests/helpers/extras-harness.js';
+import { setupHandlers as setupHandlersBase, toText } from '../../../gogcli-mcp/tests/helpers/test-harness.js';
 
 vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
   const actual = await importOriginal<typeof lib>();
@@ -11,7 +11,7 @@ vi.mock('../../../gogcli-mcp/src/lib.js', async (importOriginal) => {
   };
 });
 
-const setupHandlers = () => setupExtrasHandlers(registerExtraDocsTools);
+const setupHandlers = () => setupHandlersBase(registerExtraDocsTools);
 
 beforeEach(() => vi.clearAllMocks());
 
@@ -518,3 +518,129 @@ describe('gog_docs_comments_delete', () => {
     );
   });
 });
+
+describe('gog_docs_trash', () => {
+  it('routes to gog drive delete <docId>', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_trash')!({ docId: 'd1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['drive', 'delete', 'd1'], { account: undefined });
+  });
+});
+
+describe('gog_docs_append', () => {
+  it('uses gog docs write --append', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_append')!({ docId: 'd1', text: 'Hello' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'write', 'd1', '--append', '--text=Hello'],
+      { account: undefined },
+    );
+  });
+
+  it('passes file, markdown, and tab flags', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_append')!({
+      docId: 'd1', file: '/tmp/section.md', markdown: true, tab: 'Notes',
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'write', 'd1', '--append', '--file=/tmp/section.md', '--markdown', '--tab=Notes'],
+      { account: undefined },
+    );
+  });
+});
+
+describe('gog_docs_read', () => {
+  it('defaults to plain text via gog docs cat', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('hello'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_read')!({ docId: 'd1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'cat', 'd1'], { account: undefined });
+  });
+
+  it('routes json format to gog docs raw --pretty', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_read')!({ docId: 'd1', format: 'json' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'raw', 'd1', '--pretty'], { account: undefined });
+  });
+
+  it('passes tab, allTabs, maxBytes in text mode', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText(''));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_read')!({ docId: 'd1', tab: 'Section A', allTabs: true, maxBytes: 0 });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'cat', 'd1', '--tab=Section A', '--all-tabs', '--max-bytes=0'],
+      { account: undefined },
+    );
+  });
+});
+
+describe('gog_docs_format', () => {
+  it('passes all text/paragraph attribute flags', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_format')!({
+      docId: 'd1',
+      match: 'Title',
+      matchAll: true,
+      matchCase: true,
+      tab: 'Body',
+      fontFamily: 'Arial',
+      fontSize: 18,
+      textColor: '#333333',
+      bgColor: '#FFF5D9',
+      bold: true,
+      italic: true,
+      underline: true,
+      strikethrough: true,
+      alignment: 'center',
+      lineSpacing: 150,
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      [
+        'docs', 'format', 'd1',
+        '--match=Title',
+        '--match-all',
+        '--match-case',
+        '--tab=Body',
+        '--font-family=Arial',
+        '--font-size=18',
+        '--text-color=#333333',
+        '--bg-color=#FFF5D9',
+        '--bold',
+        '--italic',
+        '--underline',
+        '--strikethrough',
+        '--alignment=center',
+        '--line-spacing=150',
+      ],
+      { account: undefined },
+    );
+  });
+
+  it('emits clear-style flags (noBold/noItalic/...) without the set variants', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_format')!({
+      docId: 'd1',
+      noBold: true,
+      noItalic: true,
+      noUnderline: true,
+      noStrikethrough: true,
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'format', 'd1', '--no-bold', '--no-italic', '--no-underline', '--no-strikethrough'],
+      { account: undefined },
+    );
+  });
+
+  it('omits all flags when not provided (whole-doc no-op call passes through)', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_format')!({ docId: 'd1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'format', 'd1'], { account: undefined });
+  });
+});