gogcli-mcp-docs 2.5.0 → 2.6.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": "2.5.0"
+    "version": "2.6.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": "2.5.0",
+      "version": "2.6.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/dist/index.js

@@ -31318,7 +31318,7 @@ var failIfNotEmptyParam = external_exports.boolean().optional().describe(
 );
 
 // ../gogcli-mcp/src/server.ts
-var VERSION = true ? "2.5.0" : "0.0.0";
+var VERSION = true ? "2.6.0" : "0.0.0";
 function createServer(options) {
   return new McpServer({
     name: options?.name ?? "gogcli",
@@ -31346,13 +31346,22 @@ function registerExtraDocsTools(server2) {
     annotations: { destructiveHint: true },
     inputSchema: {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
-      start: external_exports.number().describe("Start index (character position, 1-based)"),
-      end: external_exports.number().describe("End index (character position, exclusive)"),
+      start: external_exports.number().optional().describe("Start index (character position, 1-based). Required unless `at` is set."),
+      end: external_exports.number().optional().describe("End index (character position, exclusive). Required unless `at` is set."),
+      at: external_exports.string().optional().describe("Anchor by literal text and delete that matched range, instead of supplying start/end indices."),
+      occurrence: external_exports.number().int().optional().describe("Use the Nth `at` match (1-based; required when `at` is ambiguous)"),
+      matchCase: external_exports.boolean().optional().describe("Case-sensitive `at` matching"),
       tabId: external_exports.string().optional().describe("Tab ID to delete content from (for multi-tab docs)"),
       account: accountParam
     }
-  }, async ({ docId, start, end, tabId, account }) => {
-    const args = ["docs", "delete", `--start=${start}`, `--end=${end}`, docId];
+  }, async ({ docId, start, end, at, occurrence, matchCase, tabId, account }) => {
+    const args = ["docs", "delete"];
+    if (start !== void 0) args.push(`--start=${start}`);
+    if (end !== void 0) args.push(`--end=${end}`);
+    args.push(docId);
+    if (at) args.push(`--at=${at}`);
+    if (occurrence !== void 0) args.push(`--occurrence=${occurrence}`);
+    if (matchCase) args.push("--match-case");
     if (tabId) args.push(`--tab-id=${tabId}`);
     return runOrDiagnose(args, { account });
   });
@@ -31424,6 +31433,8 @@ function registerExtraDocsTools(server2) {
       strikethrough: external_exports.boolean().optional().describe("Set strikethrough"),
       noStrikethrough: external_exports.boolean().optional().describe("Clear strikethrough"),
       code: external_exports.boolean().optional().describe("Apply code style (Courier New monospace + grey background)"),
+      link: external_exports.string().optional().describe("Set a hyperlink on the matched text. Accepts http://, https://, mailto:, #bookmarkId, or #heading-slug."),
+      noLink: external_exports.boolean().optional().describe("Clear any hyperlink on the matched text"),
       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)"),
       headingLevel: external_exports.number().int().optional().describe("Set paragraph named style to HEADING_1..HEADING_6 (shortcut for namedStyle=HEADING_N)"),
@@ -31450,6 +31461,8 @@ function registerExtraDocsTools(server2) {
     if (a.strikethrough) argv.push("--strikethrough");
     if (a.noStrikethrough) argv.push("--no-strikethrough");
     if (a.code) argv.push("--code");
+    if (a.link) argv.push(`--link=${a.link}`);
+    if (a.noLink) argv.push("--no-link");
     if (a.alignment) argv.push(`--alignment=${a.alignment}`);
     if (a.lineSpacing !== void 0) argv.push(`--line-spacing=${a.lineSpacing}`);
     if (a.headingLevel !== void 0) argv.push(`--heading-level=${a.headingLevel}`);
@@ -31479,14 +31492,20 @@ function registerExtraDocsTools(server2) {
       content: external_exports.string().optional().describe("Text content to insert"),
       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"),
+      at: external_exports.string().optional().describe("Anchor by literal text and insert at the start of the matched range, instead of computing an index."),
+      occurrence: external_exports.number().int().optional().describe("Use the Nth `at` match (1-based; required when `at` is ambiguous)"),
+      matchCase: external_exports.boolean().optional().describe("Case-sensitive `at` matching"),
       tabId: external_exports.string().optional().describe("Tab ID to insert into (for multi-tab docs)"),
       account: accountParam
     }
-  }, async ({ docId, content, index, file: file2, tabId, account }) => {
+  }, async ({ docId, content, index, file: file2, at, occurrence, matchCase, tabId, account }) => {
     const args = ["docs", "insert", docId];
     if (content) args.push(content);
     if (index !== void 0) args.push(`--index=${index}`);
     if (file2) args.push(`--file=${file2}`);
+    if (at) args.push(`--at=${at}`);
+    if (occurrence !== void 0) args.push(`--occurrence=${occurrence}`);
+    if (matchCase) args.push("--match-case");
     if (tabId) args.push(`--tab-id=${tabId}`);
     return runOrDiagnose(args, { account });
   });
@@ -31552,17 +31571,23 @@ function registerExtraDocsTools(server2) {
       index: external_exports.number().optional().describe("Character index to insert at"),
       replaceRange: external_exports.string().optional().describe('Replace a UTF-16 Docs API range START:END (e.g. "25:40") instead of inserting at index. The replacement text/file content overwrites the range.'),
       markdown: external_exports.boolean().optional().describe("Convert markdown in the text/file to Google Docs formatting (headings, bold, lists, etc.) instead of inserting it literally."),
+      at: external_exports.string().optional().describe("Anchor by literal text and replace that matched range, instead of supplying an index or replaceRange."),
+      occurrence: external_exports.number().int().optional().describe("Use the Nth `at` match (1-based; required when `at` is ambiguous)"),
+      matchCase: external_exports.boolean().optional().describe("Case-sensitive `at` matching"),
       tabId: external_exports.string().optional().describe("Tab ID for multi-tab docs"),
       pageless: external_exports.boolean().optional().describe("Set document to pageless format"),
       account: accountParam
     }
-  }, async ({ docId, text, file: file2, index, replaceRange, markdown, tabId, pageless, account }) => {
+  }, async ({ docId, text, file: file2, index, replaceRange, markdown, at, occurrence, matchCase, tabId, pageless, account }) => {
     const args = ["docs", "update", docId];
     if (text) args.push(`--text=${text}`);
     if (file2) args.push(`--file=${file2}`);
     if (index !== void 0) args.push(`--index=${index}`);
     if (replaceRange) args.push(`--replace-range=${replaceRange}`);
     if (markdown) args.push("--markdown");
+    if (at) args.push(`--at=${at}`);
+    if (occurrence !== void 0) args.push(`--occurrence=${occurrence}`);
+    if (matchCase) args.push("--match-case");
     if (tabId) args.push(`--tab-id=${tabId}`);
     if (pageless) args.push("--pageless");
     return runOrDiagnose(args, { account });
@@ -31655,6 +31680,48 @@ function registerExtraDocsTools(server2) {
   }, async ({ docId, commentId, account }) => {
     return runOrDiagnose(["docs", "comments", "reopen", docId, commentId], { account });
   });
