mcp-google-multi 6.0.0-alpha.1 → 6.0.0-alpha.11

package/README.md

@@ -12,45 +12,46 @@ The most complete **local Google Workspace MCP server**: Gmail, Drive, Calendar,
 
 ## Quick setup
 
-You don't need to know anything about MCP or OAuth — five steps, all copy-paste:
+New to all this? It's written for someone who just installed Claude Code and has never made an API key. Copy-paste each step; it says what you'll see. (Already technical? The [Configuration reference](./docs/configuration.md) is the terse version.)
 
-1. **Install [Node.js](https://nodejs.org) 22 or newer**, then install the server:
+1. **Install it.** Get [Node.js](https://nodejs.org) (the green "LTS" button, version 22 or newer), then run:
 
    ```bash
    npm install -g mcp-google-multi
    ```
 
-2. **Create your (free) Google app** so the server can sign in as you — one-time, ~2 minutes: follow [Google Cloud setup](./docs/google-cloud-setup.md). You come back with a **Client ID** and **Client Secret**.
+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. **Create a file named `.env`** in the folder you'll run from, and fill in your values:
+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:
 
    ```bash
    GOOGLE_CLIENT_ID=paste-your-client-id
    GOOGLE_CLIENT_SECRET=paste-your-client-secret
-   # name each Google account with a short alias:
-   GOOGLE_ACCOUNTS=work:you@company.com,personal:you@gmail.com
-   # encryption key for stored tokens — generate one with: openssl rand -base64 32
-   MASTER_KEY=paste-the-generated-key
+   # any short nickname, then your Gmail address:
+   GOOGLE_ACCOUNTS=me:you@gmail.com
    ```
 
-4. **Sign in each account** (a browser window opens; approve the permissions):
+   No encryption key to make: the server generates and stores one for you.
+
+4. **Sign in.** A browser opens; pick your account and click Allow:
 
    ```bash
-   mcp-google-multi auth --account work
-   mcp-google-multi auth --account personal
+   mcp-google-multi auth --account me
    ```
 
-5. **Connect it to Claude Code** (any MCP client works the same way):
+5. **Add it to Claude Code, then restart Claude Code:**
 
    ```bash
    claude mcp add google-multi -s user -- npx -y mcp-google-multi
    ```
 
-Restart your client and the tools appear. Check everything with `mcp-google-multi config check`.
+**Stuck at any point? Run `mcp-google-multi doctor`.** It inspects every part and prints the exact fix for anything wrong (a missing sign-in, a Google API you still need to switch on, and so on). Once it reads all-green, just talk to Claude: *"summarize my unread email."*
+
+*Got more than one Google account?* Add them together, like `GOOGLE_ACCOUNTS=me:you@gmail.com,work:you@company.com`, and run step 4 once per nickname.
 
-**Running it remotely?** To reach the server from [claude.ai](https://claude.ai) as a custom connector or from another machine, run it over HTTP — it ships its own OAuth 2.1 server, so no bearer tokens to paste. Follow [Remote HTTP setup](./docs/http-setup.md) (Cloudflare named tunnel, Docker, or one-click Render/Railway). Coming from v5? See the [v6 migration guide](./MIGRATION-v6.md).
+*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) · [Upgrading from v4](./docs/upgrading-v4.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) · [Migrating to v6](./MIGRATION-v6.md) · [Security policy](./SECURITY.md) · [Roadmap](https://github.com/bakissation/mcp-google-multi/milestones)
 
 ## Maintainer & credits
 

package/dist/api-probe.d.ts

@@ -0,0 +1,18 @@
+import type { ApiProbeResult } from './doctor.js';
+export interface ApiProbeSpec {
+    service: string;
+    /** console library id for the enable deep-link, e.g. "calendar-json". */
+    api: string;
+    url: string;
+    scopePrefixes: string[];
+    /** id-required APIs have no no-arg read; a 404 on a nonexistent id still
+     * proves the API is enabled (accessNotConfigured wins before routing). */
+    notFoundMeansEnabled?: boolean;
+}
+export declare const API_PROBES: ApiProbeSpec[];
+export declare function planProbes(granted: string[], probes?: ApiProbeSpec[]): ApiProbeSpec[];
+export interface ApiProbeDeps {
+    grantedScopes: (alias: string) => string[];
+    request: (alias: string, url: string) => Promise<void>;
+}
+export declare function probeApiEnablement(alias: string, deps?: ApiProbeDeps): Promise<ApiProbeResult[]>;

package/dist/api-probe.js

@@ -0,0 +1,65 @@
+import { getClient } from './client.js';
+import { readToken } from './token-store.js';
+import { mapGoogleError } from './tools/_errors.js';
+const P = 'https://www.googleapis.com/auth/';
+const BOGUS_ID = 'mcp-google-multi-probe-nonexistent';
+export const API_PROBES = [
+    { service: 'gmail', api: 'gmail', url: 'https://gmail.googleapis.com/gmail/v1/users/me/profile', scopePrefixes: [`${P}gmail.`] },
+    { service: 'drive', api: 'drive', url: 'https://www.googleapis.com/drive/v3/about?fields=user', scopePrefixes: [`${P}drive`] },
+    { service: 'calendar', api: 'calendar-json', url: 'https://www.googleapis.com/calendar/v3/users/me/calendarList?maxResults=1', scopePrefixes: [`${P}calendar`] },
+    // people/me needs profile scopes, not contacts; connections is the read the
+    // contacts grant actually authorizes.
+    { service: 'contacts', api: 'people', url: 'https://people.googleapis.com/v1/people/me/connections?personFields=names&pageSize=1', scopePrefixes: [`${P}contacts`] },
+    { service: 'sheets', api: 'sheets', url: `https://sheets.googleapis.com/v4/spreadsheets/${BOGUS_ID}`, scopePrefixes: [`${P}spreadsheets`], notFoundMeansEnabled: true },
+    { service: 'docs', api: 'docs', url: `https://docs.googleapis.com/v1/documents/${BOGUS_ID}`, scopePrefixes: [`${P}documents`], notFoundMeansEnabled: true },
+    { service: 'searchconsole', api: 'searchconsole', url: 'https://www.googleapis.com/webmasters/v3/sites', scopePrefixes: [`${P}webmasters`] },
+    { service: 'tasks', api: 'tasks', url: 'https://tasks.googleapis.com/tasks/v1/users/@me/lists?maxResults=1', scopePrefixes: [`${P}tasks`] },
+    { 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 },
+];
+export function planProbes(granted, probes = API_PROBES) {
+    return probes.filter((p) => granted.some((s) => p.scopePrefixes.some((prefix) => s.startsWith(prefix))));
+}
+const DEFAULT_DEPS = {
+    grantedScopes: (alias) => {
+        try {
+            const scope = readToken(alias)?.scope;
+            return typeof scope === 'string' ? scope.split(' ').filter(Boolean) : [];
+        }
+        catch {
+            return [];
+        }
+    },
+    request: async (alias, url) => {
+        const auth = await getClient(alias);
+        await auth.request({ url, timeout: 10_000 });
+    },
+};
+export async function probeApiEnablement(alias, deps = DEFAULT_DEPS) {
+    const results = [];
+    for (const spec of planProbes(deps.grantedScopes(alias))) {
+        try {
+            await deps.request(alias, spec.url);
+            results.push({ service: spec.service, api: spec.api, ok: true });
+        }
+        catch (error) {
+            const envelope = mapGoogleError(error, alias);
+            if (envelope.error === 'network_error') {
+                // One connect failure means they will all fail: abort so section 6
+                // reports a single WARN "Probe could not complete" with the code.
+                throw new Error(envelope.message, { cause: error });
+            }
+            if (envelope.error === 'api_not_enabled') {
+                results.push({ service: spec.service, api: spec.api, ok: false, notEnabled: true, message: envelope.message });
+            }
+            else if (spec.notFoundMeansEnabled && envelope.error === 'not_found') {
+                results.push({ service: spec.service, api: spec.api, ok: true });
+            }
+            else {
+                results.push({ service: spec.service, api: spec.api, ok: false, message: envelope.error });
+            }
+        }
+    }
+    return results;
+}

package/dist/arg-normalize.d.ts

@@ -0,0 +1,19 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.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
+ * 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): JSONRPCMessage;
+/** 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): Transport;

package/dist/arg-normalize.js

@@ -0,0 +1,90 @@
+// 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: SDK 1.x 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`)) {
+    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(', ')}`);
+    return {
+        ...msg,
+        params: { ...m.params, arguments: normalized },
+    };
+}
+/** 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) {
+    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) => handler(normalizeMessage(message, shapeFor, log), 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/doctor.d.ts

@@ -2,6 +2,7 @@ import type { ToolRegistry } from './registry.js';
 import { getAccountSet } from './accounts.js';
 import { type AccountHealth } from './tools/accounts-tool.js';
 import { peekMasterKeyProvenance } from './master-key.js';
+import { type HttpConfig } from './http-config.js';
 export type Verdict = 'ok' | 'warn' | 'fail' | 'unknown';
 export interface DiagnosticSection {
     id: number;
@@ -38,6 +39,17 @@ export interface DiagnosticsDeps {
     /** Optional live section-6 probe; when absent the section reports `unknown`
      * (spec: a section that cannot run is unknown, not FAIL). */
     probeApi?: (alias: string) => Promise<ApiProbeResult[]>;
+    /** Optional live section-7 endpoint probe (PRM/AS-metadata self-fetch);
+     * when absent, section 7 stays on its offline config checks. */
+    probeHttp?: (cfg: HttpConfig) => Promise<HttpProbeResult>;
+}
+/** Live §7 probe outcome. `unreachable` = connection-level failure (server not
+ * running), reported as `unknown` rather than FAIL; `problem` = a real
+ * metadata fault at a reachable server. */
+export interface HttpProbeResult {
+    ok: boolean;
+    unreachable?: boolean;
+    problem?: string;
 }
 /** Console deep-link to enable one API (section-6 hint, error taxonomy B10). */
 export declare function apiEnableLink(api: string): string;

package/dist/doctor.js

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

package/dist/http-transport.d.ts

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

package/dist/http-transport.js

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

package/dist/index.js

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

package/dist/net-tuning.d.ts

@@ -0,0 +1,8 @@
+export declare const CONNECT_ATTEMPT_TIMEOUT_MS = 2000;
+/** Pure decision: the timeout to apply, or null to leave Node's setting alone. */
+export declare function decideConnectAttemptTimeout(opts: {
+    execArgv: readonly string[];
+    nodeOptions: string | undefined;
+    current: number;
+}): number | null;
+export declare function applyNetTuning(): void;

package/dist/net-tuning.js

@@ -0,0 +1,25 @@
+import net from 'node:net';
+// Node's happy-eyeballs gives each address family 250ms per connect attempt on
+// every LTS line (raised to 500ms only in v25.2+); on high-latency or
+// broken-IPv6 links that aborts EVERY Google call while curl works. Raise the
+// process default unless the user tuned it themselves. Why: docs/internals.md.
+export const CONNECT_ATTEMPT_TIMEOUT_MS = 2000;
+const USER_FLAGS = ['--network-family-autoselection-attempt-timeout', '--no-network-family-autoselection'];
+/** Pure decision: the timeout to apply, or null to leave Node's setting alone. */
+export function decideConnectAttemptTimeout(opts) {
+    const userArgs = [...opts.execArgv, opts.nodeOptions ?? ''].join(' ');
+    if (USER_FLAGS.some((f) => userArgs.includes(f)))
+        return null;
+    if (opts.current >= CONNECT_ATTEMPT_TIMEOUT_MS)
+        return null;
+    return CONNECT_ATTEMPT_TIMEOUT_MS;
+}
+export function applyNetTuning() {
+    const timeout = decideConnectAttemptTimeout({
+        execArgv: process.execArgv,
+        nodeOptions: process.env.NODE_OPTIONS,
+        current: net.getDefaultAutoSelectFamilyAttemptTimeout(),
+    });
+    if (timeout !== null)
+        net.setDefaultAutoSelectFamilyAttemptTimeout(timeout);
+}

package/dist/registry.d.ts

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

package/dist/registry.js

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

package/dist/scope-catalog.d.ts

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

package/dist/scope-catalog.js

@@ -169,7 +169,7 @@ export function closestBundle(name) {
     }
     return best;
 }
