mcp-google-multi 6.0.0-beta.2 → 6.0.0-beta.4

package/dist/arg-strict.js

@@ -1,15 +1,7 @@
-// Unknown-argument screening (backlog item 14). zod strips undeclared keys
-// before a handler runs, so a misremembered argument name used to produce a
-// SUCCESS response with wrong behavior: `parentId` on drive_create_folder was
-// dropped and the folder landed in My Drive root. Field-reported, then
-// reproduced: the typo, the correct name and a wholly invented key all
-// returned byte-identical responses.
-//
-// This module is pure and holds no registry reference. It never rewrites a key
-// and never touches a VALUE: it only decides that a key is undeclared, and
-// suggests what the caller probably meant. Rewriting would risk sending a real
-// value to Google on a guess, which is strictly worse than refusing.
-import { editDistance } from './scope-catalog.js';
+// Unknown-argument screening: zod strips undeclared keys before a handler
+// runs, so a misremembered name used to produce a SUCCESS with wrong behavior. See docs/internals.md.
+import { editDistance, SUGGEST_MAX_INPUT } from './scope-catalog.js';
+import { sliceClean } from './trim.js';
 /**
  * `GOOGLE_ARG_UNKNOWN`: reject | warn | off. A typo in the VALUE still falls
  * back to `warn`, not to the default: an operator who misspells the setting
@@ -25,24 +17,15 @@ export function unknownArgMode(env = process.env) {
     process.stderr.write(`GOOGLE_ARG_UNKNOWN="${raw}" is not valid (reject | warn | off); using warn\n`);
     return 'warn';
 }
-// The staged rollout is over: `warn` shipped first as pure observability, and
-// this is the flip it was staging for. An undeclared argument is dropped by
-// zod before the handler runs, so `warn` means the CLIENT sees a confident
-// success for a call the server did not perform: drive_list with a misspelled
-// folder key returned the My Drive root, byte-identical to no argument at all.
-// A wrong answer that reads as right is the failure mode agents recover from
-// worst, so the default refuses the call and says what it probably meant.
+// `warn` means the client sees a confident success for a call the server
+// didn't perform; a wrong answer that reads as right is the worst failure mode to recover from.
 const DEFAULT_MODE = 'reject';
 /** Tools that legitimately accept open-ended top-level keys. Empty at 6.0.0:
  * the escape hatch is NOT one, because its open-endedness lives in the VALUES
  * of queryParams/body, never in its six fixed top-level keys. */
 export const STRICT_EXEMPT_TOOLS = new Set();
