mcp-google-multi 6.0.0-alpha.5 → 6.0.0-alpha.51

package/README.md

@@ -1,13 +1,13 @@
 # mcp-google-multi
 
-The most complete **local Google Workspace MCP server**: Gmail, Drive, Calendar, Sheets, Docs, Slides, Forms, Contacts, Tasks, Chat, Meet, Classroom, Vault, Admin and more — **every OAuth-reachable Workspace API method** as a tool, across **multiple Google accounts** at once, from Claude Code or any MCP client.
+The most complete **local Google Workspace MCP server**: Gmail, Drive, Calendar, Sheets, Docs, Slides, Forms, Contacts, Tasks, Chat, Meet, Analytics (GA4), Search Console, Classroom, Vault, Admin and more — **every OAuth-reachable API method** as a tool, across **multiple Google accounts** at once, from Claude Code or any MCP client.
 
 [![npm](https://img.shields.io/npm/v/mcp-google-multi?label=npm&color=cb3837)](https://www.npmjs.com/package/mcp-google-multi)
 
-- 🧰 **Exhaustive** — 874 tools across 28 services + an escape hatch for anything else → [COVERAGE.md](./COVERAGE.md)
+- 🧰 **Exhaustive** — 940 tools across 29 services, now including Google Analytics (GA4), + an escape hatch for anything else → [COVERAGE.md](./COVERAGE.md)
 - 🔑 **Multi-account** — drive any number of Google accounts by alias, or fan one call out across all of them
 - 🔒 **Private by design** — your own OAuth app, tokens encrypted at rest (AES-256-GCM), writes deny-by-default, no telemetry, no metering — it talks only to Google
-- 🌐 **Local or remote** — runs locally over stdio, or self-hosted over HTTP with its own built-in OAuth 2.1 server (Claude Code's `/mcp` login and the claude.ai connector, zero custom UI) → [remote setup](./docs/http-setup.md)
+- 🌐 **Local or remote** — runs locally over stdio, or self-hosted over HTTP with its own built-in OAuth 2.1 server (Claude Code's `/mcp` login and the claude.ai connector, zero custom UI). Pull-and-up Docker Compose with optional automatic HTTPS → [remote setup](./docs/http-setup.md)
 - ✉️ **Built for real work** — send and read email in Markdown with attachments and one-call replies, an interactive setup wizard with a `doctor` self-check, and per-account scope profiles → [features tour](./docs/features.md)
 
 ## Quick setup
@@ -20,6 +20,8 @@ New to all this? It's written for someone who just installed Claude Code and has
    npm install -g mcp-google-multi
    ```
 
+   Claude Desktop user? You can skip npm entirely: download the `mcp-google-multi.mcpb` bundle from the [latest release](https://github.com/bakissation/mcp-google-multi/releases/latest), double-click it (or drag it into Claude Desktop → Settings → Extensions), and fill in the values from step 2 when prompted.
+
 2. **Make your Google key** (the one manual part, a few minutes, because Google has no way to script it). Follow the step-by-step [Google Cloud setup](./docs/google-cloud-setup.md), or just ask Claude Code: *"walk me through creating a Google OAuth Desktop client for mcp-google-multi."* You finish with two values, a **Client ID** and a **Client Secret**. It's free and private to you.
 
 3. **Put them in a file.** In the folder you'll run from, make a file named `.env` and paste this, filling in your values:
@@ -51,7 +53,7 @@ New to all this? It's written for someone who just installed Claude Code and has
 
 *On a server or from claude.ai?* Advanced path: [Remote / HTTP setup](./docs/http-setup.md). *Coming from v5?* [v6 migration guide](./MIGRATION-v6.md).
 
-**Go deeper:** [Configuration reference](./docs/configuration.md) · [What's covered](./COVERAGE.md) · [Features tour](./docs/features.md) · [Remote / HTTP setup](./docs/http-setup.md) · [Secrets in a vault](./docs/secrets.md) · [Migrating to v6](./MIGRATION-v6.md) · [Security policy](./SECURITY.md) · [Roadmap](https://github.com/bakissation/mcp-google-multi/milestones)
+**Go deeper:** [Configuration reference](./docs/configuration.md) · [What's covered](./COVERAGE.md) · [Features tour](./docs/features.md) · [Remote / HTTP setup](./docs/http-setup.md) · [Secrets in a vault](./docs/secrets.md) · [Local usage metrics](./docs/usage-metrics.md) · [Migrating to v6](./MIGRATION-v6.md) · [Security policy](./SECURITY.md) · [Roadmap](https://github.com/bakissation/mcp-google-multi/milestones)
 
 ## Maintainer & credits
 

package/dist/accounts.d.ts

@@ -18,7 +18,10 @@ export interface AccountSet {
     defaultAccount?: string;
     defaultAccountSource?: 'env' | 'config';
 }
-export declare function resolveAccounts(env?: NodeJS.ProcessEnv, filePath?: string, onInvalid?: 'exit' | 'throw'): AccountSet;
+export declare function resolveAccounts(env?: NodeJS.ProcessEnv, filePath?: string, onInvalid?: 'exit' | 'throw', opts?: {
+    tokenDir?: string;
+}): AccountSet;
+export declare function fileStamp(filePath: string, version: number): string;
 /** Live accessor: dispatch-time readers use this, never a captured snapshot. */
 export declare function getAccountSet(): AccountSet;
 /** Re-resolve after a config.json mutation and swap the live set. */
@@ -30,6 +33,11 @@ export declare function isAccountSetStale(): boolean;
  * Snapshot from the initial load; enums widen only when the registry is
  * rebuilt after a mutation (account_add, later slice). */
 export declare const ACCOUNTS: string[];
+/** One message for a mistyped alias, shared by every account schema. `aliases`
+ * is the SCHEMA's own snapshot, not the live registry: those are the values the
+ * enum actually accepts, and naming a runtime-added alias as valid while
+ * rejecting it would be a lie. */
+export declare function unknownAliasMessage(aliases: readonly string[], selectors?: boolean): string;
 /**
  * The `account` param schema, empty-registry-safe. A `z.enum` requires at least
  * one value, so a fresh install (zero aliases) would throw at schema-build time
@@ -40,6 +48,13 @@ export declare const ACCOUNTS: string[];
 export declare function accountAliasSchemaFor(aliases: readonly string[]): z.ZodType<string>;
 /** Shared, load-time snapshot used by every tool's `account` field. */
 export declare const accountAliasSchema: z.ZodType<string>;
+/** Live account argument: validates at PARSE time against the accessor's
+ * CURRENT aliases, so an alias added mid-session (account_add, or a tenant
+ * alias link) is immediately valid on already-registered tools — a baked
+ * z.enum freezes the boot-time set until restart. An empty set stays
+ * permissive (same empty-safe rule as above); dispatch still resolves the
+ * alias against the live registry. */
+export declare function accountArgLive(aliases: () => readonly string[]): z.ZodType<string>;
 /**
  * BR-4: the stdio/http SERVER never boots with an empty registry — a fresh user
  * bootstraps via env / `migrate-config` / `account import` / `auth` first. The

package/dist/accounts.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import fs from 'node:fs';
 import { z } from 'zod';
 import { loadEnvFiles } from './env-load.js';
-import { CONFIG_VERSION, configDir, configFilePath, failStartup, loadConfigFile, mutateConfigFile } from './config-file.js';
+import { ALIAS_RE, CONFIG_VERSION, configDir, configFilePath, failStartup, isReservedAlias, loadConfigFile, mutateConfigFile } from './config-file.js';
 import { BUNDLE_CATALOG, closestBundle, resolveBundleAliases } from './scope-catalog.js';
 const envLoad = loadEnvFiles();
 const defaultTokenDir = path.join(configDir(), 'tokens');
@@ -15,14 +15,14 @@ export function getTokenDir() {
 function parseCsv(value) {
     return (value ?? '').split(',').map((s) => s.trim()).filter(Boolean);
 }
-function accountPaths(alias) {
+function accountPaths(alias, dir = tokenDir) {
     return {
-        tokenPath: path.join(tokenDir, alias, 'token.json'),
-        encPath: path.join(tokenDir, `${alias}.enc`),
+        tokenPath: path.join(dir, alias, 'token.json'),
+        encPath: path.join(dir, `${alias}.enc`),
     };
 }
 /** v5 env parser, guards verbatim. Format: GOOGLE_ACCOUNTS="alias1:email1,alias2:email2". */
-function parseEnvAccounts(raw, adminAliases) {
+function parseEnvAccounts(raw, adminAliases, dir = tokenDir) {
     const configs = {};
     const aliases = [];
     for (const entry of raw.split(',')) {
@@ -40,7 +40,7 @@ function parseEnvAccounts(raw, adminAliases) {
         }
         // Restrict alias to a safe charset so it can't escape `tokenDir` via path traversal
         // (e.g. "../../etc/passwd:foo@bar.com" in .env).
-        if (!/^[a-zA-Z0-9_-]+$/.test(alias) || ['__proto__', 'constructor', 'prototype'].includes(alias)) {
+        if (!ALIAS_RE.test(alias) || isReservedAlias(alias)) {
             throw new Error(`Invalid alias "${alias}". Allowed characters: letters, digits, underscore, hyphen.`);
         }
         if (aliases.includes(alias)) {
@@ -49,7 +49,7 @@ function parseEnvAccounts(raw, adminAliases) {
         aliases.push(alias);
         configs[alias] = {
             email,
-            ...accountPaths(alias),
+            ...accountPaths(alias, dir),
             admin: adminAliases.includes(alias) || undefined,
             source: 'env',
         };
@@ -74,7 +74,8 @@ function noAccountsMessage() {
  * empty behaves as unset, mirroring GOOGLE_ACCOUNTS semantics.
  */
 let warnedLegacy = false;
-export function resolveAccounts(env = process.env, filePath = configFilePath(), onInvalid = 'exit') {
+export function resolveAccounts(env = process.env, filePath = configFilePath(), onInvalid = 'exit', opts = {}) {
+    const dir = opts.tokenDir ?? tokenDir;
     const adminEnv = parseCsv(env.GOOGLE_ADMIN_ACCOUNTS);
     const rawEnv = env.GOOGLE_ACCOUNTS;
     const fail = (slug, message) => {
@@ -102,7 +103,7 @@ export function resolveAccounts(env = process.env, filePath = configFilePath(),
         }
     }
     if (rawEnv && rawEnv.trim() !== '') {
-        const { aliases, configs } = parseEnvAccounts(rawEnv, adminEnv);
+        const { aliases, configs } = parseEnvAccounts(rawEnv, adminEnv, dir);
         materializeFirstRun(aliases, configs, filePath);
         const def = resolveDefaultAccount(env, null, aliases, fail);
         return {
@@ -167,7 +168,7 @@ export function resolveAccounts(env = process.env, filePath = configFilePath(),
         aliases.push(alias);
         configs[alias] = {
             email: entry.email,
-            ...accountPaths(alias),
+            ...accountPaths(alias, dir),
             scopeProfile: entry.scopeProfile,
             admin: adminEnv.length > 0 ? adminEnv.includes(alias) : entry.admin,
             source: 'config',
@@ -196,7 +197,7 @@ function resolveDefaultAccount(env, fromConfig, aliases, fail) {
     }
     return { defaultAccount: value, defaultAccountSource: fromEnv ? 'env' : 'config' };
 }
-function fileStamp(filePath, version) {
+export function fileStamp(filePath, version) {
     try {
         return `${version}:${fs.statSync(filePath).mtimeMs}`;
     }
@@ -278,6 +279,15 @@ export function isAccountSetStale() {
  * Snapshot from the initial load; enums widen only when the registry is
  * rebuilt after a mutation (account_add, later slice). */
 export const ACCOUNTS = current.aliases;
+/** One message for a mistyped alias, shared by every account schema. `aliases`
+ * is the SCHEMA's own snapshot, not the live registry: those are the values the
+ * enum actually accepts, and naming a runtime-added alias as valid while
+ * rejecting it would be a lie. */
+export function unknownAliasMessage(aliases, selectors = false) {
+    const all = selectors ? '; "*" for all accounts' : '';
+    const csv = selectors && aliases.length > 1 ? `; or a CSV subset like "${aliases.slice(0, 2).join(',')}"` : '';
+    return `Unknown account alias. Valid: ${aliases.join(', ')}${all}${csv}. Run account_list if accounts changed since this server started.`;
+}
 /**
  * The `account` param schema, empty-registry-safe. A `z.enum` requires at least
  * one value, so a fresh install (zero aliases) would throw at schema-build time
@@ -286,10 +296,26 @@ export const ACCOUNTS = current.aliases;
  * are no aliases: no alias exists to enumerate, the server refuses to boot empty
  * anyway, and dispatch validates the account against the live set. */
 export function accountAliasSchemaFor(aliases) {
-    return aliases.length > 0 ? z.enum(aliases) : z.string();
+    return aliases.length > 0
+        ? z.enum(aliases, { error: () => unknownAliasMessage(aliases) })
+        : z.string();
 }
 /** Shared, load-time snapshot used by every tool's `account` field. */
 export const accountAliasSchema = accountAliasSchemaFor(ACCOUNTS);
+/** Live account argument: validates at PARSE time against the accessor's
+ * CURRENT aliases, so an alias added mid-session (account_add, or a tenant
+ * alias link) is immediately valid on already-registered tools — a baked
+ * z.enum freezes the boot-time set until restart. An empty set stays
+ * permissive (same empty-safe rule as above); dispatch still resolves the
+ * alias against the live registry. */
+export function accountArgLive(aliases) {
+    return z.string().superRefine((value, ctx) => {
+        const current = aliases();
+        if (current.length > 0 && !current.includes(value)) {
+            ctx.addIssue({ code: 'custom', message: unknownAliasMessage(current) });
+        }
+    });
+}
 /**
  * BR-4: the stdio/http SERVER never boots with an empty registry — a fresh user
  * bootstraps via env / `migrate-config` / `account import` / `auth` first. The

package/dist/api-probe.js

@@ -17,6 +17,9 @@ export const API_PROBES = [
     { service: 'chat', api: 'chat', url: 'https://chat.googleapis.com/v1/spaces?pageSize=1', scopePrefixes: [`${P}chat.`] },
     { service: 'meet', api: 'meet', url: 'https://meet.googleapis.com/v2/conferenceRecords?pageSize=1', scopePrefixes: [`${P}meetings.`] },
     { service: 'forms', api: 'forms', url: `https://forms.googleapis.com/v1/forms/${BOGUS_ID}`, scopePrefixes: [`${P}forms.`], notFoundMeansEnabled: true },
+    // Probes the Admin API only: the Data API has no no-arg read (every call
+    // needs a property id), so its enablement surfaces on first report instead.
+    { service: 'analytics', api: 'analyticsadmin', url: 'https://analyticsadmin.googleapis.com/v1beta/accountSummaries?pageSize=1', scopePrefixes: [`${P}analytics`] },
 ];
 export function planProbes(granted, probes = API_PROBES) {
     return probes.filter((p) => granted.some((s) => p.scopePrefixes.some((prefix) => s.startsWith(prefix))));

package/dist/arg-normalize.d.ts

@@ -0,0 +1,76 @@
+import type { Transport, JSONRPCMessage } from "@modelcontextprotocol/server";
+import { type SiblingSpelling, type UnknownArgMode } from './arg-strict.js';
+export declare function isSchemaValidationText(text: string): boolean;
+export declare function argNormalizationEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** Declared scalar kind per schema key; drives value coercion on RENAMED keys
+ * only. Clients string-encode values for keys absent from the advertised
+ * schema, so a renamed key almost always arrives as a string — without
+ * coercion the rename would just move the -32602 from the key to the value. */
+export type ArgKind = 'number' | 'boolean' | 'other';
+export type ArgShape = ReadonlyMap<string, ArgKind>;
+export declare function normalizeCallArguments(shape: ArgShape, args: Record<string, unknown>): {
+    args: Record<string, unknown>;
+    renamed: [string, string][];
+};
+export declare function normalizeMessage(msg: JSONRPCMessage, shapeFor: (tool: string) => ArgShape | undefined, log?: (line: string) => void, onRename?: (tool: string, renames: number) => void): JSONRPCMessage;
+export interface StrictArgOptions {
+    mode: UnknownArgMode;
+    /** full declared key list for a tool, in declaration order */
+    declaredFor: (tool: string) => readonly string[] | undefined;
+    /** sibling spellings of a concept elsewhere in the same service */
+    siblingsFor?: (tool: string, keys: string[]) => SiblingSpelling[];
+    /** Replacement text for the SDK's bare "Tool X not found". Still answered as
+     * a JSON-RPC error, which is what the spec prescribes for an unknown tool;
+     * only the message improves. */
+    unknownTool?: (tool: string) => string;
+    onDrop?: (tool: string, resolvedKeys: string[]) => void;
+}
+export type ScreenOutcome = {
+    action: 'forward';
+    msg: JSONRPCMessage;
+} | {
+    action: 'reject';
+    response: JSONRPCMessage;
+};
+/**
+ * Screen a normalized tools/call for undeclared keys. `warn` forwards exactly
+ * as before and only reports; `reject` answers with the taxonomy envelope and
+ * never reaches the handler, so nothing is sent to Google on a guess.
+ */
+export declare function screenMessage(msg: JSONRPCMessage, opts: StrictArgOptions, log?: (line: string) => void): ScreenOutcome;
+/** Wrap a server-side transport so tools/call argument keys are normalized
+ * before the SDK validates them. The Protocol assigns `onmessage` during
+ * connect(); the interceptor lives in that setter, so the wrapper works
+ * identically for stdio and (per-request, stateless) HTTP transports. */
+export declare function withArgNormalization(transport: Transport, shapeFor: (tool: string) => ArgShape | undefined, log?: (line: string) => void, onRename?: (tool: string, renames: number) => void, strict?: StrictArgOptions): Transport;
+export interface ValidationEnvelopeOptions {
+    /** Membership against the REGISTERED tool set: the name on the frame is
+     * ultimately client-supplied, and it must never enter an envelope unchecked. */
+    isKnownTool?: (name: string) => boolean;
+    /** The account the call WOULD have run as. The registry injects the default
+     * AFTER validation, so a validation failure never got that far. */
+    defaultAccount?: () => string | undefined;
+}
+interface PendingCall {
+    tool: string;
+    account?: string;
+}
+export declare function validationEnvelope(tool: string, issues: string, account: string | undefined): {
+    error: string;
+    message: string;
+    hint: string;
+    retriable: boolean;
+    account: string;
+};
+/** Floor for the OTHER bare prose the same SDK catch produces: an output-schema
+ * failure. Nothing is known about the cause, so it says exactly that. */
+export declare function outputFailureEnvelope(tool: string, text: string, account: string | undefined): {
+    error: string;
+    message: string;
+    hint: string;
+    retriable: boolean;
+    account: string;
+};
+export declare function rewriteValidationFrame(message: JSONRPCMessage, pending: Map<string | number, PendingCall>, opts: ValidationEnvelopeOptions): JSONRPCMessage;
+export declare function withValidationEnvelope(transport: Transport, opts?: ValidationEnvelopeOptions): Transport;
+export {};

package/dist/arg-normalize.js

@@ -0,0 +1,314 @@
+import { screenArguments, unknownArgEnvelope, } from './arg-strict.js';
+import { sliceClean } from './trim.js';
+// The SDK synthesizes input-validation failures as isError RESULTS, skipping
+// the handler entirely: no handler of ours runs, so no envelope exists and the
+// client gets free text. The text is prose in both SDK eras (v1 prefixed it
+// with "MCP error -32602: ", v2 dropped that prefix), while handler envelopes
+// are always JSON starting with "{".
+const SCHEMA_VALIDATION_TEXT = /^(MCP error -32602: )?Input validation error:/;
+export function isSchemaValidationText(text) {
+    return SCHEMA_VALIDATION_TEXT.test(text);
+}
+/** Capture form of the v2 text. The tool-name class excludes ':' and ' ', so
+ * the first ": " after the name is unambiguously the delimiter. */
+const VALIDATION_PROSE = /^(?:MCP error -32602: )?Input validation error: Invalid arguments for tool ([A-Za-z0-9_.-]+): ([\s\S]+)$/;
+/** The SDK's OTHER synthesized prose on the same catch. Both prefixes are
+ * SDK-authored; a HANDLER's free text is not, and must survive untouched
+ * (the account wizard answers in prose today). */
+const SDK_OUTPUT_PROSE = /^(?:MCP error -32602: )?Output validation error: /;
+// Wire-level tools/call argument normalization. Clients (LLMs) recurringly
+// snake_case a camelCase parameter (thread_id for threadId) and burn a retry
+// on the -32602. A schema-level fix is off the table: the SDK advertises an
+// EMPTY input schema for any non-object wrapper (pipe/preprocess), so the
+// only seam that keeps tools/list intact is the JSON-RPC message itself —
+// which is versioned MCP spec, stabler than any SDK internal. The rename is
+// provably lossless: it fires only when the sent key is NOT in the tool's
+// schema, its camelCase twin IS, and that twin was not also sent.
+export function argNormalizationEnabled(env = process.env) {
+    return !/^(0|false|off|no)$/i.test((env.GOOGLE_ARG_NORMALIZE ?? '').trim());
+}
+const snakeToCamel = (key) => key.replace(/_([a-z0-9])/g, (_m, c) => c.toUpperCase());
+function coerceRenamedValue(value, kind) {
+    if (typeof value !== 'string')
+        return value;
+    const v = value.trim();
+    if (kind === 'number' && /^-?\d+(\.\d+)?$/.test(v))
+        return Number(v);
+    if (kind === 'boolean' && /^(true|false)$/i.test(v))
+        return v.toLowerCase() === 'true';
+    return value;
+}
+export function normalizeCallArguments(shape, args) {
+    const renamed = [];
+    let out;
+    for (const key of Object.keys(args)) {
+        if (shape.has(key) || !key.includes('_'))
+            continue;
+        const camel = snakeToCamel(key);
+        if (camel !== key && shape.has(camel) && !(camel in args)) {
+            out ??= { ...args };
+            out[camel] = coerceRenamedValue(out[key], shape.get(camel));
+            delete out[key];
+            renamed.push([key, camel]);
+        }
+    }
+    return { args: out ?? args, renamed };
+}
+export function normalizeMessage(msg, shapeFor, log = (l) => process.stderr.write(`${l}\n`), onRename) {
+    const m = msg;
+    if (m.method !== 'tools/call' || typeof m.params?.name !== 'string')
+        return msg;
+    const args = m.params.arguments;
+    if (!args || typeof args !== 'object' || Array.isArray(args))
+        return msg;
+    const shape = shapeFor(m.params.name);
+    if (!shape)
+        return msg;
+    const { args: normalized, renamed } = normalizeCallArguments(shape, args);
+    if (renamed.length === 0)
+        return msg;
+    // Key names only — argument VALUES never reach the log.
+    log(`[args] ${m.params.name}: ${renamed.map(([f, t]) => `${f} -> ${t}`).join(', ')}`);
+    try {
+        onRename?.(m.params.name, renamed.length);
+    }
+    catch { /* observers never break dispatch */ }
+    return {
+        ...msg,
+        params: { ...m.params, arguments: normalized },
+    };
+}
+/**
+ * Screen a normalized tools/call for undeclared keys. `warn` forwards exactly
+ * as before and only reports; `reject` answers with the taxonomy envelope and
+ * never reaches the handler, so nothing is sent to Google on a guess.
+ */
+export function screenMessage(msg, opts, log = (l) => process.stderr.write(`${l}\n`)) {
+    if (opts.mode === 'off')
+        return { action: 'forward', msg };
+    const m = msg;
+    if (m.method !== 'tools/call' || typeof m.params?.name !== 'string')
+        return { action: 'forward', msg };
+    const args = m.params.arguments;
+    if (!args || typeof args !== 'object' || Array.isArray(args))
+        return { action: 'forward', msg };
+    const tool = m.params.name;
+    const declared = opts.declaredFor(tool);
+    // Unregistered tool. The spec keeps this a PROTOCOL error (unknown tool is
+    // not something the model can fix by adjusting arguments), so the channel
+    // stays a JSON-RPC error; only the message gets the did-you-mean and the
+    // gated-service next step. Without `unknownTool`, or on a notification,
+    // the SDK's own "not found" still answers.
+    if (!declared) {
+        if (!opts.unknownTool || m.id === undefined)
+            return { action: 'forward', msg };
+        return {
+            action: 'reject',
+            response: {
+                jsonrpc: '2.0',
+                id: m.id,
+                error: { code: -32602, message: opts.unknownTool(tool) },
+            },
+        };
+    }
+    const screened = screenArguments(tool, args, declared);
+    if (screened.unknown.length === 0 && screened.redundant.length === 0)
+        return { action: 'forward', msg };
+    const all = [...screened.unknown.map((u) => u.sent), ...screened.redundant];
+    // Key names only; argument VALUES never reach the log.
+    log(`[args] ${tool}: undeclared ${all.join(', ')}${opts.mode === 'warn' ? ' (dropped)' : ' (rejected)'}`);
+    try {
+        // Only ever a DECLARED key or the literal placeholder, so the metrics
+        // closed-vocabulary rule holds: the caller's key is never persisted.
+        opts.onDrop?.(tool, screened.unknown.map((u) => u.suggestions[0] ?? '_unmatched'));
+    }
+    catch { /* observers never break dispatch */ }
+    if (opts.mode === 'warn' || screened.unknown.length === 0)
+        return { action: 'forward', msg };
+    // Nothing to answer (a malformed notification): dispatch as before.
+    if (m.id === undefined)
+        return { action: 'forward', msg };
+    const account = args.account;
+    const siblings = screened.unknown.some((u) => u.suggestions.length > 0)
+        ? []
+        : (opts.siblingsFor?.(tool, screened.unknown.map((u) => u.sent)) ?? []);
+    const envelope = unknownArgEnvelope(tool, screened.unknown, declared, typeof account === 'string' ? account : undefined, siblings);
+    return {
+        action: 'reject',
+        response: {
+            jsonrpc: '2.0',
+            id: m.id,
+            result: { content: [{ type: 'text', text: JSON.stringify(envelope) }], isError: true },
+        },
+    };
+}
+/** Wrap a server-side transport so tools/call argument keys are normalized
+ * before the SDK validates them. The Protocol assigns `onmessage` during
+ * connect(); the interceptor lives in that setter, so the wrapper works
+ * identically for stdio and (per-request, stateless) HTTP transports. */
+export function withArgNormalization(transport, shapeFor, log, onRename, strict) {
+    const wrapper = {
+        start: () => transport.start(),
+        send: (message, options) => transport.send(message, options),
+        close: () => transport.close(),
+    };
+    Object.defineProperty(wrapper, 'onmessage', {
+        get: () => transport.onmessage,
+        set: (handler) => {
+            transport.onmessage = handler
+                ? (message, extra) => {
+                    // Rename FIRST: a snake_case twin of a declared key is a fix, not
+                    // an unknown argument, so it must never reach the screen.
+                    const normalized = normalizeMessage(message, shapeFor, log, onRename);
+                    if (!strict)
+                        return handler(normalized, extra);
+                    const outcome = screenMessage(normalized, strict, log);
+                    if (outcome.action === 'forward')
+                        return handler(outcome.msg, extra);
+                    // Last-resort fallback: dispatch as before rather than hang the
+                    // caller. The stderr line and the counter already fired above.
+                    // `send` is async, so a rejected promise needs catching too: a
+                    // bare `void` left the client waiting for a frame that never came.
+                    const fallback = () => handler(normalized, extra);
+                    try {
+                        // Answer on the INNER transport so the metrics tap still sees the
+                        // frame and clears its pending id.
+                        void Promise.resolve(transport.send(outcome.response)).catch(fallback);
+                    }
+                    catch {
+                        fallback();
+                    }
+                }
+                : undefined;
+        },
+    });
+    for (const prop of ['onclose', 'onerror']) {
+        Object.defineProperty(wrapper, prop, {
+            get: () => transport[prop],
+            set: (v) => {
+                transport[prop] = v;
+            },
+        });
+    }
+    Object.defineProperty(wrapper, 'sessionId', { get: () => transport.sessionId });
+    if (transport.setProtocolVersion) {
+        wrapper.setProtocolVersion = (v) => transport.setProtocolVersion(v);
+    }
+    // v2-only, called by Protocol.connect() before start(). A no-op today (both
+    // sides default to the same exported constant), but a proxy that silently
+    // eats a member the SDK calls is a bug waiting for the first caller that
+    // passes supportedProtocolVersions explicitly.
+    if (transport.setSupportedProtocolVersions) {
+        wrapper.setSupportedProtocolVersions = (v) => transport.setSupportedProtocolVersions(v);
+    }
+    return wrapper;
+}
+const MAX_ACCOUNT_CHARS = 64;
+const MAX_ISSUE_CHARS = 800;
+const MAX_PROSE_CHARS = 500;
+const ENVELOPE_PENDING_CAP = 1_000;
+export function validationEnvelope(tool, issues, account) {
+    return {
+        error: 'validation_error',
+        message: `${tool} arguments failed validation: ${sliceClean(issues, MAX_ISSUE_CHARS)}`,
+        hint: `Fix the argument named in the message and call again. This tool's inputSchema in tools/list lists every accepted argument, its type and its allowed values. Nothing was sent to Google.`,
+        retriable: false,
+        account: account ?? '',
+    };
+}
+/** Floor for the OTHER bare prose the same SDK catch produces: an output-schema
+ * failure. Nothing is known about the cause, so it says exactly that. */
+export function outputFailureEnvelope(tool, text, account) {
+    return {
+        error: 'internal',
+        message: `${tool} returned a result the protocol rejected: ${sliceClean(text, MAX_PROSE_CHARS)}`,
+        hint: 'A server-side failure, not a rejected argument. Retry once; if it repeats, the message above is the signal to report.',
+        retriable: false,
+        account: account ?? '',
+    };
+}
+export function rewriteValidationFrame(message, pending, opts) {
+    const m = message;
+    // Responses only. A server-initiated REQUEST (elicitation, sampling) also
+    // carries an id, from a different id space, and evicting on it would drop a
+    // real pending call.
+    if (m.id === undefined || m.method !== undefined)
+        return message;
+    const call = pending.get(m.id);
+    pending.delete(m.id);
+    if (m.result?.isError !== true)
+        return message;
+    const content = m.result.content;
+    if (!content || content.length !== 1 || content[0]?.type !== 'text')
+        return message;
+    const text = content[0].text;
+    if (typeof text !== 'string' || text.startsWith('{'))
+        return message;
+    const parsed = isSchemaValidationText(text) ? VALIDATION_PROSE.exec(text) : null;
+    // Anything the SDK did not author is a handler's own answer. Leave it alone.
+    if (!parsed && !SDK_OUTPUT_PROSE.test(text))
+        return message;
+    const tool = parsed?.[1] ?? call?.tool;
+    if (!tool || (opts.isKnownTool && !opts.isKnownTool(tool)))
+        return message;
+    const account = call?.account ?? opts.defaultAccount?.();
+    const envelope = parsed
+        ? validationEnvelope(tool, parsed[2], account)
+        : outputFailureEnvelope(tool, text, account);
+    return {
+        ...message,
+        result: { ...m.result, content: [{ type: 'text', text: JSON.stringify(envelope) }] },
+    };
+}
+export function withValidationEnvelope(transport, opts = {}) {
+    const pending = new Map();
+    const wrapper = {
+        start: () => transport.start(),
+        send: (message, options) => {
+            let out = message;
+            try {
+                out = rewriteValidationFrame(message, pending, opts);
+            }
+            catch { /* the seam may never break the wire */ }
+            return transport.send(out, options);
+        },
+        close: () => transport.close(),
+    };
+    Object.defineProperty(wrapper, 'onmessage', {
+        get: () => transport.onmessage,
+        set: (handler) => {
+            transport.onmessage = handler
+                ? (message, extra) => {
+                    try {
+                        const m = message;
+                        if (m.method === 'tools/call' && m.id !== undefined && typeof m.params?.name === 'string') {
+                            if (pending.size >= ENVELOPE_PENDING_CAP)
+                                pending.clear();
+                            const args = m.params.arguments;
+                            const raw = args && typeof args === 'object' ? args.account : undefined;
+                            pending.set(m.id, {
+                                tool: m.params.name,
+                                account: typeof raw === 'string' ? sliceClean(raw, MAX_ACCOUNT_CHARS) : undefined,
+                            });
+                        }
+                    }
+                    catch { /* never break dispatch */ }
+                    handler(message, extra);
+                }
+                : undefined;
+        },
+    });
+    for (const prop of ['onclose', 'onerror']) {
+        Object.defineProperty(wrapper, prop, {
+            get: () => transport[prop],
+            set: (v) => {
+                transport[prop] = v;
+            },
+        });
+    }
+    Object.defineProperty(wrapper, 'sessionId', { get: () => transport.sessionId });
+    if (transport.setProtocolVersion) {
+        wrapper.setProtocolVersion = (v) => transport.setProtocolVersion(v);
+    }
+    return wrapper;
+}

package/dist/arg-strict.d.ts

@@ -0,0 +1,54 @@
+export type UnknownArgMode = 'reject' | 'warn' | 'off';
+/**
+ * `GOOGLE_ARG_UNKNOWN`: reject | warn | off. A typo in the VALUE still falls
+ * back to `warn`, not to the default: an operator who misspells the setting
+ * has said nothing about which behavior they want, and guessing the strict
+ * one would turn a config typo into failing tool calls.
+ */
+export declare function unknownArgMode(env?: NodeJS.ProcessEnv): UnknownArgMode;
+/** Tools that legitimately accept open-ended top-level keys. Empty at 6.0.0:
+ * the escape hatch is NOT one, because its open-endedness lives in the VALUES
+ * of queryParams/body, never in its six fixed top-level keys. */
+export declare const STRICT_EXEMPT_TOOLS: ReadonlySet<string>;
+/** Metadata a client may legitimately attach. Measured against all registered
+ * tools: no declared key starts with `_` or contains `/`, so neither rule can
+ * shadow a real parameter. */
+export declare function isExemptKey(key: string): boolean;
+/**
+ * Rank declared keys for an unknown key. Tiers, best non-empty tier wins:
+ *   0 same key modulo case and separators
+ *   1 every token of the unknown key appears in the declared key
+ *   2 substring containment of the flattened forms
+ *   3 a genuine typo by edit distance
+ * Plain edit distance alone cannot carry this: parentid -> parentfolderid is
+ * distance 6, well past any sane threshold, which is why tier 1 exists.
+ */
+export declare function suggestKeys(unknown: string, declared: readonly string[], limit?: number): string[];
+export interface ScreenedKey {
+    /** the key the caller sent; for stderr and the agent-facing hint only */
+    sent: string;
+    /** best suggestions, always declared keys of the tool being called */
+    suggestions: string[];
+}
+export interface ScreenResult {
+    unknown: ScreenedKey[];
+    /** dropped exactly as before: the caller also sent the declared key */
+    redundant: string[];
+}
+/**
+ * Split a call's post-rename keys into declared, redundant-duplicate and
+ * genuinely unknown. `declared` is the tool's full declared key list.
+ */
+export declare function screenArguments(tool: string, args: Record<string, unknown>, declared: readonly string[]): ScreenResult;
+export interface SiblingSpelling {
+    key: string;
+    tools: string[];
+}
+/** The agent-facing envelope. Values are never included, only key names. */
+export declare function unknownArgEnvelope(tool: string, unknown: ScreenedKey[], declared: readonly string[], account: string | undefined, siblings?: SiblingSpelling[]): {
+    error: string;
+    message: string;
+    hint: string;
+    retriable: boolean;
+    account?: string;
+};