gogcli-mcp 1.0.2 → 1.0.3

package/dist/index.js

@@ -30116,14 +30116,26 @@ var StdioServerTransport = class {
 // src/runner.ts
 import { spawn } from "node:child_process";
 var TIMEOUT_MS = 3e4;
+function formatTimeout(ms) {
+  const seconds = Math.round(ms / 1e3);
+  if (seconds >= 60) {
+    const minutes = Math.round(seconds / 60);
+    return `${ms}ms (${minutes} minute${minutes !== 1 ? "s" : ""})`;
+  }
+  return `${ms}ms`;
+}
 async function run(args, options = {}) {
-  const { account, spawner = spawn } = options;
+  const { account, spawner = spawn, interactive = false, timeout } = options;
   const effectiveAccount = account ?? process.env.GOG_ACCOUNT;
-  const fullArgs = ["--json", "--no-input", "--color=never"];
+  const fullArgs = ["--json", "--color=never"];
+  if (!interactive) {
+    fullArgs.push("--no-input");
+  }
   if (effectiveAccount) {
     fullArgs.push("--account", effectiveAccount);
   }
   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 = "";
@@ -30132,8 +30144,8 @@ async function run(args, options = {}) {
     const timer = setTimeout(() => {
       settled = true;
       child.kill();
-      reject(new Error(`gog timed out after ${TIMEOUT_MS}ms`));
-    }, TIMEOUT_MS);
+      reject(new Error(`gog timed out after ${formatTimeout(effectiveTimeout)}`));
+    }, effectiveTimeout);
     child.stdout.on("data", (chunk) => {
       stdout += chunk.toString();
     });
@@ -30145,7 +30157,11 @@ async function run(args, options = {}) {
       if (settled) return;
       settled = true;
       if (code === 0) {
-        resolve(stdout);
+        if (interactive && stderr.trim()) {
+          resolve(stdout + "\n" + stderr);
+        } else {
+          resolve(stdout);
+        }
       } else {
         reject(new Error(stderr.trim() || `gog exited with code ${code}`));
       }
@@ -30221,8 +30237,27 @@ function registerAuthTools(server2) {
       return toError(err);
     }
   });
