gogcli-mcp 2.8.0 → 2.18.0

package/src/tools/utils.ts

@@ -1,8 +1,47 @@
 import { z } from 'zod';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import { errorResult, rawTextResult } from '@chrischall/mcp-utils';
 import { run } from '../runner.js';
+import type { GogArg } from '../runner.js';
 
-export type ToolResult = { content: [{ type: 'text'; text: string }] };
+// Byte size at or below which a payload stays on the plain inline flag.
+//
+// Two reasons not to route everything through a file. First, gog's semantics
+// differ between the two forms: reading a body from a file strips ALL trailing
+// newlines (measured on gog 0.34.1 — a 5-byte payload padded to 6/7/8 bytes all
+// came back as 5; tracked upstream at openclaw/gogcli#936), so a body ending in
+// "\n" cannot round-trip byte-for-byte through the file path. Second, the file
+// path costs a temp dir, a write, and a delete per call.
+//
+// The value matches the per-arg byte limit the Fly runner enforced BEFORE large
+// payloads could leave argv (the old MAX_ARG_LEN, 4096). That is deliberate:
+// every body that used to round-trip inline byte-for-byte still does, so this
+// change adds no trailing-newline regression for any body that already worked —
+// only bodies that previously exceeded the cap and hard-failed ("each arg must
+// be at most 4096 chars") now take the file path and its newline trim. The
+// runner's plain-arg cap is now 64 KiB, so a 4096-byte inline value is nowhere
+// near being rejected.
+export const PAYLOAD_INLINE_MAX = 4096;
+
+// The ONE place the inline-vs-file decision is made. Every tool that has a
+// gog `--x` / `--x-file` flag pair routes its value through here so the
+// threshold cannot drift between tools.
+//
+// Measures BYTES, not characters: the Fly runner's cap and the Linux kernel's
+// MAX_ARG_STRLEN are both byte-based, so a multibyte-heavy body (CJK, emoji)
+// would slip past a `.length` check at up to 4x its real argv cost.
+export function payloadArg(
+  inlineFlag: string,
+  fileFlag: string,
+  value: string,
+  ext?: string,
+): GogArg {
+  if (Buffer.byteLength(value, 'utf8') <= PAYLOAD_INLINE_MAX) {
+    return `--${inlineFlag}=${value}`;
+  }
+  return { kind: 'file', flag: fileFlag, contents: value, ext };
+}
 
 export const accountParam = z.string().optional().describe(
   'Google account email to use, e.g. you@gmail.com — must be the full address, not a bare username. ' +
@@ -88,16 +127,21 @@ export function registerRunTool(
   });
 }
 
