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

package/dist/open-url.js

@@ -0,0 +1,30 @@
+import { spawn } from 'node:child_process';
+import { release } from 'node:os';
+const isWsl = () => process.platform === 'linux' && release().toLowerCase().includes('microsoft');
+// Best-effort browser launch. Never throws, never blocks, writes nothing to
+// the parent's stdio — the caller has already printed the URL as the fallback.
+export function openUrl(url) {
+    try {
+        let cmd;
+        let args;
+        if (process.platform === 'darwin') {
+            cmd = 'open';
+            args = [url];
+        }
+        else if (process.platform === 'win32' || isWsl()) {
+            const encoded = Buffer.from(`Start-Process "${url}"`, 'utf16le').toString('base64');
+            cmd = 'powershell.exe';
+            args = ['-NoProfile', '-NonInteractive', '-EncodedCommand', encoded];
+        }
+        else {
+            cmd = 'xdg-open';
+            args = [url];
+        }
+        const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // Headless/odd platforms: the printed URL is the supported path.
+    }
+}

package/dist/reauth-hint.d.ts

@@ -0,0 +1,2 @@
+export declare function setHttpReauthBase(base: string | null): void;
+export declare function reauthHint(account: string): string;

package/dist/reauth-hint.js

@@ -0,0 +1,15 @@
+// B13 in-call re-auth (BV-1): a dead/missing per-account Google token is a
+// leg-C failure. Over stdio the fix is the `auth --account` CLI; over HTTP the
+// user cannot run a CLI, so the hint becomes a clickable link into the AS's
+// clientless alias_reauth flow (${BASE}/authorize?flow=alias_reauth&alias=…).
+// The HTTP bootstrap sets the base when the AS starts; stdio never does.
+let httpReauthBase = null;
+export function setHttpReauthBase(base) {
+    httpReauthBase = base;
+}
+export function reauthHint(account) {
+    if (httpReauthBase) {
+        return `Re-authenticate "${account}" in your browser, then retry: ${httpReauthBase}/authorize?flow=alias_reauth&alias=${encodeURIComponent(account)}`;
+    }
+    return `Run: npx mcp-google-multi auth --account ${account}`;
+}

package/dist/registry-transfer.d.ts

@@ -0,0 +1,41 @@
+export interface TransferBundle {
+    manifest: {
+        v: 1;
+        exportedAt: string;
+        aliases: string[];
+    };
+    /** Raw config.json contents (plaintext registry; no secrets). */
+    config: string | null;
+    /** alias -> raw <alias>.enc contents (still under the SOURCE MASTER_KEY). */
+    tokens: Record<string, string>;
+}
+export interface TransferDeps {
+    configPath?: string;
+    tokenDir?: string;
+    fileExists?: (p: string) => boolean;
+    readFile?: (p: string) => string;
+    listDir?: (p: string) => string[];
+}
+/** Collect the config + every `<alias>.enc` token file present in the token dir. */
+export declare function buildTransferBundle(exportedAt: string, deps?: TransferDeps): TransferBundle;
+export declare function encryptBundle(bundle: TransferBundle, passphrase: string): string;
+export declare class BundleDecryptError extends Error {
+}
+export declare function decryptBundle(contents: string, passphrase: string): TransferBundle;
+export interface ImportPlan {
+    mergedConfig: string;
+    tokenWrites: Record<string, string>;
+    added: string[];
+    replaced: string[];
+    skipped: string[];
+}
+/**
+ * Merge the bundle into the local registry. Default MERGE = add non-colliding
+ * aliases; a collision is skipped (never clobbers a local account's tokens)
+ * unless `replace` is set. Pure for unit testing.
+ */
+export declare function planImport(bundle: TransferBundle, localConfigRaw: string | null, opts?: {
+    replace?: boolean;
+}): ImportPlan;
+export declare function runExportCli(argv: string[]): Promise<number>;
+export declare function runImportCli(argv: string[]): Promise<number>;

package/dist/registry-transfer.js

