mcp-google-multi 6.0.0-alpha.32 → 6.0.0-alpha.33

package/dist/arg-normalize.d.ts

@@ -1,4 +1,5 @@
 import type { Transport, JSONRPCMessage } from "@modelcontextprotocol/server";
+import { type SiblingSpelling, type UnknownArgMode } from './arg-strict.js';
 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
@@ -11,8 +12,29 @@ export declare function normalizeCallArguments(shape: ArgShape, args: Record<str
     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[];
+    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): Transport;
+export declare function withArgNormalization(transport: Transport, shapeFor: (tool: string) => ArgShape | undefined, log?: (line: string) => void, onRename?: (tool: string, renames: number) => void, strict?: StrictArgOptions): Transport;

package/dist/arg-normalize.js

@@ -1,3 +1,4 @@
+import { screenArguments, unknownArgEnvelope, } from './arg-strict.js';
 // 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
@@ -60,11 +61,61 @@ export function normalizeMessage(msg, shapeFor, log = (l) => process.stderr.writ
         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: leave it to the SDK's own "not found".
+    if (!declared)
+        return { action: 'forward', msg };
+    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) {
+export function withArgNormalization(transport, shapeFor, log, onRename, strict) {
     const wrapper = {
         start: () => transport.start(),
         send: (message, options) => transport.send(message, options),
@@ -74,7 +125,26 @@ export function withArgNormalization(transport, shapeFor, log, onRename) {
         get: () => transport.onmessage,
         set: (handler) => {
             transport.onmessage = handler
-                ? (message, extra) => handler(normalizeMessage(message, shapeFor, log, onRename), extra)
+                ? (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);
+                    try {
+                        // Answer on the INNER transport so the metrics tap still sees the
+                        // frame and clears its pending id.
+                        void transport.send(outcome.response);
+                    }
+                    catch {
+                        // Last-resort: dispatch as before rather than hang the caller.
+                        // The stderr line and the counter already fired above.
+                        handler(normalized, extra);
+                    }
+                }
                 : undefined;
         },
     });

package/dist/arg-strict.d.ts

@@ -0,0 +1,52 @@
+export type UnknownArgMode = 'reject' | 'warn' | 'off';
+/**
+ * `GOOGLE_ARG_UNKNOWN`: reject | warn | off. Fail-open to `warn` on a bad
+ * value, because the safe state here is the one that changes no behavior.
+ */
+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;
+};

package/dist/arg-strict.js