-/** Keys a CLIENT adds on its own, not keys the model chose. `random_string`
- * is the long-standing probe some clients send to a tool they read as taking
- * no arguments; the others are call-plumbing that bridges and proxies have
- * been observed to fold into `arguments` instead of `params._meta`, where the
- * spec puts them. Rejecting these would fail a call the model got right.
- * Measured against the full 978-tool surface: none is a declared key. */
+// Keys a CLIENT adds on its own, not keys the model chose (a probe some
+// clients send to argument-less tools, plus call-plumbing bridges fold into `arguments`).
 const CLIENT_ARTIFACT_KEYS = new Set([
     'random_string',
     'toolCallId',
@@ -59,6 +42,20 @@ export function isExemptKey(key) {
  * alone; they match far too much to be useful. */
 const GENERIC = new Set(['id', 'name', 'title', 'body', 'parent', 'text', 'content', 'type', 'value', 'key', 'data']);
 const flatten = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+/** A call can carry thousands of unknown keys, or one of megabytes: only the
+ * first few earn a did-you-mean, and the log line and the envelope echo a
+ * bounded prefix of each name. The reject decision itself is never capped. */
+export const MAX_SUGGESTED_KEYS = 8;
+const MAX_ECHO_CHARS = 64;
+export function echoName(name) {
+    return name.length > MAX_ECHO_CHARS ? `${sliceClean(name, MAX_ECHO_CHARS)}...` : name;
+}
+/** The first MAX_SUGGESTED_KEYS names, each capped, then "and N more". */
+export function echoNames(names, quote = false) {
+    const shown = names.slice(0, MAX_SUGGESTED_KEYS).map((n) => (quote ? `"${echoName(n)}"` : echoName(n)));
+    const rest = names.length - shown.length;
+    return rest > 0 ? `${shown.join(', ')} and ${rest} more` : shown.join(', ');
+}
 function tokens(s) {
     return s
         .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
@@ -76,6 +73,8 @@ function tokens(s) {
  * distance 6, well past any sane threshold, which is why tier 1 exists.
  */
 export function suggestKeys(unknown, declared, limit = 2) {
+    if (unknown.length > SUGGEST_MAX_INPUT)
+        return [];
     const uFlat = flatten(unknown);
     const uTok = tokens(unknown);
     const tiers = [[], [], [], []];
@@ -94,8 +93,12 @@ export function suggestKeys(unknown, declared, limit = 2) {
             tiers[2].push({ key, rank: Math.abs(kFlat.length - uFlat.length) });
             continue;
         }
+        const maxDist = Math.max(1, Math.floor(uFlat.length / 4));
+        // The distance is at least the length gap: skip the DP when that alone fails.
+        if (Math.abs(uFlat.length - kFlat.length) > maxDist)
+            continue;
         const d = editDistance(uFlat, kFlat);
-        if (d <= Math.max(1, Math.floor(uFlat.length / 4)))
+        if (d <= maxDist)
             tiers[3].push({ key, rank: d });
     }
     const tier = tiers.find((t) => t.length > 0);
@@ -117,10 +120,17 @@ export function screenArguments(tool, args, declared) {
     if (STRICT_EXEMPT_TOOLS.has(tool) || declared.length === 0)
         return out;
     const declaredSet = new Set(declared);
+    // Tier 0 is a map lookup, so a redundant twin is recognised past the
+    // ranking budget too; a near-miss duplicate still needs that budget.
+    const byFlat = new Map();
+    for (const k of declared)
+        byFlat.set(flatten(k), [...(byFlat.get(flatten(k)) ?? []), k]);
+    let ranked = 0;
     for (const key of Object.keys(args)) {
         if (declaredSet.has(key) || isExemptKey(key))
             continue;
-        const suggestions = suggestKeys(key, declared);
+        const twins = key.length <= SUGGEST_MAX_INPUT ? byFlat.get(flatten(key)) : undefined;
+        const suggestions = twins ? twins.slice(0, 2) : ranked++ < MAX_SUGGESTED_KEYS ? suggestKeys(key, declared) : [];
         // The caller sent both spellings, so the declared one already won and the
         // outcome is what it has always been. Never fail a call that works today.
         if (suggestions.some((s) => s in args)) {
@@ -133,7 +143,7 @@ export function screenArguments(tool, args, declared) {
 }
 /** The agent-facing envelope. Values are never included, only key names. */
 export function unknownArgEnvelope(tool, unknown, declared, account, siblings = []) {
-    const names = unknown.map((u) => `"${u.sent}"`).join(', ');
+    const names = echoNames(unknown.map((u) => u.sent), true);
     const accepts = `This tool accepts: ${declared.join(', ')}.`;
     const suggested = unknown.flatMap((u) => u.suggestions);
     let hint;

package/dist/auth.d.ts

@@ -1,17 +1,18 @@
+import type { AccountSet } from './accounts.js';
 import { ADMIN_SCOPES } from './scope-catalog.js';
 export declare const BASE_SCOPES: string[];
 export declare const OPTIONAL_SCOPE_BUNDLES: Record<string, string[]>;
 export { ADMIN_SCOPES };
 /** 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 declare function getOptionalBundles(): string[];
+ * account can authorize it; per-account authz happens at call time. */
+export declare function getOptionalBundles(set?: AccountSet): string[];
 /** 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 declare function getAdminAccounts(): string[];
+export declare function getAdminAccounts(set?: AccountSet): string[];
 /** 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 declare function resolveScopesForAccount(alias: string): string[];
+export declare function resolveScopesForAccount(alias: string, set?: AccountSet): string[];
 export declare function runAuthFlow(args: string[]): Promise<void>;

package/dist/auth.js

@@ -1,7 +1,7 @@
 import { randomBytes } from 'node:crypto';
 import { openUrl } from './open-url.js';
 import { ACCOUNTS, getAccountSet } from './accounts.js';
-import { ADMIN_SCOPES, BUNDLE_CATALOG, closestBundle, resolveBundleAliases } from './scope-catalog.js';
+import { ADMIN_SCOPES, BUNDLE_CATALOG, closestBundle, isKnownBundle, resolveBundleAliases } from './scope-catalog.js';
 import { resolveMasterKey } from './master-key.js';
 import { writeToken } from './token-store.js';
 import { buildConsentClient, openLoopbackConsent, TESTING_MODE_WARNING } from './oauth-consent.js';
@@ -31,12 +31,8 @@ function parseCsvEnv(name) {
         .map(s => s.trim())
         .filter(Boolean);
 }
-/**
- * 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.
- */
+// A set GOOGLE_OPTIONAL_SCOPES acts as an implicit profile applied to every
+// account (env wins over file profiles); unknown names fail loudly.
 function legacyGlobalProfile() {
     const names = parseCsvEnv('GOOGLE_OPTIONAL_SCOPES');
     if (names.length === 0)
@@ -48,33 +44,31 @@ function legacyGlobalProfile() {
         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)) {
+        if (!isKnownBundle(bundle)) {
             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) {
+function profileForAccount(alias, set = getAccountSet()) {
     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() {
+ * account can authorize it; per-account authz happens at call time. */
+export function getOptionalBundles(set = getAccountSet()) {
     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) {
+        for (const b of profileForAccount(alias, set).bundles) {
             if (b !== 'admin')
                 union.add(b);
         }
@@ -84,12 +78,12 @@ export function getOptionalBundles() {
 /** 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() {
-    const { aliases, configs } = getAccountSet();
+export function getAdminAccounts(set = getAccountSet()) {
+    const { aliases, configs } = set;
     return aliases.filter((a) => {
         if (configs[a].admin === true)
             return true;
-        const p = profileForAccount(a);
+        const p = profileForAccount(a, set);
         return p.admin === true || p.bundles.includes('admin');
     });
 }
@@ -97,15 +91,15 @@ export function getAdminAccounts() {
  * 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 profile = profileForAccount(alias);
+export function resolveScopesForAccount(alias, set = getAccountSet()) {
+    const profile = profileForAccount(alias, set);
     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)) {
+    if (getAdminAccounts(set).includes(alias)) {
         scopes.push(...ADMIN_SCOPES);
     }
     return Array.from(new Set(scopes));
@@ -132,9 +126,8 @@ export async function runAuthFlow(args) {
     // Auto-provisions on a fresh install (env > keychain > file > generate);
     // resolves eagerly so a provisioning failure surfaces before the browser opens.
     resolveMasterKey();
-    // Shared ephemeral-port loopback flow (oauth-consent.ts): listen first, then
-    // build the auth URL from the assigned redirect. CLI gets a patient timeout;
-    // errors propagate to main()'s fatal handler like every other CLI failure.
+    // Listen first, then build the auth URL from the assigned redirect; errors
+    // propagate to main()'s fatal handler like every other CLI failure.
     const loop = await openLoopbackConsent({ timeoutMs: 10 * 60_000 });
     const oauth2Client = buildConsentClient(loop.redirect);
     // CSRF protection for the OAuth callback (RFC 6749 §10.12).

package/dist/boot-gates.d.ts

@@ -0,0 +1,26 @@
+export interface MtBootGates {
+    /** True = multi-tenant deployment: the server boots with zero accounts
+     * (tenants provision in-band) and the provisioning gate below replaces the
+     * flat owner-allowlist requirement. */
+    multiTenant: boolean;
+    /** Fail-fast replacement for the E_OWNER_EMAILS_REQUIRED check. MUST refuse
+     * (exit/throw) when no valid provisioning mechanism is configured — an
+     * ungated HTTP endpoint must never boot, whatever the condition checked. */
+    assertProvisioningGate: () => void;
+}
+export declare function setMtBootGates(g: MtBootGates | null): void;
+export declare function mtBootGates(): MtBootGates | null;
+export declare function isMultiTenantBoot(): boolean;
+/** The empty-registry guard applies to stdio always, and to HTTP only when single-owner: a
+ * multi-tenant HTTP deploy starts empty by design. */
+export declare function accountsAssertRequired(wantStdio: boolean, multiTenant: boolean): boolean;
+/** A set GOOGLE_ACCOUNTS on a multi-tenant boot is refused at DEPLOY time:
+ * the env registry is process-wide, so it would graft one operator's accounts
+ * onto every tenant and turn every tenant's first wizard call into a dead
+ * end (the per-call E_ENV_ACCOUNTS_MODE guard), N confusing failures instead
+ * of one clear one. */
+export declare function assertNoEnvAccountsMode(env?: NodeJS.ProcessEnv): void;
+/** Same class, second vector: GOOGLE_OPTIONAL_SCOPES is a process-wide legacy
+ * global scope profile, so on a multi-tenant box one operator's scope choice
+ * would silently apply to every tenant's consent. */
+export declare function assertNoEnvOptionalScopesMode(env?: NodeJS.ProcessEnv): void;

package/dist/boot-gates.js

@@ -0,0 +1,36 @@
+// Multi-tenant boot gates: every helper reduces to single-owner behavior when
+// no gates are installed. Deliberately side-effect-free, unlike accounts.ts/auth.ts.
+import { failStartup } from './config-file.js';
+let gates = null;
+export function setMtBootGates(g) {
+    gates = g;
+}
+export function mtBootGates() {
+    return gates;
+}
+export function isMultiTenantBoot() {
+    return gates?.multiTenant === true;
+}
+/** The empty-registry guard applies to stdio always, and to HTTP only when single-owner: a
+ * multi-tenant HTTP deploy starts empty by design. */
+export function accountsAssertRequired(wantStdio, multiTenant) {
+    return wantStdio || !multiTenant;
+}
+/** A set GOOGLE_ACCOUNTS on a multi-tenant boot is refused at DEPLOY time:
+ * the env registry is process-wide, so it would graft one operator's accounts
+ * onto every tenant and turn every tenant's first wizard call into a dead
+ * end (the per-call E_ENV_ACCOUNTS_MODE guard), N confusing failures instead
+ * of one clear one. */
+export function assertNoEnvAccountsMode(env = process.env) {
+    if (env.GOOGLE_ACCOUNTS?.trim()) {
+        failStartup('E_ENV_ACCOUNTS_MODE_MT', 'GOOGLE_ACCOUNTS must not be set on a multi-tenant deployment; accounts are linked in-band per tenant. Unset it and restart.');
+    }
+}
+/** Same class, second vector: GOOGLE_OPTIONAL_SCOPES is a process-wide legacy
+ * global scope profile, so on a multi-tenant box one operator's scope choice
+ * would silently apply to every tenant's consent. */
+export function assertNoEnvOptionalScopesMode(env = process.env) {
+    if (env.GOOGLE_OPTIONAL_SCOPES?.trim()) {
+        failStartup('E_ENV_OPTIONAL_SCOPES_MT', 'GOOGLE_OPTIONAL_SCOPES must not be set on a multi-tenant deployment; scopes are chosen per tenant at consent. Unset it and restart.');
+    }
+}

package/dist/cimd-cache.d.ts

@@ -0,0 +1,38 @@
+export declare const CIMD_TTL_MS: number;
+/** The oldest validated document still served while the cap is full or the issuer cannot answer. */
+export declare const CIMD_MAX_STALE_MS: number;
+/** Fetches at once. A lookup can outlive the fetch that gave up on it, so ssrf-guard caps its own lookups apart. */
+export declare const CIMD_MAX_IN_FLIGHT = 4;
+export declare const CIMD_CACHE_MAX = 256;
+export type CimdDocument = Record<string, unknown>;
+type CimdError = {
+    error: 'E_CIMD_SSRF_BLOCKED' | 'E_CIMD_INVALID';
+};
+/** `fresh` is true only for the request whose fetch produced the document. */
+export type CimdResolution = {
+    doc: CimdDocument;
+    fresh: boolean;
+} | {
+    busy: true;
+} | CimdError;
+export interface CimdCacheDeps {
+    fetch: (clientId: string) => Promise<CimdDocument>;
+    now: () => number;
+    log: (line: string) => void;
+}
+export declare class CimdClientCache {
+    private readonly deps;
+    private readonly entries;
+    private readonly inFlight;
+    private busyLoggedAt;
+    private busySuppressed;
+    constructor(deps: CimdCacheDeps);
+    get size(): number;
+    /** `validate` runs once per fetch, in the request that started it, and every
+     * request waiting on that fetch gets the same answer. */
+    resolve(clientId: string, validate: (doc: CimdDocument) => boolean): Promise<CimdResolution>;
+    private fetchFor;
+    private store;
+    private noteBusy;
+}
+export {};

package/dist/cimd-cache.js

@@ -0,0 +1,111 @@
+// Bounds the unauthenticated-fetch surface of GET /authorize: capped
+// in-flight fetches, one fetch per client_id, no error caching. See docs/internals.md.
+import { CimdHttpError, isTransientFetchError, SsrfBlockedError } from './ssrf-guard.js';
+import { logSafe } from './trim.js';
+export const CIMD_TTL_MS = 5 * 60_000;
+/** The oldest validated document still served while the cap is full or the issuer cannot answer. */
+export const CIMD_MAX_STALE_MS = 24 * 60 * 60_000;
+/** Fetches at once. A lookup can outlive the fetch that gave up on it, so ssrf-guard caps its own lookups apart. */
+export const CIMD_MAX_IN_FLIGHT = 4;
+export const CIMD_CACHE_MAX = 256;
+const BUSY_LOG_EVERY_MS = 60_000;
+export class CimdClientCache {
+    deps;
+    entries = new Map();
+    // One entry per running fetch, so its size is the number of permits taken.
+    inFlight = new Map();
+    busyLoggedAt = -Infinity;
+    busySuppressed = 0;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get size() {
+        return this.entries.size;
+    }
+    /** `validate` runs once per fetch, in the request that started it, and every
+     * request waiting on that fetch gets the same answer. */
+    async resolve(clientId, validate) {
+        const entry = this.entries.get(clientId);
+        const age = entry ? this.deps.now() - entry.at : 0;
+        if (entry && age < CIMD_TTL_MS)
+            return { doc: entry.doc, fresh: false };
+        if (entry && age >= CIMD_MAX_STALE_MS)
+            this.entries.delete(clientId);
+        const running = this.inFlight.get(clientId);
+        if (running) {
+            const out = await running;
+            return 'doc' in out ? { doc: out.doc, fresh: false } : out;
+        }
+        if (this.inFlight.size >= CIMD_MAX_IN_FLIGHT) {
+            // A flood of fresh paths is exactly when the cap is full, and a client
+            // that signed in before must still be able to.
+            const stale = this.entries.get(clientId);
+            if (stale)
+                return { doc: stale.doc, fresh: false };
+            this.noteBusy();
+            return { busy: true };
+        }
+        return this.fetchFor(clientId, validate);
+    }
+    async fetchFor(clientId, validate) {
+        // Never rejects: neither core nor a host installs an unhandledRejection
+        // handler, and a waiter that stopped listening must not take the process down.
+        let settle;
+        this.inFlight.set(clientId, new Promise((r) => (settle = r)));
+        let out = { error: 'E_CIMD_INVALID' };
+        try {
+            const doc = await this.deps.fetch(clientId);
+            if (validate(doc)) {
+                this.store(clientId, doc);
+                out = { doc, fresh: true };
+            }
+            else {
+                this.entries.delete(clientId);
+            }
+        }
+        catch (e) {
+            out = { error: e instanceof SsrfBlockedError ? 'E_CIMD_SSRF_BLOCKED' : 'E_CIMD_INVALID' };
+            // stale-if-error: an issuer that's down/overloaded says nothing about
+            // the document, so the last good one stays and serves this fetch too.
+            const stale = this.entries.get(clientId);
+            if (!saysNothingAboutDocument(e))
+                this.entries.delete(clientId);
+            else if (stale && this.deps.now() - stale.at < CIMD_MAX_STALE_MS)
+                out = { doc: stale.doc, fresh: false };
+            // The detail goes to the log only; the caller gets a generic answer.
+            this.deps.log(`CIMD fetch failed for ${logSafe(clientId, 128)}: ${logSafe(e instanceof Error ? e.message : 'non-Error rejection', 200)}`);
+        }
+        finally {
+            this.inFlight.delete(clientId);
+            settle(out);
+        }
+        return out;
+    }
+    store(clientId, doc) {
+        this.entries.delete(clientId);
+        while (this.entries.size >= CIMD_CACHE_MAX) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.entries.delete(oldest);
+        }
+        this.entries.set(clientId, { doc, at: this.deps.now() });
+    }
+    // Over-cap requests arrive at whatever rate the caller likes.
+    noteBusy() {
+        const now = this.deps.now();
+        if (now >= this.busyLoggedAt && now - this.busyLoggedAt < BUSY_LOG_EVERY_MS) {
+            this.busySuppressed++;
+            return;
+        }
+        const suppressed = this.busySuppressed;
+        this.busyLoggedAt = now;
+        this.busySuppressed = 0;
+        this.deps.log(`CIMD busy: in-flight cap reached${suppressed > 0 ? ` (n=${suppressed} suppressed)` : ''}`);
+    }
+}
+function saysNothingAboutDocument(e) {
+    if (isTransientFetchError(e))
+        return true;
+    return e instanceof CimdHttpError && (e.status === 408 || e.status === 429 || e.status >= 500);
+}

package/dist/client-config.d.ts

@@ -38,7 +38,7 @@ export interface EntryOptions {
 }
 /**
  * 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
+ * its own .env from ~/.config/mcp-google-multi, so we never
  * inline MASTER_KEY / GOOGLE_CLIENT_SECRET into a world-readable client config.
  */
 export declare function buildServerEntry(opts: EntryOptions): ServerEntry;
@@ -73,7 +73,7 @@ export type ApplyResult = {
  * 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).
+/** Resolve stdio-vs-http mode from the current transport config.
  * http/both → a `url` entry; stdio → a `command` entry. */
 export declare function resolveMode(httpConfig?: {
     transport: 'stdio' | 'http' | 'both';

package/dist/client-config.js

@@ -1,9 +1,5 @@
-// 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).
+// Registers 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.
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import * as readline from 'node:readline';
 import path from 'node:path';
@@ -20,9 +16,8 @@ function resolve(deps) {
         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).
+// Build paths for the TARGET platform's separators, not the running host's,
+// so the injected `platform` is honored deterministically.
 function pp(r) {
     return r.platform === 'win32' ? path.win32 : path.posix;
 }
@@ -78,7 +73,7 @@ export function detectClients(deps = {}) {
 }
 /**
  * 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
+ * its own .env from ~/.config/mcp-google-multi, so we never
  * inline MASTER_KEY / GOOGLE_CLIENT_SECRET into a world-readable client config.
  */
 export function buildServerEntry(opts) {
@@ -155,9 +150,8 @@ export function applyFileEntry(client, name, entry, deps = {}) {
     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).
+    // Back up before rewriting so a bad write is recoverable; our own
+    // config.json uses fs-atomic, but these small foreign configs don't need it.
     let backup;
     if (priorRaw !== null) {
         backup = `${p}.bak`;
@@ -166,7 +160,7 @@ export function applyFileEntry(client, name, entry, deps = {}) {
     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).
+/** Resolve stdio-vs-http mode from the current transport config.
  * http/both → a `url` entry; stdio → a `command` entry. */
 export function resolveMode(httpConfig) {
     if (httpConfig && (httpConfig.transport === 'http' || httpConfig.transport === 'both')) {

package/dist/client.d.ts

@@ -1,3 +1,33 @@
 import { OAuth2Client } from 'googleapis-common';
-import type { Account } from './accounts.js';
-export declare function getClient(account: Account): Promise<OAuth2Client>;
+import type { Account, AccountSet } from './accounts.js';
+import type { TokenData } from './types.js';
+export interface GetClientDeps {
+    /** Live account view — read at call time, never a captured snapshot. */
+    accounts: () => AccountSet;
+    readToken: (alias: string) => TokenData | null;
+    updateToken: (alias: string, updates: object) => void;
+    /** Cross-process staleness probe (single-owner global registry only). */
+    refreshIfStale?: () => void;
+}
+/** Test-only visibility into the dedupe map. */
+export declare function __inflightSizeForTest(): number;
+/**
+ * Per-context client factory: `contextKey` namespaces the single-flight map
+ * (one lane per tenant), `deps` carry that context's account view and token
+ * custody. The free core builds exactly one, bound to the global registry.
+ */
+export declare function makeGetClient(contextKey: string, deps: GetClientDeps): (account: Account) => Promise<OAuth2Client>;
+/** Injection surface for curated tool files: absent = the single-owner
+ * getClient below (today's behavior); a tenant context passes its own. */
+export interface CuratedToolDeps {
+    getClientFn?: typeof getClient;
+    /** Whether tools may read or write the server host's disk (local uploads,
+     * downloads, attachments). Absent = true; the host belongs to its operator,
+     * so a non-owner context passes false. */
+    localFiles?: boolean;
+}
+/** The single-owner client, bound to the global registry + token store. The
+ * operator surfaces that never carry a tenant (api-probe, executor and
+ * escape-hatch `deps.getClientFn ?? getClient` defaults) resolve through
+ * this. */
+export declare const getClient: (account: Account) => Promise<OAuth2Client>;

package/dist/compose.d.ts

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import type { ServerTarget } from './http-transport.js';
+import { ToolRegistry, type DiscoveryMode } from './registry.js';
+import { type IdentityContext } from './identity.js';
+import type { Metrics } from './usage-metrics.js';
+export interface McpServerOptions {
+    /** Sent in the initialize result; omitted entirely when absent or blank. */
+    instructions?: string;
+}
+/** The one place the MCP server is constructed, so an embedding host can pass
+ * per-session `instructions` without re-deriving the server identity. */
+export declare function createMcpServer(version: string, opts?: McpServerOptions): McpServer;
+export declare function buildRegistry(server: McpServer, ctx: IdentityContext, mode?: DiscoveryMode, metrics?: Metrics | null): ToolRegistry;
+/** The per-request hooks bound to one registry: argument shapes, unknown-
+ * argument screening and the account a validation envelope names. Both
+ * transports and every resolved server target build them here, so a mistyped
+ * argument behaves the same wherever it arrives. */
+export declare function requestHooksFor(registry: ToolRegistry, ctx: Pick<IdentityContext, 'accounts'>, metrics?: Metrics | null, env?: NodeJS.ProcessEnv): Omit<ServerTarget, 'server'>;