gogcli-mcp 2.0.8 → 2.0.9

package/src/lib.ts

@@ -15,5 +15,14 @@ export {
 } from './server.js';
 export { run } from './runner.js';
 export type { RunOptions, Spawner } from './runner.js';
-export { accountParam, runOrDiagnose, toText, toError } from './tools/utils.js';
+export {
+  accountParam,
+  runOrDiagnose,
+  toText,
+  toError,
+  ids,
+  paginationParams,
+  pushPaginationFlags,
+  registerRunTool,
+} from './tools/utils.js';
 export type { ToolResult } from './tools/utils.js';

package/src/runner.ts

@@ -27,6 +27,40 @@ function envOrUndefined(key: string): string | undefined {
   return value;
 }
 
+// Strip ambient secrets from the child env so gogcli only sees its own
+// configured credentials. GOG_ACCESS_TOKEN is the original target: gogcli
+// would otherwise try to use a (potentially stale) directly-passed token
+// instead of the stored refresh token. The broader patterns are
+// defense-in-depth — the parent process's shell may have other Google /
+// cloud / API secrets in scope that the child has no business seeing.
+function sanitizedEnv(): NodeJS.ProcessEnv {
+  const result: NodeJS.ProcessEnv = {};
+  for (const [key, value] of Object.entries(process.env)) {
+    if (key === 'GOG_ACCESS_TOKEN') continue;
+    if (key === 'GOOGLE_APPLICATION_CREDENTIALS') continue;
+    if (/(_TOKEN|_SECRET|_API_KEY|_PRIVATE_KEY)$/.test(key)) continue;
+    result[key] = value;
+  }
+  return result;
+}
+
+// Redact bearer/refresh-token patterns from error text before surfacing
+// it back to the MCP client. If gog ever emits a token in stderr (e.g.
+// from a verbose log mode), this prevents it from leaking to the model.
+const TOKEN_PATTERNS: RegExp[] = [
+  /Bearer\s+[A-Za-z0-9._\-+/=]+/gi,
+  /ya29\.[A-Za-z0-9._\-]+/g,           // OAuth2 access tokens
+  /1\/\/[A-Za-z0-9._\-]+/g,            // OAuth2 refresh tokens
+  /AIza[A-Za-z0-9_\-]{35}/g,           // Google API keys
+];
+export function redactSecrets(text: string): string {
+  let redacted = text;
+  for (const re of TOKEN_PATTERNS) {
+    redacted = redacted.replace(re, '[REDACTED]');
+  }
+  return redacted;
+}
+
 // MCP desktop clients often spawn servers with a stripped PATH that excludes
 // Homebrew, user-local, and Go's default install dirs — so even when gog is
 // installed, the spawned server can't find it. Augment the child's PATH with