@@ -0,0 +1,144 @@
+// Unknown-argument screening (backlog item 14). zod strips undeclared keys
+// before a handler runs, so a misremembered argument name used to produce a
+// SUCCESS response with wrong behavior: `parentId` on drive_create_folder was
+// dropped and the folder landed in My Drive root. Field-reported, then
+// reproduced: the typo, the correct name and a wholly invented key all
+// returned byte-identical responses.
+//
+// This module is pure and holds no registry reference. It never rewrites a key
+// and never touches a VALUE: it only decides that a key is undeclared, and
+// suggests what the caller probably meant. Rewriting would risk sending a real
+// value to Google on a guess, which is strictly worse than refusing.
+import { editDistance } from './scope-catalog.js';
+/**
+ * `GOOGLE_ARG_UNKNOWN`: reject | warn | off. Fail-open to `warn` on a bad
+ * value, because the safe state here is the one that changes no behavior.
+ */
+export function unknownArgMode(env = process.env) {
+    const raw = (env.GOOGLE_ARG_UNKNOWN ?? '').trim().toLowerCase();
+    if (raw === '')
+        return DEFAULT_MODE;
+    if (raw === 'reject' || raw === 'warn' || raw === 'off')
+        return raw;
+    process.stderr.write(`GOOGLE_ARG_UNKNOWN="${raw}" is not valid (reject | warn | off); using ${DEFAULT_MODE}\n`);
+    return DEFAULT_MODE;
+}
+// Staged rollout: `warn` ships first so the change is pure observability, and
+// the flip to `reject` is its own reviewable change.
+const DEFAULT_MODE = 'warn';
+/** 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 const STRICT_EXEMPT_TOOLS = new Set();
+/** 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 function isExemptKey(key) {
+    return key.startsWith('_') || key.includes('/');
+}
+/** Generic words that must never be offered as a suggestion on containment
+ * alone; they match far too much to be useful. */
+const GENERIC = new Set(['id', 'name', 'title', 'body', 'parent', 'text', 'content', 'type', 'value', 'key', 'data']);
+const flatten = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+function tokens(s) {
+    return s
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[\s_\-.]+/)
+        .map((t) => t.toLowerCase())
+        .filter(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 function suggestKeys(unknown, declared, limit = 2) {
+    const uFlat = flatten(unknown);
+    const uTok = tokens(unknown);
+    const tiers = [[], [], [], []];
+    for (const key of declared) {
+        const kFlat = flatten(key);
+        const kTok = tokens(key);
+        if (kFlat === uFlat) {
+            tiers[0].push({ key, rank: 0 });
+            continue;
+        }
+        if (uTok.length >= 2 && uTok.every((t) => kTok.includes(t))) {
+            tiers[1].push({ key, rank: Math.abs(kTok.length - uTok.length) });
+            continue;
+        }
+        if (uFlat.length >= 4 && !GENERIC.has(kFlat) && (kFlat.includes(uFlat) || uFlat.includes(kFlat))) {
+            tiers[2].push({ key, rank: Math.abs(kFlat.length - uFlat.length) });
+            continue;
+        }
+        const d = editDistance(uFlat, kFlat);
+        if (d <= Math.max(1, Math.floor(uFlat.length / 4)))
+            tiers[3].push({ key, rank: d });
+    }
+    const tier = tiers.find((t) => t.length > 0);
+    if (!tier)
+        return [];
+    // Stable: declaration order breaks rank ties.
+    return tier
+        .map((e, i) => ({ ...e, i }))
+        .sort((a, b) => a.rank - b.rank || a.i - b.i)
+        .slice(0, limit)
+        .map((e) => e.key);
+}
+/**
+ * Split a call's post-rename keys into declared, redundant-duplicate and
+ * genuinely unknown. `declared` is the tool's full declared key list.
+ */
+export function screenArguments(tool, args, declared) {
+    const out = { unknown: [], redundant: [] };
+    if (STRICT_EXEMPT_TOOLS.has(tool) || declared.length === 0)
+        return out;
+    const declaredSet = new Set(declared);
+    for (const key of Object.keys(args)) {
+        if (declaredSet.has(key) || isExemptKey(key))
+            continue;
+        const suggestions = suggestKeys(key, declared);
+        // The caller sent both spellings, so the declared one already won and the
+        // outcome is what it has always been. Never fail a call that works today.
+        if (suggestions.some((s) => s in args)) {
+            out.redundant.push(key);
+            continue;
+        }
+        out.unknown.push({ sent: key, suggestions });
+    }
+    return out;
+}
+/** The agent-facing envelope. Values are never included, only key names. */
+export function unknownArgEnvelope(tool, unknown, declared, account, siblings = []) {
+    const names = unknown.map((u) => `"${u.sent}"`).join(', ');
+    const accepts = `This tool accepts: ${declared.join(', ')}.`;
+    const suggested = unknown.flatMap((u) => u.suggestions);
+    let hint;
+    if (suggested.length > 0) {
+        const did = unknown
+            .filter((u) => u.suggestions.length > 0)
+            .map((u) => u.suggestions.map((s) => `"${s}"`).join(' or '))
+            .join(', ');
+        hint = `Did you mean ${did}? ${accepts}`;
+    }
+    else if (siblings.length > 0) {
+        const spelled = siblings
+            .map((s) => `"${s.key}" (${s.tools.slice(0, 3).join(', ')})`)
+            .join(' and ');
+        hint = `${accepts} Other tools in this service spell a similar argument ${spelled}.`;
+    }
+    else {
+        hint = accepts;
+    }
+    return {
+        error: 'unknown_argument',
+        message: `${tool} does not accept ${names}. Nothing was sent to Google.`,
+        hint,
+        retriable: false,
+        ...(account !== undefined ? { account } : {}),
+    };
+}

package/dist/http-transport.d.ts

@@ -1,7 +1,7 @@
 import type { McpServer, Transport } from "@modelcontextprotocol/server";
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import type { HttpConfig } from './http-config.js';
-import { type ArgShape } from './arg-normalize.js';
+import { type ArgShape, type StrictArgOptions } from './arg-normalize.js';
 export type AuthOutcome = {
     ok: true;
 } | {
@@ -35,6 +35,8 @@ export interface HttpHostOptions {
     metricsTap?: (t: Transport) => Transport;
     /** Usage-metrics argfix observer, forwarded into arg normalization. */
     onArgRename?: (tool: string, renames: number) => void;
+    /** Unknown-argument screening (arg-strict.ts); absent = off. */
+    strictArgs?: StrictArgOptions;
 }
 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

@@ -183,7 +183,9 @@ export class HttpTransportHost {
                 timer.unref?.();
             });
             const tapped = this.opts.metricsTap ? this.opts.metricsTap(transport) : transport;
-            await this.opts.server.connect(this.opts.argShapeFor ? withArgNormalization(tapped, this.opts.argShapeFor, this.opts.log, this.opts.onArgRename) : tapped);
+            await this.opts.server.connect(this.opts.argShapeFor || this.opts.strictArgs
+                ? withArgNormalization(tapped, this.opts.argShapeFor ?? (() => undefined), this.opts.log, this.opts.onArgRename, this.opts.strictArgs)
+                : tapped);
             // 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

@@ -21,12 +21,26 @@ import { buildIdentityContext } from './identity.js';
 import { registerSetupPrompt } from './setup-prompt.js';
 import { applyNetTuning } from './net-tuning.js';
 import { argNormalizationEnabled, withArgNormalization } from './arg-normalize.js';
+import { unknownArgMode } from './arg-strict.js';
 import { envValueSource } from './env-load.js';
 import { loadConfigFile } from './config-file.js';
 import { initUsageMetrics, resolveUsageMetrics, sourceLabel } from './usage-metrics.js';
 applyNetTuning();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8'));
+/** Unknown-argument screening options, or undefined when the feature is off.
+ * Shared by both transports so a mistyped argument behaves identically. */
+function strictArgOptions(registry, metrics) {
+    const mode = unknownArgMode();
+    if (mode === 'off')
+        return undefined;
+    return {
+        mode,
+        declaredFor: (tool) => registry.declaredKeys(tool),
+        siblingsFor: (tool, keys) => registry.siblingSpellings(tool, keys),
+        onDrop: metrics ? (tool, keys) => metrics.recordArgDrop(tool, keys) : undefined,
+    };
+}
 function buildRegistry(server, ctx, mode, metrics = null) {
     const policy = ctx.policy;
     const registry = new ToolRegistry(server, policy, mode, metrics);
@@ -249,8 +263,9 @@ async function main() {
             const { tapUsageMetrics } = await import('./metrics-tap.js');
             transport = tapUsageMetrics(transport, stdioMetrics, (n) => registry.hasTool(n));
         }
-        await server.connect(argNormalizationEnabled()
-            ? withArgNormalization(transport, (n) => registry.argShape(n), undefined, stdioMetrics ? (tool, n) => stdioMetrics.recordArgFix(tool, n) : undefined)
+        const strictStdio = strictArgOptions(registry, stdioMetrics);
+        await server.connect(argNormalizationEnabled() || strictStdio
+            ? withArgNormalization(transport, (n) => registry.argShape(n), undefined, stdioMetrics ? (tool, n) => stdioMetrics.recordArgFix(tool, n) : undefined, strictStdio)
             : transport);
     }
     if (wantHttp) {
@@ -351,6 +366,7 @@ async function main() {
             argShapeFor: argNormalizationEnabled() ? (n) => registry.argShape(n) : undefined,
             metricsTap: httpTap,
             onArgRename: httpMetrics ? (tool, n) => httpMetrics.recordArgFix(tool, n) : undefined,
+            strictArgs: strictArgOptions(registry, httpMetrics),
         });
         await host.start();
         process.stderr.write(`HTTP transport listening on http://${httpCfg.host}:${httpCfg.port} (public ${httpCfg.publicUrl})\n`);

package/dist/registry.d.ts

@@ -55,6 +55,18 @@ export declare class ToolRegistry {
     /** 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;
+    /** Declared argument keys for a tool, in declaration order; undefined when
+     * the tool is not registered. Backs unknown-argument screening, which needs
+     * the full key list rather than argShape's scalar-kind subset view. */
+    declaredKeys(name: string): readonly string[] | undefined;
+    /** Keys spelling a similar concept elsewhere in the same service, for the
+     * hint on a call whose key matched nothing. Kept only when a key is declared
+     * by at least two tools in the service or by a curated one, so one-off
+     * generated parameters do not become advice. */
+    siblingSpellings(tool: string, unknownKeys: string[]): Array<{
+        key: string;
+        tools: string[];
+    }>;
     catalog(service: string, query?: string): CatalogOperation[];
     /** The metrics recorder, for hook sites (escape hatch); null when off. */
     get usageMetrics(): Metrics | null;

package/dist/registry.js

@@ -4,6 +4,7 @@ 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';
+import { suggestKeys } from './arg-strict.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.
@@ -239,6 +240,47 @@ export class ToolRegistry {
         this.argShapeCache.set(name, shape);
         return shape;
     }
+    /** Declared argument keys for a tool, in declaration order; undefined when
+     * the tool is not registered. Backs unknown-argument screening, which needs
+     * the full key list rather than argShape's scalar-kind subset view. */
+    declaredKeys(name) {
+        const entry = this.tools.find((t) => t.name === name);
+        return entry ? Object.keys(entry.inputShape) : undefined;
+    }
+    /** Keys spelling a similar concept elsewhere in the same service, for the
+     * hint on a call whose key matched nothing. Kept only when a key is declared
+     * by at least two tools in the service or by a curated one, so one-off
+     * generated parameters do not become advice. */
+    siblingSpellings(tool, unknownKeys) {
+        const self = this.tools.find((t) => t.name === tool);
+        if (!self)
+            return [];
+        const declared = new Set(Object.keys(self.inputShape));
+        const byKey = new Map();
+        for (const t of this.tools) {
+            if (t.service !== self.service || t.name === tool)
+                continue;
+            for (const key of Object.keys(t.inputShape)) {
+                if (declared.has(key))
+                    continue;
+                const e = byKey.get(key) ?? { tools: [], curated: false };
+                e.tools.push(t.name);
+                if (!t.generated)
+                    e.curated = true;
+                byKey.set(key, e);
+            }
+        }
+        const candidates = [...byKey.entries()].filter(([, e]) => e.tools.length >= 2 || e.curated);
+        // Reuse the tiered matcher rather than a substring test: the motivating
+        // case (parentId against parentFolderId) fails containment and edit
+        // distance alike, which is the whole reason that matcher exists.
+        const keys = candidates.map(([key]) => key);
+        const hits = new Set(unknownKeys.flatMap((k) => suggestKeys(k, keys)));
+        return candidates
+            .filter(([key]) => hits.has(key))
+            .slice(0, 2)
+            .map(([key, e]) => ({ key, tools: e.tools }));
+    }
     catalog(service, query) {
         const q = query?.trim().toLowerCase();
         return this.tools

package/dist/tools/_coerce.d.ts

@@ -1,8 +1,9 @@
 import { z } from 'zod';
 export declare function coerceArray<T extends z.ZodTypeAny>(element: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<T>>;
 export declare function coerceJson<T extends z.ZodTypeAny>(schema: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, T>;
-/** Numeric args arrive string-encoded from some clients; over stdio the SDK
- * validates the schema directly (the HTTP transport's arg-normalization layer
- * never runs), so the coercion must live in the schema itself. */
+/** Numeric args arrive string-encoded from some clients. Arg normalization
+ * runs on BOTH transports, but it only coerces keys it RENAMED, so a value
+ * sent under the correct key never passes through it and the coercion has to
+ * live in the schema. */
 export declare function coerceNumber<T extends z.ZodTypeAny>(schema: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, T>;
 export declare const coerceBoolean: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>;

package/dist/tools/_coerce.js

@@ -22,9 +22,10 @@ export function coerceArray(element) {
 export function coerceJson(schema) {
     return z.preprocess((val) => (typeof val === 'string' ? parseJsonLoose(val) : val), schema);
 }
-/** Numeric args arrive string-encoded from some clients; over stdio the SDK
- * validates the schema directly (the HTTP transport's arg-normalization layer
- * never runs), so the coercion must live in the schema itself. */
+/** Numeric args arrive string-encoded from some clients. Arg normalization
+ * runs on BOTH transports, but it only coerces keys it RENAMED, so a value
+ * sent under the correct key never passes through it and the coercion has to
+ * live in the schema. */
 export function coerceNumber(schema) {
     return z.preprocess((val) => {
         if (typeof val === 'string' && val.trim() !== '' && !Number.isNaN(Number(val)))

package/dist/tools/drive.js

@@ -273,7 +273,7 @@ export function registerDriveTools(server) {
         description: 'List files in a Google Drive folder or root',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            folderId: z.string().optional().describe('Folder ID (omit for root)'),
+            folderId: z.string().optional().describe('Folder ID to list, omit for root. Named folderId here, not parentFolderId'),
             maxResults: z.number().min(1).max(100).default(50).optional()
                 .describe('Max results to return (default: 50)'),
         },
@@ -307,7 +307,7 @@ export function registerDriveTools(server) {
             filename: z.string().describe('Name as it appears in Drive'),
             mimeType: z.string().optional().describe('Source MIME type of the local file (inferred from extension if omitted). With `convertTo`, this is the format Drive imports from.'),
             convertTo: z.enum(CONVERT_TO_VALUES).optional().describe('Convert the upload into this native Google Workspace type on import: "document" | "spreadsheet" | "presentation" | "drawing" (full application/vnd.google-apps.* ids also accepted). E.g. upload .md/.html/.docx/.txt with convertTo=document to get a real Google Doc. Source must be an importable format. Omit to store the file as-is.'),
-            parentFolderId: z.string().optional().describe('Parent folder ID (defaults to My Drive root)'),
+            parentFolderId: z.string().optional().describe('Parent folder ID, not parentId. Defaults to My Drive root'),
         },
     }, async ({ account, localPath, filename, mimeType: mimeTypeArg, convertTo, parentFolderId }) => {
         try {
@@ -402,7 +402,7 @@ export function registerDriveTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             name: z.string().describe('Folder name'),
-            parentFolderId: z.string().optional().describe('Parent folder ID (defaults to My Drive root)'),
+            parentFolderId: z.string().optional().describe('Parent folder ID, not parentId. Defaults to My Drive root'),
         },
     }, async ({ account, name, parentFolderId }) => {
         try {
@@ -431,7 +431,7 @@ export function registerDriveTools(server) {
             account: accountEnum.describe('Google account alias'),
             fileId: z.string().describe('Google Drive file ID'),
             newName: z.string().optional().describe('New filename'),
-            newParentFolderId: z.string().optional().describe('Move to this folder'),
+            newParentFolderId: z.string().optional().describe('Move to this folder, named newParentFolderId here, not parentFolderId'),
             localPath: z.string().optional().describe('Replace file content with this local file (path on the machine running the server)'),
             mimeType: z.string().optional().describe('MIME type of the replacement file (required if localPath is provided)'),
             convertTo: z.enum(CONVERT_TO_VALUES).optional().describe('When replacing content via localPath, convert the new content into this native Google Workspace type on import: "document" | "spreadsheet" | "presentation" | "drawing" (full application/vnd.google-apps.* ids also accepted).'),
@@ -563,7 +563,7 @@ export function registerDriveTools(server) {
             account: accountEnum.describe('Google account alias'),
             fileId: z.string().describe('Google Drive file ID to copy'),
             newName: z.string().optional().describe('Name for the copy (default: "Copy of <original>")'),
-            parentFolderId: z.string().optional().describe('Where to put the copy (default: same folder)'),
+            parentFolderId: z.string().optional().describe('Where to put the copy, not parentId. Default: same folder'),
         },
     }, async ({ account, fileId, newName, parentFolderId }) => {
         try {
@@ -591,7 +591,7 @@ export function registerDriveTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             fileId: z.string().describe('Google Drive file ID'),
-            newParentFolderId: z.string().describe('Destination folder ID'),
+            newParentFolderId: z.string().describe('Destination folder ID, named newParentFolderId here, not parentFolderId'),
         },
     }, async ({ account, fileId, newParentFolderId }) => {
         try {
@@ -1212,7 +1212,7 @@ export function registerDriveTools(server) {
             fromAccount: requiredAccountEnum.describe('Source account alias'),
             toAccount: requiredAccountEnum.describe('Target account alias'),
             fileId: z.string().describe('File ID in the source account (folders are not supported)'),
-            parentFolderId: z.string().optional().describe('Target folder ID (default: target My Drive root)'),
+            parentFolderId: z.string().optional().describe('Target folder ID, not parentId. Default: target My Drive root'),
             newName: z.string().optional().describe('Rename the copy (default: keep the source name)'),
             move: coerceBoolean.optional().describe('Trash the source after a successful copy (delete-gated)'),
         },

package/dist/usage-metrics.d.ts

@@ -46,6 +46,8 @@ interface ToolAgg {
         calls: number;
     } & Record<string, number>;
     argfix?: number;
+    /** undeclared keys, counted by the DECLARED key they resolve to */
+    argdrop?: Record<string, number>;
 }
 export interface DayAgg {
     v: 1;
@@ -119,6 +121,13 @@ export declare class Metrics {
     recordEscapeMethod(idOrNull: string | null): void;
     /** Search instrument: post-resolution SUPPORTED_APIS keys, or null on failure. */
     recordSearchApi(resolvedApis: string[] | null): void;
+    /**
+     * Undeclared argument keys seen on a call. `resolvedKeys` carries only the
+     * SUGGESTED (declared) key or the literal `_unmatched`, never the caller's
+     * key, so the closed-vocabulary guarantee holds: a client cannot write an
+     * invented string to disk through this path.
+     */
+    recordArgDrop(tool: string, resolvedKeys: string[]): void;
     recordArgFix(tool: string, by?: number): void;
     /** Protocol-level failures (no handler ran); wired by the transport tap. */
     recordRpc(kind: 'schema_validation' | 'tool_not_found' | number, tool?: string): void;

package/dist/usage-metrics.js

@@ -30,6 +30,9 @@ const CHARS_BOUNDS = [64, 256, 1024, 4096, 16384, 65536];
 const METHOD_ID_RE = /^[a-z][a-zA-Z0-9]*(\.[a-zA-Z0-9]+)+$/;
 const METHOD_ID_MAX = 128;
 const TOOL_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
+// Declared argument keys are camelCase identifiers, some dotted
+// (groupKey.id, debugOptions.enableDebugging).
+const ARG_KEY_RE = /^[A-Za-z][A-Za-z0-9_.]{0,63}$/;
 /** Union of every `error:` slug literal emitted anywhere in src/ (kept honest
  * by a set-equality grep test). Anything outside buckets to `other`. */
 export const KNOWN_ERROR_SLUGS = new Set([
@@ -40,7 +43,7 @@ export const KNOWN_ERROR_SLUGS = new Set([
     'invalid_grant', 'invalid_params', 'invalid_query', 'invalid_request',
     'invalid_scope', 'network_error', 'not_found', 'rate_limited',
     'reauth_required', 'recipient_not_allowed', 'too_large', 'toolset_disabled', 'unknown_api',
-    'unknown_method', 'unsupported_grant_type', 'unsupported_type',
+    'unknown_argument', 'unknown_method', 'unsupported_grant_type', 'unsupported_type',
     'untrusted_host', 'upstream_error', 'validation_error', 'write_disabled',
 ]);
 const RPC_CODES = new Set([-32700, -32600, -32601, -32603]);
@@ -138,6 +141,8 @@ export function mergeDay(a, b) {
         const argfix = num(x?.argfix, y?.argfix);
         if (argfix > 0)
             t.argfix = argfix;
+        if (x?.argdrop || y?.argdrop)
+            t.argdrop = map(x?.argdrop, y?.argdrop);
         out.tools[name] = t;
     }
     const slugSet = new Set([...Object.keys(a.hints), ...Object.keys(b.hints)]);
@@ -183,8 +188,11 @@ function applyCaps(day) {
             kept.other = (kept.other ?? 0) + dropped;
         return kept;
     };
-    for (const t of Object.values(day.tools))
+    for (const t of Object.values(day.tools)) {
         t.err = cap(t.err, ERR_SLUG_CAP);
+        if (t.argdrop)
+            t.argdrop = cap(t.argdrop, ERR_SLUG_CAP);
+    }
     // Bounded by the registered tool set via the tap's membership test, but
     // capped anyway: this map is the only one fed by a wire-supplied key.
     day.validation = cap(day.validation, VALIDATION_CAP);
@@ -416,6 +424,28 @@ export class Metrics {
         }
         catch { /* never throws outward */ }
     }
+    /**
+     * Undeclared argument keys seen on a call. `resolvedKeys` carries only the
+     * SUGGESTED (declared) key or the literal `_unmatched`, never the caller's
+     * key, so the closed-vocabulary guarantee holds: a client cannot write an
+     * invented string to disk through this path.
+     */
+    recordArgDrop(tool, resolvedKeys) {
+        try {
+            this.rolloverIfNeeded();
+            if (!TOOL_NAME_RE.test(tool))
+                return;
+            const t = (this.deltas.tools[tool] ??= { n: 0, err: {}, hint: 0, lat: {} });
+            const map = (t.argdrop ??= {});
+            for (const key of resolvedKeys) {
+                if (key !== '_unmatched' && !ARG_KEY_RE.test(key))
+                    continue;
+                addInto(map, key);
+            }
+            this.dirty = true;
+        }
+        catch { /* never throws outward */ }
+    }
     recordArgFix(tool, by = 1) {
         try {
             this.rolloverIfNeeded();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.32",
+  "version": "6.0.0-alpha.33",
   "mcpName": "io.github.bakissation/mcp-google-multi",
   "description": "Local MCP server for Google Workspace (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console, +Forms/Chat/Admin) across multiple accounts — OAuth-only, encrypted token storage, deny-by-default writes.",
   "type": "module",