mcp-google-multi 6.0.0-beta.3 → 6.0.0-beta.5

package/README.md

@@ -4,7 +4,7 @@ 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** — 940 tools across 29 services, now including Google Analytics (GA4), + an escape hatch for anything else → [COVERAGE.md](./COVERAGE.md)
+- 🧰 **Exhaustive** — 942 tools across 29 services, now including Google Analytics (GA4), + 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). Pull-and-up Docker Compose with optional automatic HTTPS → [remote setup](./docs/http-setup.md)
@@ -44,7 +44,7 @@ New to all this? It's written for someone who just installed Claude Code and has
 5. **Add it to Claude Code, then restart Claude Code:**
 
    ```bash
-   claude mcp add google-multi -s user -- npx -y mcp-google-multi
+   claude mcp add mcp-google-multi -s user -- npx -y mcp-google-multi
    ```
 
 **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."*
@@ -55,14 +55,28 @@ New to all this? It's written for someone who just installed Claude Code and has
 
 **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) · [Local usage metrics](./docs/usage-metrics.md) · [Migrating to v6](./MIGRATION-v6.md) · [Security policy](./SECURITY.md) · [Roadmap](https://github.com/bakissation/mcp-google-multi/milestones)
 
-## Maintainer & credits
+## Agent skill
+
+The repo and the npm package both ship an [Agent Skill](https://code.claude.com/docs/en/skills) at `skills/google-workspace/`: a hand-written `SKILL.md` covering account selection, the discover step, incremental Gmail sweeps, keeping results small, write profiles, and the escape hatch, plus a `reference/` folder with a generated argument table per service. Loading it gets an agent calling this server's tools correctly without guessing argument names.
+
+To install it for Claude Code, copy or symlink the `skills/google-workspace` folder into `~/.claude/skills/` (every project) or a project's own `.claude/skills/` (that project only):
+
+```bash
+# from a cloned copy of this repo
+ln -s "$(pwd)/skills/google-workspace" ~/.claude/skills/google-workspace
+
+# from the installed npm package
+ln -s "$(npm root -g)/mcp-google-multi/skills/google-workspace" ~/.claude/skills/google-workspace
+```
+
+## Maintainer, sponsor & license
 
 Built and maintained by **Abdelbaki Berkati** — [berkati.xyz](https://berkati.xyz) · [@bakissation](https://github.com/bakissation). [Read the case study →](https://berkati.xyz/case-studies/mcp-google-multi/)
 
 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)). **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.
+An Enterprise Edition (hosted, multi-tenant) is available: ask through [berkati.xyz](https://berkati.xyz) (email or LinkedIn there).
 
-## License
+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.
 
-[MIT](./LICENSE)
+Licensed under [MIT](./LICENSE).

package/dist/accounts.d.ts

@@ -28,7 +28,7 @@ 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. */
+/** Cross-process staleness probe: 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
@@ -43,7 +43,7 @@ export declare function unknownAliasMessage(aliases: readonly string[], selector
  * 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
+ * REPORT the empty registry. 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>;
@@ -62,7 +62,7 @@ export declare function liveAccountCheck(aliases: () => readonly string[], selec
 /** True for a field built on liveAccountCheck, optional or not. */
 export declare function isLiveAccountField(field: unknown): boolean;
 /**
- * BR-4: the stdio/http SERVER never boots with an empty registry — a fresh user
+ * 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). */

package/dist/accounts.js

@@ -67,7 +67,7 @@ function noAccountsMessage() {
         `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 resolution: 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);
@@ -75,8 +75,7 @@ function noAccountsMessage() {
  */
 let warnedLegacy = false;
 export function resolveAccounts(env = process.env, filePath = configFilePath(), onInvalid = 'exit', 
-// emptyOk: zero accounts is a valid set, not an error, even with 'throw'
-// (a context that has linked nothing yet). An invalid file still fails.
+// emptyOk: zero accounts is a valid set, not an error, even with 'throw'.
 opts = {}) {
     const dir = opts.tokenDir ?? tokenDir;
     const adminEnv = parseCsv(env.GOOGLE_ADMIN_ACCOUNTS);
@@ -86,9 +85,8 @@ opts = {}) {
             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).
+    // Validate at BOOT, or a typo only surfaces at dispatch time inside
+    // account_list instead of the promised startup error.
     const legacyNames = parseCsv(env.GOOGLE_OPTIONAL_SCOPES);
     if (legacyNames.length > 0) {
         for (const bundle of resolveBundleAliases(legacyNames)) {
@@ -120,19 +118,13 @@ opts = {}) {
             ...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.
+    // Stat BEFORE read, so a race lands on the conservative (stale) side.
     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.
+        // Not fatal here: bootstrap/diagnostic CLIs must run on a fresh install;
+        // only the server refuses to boot empty (index.ts).
         if (onInvalid === 'throw' && !opts.emptyOk) {
             throw new Error(`E_NO_ACCOUNTS_CONFIGURED: ${noAccountsMessage()}`);
         }
@@ -144,9 +136,8 @@ opts = {}) {
             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.
+    // Unknown bundle names fail loudly (a mis-scoped token is worse than a clear
+    // error). Null prototype: profile names are user input, must never collide with Object.prototype.
     const scopeProfiles = Object.create(null);
     scopeProfiles.base = { bundles: [] };
     for (const [name, profile] of Object.entries(config?.scopeProfiles ?? {})) {
@@ -187,9 +178,8 @@ opts = {}) {
         ...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). */
+// env GOOGLE_DEFAULT_ACCOUNT > config.defaultAccount > unset; an unknown alias
+// refuses to start as E_DEFAULT_ACCOUNT_UNKNOWN, 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;
@@ -208,17 +198,14 @@ export function fileStamp(filePath, version) {
         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).
+// env is set and no config.json exists yet: materialize the file so the
+// wizard has something to edit; a write failure must never block boot.
 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).
+        // lock + re-check + atomic write, so a concurrent wizard/migrate writer is never clobbered.
         mutateConfigFile((current) => {
             if (Object.keys(current.accounts ?? {}).length > 0)
                 return current;
@@ -251,7 +238,7 @@ export function invalidateAccountSet() {
     return current;
 }
 /**
- * Dispatch-path reload (BR-7): NEVER exits and never throws — a mid-edit,
+ * Dispatch-path reload: 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.
  */
@@ -271,7 +258,7 @@ export function refreshAccountSetIfStale() {
         }
     }
 }
-/** Cross-process staleness probe (BR-7): one stat, compared against the stamp. */
+/** Cross-process staleness probe: one stat, compared against the stamp. */
 export function isAccountSetStale() {
     if (current.source !== 'file')
         return false;
@@ -297,7 +284,7 @@ export function unknownAliasMessage(aliases, selectors = false) {
  * 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
+ * REPORT the empty registry. 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) {
@@ -339,7 +326,7 @@ export function isLiveAccountField(field) {
     return def?.checks?.some((c) => LIVE_ACCOUNT_CHECKS.has(c)) ?? false;
 }
 /**
- * BR-4: the stdio/http SERVER never boots with an empty registry — a fresh user
+ * 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). */

package/dist/arg-normalize.js

@@ -1,10 +1,7 @@
 import { echoName, echoNames, screenArguments, unknownArgEnvelope, } from './arg-strict.js';
 import { logSafe, sliceClean } from './trim.js';
-// The SDK synthesizes input-validation failures as isError RESULTS, skipping
-// the handler entirely: no handler of ours runs, so no envelope exists and the
-// client gets free text. The text is prose in both SDK eras (v1 prefixed it
-// with "MCP error -32602: ", v2 dropped that prefix), while handler envelopes
-// are always JSON starting with "{".
+// The SDK synthesizes input-validation failures as isError RESULTS (no handler
+// runs), so the client gets free prose; handler envelopes always start with "{".
 const SCHEMA_VALIDATION_TEXT = /^(MCP error -32602: )?Input validation error:/;
 export function isSchemaValidationText(text) {
     return SCHEMA_VALIDATION_TEXT.test(text);
@@ -12,18 +9,11 @@ export function isSchemaValidationText(text) {
 /** Capture form of the v2 text. The tool-name class excludes ':' and ' ', so
  * the first ": " after the name is unambiguously the delimiter. */
 const VALIDATION_PROSE = /^(?:MCP error -32602: )?Input validation error: Invalid arguments for tool ([A-Za-z0-9_.-]+): ([\s\S]+)$/;
-/** The SDK's OTHER synthesized prose on the same catch. Both prefixes are
- * SDK-authored; a HANDLER's free text is not, and must survive untouched
- * (the account wizard answers in prose today). */
+/** The SDK's OTHER synthesized prose on the same catch; a HANDLER's free text
+ * is not SDK-authored and must survive untouched. */
 const SDK_OUTPUT_PROSE = /^(?:MCP error -32602: )?Output validation error: /;
-// 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: the SDK 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.
+// Wire-level, not schema-level: the SDK advertises an EMPTY input schema for
+// any non-object wrapper, so the JSON-RPC message is the only stable seam. See docs/internals.md.
 export function argNormalizationEnabled(env = process.env) {
     return !/^(0|false|off|no)$/i.test((env.GOOGLE_ARG_NORMALIZE ?? '').trim());
 }
@@ -94,11 +84,8 @@ export function screenMessage(msg, opts, log = (l) => process.stderr.write(`${l}
         return { action: 'forward', msg };
     const tool = m.params.name;
     const declared = opts.declaredFor(tool);
-    // Unregistered tool. The spec keeps this a PROTOCOL error (unknown tool is
-    // not something the model can fix by adjusting arguments), so the channel
-    // stays a JSON-RPC error; only the message gets the did-you-mean and the
-    // gated-service next step. Without `unknownTool`, or on a notification,
-    // the SDK's own "not found" still answers.
+    // Unregistered tool stays a PROTOCOL error (not an arguments problem); only
+    // the message gets the did-you-mean. No `unknownTool`, or a notification: the SDK's own answers.
     if (!declared) {
         if (!opts.unknownTool || m.id === undefined)
             return { action: 'forward', msg };
@@ -115,8 +102,7 @@ export function screenMessage(msg, opts, log = (l) => process.stderr.write(`${l}
     if (screened.unknown.length === 0 && screened.redundant.length === 0)
         return { action: 'forward', msg };
     const all = [...screened.unknown.map((u) => u.sent), ...screened.redundant];
-    // Key names only; argument VALUES never reach the log. The names are the
-    // caller's, so they are escaped here and only here: the envelope is JSON.
+    // Key names only, escaped here and only here: the caller's names, never values, reach the log.
     log(`[args] ${tool}: undeclared ${logSafe(echoNames(all), 600)}${opts.mode === 'warn' ? ' (dropped)' : ' (rejected)'}`);
     try {
         // Only ever a DECLARED key or the literal placeholder, so the metrics
@@ -167,13 +153,10 @@ export function withArgNormalization(transport, shapeFor, log, onRename, strict)
                     if (outcome.action === 'forward')
                         return handler(outcome.msg, extra);
                     // Last-resort fallback: dispatch as before rather than hang the
-                    // caller. The stderr line and the counter already fired above.
-                    // `send` is async, so a rejected promise needs catching too: a
-                    // bare `void` left the client waiting for a frame that never came.
+                    // caller; send is async, so a bare `void` would leave it waiting forever on rejection.
                     const fallback = () => handler(normalized, extra);
                     try {
-                        // Answer on the INNER transport so the metrics tap still sees the
-                        // frame and clears its pending id.
+                        // On the INNER transport so the metrics tap still sees the frame and clears its pending id.
                         void Promise.resolve(transport.send(outcome.response)).catch(fallback);
                     }
                     catch {
@@ -195,10 +178,8 @@ export function withArgNormalization(transport, shapeFor, log, onRename, strict)
     if (transport.setProtocolVersion) {
         wrapper.setProtocolVersion = (v) => transport.setProtocolVersion(v);
     }
-    // v2-only, called by Protocol.connect() before start(). A no-op today (both
-    // sides default to the same exported constant), but a proxy that silently
-    // eats a member the SDK calls is a bug waiting for the first caller that
-    // passes supportedProtocolVersions explicitly.
+    // A no-op today, but a proxy silently eating an SDK-called member is a bug
+    // waiting for the first caller that passes this explicitly.
     if (transport.setSupportedProtocolVersions) {
         wrapper.setSupportedProtocolVersions = (v) => transport.setSupportedProtocolVersions(v);
     }
@@ -230,9 +211,8 @@ export function outputFailureEnvelope(tool, text, account) {
 }
 export function rewriteValidationFrame(message, pending, opts) {
     const m = message;
-    // Responses only. A server-initiated REQUEST (elicitation, sampling) also
-    // carries an id, from a different id space, and evicting on it would drop a
-    // real pending call.
+    // Responses only: a server-initiated REQUEST also carries an id (a
+    // different id space), and evicting on it would drop a real pending call.
     if (m.id === undefined || m.method !== undefined)
         return message;
     const call = pending.get(m.id);

package/dist/arg-strict.js

@@ -1,14 +1,5 @@
-// 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.
+// 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';
 /**
@@ -26,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',
@@ -138,10 +120,8 @@ export function screenArguments(tool, args, declared) {
     if (STRICT_EXEMPT_TOOLS.has(tool) || declared.length === 0)
         return out;
     const declaredSet = new Set(declared);
-    // Tier 0 (same key modulo case and separators) is a map lookup, so every key
-    // gets it and a redundant twin is recognised past the ranking budget too.
-    // A near-miss duplicate (a typo sent next to its declared key) is recognised
-    // only within the budget: a call needs 9 of them before one is refused.
+    // 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]);

package/dist/auth.d.ts

@@ -4,7 +4,7 @@ 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). */
+ * 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

package/dist/auth.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)
@@ -65,7 +61,7 @@ function profileForAccount(alias, set = getAccountSet()) {
     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). */
+ * account can authorize it; per-account authz happens at call time. */
 export function getOptionalBundles(set = getAccountSet()) {
     const legacy = legacyGlobalProfile();
     if (legacy)
@@ -130,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

@@ -11,7 +11,7 @@ export interface MtBootGates {
 export declare function setMtBootGates(g: MtBootGates | null): void;
 export declare function mtBootGates(): MtBootGates | null;
 export declare function isMultiTenantBoot(): boolean;
-/** BR-4 applies to stdio always, and to HTTP only when single-owner: a
+/** 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:

package/dist/boot-gates.js

@@ -1,7 +1,5 @@
-// S1.16: multi-tenant boot gates. The free core never sets these — every
-// helper reduces to today's single-owner behavior when no gates are
-// installed. Deliberately a side-effect-free module (accounts.ts/auth.ts
-// resolve env at import time) so the tenancy module can import it cheaply.
+// 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) {
@@ -13,7 +11,7 @@ export function mtBootGates() {
 export function isMultiTenantBoot() {
     return gates?.multiTenant === true;
 }
-/** BR-4 applies to stdio always, and to HTTP only when single-owner: a
+/** 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;

package/dist/cimd-cache.js

@@ -1,9 +1,5 @@
-// H4 F6: GET /authorize is unauthenticated, and a client_id on an allowlisted
-// issuer with a path never seen before forces an outbound fetch. So the
-// fetches running at once are capped, one client_id is fetched once however
-// many requests wait on it, and only a document that passed validation is
-// kept. Errors are never cached (CIMD section 5.2), and a negative cache would
-// not help anyway: the attack varies the path, so its key never repeats.
+// 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;
@@ -69,16 +65,14 @@ export class CimdClientCache {
         }
         catch (e) {
             out = { error: e instanceof SsrfBlockedError ? 'E_CIMD_SSRF_BLOCKED' : 'E_CIMD_INVALID' };
-            // A document that went bad is never served stale. An issuer that is down
-            // or overloaded says nothing about the document, so the last good one
-            // stays and answers this fetch's requests too (stale-if-error; the error
-            // itself is never stored).
+            // 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 };
-            // #13: the detail goes to the log only; the caller gets a generic answer.
+            // 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 {

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/compose.d.ts

@@ -1,8 +1,15 @@
-import type { McpServer } from "@modelcontextprotocol/server";
+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

package/dist/compose.js

@@ -1,8 +1,6 @@
-// S1.12: registry composition, extracted from index.ts so the tenancy module
-// (and tests) can build registries without touching the CLI entrypoint. This
-// module must stay free of import-time side effects of its own: no argv
-// parsing, no process.exit, no prints (accounts.js module-load resolution is
-// the one inherited, pre-existing exception on the import chain).
+// Registry composition, extracted from index.ts so tests can build registries
+// without touching the CLI entrypoint. No import-time side effects of its own.
+import { McpServer } from "@modelcontextprotocol/server";
 import { GENERATED_SERVICES } from './tools/generated/index.js';
 import { GENERATED_GATES, SERVICES, servicesAwaitingRestart, unknownToolMessage } from './services.js';
 import { argNormalizationEnabled } from './arg-normalize.js';
@@ -16,15 +14,17 @@ import { registerAccountWizardTools } from './tools/account-wizard.js';
 import { getToolsets, toolsetEnabled } from './toolsets.js';
 import { isOwnerContext } from './identity.js';
 import { resolveScopesForAccount } from './auth.js';
+/** The one place the MCP server is constructed, so an embedding host can pass
+ * per-session `instructions` without re-deriving the server identity. */
+export function createMcpServer(version, opts = {}) {
+    const instructions = opts.instructions?.trim() ? opts.instructions : undefined;
+    return new McpServer({ name: 'mcp-google-multi', version }, instructions ? { instructions } : undefined);
+}
 export function buildRegistry(server, ctx, mode, metrics = null) {
     const policy = ctx.policy;
-    // The registry's account view IS the context's: fan-out expansion,
-    // selector validation and default-account injection all follow this
-    // context, not the process global (identical for the free core's one ctx).
+    // The registry's account view IS the context's, not the process global.
     const registry = new ToolRegistry(server, policy, mode, metrics, () => ctx.accounts);
-    // Every handler resolves its client, token reads and scope hints through
-    // this context; ctx.accounts is read per call, never snapshotted here, so
-    // the owner's live getter stays live.
+    // ctx.accounts is read per call, never snapshotted here, so a live getter stays live.
     const owner = isOwnerContext(ctx);
     const clientDeps = { getClientFn: ctx.getClient, localFiles: owner };
     const execDeps = {