@@ -79,10 +113,7 @@ export async function run(args: string[], options: RunOptions = {}): Promise<str
   const effectiveTimeout = timeout ?? TIMEOUT_MS;
 
   return new Promise((resolve, reject) => {
-    // 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 childEnv = { ...cleanEnv, PATH: augmentedPath() };
+    const childEnv = { ...sanitizedEnv(), PATH: augmentedPath() };
     const child = spawner(envOrUndefined('GOG_PATH') ?? 'gog', fullArgs, { env: childEnv });
     const stdoutChunks: Buffer[] = [];
     const stderrChunks: Buffer[] = [];
@@ -110,7 +141,7 @@ export async function run(args: string[], options: RunOptions = {}): Promise<str
           resolve(stdout);
         }
       } else {
-        reject(new Error(stderr || `gog exited with code ${code}`));
+        reject(new Error(redactSecrets(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, runOrDiagnose } from './utils.js';
+import { toText, toError, runOrDiagnose, registerRunTool } from './utils.js';
 
 export function registerAuthTools(server: McpServer): void {
   server.registerTool('gog_auth_list', {
@@ -65,14 +65,10 @@ export function registerAuthTools(server: McpServer): void {
     }
   });
 
-  server.registerTool('gog_auth_run', {
-    description: 'Run any gog auth subcommand. Run `gog auth --help` to see all available subcommands and flags. Note: for browser-based authorization, use gog_auth_add instead.',
-    annotations: { destructiveHint: true },
-    inputSchema: {
-      subcommand: z.string().describe('The gog auth subcommand, e.g. "remove", "alias", "tokens"'),
-      args: z.array(z.string()).describe('Additional positional args and flags'),
-    },
-  }, async ({ subcommand, args }) => {
-    return runOrDiagnose(['auth', subcommand, ...args], {});
+  registerRunTool(server, {
+    service: 'auth',
+    examples: '"remove", "alias", "tokens"',
+    omitAccount: true,
+    note: 'For browser-based authorization, use gog_auth_add instead.',
   });
 }

package/src/tools/calendar.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose } from './utils.js';
+import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
 
 export function registerCalendarTools(server: McpServer): void {
   server.registerTool('gog_calendar_events', {
@@ -114,15 +114,5 @@ export function registerCalendarTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
-  server.registerTool('gog_calendar_run', {
-    description: 'Run any gog calendar subcommand not covered by the other tools. Run `gog calendar --help` for the full list of subcommands, or `gog calendar <subcommand> --help` for flags on a specific subcommand.',
-    annotations: { destructiveHint: true },
-    inputSchema: {
-      subcommand: z.string().describe('The gog calendar subcommand to run, e.g. "calendars", "freebusy"'),
-      args: z.array(z.string()).describe('Additional positional args and flags'),
-      account: accountParam,
-    },
-  }, async ({ subcommand, args, account }) => {
-    return runOrDiagnose(['calendar', subcommand, ...args], { account });
-  });
+  registerRunTool(server, { service: 'calendar', examples: '"calendars", "freebusy"' });
 }

package/src/tools/classroom.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose } from './utils.js';
+import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
 
 export function registerClassroomTools(server: McpServer): void {
   server.registerTool('gog_classroom_courses_list', {
@@ -387,15 +387,9 @@ export function registerClassroomTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
-  server.registerTool('gog_classroom_run', {
-    description: 'Run any gog classroom subcommand not covered by the other tools (guardians, guardian-invitations, materials, coursework assignees, announcement assignees, etc.). Run `gog classroom --help` for the full list, or `gog classroom <subcommand> --help` for flags.',
-    annotations: { destructiveHint: true },
-    inputSchema: {
-      subcommand: z.string().describe('The gog classroom subcommand to run, e.g. "guardians", "materials", "guardian-invitations"'),
-      args: z.array(z.string()).describe('Additional positional args and flags'),
-      account: accountParam,
-    },
-  }, async ({ subcommand, args, account }) => {
-    return runOrDiagnose(['classroom', subcommand, ...args], { account });
+  registerRunTool(server, {
+    service: 'classroom',
+    examples: '"guardians", "materials", "guardian-invitations"',
+    note: 'Covers anything not wrapped by the dedicated tools (guardians, guardian-invitations, materials, coursework assignees, announcement assignees, etc.).',
   });
 }

package/src/tools/contacts.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose } from './utils.js';
+import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
 
 export function registerContactsTools(server: McpServer): void {
   server.registerTool('gog_contacts_search', {
@@ -57,15 +57,5 @@ export function registerContactsTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
-  server.registerTool('gog_contacts_run', {
-    description: 'Run any gog contacts subcommand not covered by the other tools. Run `gog contacts --help` for the full list of subcommands, or `gog contacts <subcommand> --help` for flags on a specific subcommand.',
-    annotations: { destructiveHint: true },
-    inputSchema: {
-      subcommand: z.string().describe('The gog contacts subcommand to run, e.g. "update", "delete", "directory"'),
-      args: z.array(z.string()).describe('Additional positional args and flags'),
-      account: accountParam,
-    },
-  }, async ({ subcommand, args, account }) => {
-    return runOrDiagnose(['contacts', subcommand, ...args], { account });
-  });
+  registerRunTool(server, { service: 'contacts', examples: '"update", "delete", "directory"' });
 }

package/src/tools/docs.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose } from './utils.js';
+import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
 
 export function registerDocsTools(server: McpServer): void {
   server.registerTool('gog_docs_info', {
@@ -74,15 +74,5 @@ export function registerDocsTools(server: McpServer): void {
     return runOrDiagnose(['docs', 'structure', docId], { 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 },
-    inputSchema: {
-      subcommand: z.string().describe('The gog docs subcommand to run, e.g. "copy", "clear", "insert", "sed", "export"'),
-      args: z.array(z.string()).describe('Additional positional args and flags'),
-      account: accountParam,
-    },
-  }, async ({ subcommand, args, account }) => {
-    return runOrDiagnose(['docs', subcommand, ...args], { account });
-  });
+  registerRunTool(server, { service: 'docs', examples: '"copy", "clear", "insert", "sed", "export"' });
 }

package/src/tools/drive.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose } from './utils.js';
+import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
 
 export function registerDriveTools(server: McpServer): void {
   server.registerTool('gog_drive_ls', {
@@ -114,15 +114,5 @@ export function registerDriveTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
-  server.registerTool('gog_drive_run', {
-    description: 'Run any gog drive subcommand not covered by the other tools. Run `gog drive --help` for the full list of subcommands, or `gog drive <subcommand> --help` for flags on a specific subcommand.',
-    annotations: { destructiveHint: true },
-    inputSchema: {
-      subcommand: z.string().describe('The gog drive subcommand to run, e.g. "copy", "upload", "download", "permissions"'),
-      args: z.array(z.string()).describe('Additional positional args and flags'),
-      account: accountParam,
-    },
-  }, async ({ subcommand, args, account }) => {
-    return runOrDiagnose(['drive', subcommand, ...args], { account });
-  });
+  registerRunTool(server, { service: 'drive', examples: '"copy", "upload", "download", "permissions"' });
 }

package/src/tools/gmail.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose } from './utils.js';
+import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
 
 export function registerGmailTools(server: McpServer): void {
   server.registerTool('gog_gmail_search', {
@@ -53,15 +53,5 @@ export function registerGmailTools(server: McpServer): void {
     return runOrDiagnose(args, { account });
   });
 
-  server.registerTool('gog_gmail_run', {
-    description: 'Run any gog gmail subcommand not covered by the other tools. Run `gog gmail --help` for the full list of subcommands, or `gog gmail <subcommand> --help` for flags on a specific subcommand.',
-    annotations: { destructiveHint: true },
-    inputSchema: {
-      subcommand: z.string().describe('The gog gmail subcommand to run, e.g. "archive", "mark-read", "labels"'),
-      args: z.array(z.string()).describe('Additional positional args and flags'),
-      account: accountParam,
-    },
-  }, async ({ subcommand, args, account }) => {
-    return runOrDiagnose(['gmail', subcommand, ...args], { account });
-  });
+  registerRunTool(server, { service: 'gmail', examples: '"archive", "mark-read", "labels"' });
 }

package/src/tools/sheets.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose } from './utils.js';
+import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
 
 export function registerSheetsTools(server: McpServer): void {
   server.registerTool('gog_sheets_get', {
@@ -94,15 +94,5 @@ export function registerSheetsTools(server: McpServer): void {
     return runOrDiagnose(['sheets', 'find-replace', spreadsheetId, find, replace], { account });
   });
 
-  server.registerTool('gog_sheets_run', {
-    description: 'Run any gog sheets subcommand not covered by the other tools. Run `gog sheets --help` for the full list of subcommands, or `gog sheets <subcommand> --help` for flags on a specific subcommand.',
-    annotations: { destructiveHint: true },
-    inputSchema: {
-      subcommand: z.string().describe('The gog sheets subcommand to run, e.g. "freeze", "add-tab", "rename-tab"'),
-      args: z.array(z.string()).describe('Additional positional args and flags, e.g. ["<spreadsheetId>", "--rows=1"]'),
-      account: accountParam,
-    },
-  }, async ({ subcommand, args, account }) => {
-    return runOrDiagnose(['sheets', subcommand, ...args], { account });
-  });
+  registerRunTool(server, { service: 'sheets', examples: '"freeze", "add-tab", "rename-tab"' });
 }

package/src/tools/slides.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose } from './utils.js';
+import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
 
 export function registerSlidesTools(server: McpServer): void {
   server.registerTool('gog_slides_export', {
@@ -82,15 +82,5 @@ export function registerSlidesTools(server: McpServer): void {
     return runOrDiagnose(['slides', 'read-slide', presentationId, slideId], { account });
   });
 
-  server.registerTool('gog_slides_run', {
-    description: 'Run any gog slides subcommand not covered by the other tools. Run `gog slides --help` for the full list of subcommands, or `gog slides <subcommand> --help` for flags on a specific subcommand.',
-    annotations: { destructiveHint: true },
-    inputSchema: {
-      subcommand: z.string().describe('The gog slides subcommand to run'),
-      args: z.array(z.string()).describe('Additional positional args and flags'),
-      account: accountParam,
-    },
-  }, async ({ subcommand, args, account }) => {
-    return runOrDiagnose(['slides', subcommand, ...args], { account });
-  });
+  registerRunTool(server, { service: 'slides', examples: '"add-slide", "delete-slide", "update-notes"' });
 }

package/src/tools/tasks.ts

@@ -1,6 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { accountParam, runOrDiagnose } from './utils.js';
+import { accountParam, runOrDiagnose, registerRunTool } from './utils.js';
 
 export function registerTasksTools(server: McpServer): void {
   server.registerTool('gog_tasks_lists', {
@@ -77,15 +77,5 @@ export function registerTasksTools(server: McpServer): void {
     return runOrDiagnose(['tasks', 'delete', tasklistId, taskId], { account });
   });
 
-  server.registerTool('gog_tasks_run', {
-    description: 'Run any gog tasks subcommand not covered by the other tools. Run `gog tasks --help` for the full list of subcommands, or `gog tasks <subcommand> --help` for flags on a specific subcommand.',
-    annotations: { destructiveHint: true },
-    inputSchema: {
-      subcommand: z.string().describe('The gog tasks subcommand to run, e.g. "update", "undo", "clear"'),
-      args: z.array(z.string()).describe('Additional positional args and flags'),
-      account: accountParam,
-    },
-  }, async ({ subcommand, args, account }) => {
-    return runOrDiagnose(['tasks', subcommand, ...args], { account });
-  });
+  registerRunTool(server, { service: 'tasks', examples: '"update", "undo", "clear"' });
 }

package/src/tools/utils.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { run } from '../runner.js';
 
 export type ToolResult = { content: [{ type: 'text'; text: string }] };
@@ -7,6 +8,85 @@ export const accountParam = z.string().optional().describe(
   'Google account email to use (overrides GOG_ACCOUNT env var)',
 );
 
+// Canonical ID descriptors. Use these instead of redefining the same
+// `z.string().describe('Course ID')` etc. across multiple tool files —
+// keeps descriptions in lockstep so they don't drift apart.
+export const ids = {
+  course: z.string().describe('Course ID'),
+  coursework: z.string().describe('Coursework ID'),
+  submission: z.string().describe('Submission ID'),
+  announcement: z.string().describe('Announcement ID'),
+  topic: z.string().describe('Topic ID'),
+  invitation: z.string().describe('Invitation ID'),
+  spreadsheet: z.string().describe('Spreadsheet ID (from the URL)'),
+  doc: z.string().describe('Doc ID (from the URL)'),
+  presentation: z.string().describe('Presentation ID'),
+  slide: z.string().describe('Slide ID'),
+  file: z.string().describe('File ID'),
+  message: z.string().describe('Message ID'),
+  thread: z.string().describe('Thread ID'),
+  draft: z.string().describe('Draft ID'),
+  label: z.string().describe('Label ID or name'),
+  attachment: z.string().describe('Attachment ID'),
+  comment: z.string().describe('Comment ID'),
+  meetingCode: z.string().describe('Meeting code (e.g. abc-defg-hij)'),
+  permission: z.string().describe('Permission ID'),
+  user: z.string().describe('User ID'),
+  // People API uses fully-qualified resource names ("people/c123") not bare IDs.
+  person: z.string().describe('Person resource name (people/...) or email'),
+};
+
+// Pagination param triple — appears in 20+ tools across base + extras.
+export const paginationParams = {
+  max: z.number().int().optional().describe('Max results'),
+  page: z.string().optional().describe('Page token'),
+  all: z.boolean().optional().describe('Fetch all pages'),
+};
+
+// Append pagination flags to an argv array. Mirrors the shape of
+// paginationParams above. Use together to keep call sites concise.
+export function pushPaginationFlags(
+  args: string[],
+  p: { max?: number; page?: string; all?: boolean },
+): void {
+  if (p.max !== undefined) args.push(`--max=${p.max}`);
+  if (p.page) args.push(`--page=${p.page}`);
+  if (p.all) args.push('--all');
+}
+
+// Register a `gog_<service>_run` escape-hatch tool. 11 services currently
+// register an identical-shape tool; this factory keeps them in lockstep.
+// Pass `omitAccount: true` only for auth, which doesn't take --account.
+export function registerRunTool(
+  server: McpServer,
+  options: {
+    service: string;
+    examples: string;
+    omitAccount?: boolean;
+    /** Extra sentence appended to the description (used by auth to point to gog_auth_add). */
+    note?: string;
+  },
+): void {
+  const { service, examples, omitAccount = false, note } = options;
+  const baseDescription = `Run any gog ${service} subcommand not covered by the other tools. Run \`gog ${service} --help\` for the full list of subcommands, or \`gog ${service} <subcommand> --help\` for flags on a specific subcommand.`;
+  const description = note ? `${baseDescription} ${note}` : baseDescription;
+  const inputSchema: Record<string, z.ZodTypeAny> = {
+    subcommand: z.string().describe(`The gog ${service} subcommand to run, e.g. ${examples}`),
+    args: z.array(z.string()).describe('Additional positional args and flags'),
+  };
+  if (!omitAccount) {
+    inputSchema.account = accountParam;
+  }
+  server.registerTool(`gog_${service}_run`, {
+    description,
+    annotations: { destructiveHint: true },
+    inputSchema,
+  }, async (rawArgs) => {
+    const { subcommand, args, account } = rawArgs as { subcommand: string; args: string[]; account?: string };
+    return runOrDiagnose([service, subcommand, ...args], { account });
+  });
+}
+
 export function toText(output: string): ToolResult {
   return { content: [{ type: 'text' as const, text: output }] };
 }

package/tests/helpers/{extras-harness.ts → test-harness.ts}

@@ -1,11 +1,7 @@
-// Shared test harness for `*-extra.ts` registrars across sub-packages.
+// Shared test harness for tool registrars across base + sub-packages.
 //
-// Each sub-package's extras test file follows the same shape: mock the
-// `runOrDiagnose` export from `gogcli-mcp/lib`, register the extras tools onto
-// a stub `McpServer`, capture each tool's handler into a Map, and exercise the
-// handlers with sample inputs. The `vi.mock(...)` call must stay in the
-// caller's test file (vitest hoists it at the module scope), but the
-// boilerplate around it can live here.
+// `vi.mock(...)` must stay in the caller's test file because vitest hoists
+// it at module scope, but the boilerplate around it lives here.
 import { vi } from 'vitest';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
@@ -17,7 +13,7 @@ export function toText(text: string): { content: Array<{ type: string; text: str
   return { content: [{ type: 'text', text }] };
 }
 
-export function setupExtrasHandlers(
+export function setupHandlers(
   register: (server: McpServer) => void,
 ): Map<string, ToolHandler> {
   const server = new McpServer({ name: 'test', version: '0.0.0' });

package/tests/runner.test.ts

@@ -483,6 +483,65 @@ describe('run', () => {
     }
   });
 
+  it('strips GOOGLE_APPLICATION_CREDENTIALS and *_TOKEN/*_SECRET/*_API_KEY/*_PRIVATE_KEY vars', async () => {
+    const spawner = makeSpawner(0, '{}');
+    const snapshot = {
+      GOOGLE_APPLICATION_CREDENTIALS: process.env.GOOGLE_APPLICATION_CREDENTIALS,
+      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
+      DB_PASSWORD_TOKEN: process.env.DB_PASSWORD_TOKEN,
+      AWS_SECRET: process.env.AWS_SECRET,
+      MY_PRIVATE_KEY: process.env.MY_PRIVATE_KEY,
+      BENIGN_VAR: process.env.BENIGN_VAR,
+    };
+    process.env.GOOGLE_APPLICATION_CREDENTIALS = '/path/to/sa.json';
+    process.env.ANTHROPIC_API_KEY = 'sk-ant-secret';
+    process.env.DB_PASSWORD_TOKEN = 'secret';
+    process.env.AWS_SECRET = 'secret';
+    process.env.MY_PRIVATE_KEY = 'secret';
+    process.env.BENIGN_VAR = 'hello';
+    try {
+      await run(['docs', 'cat', 'id'], { spawner });
+      const envPassed = (spawner as ReturnType<typeof vi.fn>).mock.calls[0][2].env as NodeJS.ProcessEnv;
+      expect(envPassed.GOOGLE_APPLICATION_CREDENTIALS).toBeUndefined();
+      expect(envPassed.ANTHROPIC_API_KEY).toBeUndefined();
+      expect(envPassed.DB_PASSWORD_TOKEN).toBeUndefined();
+      expect(envPassed.AWS_SECRET).toBeUndefined();
+      expect(envPassed.MY_PRIVATE_KEY).toBeUndefined();
+      expect(envPassed.BENIGN_VAR).toBe('hello');
+    } finally {
+      for (const [k, v] of Object.entries(snapshot)) {
+        if (v === undefined) delete process.env[k];
+        else process.env[k] = v;
+      }
+    }
+  });
+
+  it('redacts Bearer with quoted/encoded characters', async () => {
+    const stderrLeak = 'http 401: header was Bearer eyJ.test+slash/equal=padding more text';
+    const spawner = makeSpawner(1, '', stderrLeak);
+    try {
+      await run(['gmail', 'get', 'm1'], { spawner });
+    } catch (e) {
+      const msg = (e as Error).message;
+      expect(msg).not.toContain('eyJ.test+slash/equal=padding');
+      expect(msg).toContain('[REDACTED]');
+    }
+  });
+
+  it('redacts bearer/refresh tokens and Google API keys from stderr surfaced to the client', async () => {
+    const stderrLeak = 'request failed: Authorization: Bearer ya29.a0Ad52N3-LEAKED-TOKEN-VALUE refresh 1//0eLEAKED-REFRESH key AIzaSyDdI0hCZtE6vySjMm-WEfRq3CPzqKqqsHI extra';
+    const spawner = makeSpawner(1, '', stderrLeak);
+    try {
+      await run(['gmail', 'get', 'm1'], { spawner });
+    } catch (e) {
+      const msg = (e as Error).message;
+      expect(msg).not.toContain('ya29.a0Ad52N3-LEAKED-TOKEN-VALUE');
+      expect(msg).not.toContain('1//0eLEAKED-REFRESH');
+      expect(msg).not.toContain('AIzaSyDdI0hCZtE6vySjMm-WEfRq3CPzqKqqsHI');
+      expect(msg).toContain('[REDACTED]');
+    }
+  });
+
   it('ignores timeout if close event already settled the promise', async () => {
     vi.useFakeTimers();
     const spawner = vi.fn(() => {

package/tests/tools/auth.test.ts

@@ -1,22 +1,11 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { registerAuthTools } from '../../src/tools/auth.js';
 import * as runner from '../../src/runner.js';
+import { setupHandlers as setupHandlersBase, type ToolHandler } from '../helpers/test-harness.js';
 
 vi.mock('../../src/runner.js');
 
-type ToolHandler = (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text: string }> }>;
-
-function setupHandlers(): Map<string, ToolHandler> {
-  const server = new McpServer({ name: 'test', version: '0.0.0' });
-  const handlers = new Map<string, ToolHandler>();
-  vi.spyOn(server, 'registerTool').mockImplementation((name, _config, cb) => {
-    handlers.set(name, cb as ToolHandler);
-    return undefined as never;
-  });
-  registerAuthTools(server);
-  return handlers;
-}
+const setupHandlers = () => setupHandlersBase(registerAuthTools);
 
 beforeEach(() => vi.clearAllMocks());
 

package/tests/tools/calendar.test.ts

@@ -1,22 +1,11 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { registerCalendarTools } from '../../src/tools/calendar.js';
 import * as runner from '../../src/runner.js';
+import { setupHandlers as setupHandlersBase, type ToolHandler } from '../helpers/test-harness.js';
 
 vi.mock('../../src/runner.js');
 
-type ToolHandler = (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text: string }> }>;
-
-function setupHandlers(): Map<string, ToolHandler> {
-  const server = new McpServer({ name: 'test', version: '0.0.0' });
-  const handlers = new Map<string, ToolHandler>();
-  vi.spyOn(server, 'registerTool').mockImplementation((name, _config, cb) => {
-    handlers.set(name, cb as ToolHandler);
-    return undefined as never;
-  });
-  registerCalendarTools(server);
-  return handlers;
-}
+const setupHandlers = () => setupHandlersBase(registerCalendarTools);
 
 beforeEach(() => vi.clearAllMocks());
 

package/tests/tools/classroom.test.ts

@@ -1,22 +1,11 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { registerClassroomTools } from '../../src/tools/classroom.js';
 import * as runner from '../../src/runner.js';
+import { setupHandlers as setupHandlersBase, type ToolHandler } from '../helpers/test-harness.js';
 
 vi.mock('../../src/runner.js');
 
-type ToolHandler = (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text: string }> }>;
-
-function setupHandlers(): Map<string, ToolHandler> {
-  const server = new McpServer({ name: 'test', version: '0.0.0' });
-  const handlers = new Map<string, ToolHandler>();
-  vi.spyOn(server, 'registerTool').mockImplementation((name, _config, cb) => {
-    handlers.set(name, cb as ToolHandler);
-    return undefined as never;
-  });
-  registerClassroomTools(server);
-  return handlers;
-}
+const setupHandlers = () => setupHandlersBase(registerClassroomTools);
 
 let handlers: Map<string, ToolHandler>;
 

package/tests/tools/contacts.test.ts

@@ -1,22 +1,11 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { registerContactsTools } from '../../src/tools/contacts.js';
 import * as runner from '../../src/runner.js';
+import { setupHandlers as setupHandlersBase, type ToolHandler } from '../helpers/test-harness.js';
 
 vi.mock('../../src/runner.js');
 
-type ToolHandler = (args: Record<string, unknown>) => Promise<{ content: Array<{ type: string; text: string }> }>;
-
-function setupHandlers(): Map<string, ToolHandler> {
-  const server = new McpServer({ name: 'test', version: '0.0.0' });
-  const handlers = new Map<string, ToolHandler>();
-  vi.spyOn(server, 'registerTool').mockImplementation((name, _config, cb) => {
-    handlers.set(name, cb as ToolHandler);
-    return undefined as never;
-  });
-  registerContactsTools(server);
-  return handlers;
-}
+const setupHandlers = () => setupHandlersBase(registerContactsTools);
 
 beforeEach(() => vi.clearAllMocks());