gogcli-mcp 1.0.3 → 1.0.5

package/.mcp.json

@@ -6,8 +6,7 @@
       "cwd": "/Users/chris/git/gogcli-mcp",
       "env": {
         "GOG_ACCOUNT": "${GOG_ACCOUNT}",
-        "GOG_PATH": "${GOG_PATH}",
-        "GOG_ACCESS_TOKEN": "${GOG_ACCESS_TOKEN}"
+        "GOG_PATH": "${GOG_PATH}"
       }
     }
   }

package/CLAUDE.md

@@ -31,7 +31,7 @@ Main is always one version ahead of the latest tag. To release, run the **Tag &
 4. Rebuilds, commits, and pushes main + tag
 5. The tag push triggers the **Release** workflow (CI + npm publish + .mcpb + .skill + GitHub release)
 
-Do NOT manually bump versions or create tags unless the user explicitly asks.
+Do NOT manually bump versions or create tags unless the user explicitly asks. Always prefer the Tag & Bump action: `gh workflow run tag-and-bump.yml --ref main`. The action handles all four version files, tagging, and triggering the release.
 
 ## Architecture
 

package/dist/index.js

@@ -30137,9 +30137,10 @@ async function run(args, options = {}) {
   fullArgs.push(...args);
   const effectiveTimeout = timeout ?? TIMEOUT_MS;
   return new Promise((resolve, reject) => {
-    const child = spawner(process.env.GOG_PATH ?? "gog", fullArgs, { env: process.env });
-    let stdout = "";
-    let stderr = "";
+    const { GOG_ACCESS_TOKEN: _, ...cleanEnv } = process.env;
+    const child = spawner(process.env.GOG_PATH ?? "gog", fullArgs, { env: cleanEnv });
+    const stdoutChunks = [];
+    const stderrChunks = [];
     let settled = false;
     const timer = setTimeout(() => {
       settled = true;
@@ -30147,23 +30148,25 @@ async function run(args, options = {}) {
       reject(new Error(`gog timed out after ${formatTimeout(effectiveTimeout)}`));
     }, effectiveTimeout);
     child.stdout.on("data", (chunk) => {
-      stdout += chunk.toString();
+      stdoutChunks.push(chunk);
     });
     child.stderr.on("data", (chunk) => {
-      stderr += chunk.toString();
+      stderrChunks.push(chunk);
     });
     child.on("close", (code) => {
       clearTimeout(timer);
       if (settled) return;
       settled = true;
+      const stdout = Buffer.concat(stdoutChunks).toString();
+      const stderr = Buffer.concat(stderrChunks).toString().trim();
       if (code === 0) {
-        if (interactive && stderr.trim()) {
+        if (interactive && stderr) {
           resolve(stdout + "\n" + stderr);
         } else {
           resolve(stdout);
         }
       } else {
-        reject(new Error(stderr.trim() || `gog exited with code ${code}`));
+        reject(new Error(stderr || `gog exited with code ${code}`));
       }
     });
     child.on("error", (err) => {
@@ -30185,19 +30188,24 @@ function toText(output) {
 function toError(err) {
   return toText(err instanceof Error ? `Error: ${err.message}` : String(err));
 }
+var AUTH_ERROR_PATTERN = /\b(401|unauthorized|token.*(expired|revoked)|invalid_grant)\b/i;
+var AUTH_HINT = "\n\nAuthentication may have expired. Use gog_auth_add to re-authorize the account. Ask the user if they would like to re-authenticate.";
 async function runOrDiagnose(args, options) {
   try {
     return toText(await run(args, options));
   } catch (err) {
     const base = toError(err);
+    const errText = base.content[0].text;
+    const isAuthError = AUTH_ERROR_PATTERN.test(errText);
+    const hint = isAuthError ? AUTH_HINT : "";
     try {
       const accounts = await run(["auth", "list"]);
-      return toText(`${base.content[0].text}
+      return toText(`${errText}
 
 Configured accounts:
-${accounts}`);
+${accounts}${hint}`);
     } catch {
-      return base;
+      return toText(`${errText}${hint}`);
     }
   }
 }
@@ -30264,11 +30272,7 @@ function registerAuthTools(server2) {
       args: external_exports3.array(external_exports3.string()).describe("Additional positional args and flags")
     }
   }, async ({ subcommand, args }) => {
-    try {
-      return toText(await run(["auth", subcommand, ...args]));
-    } catch (err) {
-      return toError(err);
-    }
+    return runOrDiagnose(["auth", subcommand, ...args], {});
   });
 }
 
@@ -30481,7 +30485,6 @@ function registerDocsTools(server2) {
   });
   server2.registerTool("gog_docs_create", {
     description: "Create a new Google Doc. Returns JSON with the new docId and URL.",
-    annotations: { destructiveHint: false },
     inputSchema: {
       title: external_exports3.string().describe("Title for the new document"),
       account: accountParam
@@ -30525,6 +30528,79 @@ function registerDocsTools(server2) {
   }, async ({ docId, account }) => {
     return runOrDiagnose(["docs", "structure", docId], { account });
   });
+  server2.registerTool("gog_docs_comments_list", {
+    description: "List comments on a Google Doc. Returns open comments by default; set includeResolved=true to include resolved comments.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      docId: external_exports3.string().describe("Doc ID (from the URL)"),
+      includeResolved: external_exports3.boolean().optional().describe("Include resolved comments (default: false, open only)"),
+      account: accountParam
+    }
+  }, async ({ docId, includeResolved, account }) => {
+    const args = ["docs", "comments", "list", docId];
+    if (includeResolved) args.push("--include-resolved");
+    return runOrDiagnose(args, { account });
+  });
+  server2.registerTool("gog_docs_comments_get", {
+    description: "Get a single comment by ID, including its replies.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      docId: external_exports3.string().describe("Doc ID (from the URL)"),
+      commentId: external_exports3.string().describe("Comment ID"),
+      account: accountParam
+    }
+  }, async ({ docId, commentId, account }) => {
+    return runOrDiagnose(["docs", "comments", "get", docId, commentId], { account });
+  });
+  server2.registerTool("gog_docs_comments_add", {
+    description: "Add a comment to a Google Doc. Optionally attach quoted text that appears as the highlighted passage in the Google Docs UI.",
+    inputSchema: {
+      docId: external_exports3.string().describe("Doc ID (from the URL)"),
+      content: external_exports3.string().describe("Comment text"),
+      quoted: external_exports3.string().optional().describe("Quoted text to attach to the comment (shown in UIs when available)"),
+      account: accountParam
+    }
+  }, async ({ docId, content, quoted, account }) => {
+    const args = ["docs", "comments", "add", docId, content];
+    if (quoted) args.push(`--quoted=${quoted}`);
+    return runOrDiagnose(args, { account });
+  });
+  server2.registerTool("gog_docs_comments_reply", {
+    description: "Reply to an existing comment on a Google Doc.",
+    inputSchema: {
+      docId: external_exports3.string().describe("Doc ID (from the URL)"),
+      commentId: external_exports3.string().describe("Comment ID to reply to"),
+      content: external_exports3.string().describe("Reply text"),
+      account: accountParam
+    }
+  }, async ({ docId, commentId, content, account }) => {
+    return runOrDiagnose(["docs", "comments", "reply", docId, commentId, content], { account });
+  });
+  server2.registerTool("gog_docs_comments_resolve", {
+    description: "Resolve a comment (mark as done). Optionally include a closing message.",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: external_exports3.string().describe("Doc ID (from the URL)"),
+      commentId: external_exports3.string().describe("Comment ID to resolve"),
+      message: external_exports3.string().optional().describe("Optional message to include when resolving"),
+      account: accountParam
+    }
+  }, async ({ docId, commentId, message, account }) => {
+    const args = ["docs", "comments", "resolve", docId, commentId];
+    if (message) args.push(`--message=${message}`);
+    return runOrDiagnose(args, { account });
+  });
+  server2.registerTool("gog_docs_comments_delete", {
+    description: "Delete a comment from a Google Doc. This action is permanent.",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: external_exports3.string().describe("Doc ID (from the URL)"),
+      commentId: external_exports3.string().describe("Comment ID to delete"),
+      account: accountParam
+    }
+  }, async ({ docId, commentId, account }) => {
+    return runOrDiagnose(["docs", "comments", "delete", docId, commentId], { 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 },
@@ -30890,7 +30966,7 @@ function registerTasksTools(server2) {
 }
 
 // src/index.ts
-var server = new McpServer({ name: "gogcli", version: "1.0.3" });
+var server = new McpServer({ name: "gogcli", version: "1.0.5" });
 registerAuthTools(server);
 registerCalendarTools(server);
 registerContactsTools(server);

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",
@@ -37,8 +37,7 @@
       ],
       "env": {
         "GOG_ACCOUNT": "${user_config.gog_account}",
-        "GOG_PATH": "${user_config.gog_path}",
-        "GOG_ACCESS_TOKEN": "${user_config.gog_access_token}"
+        "GOG_PATH": "${user_config.gog_path}"
       }
     }
   },
@@ -54,13 +53,6 @@
       "title": "gog Executable Path",
       "description": "Path to the gog executable (optional — defaults to 'gog' on your PATH)",
       "required": false
-    },
-    "gog_access_token": {
-      "type": "string",
-      "title": "Google Access Token",
-      "description": "Short-lived OAuth access token (optional — bypasses stored refresh tokens, expires in ~1h). Useful for CI or automated contexts.",
-      "required": false,
-      "sensitive": true
     }
   },
   "tools": [
@@ -236,6 +228,30 @@
       "name": "gog_docs_structure",
       "description": "Show document structure with numbered paragraphs"
     },