-function editDistance(a, b) {
+export function editDistance(a, b) {
     const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
     for (let j = 1; j <= b.length; j++)
         dp[0][j] = j;

package/dist/tools/_errors.js

@@ -12,6 +12,32 @@ function reasonOf(error) {
 function messageOf(error) {
     return error?.response?.data?.error?.message ?? error?.message ?? String(error);
 }
+// Connect/DNS syscall codes. ENOTFOUND (no such name) is the one non-transient
+// member. node-fetch flattens the happy-eyeballs AggregateError to a bare code
+// with an empty message, so the code is the only surviving signal to surface.
+const RETRIABLE_NET_CODES = new Set([
+    'ETIMEDOUT', 'ECONNRESET', 'ECONNREFUSED', 'ECONNABORTED', 'ENETUNREACH',
+    'EHOSTUNREACH', 'EPIPE', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET',
+]);
+const NET_CODES = new Set([...RETRIABLE_NET_CODES, 'ENOTFOUND']);
+// Local-filesystem syscall codes from caller-supplied paths (localPath/savePath).
+// String codes, so they never collide with Google's numeric statuses; the
+// network codes above are deliberately excluded.
+const LOCAL_FS_CODES = new Set(['ENOENT', 'EACCES', 'EISDIR', 'ENOTDIR', 'EPERM', 'ELOOP', 'ENAMETOOLONG', 'ENOSPC']);
+/** First known network code on the error or its cause chain (GaxiosError.cause
+ * -> FetchError; undici TypeError.cause -> AggregateError.errors). */
+function netCodeOf(error) {
+    for (let e = error, depth = 0; e && depth < 5; e = e.cause ?? e.error, depth++) {
+        if (typeof e.code === 'string' && NET_CODES.has(e.code))
+            return e.code;
+        if (Array.isArray(e.errors)) {
+            const sub = e.errors.find((x) => typeof x?.code === 'string' && NET_CODES.has(x.code));
+            if (sub)
+                return sub.code;
+        }
+    }
+    return undefined;
+}
 /** Console deep-link to enable one API (noob-proofing hint, B10). */
 function apiEnableLink(api) {
     return `https://console.cloud.google.com/apis/library/${api}.googleapis.com`;
@@ -114,6 +140,31 @@ export function mapGoogleError(error, account, forbiddenHint, scopeContext) {
     if (status !== undefined && status >= 500) {
         return { error: 'upstream_error', message, retriable: true, account };
     }
+    if (status === undefined) {
+        const fsCode = typeof error?.code === 'string' && LOCAL_FS_CODES.has(error.code) ? error.code : undefined;
+        if (fsCode) {
+            const p = typeof error?.path === 'string' ? ` "${error.path}"` : '';
+            return {
+                error: 'invalid_params',
+                message: `Cannot access local path${p}: ${fsCode}`,
+                hint: 'The path must exist on the machine running this server and be accessible to it. ' +
+                    'When the server runs remotely (HTTP transport), paths on your own machine are not visible to it.',
+                retriable: false,
+                account,
+            };
+        }
+        const netCode = netCodeOf(error);
+        if (netCode) {
+            return {
+                error: 'network_error',
+                message: message.includes(netCode) ? message : message.endsWith('reason: ') ? `${message}${netCode}` : `${message} (${netCode})`,
+                hint: `Network failure (${netCode}) before reaching Google - not an auth or API problem. Usually transient: retry. ` +
+                    'If it persists on a high-latency or broken-IPv6 link, raise the happy-eyeballs budget: NODE_OPTIONS=--network-family-autoselection-attempt-timeout=4000 (server default 2000ms), and check connectivity with curl.',
+                retriable: RETRIABLE_NET_CODES.has(netCode),
+                account,
+            };
+        }
+    }
     return { error: 'upstream_error', message, retriable: false, account };
 }
 export function handleGoogleApiError(error, account, forbiddenHint, scopeContext) {

package/dist/tools/_local-files.d.ts

@@ -0,0 +1,3 @@
+import * as fs from 'fs';
+export declare function prepareLocalDest(savePath: string, filename: string): string;
+export declare function openLocalReadStream(localPath: string): Promise<fs.ReadStream>;

package/dist/tools/_local-files.js

@@ -0,0 +1,29 @@
+import * as fs from 'fs';
+import * as path from 'path';
+// path.basename() is a traversal guard — a caller-supplied filename must never escape savePath.
+export function prepareLocalDest(savePath, filename) {
+    const dest = path.join(savePath, path.basename(filename));
+    fs.mkdirSync(savePath, { recursive: true });
+    return dest;
+}
+// fs.createReadStream() reports an unopenable path as an async 'error' EVENT;
+// with no listener attached, that single event kills the whole process — fatal
+// for the shared HTTP transport. Opening the fd first turns the open-failure
+// class (ENOENT/EACCES/...) into a normal rejection the caller's try/catch can
+// map to an error envelope.
+export async function openLocalReadStream(localPath) {
+    const handle = await fs.promises.open(localPath, 'r');
+    // open() succeeds on a directory; fail it here rather than as an async read error.
+    if ((await handle.stat()).isDirectory()) {
+        await handle.close();
+        throw Object.assign(new Error(`EISDIR: illegal operation on a directory, read '${localPath}'`), {
+            code: 'EISDIR',
+            path: localPath,
+        });
+    }
+    const stream = handle.createReadStream();
+    // Mid-read errors still reach the consumer through its own listeners; this
+    // one only closes the unhandled-'error' crash path.
+    stream.on('error', () => { });
+    return stream;
+}

package/dist/tools/drive.d.ts

@@ -1,5 +1,6 @@
 import type { ToolRegistry } from '../registry.js';
-export declare function prepareLocalDest(savePath: string, filename: string): string;
+export declare function isTextualMime(mimeType: string): boolean;
+export declare function resolveConvertTarget(convertTo: string | undefined): string | undefined;
 export declare const DRIVE_QUERY_HINT: string;
 export declare function normalizeDriveQuery(raw: string): string;
 export declare function isDriveInvalidQuery(error: any): boolean;

package/dist/tools/drive.js

@@ -4,6 +4,7 @@ import { drive as driveClient } from '@googleapis/drive';
 import { accountAliasSchema, getAccountSet } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
+import { openLocalReadStream, prepareLocalDest } from './_local-files.js';
 import { isAllowed, writeDisabledResult } from '../write-control.js';
 import { capText } from '../trim.js';
 import * as fs from 'fs';
@@ -24,6 +25,52 @@ const GOOGLE_WORKSPACE_TYPES = new Set([
     'application/vnd.google-apps.presentation',
     'application/vnd.google-apps.drawing',
 ]);
+// drive_read inlines only textual content. Beyond text/*, RFC 6839 structured-
+// syntax suffixes (+json/+xml/...) and a few bare application/* types are text
+// in practice — image/svg+xml was the motivating false "binary" refusal.
+const TEXTUAL_EXACT = new Set([
+    'application/json',
+    'application/xml',
+    'application/javascript',
+    'application/x-ndjson',
+    'application/yaml',
+    'application/x-yaml',
+    'application/sql',
+    'application/x-sh',
+    'application/csv',
+]);
+export function isTextualMime(mimeType) {
+    const bare = mimeType.split(';')[0].trim().toLowerCase();
+    if (bare.startsWith('text/'))
+        return true;
+    if (/\+(json|xml|yaml|toml|csv)$/.test(bare))
+        return true;
+    return TEXTUAL_EXACT.has(bare);
+}
+const BINARY_READ_HINT = 'Binary content cannot be inlined. Use drive_download to save the file to disk, or drive_export for Google Workspace files.';
+// Accepted alongside the full application/vnd.google-apps.* ids so the obvious
+// short spelling ("document") works; the enum advertises both.
+const CONVERT_SHORTHANDS = {
+    document: 'application/vnd.google-apps.document',
+    spreadsheet: 'application/vnd.google-apps.spreadsheet',
+    presentation: 'application/vnd.google-apps.presentation',
+    drawing: 'application/vnd.google-apps.drawing',
+};
+export function resolveConvertTarget(convertTo) {
+    if (!convertTo)
+        return undefined;
+    return CONVERT_SHORTHANDS[convertTo] ?? convertTo;
+}
+const CONVERT_TO_VALUES = [
+    'document',
+    'spreadsheet',
+    'presentation',
+    'drawing',
+    'application/vnd.google-apps.document',
+    'application/vnd.google-apps.spreadsheet',
+    'application/vnd.google-apps.presentation',
+    'application/vnd.google-apps.drawing',
+];
 // Comment/Reply fields list — Drive API requires explicit `fields` on every call.
 const COMMENT_BASE_FIELDS = 'id,kind,content,htmlContent,createdTime,modifiedTime,resolved,anchor,author,deleted,quotedFileContent';
 const REPLY_SUBFIELDS = 'id,content,action,createdTime,modifiedTime,author,deleted';
@@ -31,12 +78,6 @@ const COMMENT_FIELDS = `${COMMENT_BASE_FIELDS},replies(${REPLY_SUBFIELDS})`;
 const COMMENT_LIST_FIELDS = `nextPageToken,comments(${COMMENT_BASE_FIELDS},replies(${REPLY_SUBFIELDS}))`;
 const REPLY_FIELDS = `kind,htmlContent,${REPLY_SUBFIELDS}`;
 const REPLY_LIST_FIELDS = `nextPageToken,replies(${REPLY_FIELDS})`;
-// path.basename() is a traversal guard — a caller-supplied filename must never escape savePath.
-export function prepareLocalDest(savePath, filename) {
-    const dest = path.join(savePath, path.basename(filename));
-    fs.mkdirSync(savePath, { recursive: true });
-    return dest;
-}
 export const DRIVE_QUERY_HINT = "Drive search syntax: a plain keyword is treated as a full-text search, but a " +
     "structured query needs an operator, e.g. \"name contains 'report'\", " +
     "\"mimeType = 'application/pdf'\", or \"'me' in owners\". " +
@@ -131,7 +172,7 @@ export function registerDriveTools(server) {
     });
     server.registerTool('drive_read', {
         _meta: { 'anthropic/maxResultSizeChars': 100_000 },
-        description: 'Read the content of a Google Drive file (returns up to maxChars characters per call; non-Google-native files over 2MB return too_large)',
+        description: 'Read the content of a Google Drive file: Workspace docs and textual types (text/*, JSON/XML/SVG and similar) inline; other binaries return error:binary (returns up to maxChars characters per call; non-Google-native files over 2MB return too_large)',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             fileId: z.string().describe('Google Drive file ID'),
@@ -184,6 +225,7 @@ export function registerDriveTools(server) {
                                 name,
                                 mimeType,
                                 error: 'binary',
+                                hint: BINARY_READ_HINT,
                                 webViewLink,
                             }, null, 2),
                         }],
@@ -204,7 +246,7 @@ export function registerDriveTools(server) {
                         }],
                 };
             }