+  server2.registerTool("gog_docs_comments_locate", {
+    description: "Locate a comment's anchor in a Google Doc \u2014 resolves the comment's quoted text to its current Docs API index range, or reports the comment as orphaned if the quote can no longer be found (e.g. the anchored text was edited away). Read-only; useful before an index-based edit near a comment.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      docId: external_exports.string().describe("Doc ID (from the URL)"),
+      commentId: external_exports.string().describe("Comment ID to locate"),
+      matchCase: external_exports.boolean().optional().describe("Case-sensitive matching of the comment quote"),
+      normalizeWhitespace: external_exports.boolean().optional().describe("Collapse whitespace while matching the comment quote"),
+      tab: external_exports.string().optional().describe("Target a specific tab by title or ID"),
+      account: accountParam
+    }
+  }, async ({ docId, commentId, matchCase, normalizeWhitespace, tab, account }) => {
+    const args = ["docs", "comments", "locate", docId, commentId];
+    if (matchCase) args.push("--match-case");
+    if (normalizeWhitespace) args.push("--normalize-whitespace");
+    if (tab) args.push(`--tab=${tab}`);
+    return runOrDiagnose(args, { account });
+  });
+  server2.registerTool("gog_docs_find_range", {
+    description: "Map literal text in a Google Doc to its Docs API UTF-16 index range(s). Read-only helper for computing the start/end indices that index-based tools (gog_docs_delete, gog_docs_update --replace-range) need. Returns the first match by default; use occurrence to pick a specific one or all to return every match.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      docId: external_exports.string().describe("Doc ID (from the URL)"),
+      text: external_exports.string().describe("Literal text to locate"),
+      occurrence: external_exports.number().int().optional().describe("Return the Nth occurrence (1-based; default: first)"),
+      matchCase: external_exports.boolean().optional().describe("Case-sensitive matching"),
+      normalizeWhitespace: external_exports.boolean().optional().describe("Collapse whitespace while matching"),
+      all: external_exports.boolean().optional().describe("Return all matches instead of just one"),
+      failEmpty: external_exports.boolean().optional().describe("Treat no matches as an error instead of returning an empty result"),
+      tab: external_exports.string().optional().describe("Target a specific tab by title or ID"),
+      account: accountParam
+    }
+  }, async ({ docId, text, occurrence, matchCase, normalizeWhitespace, all, failEmpty, tab, account }) => {
+    const args = ["docs", "find-range", docId, text];
+    if (occurrence !== void 0) args.push(`--occurrence=${occurrence}`);
+    if (matchCase) args.push("--match-case");
+    if (normalizeWhitespace) args.push("--normalize-whitespace");
+    if (all) args.push("--all");
+    if (failEmpty) args.push("--fail-empty");
+    if (tab) args.push(`--tab=${tab}`);
+    return runOrDiagnose(args, { account });
+  });
   server2.registerTool("gog_docs_table_column_width", {
     description: "Set a fixed width (in points) for a table column, or reset columns to Docs-managed even distribution. Target the table by 1-based index in document order (negative counts from the end) and the column by 1-based number. Pass evenlyDistributed without col to reset every column in the table.",
     annotations: { destructiveHint: true },
@@ -31683,13 +31750,19 @@ function registerExtraDocsTools(server2) {
       docId: external_exports.string().describe("Doc ID (from the URL)"),
       index: external_exports.number().int().optional().describe("Character index to insert at (1 = beginning). Omit or use atEnd for end-of-doc."),
       atEnd: external_exports.boolean().optional().describe("Insert at end-of-doc/tab (mutually exclusive with index)"),
+      at: external_exports.string().optional().describe("Anchor by literal text and insert the page break at the start of the matched range, instead of an index."),
+      occurrence: external_exports.number().int().optional().describe("Use the Nth `at` match (1-based; required when `at` is ambiguous)"),
+      matchCase: external_exports.boolean().optional().describe("Case-sensitive `at` matching"),
       tab: external_exports.string().optional().describe("Target a specific tab by title or ID"),
       account: accountParam
     }
-  }, async ({ docId, index, atEnd, tab, account }) => {
+  }, async ({ docId, index, atEnd, at, occurrence, matchCase, tab, account }) => {
     const args = ["docs", "insert-page-break", docId];
     if (index !== void 0) args.push(`--index=${index}`);
     if (atEnd) args.push("--at-end");
+    if (at) args.push(`--at=${at}`);
+    if (occurrence !== void 0) args.push(`--occurrence=${occurrence}`);
+    if (matchCase) args.push("--match-case");
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
   });