+    {
+      "name": "gog_docs_comments_list",
+      "description": "List comments on a Google Doc"
+    },
+    {
+      "name": "gog_docs_comments_get",
+      "description": "Get a single comment by ID with replies"
+    },
+    {
+      "name": "gog_docs_comments_add",
+      "description": "Add a comment to a Google Doc"
+    },
+    {
+      "name": "gog_docs_comments_reply",
+      "description": "Reply to a comment on a Google Doc"
+    },
+    {
+      "name": "gog_docs_comments_resolve",
+      "description": "Resolve (mark as done) a comment on a Google Doc"
+    },
+    {
+      "name": "gog_docs_comments_delete",
+      "description": "Delete a comment from a Google Doc"
+    },
     {
       "name": "gog_docs_run",
       "description": "Run any gog docs subcommand (escape hatch)"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "MCP server wrapping gogcli for Google service access",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -10,7 +10,7 @@ import { registerGmailTools } from './tools/gmail.js';
 import { registerSheetsTools } from './tools/sheets.js';
 import { registerTasksTools } from './tools/tasks.js';
 
-const server = new McpServer({ name: 'gogcli', version: '1.0.3' });
+const server = new McpServer({ name: 'gogcli', version: '1.0.5' });
 
 registerAuthTools(server);
 registerCalendarTools(server);

package/src/runner.ts

@@ -42,9 +42,12 @@ export async function run(args: string[], options: RunOptions = {}): Promise<str
   const effectiveTimeout = timeout ?? TIMEOUT_MS;
 
   return new Promise((resolve, reject) => {
-    const child = spawner(process.env.GOG_PATH ?? 'gog', fullArgs, { env: process.env });
-    let stdout = '';
-    let stderr = '';
+    // Strip GOG_ACCESS_TOKEN so gogcli uses stored refresh tokens instead of
+    // a potentially stale direct access token passed through MCP env config.
+    const { GOG_ACCESS_TOKEN: _, ...cleanEnv } = process.env;
+    const child = spawner(process.env.GOG_PATH ?? 'gog', fullArgs, { env: cleanEnv });
+    const stdoutChunks: Buffer[] = [];
+    const stderrChunks: Buffer[] = [];
     let settled = false;
 
     const timer = setTimeout(() => {
@@ -53,21 +56,23 @@ export async function run(args: string[], options: RunOptions = {}): Promise<str
       reject(new Error(`gog timed out after ${formatTimeout(effectiveTimeout)}`));
     }, effectiveTimeout);
 
-    child.stdout!.on('data', (chunk: Buffer) => { stdout += chunk.toString(); });
-    child.stderr!.on('data', (chunk: Buffer) => { stderr += chunk.toString(); });
+    child.stdout!.on('data', (chunk: Buffer) => { stdoutChunks.push(chunk); });
+    child.stderr!.on('data', (chunk: Buffer) => { stderrChunks.push(chunk); });
 
     child.on('close', (code: number | null) => {
       clearTimeout(timer);
       if (settled) return;
       settled = true;
+      const stdout = Buffer.concat(stdoutChunks).toString();
+      const stderr = Buffer.concat(stderrChunks).toString().trim();
       if (code === 0) {
-        if (interactive && stderr.trim()) {
+        if (interactive && stderr) {
           resolve(stdout + '\n' + stderr);
         } else {
           resolve(stdout);
         }
       } else {
-        reject(new Error(stderr.trim() || `gog exited with code ${code}`));
+        reject(new Error(stderr || `gog exited with code ${code}`));
       }
     });
 

package/src/tools/auth.ts

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { run } from '../runner.js';
-import { toText, toError } from './utils.js';
+import { toText, toError, runOrDiagnose } from './utils.js';
 
 export function registerAuthTools(server: McpServer): void {
   server.registerTool('gog_auth_list', {
@@ -73,10 +73,6 @@ export function registerAuthTools(server: McpServer): void {
       args: z.array(z.string()).describe('Additional positional args and flags'),
     },
   }, async ({ subcommand, args }) => {
-    try {
-      return toText(await run(['auth', subcommand, ...args]));
-    } catch (err) {
-      return toError(err);
-    }
+    return runOrDiagnose(['auth', subcommand, ...args], {});
   });
 }

package/src/tools/docs.ts

@@ -27,7 +27,6 @@ export function registerDocsTools(server: McpServer): void {
 
   server.registerTool('gog_docs_create', {
     description: 'Create a new Google Doc. Returns JSON with the new docId and URL.',
-    annotations: { destructiveHint: false },
     inputSchema: {
       title: z.string().describe('Title for the new document'),
       account: accountParam,
@@ -75,6 +74,89 @@ export function registerDocsTools(server: McpServer): void {
     return runOrDiagnose(['docs', 'structure', docId], { account });
   });
 
+  // --- Comments 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.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      includeResolved: z.boolean().optional().describe('Include resolved comments (default: false, open only)'),
+      account: accountParam,
+    },
+  }, async ({ docId, includeResolved, account }) => {
+    const args = ['docs', 'comments', 'list', docId];
+    if (includeResolved) args.push('--include-resolved');
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_docs_comments_get', {
+    description: 'Get a single comment by ID, including its replies.',
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      commentId: z.string().describe('Comment ID'),
+      account: accountParam,
+    },
+  }, async ({ docId, commentId, account }) => {
+    return runOrDiagnose(['docs', 'comments', 'get', docId, commentId], { account });
+  });
+
+  server.registerTool('gog_docs_comments_add', {
+    description:
+      'Add a comment to a Google Doc. Optionally attach quoted text that appears as the highlighted passage in the Google Docs UI.',
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      content: z.string().describe('Comment text'),
+      quoted: z.string().optional().describe('Quoted text to attach to the comment (shown in UIs when available)'),
+      account: accountParam,
+    },
+  }, async ({ docId, content, quoted, account }) => {
+    const args = ['docs', 'comments', 'add', docId, content];
+    if (quoted) args.push(`--quoted=${quoted}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_docs_comments_reply', {
+    description: 'Reply to an existing comment on a Google Doc.',
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      commentId: z.string().describe('Comment ID to reply to'),
+      content: z.string().describe('Reply text'),
+      account: accountParam,
+    },
+  }, async ({ docId, commentId, content, account }) => {
+    return runOrDiagnose(['docs', 'comments', 'reply', docId, commentId, content], { account });
+  });
+
+  server.registerTool('gog_docs_comments_resolve', {
+    description: 'Resolve a comment (mark as done). Optionally include a closing message.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      commentId: z.string().describe('Comment ID to resolve'),
+      message: z.string().optional().describe('Optional message to include when resolving'),
+      account: accountParam,
+    },
+  }, async ({ docId, commentId, message, account }) => {
+    const args = ['docs', 'comments', 'resolve', docId, commentId];
+    if (message) args.push(`--message=${message}`);
+    return runOrDiagnose(args, { account });
+  });
+
+  server.registerTool('gog_docs_comments_delete', {
+    description: 'Delete a comment from a Google Doc. This action is permanent.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      docId: z.string().describe('Doc ID (from the URL)'),
+      commentId: z.string().describe('Comment ID to delete'),
+      account: accountParam,
+    },
+  }, async ({ docId, commentId, account }) => {
+    return runOrDiagnose(['docs', 'comments', 'delete', docId, commentId], { account });
+  });
+
   server.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 },

package/src/tools/utils.ts

@@ -15,8 +15,12 @@ export function toError(err: unknown): ToolResult {
   return toText(err instanceof Error ? `Error: ${err.message}` : String(err));
 }
 
-// On failure, appends `gog auth list` output so Claude can see which accounts
-// are configured and suggest the right one.
+const AUTH_ERROR_PATTERN = /\b(401|unauthorized|token.*(expired|revoked)|invalid_grant)\b/i;
+
+const AUTH_HINT =
+  '\n\nAuthentication may have expired. Use gog_auth_add to re-authorize the account. ' +
+  'Ask the user if they would like to re-authenticate.';
+
 export async function runOrDiagnose(
   args: string[],
   options: { account?: string },
@@ -25,11 +29,14 @@ export async function runOrDiagnose(
     return toText(await run(args, options));
   } catch (err) {
     const base = toError(err);
+    const errText = base.content[0].text;
+    const isAuthError = AUTH_ERROR_PATTERN.test(errText);
+    const hint = isAuthError ? AUTH_HINT : '';
     try {
       const accounts = await run(['auth', 'list']);
-      return toText(`${base.content[0].text}\n\nConfigured accounts:\n${accounts}`);
+      return toText(`${errText}\n\nConfigured accounts:\n${accounts}${hint}`);
     } catch {
-      return base;
+      return toText(`${errText}${hint}`);
     }
   }
 }

package/tests/runner.test.ts

@@ -300,6 +300,23 @@ describe('run', () => {
     vi.useRealTimers();
   });
 
+  it('strips GOG_ACCESS_TOKEN from child environment to force refresh-token auth', async () => {
+    const spawner = makeSpawner(0, '{}');
+    const originalToken = process.env.GOG_ACCESS_TOKEN;
+    process.env.GOG_ACCESS_TOKEN = 'stale-token-from-mcp-config';
+    try {
+      await run(['docs', 'comments', 'list', 'docId'], { spawner });
+      const envPassed = (spawner as ReturnType<typeof vi.fn>).mock.calls[0][2].env as NodeJS.ProcessEnv;
+      expect(envPassed.GOG_ACCESS_TOKEN).toBeUndefined();
+    } finally {
+      if (originalToken === undefined) {
+        delete process.env.GOG_ACCESS_TOKEN;
+      } else {
+        process.env.GOG_ACCESS_TOKEN = originalToken;
+      }
+    }
+  });
+
   it('ignores timeout if close event already settled the promise', async () => {
     vi.useFakeTimers();
     const spawner = vi.fn(() => {

package/tests/tools/auth.test.ts

@@ -121,7 +121,7 @@ describe('gog_auth_run', () => {
     vi.mocked(runner.run).mockResolvedValue('removed user@gmail.com');
     const handlers = setupHandlers();
     const result = await handlers.get('gog_auth_run')!({ subcommand: 'remove', args: ['user@gmail.com'] });
-    expect(runner.run).toHaveBeenCalledWith(['auth', 'remove', 'user@gmail.com']);
+    expect(runner.run).toHaveBeenCalledWith(['auth', 'remove', 'user@gmail.com'], {});
     expect(result.content[0].text).toBe('removed user@gmail.com');
   });
 
@@ -129,7 +129,7 @@ describe('gog_auth_run', () => {
     vi.mocked(runner.run).mockResolvedValue('token info');
     const handlers = setupHandlers();
     await handlers.get('gog_auth_run')!({ subcommand: 'tokens', args: [] });
-    expect(runner.run).toHaveBeenCalledWith(['auth', 'tokens']);
+    expect(runner.run).toHaveBeenCalledWith(['auth', 'tokens'], {});
   });
 
   it('returns error text on failure', async () => {

package/tests/tools/docs.test.ts

@@ -161,6 +161,193 @@ describe('gog_docs_structure', () => {
   });
 });
 
+// --- Comments tools ---
+
+describe('gog_docs_comments_list', () => {
+  it('calls run with correct args for open comments', async () => {
+    vi.mocked(runner.run).mockResolvedValue('[{"id":"c1","content":"Fix this"}]');
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_docs_comments_list')!({ docId: 'abc' });
+    expect(runner.run).toHaveBeenCalledWith(['docs', 'comments', 'list', 'abc'], { account: undefined });
+    expect(result.content[0].text).toContain('Fix this');
+  });
+
+  it('includes --include-resolved when set', async () => {
+    vi.mocked(runner.run).mockResolvedValue('[]');
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_comments_list')!({ docId: 'abc', includeResolved: true });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['docs', 'comments', 'list', 'abc', '--include-resolved'],
+      { account: undefined },
+    );
+  });
+
+  it('omits --include-resolved when false', async () => {
+    vi.mocked(runner.run).mockResolvedValue('[]');
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_comments_list')!({ docId: 'abc', includeResolved: false });
+    expect(runner.run).toHaveBeenCalledWith(['docs', 'comments', 'list', 'abc'], { account: undefined });
+  });
+
+  it('forwards account override', async () => {
+    vi.mocked(runner.run).mockResolvedValue('[]');
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_comments_list')!({ docId: 'abc', account: 'other@gmail.com' });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['docs', 'comments', 'list', 'abc'],
+      { account: 'other@gmail.com' },
+    );
+  });
+
+  it('returns error text on failure', async () => {
+    vi.mocked(runner.run).mockRejectedValue(new Error('List failed'));
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_docs_comments_list')!({ docId: 'bad' });
+    expect(result.content[0].text).toContain('Error: List failed');
+  });
+});
+
+describe('gog_docs_comments_get', () => {
+  it('calls run with correct args', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"id":"c1","content":"Fix this","replies":[]}');
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_docs_comments_get')!({ docId: 'abc', commentId: 'c1' });
+    expect(runner.run).toHaveBeenCalledWith(['docs', 'comments', 'get', 'abc', 'c1'], { account: undefined });
+    expect(result.content[0].text).toContain('Fix this');
+  });
+
+  it('returns error text on failure', async () => {
+    vi.mocked(runner.run).mockRejectedValue(new Error('Not found'));
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_docs_comments_get')!({ docId: 'abc', commentId: 'bad' });
+    expect(result.content[0].text).toContain('Error: Not found');
+  });
+});
+
+describe('gog_docs_comments_add', () => {
+  it('calls run with content', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"id":"c2"}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_comments_add')!({ docId: 'abc', content: 'Please review' });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['docs', 'comments', 'add', 'abc', 'Please review'],
+      { account: undefined },
+    );
+  });
+
+  it('includes --quoted when provided', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"id":"c2"}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_comments_add')!({
+      docId: 'abc',
+      content: 'Typo here',
+      quoted: 'teh',
+    });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['docs', 'comments', 'add', 'abc', 'Typo here', '--quoted=teh'],
+      { account: undefined },
+    );
+  });
+
+  it('omits --quoted when not provided', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"id":"c2"}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_comments_add')!({ docId: 'abc', content: 'Nice' });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['docs', 'comments', 'add', 'abc', 'Nice'],
+      { account: undefined },
+    );
+  });
+
+  it('returns error text on failure', async () => {
+    vi.mocked(runner.run).mockRejectedValue(new Error('Add failed'));
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_docs_comments_add')!({ docId: 'bad', content: 'x' });
+    expect(result.content[0].text).toContain('Error: Add failed');
+  });
+});
+
+describe('gog_docs_comments_reply', () => {
+  it('calls run with correct args', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"id":"r1"}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_comments_reply')!({ docId: 'abc', commentId: 'c1', content: 'Done' });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['docs', 'comments', 'reply', 'abc', 'c1', 'Done'],
+      { account: undefined },
+    );
+  });
+
+  it('returns error text on failure', async () => {
+    vi.mocked(runner.run).mockRejectedValue(new Error('Reply failed'));
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_docs_comments_reply')!({
+      docId: 'abc', commentId: 'c1', content: 'x',
+    });
+    expect(result.content[0].text).toContain('Error: Reply failed');
+  });
+});
+
+describe('gog_docs_comments_resolve', () => {
+  it('calls run with correct args', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_comments_resolve')!({ docId: 'abc', commentId: 'c1' });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['docs', 'comments', 'resolve', 'abc', 'c1'],
+      { account: undefined },
+    );
+  });
+
+  it('includes --message when provided', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_comments_resolve')!({
+      docId: 'abc', commentId: 'c1', message: 'Fixed in v2',
+    });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['docs', 'comments', 'resolve', 'abc', 'c1', '--message=Fixed in v2'],
+      { account: undefined },
+    );
+  });
+
+  it('omits --message when not provided', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_comments_resolve')!({ docId: 'abc', commentId: 'c1' });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['docs', 'comments', 'resolve', 'abc', 'c1'],
+      { account: undefined },
+    );
+  });
+
+  it('returns error text on failure', async () => {
+    vi.mocked(runner.run).mockRejectedValue(new Error('Resolve failed'));
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_docs_comments_resolve')!({ docId: 'abc', commentId: 'c1' });
+    expect(result.content[0].text).toContain('Error: Resolve failed');
+  });
+});
+
+describe('gog_docs_comments_delete', () => {
+  it('calls run with correct args', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{}');
+    const handlers = setupHandlers();
+    await handlers.get('gog_docs_comments_delete')!({ docId: 'abc', commentId: 'c1' });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['docs', 'comments', 'delete', 'abc', 'c1'],
+      { account: undefined },
+    );
+  });
+
+  it('returns error text on failure', async () => {
+    vi.mocked(runner.run).mockRejectedValue(new Error('Delete failed'));
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_docs_comments_delete')!({ docId: 'abc', commentId: 'c1' });
+    expect(result.content[0].text).toContain('Error: Delete failed');
+  });
+});
+
 describe('gog_docs_run', () => {
   it('passes raw subcommand and args to runner', async () => {
     vi.mocked(runner.run).mockResolvedValue('{}');

package/tests/tools/utils.test.ts

@@ -0,0 +1,79 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import * as runner from '../../src/runner.js';
+import { runOrDiagnose } from '../../src/tools/utils.js';
+
+vi.mock('../../src/runner.js');
+
+beforeEach(() => vi.clearAllMocks());
+
+describe('runOrDiagnose', () => {
+  it('returns output text on success', async () => {
+    vi.mocked(runner.run).mockResolvedValue('{"ok":true}');
+    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    expect(result.content[0].text).toBe('{"ok":true}');
+  });
+
+  it('appends auth list on non-auth failure', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('Doc not found'))
+      .mockResolvedValueOnce('user@gmail.com');
+    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    expect(result.content[0].text).toBe(
+      'Error: Doc not found\n\nConfigured accounts:\nuser@gmail.com',
+    );
+    expect(result.content[0].text).not.toContain('gog_auth_add');
+  });
+
+  it('appends re-auth hint on 401 error', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('Request failed with status 401'))
+      .mockResolvedValueOnce('user@gmail.com');
+    const result = await runOrDiagnose(['docs', 'comments', 'list', 'abc'], {});
+    expect(result.content[0].text).toContain('Error: Request failed with status 401');
+    expect(result.content[0].text).toContain('Configured accounts:\nuser@gmail.com');
+    expect(result.content[0].text).toContain('gog_auth_add');
+  });
+
+  it('appends re-auth hint on "unauthorized" error', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('unauthorized access'))
+      .mockResolvedValueOnce('user@gmail.com');
+    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    expect(result.content[0].text).toContain('gog_auth_add');
+  });
+
+  it('appends re-auth hint on "token expired" error', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('token has been expired or revoked'))
+      .mockResolvedValueOnce('user@gmail.com');
+    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    expect(result.content[0].text).toContain('gog_auth_add');
+  });
+
+  it('appends re-auth hint on "invalid_grant" error', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('invalid_grant'))
+      .mockResolvedValueOnce('user@gmail.com');
+    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    expect(result.content[0].text).toContain('gog_auth_add');
+  });
+
+  it('returns plain error with auth hint when auth list also fails on auth error', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('Request failed with status 401'))
+      .mockRejectedValueOnce(new Error('auth list failed'));
+    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    expect(result.content[0].text).toContain('Error: Request failed with status 401');
+    expect(result.content[0].text).toContain('gog_auth_add');
+    expect(result.content[0].text).not.toContain('Configured accounts');
+  });
+
+  it('returns plain error when auth list also fails on non-auth error', async () => {
+    vi.mocked(runner.run)
+      .mockRejectedValueOnce(new Error('Doc not found'))
+      .mockRejectedValueOnce(new Error('auth list failed'));
+    const result = await runOrDiagnose(['docs', 'cat', 'abc'], {});
+    expect(result.content[0].text).toBe('Error: Doc not found');
+    expect(result.content[0].text).not.toContain('gog_auth_add');
+  });
+});