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

package/README.md

@@ -53,11 +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)
-
-## Local usage metrics (off by default)
-
-The server can keep anonymous, **local-only** usage aggregates for its operator: tool names, error classes, latency buckets. Never arguments, payloads, message content, accounts, or identities of any kind, and **zero network egress ever** — the data cannot leave your machine unless you copy files yourself. It is off until you set `GOOGLE_USAGE_METRICS=on`; when on, the boot log and `doctor` say so and name the source. Read your own data with `mcp-google-multi metrics report`. Details, file format, and the honest threat model: [docs/usage-metrics.md](./docs/usage-metrics.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) · [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

@@ -30,6 +30,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

package/dist/accounts.js

@@ -278,6 +278,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,7 +295,9 @@ 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);

package/dist/arg-normalize.d.ts

@@ -1,5 +1,6 @@
 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
@@ -18,6 +19,10 @@ export interface StrictArgOptions {
     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 = {
@@ -38,3 +43,34 @@ export declare function screenMessage(msg: JSONRPCMessage, opts: StrictArgOption
  * 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

@@ -1,4 +1,21 @@
 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
@@ -77,9 +94,23 @@ export function screenMessage(msg, opts, log = (l) => process.stderr.write(`${l}
         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 };
+    // 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 };
@@ -134,15 +165,18 @@ export function withArgNormalization(transport, shapeFor, log, onRename, strict)
                     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 transport.send(outcome.response);
+                        void Promise.resolve(transport.send(outcome.response)).catch(fallback);
                     }
                     catch {
-                        // Last-resort: dispatch as before rather than hang the caller.
-                        // The stderr line and the counter already fired above.
-                        handler(normalized, extra);
+                        fallback();
                     }
                 }
                 : undefined;
@@ -169,3 +203,112 @@ export function withArgNormalization(transport, shapeFor, log, onRename, strict)
     }
     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

@@ -1,7 +1,9 @@
 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.
+ * `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:

package/dist/arg-strict.js

@@ -11,8 +11,10 @@
 // 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.
+ * `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 function unknownArgMode(env = process.env) {
     const raw = (env.GOOGLE_ARG_UNKNOWN ?? '').trim().toLowerCase();
@@ -20,21 +22,38 @@ export function unknownArgMode(env = process.env) {
         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;
+    process.stderr.write(`GOOGLE_ARG_UNKNOWN="${raw}" is not valid (reject | warn | off); using warn\n`);
+    return 'warn';
 }
-// 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';
+// The staged rollout is over: `warn` shipped first as pure observability, and
+// this is the flip it was staging for. An undeclared argument is dropped by
+// zod before the handler runs, so `warn` means the CLIENT sees a confident
+// success for a call the server did not perform: drive_list with a misspelled
+// folder key returned the My Drive root, byte-identical to no argument at all.
+// A wrong answer that reads as right is the failure mode agents recover from
+// worst, so the default refuses the call and says what it probably meant.
+const DEFAULT_MODE = 'reject';
 /** 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();
+/** Keys a CLIENT adds on its own, not keys the model chose. `random_string`
+ * is the long-standing probe some clients send to a tool they read as taking
+ * no arguments; the others are call-plumbing that bridges and proxies have
+ * been observed to fold into `arguments` instead of `params._meta`, where the
+ * spec puts them. Rejecting these would fail a call the model got right.
+ * Measured against the full 978-tool surface: none is a declared key. */
+const CLIENT_ARTIFACT_KEYS = new Set([
+    'random_string',
+    'toolCallId',
+    'tool_call_id',
+    'tool_call_description',
+]);
 /** 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('/');
+    return key.startsWith('_') || key.includes('/') || CLIENT_ARTIFACT_KEYS.has(key);
 }
 /** Generic words that must never be offered as a suggestion on containment
  * alone; they match far too much to be useful. */

package/dist/client.js

@@ -2,24 +2,32 @@ import { OAuth2Client } from 'googleapis-common';
 import { getAccountSet, refreshAccountSetIfStale } from './accounts.js';
 import { readToken, updateToken } from './token-store.js';
 import { reauthHint } from './reauth-hint.js';
+/** A local precondition failure, carrying a code the error mapper classifies
+ * on. Without it these land on the generic floor and read as Google errors. */
+function tagged(message, code) {
+    return Object.assign(new Error(message), { code });
+}
 export async function getClient(account) {
     // BR-7: lazy cross-process reload — one stat per dispatch, no watcher;
     // reload failures keep the last-good registry, never kill the server.
     refreshAccountSetIfStale();
     const config = getAccountSet().configs[account];
     if (!config) {
-        throw new Error(`Unknown account "${account}". Valid aliases: ${getAccountSet().aliases.join(', ')}`);
+        // Tagged so mapGoogleError can classify it. Untagged, a caller's typo in
+        // an alias came back as `upstream_error` with "Unclassified error", i.e.
+        // the server blaming Google for a local argument mistake.
+        throw tagged(`Unknown account "${account}". Valid aliases: ${getAccountSet().aliases.join(', ')}`, 'E_UNKNOWN_ACCOUNT');
     }
     if (!process.env.GOOGLE_CLIENT_ID || !process.env.GOOGLE_CLIENT_SECRET) {
-        throw new Error('GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET must be set. ' +
-            'Check that .env exists in the project root or pass them as env vars.');
+        throw tagged('GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET must be set. ' +
+            'Check that .env exists in the project root or pass them as env vars.', 'E_NO_OAUTH_CLIENT');
     }
     // Redirect URI is unused on the refresh-token grant; consent flows bind an
     // ephemeral loopback port at auth time (oauth-consent.ts).
     const oauth2Client = new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost/oauth2callback');
     const tokenData = readToken(account);
     if (!tokenData) {
-        throw new Error(`No token found for account "${account}" (${config.email}). ${reauthHint(account)}`);
+        throw tagged(`No token found for account "${account}" (${config.email}). ${reauthHint(account)}`, 'E_NO_TOKEN');
     }
     oauth2Client.setCredentials(tokenData);
     oauth2Client.on('tokens', (tokens) => {

package/dist/discovery-client.js

@@ -198,11 +198,22 @@ export function clearDiscoveryMemoryCache() {
 }
 // GA4-style report execution (runReport, batchRunPivotReports, runAccessReport)
 // and check* predicates are POSTs purely for the request-body size — reads.
-const POST_READ_VERB = /^(get|list|search|query|lookup|count|batchGet|generateIds|export|download|inspect|check|(batch)?run\w*report)/i;
-const POST_UPDATE_VERB = /^(untrash|undelete|restore|modify|move|set|sort|merge|unmerge|replace|resize|publish|resolve|update|patch|write|format)/i;
+const POST_READ_VERB = /^(get|list|search|query|lookup|count|batchGet|generateIds|export|download|inspect|check|suggest|(batch)?run\w*report)/i;
+// `cancelWipe` must be matched here, BEFORE `cancel` reaches the delete list:
+// it calls off a pending wipe, which is the opposite of one. Update is tested
+// before delete for exactly that reason.
+// State transitions on something that already exists: reversible, and none of
+// them creates anything, so `create` was both wrong and the most permissive
+// class available. `(batch)?` mirrors the delete list, without which every
+// `batchUpdate*` POST fell through to `create`.
+const POST_UPDATE_VERB = /^(cancelWipe|(batch)?(untrash|undelete|restore|modify|move|set|sort|merge|unmerge|replace|resize|publish|resolve|update|patch|write|format|change|close|reopen|enable|disable|hide|unhide|accept|approve|decline|reassign|reactivate|renew|mark|turn|suspend|activate|make|return|reclaim|complete))/i;
 // archive sits with the deletes: in GA4 archiving a custom dimension/metric is
 // permanent, so the most restrictive write class is the safe classification.
-const POST_DELETE_VERB = /^(batch)?(delete|remove|trash|clear|empty|obliterate|purge|revoke|wipeout|archive)/i;
+// So do the teardown verbs: `stop` and `cancel` tear down a push channel or a
+// long-running operation, `wipe`/`invalidate`/`signOut` destroy device data,
+// codes and sessions, `reset` discards a configuration, and `end` terminates a
+// live conference. Each removes something that existed.
+const POST_DELETE_VERB = /^(batch)?(delete|remove|trash|clear|empty|obliterate|purge|revoke|wipeout|archive|wipe|invalidate|signOut|stop|cancel|unregister|unreserve|reset|end)/i;
 export function cudFromMethod(method) {
     switch (method.httpMethod) {
         case 'GET':
@@ -233,7 +244,23 @@ export function expandPath(template, pathParams) {
         if (value === undefined) {
             throw new Error(`Missing required path parameter "${name}"`);
         }
-        return plus ? String(value).split('/').map(encodeURIComponent).join('/') : encodeURIComponent(String(value));
+        // A blank segment collapses the path and Google routes the resulting
+        // trailing-slash URL to the COLLECTION: `sites.get` with siteUrl:"" came
+        // back as the whole site LIST, reported as success. Dot segments resolve
+        // at URL-parse time, so `../v1/contactGroups` retargets the call at a
+        // different endpoint and returns ITS response as success. Both are
+        // silent-wrong, so refuse locally rather than send a different request.
+        // `{+param}` keeps its slashes, so every segment has to be checked.
+        const segments = plus ? String(value).split('/') : [String(value)];
+        for (const segment of segments) {
+            if (segment.trim() === '') {
+                throw new Error(`Path parameter "${name}" is empty. An empty value addresses the collection, not one resource, so nothing was sent to Google.`);
+            }
+            if (segment === '.' || segment === '..') {
+                throw new Error(`Path parameter "${name}" contains a "${segment}" path segment, which would retarget the request at a different endpoint. Nothing was sent to Google.`);
+            }
+        }
+        return segments.map(encodeURIComponent).join('/');
     });
 }
 export function searchMethods(index, query, limit = 10) {

package/dist/doctor.d.ts

@@ -67,7 +67,12 @@ export declare function renderReport(report: DiagnosticsReport, version: string)
 /** Exit non-zero when any section FAILs; with strict, WARN counts too. */
 export declare function exitCodeFor(report: DiagnosticsReport, strict: boolean): number;
 /** Agent-callable structured health report (read-only). Mirrors `doctor`'s
- * engine; NOT alwaysLoad (the agent asks for it when diagnosing). */
+ * engine. Registered as a META tool, like `account_list`: it introspects this
+ * server rather than Google data, and as a normal tool it became a service of
+ * its own with no `{service}_discover` to reveal it (discover tools are built
+ * from already-registered services, and this runs after that), so it was
+ * advertised only once something else expanded the surface. The README sends
+ * people here when they are stuck, so it has to be findable. */
 export declare function registerDiagnoseTool(registry: ToolRegistry): void;
 export interface ResetOptions {
     account?: string;

package/dist/doctor.js

@@ -9,6 +9,7 @@ import { configDir, loadConfigFile } from './config-file.js';
 import { envValueSource } from './env-load.js';
 import { describeMetricsDir, resolveUsageMetrics, sourceLabel } from './usage-metrics.js';
 import { probeApiEnablement } from './api-probe.js';
+import { safeMessage, stringifyEnvelope } from './tools/_errors.js';
 import { resolveHttpConfig, HttpConfigError } from './http-config.js';
 import { parseOwnerEmails } from './http-transport.js';
 const MIN_NODE_MAJOR = 22;
@@ -356,9 +357,14 @@ export function exitCodeFor(report, strict) {
     return 0;
 }
 /** Agent-callable structured health report (read-only). Mirrors `doctor`'s
- * engine; NOT alwaysLoad (the agent asks for it when diagnosing). */
+ * engine. Registered as a META tool, like `account_list`: it introspects this
+ * server rather than Google data, and as a normal tool it became a service of
+ * its own with no `{service}_discover` to reveal it (discover tools are built
+ * from already-registered services, and this runs after that), so it was
+ * advertised only once something else expanded the surface. The README sends
+ * people here when they are stuck, so it has to be findable. */
 export function registerDiagnoseTool(registry) {
-    registry.registerTool('diagnose', {
+    registry.registerMeta('diagnose', {
         annotations: { readOnlyHint: true, openWorldHint: true },
         description: 'Health report for this server: runtime, config, keys, per-account token status, scope grants, and API enablement. Read-only; returns copy-pasteable fixes for anything wrong. Call this to diagnose auth/config failures.',
         inputSchema: {},
@@ -368,7 +374,11 @@ export function registerDiagnoseTool(registry) {
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
         }
         catch (e) {
-            return { content: [{ type: 'text', text: JSON.stringify({ error: 'diagnose_failed', message: e?.message ?? String(e) }) }], isError: true };
+            return { content: [{ type: 'text', text: stringifyEnvelope({
+                            error: 'diagnose_failed',
+                            message: safeMessage(e),
+                            retriable: false,
+                        }) }], isError: true };
         }
     });
 }

package/dist/executor.js

@@ -1,4 +1,5 @@
 import { getClient } from './client.js';
+import { sliceEncoded } from './trim.js';
 import { expandPath, isGoogleApiUrl } from './discovery-client.js';
 import { handleGoogleApiError } from './tools/_errors.js';
 import { scopeHintForMethod } from './scope-observability.js';
@@ -88,10 +89,14 @@ export async function executeApiMethod(method, args, deps = {}) {
         });
         const text = JSON.stringify(res.data ?? null);
         if (text.length > MAX_RESPONSE_CHARS) {
+            // Budget the ENCODED head: jsonResult re-stringifies it, so every quote
+            // and backslash inside doubles. Slicing raw characters made the emitted
+            // result exceed the cap this tool advertises, by up to 15 percent on a
+            // quote-dense listing.
             return jsonResult({
                 truncated: true,
                 totalChars: text.length,
-                head: text.slice(0, MAX_RESPONSE_CHARS),
+                head: sliceEncoded(text, MAX_RESPONSE_CHARS),
                 hint: 'Narrow the request (fields mask, pageSize) to get complete JSON.',
             });
         }

package/dist/fanout.js

@@ -1,21 +1,33 @@
 import { z } from 'zod';
-import { ACCOUNTS, getAccountSet } from './accounts.js';
+import { ACCOUNTS, getAccountSet, unknownAliasMessage } from './accounts.js';
 export const CSV_RE = /^[a-zA-Z0-9_-]+(\s*,\s*[a-zA-Z0-9_-]+)+$/;
 const FANOUT_CONCURRENCY = 5;
 export function fanoutAccountField(description) {
     const csvExample = ACCOUNTS.length > 1 ? `; or a CSV subset like "${ACCOUNTS.slice(0, 2).join(',')}"` : '';
+    // The union's OWN error only fires when every branch aborts at the type
+    // check (a non-string). For a string, zod surfaces the single non-aborted
+    // branch verbatim, which is the CSV regex, so a mistyped alias used to read
+    // as "Invalid string: must match pattern /^[a-zA-Z0-9_-]+(,...)/" and never
+    // named an alias. Hence the same message on BOTH.
+    const bad = () => unknownAliasMessage(ACCOUNTS, true);
     return z
         // '*' first so the tuple is statically non-empty even when ACCOUNTS is empty
         // (a fresh install): z.enum requires [string, ...string[]].
-        .union([z.enum(['*', ...ACCOUNTS]), z.string().regex(CSV_RE)])
+        .union([z.enum(['*', ...ACCOUNTS]), z.string().regex(CSV_RE, { error: bad })], { error: bad })
         .optional()
         .describe(`${description}; "*" = all accounts${csvExample}; omit for the default account`);
 }
 export function parseAccountSelector(value, accounts = getAccountSet().aliases) {
     if (value === '*')
         return { ok: true, fanout: true, aliases: [...accounts] };
-    if (!value.includes(','))
-        return { ok: true, fanout: false, aliases: [value] };
+    // A single alias used to skip validation entirely and reach getClient, whose
+    // throw landed on the mapper's floor as an unclassified upstream_error. Same
+    // check and same envelope wherever the alias was typed.
+    if (!value.includes(',')) {
+        return accounts.includes(value)
+            ? { ok: true, fanout: false, aliases: [value] }
+            : { ok: false, invalid: [value] };
+    }
     const seen = new Set();
     const aliases = [];
     const invalid = [];
@@ -30,7 +42,9 @@ export function parseAccountSelector(value, accounts = getAccountSet().aliases)
     }
     if (invalid.length > 0)
         return { ok: false, invalid };
-    return { ok: true, fanout: aliases.length > 1, aliases };
+    // Keyed on the CSV FORM, not the deduped count: "a,a" asked for the merged
+    // multi-account envelope and used to get a bare single-account payload.
+    return { ok: true, fanout: true, aliases };
 }
 export function invalidAccountsResult(invalid, accounts = getAccountSet().aliases) {
     return {
@@ -40,8 +54,9 @@ export function invalidAccountsResult(invalid, accounts = getAccountSet().aliase
                 text: JSON.stringify({
                     error: 'validation_error',
                     message: `Unknown account alias(es): ${invalid.join(', ')}.`,
-                    hint: `Valid aliases: ${accounts.join(', ')}; or "*" for all accounts.`,
+                    hint: unknownAliasMessage(accounts, true),
                     retriable: false,
+                    account: invalid.join(','),
                 }),
             },
         ],
@@ -82,7 +97,27 @@ export async function runFanout(handler, args, aliases) {
     };
     await Promise.all(Array.from({ length: Math.min(FANOUT_CONCURRENCY, aliases.length) }, () => worker()));
     const failed = results.filter((r) => !r.ok).length;
+    if (failed === results.length && results.length > 0) {
+        // Every account failed, so this IS an error result, and used to carry
+        // `isError` with no top-level error, hint or retriable: the agent saw a
+        // successful-looking object flagged as an error, and metrics bucketed it
+        // as `other`. Hoist a real envelope, keeping the per-account detail.
+        const slugs = [...new Set(results.map((r) => r.error?.error ?? 'internal'))];
+        const hints = [...new Set(results.map((r) => r.error?.hint).filter(Boolean))];
+        const retriable = results.every((r) => r.error?.retriable === true);
+        return {
+            content: [{ type: 'text', text: JSON.stringify({
+                        error: 'fanout_failed',
+                        message: `All ${results.length} accounts failed: ${slugs.join(', ')}. Per-account detail is in results.`,
+                        hint: hints.length === 1 ? hints[0] : 'Each entry in results carries its own error and hint; they differ per account.',
+                        retriable,
+                        account: aliases.join(','),
+                        results,
+                        partial: true,
+                    }) }],
+            isError: true,
+        };
+    }
     const body = { results, partial: failed > 0 };
-    const out = { content: [{ type: 'text', text: JSON.stringify(body) }] };
-    return failed === results.length ? { ...out, isError: true } : out;
+    return { content: [{ type: 'text', text: JSON.stringify(body) }] };
 }

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, type StrictArgOptions } from './arg-normalize.js';
+import { type ArgShape, type StrictArgOptions, type ValidationEnvelopeOptions } from './arg-normalize.js';
 export type AuthOutcome = {
     ok: true;
 } | {
@@ -33,6 +33,9 @@ export interface HttpHostOptions {
     argShapeFor?: (tool: string) => ArgShape | undefined;
     /** Usage-metrics transport tap (metrics-tap.ts); absent = off. */
     metricsTap?: (t: Transport) => Transport;
+    /** Wired identically on both transports so a schema rejection reads the same
+     * over stdio and over HTTP. */
+    validationEnvelope?: ValidationEnvelopeOptions;
     /** Usage-metrics argfix observer, forwarded into arg normalization. */
     onArgRename?: (tool: string, renames: number) => void;
     /** Unknown-argument screening (arg-strict.ts); absent = off. */