@@ -31831,13 +31904,19 @@ function registerExtraDocsTools(server2) {
       email: external_exports.string().describe("Email address for the person chip"),
       index: external_exports.number().int().optional().describe("Character index to insert at. Omit or use atEnd for end-of-doc."),
       atEnd: external_exports.boolean().optional().describe("Insert at end-of-doc/tab (mutually exclusive with index)"),
+      at: external_exports.string().optional().describe("Anchor by literal text, delete the match, and insert the person chip there, instead of an index."),
+      occurrence: external_exports.number().int().optional().describe("Use the Nth `at` match (1-based; required when `at` is ambiguous)"),
+      matchCase: external_exports.boolean().optional().describe("Case-sensitive `at` matching"),
       tab: external_exports.string().optional().describe("Target a specific tab by title or ID"),
       account: accountParam
     }
-  }, async ({ docId, email: email3, index, atEnd, tab, account }) => {
+  }, async ({ docId, email: email3, index, atEnd, at, occurrence, matchCase, tab, account }) => {
     const args = ["docs", "insert-person", docId, `--email=${email3}`];
     if (index !== void 0) args.push(`--index=${index}`);
     if (atEnd) args.push("--at-end");
+    if (at) args.push(`--at=${at}`);
+    if (occurrence !== void 0) args.push(`--occurrence=${occurrence}`);
+    if (matchCase) args.push("--match-case");
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
   });

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp-docs",
   "display_name": "gogcli (Docs)",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Extended Google Docs for Claude via gogcli — auth + full Docs and comments support",
   "author": {
     "name": "Chris Hall",
@@ -195,6 +195,14 @@
       "name": "gog_docs_comments_reopen",
       "description": "Reopen a previously resolved comment."
     },
