mcp-google-multi 5.4.1-alpha.2 → 6.0.0-alpha.10

package/README.md

@@ -4,49 +4,54 @@ The most complete **local Google Workspace MCP server**: Gmail, Drive, Calendar,
 
 [![npm](https://img.shields.io/npm/v/mcp-google-multi?label=npm&color=cb3837)](https://www.npmjs.com/package/mcp-google-multi)
 
-- 🧰 **Exhaustive** — 872 tools across 28 services + an escape hatch for anything else → [COVERAGE.md](./COVERAGE.md)
+- 🧰 **Exhaustive** — 874 tools across 28 services + an escape hatch for anything else → [COVERAGE.md](./COVERAGE.md)
 - 🔑 **Multi-account** — drive any number of Google accounts by alias, or fan one call out across all of them
 - 🔒 **Private by design** — your own OAuth app, tokens encrypted at rest (AES-256-GCM), writes deny-by-default, no telemetry, no metering — it talks only to Google
+- 🌐 **Local or remote** — runs locally over stdio, or self-hosted over HTTP with its own built-in OAuth 2.1 server (Claude Code's `/mcp` login and the claude.ai connector, zero custom UI) → [remote setup](./docs/http-setup.md)
+- ✉️ **Built for real work** — send and read email in Markdown with attachments and one-call replies, an interactive setup wizard with a `doctor` self-check, and per-account scope profiles → [features tour](./docs/features.md)
 
 ## Quick setup
 
-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) 20 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.
+
+*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) · [Secrets in a vault](./docs/secrets.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
 
@@ -54,7 +59,7 @@ Built and maintained by **Abdelbaki Berkati** — [berkati.xyz](https://berkati.
 
 Development is **funded by [IdeaCrafters](https://ideacrafters.com)** ([@IdeaCraftersHQ](https://github.com/IdeaCraftersHQ)) — the studio that pays for this OSS to exist.
 
-Thanks to contributors [@obatried](https://github.com/obatried), [@trevor-commits](https://github.com/trevor-commits), and [@mjreddy](https://github.com/mjreddy). The project is maintainer-led (roadmap on [Milestones](https://github.com/bakissation/mcp-google-multi/milestones); bug reports welcome, feature PRs by prior agreement — see [CONTRIBUTING.md](./CONTRIBUTING.md)). **v5 is complete and in a feedback period: [open an issue](https://github.com/bakissation/mcp-google-multi/issues/new/choose) with bugs, pain points, or what you wish it did — it directly shapes the v6 roadmap.** Security reports go to [SECURITY.md](./SECURITY.md), never a public issue.
+Thanks to contributors [@obatried](https://github.com/obatried), [@trevor-commits](https://github.com/trevor-commits), and [@mjreddy](https://github.com/mjreddy). The project is maintainer-led (roadmap on [Milestones](https://github.com/bakissation/mcp-google-multi/milestones); bug reports welcome, feature PRs by prior agreement — see [CONTRIBUTING.md](./CONTRIBUTING.md)). **Feedback shapes the roadmap: [open an issue](https://github.com/bakissation/mcp-google-multi/issues/new/choose) with bugs, pain points, or what you wish it did.** Security reports go to [SECURITY.md](./SECURITY.md), never a public issue.
 
 ## License
 

package/dist/accounts.d.ts

@@ -1,11 +1,50 @@
+import { z } from 'zod';
+import type { ScopeProfile } from './scope-catalog.js';
+export declare function getTokenDir(): string;
 export interface AccountConfig {
     email: string;
     tokenPath: string;
     encPath: string;
+    scopeProfile?: string;
+    admin?: boolean;
+    source: 'config' | 'env';
 }
-/** Tuple of account aliases (at least one) — usable with z.enum() */
-export declare const ACCOUNTS: [string, ...string[]];
-/** Map of alias → { email, tokenPath } */
-export declare const ACCOUNT_CONFIG: Record<string, AccountConfig>;
-/** Valid account alias (string union isn't static, so tools use z.enum(ACCOUNTS)) */
+export interface AccountSet {
+    aliases: string[];
+    configs: Record<string, AccountConfig>;
+    scopeProfiles: Record<string, ScopeProfile>;
+    source: 'env' | 'file' | 'merged';
+    stamp: string;
+    defaultAccount?: string;
+    defaultAccountSource?: 'env' | 'config';
+}
+export declare function resolveAccounts(env?: NodeJS.ProcessEnv, filePath?: string, onInvalid?: 'exit' | 'throw'): AccountSet;
+/** Live accessor: dispatch-time readers use this, never a captured snapshot. */
+export declare function getAccountSet(): AccountSet;
+/** Re-resolve after a config.json mutation and swap the live set. */
+export declare function invalidateAccountSet(): AccountSet;
+export declare function refreshAccountSetIfStale(): void;
+/** Cross-process staleness probe (BR-7): one stat, compared against the stamp. */
+export declare function isAccountSetStale(): boolean;
+/** Account aliases (possibly empty on a fresh install).
+ * 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[];
+/**
+ * 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
+ * (module load) and take down every CLI — including `doctor`, which is meant to
+ * REPORT the empty registry (gap #23). Fall back to a plain string when there
+ * 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 declare function accountAliasSchemaFor(aliases: readonly string[]): z.ZodType<string>;
+/** Shared, load-time snapshot used by every tool's `account` field. */
+export declare const accountAliasSchema: z.ZodType<string>;
+/**
+ * BR-4: the stdio/http SERVER never boots with an empty registry — a fresh user
+ * bootstraps via env / `migrate-config` / `account import` / `auth` first. The
+ * bootstrap and diagnostic CLIs return before this guard, so it gates only the
+ * server path (called from index.ts after the CLI branches). */
+export declare function assertServerAccountsConfigured(): void;
+/** Valid account alias (string union isn't static, so tools use accountAliasSchema) */
 export type Account = string;

package/dist/accounts.js

@@ -1,23 +1,28 @@
-import dotenv from 'dotenv';
-import { fileURLToPath } from 'node:url';
 import path from 'node:path';
-import { homedir } from 'node:os';
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// dotenv v17 prints a banner to stdout, corrupting the stdio JSON-RPC channel;
-// DOTENV_CONFIG_QUIET cannot help, it would be read from .env after config() ran.
-dotenv.config({ quiet: true });
-dotenv.config({ path: path.resolve(__dirname, '..', '.env'), quiet: true });
-const defaultTokenDir = path.join(process.env.XDG_CONFIG_HOME || path.join(homedir(), '.config'), 'mcp-google-multi', 'tokens');
+import fs from 'node:fs';
+import { z } from 'zod';
+import { loadEnvFiles } from './env-load.js';
+import { CONFIG_VERSION, configDir, configFilePath, failStartup, loadConfigFile, mutateConfigFile } from './config-file.js';
+import { BUNDLE_CATALOG, closestBundle, resolveBundleAliases } from './scope-catalog.js';
+const envLoad = loadEnvFiles();
+const defaultTokenDir = path.join(configDir(), 'tokens');
 const tokenDir = process.env.TOKEN_STORE_PATH
     ? path.resolve(process.env.TOKEN_STORE_PATH)
     : defaultTokenDir;
-/** Format: GOOGLE_ACCOUNTS="alias1:email1,alias2:email2". */
-function parseAccounts() {
-    const raw = process.env.GOOGLE_ACCOUNTS;
-    if (!raw || raw.trim() === '') {
-        throw new Error('GOOGLE_ACCOUNTS is not set. Define it in .env like:\n' +
-            'GOOGLE_ACCOUNTS=work:user@company.com,personal:user@gmail.com');
-    }
+export function getTokenDir() {
+    return tokenDir;
+}
+function parseCsv(value) {
+    return (value ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+}
+function accountPaths(alias) {
+    return {
+        tokenPath: path.join(tokenDir, alias, 'token.json'),
+        encPath: path.join(tokenDir, `${alias}.enc`),
+    };
+}
+/** v5 env parser, guards verbatim. Format: GOOGLE_ACCOUNTS="alias1:email1,alias2:email2". */
+function parseEnvAccounts(raw, adminAliases) {
     const configs = {};
     const aliases = [];
     for (const entry of raw.split(',')) {
@@ -35,7 +40,7 @@ function parseAccounts() {
         }
         // Restrict alias to a safe charset so it can't escape `tokenDir` via path traversal
         // (e.g. "../../etc/passwd:foo@bar.com" in .env).
-        if (!/^[a-zA-Z0-9_-]+$/.test(alias)) {
+        if (!/^[a-zA-Z0-9_-]+$/.test(alias) || ['__proto__', 'constructor', 'prototype'].includes(alias)) {
             throw new Error(`Invalid alias "${alias}". Allowed characters: letters, digits, underscore, hyphen.`);
         }
         if (aliases.includes(alias)) {
@@ -44,17 +49,254 @@ function parseAccounts() {
         aliases.push(alias);
         configs[alias] = {
             email,
-            tokenPath: path.join(tokenDir, alias, 'token.json'),
-            encPath: path.join(tokenDir, `${alias}.enc`),
+            ...accountPaths(alias),
+            admin: adminAliases.includes(alias) || undefined,
+            source: 'env',
         };
     }
     if (aliases.length === 0) {
         throw new Error('GOOGLE_ACCOUNTS must define at least one account.');
     }
-    return { aliases: aliases, configs };
+    return { aliases, configs };
+}
+function noAccountsMessage() {
+    const envHint = envLoad.loaded.length === 0
+        ? ` No readable .env file was found (searched: ${envLoad.searched.join(', ')}).`
+        : '';
+    return (`no accounts configured. Add them to ${configFilePath()} (run: mcp-google-multi migrate-config), ` +
+        `or set GOOGLE_ACCOUNTS=work:user@company.com,personal:user@gmail.com in the environment.${envHint}`);
+}
+/**
+ * Registry resolution (BR-2): a non-empty GOOGLE_ACCOUNTS env takes the WHOLE
+ * registry from env (12-factor override, never merged key-by-key); otherwise
+ * the registry comes from config.json. GOOGLE_ADMIN_ACCOUNTS, when NON-EMPTY,
+ * overrides per-account admin flags from the file (env var > config field);
+ * empty behaves as unset, mirroring GOOGLE_ACCOUNTS semantics.
+ */
+let warnedLegacy = false;
+export function resolveAccounts(env = process.env, filePath = configFilePath(), onInvalid = 'exit') {
+    const adminEnv = parseCsv(env.GOOGLE_ADMIN_ACCOUNTS);
+    const rawEnv = env.GOOGLE_ACCOUNTS;
+    const fail = (slug, message) => {
+        if (onInvalid === 'throw')
+            throw new Error(`${slug}: ${message}`);
+        failStartup(slug, message);
+    };
+    // Validate the legacy global override AT BOOT, whatever GOOGLE_TOOLSETS
+    // selects — otherwise a typo only surfaces at dispatch time inside
+    // account_list instead of the promised startup error (BR3).
+    const legacyNames = parseCsv(env.GOOGLE_OPTIONAL_SCOPES);
+    if (legacyNames.length > 0) {
+        for (const bundle of resolveBundleAliases(legacyNames)) {
+            if (bundle === 'admin') {
+                fail('E_UNKNOWN_BUNDLE', '"admin" is not a global bundle: grant it per account via GOOGLE_ADMIN_ACCOUNTS or an "admin: true" scope profile.');
+            }
+            if (!(bundle in BUNDLE_CATALOG)) {
+                const hint = closestBundle(bundle);
+                fail('E_UNKNOWN_BUNDLE', `unknown bundle "${bundle}" in GOOGLE_OPTIONAL_SCOPES${hint ? ` — did you mean "${hint}"?` : ''}`);
+            }
+        }
+        if (!warnedLegacy) {
+            warnedLegacy = true;
+            process.stderr.write('E_LEGACY_GLOBAL_SCOPES: GOOGLE_OPTIONAL_SCOPES applies one global scope set to every account; migrate to per-account scopeProfiles (mcp-google-multi migrate-config).\n');
+        }
+    }
+    if (rawEnv && rawEnv.trim() !== '') {
+        const { aliases, configs } = parseEnvAccounts(rawEnv, adminEnv);
+        materializeFirstRun(aliases, configs, filePath);
+        const def = resolveDefaultAccount(env, null, aliases, fail);
+        return {
+            aliases,
+            configs,
+            // Env-sourced accounts cannot reference file profiles; the legacy
+            // GOOGLE_OPTIONAL_SCOPES override is applied live in auth.ts.
+            scopeProfiles: { base: { bundles: [] } },
+            source: 'env',
+            stamp: 'env:0',
+            ...def,
+        };
+    }
+    // Stat BEFORE read: a cross-process write landing between the two makes the
+    // stamp conservative (flags stale again next dispatch) instead of pinning
+    // stale content behind a fresh stamp.
+    const preStamp = fileStamp(filePath, CONFIG_VERSION);
+    const config = loadConfigFile(filePath, onInvalid);
+    const entries = Object.entries(config?.accounts ?? {});
+    if (entries.length === 0) {
+        // Gap #23: an empty registry is NOT fatal at resolve time — the bootstrap and
+        // diagnostic CLIs (doctor/reset/account import/migrate-config/config check)
+        // must run on a fresh install. Only the stdio/http SERVER refuses to boot
+        // empty (BR-4), enforced by assertServerAccountsConfigured() in index.ts.
+        // The dispatch-path reload ('throw') still throws so a mid-session emptied
+        // config.json keeps the last-good registry (BR-7) instead of dropping tools.
+        if (onInvalid === 'throw') {
+            throw new Error(`E_NO_ACCOUNTS_CONFIGURED: ${noAccountsMessage()}`);
+        }
+        return {
+            aliases: [],
+            configs: {},
+            scopeProfiles: { base: { bundles: [] } },
+            source: 'file',
+            stamp: `${config?.version ?? CONFIG_VERSION}:${preStamp.split(':')[1]}`,
+        };
+    }
+    // BR3: unknown bundle names fail loudly (a mis-scoped token is worse than a
+    // clear error); v5 silently filtered them. Null prototype: profile names are
+    // user input and must never collide with Object.prototype members.
+    const scopeProfiles = Object.create(null);
+    scopeProfiles.base = { bundles: [] };
+    for (const [name, profile] of Object.entries(config?.scopeProfiles ?? {})) {
+        const bundles = resolveBundleAliases(profile.bundles);
+        for (const bundle of bundles) {
+            if (!(bundle in BUNDLE_CATALOG)) {
+                const hint = closestBundle(bundle);
+                fail('E_UNKNOWN_BUNDLE', `unknown bundle "${bundle}" in scope profile "${name}"${hint ? ` — did you mean "${hint}"?` : ''}`);
+            }
+        }
+        if (profile.includesBase === false && bundles.length === 0 && profile.admin !== true) {
+            fail('E_CONFIG_INVALID', `scope profile "${name}" resolves to zero scopes (includesBase: false with no bundles); Google rejects an empty consent request.`);
+        }
+        scopeProfiles[name] = { ...profile, bundles };
+    }
+    const configs = {};
+    const aliases = [];
+    for (const [alias, entry] of entries) {
+        if (entry.scopeProfile && !Object.hasOwn(scopeProfiles, entry.scopeProfile)) {
+            fail('E_CONFIG_INVALID', `account "${alias}" references scope profile "${entry.scopeProfile}", which is not defined in scopeProfiles.`);
+        }
+        aliases.push(alias);
+        configs[alias] = {
+            email: entry.email,
+            ...accountPaths(alias),
+            scopeProfile: entry.scopeProfile,
+            admin: adminEnv.length > 0 ? adminEnv.includes(alias) : entry.admin,
+            source: 'config',
+        };
+    }
+    const def = resolveDefaultAccount(env, config?.defaultAccount ?? null, aliases, fail);
+    return {
+        aliases,
+        configs,
+        scopeProfiles,
+        source: 'file',
+        stamp: `${config?.version ?? CONFIG_VERSION}:${preStamp.split(':')[1]}`,
+        ...def,
+    };
+}
+/** A2: env GOOGLE_DEFAULT_ACCOUNT > config.defaultAccount > unset. A configured
+ * default naming an unknown alias refuses to start (E_DEFAULT_ACCOUNT_UNKNOWN —
+ * deliberately NOT E_CONFIG_INVALID: the config is schema-valid). */
+function resolveDefaultAccount(env, fromConfig, aliases, fail) {
+    const fromEnv = env.GOOGLE_DEFAULT_ACCOUNT?.trim();
+    const value = fromEnv || fromConfig || undefined;
+    if (!value)
+        return {};
+    if (!aliases.includes(value)) {
+        fail('E_DEFAULT_ACCOUNT_UNKNOWN', `default account "${value}" (from ${fromEnv ? 'GOOGLE_DEFAULT_ACCOUNT' : 'config.json defaultAccount'}) is not a configured alias. Valid: ${aliases.join(', ')}.`);
+    }
+    return { defaultAccount: value, defaultAccountSource: fromEnv ? 'env' : 'config' };
+}
+function fileStamp(filePath, version) {
+    try {
+        return `${version}:${fs.statSync(filePath).mtimeMs}`;
+    }
+    catch {
+        return `${version}:0`;
+    }
+}
+// First-run shim (BC6): env is set and no config.json exists yet — materialize
+// the file so the wizard has something to edit. Env still wins this session;
+// a write failure must never block boot (warn on stderr and continue).
+function materializeFirstRun(aliases, configs, filePath) {
+    if (fs.existsSync(filePath))
+        return;
+    try {
+        let wrote = false;
+        // mutateConfigFile = lock + re-check + atomic write, so a concurrent
+        // wizard/migrate writer is never clobbered (the loaded `current` is
+        // re-read under the lock; only a still-absent file gets the env content).
+        mutateConfigFile((current) => {
+            if (Object.keys(current.accounts ?? {}).length > 0)
+                return current;
+            const accounts = {};
+            for (const alias of aliases) {
+                accounts[alias] = {
+                    email: configs[alias].email,
+                    ...(configs[alias].admin ? { admin: true } : {}),
+                };
+            }
+            wrote = true;
+            return { ...current, version: current.version || CONFIG_VERSION, accounts };
+        }, filePath);
+        if (wrote) {
+            process.stderr.write(`Materialized ${filePath} from GOOGLE_ACCOUNTS (env still overrides while set).\n`);
+        }
+    }
+    catch (e) {
+        process.stderr.write(`Could not materialize ${filePath}: ${e.message}\n`);
+    }
+}
+let current = resolveAccounts();
+/** Live accessor: dispatch-time readers use this, never a captured snapshot. */
+export function getAccountSet() {
+    return current;
+}
+/** Re-resolve after a config.json mutation and swap the live set. */
+export function invalidateAccountSet() {
+    current = resolveAccounts();
+    return current;
+}
+/**
+ * Dispatch-path reload (BR-7): NEVER exits and never throws — a mid-edit,
+ * corrupt, or deleted config.json keeps the last-good set and warns once per
+ * distinct failure on stderr. failStartup semantics are boot/CLI-only.
+ */
+let lastReloadWarning = '';
+export function refreshAccountSetIfStale() {
+    if (!isAccountSetStale())
+        return;
+    try {
+        current = resolveAccounts(process.env, configFilePath(), 'throw');
+        lastReloadWarning = '';
+    }
+    catch (e) {
+        const msg = e.message;
+        if (msg !== lastReloadWarning) {
+            process.stderr.write(`config.json reload skipped (keeping last-good registry): ${msg}\n`);
+            lastReloadWarning = msg;
+        }
+    }
+}
+/** Cross-process staleness probe (BR-7): one stat, compared against the stamp. */
+export function isAccountSetStale() {
+    if (current.source !== 'file')
+        return false;
+    const [version] = current.stamp.split(':');
+    return current.stamp !== fileStamp(configFilePath(), Number(version));
+}
+/** Account aliases (possibly empty on a fresh install).
+ * 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;
+/**
+ * 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
+ * (module load) and take down every CLI — including `doctor`, which is meant to
+ * REPORT the empty registry (gap #23). Fall back to a plain string when there
+ * 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();
+}
+/** Shared, load-time snapshot used by every tool's `account` field. */
+export const accountAliasSchema = accountAliasSchemaFor(ACCOUNTS);
+/**
+ * BR-4: the stdio/http SERVER never boots with an empty registry — a fresh user
+ * bootstraps via env / `migrate-config` / `account import` / `auth` first. The
+ * bootstrap and diagnostic CLIs return before this guard, so it gates only the
+ * server path (called from index.ts after the CLI branches). */
+export function assertServerAccountsConfigured() {
+    if (current.aliases.length === 0) {
+        failStartup('E_NO_ACCOUNTS_CONFIGURED', noAccountsMessage());
+    }
 }
-const parsed = parseAccounts();
-/** Tuple of account aliases (at least one) — usable with z.enum() */
-export const ACCOUNTS = parsed.aliases;
-/** Map of alias → { email, tokenPath } */
-export const ACCOUNT_CONFIG = parsed.configs;

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,13 @@
+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;
+export declare function normalizeCallArguments(shapeKeys: ReadonlySet<string>, args: Record<string, unknown>): {
+    args: Record<string, unknown>;
+    renamed: [string, string][];
+};
+export declare function normalizeMessage(msg: JSONRPCMessage, shapeFor: (tool: string) => ReadonlySet<string> | 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) => ReadonlySet<string> | undefined, log?: (line: string) => void): Transport;

package/dist/arg-normalize.js

@@ -0,0 +1,80 @@
+// 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());
+export function normalizeCallArguments(shapeKeys, args) {
+    const renamed = [];
+    let out;
+    for (const key of Object.keys(args)) {
+        if (shapeKeys.has(key) || !key.includes('_'))
+            continue;
+        const camel = snakeToCamel(key);
+        if (camel !== key && shapeKeys.has(camel) && !(camel in args)) {
+            out ??= { ...args };
+            out[camel] = out[key];
+            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;
+}