@@ -0,0 +1,219 @@
+// B19: encrypted registry export / import (account-registry.md). Moves a whole
+// setup to another machine. The bundle is encrypted under a user PASSPHRASE
+// (portable across machines with different MASTER_KEYs) via the token-store AES
+// primitives; the bundled <alias>.enc token files stay encrypted under the
+// SOURCE MASTER_KEY (double-locked), so the target needs the same MASTER_KEY to
+// use them. Secrets (MASTER_KEY / client secret) are never in the bundle.
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import * as readline from 'node:readline';
+import path from 'node:path';
+import { encryptToken, decryptToken } from './token-store.js';
+import { atomicWriteFileSync, atomicWriteWithLock } from './fs-atomic.js';
+import { configFilePath, CONFIG_VERSION } from './config-file.js';
+import { getTokenDir } from './accounts.js';
+const ALIAS_RE = /^[a-zA-Z0-9_-]+$/;
+function resolveDeps(deps) {
+    return {
+        configPath: deps.configPath ?? configFilePath(),
+        tokenDir: deps.tokenDir ?? getTokenDir(),
+        fileExists: deps.fileExists ?? existsSync,
+        readFile: deps.readFile ?? ((p) => readFileSync(p, 'utf-8')),
+        listDir: deps.listDir ?? ((p) => (existsSync(p) ? readdirSync(p) : [])),
+    };
+}
+/** Collect the config + every `<alias>.enc` token file present in the token dir. */
+export function buildTransferBundle(exportedAt, deps = {}) {
+    const r = resolveDeps(deps);
+    const config = r.fileExists(r.configPath) ? r.readFile(r.configPath) : null;
+    const tokens = {};
+    for (const name of r.listDir(r.tokenDir)) {
+        if (!name.endsWith('.enc'))
+            continue;
+        const alias = name.slice(0, -'.enc'.length);
+        if (!ALIAS_RE.test(alias))
+            continue; // never trust a stray filename as an alias
+        tokens[alias] = r.readFile(path.join(r.tokenDir, name));
+    }
+    // Alias list = token-authed aliases plus any account defined only in config.
+    const aliasSet = new Set(Object.keys(tokens));
+    if (config) {
+        try {
+            const accounts = JSON.parse(config).accounts ?? {};
+            for (const a of Object.keys(accounts))
+                aliasSet.add(a);
+        }
+        catch {
+            // malformed config is passed through as-is; import will re-validate it.
+        }
+    }
+    return { manifest: { v: 1, exportedAt, aliases: [...aliasSet].sort() }, config, tokens };
+}
+export function encryptBundle(bundle, passphrase) {
+    return encryptToken(bundle, passphrase);
+}
+export class BundleDecryptError extends Error {
+}
+export function decryptBundle(contents, passphrase) {
+    let obj;
+    try {
+        obj = decryptToken(contents, passphrase);
+    }
+    catch {
+        throw new BundleDecryptError('Could not decrypt the bundle — wrong passphrase or the file is corrupt.');
+    }
+    const b = obj;
+    if (!b || typeof b !== 'object' || !b.manifest || b.manifest.v !== 1 || typeof b.tokens !== 'object') {
+        throw new BundleDecryptError('Bundle decrypted but is not a valid registry export (bad manifest).');
+    }
+    return b;
+}
+function parseConfig(raw) {
+    if (!raw || raw.trim() === '')
+        return { version: CONFIG_VERSION, accounts: {} };
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null)
+        throw new Error('config is not an object');
+    parsed.accounts ??= {};
+    parsed.version ??= CONFIG_VERSION;
+    return parsed;
+}
+/**
+ * Merge the bundle into the local registry. Default MERGE = add non-colliding
+ * aliases; a collision is skipped (never clobbers a local account's tokens)
+ * unless `replace` is set. Pure for unit testing.
+ */
+export function planImport(bundle, localConfigRaw, opts = {}) {
+    const local = parseConfig(localConfigRaw);
+    const incoming = parseConfig(bundle.config);
+    const replace = opts.replace === true;
+    const added = [];
+    const replaced = [];
+    const skipped = [];
+    const nextAccounts = { ...local.accounts };
+    const nextProfiles = { ...(local.scopeProfiles ?? {}) };
+    const tokenWrites = {};
+    const incomingAccounts = incoming.accounts ?? {};
+    const incomingProfiles = incoming.scopeProfiles ?? {};
+    for (const alias of Object.keys(incomingAccounts)) {
+        const collides = Object.prototype.hasOwnProperty.call(local.accounts, alias);
+        if (collides && !replace) {
+            skipped.push(alias);
+            continue;
+        }
+        nextAccounts[alias] = incomingAccounts[alias];
+        // carry the account's scope profile if it points at one
+        const row = incomingAccounts[alias];
+        if (row?.scopeProfile && Object.prototype.hasOwnProperty.call(incomingProfiles, row.scopeProfile)) {
+            nextProfiles[row.scopeProfile] = incomingProfiles[row.scopeProfile];
+        }
+        if (bundle.tokens[alias])
+            tokenWrites[alias] = bundle.tokens[alias];
+        (collides ? replaced : added).push(alias);
+    }
+    // Token files with no config account (authed but registry-less) follow the
+    // same collision rule keyed on whether we already wrote/kept that alias.
+    for (const alias of Object.keys(bundle.tokens)) {
+        if (alias in tokenWrites || added.includes(alias) || replaced.includes(alias))
+            continue;
+        if (Object.prototype.hasOwnProperty.call(local.accounts, alias) && !replace)
+            continue;
+        tokenWrites[alias] = bundle.tokens[alias];
+    }
+    const merged = { ...local, version: local.version ?? CONFIG_VERSION, accounts: nextAccounts };
+    if (Object.keys(nextProfiles).length > 0)
+        merged.scopeProfiles = nextProfiles;
+    return {
+        mergedConfig: `${JSON.stringify(merged, null, 2)}\n`,
+        tokenWrites,
+        added: added.sort(),
+        replaced: replaced.sort(),
+        skipped: skipped.sort(),
+    };
+}
+// ---- CLI -------------------------------------------------------------------
+function argFlag(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+/** Passphrase from MCP_TRANSFER_PASSPHRASE (automation) or a TTY prompt; never
+ * a CLI flag (would leak in the process list). */
+async function resolvePassphrase(prompt) {
+    const fromEnv = process.env.MCP_TRANSFER_PASSPHRASE;
+    if (fromEnv && fromEnv.length > 0)
+        return fromEnv;
+    if (!process.stdin.isTTY)
+        return null;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolve) => rl.question(prompt, resolve));
+        return answer.trim() || null;
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function runExportCli(argv) {
+    const out = argFlag(argv, '--out');
+    if (!out) {
+        console.error('Usage: mcp-google-multi account export --out <bundle.enc>');
+        return 2;
+    }
+    const passphrase = await resolvePassphrase('Choose a passphrase to encrypt the export: ');
+    if (!passphrase) {
+        console.error('E_INPUT_REQUIRED: a passphrase is required. Set MCP_TRANSFER_PASSPHRASE or run in a terminal.');
+        return 2;
+    }
+    const bundle = buildTransferBundle(new Date().toISOString());
+    atomicWriteFileSync(path.resolve(out), encryptBundle(bundle, passphrase), 0o600);
+    console.error(`Exported ${bundle.manifest.aliases.length} account(s) to ${out} (0600).`);
+    console.error('Note: the bundled token files stay encrypted under this machine\'s MASTER_KEY. To use the tokens on the target, set the same MASTER_KEY there; otherwise re-authenticate with account_reauth.');
+    return 0;
+}
+export async function runImportCli(argv) {
+    const file = argv[argv.indexOf('import') + 1];
+    if (!file || file.startsWith('--')) {
+        console.error('Usage: mcp-google-multi account import <bundle.enc> [--replace]');
+        return 2;
+    }
+    const replace = argv.includes('--replace');
+    if (!existsSync(path.resolve(file))) {
+        console.error(`E_NOT_FOUND: ${file}`);
+        return 2;
+    }
+    const passphrase = await resolvePassphrase('Passphrase to decrypt the bundle: ');
+    if (!passphrase) {
+        console.error('E_INPUT_REQUIRED: a passphrase is required. Set MCP_TRANSFER_PASSPHRASE or run in a terminal.');
+        return 2;
+    }
+    let bundle;
+    try {
+        bundle = decryptBundle(readFileSync(path.resolve(file), 'utf-8'), passphrase);
+    }
+    catch (e) {
+        console.error(e.message);
+        return 1;
+    }
+    const cfgPath = configFilePath();
+    const localRaw = existsSync(cfgPath) ? readFileSync(cfgPath, 'utf-8') : null;
+    let plan;
+    try {
+        plan = planImport(bundle, localRaw, { replace });
+    }
+    catch (e) {
+        console.error(`E_CONFIG_INVALID: the bundle's config could not be merged: ${e.message}`);
+        return 1;
+    }
+    atomicWriteWithLock(cfgPath, plan.mergedConfig, 0o600);
+    const tokenDir = getTokenDir();
+    for (const [alias, contents] of Object.entries(plan.tokenWrites)) {
+        atomicWriteFileSync(path.join(tokenDir, `${alias}.enc`), contents, 0o600);
+    }
+    if (process.env.GOOGLE_ACCOUNTS?.trim()) {
+        console.error('Note: GOOGLE_ACCOUNTS is set, so config.json is ignored (env-sourced mode). The imported registry takes effect once you unset GOOGLE_ACCOUNTS. Token files were still placed.');
+    }
+    console.error(`Imported: ${plan.added.length} added${plan.added.length ? ` (${plan.added.join(', ')})` : ''}, ` +
+        `${plan.replaced.length} replaced${plan.replaced.length ? ` (${plan.replaced.join(', ')})` : ''}, ` +
+        `${plan.skipped.length} skipped${plan.skipped.length ? ` (${plan.skipped.join(', ')}; re-run with --replace to overwrite)` : ''}.`);
+    console.error('Run `mcp-google-multi doctor` to verify token health (tokens need the source MASTER_KEY; otherwise account_reauth).');
+    return 0;
+}