+    {
+      "name": "gog_docs_comments_locate",
+      "description": "Resolve a comment's quoted anchor to its current Docs API index range, or report it as orphaned."
+    },
+    {
+      "name": "gog_docs_find_range",
+      "description": "Map literal text to its Docs API UTF-16 index range(s) for index-based edits."
+    },
     {
       "name": "gog_docs_table_column_width",
       "description": "Set a fixed table column width in points, or reset columns to Docs-managed even distribution."

package/package.json

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

package/server.json

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

package/src/tools/docs-extra.ts

@@ -22,13 +22,22 @@ export function registerExtraDocsTools(server: McpServer): void {
     annotations: { destructiveHint: true },
     inputSchema: {
       docId: z.string().describe('Doc ID (from the URL)'),
-      start: z.number().describe('Start index (character position, 1-based)'),
-      end: z.number().describe('End index (character position, exclusive)'),
+      start: z.number().optional().describe('Start index (character position, 1-based). Required unless `at` is set.'),
+      end: z.number().optional().describe('End index (character position, exclusive). Required unless `at` is set.'),
+      at: z.string().optional().describe('Anchor by literal text and delete that matched range, instead of supplying start/end indices.'),
+      occurrence: z.number().int().optional().describe('Use the Nth `at` match (1-based; required when `at` is ambiguous)'),
+      matchCase: z.boolean().optional().describe('Case-sensitive `at` matching'),
       tabId: z.string().optional().describe('Tab ID to delete content from (for multi-tab docs)'),
       account: accountParam,
     },
-  }, async ({ docId, start, end, tabId, account }) => {
-    const args = ['docs', 'delete', `--start=${start}`, `--end=${end}`, docId];
+  }, async ({ docId, start, end, at, occurrence, matchCase, tabId, account }) => {
+    const args = ['docs', 'delete'];
+    if (start !== undefined) args.push(`--start=${start}`);
+    if (end !== undefined) args.push(`--end=${end}`);
+    args.push(docId);
+    if (at) args.push(`--at=${at}`);
+    if (occurrence !== undefined) args.push(`--occurrence=${occurrence}`);
+    if (matchCase) args.push('--match-case');
     if (tabId) args.push(`--tab-id=${tabId}`);
     return runOrDiagnose(args, { account });
   });