-export function toText(output: string): ToolResult {
-  return { content: [{ type: 'text' as const, text: output }] };
-}
-
-export function toError(err: unknown): ToolResult {
-  return toText(err instanceof Error ? `Error: ${err.message}` : String(err));
+// The fleet-standard error text for a thrown value ("Error: <message>").
+// Pair with mcp-utils errorResult (which redacts secrets and sets
+// `isError: true`) when the text is the whole tool result.
+export function errorText(err: unknown): string {
+  return err instanceof Error ? `Error: ${err.message}` : String(err);
 }
 
 const AUTH_ERROR_PATTERN = /\b(401|unauthorized|token.*(expired|revoked)|invalid_grant)\b/i;
 
+// A DEAD refresh token — the whole account is signed out, not just a stale
+// access token that would refresh silently. This is the recurring account-wide
+// failure, so it gets its own plain-English cause + durable fix, distinct from
+// the generic 401/unauthorized case.
+const INVALID_GRANT_PATTERN = /invalid_grant|token has been expired or revoked/i;
+
 const TRANSIENT_ERROR_PATTERN =
   /\b429\b|\b5\d\d\b|\bquota\b|rateLimit|\bDEADLINE_EXCEEDED\b/i;
 
@@ -110,6 +154,20 @@ 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.';
 
+// invalid_grant means the stored REFRESH token was rejected, so re-auth is
+// mandatory (no silent recovery) and it will recur unless the root cause is
+// fixed. Name the most common cause (the 7-day limit Google puts on OAuth apps
+// still in "Testing"), offer both re-auth paths (browser + remote/headless),
+// and point at the durable fix. Keeps the literal `gog_auth_add` token so the
+// generic auth-recovery guidance still applies.
+const INVALID_GRANT_HINT =
+  '\n\nThe stored refresh token was rejected (invalid_grant): it has expired or been revoked, so the ' +
+  'whole account is signed out and re-authorization is required. The most common cause is the 7-day ' +
+  'refresh-token limit Google applies to OAuth apps whose consent screen is still in "Testing" mode. ' +
+  'Re-authorize with gog_auth_add (opens a browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless). ' +
+  'To stop this recurring, publish the OAuth consent screen to "In production" in the Google Cloud project ' +
+  'that owns the OAuth client. Ask the user if they would like to re-authenticate.';
+
 const TRANSIENT_HINT =
   '\n\nThis error is often transient. Retry the same call before trying a different approach ' +
   '(do not fall back to smaller writes or row-by-row operations).';
@@ -139,39 +197,117 @@ export function formatAccountList(raw: string): string {
   return raw.trim();
 }
 
-// Turn a thrown error into a diagnosed ToolResult: the error text, an
-// actionable hint when the failure class is recognised (auth / transient /
-// off-grid write), and the list of configured accounts. Callers that need to
-// surface a failure without going through runOrDiagnose (e.g. a pre-write
-// verification read that must abort) can reuse this so the error keeps the
-// same diagnostic quality as everywhere else.
-export async function diagnose(err: unknown): Promise<ToolResult> {
-  const errText = toError(err).content[0].text;
+// Turn a thrown error into a diagnosed error result (`isError: true`): the
+// error text, an actionable hint when the failure class is recognised (auth /
+// transient / off-grid write), and the list of configured accounts. Callers
+// that need to surface a failure without going through runOrDiagnose (e.g. a
+// pre-write verification read that must abort) can reuse this so the error
+// keeps the same diagnostic quality as everywhere else.
+export async function diagnose(err: unknown): Promise<CallToolResult> {
+  const errText = errorText(err);
+  const isInvalidGrant = INVALID_GRANT_PATTERN.test(errText);
   const isAuthError = AUTH_ERROR_PATTERN.test(errText);
   const isTransientError = !isAuthError && TRANSIENT_ERROR_PATTERN.test(errText);
   const isGridLimitError = GRID_LIMIT_ERROR_PATTERN.test(errText);
-  const hint = isAuthError
-    ? AUTH_HINT
-    : isTransientError
-      ? TRANSIENT_HINT
-      : isGridLimitError
-        ? GRID_LIMIT_HINT
-        : '';
+  const hint = isInvalidGrant
+    ? INVALID_GRANT_HINT
+    : isAuthError
+      ? AUTH_HINT
+      : isTransientError
+        ? TRANSIENT_HINT
+        : isGridLimitError
+          ? GRID_LIMIT_HINT
+          : '';
   try {
     const accounts = formatAccountList(await run(['auth', 'list']));
-    return toText(`${errText}\n\nConfigured accounts:\n${accounts || '(none)'}${hint}`);
+    return errorResult(`${errText}\n\nConfigured accounts:\n${accounts || '(none)'}${hint}`);
   } catch {
-    return toText(`${errText}${hint}`);
+    return errorResult(`${errText}${hint}`);
   }
 }
 
 export async function runOrDiagnose(
-  args: string[],
+  args: GogArg[],
   options: { account?: string },
-): Promise<ToolResult> {
+): Promise<CallToolResult> {
   try {
-    return toText(await run(args, options));
+    return rawTextResult(await run(args, options));
   } catch (err) {
     return diagnose(err);
   }
 }
+
+// Google puts a 7-day cap on refresh tokens issued by OAuth apps whose consent
+// screen is still in "Testing" — the recurring account-wide sign-out this tool
+// exists to warn about. Once the token is this old and still valid, expiry is
+// imminent, so surface it before it becomes a hard failure mid-task.
+const REFRESH_TOKEN_TESTING_TTL_DAYS = 7;
+const HEALTH_WARN_AGE_DAYS = 6;
+const MS_PER_DAY = 86_400_000;
+
+interface AuthHealthAccount {
+  email?: string;
+  created_at?: string;
+  valid?: boolean;
+  error?: string;
+}
+
+// Days between an ISO timestamp and `now`, or null if unparseable/absent.
+function ageInDays(createdAt: string | undefined, now: number): number | null {
+  if (!createdAt) return null;
+  const t = Date.parse(createdAt);
+  if (Number.isNaN(t)) return null;
+  return (now - t) / MS_PER_DAY;
+}
+
+function formatOneAccountHealth(a: AuthHealthAccount, now: number): string {
+  const email = a.email ?? '(unknown account)';
+  const age = ageInDays(a.created_at, now);
+  const ageStr = age === null ? '' : ` Authorized ${age.toFixed(1)} day(s) ago.`;
+
+  if (a.valid === false) {
+    // Map the dead-refresh-token error to a plain cause; fall back to the raw
+    // (already token-redacted by run()) error for anything else.
+    const cause = INVALID_GRANT_PATTERN.test(a.error ?? '')
+      ? 'refresh token expired or revoked — commonly the 7-day limit on OAuth consent screens still in "Testing" mode'
+      : (a.error?.trim() || 'unknown error');
+    return `✗ ${email}: NEEDS RE-AUTH — ${cause}.${ageStr} ` +
+      'Re-authorize with gog_auth_add (browser) or gog_auth_add_url + gog_auth_add_complete (remote/headless).';
+  }
+
+  if (a.valid === true) {
+    let line = `✓ ${email}: token valid.${ageStr}`;
+    if (age !== null && age >= HEALTH_WARN_AGE_DAYS) {
+      const est = new Date(Date.parse(a.created_at as string) + REFRESH_TOKEN_TESTING_TTL_DAYS * MS_PER_DAY)
+        .toISOString()
+        .slice(0, 10);
+      line += ` ⚠ Approaching the 7-day refresh-token limit for OAuth apps in "Testing" mode ` +
+        `(if that applies, expect expiry around ${est}). Re-authorize soon, or publish the OAuth ` +
+        'consent screen to "In production" to stop the weekly expiry.';
+    }
+    return line;
+  }
+
+  // valid absent — the caller ran without --check (or gog omitted the field).
+  return `? ${email}: token validity unknown.${ageStr} Run this check again to probe it live.`;
+}
+
+// Turn `gog auth list --check --json` into a per-account health summary:
+// validity, a mapped cause for dead tokens, token age, and a pre-expiry warning
+// near the 7-day testing-mode cliff. Only email/created_at/valid/error are read
+// — scopes/subject never appear in the summary. Falls back to trimmed raw text
+// when the output isn't the expected JSON shape.
+export function formatAuthHealth(raw: string, now: number): string {
+  let accounts: AuthHealthAccount[];
+  try {
+    const parsed = JSON.parse(raw) as { accounts?: unknown };
+    if (!Array.isArray(parsed?.accounts)) return raw.trim();
+    accounts = parsed.accounts as AuthHealthAccount[];
+  } catch {
+    return raw.trim();
+  }
+  if (accounts.length === 0) {
+    return 'No Google accounts are configured. Use gog_auth_add to authorize one.';
+  }
+  return accounts.map((a) => formatOneAccountHealth(a, now)).join('\n\n');
+}

package/src/worker.ts

@@ -0,0 +1,99 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpAgent } from 'agents/mcp';
+import { OAuthProvider } from '@cloudflare/workers-oauth-provider';
+import { handleAuthorize } from '@chrischall/mcp-connector';
+import type { ToolRegistrar } from '@chrischall/mcp-utils';
+import {
+  BASE_TOOL_REGISTRARS,
+  authToolsFor,
+  registerSheetsTools,
+  registerGmailTools,
+  registerDriveTools,
+  registerDocsTools,
+} from './lib.js';
+import { registerExtraSheetsTools } from '../../gogcli-mcp-sheets/src/tools/sheets-extra.js';
+import { registerExtraGmailTools } from '../../gogcli-mcp-gmail/src/tools/gmail-extra.js';
+import { registerExtraDriveTools } from '../../gogcli-mcp-drive/src/tools/drive-extra.js';
+import { registerExtraDocsTools } from '../../gogcli-mcp-docs/src/tools/docs-extra.js';
+import { makeFlyExecutor, wrapServer } from './connector-runtime.js';
+import { gogAuth, type GogProps } from './connector-auth.js';
+
+// The Cloudflare remote-connector entrypoint for gogcli-mcp.
+//
+// It reuses the EXISTING transport-neutral tool registrars UNCHANGED and executes
+// every assembled `gog` arg-array by forwarding it to a Fly.io backend (a Worker
+// cannot spawn processes). The bridge is the `runExecutor` AsyncLocalStorage seam
+// in `runner.ts`: `wrapServer` scopes each tool handler in `runExecutor.run(...)`
+// so the handler's `run()` forwards to the per-session Fly executor.
+//
+// One Worker serves several MCP endpoints under one OAuth login, each a distinct
+// tool set backed by its own Durable Object:
+//   /mcp          all-services base (BASE_TOOL_REGISTRARS)
+//   /mcp/sheets   auth + Sheets base + Sheets extras
+//   /mcp/gmail    auth + Gmail base + Gmail extras
+//   /mcp/drive    auth + Drive base + Drive extras
+//   /mcp/docs     auth + Docs base + Docs extras
+// Each per-service path exposes the SAME tool set as that sub-package's stdio
+// server, so the ~50-70 extras per service are reachable without swamping one
+// connector with all ~360 tools at once. Add whichever paths you want as separate
+// connectors in claude.ai (each authorizes with the same connector key).
+
+const VERSION = '2.18.0'; // x-release-please-version
+
+// Build an McpAgent subclass whose init() registers `registrars` onto its server,
+// each handler wrapped in the ALS scope carrying the per-session Fly executor.
+// (Kept in worker.ts, not connector-runtime.ts, because it imports the Worker-only
+// `agents` runtime; the node-testable helpers stay in connector-runtime.ts.)
+function makeAgent(registrars: ToolRegistrar[]): typeof McpAgent {
+  class GogAgent extends McpAgent<unknown, unknown, GogProps> {
+    server = new McpServer({ name: 'gogcli-mcp', version: VERSION });
+    async init() {
+      const executor = makeFlyExecutor((this.env as { FLY_ENDPOINT: string }).FLY_ENDPOINT, this.props.key);
+      const wrapped = wrapServer(this.server, executor);
+      for (const register of registrars) register(wrapped);
+    }
+  }
+  return GogAgent as unknown as typeof McpAgent;
+}
+
+// auth + <service> base + <service> extras — the exact set each sub-package's
+// stdio server exposes. The auth registrar is bound to THIS service's default
+// `services` (least-privilege): a per-service connector re-auths requesting only
+// its own scopes, so one unregistered scope for a service it doesn't wrap can't
+// poison its re-auth with invalid_scope. The base /mcp agent keeps 'all'.
+const svc = (service: string, base: ToolRegistrar, extra: ToolRegistrar): ToolRegistrar[] =>
+  [authToolsFor(service), base, extra];
+
+export class GogcliMcpAgent extends makeAgent(BASE_TOOL_REGISTRARS) {}
+export class GogcliSheetsAgent extends makeAgent(svc('sheets', registerSheetsTools, registerExtraSheetsTools)) {}
+export class GogcliGmailAgent extends makeAgent(svc('gmail', registerGmailTools, registerExtraGmailTools)) {}
+export class GogcliDriveAgent extends makeAgent(svc('drive,driveactivity,drivelabels', registerDriveTools, registerExtraDriveTools)) {}
+export class GogcliDocsAgent extends makeAgent(svc('docs', registerDocsTools, registerExtraDocsTools)) {}
+
+const defaultHandler = {
+  fetch(request: Request, env: unknown): Response | Promise<Response> {
+    const url = new URL(request.url);
+    if (url.pathname === '/authorize') return handleAuthorize(request, env, gogAuth);
+    return new Response('Not found', { status: 404 });
+  },
+};
+
+// NOTE: OAuthProvider matches apiHandlers by PREFIX and returns the FIRST match,
+// so the specific per-service paths MUST be listed before the base `/mcp`
+// (otherwise `/mcp` greedily swallows `/mcp/sheets`).
+const handler = new OAuthProvider({
+  apiHandlers: {
+    '/mcp/sheets': GogcliSheetsAgent.serve('/mcp/sheets', { binding: 'SHEETS_MCP' }) as never,
+    '/mcp/gmail': GogcliGmailAgent.serve('/mcp/gmail', { binding: 'GMAIL_MCP' }) as never,
+    '/mcp/drive': GogcliDriveAgent.serve('/mcp/drive', { binding: 'DRIVE_MCP' }) as never,
+    '/mcp/docs': GogcliDocsAgent.serve('/mcp/docs', { binding: 'DOCS_MCP' }) as never,
+    '/mcp': GogcliMcpAgent.serve('/mcp') as never,
+    '/sse': GogcliMcpAgent.serveSSE('/sse') as never,
+  },
+  defaultHandler: defaultHandler as never,
+  authorizeEndpoint: '/authorize',
+  tokenEndpoint: '/token',
+  clientRegistrationEndpoint: '/register',
+});
+
+export default handler;

package/tests/connector-auth.test.ts

@@ -0,0 +1,28 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { gogAuth } from '../src/connector-auth.js';
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('gogAuth.login', () => {
+  const env = { FLY_ENDPOINT: 'https://runner.example' };
+
+  it('verifies the key against the backend /health and returns the props', async () => {
+    const fetchMock = vi.fn(async () => ({ ok: true }));
+    vi.stubGlobal('fetch', fetchMock);
+
+    const props = await gogAuth.login({ key: 'my-key' }, env);
+    expect(props).toEqual({ key: 'my-key' });
+    expect(fetchMock).toHaveBeenCalledWith('https://runner.example/health', {
+      headers: { Authorization: 'Bearer my-key' },
+    });
+  });
+
+  it('throws when the backend rejects the key', async () => {
+    vi.stubGlobal('fetch', vi.fn(async () => ({ ok: false })));
+    await expect(gogAuth.login({ key: 'bad' }, env)).rejects.toThrow(
+      'Invalid connector key',
+    );
+  });
+});