package/dist/registry.d.ts

@@ -2,6 +2,8 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { type Policy } from './write-control.js';
 export type Cud = 'read' | 'create' | 'update' | 'delete';
+export type DiscoveryMode = 'lazy' | 'curated' | 'eager';
+export declare function resolveDiscoveryMode(env?: NodeJS.ProcessEnv): DiscoveryMode;
 export interface ToolEntry {
     name: string;
     service: string;
@@ -9,7 +11,18 @@ export interface ToolEntry {
     description: string;
     inputShape: z.ZodRawShape;
     annotations: Record<string, unknown>;
+    /** anthropic/* client extension keys: honoring clients (Claude Code) read
+     * these from the wire Tool's _meta — SDK clients STRIP unknown keys from
+     * annotations (closed ToolAnnotationsSchema), so they must never live there. */
+    clientMeta?: Record<string, unknown>;
     meta: boolean;
+    /** Discovery-codegen provenance (the only tools passing an explicit cud). */
+    generated: boolean;
+    /** Member of the frozen irreversible set (real send / permanent delete). */
+    irreversible: boolean;
+    /** Baked per-method scopes (generated tools); curated tools authorize at
+     * service/bundle grain and leave this undefined. */
+    requiredScopes?: readonly string[];
 }
 export interface CatalogOperation {
     tool: string;
@@ -27,11 +40,24 @@ export declare class ToolRegistry {
     private readonly jsonSchemaCache;
     private readonly compactOutput;
     private registeringMeta;
-    constructor(server: McpServer, policy: Policy);
+    /** Configured visibility mode (GOOGLE_DISCOVERY); default lazy = v5 exact. */
+    readonly mode: DiscoveryMode;
+    /** Agent-toggled runtime overlay (discover_all / discover_reset): lifts a
+     * lazy surface to curated without touching the configured mode. */
+    private expanded;
+    constructor(server: McpServer, policy: Policy, mode?: DiscoveryMode);
     registerMeta: McpServer['registerTool'];
     services(): string[];
     catalog(service: string, query?: string): CatalogOperation[];
     reveal(service: string): boolean;
+    /** discover_all: advertise the full curated set at once. Idempotent. */
+    expand(): boolean;
+    /** discover_reset: back to the lean meta-only surface. Clears reveals too.
+     * BV-8: if a client mishandles a SHRINKING tools/list, this degrades to a
+     * no-op for that session — tools stay callable regardless (graceful
+     * dispatch), zero correctness impact. */
+    collapse(): boolean;
+    private effectiveMode;
     isVisible(tool: ToolEntry): boolean;
     visibleCount(): {
         eager: number;

package/dist/registry.js

@@ -1,11 +1,32 @@
 import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { isAllowed, writeDisabledResult } from './write-control.js';
+import { isAllowed, writeDisabledResult, IRREVERSIBLE_TOOLS } from './write-control.js';
+import { getAccountSet, refreshAccountSetIfStale } from './accounts.js';
 import { compactResult, trimEnabled } from './trim.js';
 import { fanoutAccountField, invalidAccountsResult, parseAccountSelector, runFanout } from './fanout.js';
+const DISCOVERY_MODES = ['lazy', 'curated', 'eager'];
+export function resolveDiscoveryMode(env = process.env) {
+    const raw = (env.GOOGLE_DISCOVERY ?? 'lazy').trim();
+    if (raw && !DISCOVERY_MODES.includes(raw)) {
+        // Fail-open to the lean default, but say so — a typo'd mode otherwise
+        // looks like tools silently missing (or silently flooding the context).
+        process.stderr.write(`GOOGLE_DISCOVERY="${raw}" is not valid (${DISCOVERY_MODES.join(' | ')}); using lazy\n`);
+    }
+    return DISCOVERY_MODES.includes(raw) ? raw : 'lazy';
+}
 const CUD_OVERRIDES = {
     drive_untrash: 'update',
     drive_transfer: 'create',
+    // read-only resolver; the name's "resolve" verb would otherwise infer update.
+    contacts_resolve: 'read',
+    // Account management is gated by anthropic/requiresUserInteraction (forced
+    // human approval), NOT the Google-data write-control profile — so onboarding
+    // works under any profile. cud=read also keeps them off the fan-out path.
+    account_add: 'read',
+    account_reauth: 'read',
+    // Writes a LOCAL MCP-client config, not Google data; gated by
+    // requiresUserInteraction. "write" verb would otherwise infer update.
+    account_write_config: 'read',
 };
 const SERVICE_OVERRIDES = {
     reports_activities_list: 'admin',
@@ -13,7 +34,13 @@ 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']);
 function isAccountEnum(field) {
-    return field?._zod?.def?.type === 'enum';
+    const def = field?._zod?.def;
+    if (!def)
+        return false;
+    // A2 made account enums .optional(); unwrap it or fan-out silently dies.
+    if (def.type === 'optional')
+        return def.innerType?._zod?.def?.type === 'enum';
+    return def.type === 'enum';
 }
 const DELETE_VERB = /(^|_)(delete|remove|trash|clear|empty)(_|$)/;
 const CREATE_VERB = /(^|_)(create|add|insert|send|upload|copy|import|append|submit|duplicate|share|quick)(_|$)/;
@@ -39,21 +66,37 @@ export class ToolRegistry {
     jsonSchemaCache = new Map();
     compactOutput = trimEnabled();
     registeringMeta = false;
-    constructor(server, policy) {
+    /** Configured visibility mode (GOOGLE_DISCOVERY); default lazy = v5 exact. */
+    mode;
+    /** Agent-toggled runtime overlay (discover_all / discover_reset): lifts a
+     * lazy surface to curated without touching the configured mode. */
+    expanded = false;
+    constructor(server, policy, mode = resolveDiscoveryMode()) {
         this.server = server;
         this.policy = policy;
+        this.mode = mode;
         this.registerTool = ((name, config, handler) => {
             const service = SERVICE_OVERRIDES[name] ?? (name.includes('_') ? name.slice(0, name.indexOf('_')) : name);
             const cud = config.cud ?? inferCud(name);
             // destructiveHint=false claims "additive only" (MCP spec) — updates overwrite, so they stay true.
+            // idempotent: reads trivially, deletes (already-gone = same), updates
+            // (overwrite converges); creates are not (send twice = two emails).
             const annotations = {
                 readOnlyHint: cud === 'read',
                 destructiveHint: cud === 'delete' || cud === 'update',
+                idempotentHint: cud !== 'create',
                 ...config.annotations,
             };
+            // 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;
             // never fan out meta tools: google_api_call infers cud=read but executes writes
             let inputShape = config.inputSchema ?? {};
             let baseHandler = handler;
+            const hasAccountField = 'account' in inputShape;
             if (cud === 'read' && !this.registeringMeta && !FANOUT_EXCLUDE.has(name) && isAccountEnum(inputShape.account)) {
                 const description = inputShape.account.description ?? 'Google account alias';
                 inputShape = { ...inputShape, account: fanoutAccountField(description) };
@@ -74,16 +117,54 @@ export class ToolRegistry {
                 description: config.description ?? '',
                 inputShape,
                 annotations,
+                clientMeta,
                 meta: this.registeringMeta,
+                generated: config.cud !== undefined,
+                irreversible: IRREVERSIBLE_TOOLS.has(name),
+                requiredScopes: config.requiredScopes,
             });
             const guarded = cud === 'read'
                 ? baseHandler
                 : (...args) => isAllowed({ name, service, cud }, policy)
                     ? baseHandler(...args)
                     : writeDisabledResult({ name, service, cud }, policy);
+            // A2: the ONE default-account injection site — outside the CUD gate and
+            // the fan-out parse so both observe a concrete alias; NOT meta-skipped
+            // (that is what covers google_api_call with zero bespoke code). Explicit
+            // aliases, "*" and CSV pass through untouched.
+            const withDefault = !hasAccountField
+                ? guarded
+                : (...args) => {
+                    const first = args[0];
+                    const value = first?.account;
+                    if (value != null && value !== '')
+                        return guarded(...args);
+                    // Refresh here or the unset->configured default transition never
+                    // heals for a client that always omits account (this branch never
+                    // reaches getClient's probe). One stat, only on omission.
+                    refreshAccountSetIfStale();
+                    const def = getAccountSet().defaultAccount;
+                    if (!def) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: JSON.stringify({
+                                        error: 'E_NO_DEFAULT_ACCOUNT',
+                                        message: 'No "account" given and no default account is configured.',
+                                        hint: `Pass account explicitly (valid: ${getAccountSet().aliases.join(', ')}), or set GOOGLE_DEFAULT_ACCOUNT / "defaultAccount" in config.json.`,
+                                        retriable: false,
+                                    }),
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    return guarded({ ...(first ?? {}), account: def }, ...args.slice(1));
+                };
             const finalHandler = this.compactOutput
-                ? async (...args) => compactResult(await guarded(...args))
-                : guarded;
+                ? async (...args) => compactResult(await withDefault(...args))
+                : withDefault;
             const { cud: _cud, ...sdkConfig } = config;
             return server.registerTool(name, { ...sdkConfig, inputSchema: inputShape, annotations }, finalHandler);
         });
@@ -119,8 +200,37 @@ export class ToolRegistry {
         this.server.sendToolListChanged();
         return true;
     }
+    /** discover_all: advertise the full curated set at once. Idempotent. */
+    expand() {
+        if (this.expanded || this.effectiveMode() !== 'lazy')
+            return false;
+        this.expanded = true;
+        this.server.sendToolListChanged();
+        return true;
+    }
+    /** discover_reset: back to the lean meta-only surface. Clears reveals too.
+     * BV-8: if a client mishandles a SHRINKING tools/list, this degrades to a
+     * no-op for that session — tools stay callable regardless (graceful
+     * dispatch), zero correctness impact. */
+    collapse() {
+        if (!this.expanded && this.revealed.size === 0)
+            return false;
+        this.expanded = false;
+        this.revealed.clear();
+        this.server.sendToolListChanged();
+        return true;
+    }
+    effectiveMode() {
+        if (this.mode !== 'lazy')
+            return this.mode;
+        return this.expanded ? 'curated' : 'lazy';
+    }
     isVisible(tool) {
-        return tool.meta || this.revealed.has(tool.service);
+        const mode = this.effectiveMode();
+        return (tool.meta ||
+            mode === 'eager' ||
+            this.revealed.has(tool.service) ||
+            (mode === 'curated' && !tool.generated));
     }
     visibleCount() {
         const meta = this.tools.filter((t) => t.meta).length;
@@ -148,6 +258,7 @@ export class ToolRegistry {
             description: tool.description,
             inputSchema,
             annotations: tool.annotations,
+            ...(tool.clientMeta ? { _meta: tool.clientMeta } : {}),
         };
     }
 }

package/dist/scope-catalog.d.ts

@@ -0,0 +1,19 @@
+export interface ScopeProfile {
+    includesBase?: boolean;
+    bundles: string[];
+    admin?: boolean;
+}
+export interface BundleCatalogEntry {
+    scopes: string[];
+    description: string;
+    risk: 'low' | 'medium' | 'high';
+    workspaceOnly?: boolean;
+}
+export declare const ADMIN_SCOPES: string[];
+export declare const BUNDLE_CATALOG: Record<string, BundleCatalogEntry>;
+/** One-way soft-rename map (UD5): empty at 6.0.0; the mechanism ships now so a
+ * future rename is a deprecation warning, never a breaking config change. */
+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;