@@ -104,6 +113,8 @@ export function registerExtraDocsTools(server: McpServer): void {
       strikethrough: z.boolean().optional().describe('Set strikethrough'),
       noStrikethrough: z.boolean().optional().describe('Clear strikethrough'),
       code: z.boolean().optional().describe('Apply code style (Courier New monospace + grey background)'),
+      link: z.string().optional().describe('Set a hyperlink on the matched text. Accepts http://, https://, mailto:, #bookmarkId, or #heading-slug.'),
+      noLink: z.boolean().optional().describe('Clear any hyperlink on the matched text'),
       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)'),
       headingLevel: z.number().int().optional().describe('Set paragraph named style to HEADING_1..HEADING_6 (shortcut for namedStyle=HEADING_N)'),
@@ -126,6 +137,7 @@ export function registerExtraDocsTools(server: McpServer): void {
       underline?: boolean; noUnderline?: boolean;
       strikethrough?: boolean; noStrikethrough?: boolean;
       code?: boolean;
+      link?: string; noLink?: boolean;
       alignment?: string;
       lineSpacing?: number;
       headingLevel?: number;
@@ -150,6 +162,8 @@ export function registerExtraDocsTools(server: McpServer): void {
     if (a.strikethrough) argv.push('--strikethrough');
     if (a.noStrikethrough) argv.push('--no-strikethrough');
     if (a.code) argv.push('--code');
+    if (a.link) argv.push(`--link=${a.link}`);
+    if (a.noLink) argv.push('--no-link');
     if (a.alignment) argv.push(`--alignment=${a.alignment}`);
     if (a.lineSpacing !== undefined) argv.push(`--line-spacing=${a.lineSpacing}`);
     if (a.headingLevel !== undefined) argv.push(`--heading-level=${a.headingLevel}`);
@@ -181,14 +195,20 @@ export function registerExtraDocsTools(server: McpServer): void {
       content: z.string().optional().describe('Text content to insert'),
       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'),
+      at: z.string().optional().describe('Anchor by literal text and insert at the start of the matched range, instead of computing an index.'),
+      occurrence: z.number().int().optional().describe('Use the Nth `at` match (1-based; required when `at` is ambiguous)'),
+      matchCase: z.boolean().optional().describe('Case-sensitive `at` matching'),
       tabId: z.string().optional().describe('Tab ID to insert into (for multi-tab docs)'),
       account: accountParam,
     },
-  }, async ({ docId, content, index, file, tabId, account }) => {
+  }, async ({ docId, content, index, file, at, occurrence, matchCase, tabId, account }) => {
     const args = ['docs', 'insert', docId];
     if (content) args.push(content);
     if (index !== undefined) args.push(`--index=${index}`);
     if (file) args.push(`--file=${file}`);
+    if (at) args.push(`--at=${at}`);
+    if (occurrence !== undefined) args.push(`--occurrence=${occurrence}`);
+    if (matchCase) args.push('--match-case');
     if (tabId) args.push(`--tab-id=${tabId}`);
     return runOrDiagnose(args, { account });
   });
@@ -258,17 +278,23 @@ export function registerExtraDocsTools(server: McpServer): void {
       index: z.number().optional().describe('Character index to insert at'),
       replaceRange: z.string().optional().describe('Replace a UTF-16 Docs API range START:END (e.g. "25:40") instead of inserting at index. The replacement text/file content overwrites the range.'),
       markdown: z.boolean().optional().describe('Convert markdown in the text/file to Google Docs formatting (headings, bold, lists, etc.) instead of inserting it literally.'),
+      at: z.string().optional().describe('Anchor by literal text and replace that matched range, instead of supplying an index or replaceRange.'),
+      occurrence: z.number().int().optional().describe('Use the Nth `at` match (1-based; required when `at` is ambiguous)'),
+      matchCase: z.boolean().optional().describe('Case-sensitive `at` matching'),
       tabId: z.string().optional().describe('Tab ID for multi-tab docs'),
       pageless: z.boolean().optional().describe('Set document to pageless format'),
       account: accountParam,
     },