+  server2.registerTool("gog_auth_add", {
+    description: "Authorize a Google account via browser-based OAuth. Opens a browser window where the user must sign in and grant access. Blocks for up to 5 minutes waiting for the user to complete authorization. If the browser does not open automatically, a fallback URL is included in the response. Use gog_auth_list to check which accounts are already configured.",
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      email: external_exports3.string().describe("Google account email to authorize"),
+      services: external_exports3.string().optional().default("all").describe(
+        'Services to authorize: "all" or comma-separated list (e.g. "sheets,gmail,calendar"). Default: "all"'
+      )
+    }
+  }, async ({ email: email3, services = "all" }) => {
+    try {
+      return toText(await run(["auth", "add", email3, "--services", services], {
+        interactive: true,
+        timeout: 3e5
+      }));
+    } catch (err) {
+      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: gog auth add requires interactive browser auth and cannot be completed over MCP \u2014 run it in your terminal instead: gog auth add <email> --services <service>",
+    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_exports3.string().describe('The gog auth subcommand, e.g. "remove", "alias", "tokens"'),
@@ -30855,7 +30890,7 @@ function registerTasksTools(server2) {
 }
 
 // src/index.ts
-var server = new McpServer({ name: "gogcli", version: "1.0.2" });
+var server = new McpServer({ name: "gogcli", version: "1.0.3" });
 registerAuthTools(server);
 registerCalendarTools(server);
 registerContactsTools(server);

package/docs/superpowers/plans/2026-04-13-browser-auth.md

@@ -0,0 +1,450 @@
+# Browser-Based Auth Flow Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a `gog_auth_add` MCP tool that opens the user's browser for Google OAuth and blocks until completion.
+
+**Architecture:** Extend `RunOptions` with `interactive` and `timeout` fields. Add a dedicated `gog_auth_add` tool that uses these options to run the blocking browser auth flow. Existing runner behavior is unchanged for all other tools.
+
+**Tech Stack:** TypeScript, vitest, zod, @modelcontextprotocol/sdk
+
+---
+
+### Task 1: Runner — add `interactive` option (skip `--no-input`)
+
+**Files:**
+- Modify: `src/runner.ts:4-5` (RunOptions interface)
+- Modify: `src/runner.ts:17-22` (run function)
+- Test: `tests/runner.test.ts`
+
+- [ ] **Step 1: Write the failing test for `interactive: true` omitting `--no-input`**
+
+Add to `tests/runner.test.ts` inside the existing `describe('run', ...)`:
+
+```ts
+it('omits --no-input when interactive is true', async () => {
+  const spawner = makeSpawner(0, '{"ok":true}');
+  await run(['auth', 'add', 'user@gmail.com'], { spawner, interactive: true });
+  const callArgs = (spawner as ReturnType<typeof vi.fn>).mock.calls[0][1] as string[];
+  expect(callArgs).toContain('--json');
+  expect(callArgs).toContain('--color=never');
+  expect(callArgs).not.toContain('--no-input');
+  expect(callArgs).toContain('auth');
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npm test -- --reporter=verbose -t "omits --no-input when interactive is true"`
+Expected: FAIL — `interactive` is not a recognized option yet, `--no-input` is still present.
+
+- [ ] **Step 3: Write the regression test for default (non-interactive) still including `--no-input`**
+
+Add to `tests/runner.test.ts`:
+
+```ts
+it('includes --no-input when interactive is not set', async () => {
+  const spawner = makeSpawner(0, '{"ok":true}');
+  await run(['sheets', 'get', 'id1', 'A1'], { spawner });
+  const callArgs = (spawner as ReturnType<typeof vi.fn>).mock.calls[0][1] as string[];
+  expect(callArgs).toContain('--no-input');
+});
+```
+
+- [ ] **Step 4: Implement `interactive` in runner**
+
+In `src/runner.ts`, update `RunOptions`:
+
+```ts
+export interface RunOptions {
+  account?: string;
+  spawner?: Spawner;
+  interactive?: boolean;
+  timeout?: number;
+}
+```
+
+In the `run()` function, change the `fullArgs` construction:
+
+```ts
+const { account, spawner = spawn as unknown as Spawner, interactive = false, timeout } = options;
+
+const effectiveAccount = account ?? process.env.GOG_ACCOUNT;
+
+const fullArgs = ['--json', '--color=never'];
+if (!interactive) {
+  fullArgs.push('--no-input');
+}
+```
+
+- [ ] **Step 5: Run tests to verify both pass**
+
+Run: `npm test -- --reporter=verbose`
+Expected: Both new tests PASS, all existing tests PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/runner.ts tests/runner.test.ts
+git commit -m "feat(runner): add interactive option to skip --no-input"
+```
+
+---
+
+### Task 2: Runner — add custom `timeout` option
+
+**Files:**
+- Modify: `src/runner.ts:17-18` (run function, timeout handling)
+- Test: `tests/runner.test.ts`
+
+- [ ] **Step 1: Write the failing test for custom timeout**
+
+Add to `tests/runner.test.ts`:
+
+```ts
+it('uses custom timeout when provided', async () => {
+  vi.useFakeTimers();
+  const spawner = vi.fn(() => {
+    const proc = new EventEmitter() as ReturnType<Spawner>;
+    (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stdout = new EventEmitter();
+    (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stderr = new EventEmitter();
+    proc.kill = vi.fn();
+    return proc;
+  }) as unknown as Spawner;
+
+  const promise = run(['auth', 'add', 'user@gmail.com'], { spawner, timeout: 300_000 });
+  // Should NOT have timed out at 30s
+  vi.advanceTimersByTime(30_000);
+  // Advance to custom timeout
+  vi.advanceTimersByTime(270_000);
+  await expect(promise).rejects.toThrow('gog timed out after 300000ms (5 minutes)');
+  vi.useRealTimers();
+});
+```
+
+- [ ] **Step 2: Write test that default timeout still works**
+
+Add to `tests/runner.test.ts`:
+
+```ts
+it('includes human-readable duration in timeout error for default timeout', async () => {
+  vi.useFakeTimers();
+  const spawner = vi.fn(() => {
+    const proc = new EventEmitter() as ReturnType<Spawner>;
+    (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stdout = new EventEmitter();
+    (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stderr = new EventEmitter();
+    proc.kill = vi.fn();
+    return proc;
+  }) as unknown as Spawner;
+
+  const promise = run(['sheets', 'get', 'id', 'A1'], { spawner });
+  vi.advanceTimersByTime(30_000);
+  await expect(promise).rejects.toThrow('gog timed out after 30000ms');
+  vi.useRealTimers();
+});
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+Run: `npm test -- --reporter=verbose`
+Expected: Custom timeout test FAIL (times out at 30s instead of 300s). Default timeout message test may also fail if message format changed.
+
+- [ ] **Step 4: Implement custom timeout in runner**
+
+In `src/runner.ts`, update the `run()` function:
+
+```ts
+const effectiveTimeout = timeout ?? TIMEOUT_MS;
+
+// Helper for human-readable duration
+function formatTimeout(ms: number): string {
+  const seconds = Math.round(ms / 1000);
+  if (seconds >= 60) {
+    const minutes = Math.round(seconds / 60);
+    return `${ms}ms (${minutes} minute${minutes !== 1 ? 's' : ''})`;
+  }
+  return `${ms}ms`;
+}
+
+const timer = setTimeout(() => {
+  settled = true;
+  child.kill();
+  reject(new Error(`gog timed out after ${formatTimeout(effectiveTimeout)}`));
+}, effectiveTimeout);
+```
+
+Note: `formatTimeout` should be defined inside `run()` or as a module-level helper. Since it's small, define it at module level above the `run` function.
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `npm test -- --reporter=verbose`
+Expected: All tests PASS.
+
+- [ ] **Step 6: Verify existing timeout test still passes**
+
+The existing test `'rejects with timeout error when gog does not respond'` uses `.toThrow('gog timed out after 30000ms')` which is a substring match. The new message `"gog timed out after 30000ms"` still contains this substring (30s doesn't reach the 60s threshold for the minutes suffix). Verify it passes with no changes needed.
+
+Run: `npm test -- --reporter=verbose -t "does not respond"`
+Expected: PASS with no changes.
+
+- [ ] **Step 7: Run full test suite**
+
+Run: `npm test -- --reporter=verbose`
+Expected: All tests PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/runner.ts tests/runner.test.ts
+git commit -m "feat(runner): add custom timeout option with human-readable error"
+```
+
+---
+
+### Task 3: Runner — append stderr on interactive success
+
+**Files:**
+- Modify: `src/runner.ts` (close handler)
+- Test: `tests/runner.test.ts`
+
+- [ ] **Step 1: Write the failing test for stderr appended on interactive success**
+
+Add to `tests/runner.test.ts`:
+
+```ts
+it('appends stderr to stdout on success when interactive is true', async () => {
+  const spawner = vi.fn(() => {
+    const proc = new EventEmitter() as ReturnType<Spawner>;
+    (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stdout = new EventEmitter();
+    (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stderr = new EventEmitter();
+    setTimeout(() => {
+      (proc as unknown as { stdout: EventEmitter }).stdout.emit('data', Buffer.from('{"success":true}'));
+      (proc as unknown as { stderr: EventEmitter }).stderr.emit('data', Buffer.from('Opening browser...\nIf the browser doesn\'t open, visit this URL:\nhttps://accounts.google.com/auth?...'));
+      proc.emit('close', 0);
+    }, 0);
+    return proc;
+  }) as unknown as Spawner;
+
+  const result = await run(['auth', 'add', 'user@gmail.com'], { spawner, interactive: true });
+  expect(result).toContain('{"success":true}');
+  expect(result).toContain('Opening browser...');
+  expect(result).toContain('https://accounts.google.com/auth?...');
+});
+```
+
+- [ ] **Step 2: Write test that non-interactive success does NOT include stderr**
+
+Add to `tests/runner.test.ts`:
+
+```ts
+it('does not append stderr to stdout on success when interactive is false', async () => {
+  const spawner = vi.fn(() => {
+    const proc = new EventEmitter() as ReturnType<Spawner>;
+    (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stdout = new EventEmitter();
+    (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stderr = new EventEmitter();
+    setTimeout(() => {
+      (proc as unknown as { stdout: EventEmitter }).stdout.emit('data', Buffer.from('{"ok":true}'));
+      (proc as unknown as { stderr: EventEmitter }).stderr.emit('data', Buffer.from('some warning'));
+      proc.emit('close', 0);
+    }, 0);
+    return proc;
+  }) as unknown as Spawner;
+
+  const result = await run(['sheets', 'get', 'id', 'A1'], { spawner });
+  expect(result).toBe('{"ok":true}');
+  expect(result).not.toContain('some warning');
+});
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+Run: `npm test -- --reporter=verbose`
+Expected: Interactive stderr test FAIL (stderr not included in result).
+
+- [ ] **Step 4: Implement stderr append for interactive mode**
+
+In `src/runner.ts`, update the close handler:
+
+```ts
+child.on('close', (code: number | null) => {
+  clearTimeout(timer);
+  if (settled) return;
+  settled = true;
+  if (code === 0) {
+    if (interactive && stderr.trim()) {
+      resolve(stdout + '\n' + stderr);
+    } else {
+      resolve(stdout);
+    }
+  } else {
+    reject(new Error(stderr.trim() || `gog exited with code ${code}`));
+  }
+});
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run: `npm test -- --reporter=verbose`
+Expected: All tests PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/runner.ts tests/runner.test.ts
+git commit -m "feat(runner): append stderr on interactive success for fallback URL"
+```
+
+---
+
+### Task 4: Auth tool — add `gog_auth_add`
+
+**Files:**
+- Modify: `src/tools/auth.ts:6-56` (add new tool, update `gog_auth_run` description)
+- Test: `tests/tools/auth.test.ts`
+
+- [ ] **Step 1: Write the failing test for `gog_auth_add` with default services**
+
+Add to `tests/tools/auth.test.ts`:
+
+```ts
+describe('gog_auth_add', () => {
+  it('calls run with correct args, interactive true, and 5-minute timeout', async () => {
+    vi.mocked(runner.run).mockResolvedValue('Authorization successful for user@gmail.com');
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_auth_add')!({ email: 'user@gmail.com' });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['auth', 'add', 'user@gmail.com', '--services', 'all'],
+      { interactive: true, timeout: 300_000 },
+    );
+    expect(result.content[0].text).toBe('Authorization successful for user@gmail.com');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npm test -- --reporter=verbose -t "gog_auth_add"`
+Expected: FAIL — handler `gog_auth_add` does not exist.
+
+- [ ] **Step 3: Write additional tests for `gog_auth_add`**
+
+Add inside the `describe('gog_auth_add', ...)`:
+
+```ts
+it('passes custom services when provided', async () => {
+  vi.mocked(runner.run).mockResolvedValue('Authorization successful');
+  const handlers = setupHandlers();
+  await handlers.get('gog_auth_add')!({ email: 'user@gmail.com', services: 'sheets,gmail' });
+  expect(runner.run).toHaveBeenCalledWith(
+    ['auth', 'add', 'user@gmail.com', '--services', 'sheets,gmail'],
+    { interactive: true, timeout: 300_000 },
+  );
+});
+
+it('returns error text on failure', async () => {
+  vi.mocked(runner.run).mockRejectedValue(new Error('Auth cancelled by user'));
+  const handlers = setupHandlers();
+  const result = await handlers.get('gog_auth_add')!({ email: 'user@gmail.com' });
+  expect(result.content[0].text).toBe('Error: Auth cancelled by user');
+});
+
+it('returns error text on timeout', async () => {
+  vi.mocked(runner.run).mockRejectedValue(new Error('gog timed out after 300000ms (5 minutes)'));
+  const handlers = setupHandlers();
+  const result = await handlers.get('gog_auth_add')!({ email: 'user@gmail.com' });
+  expect(result.content[0].text).toContain('timed out');
+  expect(result.content[0].text).toContain('5 minutes');
+});
+```
+
+- [ ] **Step 4: Implement `gog_auth_add` tool**
+
+Add to `src/tools/auth.ts`, before the `gog_auth_run` registration:
+
+```ts
+server.registerTool('gog_auth_add', {
+  description:
+    'Authorize a Google account via browser-based OAuth. ' +
+    'Opens a browser window where the user must sign in and grant access. ' +
+    'Blocks for up to 5 minutes waiting for the user to complete authorization. ' +
+    'If the browser does not open automatically, a fallback URL is included in the response. ' +
+    'Use gog_auth_list to check which accounts are already configured.',
+  annotations: { destructiveHint: true },
+  inputSchema: {
+    email: z.string().describe('Google account email to authorize'),
+    services: z.string().optional().default('all').describe(
+      'Services to authorize: "all" or comma-separated list (e.g. "sheets,gmail,calendar"). Default: "all"',
+    ),
+  },
+}, async ({ email, services }) => {
+  try {
+    return toText(await run(['auth', 'add', email, '--services', services], {
+      interactive: true,
+      timeout: 300_000,
+    }));
+  } catch (err) {
+    return toError(err);
+  }
+});
+```
+
+- [ ] **Step 5: Update `gog_auth_run` description**
+
+Change the `gog_auth_run` description from:
+
+```ts
+description: 'Run any gog auth subcommand. Run `gog auth --help` to see all available subcommands and flags. Note: gog auth add requires interactive browser auth and cannot be completed over MCP — run it in your terminal instead: gog auth add <email> --services <service>',
+```
+
+to:
+
+```ts
+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.',
+```
+
+- [ ] **Step 6: Run all tests**
+
+Run: `npm test -- --reporter=verbose`
+Expected: All tests PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/tools/auth.ts tests/tools/auth.test.ts
+git commit -m "feat(auth): add gog_auth_add tool for browser-based OAuth"
+```
+
+---
+
+### Task 5: Manifest update
+
+**Files:**
+- Modify: `manifest.json`
+
+- [ ] **Step 1: Add `gog_auth_add` to manifest tools list**
+
+Add a new entry in the `tools` array in `manifest.json`, after the existing `gog_auth_list` entry:
+
+```json
+{
+  "name": "gog_auth_add",
+  "description": "Authorize a Google account via browser-based OAuth"
+},
+```
+
+- [ ] **Step 2: Run build to verify no issues**
+
+Run: `npm run build`
+Expected: Build succeeds.
+
+- [ ] **Step 3: Run full test suite**
+
+Run: `npm test -- --reporter=verbose`
+Expected: All tests PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add manifest.json
+git commit -m "chore(manifest): add gog_auth_add tool"
+```

package/docs/superpowers/specs/2026-04-13-browser-auth-design.md

@@ -0,0 +1,88 @@
+# Browser-Based Auth Flow for gogcli-mcp
+
+## Summary
+
+Add a `gog_auth_add` MCP tool that runs the default `gog auth add` browser flow, opening the user's browser for Google OAuth and blocking until completion. This gives users a one-click auth experience without leaving Claude.
+
+## Runner Changes
+
+### `RunOptions` additions (`src/runner.ts`)
+
+Add two optional fields to the existing `RunOptions` interface:
+
+```ts
+export interface RunOptions {
+  account?: string;
+  spawner?: Spawner;
+  interactive?: boolean;  // NEW: when true, omit --no-input
+  timeout?: number;       // NEW: override default 30s timeout (ms)
+}
+```
+
+### Behavior changes in `run()`
+
+- When `interactive` is `true`, do NOT inject `--no-input` into `fullArgs`.
+- When `timeout` is provided, use it instead of the `TIMEOUT_MS` constant.
+- When `interactive` is `true` and the process exits successfully (code 0), append any captured stderr to the stdout result. This ensures the fallback URL ("If the browser doesn't open, visit this URL") reaches Claude even on success.
+- When `timeout` is provided, the timeout error message includes the human-readable duration: e.g., `"gog timed out after 300000ms (5 minutes)"` so both the raw value and friendly form are visible.
+
+### Default behavior
+
+Unchanged. Existing calls without `interactive` or `timeout` behave exactly as before.
+
+## New Tool: `gog_auth_add`
+
+### Registration (`src/tools/auth.ts`)
+
+- **Name:** `gog_auth_add`
+- **Annotations:** `{ destructiveHint: true }`
+- **Input schema:**
+  - `email` — required `z.string()`, Google account email to authorize
+  - `services` — optional `z.string()`, default `"all"`, comma-separated services or `"all"`
+- **Handler:** Calls `run(['auth', 'add', email, '--services', services], { interactive: true, timeout: 300_000 })`
+- **Error handling:** Standard `toError()` wrapping, same as other auth tools.
+
+### Tool description
+
+The description tells Claude:
+
+1. This opens a browser window for Google OAuth
+2. The user must complete authorization in the browser
+3. The tool blocks for up to 5 minutes waiting for completion
+4. If the browser doesn't open automatically, a fallback URL is included in the response
+
+### `gog_auth_run` description update
+
+Remove the "gog auth add requires interactive browser auth and cannot be completed over MCP" caveat. Replace with a note pointing to `gog_auth_add` for browser-based authorization.
+
+## Manifest update
+
+Add `gog_auth_add` to the `manifest.json` tools list.
+
+## Error Handling
+
+| Scenario | Behavior |
+|---|---|
+| User completes auth in browser | Tool returns success with gogcli output |
+| User doesn't complete within 5 min | Process killed, error: "gog auth timed out after 5 minutes" |
+| User cancels/denies in browser | gogcli exits non-zero, stderr returned as error |
+| Browser doesn't open | Fallback URL included in response via stderr capture |
+| Already authorized account | gogcli re-authorizes (updates scopes), no special handling |
+
+## Testing
+
+### Runner tests (`tests/runner.test.ts`)
+
+- `interactive: true` omits `--no-input` from args
+- Custom `timeout` is respected (process killed at custom time, not 30s)
+- `interactive: true` on success appends stderr to stdout result
+- `interactive: false` (or omitted) still includes `--no-input` (regression)
+- Timeout error message includes human-readable duration
+
+### Auth tool tests (`tests/tools/auth.test.ts`)
+
+- `gog_auth_add` passes correct args to runner with `interactive: true` and `timeout: 300_000`
+- `gog_auth_add` defaults services to `"all"` when omitted
+- `gog_auth_add` passes custom services when provided
+- `gog_auth_add` returns error text on failure
+- `gog_auth_add` returns error text on timeout

package/manifest.json

@@ -3,7 +3,7 @@
   "manifest_version": "0.3",
   "name": "gogcli-mcp",
   "display_name": "gogcli",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Google Sheets (and more) for Claude via gogcli — read, write, and manage spreadsheets",
   "author": {
     "name": "Chris Hall",
@@ -64,6 +64,10 @@
     }
   },
   "tools": [
+    {
+      "name": "gog_auth_add",
+      "description": "Authorize a Google account via browser-based OAuth"
+    },
     {
       "name": "gog_auth_list",
       "description": "List all Google accounts stored in gogcli"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gogcli-mcp",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "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.2' });
+const server = new McpServer({ name: 'gogcli', version: '1.0.3' });
 
 registerAuthTools(server);
 registerCalendarTools(server);

package/src/runner.ts

@@ -10,21 +10,37 @@ export type Spawner = (
 export interface RunOptions {
   account?: string;
   spawner?: Spawner;
+  interactive?: boolean;
+  timeout?: number;
 }
 
 const TIMEOUT_MS = 30_000;
 
+function formatTimeout(ms: number): string {
+  const seconds = Math.round(ms / 1000);
+  if (seconds >= 60) {
+    const minutes = Math.round(seconds / 60);
+    return `${ms}ms (${minutes} minute${minutes !== 1 ? 's' : ''})`;
+  }
+  return `${ms}ms`;
+}
+
 export async function run(args: string[], options: RunOptions = {}): Promise<string> {
-  const { account, spawner = spawn as unknown as Spawner } = options;
+  const { account, spawner = spawn as unknown as Spawner, interactive = false, timeout } = options;
 
   const effectiveAccount = account ?? process.env.GOG_ACCOUNT;
 
-  const fullArgs = ['--json', '--no-input', '--color=never'];
+  const fullArgs = ['--json', '--color=never'];
+  if (!interactive) {
+    fullArgs.push('--no-input');
+  }
   if (effectiveAccount) {
     fullArgs.push('--account', effectiveAccount);
   }
   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 = '';
@@ -34,8 +50,8 @@ export async function run(args: string[], options: RunOptions = {}): Promise<str
     const timer = setTimeout(() => {
       settled = true;
       child.kill();
-      reject(new Error(`gog timed out after ${TIMEOUT_MS}ms`));
-    }, TIMEOUT_MS);
+      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(); });
@@ -45,7 +61,11 @@ export async function run(args: string[], options: RunOptions = {}): Promise<str
       if (settled) return;
       settled = true;
       if (code === 0) {
-        resolve(stdout);
+        if (interactive && stderr.trim()) {
+          resolve(stdout + '\n' + stderr);
+        } else {
+          resolve(stdout);
+        }
       } else {
         reject(new Error(stderr.trim() || `gog exited with code ${code}`));
       }

package/src/tools/auth.ts

@@ -40,8 +40,33 @@ export function registerAuthTools(server: McpServer): void {
     }
   });
 
+  server.registerTool('gog_auth_add', {
+    description:
+      'Authorize a Google account via browser-based OAuth. ' +
+      'Opens a browser window where the user must sign in and grant access. ' +
+      'Blocks for up to 5 minutes waiting for the user to complete authorization. ' +
+      'If the browser does not open automatically, a fallback URL is included in the response. ' +
+      'Use gog_auth_list to check which accounts are already configured.',
+    annotations: { destructiveHint: true },
+    inputSchema: {
+      email: z.string().describe('Google account email to authorize'),
+      services: z.string().optional().default('all').describe(
+        'Services to authorize: "all" or comma-separated list (e.g. "sheets,gmail,calendar"). Default: "all"',
+      ),
+    },
+  }, async ({ email, services = 'all' }) => {
+    try {
+      return toText(await run(['auth', 'add', email, '--services', services], {
+        interactive: true,
+        timeout: 300_000,
+      }));
+    } catch (err) {
+      return toError(err);
+    }
+  });
+
   server.registerTool('gog_auth_run', {
-    description: 'Run any gog auth subcommand. Run `gog auth --help` to see all available subcommands and flags. Note: gog auth add requires interactive browser auth and cannot be completed over MCP — run it in your terminal instead: gog auth add <email> --services <service>',
+    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: z.string().describe('The gog auth subcommand, e.g. "remove", "alias", "tokens"'),

package/tests/runner.test.ts

@@ -18,12 +18,12 @@ function makeSpawner(exitCode: number, stdout = '', stderr = ''): Spawner {
 }
 
 describe('run', () => {
-  it('passes --json --no-input --color=never before service args', async () => {
+  it('passes --json --color=never --no-input before service args', async () => {
     const spawner = makeSpawner(0, '{"ok":true}');
     await run(['sheets', 'get', 'id1', 'A1'], { spawner });
     expect(spawner).toHaveBeenCalledWith(
       'gog',
-      ['--json', '--no-input', '--color=never', 'sheets', 'get', 'id1', 'A1'],
+      ['--json', '--color=never', '--no-input', 'sheets', 'get', 'id1', 'A1'],
       expect.objectContaining({ env: process.env }),
     );
   });
@@ -33,7 +33,7 @@ describe('run', () => {
     await run(['sheets', 'metadata', 'id1'], { account: 'me@gmail.com', spawner });
     expect(spawner).toHaveBeenCalledWith(
       'gog',
-      ['--json', '--no-input', '--color=never', '--account', 'me@gmail.com', 'sheets', 'metadata', 'id1'],
+      ['--json', '--color=never', '--no-input', '--account', 'me@gmail.com', 'sheets', 'metadata', 'id1'],
       expect.any(Object),
     );
   });
@@ -46,7 +46,7 @@ describe('run', () => {
       await run(['sheets', 'metadata', 'id1'], { spawner });
       expect(spawner).toHaveBeenCalledWith(
         'gog',
-        ['--json', '--no-input', '--color=never', '--account', 'env@gmail.com', 'sheets', 'metadata', 'id1'],
+        ['--json', '--color=never', '--no-input', '--account', 'env@gmail.com', 'sheets', 'metadata', 'id1'],
         expect.any(Object),
       );
     } finally {
@@ -66,7 +66,7 @@ describe('run', () => {
       await run(['sheets', 'metadata', 'id1'], { account: 'override@gmail.com', spawner });
       expect(spawner).toHaveBeenCalledWith(
         'gog',
-        ['--json', '--no-input', '--color=never', '--account', 'override@gmail.com', 'sheets', 'metadata', 'id1'],
+        ['--json', '--color=never', '--no-input', '--account', 'override@gmail.com', 'sheets', 'metadata', 'id1'],
         expect.any(Object),
       );
     } finally {
@@ -211,6 +211,95 @@ describe('run', () => {
     vi.useRealTimers();
   });
 
+  it('omits --no-input when interactive is true', async () => {
+    const spawner = makeSpawner(0, '{"ok":true}');
+    await run(['auth', 'add', 'user@gmail.com'], { spawner, interactive: true });
+    const callArgs = (spawner as ReturnType<typeof vi.fn>).mock.calls[0][1] as string[];
+    expect(callArgs).toContain('--json');
+    expect(callArgs).toContain('--color=never');
+    expect(callArgs).not.toContain('--no-input');
+    expect(callArgs).toContain('auth');
+  });
+
+  it('includes --no-input when interactive is not set', async () => {
+    const spawner = makeSpawner(0, '{"ok":true}');
+    await run(['sheets', 'get', 'id1', 'A1'], { spawner });
+    const callArgs = (spawner as ReturnType<typeof vi.fn>).mock.calls[0][1] as string[];
+    expect(callArgs).toContain('--no-input');
+  });
+
+  it('appends stderr to stdout on success when interactive is true', async () => {
+    const spawner = vi.fn(() => {
+      const proc = new EventEmitter() as ReturnType<Spawner>;
+      (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stdout = new EventEmitter();
+      (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stderr = new EventEmitter();
+      setTimeout(() => {
+        (proc as unknown as { stdout: EventEmitter }).stdout.emit('data', Buffer.from('{"success":true}'));
+        (proc as unknown as { stderr: EventEmitter }).stderr.emit('data', Buffer.from('Opening browser...\nIf the browser doesn\'t open, visit this URL:\nhttps://accounts.google.com/auth?...'));
+        proc.emit('close', 0);
+      }, 0);
+      return proc;
+    }) as unknown as Spawner;
+
+    const result = await run(['auth', 'add', 'user@gmail.com'], { spawner, interactive: true });
+    expect(result).toContain('{"success":true}');
+    expect(result).toContain('Opening browser...');
+    expect(result).toContain('https://accounts.google.com/auth?...');
+  });
+
+  it('does not append stderr to stdout on success when interactive is false', async () => {
+    const spawner = vi.fn(() => {
+      const proc = new EventEmitter() as ReturnType<Spawner>;
+      (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stdout = new EventEmitter();
+      (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stderr = new EventEmitter();
+      setTimeout(() => {
+        (proc as unknown as { stdout: EventEmitter }).stdout.emit('data', Buffer.from('{"ok":true}'));
+        (proc as unknown as { stderr: EventEmitter }).stderr.emit('data', Buffer.from('some warning'));
+        proc.emit('close', 0);
+      }, 0);
+      return proc;
+    }) as unknown as Spawner;
+
+    const result = await run(['sheets', 'get', 'id', 'A1'], { spawner });
+    expect(result).toBe('{"ok":true}');
+    expect(result).not.toContain('some warning');
+  });
+
+  it('uses custom timeout when provided', async () => {
+    vi.useFakeTimers();
+    const spawner = vi.fn(() => {
+      const proc = new EventEmitter() as ReturnType<Spawner>;
+      (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stdout = new EventEmitter();
+      (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stderr = new EventEmitter();
+      proc.kill = vi.fn();
+      return proc;
+    }) as unknown as Spawner;
+
+    const promise = run(['auth', 'add', 'user@gmail.com'], { spawner, timeout: 300_000 });
+    // Should NOT have timed out at 30s
+    vi.advanceTimersByTime(30_000);
+    // Advance to custom timeout
+    vi.advanceTimersByTime(270_000);
+    await expect(promise).rejects.toThrow('gog timed out after 300000ms (5 minutes)');
+    vi.useRealTimers();
+  });
+
+  it('includes human-readable duration in timeout error for default timeout', async () => {
+    vi.useFakeTimers();
+    const spawner = vi.fn(() => {
+      const proc = new EventEmitter() as ReturnType<Spawner>;
+      (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stdout = new EventEmitter();
+      (proc as unknown as { stdout: EventEmitter; stderr: EventEmitter }).stderr = new EventEmitter();
+      proc.kill = vi.fn();
+      return proc;
+    }) as unknown as Spawner;
+
+    const promise = run(['sheets', 'get', 'id', 'A1'], { spawner });
+    vi.advanceTimersByTime(30_000);
+    await expect(promise).rejects.toThrow('gog timed out after 30000ms');
+    vi.useRealTimers();
+  });
+
   it('ignores timeout if close event already settled the promise', async () => {
     vi.useFakeTimers();
     const spawner = vi.fn(() => {

package/tests/tools/auth.test.ts

@@ -78,6 +78,44 @@ describe('gog_auth_services', () => {
   });
 });
 
+describe('gog_auth_add', () => {
+  it('calls run with correct args, interactive true, and 5-minute timeout', async () => {
+    vi.mocked(runner.run).mockResolvedValue('Authorization successful for user@gmail.com');
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_auth_add')!({ email: 'user@gmail.com' });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['auth', 'add', 'user@gmail.com', '--services', 'all'],
+      { interactive: true, timeout: 300_000 },
+    );
+    expect(result.content[0].text).toBe('Authorization successful for user@gmail.com');
+  });
+
+  it('passes custom services when provided', async () => {
+    vi.mocked(runner.run).mockResolvedValue('Authorization successful');
+    const handlers = setupHandlers();
+    await handlers.get('gog_auth_add')!({ email: 'user@gmail.com', services: 'sheets,gmail' });
+    expect(runner.run).toHaveBeenCalledWith(
+      ['auth', 'add', 'user@gmail.com', '--services', 'sheets,gmail'],
+      { interactive: true, timeout: 300_000 },
+    );
+  });
+
+  it('returns error text on failure', async () => {
+    vi.mocked(runner.run).mockRejectedValue(new Error('Auth cancelled by user'));
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_auth_add')!({ email: 'user@gmail.com' });
+    expect(result.content[0].text).toBe('Error: Auth cancelled by user');
+  });
+
+  it('returns error text on timeout', async () => {
+    vi.mocked(runner.run).mockRejectedValue(new Error('gog timed out after 300000ms (5 minutes)'));
+    const handlers = setupHandlers();
+    const result = await handlers.get('gog_auth_add')!({ email: 'user@gmail.com' });
+    expect(result.content[0].text).toContain('timed out');
+    expect(result.content[0].text).toContain('5 minutes');
+  });
+});
+
 describe('gog_auth_run', () => {
   it('passes subcommand and args to runner', async () => {
     vi.mocked(runner.run).mockResolvedValue('removed user@gmail.com');