mcp-google-multi 6.0.0-alpha.2 → 6.0.0-alpha.21

package/dist/doctor.js

@@ -6,6 +6,9 @@ import { deriveAccountHealth } from './tools/accounts-tool.js';
 import { peekMasterKeyProvenance, deleteMasterKeyMaterial } from './master-key.js';
 import { hasToken } from './token-store.js';
 import { configDir } from './config-file.js';
+import { probeApiEnablement } from './api-probe.js';
+import { resolveHttpConfig, HttpConfigError } from './http-config.js';
+import { parseOwnerEmails } from './http-transport.js';
 const MIN_NODE_MAJOR = 22;
 const DEFAULT_DEPS = {
     nodeVersion: process.versions.node,
@@ -23,17 +26,44 @@ const DEFAULT_DEPS = {
     masterKeyProvenance: () => peekMasterKeyProvenance(),
     anyTokensExist: (aliases) => aliases.some((a) => hasToken(a)),
     fileExists: fs.existsSync,
+    probeApi: (alias) => probeApiEnablement(alias),
+    probeHttp: (cfg) => probeHttpEndpoints(cfg),
 };
+/** §7 live check: the advertised OAuth metadata must derive from MCP_PUBLIC_URL
+ * exactly — one mismatch between PRM `resource` / AS `issuer` and what clients
+ * compute from the public URL is the perpetual-401 interop bug (BR4). */
+async function probeHttpEndpoints(cfg) {
+    try {
+        const prmRes = await fetch(`${cfg.publicUrl}/.well-known/oauth-protected-resource`, {
+            signal: AbortSignal.timeout(2000),
+            redirect: 'manual',
+        });
+        if (!prmRes.ok)
+            return { ok: false, problem: `PRM endpoint returned HTTP ${prmRes.status}` };
+        const prm = (await prmRes.json());
+        if (prm.resource !== cfg.resourceUri) {
+            return { ok: false, problem: `PRM resource "${prm.resource}" does not match the expected "${cfg.resourceUri}"` };
+        }
+        const asRes = await fetch(`${cfg.publicUrl}/.well-known/oauth-authorization-server`, {
+            signal: AbortSignal.timeout(2000),
+            redirect: 'manual',
+        });
+        if (!asRes.ok)
+            return { ok: false, problem: `AS metadata endpoint returned HTTP ${asRes.status}` };
+        const as = (await asRes.json());
+        if (as.issuer !== cfg.publicUrl) {
+            return { ok: false, problem: `AS metadata issuer "${as.issuer}" does not match the public URL "${cfg.publicUrl}"` };
+        }
+        return { ok: true };
+    }
+    catch {
+        return { ok: false, unreachable: true };
+    }
+}
 /** Console deep-link to enable one API (section-6 hint, error taxonomy B10). */
 export function apiEnableLink(api) {
     return `https://console.cloud.google.com/apis/library/${api}.googleapis.com`;
 }
-function transportsFrom(env) {
-    return (env.MCP_TRANSPORT ?? 'stdio')
-        .split(',')
-        .map((s) => s.trim().toLowerCase())
-        .filter(Boolean);
-}
 const LEGACY_ENV_KEYS = ['GOOGLE_ACCOUNTS', 'GOOGLE_OPTIONAL_SCOPES', 'GOOGLE_ADMIN_ACCOUNTS'];
 function sectionRuntime(deps) {
     const major = Number.parseInt(deps.nodeVersion.split('.')[0] ?? '0', 10);
@@ -163,6 +193,9 @@ async function sectionApiEnablement(deps, aliases) {
         // Network / transient: WARN with the target, never crash the report.
         return { id: 6, title: 'API enablement', verdict: 'warn', lines: [`Probe could not complete: ${e?.message ?? e}`] };
     }
+    if (results.length === 0) {
+        return { id: 6, title: 'API enablement', verdict: 'unknown', lines: [`No probeable service scopes granted on "${healthy}".`] };
+    }
     const disabled = results.filter((r) => r.notEnabled);
     const lines = results.map((r) => `${r.service}: ${r.ok ? 'enabled' : r.notEnabled ? 'NOT ENABLED' : `unknown (${r.message ?? 'error'})`}`);
     if (disabled.length > 0) {
@@ -177,15 +210,65 @@ async function sectionApiEnablement(deps, aliases) {
     }
     return { id: 6, title: 'API enablement', verdict: 'ok', lines: lines.length ? lines : ['(probed account, all enabled)'] };
 }
-function sectionHttpDeferred(deps) {
-    if (!transportsFrom(deps.env).includes('http'))
+async function sectionHttp(deps, aliases) {
+    const raw = (deps.env.MCP_TRANSPORT ?? '').trim().toLowerCase();
+    if (raw === '' || raw === 'stdio')
         return null;
-    return {
-        id: 7,
-        title: 'HTTP',
-        verdict: 'unknown',
-        lines: ['HTTP diagnostics (MCP_PUBLIC_URL canonicalization, MCP_OWNER_EMAILS, PRM/AS-metadata self-fetch) land with the OAuth authorization server (not yet built).'],
-    };
+    let cfg;
+    try {
+        cfg = resolveHttpConfig(deps.env);
+    }
+    catch (err) {
+        return {
+            id: 7,
+            title: 'HTTP',
+            verdict: 'fail',
+            slug: err instanceof HttpConfigError ? err.slug : 'E_HTTP_CONFIG',
+            lines: [err.message],
+            hint: 'Fix the MCP_* variable above and re-run doctor.',
+        };
+    }
+    const lines = [`bind ${cfg.host}:${cfg.port}, public URL ${cfg.publicUrl} (resource ${cfg.resourceUri})`];
+    let verdict = 'ok';
+    let slug;
+    const hints = [];
+    const owners = parseOwnerEmails(deps.env);
+    if (owners.length === 0) {
+        verdict = 'fail';
+        slug = 'E_OWNER_EMAILS_REQUIRED';
+        lines.push('MCP_OWNER_EMAILS is empty — nobody can pass the owner gate.');
+        hints.push('Set MCP_OWNER_EMAILS to the Google email(s) allowed to authenticate.');
+    }
+    else {
+        const known = new Set(aliases.map((a) => deps.accountHealth(a).email.toLowerCase()));
+        const strangers = known.size > 0 ? owners.filter((o) => !known.has(o)) : [];
+        lines.push(`owner gate: ${owners.length} email(s)${strangers.length ? `, ${strangers.length} matching no configured account` : ''}`);
+        if (strangers.length > 0) {
+            verdict = 'warn';
+            slug = 'W_OWNER_EMAIL_UNKNOWN';
+            hints.push(`Owner entry ${strangers.join(', ')} is not a configured account email. ` +
+                'If that is a misspelling of your account email, sign-in will be refused — fix MCP_OWNER_EMAILS.');
+        }
+    }
+    if (verdict !== 'fail' && deps.probeHttp) {
+        const probe = await deps.probeHttp(cfg);
+        if (probe.ok) {
+            lines.push('live: PRM + AS metadata verified at the public URL');
+        }
+        else if (probe.unreachable) {
+            if (verdict === 'ok')
+                verdict = 'unknown';
+            lines.push(`live: ${cfg.publicUrl} not reachable (server not running?)`);
+            hints.push('Start the server (MCP_TRANSPORT=http) and re-run doctor for the live endpoint checks.');
+        }
+        else {
+            verdict = 'fail';
+            slug = 'E_HTTP_METADATA_MISMATCH';
+            lines.push(`live: ${probe.problem}`);
+            hints.push('The advertised OAuth metadata must derive from MCP_PUBLIC_URL exactly; restart the server after changing it.');
+        }
+    }
+    return { id: 7, title: 'HTTP', verdict, ...(slug ? { slug } : {}), lines, ...(hints.length ? { hint: hints.join('\n') } : {}) };
 }
 const RANK = { ok: 0, unknown: 0, warn: 1, fail: 2 };
 /** Roll section verdicts to an overall verdict. `unknown` never worsens it. */
@@ -209,7 +292,7 @@ export async function runDiagnostics(deps = DEFAULT_DEPS) {
         sections.push(tokens, scopes);
         sections.push(await sectionApiEnablement(deps, aliases));
     }
-    const http = sectionHttpDeferred(deps);
+    const http = await sectionHttp(deps, aliases);
     if (http)
         sections.push(http);
     return { verdict: overallVerdict(sections), sections };

package/dist/http-transport.d.ts

@@ -1,6 +1,7 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { HttpConfig } from './http-config.js';
+import { type ArgShape } from './arg-normalize.js';
 export type AuthOutcome = {
     ok: true;
 } | {
@@ -28,6 +29,8 @@ export interface HttpHostOptions {
     /** Deadline for a single /mcp dispatch; a hung handler past this releases the
      * shared lock instead of wedging the transport (default 120s). */
     dispatchTimeoutMs?: number;
+    /** tools/call argument-key normalization lookup (arg-normalize.ts); absent = off. */
+    argShapeFor?: (tool: string) => ArgShape | undefined;
 }
 export declare function parseOwnerEmails(env?: NodeJS.ProcessEnv): string[];
 /** Front guard: an Origin, if present, must be allowlisted; a Host must be

package/dist/http-transport.js

@@ -5,6 +5,7 @@
 // loopback-owner authenticator so the local-HTTP model works before the AS lands.
 import { createServer } from 'node:http';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { withArgNormalization } from './arg-normalize.js';
 // A hung handler that keeps the connection open would otherwise hold the global
 // serialize() lock forever. Generous by default so slow-but-valid calls (large
 // Drive exports, fan-out) still finish; the point is only to guarantee release.
@@ -182,7 +183,7 @@ export class HttpTransportHost {
                 timer = setTimeout(() => resolve('timeout'), deadlineMs);
                 timer.unref?.();
             });
-            await this.opts.server.connect(transport);
+            await this.opts.server.connect(this.opts.argShapeFor ? withArgNormalization(transport, this.opts.argShapeFor, this.opts.log) : transport);
             // Reflect the dispatch into a non-rejecting arm: if the deadline wins the
             // race, an orphaned handler settling later must not surface as an unhandled
             // rejection — but a genuine dispatch error still propagates (rethrown below).

package/dist/index.js

@@ -20,6 +20,7 @@ import { isAllowed, describePolicy } from './write-control.js';
 import { buildIdentityContext } from './identity.js';
 import { registerSetupPrompt } from './setup-prompt.js';
 import { applyNetTuning } from './net-tuning.js';
+import { argNormalizationEnabled, withArgNormalization } from './arg-normalize.js';
 applyNetTuning();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8'));
@@ -189,7 +190,8 @@ async function main() {
         const registry = buildRegistry(server, buildIdentityContext(process.env, { transport: 'stdio' }));
         registry.installListHandler();
         registerSetupPrompt(server);
-        await server.connect(new StdioServerTransport());
+        const stdioTransport = new StdioServerTransport();
+        await server.connect(argNormalizationEnabled() ? withArgNormalization(stdioTransport, (n) => registry.argShape(n)) : stdioTransport);
     }
     if (wantHttp) {
         const { HttpTransportHost, parseOwnerEmails } = await import('./http-transport.js');
@@ -280,6 +282,7 @@ async function main() {
             authenticate: authServer.authenticate,
             routes: authServer.routes,
             log: (l) => process.stderr.write(`[http] ${l}\n`),
+            argShapeFor: argNormalizationEnabled() ? (n) => registry.argShape(n) : undefined,
         });
         await host.start();
         process.stderr.write(`HTTP transport listening on http://${httpCfg.host}:${httpCfg.port} (public ${httpCfg.publicUrl})\n`);

package/dist/oauth-consent.d.ts

@@ -1,6 +1,4 @@
 import { OAuth2Client } from 'googleapis-common';
-export declare const LOOPBACK_PORT = 4242;
-export declare const LOOPBACK_REDIRECT = "http://localhost:4242/oauth2callback";
 /** GOOGLE_CLIENT_ID/SECRET absent — caller maps to E_CLIENT_CREDENTIALS_MISSING. */
 export declare class ClientCredentialsMissingError extends Error {
     constructor();
@@ -14,15 +12,32 @@ export declare class ConsentTimeoutError extends Error {
 export declare class ConsentDeniedError extends Error {
     constructor(reason: string);
 }
+export declare const TESTING_MODE_WARNING: string;
 export declare function hasClientCredentials(): boolean;
-/** Build the loopback OAuth2 client from env credentials (throws if unset). */
-export declare function buildConsentClient(): OAuth2Client;
 /**
- * Start the loopback server, await the OAuth redirect, validate the CSRF
- * `state` (RFC 6749 §10.12), and exchange the code. Returns the token set for
- * the caller to persist. Never process.exit's (safe inside a live server) and
- * times out so a stalled consent can't wedge a tool call.
+ * Build the loopback OAuth2 client from env credentials (throws if unset).
+ * `redirect` comes from openLoopbackConsent(): the port is only known once the
+ * listener is bound.
  */
-export declare function awaitLoopbackConsent(client: OAuth2Client, expectedState: string, opts?: {
+export declare function buildConsentClient(redirect: string): OAuth2Client;
+export interface LoopbackConsent {
+    /** `http://localhost:<ephemeral port>/oauth2callback` — build the auth URL from this. */
+    redirect: string;
+    /**
+     * Await the OAuth redirect, validate the CSRF `state` (RFC 6749 §10.12), and
+     * exchange the code. Returns the token set for the caller to persist.
+     */
+    finish(client: OAuth2Client, expectedState: string): Promise<Record<string, unknown>>;
+    /**
+     * Abandon the consent: shuts the listener down WITHOUT settling finish(), so
+     * an abandoned flow can never surface as an unhandled rejection later.
+     */
+    close(): void;
+}
+/**
+ * Bind the loopback listener first (ephemeral port), so the redirect URI is
+ * known before the auth URL is built and the callback can't race the browser.
+ */
+export declare function openLoopbackConsent(opts?: {
     timeoutMs?: number;
-}): Promise<Record<string, unknown>>;
+}): Promise<LoopbackConsent>;

package/dist/oauth-consent.js

@@ -2,13 +2,11 @@ import { OAuth2Client } from 'googleapis-common';
 import http from 'node:http';
 import { URL } from 'node:url';
 // Shared loopback OAuth consent (leg C of cc-auth), used by the account wizard
-// (B7). The `auth --account` CLI keeps its own inline copy for now; this module
-// is the reusable, live-server-safe form (throws typed errors instead of
-// process.exit, and times out so a never-completed consent can't wedge a tool
-// call forever). The redirect matches the CLI exactly so an existing registered
-// Desktop client keeps working.
-export const LOOPBACK_PORT = 4242;
-export const LOOPBACK_REDIRECT = `http://localhost:${LOOPBACK_PORT}/oauth2callback`;
+// (B7) and the `auth --account` CLI. Live-server-safe: typed errors instead of
+// process.exit, and a timeout so a never-completed consent can't wedge a tool
+// call forever. The listener binds an EPHEMERAL loopback port (RFC 8252 §7.3;
+// Google Desktop clients accept any http://localhost:<port> redirect), so a
+// second local process on a fixed port can never break auth.
 /** GOOGLE_CLIENT_ID/SECRET absent — caller maps to E_CLIENT_CREDENTIALS_MISSING. */
 export class ClientCredentialsMissingError extends Error {
     constructor() {
@@ -17,7 +15,7 @@ export class ClientCredentialsMissingError extends Error {
 }
 export class LoopbackPortInUseError extends Error {
     constructor() {
-        super(`E_LOOPBACK_PORT_IN_USE: port ${LOOPBACK_PORT} is already in use; close the other process and retry.`);
+        super('E_LOOPBACK_PORT_IN_USE: the loopback consent listener could not bind a port; retry.');
     }
 }
 export class ConsentTimeoutError extends Error {
@@ -30,80 +28,128 @@ export class ConsentDeniedError extends Error {
         super(`E_CONSENT_DENIED: ${reason}`);
     }
 }
+// Surfaced after every successful consent: the expiry is invisible until the
+// token dies a week later as reauth_required, so the moment of success is the
+// one place the warning is guaranteed to be seen. Full walkthrough in
+// docs/google-cloud-setup.md.
+export const TESTING_MODE_WARNING = 'Heads-up: while your OAuth client\'s Publishing status is "Testing", Google expires refresh tokens after 7 days (weekly re-auth for every account). ' +
+    'When your setup works, set it to "In production" at https://console.cloud.google.com/auth/audience. ' +
+    'No verification review is needed for personal use; see docs/google-cloud-setup.md.';
 export function hasClientCredentials() {
     return Boolean(process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET);
 }
-/** Build the loopback OAuth2 client from env credentials (throws if unset). */
-export function buildConsentClient() {
+/**
+ * Build the loopback OAuth2 client from env credentials (throws if unset).
+ * `redirect` comes from openLoopbackConsent(): the port is only known once the
+ * listener is bound.
+ */
+export function buildConsentClient(redirect) {
     if (!hasClientCredentials())
         throw new ClientCredentialsMissingError();
-    return new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, LOOPBACK_REDIRECT);
+    return new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, redirect);
 }
 /**
- * Start the loopback server, await the OAuth redirect, validate the CSRF
- * `state` (RFC 6749 §10.12), and exchange the code. Returns the token set for
- * the caller to persist. Never process.exit's (safe inside a live server) and
- * times out so a stalled consent can't wedge a tool call.
+ * Bind the loopback listener first (ephemeral port), so the redirect URI is
+ * known before the auth URL is built and the callback can't race the browser.
  */
-export function awaitLoopbackConsent(client, expectedState, opts = {}) {
+export function openLoopbackConsent(opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 5 * 60_000;
-    return new Promise((resolve, reject) => {
+    return new Promise((resolveOpen, rejectOpen) => {
+        let redirect = '';
         let timer;
+        let closed = false;
+        let pending;
+        const shutdown = () => {
+            if (closed)
+                return;
+            closed = true;
+            if (timer)
+                clearTimeout(timer);
+            server.close();
+            server.closeAllConnections();
+        };
+        const fail = (err) => {
+            const p = pending;
+            pending = undefined;
+            shutdown();
+            p?.reject(err);
+        };
         const server = http.createServer(async (req, res) => {
             if (!req.url || !req.url.startsWith('/oauth2callback')) {
                 res.writeHead(404).end();
                 return;
             }
+            if (!pending) {
+                // Only reachable if something other than our own browser launch hit
+                // the port before finish() armed the exchange; nothing to do with it.
+                res.writeHead(503).end();
+                return;
+            }
+            const p = pending;
             const done = (code, body) => {
                 res.writeHead(code, { 'Content-Type': 'text/html' });
                 res.end(body);
-                if (timer)
-                    clearTimeout(timer);
-                server.close();
-                server.closeAllConnections();
             };
             try {
-                const qs = new URL(req.url, LOOPBACK_REDIRECT).searchParams;
+                const qs = new URL(req.url, redirect).searchParams;
                 const error = qs.get('error');
                 if (error) {
                     done(400, `<p>Authorization denied: ${error}</p>`);
-                    reject(new ConsentDeniedError(error));
+                    fail(new ConsentDeniedError(error));
                     return;
                 }
                 const returnedState = qs.get('state');
-                if (returnedState !== expectedState) {
-                    done(400, '<p>State mismatch — possible CSRF attempt. Aborting.</p>');
-                    reject(new Error('E_OAUTH_STATE_MISMATCH: OAuth state token mismatch'));
+                if (returnedState !== p.expectedState) {
+                    done(400, '<p>State mismatch: possible CSRF attempt. Aborting.</p>');
+                    fail(new Error('E_OAUTH_STATE_MISMATCH: OAuth state token mismatch'));
                     return;
                 }
                 const code = qs.get('code');
                 if (!code) {
                     done(400, '<p>No authorization code received.</p>');
-                    reject(new ConsentDeniedError('no authorization code received'));
+                    fail(new ConsentDeniedError('no authorization code received'));
                     return;
                 }
-                const { tokens } = await client.getToken(code);
+                const { tokens } = await p.client.getToken(code);
                 done(200, '<h2>Authentication successful!</h2><p>You can close this tab.</p>');
-                resolve(tokens);
+                pending = undefined;
+                shutdown();
+                p.resolve(tokens);
             }
             catch (e) {
                 done(500, '<p>Internal error during authentication.</p>');
-                reject(e);
+                fail(e);
             }
         });
         server.on('error', (err) => {
-            if (timer)
-                clearTimeout(timer);
-            reject(err.code === 'EADDRINUSE' ? new LoopbackPortInUseError() : err);
+            const mapped = err.code === 'EADDRINUSE' ? new LoopbackPortInUseError() : err;
+            if (pending) {
+                fail(mapped);
+            }
+            else {
+                shutdown();
+                rejectOpen(mapped);
+            }
         });
-        server.listen(LOOPBACK_PORT, '127.0.0.1', () => {
-            timer = setTimeout(() => {
-                server.close();
-                server.closeAllConnections();
-                reject(new ConsentTimeoutError());
-            }, timeoutMs);
+        // Bind to loopback only — never expose the OAuth callback to the local network.
+        server.listen(0, '127.0.0.1', () => {
+            redirect = `http://localhost:${server.address().port}/oauth2callback`;
+            timer = setTimeout(() => fail(new ConsentTimeoutError()), timeoutMs);
             // unref so a pending consent never keeps the process alive on its own.
             timer.unref?.();
+            resolveOpen({
+                redirect,
+                finish(client, expectedState) {
+                    return new Promise((resolve, reject) => {
+                        if (closed) {
+                            reject(new ConsentTimeoutError());
+                            return;
+                        }
+                        pending = { client, expectedState, resolve, reject };
+                    });
+                },
+                close: shutdown,
+            });
         });
     });
 }

package/dist/registry.d.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { type Policy } from './write-control.js';
+import type { ArgShape } from './arg-normalize.js';
 export type Cud = 'read' | 'create' | 'update' | 'delete';
 export type DiscoveryMode = 'lazy' | 'curated' | 'eager';
 export declare function resolveDiscoveryMode(env?: NodeJS.ProcessEnv): DiscoveryMode;
@@ -38,6 +39,7 @@ export declare class ToolRegistry {
     readonly registerTool: McpServer['registerTool'];
     private readonly revealed;
     private readonly jsonSchemaCache;
+    private readonly argShapeCache;
     private readonly compactOutput;
     private registeringMeta;
     /** Configured visibility mode (GOOGLE_DISCOVERY); default lazy = v5 exact. */
@@ -48,7 +50,17 @@ export declare class ToolRegistry {
     constructor(server: McpServer, policy: Policy, mode?: DiscoveryMode);
     registerMeta: McpServer['registerTool'];
     services(): string[];
+    /** Declared input-schema keys + scalar kinds for one tool (tools/call arg
+     * normalization; the kind drives value coercion on renamed keys). */
+    argShape(name: string): ArgShape | undefined;
     catalog(service: string, query?: string): CatalogOperation[];
+    /** Op-name vocabulary for a service, split by provenance so the capped
+     * discover descriptions can list curated ops and only summarize the
+     * generated long tail. */
+    opNames(service: string): {
+        curated: string[];
+        generated: string[];
+    };
     reveal(service: string): boolean;
     /** discover_all: advertise the full curated set at once. Idempotent. */
     expand(): boolean;

package/dist/registry.js

@@ -4,6 +4,11 @@ import { isAllowed, writeDisabledResult, IRREVERSIBLE_TOOLS } from './write-cont
 import { getAccountSet, refreshAccountSetIfStale } from './accounts.js';
 import { compactResult, trimEnabled } from './trim.js';
 import { fanoutAccountField, invalidAccountsResult, parseAccountSelector, runFanout } from './fanout.js';
+import { MAX_RESPONSE_CHARS } from './executor.js';
+// Client-side result budget advertised for tools that do not declare their own
+// (fat readers do; see trim.ts). ~50k chars stays well inside a default client
+// context limit while leaving room for real list payloads.
+const DEFAULT_MAX_RESULT_CHARS = 50_000;
 const DISCOVERY_MODES = ['lazy', 'curated', 'eager'];
 export function resolveDiscoveryMode(env = process.env) {
     const raw = (env.GOOGLE_DISCOVERY ?? 'lazy').trim();
@@ -33,6 +38,23 @@ const SERVICE_OVERRIDES = {
 };
 // read tools that write local files — same savePath fanned across accounts would clobber
 const FANOUT_EXCLUDE = new Set(['gmail_download_attachment', 'drive_download', 'drive_export']);
+/** Unwrap optional/default/nullable to the declared scalar kind (zod 4 defs). */
+function scalarKindOf(field) {
+    let cur = field;
+    for (let i = 0; i < 4 && cur?._zod?.def; i++) {
+        const def = cur._zod.def;
+        if (def.type === 'number')
+            return 'number';
+        if (def.type === 'boolean')
+            return 'boolean';
+        if (def.type === 'optional' || def.type === 'default' || def.type === 'nullable') {
+            cur = def.innerType;
+            continue;
+        }
+        return 'other';
+    }
+    return 'other';
+}
 function isAccountEnum(field) {
     const def = field?._zod?.def;
     if (!def)
@@ -64,6 +86,7 @@ export class ToolRegistry {
     registerTool;
     revealed = new Set();
     jsonSchemaCache = new Map();
+    argShapeCache = new Map();
     compactOutput = trimEnabled();
     registeringMeta = false;
     /** Configured visibility mode (GOOGLE_DISCOVERY); default lazy = v5 exact. */
@@ -90,9 +113,15 @@ export class ToolRegistry {
             // A12: forced per-call human approval on the irreversible set, even in
             // bypass mode. Client-enforced via the wire _meta (Claude Code reads
             // anthropic/* ONLY there); the server verdict stays separate.
-            const clientMeta = IRREVERSIBLE_TOOLS.has(name)
-                ? { ...config._meta, 'anthropic/requiresUserInteraction': true }
-                : config._meta;
+            // Every tool also advertises a result-size budget: fat readers declare
+            // their own, everything else inherits the default, so an uncapped tool
+            // can never blow past a client's context limit. Generated tools align
+            // with the executor's server-side cap.
+            const clientMeta = {
+                'anthropic/maxResultSizeChars': config.cud !== undefined ? MAX_RESPONSE_CHARS : DEFAULT_MAX_RESULT_CHARS,
+                ...config._meta,
+                ...(IRREVERSIBLE_TOOLS.has(name) ? { 'anthropic/requiresUserInteraction': true } : {}),
+            };
             // never fan out meta tools: google_api_call infers cud=read but executes writes
             let inputShape = config.inputSchema ?? {};
             let baseHandler = handler;
@@ -181,6 +210,21 @@ export class ToolRegistry {
     services() {
         return [...new Set(this.tools.filter((t) => !t.meta).map((t) => t.service))];
     }
+    /** Declared input-schema keys + scalar kinds for one tool (tools/call arg
+     * normalization; the kind drives value coercion on renamed keys). */
+    argShape(name) {
+        const cached = this.argShapeCache.get(name);
+        if (cached)
+            return cached;
+        const entry = this.tools.find((t) => t.name === name);
+        if (!entry)
+            return undefined;
+        const shape = new Map();
+        for (const [key, field] of Object.entries(entry.inputShape))
+            shape.set(key, scalarKindOf(field));
+        this.argShapeCache.set(name, shape);
+        return shape;
+    }
     catalog(service, query) {
         const q = query?.trim().toLowerCase();
         return this.tools
@@ -193,6 +237,20 @@ export class ToolRegistry {
             cud: t.cud,
         }));
     }
+    /** Op-name vocabulary for a service, split by provenance so the capped
+     * discover descriptions can list curated ops and only summarize the
+     * generated long tail. */
+    opNames(service) {
+        const strip = (n) => (n.startsWith(`${service}_`) ? n.slice(service.length + 1) : n);
+        const curated = [];
+        const generated = [];
+        for (const t of this.tools) {
+            if (t.meta || t.service !== service)
+                continue;
+            (t.generated ? generated : curated).push(strip(t.name));
+        }
+        return { curated: [...new Set(curated)], generated: [...new Set(generated)] };
+    }
     reveal(service) {
         if (this.revealed.has(service))
             return false;

package/dist/scope-catalog.d.ts

@@ -17,3 +17,4 @@ export declare const BUNDLE_ALIASES: Record<string, string>;
 export declare function resolveBundleAliases(bundles: string[]): string[];
 /** Closest catalog key for E_UNKNOWN_BUNDLE remediation (edit distance <= 2). */
 export declare function closestBundle(name: string): string | undefined;
+export declare function editDistance(a: string, b: string): number;

package/dist/scope-catalog.js

@@ -108,6 +108,22 @@ export const BUNDLE_CATALOG = {
         description: 'Read Gmail Postmaster Tools deliverability data.',
         risk: 'low',
     },
+    analytics: {
+        scopes: ['https://www.googleapis.com/auth/analytics.readonly'],
+        description: 'Read Google Analytics (GA4): run reports and inspect accounts, properties and their configuration.',
+        risk: 'low',
+    },
+    // Includes readonly so it is self-sufficient: analytics.edit alone does not
+    // authorize Data API reads. The smaller `analytics` bundle stays the hint
+    // target for read scopes (scope-observability sorts bundles by size).
+    analytics_write: {
+        scopes: [
+            'https://www.googleapis.com/auth/analytics.readonly',
+            'https://www.googleapis.com/auth/analytics.edit',
+        ],
+        description: 'Edit Google Analytics (GA4) configuration: properties, data streams, key events, custom dimensions and metrics. Includes read access.',
+        risk: 'medium',
+    },
     groupssettings: {
         scopes: ['https://www.googleapis.com/auth/apps.groups.settings'],
         description: 'Change Google Groups settings for the domain.',
@@ -169,7 +185,7 @@ export function closestBundle(name) {
     }
     return best;
 }
-function editDistance(a, b) {
+export function editDistance(a, b) {
     const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
     for (let j = 1; j <= b.length; j++)
         dp[0][j] = j;

package/dist/services.js

@@ -11,6 +11,7 @@ import { registerSlidesTools } from './tools/slides.js';
 import { registerFormsTools } from './tools/forms.js';
 import { registerChatTools } from './tools/chat.js';
 import { registerAdminTools } from './tools/admin.js';
+import { registerAnalyticsTools } from './tools/analytics.js';
 import { getOptionalBundles, getAdminAccounts } from './auth.js';
 export const SERVICES = [
     { name: 'gmail', register: registerGmailTools },
@@ -25,9 +26,10 @@ export const SERVICES = [
     { name: 'slides', register: registerSlidesTools, enabled: () => new Set(getOptionalBundles()).has('slides') },
     { name: 'forms', register: registerFormsTools, enabled: () => new Set(getOptionalBundles()).has('forms') },
     { name: 'chat', register: registerChatTools, enabled: () => new Set(getOptionalBundles()).has('chat') },
+    { name: 'analytics', register: registerAnalyticsTools, enabled: () => { const b = new Set(getOptionalBundles()); return b.has('analytics') || b.has('analytics_write'); } },
     { name: 'admin', register: registerAdminTools, enabled: () => getAdminAccounts().length > 0 },
 ];
-// Generated-only services with opt-in scopes; admin/forms/chat reuse their curated gate in buildRegistry,
+// Generated-only services with opt-in scopes; admin/forms/chat/analytics reuse their curated gate in buildRegistry,
 // and workspaceevents is deliberately absent — no dedicated scope (subscriptions use resource scopes).
 const bundleGate = (name) => ({
     enabled: () => new Set(getOptionalBundles()).has(name),