-  }, async ({ docId, text, file, index, replaceRange, markdown, tabId, pageless, account }) => {
+  }, async ({ docId, text, file, index, replaceRange, markdown, at, occurrence, matchCase, tabId, pageless, account }) => {
     const args = ['docs', 'update', docId];
     if (text) args.push(`--text=${text}`);
     if (file) args.push(`--file=${file}`);
     if (index !== undefined) args.push(`--index=${index}`);
     if (replaceRange) args.push(`--replace-range=${replaceRange}`);
     if (markdown) args.push('--markdown');
+    if (at) args.push(`--at=${at}`);
+    if (occurrence !== undefined) args.push(`--occurrence=${occurrence}`);
+    if (matchCase) args.push('--match-case');
     if (tabId) args.push(`--tab-id=${tabId}`);
     if (pageless) args.push('--pageless');
     return runOrDiagnose(args, { account });
@@ -372,6 +398,50 @@ export function registerExtraDocsTools(server: McpServer): void {
     return runOrDiagnose(['docs', 'comments', 'reopen', docId, commentId], { account });
   });
 
+  server.registerTool('gog_docs_comments_locate', {
+    description: 'Locate a comment\'s anchor in a Google Doc — resolves the comment\'s quoted text to its current Docs API index range, or reports the comment as orphaned if the quote can no longer be found (e.g. the anchored text was edited away). Read-only; useful before an index-based edit near a comment.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      commentId: z.string().describe('Comment ID to locate'),
+      matchCase: z.boolean().optional().describe('Case-sensitive matching of the comment quote'),
+      normalizeWhitespace: z.boolean().optional().describe('Collapse whitespace while matching the comment quote'),
+      tab: z.string().optional().describe('Target a specific tab by title or ID'),
+      account: accountParam,
+    },
+  }, async ({ docId, commentId, matchCase, normalizeWhitespace, tab, account }) => {
+    const args = ['docs', 'comments', 'locate', docId, commentId];
+    if (matchCase) args.push('--match-case');
+    if (normalizeWhitespace) args.push('--normalize-whitespace');
+    if (tab) args.push(`--tab=${tab}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_docs_find_range', {
+    description: 'Map literal text in a Google Doc to its Docs API UTF-16 index range(s). Read-only helper for computing the start/end indices that index-based tools (gog_docs_delete, gog_docs_update --replace-range) need. Returns the first match by default; use occurrence to pick a specific one or all to return every match.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      text: z.string().describe('Literal text to locate'),
+      occurrence: z.number().int().optional().describe('Return the Nth occurrence (1-based; default: first)'),
+      matchCase: z.boolean().optional().describe('Case-sensitive matching'),
+      normalizeWhitespace: z.boolean().optional().describe('Collapse whitespace while matching'),
+      all: z.boolean().optional().describe('Return all matches instead of just one'),
+      failEmpty: z.boolean().optional().describe('Treat no matches as an error instead of returning an empty result'),
+      tab: z.string().optional().describe('Target a specific tab by title or ID'),
+      account: accountParam,
+    },
+  }, async ({ docId, text, occurrence, matchCase, normalizeWhitespace, all, failEmpty, tab, account }) => {
+    const args = ['docs', 'find-range', docId, text];
+    if (occurrence !== undefined) args.push(`--occurrence=${occurrence}`);
+    if (matchCase) args.push('--match-case');
+    if (normalizeWhitespace) args.push('--normalize-whitespace');
+    if (all) args.push('--all');
+    if (failEmpty) args.push('--fail-empty');
+    if (tab) args.push(`--tab=${tab}`);
+    return runOrDiagnose(args, { account });
+  });
+
   server.registerTool('gog_docs_table_column_width', {
     description: 'Set a fixed width (in points) for a table column, or reset columns to Docs-managed even distribution. Target the table by 1-based index in document order (negative counts from the end) and the column by 1-based number. Pass evenlyDistributed without col to reset every column in the table.',
     annotations: { destructiveHint: true },
@@ -401,13 +471,19 @@ export function registerExtraDocsTools(server: McpServer): void {
       docId: z.string().describe('Doc ID (from the URL)'),
       index: z.number().int().optional().describe('Character index to insert at (1 = beginning). Omit or use atEnd for end-of-doc.'),
       atEnd: z.boolean().optional().describe('Insert at end-of-doc/tab (mutually exclusive with index)'),
+      at: z.string().optional().describe('Anchor by literal text and insert the page break at the start of the matched range, instead of an index.'),
+      occurrence: z.number().int().optional().describe('Use the Nth `at` match (1-based; required when `at` is ambiguous)'),
+      matchCase: z.boolean().optional().describe('Case-sensitive `at` matching'),
       tab: z.string().optional().describe('Target a specific tab by title or ID'),
       account: accountParam,
     },
-  }, async ({ docId, index, atEnd, tab, account }) => {
+  }, async ({ docId, index, atEnd, at, occurrence, matchCase, tab, account }) => {
     const args = ['docs', 'insert-page-break', docId];
     if (index !== undefined) args.push(`--index=${index}`);
     if (atEnd) args.push('--at-end');
+    if (at) args.push(`--at=${at}`);
+    if (occurrence !== undefined) args.push(`--occurrence=${occurrence}`);
+    if (matchCase) args.push('--match-case');
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
   });
@@ -555,13 +631,19 @@ export function registerExtraDocsTools(server: McpServer): void {
       email: z.string().describe('Email address for the person chip'),
       index: z.number().int().optional().describe('Character index to insert at. Omit or use atEnd for end-of-doc.'),
       atEnd: z.boolean().optional().describe('Insert at end-of-doc/tab (mutually exclusive with index)'),
+      at: z.string().optional().describe('Anchor by literal text, delete the match, and insert the person chip there, instead of an index.'),
+      occurrence: z.number().int().optional().describe('Use the Nth `at` match (1-based; required when `at` is ambiguous)'),
+      matchCase: z.boolean().optional().describe('Case-sensitive `at` matching'),
       tab: z.string().optional().describe('Target a specific tab by title or ID'),
       account: accountParam,
     },
-  }, async ({ docId, email, index, atEnd, tab, account }) => {
+  }, async ({ docId, email, index, atEnd, at, occurrence, matchCase, tab, account }) => {
     const args = ['docs', 'insert-person', docId, `--email=${email}`];
     if (index !== undefined) args.push(`--index=${index}`);
     if (atEnd) args.push('--at-end');
+    if (at) args.push(`--at=${at}`);
+    if (occurrence !== undefined) args.push(`--occurrence=${occurrence}`);
+    if (matchCase) args.push('--match-case');
     if (tab) args.push(`--tab=${tab}`);
     return runOrDiagnose(args, { account });
   });

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

@@ -63,6 +63,17 @@ describe('gog_docs_delete', () => {
     );
   });
 
+  // gog 0.23.0
+  it('anchors by text with --at/--occurrence/--match-case', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_delete')!({ docId: 'abc', at: 'TODO', occurrence: 2, matchCase: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'delete', 'abc', '--at=TODO', '--occurrence=2', '--match-case'],
+      { account: undefined },
+    );
+  });
+
   it('includes --tab-id when provided', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
     const handlers = setupHandlers();
@@ -179,6 +190,17 @@ describe('gog_docs_insert', () => {
     );
   });
 
+  // gog 0.23.0
+  it('anchors by text with --at/--occurrence/--match-case', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_insert')!({ docId: 'abc', content: 'X', at: 'HERE', occurrence: 3, matchCase: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'insert', 'abc', 'X', '--at=HERE', '--occurrence=3', '--match-case'],
+      { account: undefined },
+    );
+  });
+
   it('includes --index when provided', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
     const handlers = setupHandlers();
@@ -312,6 +334,17 @@ describe('gog_docs_update', () => {
     );
   });
 
+  // gog 0.23.0
+  it('anchors by text with --at/--occurrence/--match-case', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_update')!({ docId: 'abc', text: 'New', at: 'OLD', occurrence: 1, matchCase: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'update', 'abc', '--text=New', '--at=OLD', '--occurrence=1', '--match-case'],
+      { account: undefined },
+    );
+  });
+
   it('includes --file when provided', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
     const handlers = setupHandlers();
@@ -495,6 +528,47 @@ describe('gog_docs_table_column_width', () => {
   });
 });
 
+// gog 0.23.0
+describe('gog_docs_find_range', () => {
+  it('maps matched text to index ranges', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_find_range')!({ docId: 'd1', text: 'hello' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'find-range', 'd1', 'hello'], { account: undefined });
+  });
+
+  it('passes all match flags', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_find_range')!({
+      docId: 'd1', text: 'hello', occurrence: 2, matchCase: true, normalizeWhitespace: true, all: true, failEmpty: true, tab: 'T',
+    });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'find-range', 'd1', 'hello', '--occurrence=2', '--match-case', '--normalize-whitespace', '--all', '--fail-empty', '--tab=T'],
+      { account: undefined },
+    );
+  });
+});
+
+describe('gog_docs_comments_locate', () => {
+  it('locates a comment by id', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_comments_locate')!({ docId: 'd1', commentId: 'c1' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(['docs', 'comments', 'locate', 'd1', 'c1'], { account: undefined });
+  });
+
+  it('passes match flags', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_comments_locate')!({ docId: 'd1', commentId: 'c1', matchCase: true, normalizeWhitespace: true, tab: 'T' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'comments', 'locate', 'd1', 'c1', '--match-case', '--normalize-whitespace', '--tab=T'],
+      { account: undefined },
+    );
+  });
+});
+
 describe('gog_docs_comments_get', () => {
   it('calls runOrDiagnose with correct args', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
@@ -776,6 +850,27 @@ describe('gog_docs_format', () => {
       { account: undefined },
     );
   });
+
+  // gog 0.23.0
+  it('sets a hyperlink with --link', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_format')!({ docId: 'd1', match: 'see docs', link: 'https://example.com' });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'format', 'd1', '--match=see docs', '--link=https://example.com'],
+      { account: undefined },
+    );
+  });
+
+  it('clears a hyperlink with --no-link', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_format')!({ docId: 'd1', match: 'linked', noLink: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'format', 'd1', '--match=linked', '--no-link'],
+      { account: undefined },
+    );
+  });
 });
 
 // --- gog 0.18.0 new tools ---
@@ -791,6 +886,17 @@ describe('gog_docs_insert_page_break', () => {
     );
   });
 
+  // gog 0.23.0
+  it('anchors by text with --at/--occurrence/--match-case', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_insert_page_break')!({ docId: 'd1', at: 'Chapter 2', occurrence: 1, matchCase: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'insert-page-break', 'd1', '--at=Chapter 2', '--occurrence=1', '--match-case'],
+      { account: undefined },
+    );
+  });
+
   it('uses --at-end when atEnd is true', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
     const handlers = setupHandlers();
@@ -955,6 +1061,17 @@ describe('gog_docs_insert_person', () => {
     );
   });
 
+  // gog 0.23.0
+  it('anchors by text with --at/--occurrence/--match-case', async () => {
+    vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_insert_person')!({ docId: 'd1', email: 'a@b.com', at: '@alice', occurrence: 1, matchCase: true });
+    expect(lib.runOrDiagnose).toHaveBeenCalledWith(
+      ['docs', 'insert-person', 'd1', '--email=a@b.com', '--at=@alice', '--occurrence=1', '--match-case'],
+      { account: undefined },
+    );
+  });
+
   it('passes --index, --at-end and --tab', async () => {
     vi.mocked(lib.runOrDiagnose).mockResolvedValue(toText('{}'));
     const handlers = setupHandlers();