-            if (mimeType?.startsWith('text/')) {
+            if (mimeType && isTextualMime(mimeType)) {
                 const downloaded = await drive.files.get({ fileId, alt: 'media', supportsAllDrives: true }, { responseType: 'text' });
                 return respond(String(downloaded.data));
             }
@@ -216,6 +258,7 @@ export function registerDriveTools(server) {
                             name,
                             mimeType,
                             error: 'binary',
+                            hint: BINARY_READ_HINT,
                             webViewLink,
                         }, null, 2),
                     }],
@@ -259,15 +302,10 @@ export function registerDriveTools(server) {
         description: 'Upload a local file to Google Drive. Pass `convertTo` to import it as a native, editable Google Doc/Sheet/Slides/Drawing instead of storing the raw bytes.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            localPath: z.string().describe('Absolute path to file on disk'),
+            localPath: z.string().describe('Absolute path of the SOURCE file on disk to upload (on the machine running the server; this is not savePath)'),
             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([
-                'application/vnd.google-apps.document',
-                'application/vnd.google-apps.spreadsheet',
-                'application/vnd.google-apps.presentation',
-                'application/vnd.google-apps.drawing',
-            ]).optional().describe('Convert the upload into this native Google Workspace type on import (e.g. upload .md/.html/.docx/.txt with convertTo=...google-apps.document to get a real Google Doc). Source must be an importable format. Omit to store the file as-is.'),
+            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)'),
         },
     }, async ({ account, localPath, filename, mimeType: mimeTypeArg, convertTo, parentFolderId }) => {
@@ -275,13 +313,13 @@ export function registerDriveTools(server) {
             const auth = await getClient(account);
             const drive = driveClient({ version: 'v3', auth });
             const resolvedMime = mimeTypeArg ?? (mime.lookup(localPath) || 'application/octet-stream');
-            const fileStream = fs.createReadStream(localPath);
+            const fileStream = await openLocalReadStream(localPath);
             const res = await drive.files.create({
                 requestBody: {
                     name: filename,
                     parents: parentFolderId ? [parentFolderId] : undefined,
                     // Setting a google-apps target type makes Drive convert the media on import.
-                    ...(convertTo ? { mimeType: convertTo } : {}),
+                    ...(convertTo ? { mimeType: resolveConvertTarget(convertTo) } : {}),
                 },
                 media: {
                     mimeType: resolvedMime,
@@ -303,14 +341,17 @@ export function registerDriveTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             fileId: z.string().describe('Google Drive file ID'),
-            savePath: z.string().describe('Absolute directory path to save into'),
-            filename: z.string().describe('Filename to save as'),
+            savePath: z.string().describe('Absolute DIRECTORY path to save into (created if missing, on the machine running the server); the file name comes from `filename`'),
+            filename: z.string().optional().describe('Filename to save as (defaults to the file name in Drive)'),
         },
     }, async ({ account, fileId, savePath, filename }) => {
         try {
             const auth = await getClient(account);
             const drive = driveClient({ version: 'v3', auth });
-            const dest = prepareLocalDest(savePath, filename);
+            const name = filename
+                ?? (await drive.files.get({ fileId, fields: 'name', supportsAllDrives: true })).data.name
+                ?? fileId;
+            const dest = prepareLocalDest(savePath, name);
             const res = await drive.files.get({ fileId, alt: 'media', supportsAllDrives: true }, { responseType: 'stream' });
             // pipeline destroys both streams on source/sink error; raw .pipe leaks the partial file.
             await pipeline(res.data, fs.createWriteStream(dest, { mode: 0o600 }));
@@ -329,14 +370,20 @@ export function registerDriveTools(server) {
             account: accountEnum.describe('Google account alias'),
             fileId: z.string().describe('Google Drive file ID'),
             mimeType: z.string().describe('Target export MIME type (e.g. "application/pdf", "text/markdown", "application/vnd.openxmlformats-officedocument.wordprocessingml.document")'),
-            savePath: z.string().describe('Absolute directory path to save into'),
-            filename: z.string().describe('Filename to save as'),
+            savePath: z.string().describe('Absolute DIRECTORY path to save into (created if missing, on the machine running the server); the file name comes from `filename`'),
+            filename: z.string().optional().describe('Filename to save as (defaults to the Drive name plus the extension implied by mimeType)'),
         },
     }, async ({ account, fileId, mimeType: exportMime, savePath, filename }) => {
         try {
             const auth = await getClient(account);
             const drive = driveClient({ version: 'v3', auth });
-            const dest = prepareLocalDest(savePath, filename);
+            let name = filename;
+            if (!name) {
+                const meta = await drive.files.get({ fileId, fields: 'name', supportsAllDrives: true });
+                const ext = mime.extension(exportMime);
+                name = `${meta.data.name ?? fileId}${ext ? `.${ext}` : ''}`;
+            }
+            const dest = prepareLocalDest(savePath, name);
             const res = await drive.files.export({ fileId, mimeType: exportMime }, { responseType: 'stream' });
             // pipeline destroys both streams on source/sink error; raw .pipe leaks the partial file.
             await pipeline(res.data, fs.createWriteStream(dest, { mode: 0o600 }));
@@ -384,14 +431,9 @@ export function registerDriveTools(server) {
             fileId: z.string().describe('Google Drive file ID'),
             newName: z.string().optional().describe('New filename'),
             newParentFolderId: z.string().optional().describe('Move to this folder'),
-            localPath: z.string().optional().describe('Replace file content with this local file'),
+            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([
-                'application/vnd.google-apps.document',
-                'application/vnd.google-apps.spreadsheet',
-                'application/vnd.google-apps.presentation',
-                'application/vnd.google-apps.drawing',
-            ]).optional().describe('When replacing content via localPath, convert the new content into this native Google Workspace type on import (e.g. replace a Google Doc body from a local .docx). Source must be an importable format.'),
+            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).'),
         },
     }, async ({ account, fileId, newName, newParentFolderId, localPath: localPathArg, mimeType: mimeTypeArg, convertTo }) => {
         try {
@@ -414,10 +456,10 @@ export function registerDriveTools(server) {
             if (localPathArg) {
                 params.media = {
                     mimeType: mimeTypeArg ?? (mime.lookup(localPathArg) || 'application/octet-stream'),
-                    body: fs.createReadStream(localPathArg),
+                    body: await openLocalReadStream(localPathArg),
                 };
                 if (convertTo)
-                    requestBody.mimeType = convertTo;
+                    requestBody.mimeType = resolveConvertTarget(convertTo);
             }
             const res = await drive.files.update(params);
             return {
@@ -1440,7 +1482,7 @@ async function downloadAndUpload(sourceDrive, targetDrive, fileId, sourceMime, p
             },
             media: {
                 mimeType: plan.kind === 'native' ? plan.exportMime : (sourceMime ?? 'application/octet-stream'),
-                body: fs.createReadStream(tmp),
+                body: await openLocalReadStream(tmp),
             },
             supportsAllDrives: true,
             fields: 'id,name,mimeType,webViewLink',

package/dist/tools/gmail.js

@@ -5,6 +5,7 @@ import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError, mapGoogleError } from './_errors.js';
 import { buildReplyHeaders, composeRaw, renderMarkdown, htmlToMarkdown, HeaderInjectionError } from './gmail-mime.js';
+import { prepareLocalDest } from './_local-files.js';
 import addressparser from 'nodemailer/lib/addressparser/index.js';
 import { lookup as lookupMime } from 'mime-types';
 import { configDir } from '../config-file.js';
@@ -664,7 +665,7 @@ export function registerGmailTools(server) {
             messageId: z.string().describe('The Gmail message ID'),
             attachmentId: z.string().describe('The attachment ID from gmail_read response'),
             filename: z.string().describe('Filename to save as (e.g. report.xlsx)'),
-            savePath: z.string().describe('Absolute directory path to save into, e.g. /home/user/Downloads'),
+            savePath: z.string().describe('Absolute DIRECTORY path to save into (created if missing, on the machine running the server), e.g. /home/user/Downloads; the file name comes from `filename`'),
         },
     }, async ({ account, messageId, attachmentId, filename, savePath }) => {
         try {
@@ -679,8 +680,7 @@ export function registerGmailTools(server) {
             if (!data)
                 throw new Error('No attachment data returned');
             const buffer = Buffer.from(data, 'base64url');
-            // Strip path components so callers can't escape savePath via "../".
-            const fullPath = path.join(savePath, path.basename(filename));
+            const fullPath = prepareLocalDest(savePath, filename);
             await fs.promises.writeFile(fullPath, buffer, { mode: 0o600 });
             return {
                 content: [{ type: 'text', text: `Saved to ${fullPath} (${buffer.length} bytes)` }],

package/dist/tools/google-api.d.ts

@@ -2,9 +2,12 @@ import type { ToolRegistry } from '../registry.js';
 import { type Policy } from '../write-control.js';
 import { getClient } from '../client.js';
 import { type Toolsets } from '../toolsets.js';
-import { type DiscoveryDeps } from '../discovery-client.js';
+import { type DiscoveryDeps, type DiscoveryMethod } from '../discovery-client.js';
 export interface EscapeDeps extends DiscoveryDeps {
     getClientFn?: typeof getClient;
     toolsets?: Toolsets;
 }
+/** Up to three closest known ids for the unknown_method did-you-mean hint;
+ * bounded distance so unrelated ids never masquerade as suggestions. */
+export declare function nearestMethodIds(methodId: string, index: DiscoveryMethod[]): string[];
 export declare function registerEscapeTools(registry: ToolRegistry, policy: Policy, deps?: EscapeDeps): void;

package/dist/tools/google-api.js

@@ -4,6 +4,7 @@ import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
 import { coerceJson } from './_coerce.js';
 import { getToolsets, toolsetEnabled } from '../toolsets.js';
+import { editDistance } from '../scope-catalog.js';
 import { executeApiMethod, jsonResult } from '../executor.js';
 import { WORKSPACE_APIS, cudFromMethod, loadMethodIndex, searchMethods, } from '../discovery-client.js';
 const accountEnum = accountAliasSchema.optional();
@@ -29,6 +30,17 @@ const SERVICE_FOR_ALIAS = {
     admin_datatransfer: 'admin',
     groupssettings: 'groupssettings',
 };
+/** Up to three closest known ids for the unknown_method did-you-mean hint;
+ * bounded distance so unrelated ids never masquerade as suggestions. */
+export function nearestMethodIds(methodId, index) {
+    const maxDist = Math.max(3, Math.floor(methodId.length / 3));
+    return index
+        .map((m) => ({ id: m.id, d: editDistance(methodId.toLowerCase(), m.id.toLowerCase()) }))
+        .filter((x) => x.d <= maxDist)
+        .sort((a, b) => a.d - b.d)
+        .slice(0, 3)
+        .map((x) => x.id);
+}
 function describeMethod(m) {
     return {
         api: m.api,
@@ -127,12 +139,25 @@ export function registerEscapeTools(registry, policy, deps = {}) {
         catch (err) {
             return jsonResult({ error: 'discovery_unavailable', message: err.message, retriable: true, account }, true);
         }
-        const method = index.find((m) => m.id === methodId);
+        let method = index.find((m) => m.id === methodId);
+        if (!method) {
+            // Some discovery docs keep a legacy id prefix (the searchconsole doc's
+            // methods are webmasters.*): when the caller prefixed with our api
+            // alias, retry under the doc's own prefix before failing.
+            const docPrefix = index[0]?.id.split('.')[0];
+            const [head, ...rest] = String(methodId).split('.');
+            if (docPrefix && head === api && head !== docPrefix && rest.length > 0) {
+                const swapped = [docPrefix, ...rest].join('.');
+                method = index.find((m) => m.id === swapped);
+            }
+        }
         if (!method) {
+            const near = nearestMethodIds(String(methodId), index);
             return jsonResult({
                 error: 'unknown_method',
                 message: `No method "${methodId}" in ${api}.`,
-                hint: `Use google_api_search({query: "...", api: "${api}"}) to find the right method id.`,
+                hint: `${near.length ? `Did you mean: ${near.join(', ')}? ` : ''}` +
+                    `Use google_api_search({query: "...", api: "${api}"}) to find the right method id.`,
                 retriable: false,
                 account,
             }, true);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.1",
+  "version": "6.0.0-alpha.11",
   "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",
   "license": "MIT",
@@ -61,22 +61,22 @@
     "pack:mcpb": "mcpb pack . mcp-google-multi.mcpb"
   },
   "dependencies": {
-    "@googleapis/admin": "^33.0.0",
-    "@googleapis/calendar": "^16.0.0",
-    "@googleapis/chat": "^47.0.0",
-    "@googleapis/docs": "^10.0.0",
-    "@googleapis/drive": "^22.0.0",
-    "@googleapis/forms": "^7.0.0",
-    "@googleapis/gmail": "^18.0.0",
-    "@googleapis/meet": "^5.0.0",
-    "@googleapis/people": "^8.0.0",
-    "@googleapis/searchconsole": "^7.0.0",
-    "@googleapis/sheets": "^14.0.0",
-    "@googleapis/slides": "^6.0.0",
-    "@googleapis/tasks": "^13.0.0",
-    "@googleapis/webmasters": "^4.0.0",
+    "@googleapis/admin": "^37.0.0",
+    "@googleapis/calendar": "^20.0.0",
+    "@googleapis/chat": "^51.0.0",
+    "@googleapis/docs": "^14.0.0",
+    "@googleapis/drive": "^26.0.0",
+    "@googleapis/forms": "^11.0.0",
+    "@googleapis/gmail": "^22.0.0",
+    "@googleapis/meet": "^9.0.0",
+    "@googleapis/people": "^12.0.0",
+    "@googleapis/searchconsole": "^11.0.0",
+    "@googleapis/sheets": "^18.0.0",
+    "@googleapis/slides": "^10.0.0",
+    "@googleapis/tasks": "^17.0.0",
+    "@googleapis/webmasters": "^9.0.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "googleapis-common": "^8.0.3",
+    "googleapis-common": "^9.0.0",
     "jose": "^6.2.8",
     "markdown-it": "15.0.0",
     "mime-types": "^3.0.2",