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

package/dist/auth.js

@@ -2,8 +2,10 @@ import { OAuth2Client } from 'googleapis-common';
 import http from 'node:http';
 import { URL } from 'node:url';
 import { randomBytes } from 'node:crypto';
-import open from 'open';
-import { ACCOUNTS, ACCOUNT_CONFIG } from './accounts.js';
+import { openUrl } from './open-url.js';
+import { ACCOUNTS, getAccountSet } from './accounts.js';
+import { ADMIN_SCOPES, BUNDLE_CATALOG, closestBundle, resolveBundleAliases } from './scope-catalog.js';
+import { resolveMasterKey } from './master-key.js';
 import { writeToken } from './token-store.js';
 // Personal (non-Workspace) accounts 403 on admin scopes; ADMIN_SCOPES stays per-account opt-in, never granted by default.
 export const BASE_SCOPES = [
@@ -18,67 +20,12 @@ export const BASE_SCOPES = [
     'https://www.googleapis.com/auth/tasks',
     'https://www.googleapis.com/auth/meetings.space.readonly',
 ];
-export const OPTIONAL_SCOPE_BUNDLES = {
-    slides: [
-        'https://www.googleapis.com/auth/presentations',
-    ],
-    forms: [
-        'https://www.googleapis.com/auth/forms.body',
-        'https://www.googleapis.com/auth/forms.responses.readonly',
-    ],
-    chat: [
-        'https://www.googleapis.com/auth/chat.spaces',
-        'https://www.googleapis.com/auth/chat.messages',
-        'https://www.googleapis.com/auth/chat.messages.create',
-    ],
-    // These extend the always-on gmail service: users.settings.* writes require these
-    // scopes (reads already work via gmail.modify); sharing is split out as riskier.
-    gmail_settings: [
-        'https://www.googleapis.com/auth/gmail.settings.basic',
-    ],
-    gmail_settings_sharing: [
-        'https://www.googleapis.com/auth/gmail.settings.sharing',
-    ],
-    classroom: [
-        'https://www.googleapis.com/auth/classroom.courses',
-        'https://www.googleapis.com/auth/classroom.coursework.me',
-        'https://www.googleapis.com/auth/classroom.coursework.students',
-        'https://www.googleapis.com/auth/classroom.courseworkmaterials',
-        'https://www.googleapis.com/auth/classroom.rosters',
-        'https://www.googleapis.com/auth/classroom.announcements',
-        'https://www.googleapis.com/auth/classroom.topics',
-    ],
-    cloudidentity: [
-        'https://www.googleapis.com/auth/cloud-identity.groups',
-        'https://www.googleapis.com/auth/cloud-identity.devices',
-    ],
-    cloudsearch: ['https://www.googleapis.com/auth/cloud_search'],
-    vault: ['https://www.googleapis.com/auth/ediscovery'],
-    keep: ['https://www.googleapis.com/auth/keep'],
-    driveactivity: ['https://www.googleapis.com/auth/drive.activity.readonly'],
-    drivelabels: [
-        'https://www.googleapis.com/auth/drive.labels',
-        'https://www.googleapis.com/auth/drive.admin.labels',
-    ],
-    script: [
-        'https://www.googleapis.com/auth/script.projects',
-        'https://www.googleapis.com/auth/script.deployments',
-        'https://www.googleapis.com/auth/script.processes',
-        'https://www.googleapis.com/auth/script.metrics',
-    ],
-    postmaster: ['https://www.googleapis.com/auth/postmaster.readonly'],
-    groupssettings: ['https://www.googleapis.com/auth/apps.groups.settings'],
-    groupsmigration: ['https://www.googleapis.com/auth/apps.groups.migration'],
-    licensing: ['https://www.googleapis.com/auth/apps.licensing'],
-    reseller: ['https://www.googleapis.com/auth/apps.order'],
-    appsmarket: ['https://www.googleapis.com/auth/appsmarketplace.license'],
-};
-export const ADMIN_SCOPES = [
-    'https://www.googleapis.com/auth/admin.reports.audit.readonly',
-    'https://www.googleapis.com/auth/admin.directory.user',
-    'https://www.googleapis.com/auth/admin.directory.group.readonly',
-    'https://www.googleapis.com/auth/admin.directory.group.member.readonly',
-];
+// Kept as a derived view for compat (docs generator, tests); the catalog in
+// scope-catalog.ts is the source of truth. "admin" is not an optional bundle.
+export const OPTIONAL_SCOPE_BUNDLES = Object.fromEntries(Object.entries(BUNDLE_CATALOG)
+    .filter(([name]) => name !== 'admin')
+    .map(([name, entry]) => [name, entry.scopes]));
+export { ADMIN_SCOPES };
 /** Parse comma-separated env value into a deduplicated string array. */
 function parseCsvEnv(name) {
     return (process.env[name]?.trim() ?? '')
@@ -86,19 +33,79 @@ function parseCsvEnv(name) {
         .map(s => s.trim())
         .filter(Boolean);
 }
-/** Bundle keys enabled via GOOGLE_OPTIONAL_SCOPES (e.g. ["forms","chat"]). */
+/**
+ * Legacy global override (BC7): a set GOOGLE_OPTIONAL_SCOPES acts as an
+ * implicit "legacy-global" profile applied to every account (env wins over
+ * file profiles, cc-config R2). Unknown names now fail loudly (BR3) where v5
+ * silently dropped them — the intended migration signal.
+ */
+function legacyGlobalProfile() {
+    const names = parseCsvEnv('GOOGLE_OPTIONAL_SCOPES');
+    if (names.length === 0)
+        return null;
+    const bundles = resolveBundleAliases(names);
+    // Boot-time validation lives in resolveAccounts (runs whatever
+    // GOOGLE_TOOLSETS selects); this is defense-in-depth for direct callers.
+    for (const bundle of bundles) {
+        if (bundle === 'admin') {
+            throw new Error('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);
+            throw new Error(`E_UNKNOWN_BUNDLE: unknown bundle "${bundle}" in GOOGLE_OPTIONAL_SCOPES${hint ? ` — did you mean "${hint}"?` : ''}`);
+        }
+    }
+    return { bundles };
+}
+function profileForAccount(alias) {
+    const legacy = legacyGlobalProfile();
+    if (legacy)
+        return legacy;
+    const set = getAccountSet();
+    const name = set.configs[alias]?.scopeProfile ?? 'base';
+    // hasOwn: a profile named like an Object.prototype member must never
+    // resolve to the inherited function.
+    return Object.hasOwn(set.scopeProfiles, name) ? set.scopeProfiles[name] : { bundles: [] };
+}
+/** Union of every account's resolved bundles: a service registers if ANY
+ * account can authorize it; per-account authz happens at call time (BR2). */
 export function getOptionalBundles() {
-    return parseCsvEnv('GOOGLE_OPTIONAL_SCOPES').filter(b => b in OPTIONAL_SCOPE_BUNDLES);
+    const legacy = legacyGlobalProfile();
+    if (legacy)
+        return legacy.bundles.filter(b => b !== 'admin');
+    const union = new Set();
+    const set = getAccountSet();
+    for (const alias of set.aliases) {
+        for (const b of profileForAccount(alias).bundles) {
+            if (b !== 'admin')
+                union.add(b);
+        }
+    }
+    return [...union];
 }
-/** Account aliases granted ADMIN_SCOPES via GOOGLE_ADMIN_ACCOUNTS. */
+/** Aliases granted ADMIN_SCOPES: per-account admin flag (env
+ * GOOGLE_ADMIN_ACCOUNTS overrides config.json at resolve) OR the account's
+ * scope profile carrying admin (boolean or "admin" bundle) — equivalent forms. */
 export function getAdminAccounts() {
-    return parseCsvEnv('GOOGLE_ADMIN_ACCOUNTS');
+    const { aliases, configs } = getAccountSet();
+    return aliases.filter((a) => {
+        if (configs[a].admin === true)
+            return true;
+        const p = profileForAccount(a);
+        return p.admin === true || p.bundles.includes('admin');
+    });
 }
-/** Scopes are fixed at consent time: changing GOOGLE_OPTIONAL_SCOPES or GOOGLE_ADMIN_ACCOUNTS requires re-running auth. */
+/** Scopes are fixed at consent time: changing an account's profile (or the
+ * legacy env) changes its consent set and requires re-running auth. Evaluated
+ * per account: `work` can carry admin + gmail_settings while `personal` is
+ * never asked for them. */
 export function resolveScopesForAccount(alias) {
-    const scopes = [...BASE_SCOPES];
-    for (const bundle of getOptionalBundles()) {
-        scopes.push(...OPTIONAL_SCOPE_BUNDLES[bundle]);
+    const profile = profileForAccount(alias);
+    const scopes = profile.includesBase === false ? [] : [...BASE_SCOPES];
+    for (const bundle of profile.bundles) {
+        if (bundle === 'admin')
+            continue;
+        scopes.push(...BUNDLE_CATALOG[bundle].scopes);
     }
     if (getAdminAccounts().includes(alias)) {
         scopes.push(...ADMIN_SCOPES);
@@ -122,12 +129,11 @@ export async function runAuthFlow(args) {
         console.error(`Unknown account "${alias}". Valid aliases: ${ACCOUNTS.join(', ')}`);
         process.exit(1);
     }
-    const config = ACCOUNT_CONFIG[alias];
+    const config = getAccountSet().configs[alias];
     const scopes = resolveScopesForAccount(alias);
-    if (!process.env.MASTER_KEY) {
-        console.error('MASTER_KEY is not set. Generate one (openssl rand -base64 32) and add it to .env before authenticating.');
-        process.exit(1);
-    }
+    // Auto-provisions on a fresh install (env > keychain > file > generate);
+    // resolves eagerly so a provisioning failure surfaces before the browser opens.
+    resolveMasterKey();
     const oauth2Client = new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost:4242/oauth2callback');
     // CSRF protection for the OAuth callback (RFC 6749 §10.12).
     const expectedState = randomBytes(32).toString('hex');
@@ -198,9 +204,10 @@ export async function runAuthFlow(args) {
         })
             // Bind to loopback only — never expose the OAuth callback to the local network.
             .listen(4242, '127.0.0.1', () => {
-            // Always print the URL: `open` silently no-ops on headless/SSH sessions.
+            // Always print the URL first: the browser launch is best-effort and
+            // silently does nothing on headless/SSH sessions.
             console.log(`Opening your browser to authorize "${alias}". If nothing opens, visit:\n${authorizeUrl}`);
-            open(authorizeUrl, { wait: false }).then((cp) => cp.unref());
+            openUrl(authorizeUrl);
         });
         server.on('error', (err) => {
             if (err.code === 'EADDRINUSE') {

package/dist/client-config.d.ts

@@ -0,0 +1,90 @@
+export type ClientId = 'claude-code' | 'claude-desktop' | 'cursor';
+export type Mode = 'stdio' | 'http';
+export declare const DEFAULT_SERVER_NAME = "mcp-google-multi";
+export interface ClientInfo {
+    id: ClientId;
+    label: string;
+    /** `cli` = registered via a command (Claude Code's ~/.claude.json is
+     *  app-managed, so we never hand-edit it); `file` = a JSON config we merge. */
+    managed: 'file' | 'cli';
+    /** For `file`: the config path. For `cli`: the file we probe for presence. */
+    configPath: string;
+    present: boolean;
+}
+export interface ClientDeps {
+    homedir?: string;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    fileExists?: (p: string) => boolean;
+    readFile?: (p: string) => string;
+    writeFile?: (p: string, data: string) => void;
+    mkdirp?: (dir: string) => void;
+}
+export declare function detectClients(deps?: ClientDeps): ClientInfo[];
+export type ServerEntry = {
+    command: string;
+    args: string[];
+} | {
+    url: string;
+};
+export interface EntryOptions {
+    name?: string;
+    mode: Mode;
+    /** Required for http mode: `${MCP_PUBLIC_URL}/mcp`. */
+    resourceUri?: string;
+    /** stdio launch override; defaults to `npx -y mcp-google-multi`. */
+    command?: string;
+    args?: string[];
+}
+/**
+ * The client `mcpServers` entry. stdio needs no secret env: the server loads
+ * its own .env from ~/.config/mcp-google-multi (cc-config R1), so we never
+ * inline MASTER_KEY / GOOGLE_CLIENT_SECRET into a world-readable client config.
+ */
+export declare function buildServerEntry(opts: EntryOptions): ServerEntry;
+/** The `claude mcp add ...` invocation for Claude Code (cli-managed). */
+export declare function claudeCodeCommand(name: string, entry: ServerEntry): string;
+export interface Instruction {
+    client: ClientId;
+    kind: 'cli' | 'file';
+    /** The copy-pasteable command (cli) or JSON snippet (file). */
+    text: string;
+    /** Target file for `file` kind. */
+    path?: string;
+}
+export declare function renderInstruction(client: ClientInfo, name: string, entry: ServerEntry): Instruction;
+export type ApplyResult = {
+    ok: true;
+    client: ClientId;
+    action: 'added' | 'updated';
+    path: string;
+    backup?: string;
+} | {
+    ok: false;
+    client: ClientId;
+    reason: 'parse_error' | 'cli_managed';
+    message: string;
+    path: string;
+    snippet?: string;
+};
+/**
+ * Idempotently merge the entry into a file-managed client config: read latest,
+ * refuse to clobber an unparseable file (print the snippet instead), back up
+ * the prior file, update-in-place if the key exists.
+ */
+export declare function applyFileEntry(client: ClientInfo, name: string, entry: ServerEntry, deps?: ClientDeps): ApplyResult;
+/** Resolve stdio-vs-http mode from the current transport config (B11).
+ * http/both → a `url` entry; stdio → a `command` entry. */
+export declare function resolveMode(httpConfig?: {
+    transport: 'stdio' | 'http' | 'both';
+    resourceUri: string;
+}): {
+    mode: Mode;
+    resourceUri?: string;
+};
+/**
+ * CLI: `mcp-google-multi write-client-config [--client id] [--name n] [--url u]
+ * [--print] [--yes]`. Consent-gated (clig.dev): never writes a file-managed
+ * config without an explicit yes; non-TTY / `--print` prints the snippet.
+ */
+export declare function runWriteClientConfigCli(argv: string[]): Promise<number>;

package/dist/client-config.js

@@ -0,0 +1,282 @@
+// B15: after the setup wizard finalizes an account, offer to register the
+// server with the user's MCP client so they never hand-edit JSON. Pure core
+// (detection + entry building + idempotent apply), deps-injectable for tests.
+// Consent + non-TTY behavior live in the CLI/tool surfaces; secrets are NEVER
+// inlined — the server self-loads its .env from ~/.config/mcp-google-multi, so
+// a stdio entry needs no secret env at all (distribution.md B15).
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import * as readline from 'node:readline';
+import path from 'node:path';
+import { homedir } from 'node:os';
+export const DEFAULT_SERVER_NAME = 'mcp-google-multi';
+function resolve(deps) {
+    return {
+        home: deps.homedir ?? homedir(),
+        platform: deps.platform ?? process.platform,
+        env: deps.env ?? process.env,
+        fileExists: deps.fileExists ?? ((p) => existsSync(p)),
+        readFile: deps.readFile ?? ((p) => readFileSync(p, 'utf-8')),
+        writeFile: deps.writeFile ?? ((p, d) => writeFileSync(p, d)),
+        mkdirp: deps.mkdirp ?? ((dir) => mkdirSync(dir, { recursive: true })),
+    };
+}
+// Build paths for the TARGET platform's separators, not the running host's, so
+// the injected `platform` is honored deterministically (a Windows CI runner
+// must still produce posix paths for a linux target, and vice versa).
+function pp(r) {
+    return r.platform === 'win32' ? path.win32 : path.posix;
+}
+/** Claude Desktop's config path is OS-specific. */
+function desktopConfigPath(r) {
+    const j = pp(r);
+    if (r.platform === 'darwin') {
+        return j.join(r.home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+    }
+    if (r.platform === 'win32') {
+        const appData = r.env.APPDATA || j.join(r.home, 'AppData', 'Roaming');
+        return j.join(appData, 'Claude', 'claude_desktop_config.json');
+    }
+    return j.join(r.home, '.config', 'Claude', 'claude_desktop_config.json');
+}
+function claudeJsonPath(r) {
+    return pp(r).join(r.home, '.claude.json');
+}
+function cursorConfigPath(r) {
+    return pp(r).join(r.home, '.cursor', 'mcp.json');
+}
+export function detectClients(deps = {}) {
+    const r = resolve(deps);
+    const j = pp(r);
+    const desktop = desktopConfigPath(r);
+    const cursor = cursorConfigPath(r);
+    const claudeJson = claudeJsonPath(r);
+    return [
+        {
+            id: 'claude-code',
+            label: 'Claude Code',
+            managed: 'cli',
+            configPath: claudeJson,
+            // Best-effort: the CLI-managed file or the config dir signals a Claude
+            // Code install; we can't reliably probe PATH cross-platform here.
+            present: r.fileExists(claudeJson) || r.fileExists(j.join(r.home, '.claude')),
+        },
+        {
+            id: 'claude-desktop',
+            label: 'Claude Desktop',
+            managed: 'file',
+            configPath: desktop,
+            present: r.fileExists(desktop) || r.fileExists(j.dirname(desktop)),
+        },
+        {
+            id: 'cursor',
+            label: 'Cursor',
+            managed: 'file',
+            configPath: cursor,
+            present: r.fileExists(cursor) || r.fileExists(j.dirname(cursor)),
+        },
+    ];
+}
+/**
+ * The client `mcpServers` entry. stdio needs no secret env: the server loads
+ * its own .env from ~/.config/mcp-google-multi (cc-config R1), so we never
+ * inline MASTER_KEY / GOOGLE_CLIENT_SECRET into a world-readable client config.
+ */
+export function buildServerEntry(opts) {
+    if (opts.mode === 'http') {
+        if (!opts.resourceUri)
+            throw new Error('E_VALIDATION: http mode requires resourceUri');
+        return { url: opts.resourceUri };
+    }
+    return {
+        command: opts.command ?? 'npx',
+        args: opts.args ?? ['-y', 'mcp-google-multi'],
+    };
+}
+/** The `claude mcp add ...` invocation for Claude Code (cli-managed). */
+export function claudeCodeCommand(name, entry) {
+    if ('url' in entry) {
+        return `claude mcp add --transport http ${name} ${entry.url}`;
+    }
+    return `claude mcp add ${name} -- ${entry.command} ${entry.args.join(' ')}`;
+}
+export function renderInstruction(client, name, entry) {
+    if (client.managed === 'cli') {
+        return { client: client.id, kind: 'cli', text: claudeCodeCommand(name, entry) };
+    }
+    const snippet = JSON.stringify({ mcpServers: { [name]: entry } }, null, 2);
+    return { client: client.id, kind: 'file', text: snippet, path: client.configPath };
+}
+/**
+ * Idempotently merge the entry into a file-managed client config: read latest,
+ * refuse to clobber an unparseable file (print the snippet instead), back up
+ * the prior file, update-in-place if the key exists.
+ */
+export function applyFileEntry(client, name, entry, deps = {}) {
+    const r = resolve(deps);
+    if (client.managed !== 'file') {
+        return { ok: false, client: client.id, reason: 'cli_managed', message: `${client.label} is registered via the CLI, not a config file.`, path: client.configPath };
+    }
+    const p = client.configPath;
+    let existing = {};
+    let priorRaw = null;
+    if (r.fileExists(p)) {
+        priorRaw = r.readFile(p);
+        if (priorRaw.trim() !== '') {
+            let parsed;
+            try {
+                parsed = JSON.parse(priorRaw);
+            }
+            catch {
+                return {
+                    ok: false,
+                    client: client.id,
+                    reason: 'parse_error',
+                    message: `${p} is not valid JSON; not overwriting. Add this entry by hand:`,
+                    path: p,
+                    snippet: renderInstruction(client, name, entry).text,
+                };
+            }
+            if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+                return {
+                    ok: false,
+                    client: client.id,
+                    reason: 'parse_error',
+                    message: `${p} is not a JSON object; not overwriting. Add this entry by hand:`,
+                    path: p,
+                    snippet: renderInstruction(client, name, entry).text,
+                };
+            }
+            existing = parsed;
+        }
+    }
+    const prevServers = (existing.mcpServers && typeof existing.mcpServers === 'object' && !Array.isArray(existing.mcpServers))
+        ? existing.mcpServers
+        : {};
+    const had = Object.prototype.hasOwnProperty.call(prevServers, name);
+    const next = { ...existing, mcpServers: { ...prevServers, [name]: entry } };
+    r.mkdirp(pp(r).dirname(p));
+    // Back up the prior file before rewriting so a bad write is recoverable
+    // (these foreign configs are small and not concurrently written by us, so a
+    // backup + direct write is sufficient — our own config.json uses fs-atomic).
+    let backup;
+    if (priorRaw !== null) {
+        backup = `${p}.bak`;
+        r.writeFile(backup, priorRaw);
+    }
+    r.writeFile(p, `${JSON.stringify(next, null, 2)}\n`);
+    return { ok: true, client: client.id, action: had ? 'updated' : 'added', path: p, backup };
+}
+/** Resolve stdio-vs-http mode from the current transport config (B11).
+ * http/both → a `url` entry; stdio → a `command` entry. */
+export function resolveMode(httpConfig) {
+    if (httpConfig && (httpConfig.transport === 'http' || httpConfig.transport === 'both')) {
+        return { mode: 'http', resourceUri: httpConfig.resourceUri };
+    }
+    return { mode: 'stdio' };
+}
+function argFlag(argv, name) {
+    const i = argv.indexOf(name);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+async function confirmTty(prompt) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    try {
+        const answer = await new Promise((resolve) => rl.question(prompt, resolve));
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * CLI: `mcp-google-multi write-client-config [--client id] [--name n] [--url u]
+ * [--print] [--yes]`. Consent-gated (clig.dev): never writes a file-managed
+ * config without an explicit yes; non-TTY / `--print` prints the snippet.
+ */
+export async function runWriteClientConfigCli(argv) {
+    const name = argFlag(argv, '--name') ?? DEFAULT_SERVER_NAME;
+    const only = argFlag(argv, '--client');
+    const printOnly = argv.includes('--print');
+    const yes = argv.includes('--yes');
+    const urlOverride = argFlag(argv, '--url');
+    let mode = 'stdio';
+    let resourceUri;
+    if (urlOverride) {
+        mode = 'http';
+        resourceUri = urlOverride.replace(/\/+$/, '');
+    }
+    else {
+        try {
+            const { resolveHttpConfig } = await import('./http-config.js');
+            const http = resolveHttpConfig();
+            const m = resolveMode(http);
+            mode = m.mode;
+            resourceUri = m.resourceUri;
+        }
+        catch {
+            // fall back to stdio on any config error
+        }
+    }
+    let entry;
+    try {
+        entry = buildServerEntry({ name, mode, resourceUri });
+    }
+    catch (e) {
+        console.error(e.message);
+        return 1;
+    }
+    let clients = detectClients();
+    if (only) {
+        clients = clients.filter((c) => c.id === only);
+        if (clients.length === 0) {
+            console.error(`Unknown --client "${only}". Known: claude-code, claude-desktop, cursor.`);
+            return 1;
+        }
+    }
+    else {
+        const present = clients.filter((c) => c.present);
+        if (present.length > 0)
+            clients = present;
+    }
+    const nonTty = !process.stdin.isTTY;
+    let wrote = 0;
+    for (const client of clients) {
+        const instr = renderInstruction(client, name, entry);
+        if (client.managed === 'cli') {
+            console.log(`\n${client.label}: run this command`);
+            console.log(`  ${instr.text}`);
+            continue;
+        }
+        if (printOnly || (nonTty && !yes)) {
+            console.log(`\n${client.label}: add to ${instr.path}`);
+            console.log(instr.text);
+            if (nonTty && !yes && !printOnly)
+                console.log('(re-run with --yes to write this automatically)');
+            continue;
+        }
+        const ok = yes || (await confirmTty(`\n${client.label}: write ${instr.path}? [y/N] `));
+        if (!ok) {
+            console.log(`Skipped ${client.label}. Snippet for ${instr.path}:`);
+            console.log(instr.text);
+            continue;
+        }
+        const res = applyFileEntry(client, name, entry);
+        if (res.ok) {
+            wrote++;
+            console.log(`✔ ${client.label}: ${res.action} "${name}" in ${res.path}${res.backup ? ` (backup ${res.backup})` : ''}`);
+        }
+        else {
+            console.error(`✖ ${client.label}: ${res.message}`);
+            if (res.snippet)
+                console.error(res.snippet);
+        }
+    }
+    if (mode === 'http') {
+        console.log(`\nRemote HTTP server: ${resourceUri} — authentication is handled by the OAuth flow, so no secrets are stored in the client config.`);
+    }
+    else {
+        console.log('\nSecrets stay in ~/.config/mcp-google-multi/.env; the client entry carries none.');
+    }
+    void wrote;
+    return 0;
+}

package/dist/client.js

@@ -1,8 +1,15 @@
 import { OAuth2Client } from 'googleapis-common';
-import { ACCOUNT_CONFIG } from './accounts.js';
+import { getAccountSet, refreshAccountSetIfStale } from './accounts.js';
 import { readToken, updateToken } from './token-store.js';
+import { reauthHint } from './reauth-hint.js';
 export async function getClient(account) {
-    const config = ACCOUNT_CONFIG[account];
+    // BR-7: lazy cross-process reload — one stat per dispatch, no watcher;
+    // reload failures keep the last-good registry, never kill the server.
+    refreshAccountSetIfStale();
+    const config = getAccountSet().configs[account];
+    if (!config) {
+        throw new Error(`Unknown account "${account}". Valid aliases: ${getAccountSet().aliases.join(', ')}`);
+    }
     if (!process.env.GOOGLE_CLIENT_ID || !process.env.GOOGLE_CLIENT_SECRET) {
         throw new Error('GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET must be set. ' +
             'Check that .env exists in the project root or pass them as env vars.');
@@ -10,8 +17,7 @@ export async function getClient(account) {
     const oauth2Client = new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost:4242/oauth2callback');
     const tokenData = readToken(account);
     if (!tokenData) {
-        throw new Error(`No token found for account "${account}" (${config.email}). ` +
-            `Run: npx mcp-google-multi auth --account ${account}`);
+        throw new Error(`No token found for account "${account}" (${config.email}). ${reauthHint(account)}`);
     }
     oauth2Client.setCredentials(tokenData);
     oauth2Client.on('tokens', (tokens) => {

package/dist/config-file.d.ts

@@ -0,0 +1,38 @@
+export declare const CONFIG_VERSION = 1;
+export declare function configDir(env?: NodeJS.ProcessEnv): string;
+export declare function configFilePath(env?: NodeJS.ProcessEnv): string;
+export declare const ALIAS_RE: RegExp;
+export interface ConfigFile {
+    version: number;
+    accounts?: Record<string, {
+        email: string;
+        scopeProfile?: string;
+        admin?: boolean;
+    }>;
+    scopeProfiles?: Record<string, {
+        bundles: string[];
+        admin?: boolean;
+        includesBase?: boolean;
+    }>;
+    defaultAccount?: string;
+    discovery?: 'lazy' | 'curated' | 'eager';
+    toolsets?: string;
+}
+export declare function failStartup(slug: string, message: string): never;
+export declare class ConfigFileError extends Error {
+    slug: string;
+    constructor(slug: string, message: string);
+}
+/**
+ * Load + validate config.json. Returns null when the file does not exist.
+ * onInvalid 'exit' is for boot/CLI only; runtime reload paths use 'throw' so a
+ * mid-edit or corrupt file can NEVER kill a running server (and so lock
+ * finally-cleanup still runs).
+ */
+export declare function loadConfigFile(filePath?: string, onInvalid?: 'exit' | 'throw'): ConfigFile | null;
+export declare function writeConfigFile(config: ConfigFile, filePath?: string): void;
+/**
+ * Read-latest-under-lock mutation: acquire the lock, re-read the current file,
+ * apply the change to that (never a stale in-memory copy), write atomically.
+ */
+export declare function mutateConfigFile(fn: (current: ConfigFile) => ConfigFile, filePath?: string): ConfigFile;