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

package/dist/hint-provider.js

@@ -1,9 +1,5 @@
-// A plain array literal, not derived from the union: deriving it would need a
-// value-level mirror of the type anyway, and this way a missing member is
-// caught by the completeness check below instead of silently compiling.
-// `as const` so that check narrows to the literal tuple rather than widening
-// every element back to the whole HintCase['kind'] union (which would make
-// it pass trivially, whatever was listed).
+// A plain array literal, not derived from the union, so a missing member is
+// caught by the completeness check below rather than silently compiling.
 export const HINT_KINDS = [
     'reauth',
     'legacy_plaintext_token',
@@ -43,10 +39,8 @@ let installed = null;
 export function setHintProvider(p) {
     installed = p;
 }
-// A throwing provider must never take down the call site: every call site
-// does `hints()?.render(...)?.hint ?? <default>`, so a render that cannot
-// produce a Rendered falls back to the same literal a missing provider
-// would, and the provider's own error text never reaches a client.
+// A throwing provider must never take down the call site: it falls back to
+// the same literal a missing provider would, never leaking its own error text.
 export function hints() {
     if (!installed)
         return null;

package/dist/http-config.d.ts

@@ -11,7 +11,7 @@ export interface HttpConfig {
     transport: Transport;
     host: string;
     port: number;
-    /** Canonical public base URL (BR4): lowercase scheme+host, no default port,
+    /** Canonical public base URL: lowercase scheme+host, no default port,
      *  no trailing slash, no fragment/query. The issuer and every advertised
      *  endpoint derive from this. */
     publicUrl: string;
@@ -27,7 +27,7 @@ export interface HttpConfig {
 export declare function transportIncludesHttp(t: Transport): boolean;
 export declare function resolveTransport(env?: NodeJS.ProcessEnv): Transport;
 /**
- * Canonicalize a public base URL per BR4. WHATWG `URL` already lowercases the
+ * Canonicalize a public base URL. WHATWG `URL` already lowercases the
  * scheme+host and omits a default port from `.host`; this adds the HTTPS-only
  * scheme check, strips fragment/query/userinfo, and removes a trailing slash.
  */

package/dist/http-config.js

@@ -1,9 +1,5 @@
-// Transport selection + public-base-URL / Origin / host config plumbing (B11).
-// Pure, resolved once at boot; the HTTP host that consumes this lands in B12
-// (cc-transport-hosting) and the AS metadata in B13 (oauth-authorization-server).
-// Owns the canonicalization rule (cc-transport-hosting BR4): a single mismatch
-// between the advertised resource URI and the client's `resource`/`aud` = a
-// perpetual 401 loop (the #1 interop bug), so it is normalized exactly once.
+// Transport + public-base-URL / Origin / host config, pure and resolved once
+// at boot. A mismatch between the advertised URI and the client's `aud` is a perpetual 401 loop.
 export const DEFAULT_HTTP_HOST = '127.0.0.1';
 export const DEFAULT_HTTP_PORT = 4243;
 export const CLAUDE_AI_ORIGIN = 'https://claude.ai';
@@ -30,7 +26,7 @@ export function resolveTransport(env = process.env) {
     throw new HttpConfigError('E_INVALID_TRANSPORT', `MCP_TRANSPORT must be one of stdio|http|both (got "${env.MCP_TRANSPORT}")`);
 }
 /**
- * Canonicalize a public base URL per BR4. WHATWG `URL` already lowercases the
+ * Canonicalize a public base URL. WHATWG `URL` already lowercases the
  * scheme+host and omits a default port from `.host`; this adds the HTTPS-only
  * scheme check, strips fragment/query/userinfo, and removes a trailing slash.
  */

package/dist/http-transport.d.ts

@@ -12,9 +12,9 @@ export type AuthOutcome = {
     body: string;
     headers?: Record<string, string>;
 };
-/** Bearer / owner check for POST /mcp. B12 default = loopback-owner; B13 swaps in JWT verify. */
+/** Bearer / owner check for POST /mcp. Default = loopback-owner; the AS swaps in JWT verify. */
 export type Authenticator = (req: IncomingMessage) => AuthOutcome | Promise<AuthOutcome>;
-/** A mounted extra route (the AS endpoints, B13). Return true if it wrote a response. */
+/** A mounted extra route (the AS endpoints). Return true if it wrote a response. */
 export type RouteHandler = (req: IncomingMessage, res: ServerResponse, url: URL) => boolean | Promise<boolean>;
 /** What a verified subject resolves to: ITS server plus the per-request hooks
  * bound to that server's registry (tool shapes, declared keys, the default
@@ -27,7 +27,7 @@ export interface ServerTarget {
     validationEnvelope?: ValidationEnvelopeOptions;
 }
 export interface HttpHostOptions {
-    /** The ONE McpServer + registry built at boot (P1 / BV gap #4: never per request). */
+    /** The ONE McpServer + registry built at boot (never per request). */
     server: McpServer;
     config: HttpConfig;
     version: string;
@@ -53,7 +53,7 @@ export interface HttpHostOptions {
             message: string;
         };
     };
-    /** Extra routes keyed by exact pathname (AS endpoints mount here in B13). */
+    /** Extra routes keyed by exact pathname (AS endpoints mount here). */
     routes?: Record<string, RouteHandler>;
     log?: (line: string) => void;
     /** Max /mcp JSON body bytes (DoS guard). */
@@ -81,7 +81,7 @@ export interface HttpHostOptions {
 export declare function parseOwnerEmails(env?: NodeJS.ProcessEnv): string[];
 /** Front guard: an Origin, if present, must be allowlisted; a Host must be
  * allowlisted. Absent Origin passes (native/CLI/backend clients — the claude.ai
- * connector calls /mcp server-to-server with no Origin, BV-4). */
+ * connector calls /mcp server-to-server with no Origin). */
 export declare function originAllowed(origin: string | undefined, allowed: string[]): boolean;
 export declare function hostAllowed(host: string | undefined, allowed: string[]): boolean;
 /** JSON-RPC method name(s) for an observability log line: no params, no PII.

package/dist/http-transport.js

@@ -1,30 +1,21 @@
 import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/node";
-// node:http server, the route table, the front guard (Host / Origin / DNS-rebind),
-// and the stateless per-request /mcp dispatch. The OAuth AS endpoints and Bearer
-// verification are a seam filled by B13 (oauth-authorization-server); B12 ships a
-// loopback-owner authenticator so the local-HTTP model works before the AS lands.
 import { createServer } from 'node:http';
 import { withArgNormalization, withValidationEnvelope } from './arg-normalize.js';
 import { logSafe } from './trim.js';
 // A host wrapping the log callbacks it hands core needs this, and trim has no package export.
 export { logSafe } from './trim.js';
 // A hung handler that keeps the connection open would otherwise hold the global
-// serialize() lock forever. Generous by default so slow-but-valid calls (large
-// Drive exports, fan-out) still finish; the point is only to guarantee release.
+// serialize() lock forever; generous by default so slow-but-valid calls still finish.
 const DISPATCH_TIMEOUT_DEFAULT = 120_000;
-/** MCP 2025-06-18 dropped JSON-RPC batching, and the SDK screens every frame
- * of a batch synchronously in one tick: without a cap one body multiplies the
- * per-call work by however many frames fit in it. */
+// Without a cap, one body multiplies per-call work by however many
+// JSON-RPC frames the SDK's synchronous batch screening finds in it.
 const MAX_BATCH_FRAMES = 16;
-// A resolveServer refusal's body reaches the wire verbatim (H3 PR1): validated
-// so a host cannot accidentally leak an operator path/env var through a wrongly
-// shaped slug or an overlong message. No new slug literal enters core itself —
-// the slug is always the host's own value.
+// A refusal's body reaches the wire verbatim, so it's validated: no new slug
+// literal enters core, and an overlong message can't leak an operator path/env var.
 const REFUSAL_SLUG_RE = /^[a-z][a-z0-9_]{0,39}$/;
 const MAX_REFUSAL_MESSAGE_CHARS = 300;
-// C0/C1 controls, format chars (includes bidi overrides like U+202E and
-// zero-width joiners) and the line/paragraph separators; ordinary non-ASCII
-// letters stay allowed.
+// C0/C1 controls, format chars (bidi overrides, zero-width joiners) and
+// line/paragraph separators; ordinary non-ASCII letters stay allowed.
 const NON_PRINTABLE_RE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
 function isValidRefusal(r) {
     return (typeof r.error === 'string' &&
@@ -42,7 +33,7 @@ export function parseOwnerEmails(env = process.env) {
 }
 /** Front guard: an Origin, if present, must be allowlisted; a Host must be
  * allowlisted. Absent Origin passes (native/CLI/backend clients — the claude.ai
- * connector calls /mcp server-to-server with no Origin, BV-4). */
+ * connector calls /mcp server-to-server with no Origin). */
 export function originAllowed(origin, allowed) {
     if (!origin)
         return true;
@@ -81,25 +72,17 @@ export function jsonRpcMethod(body) {
 /** setTimeout fires at once for a delay above this, so a longer grace would
  * cut every connection immediately. */
 const MAX_GRACE_MS = 2 ** 31 - 1;
-// A lingering close: a socket destroyed while its client is still sending (a
-// body pipelined after the close) is reset by the kernel, which drops whatever
-// of the last response is still unsent. So the socket only ends its side and
-// waits for the client's FIN, or for the grace to end.
+// A lingering close (ends the socket, never destroys it); see docs/internals.md (Graceful close).
 function endAfterFlush(socket) {
     if (socket.destroyed || socket.writableEnded)
         return;
-    // Node arms a keep-alive timer when a response finishes and destroys the
-    // socket when it fires, which would cut a slow reader's unread tail just as
-    // an early destroy does. Only the client's FIN or the grace ends it now.
+    // Disarm the keep-alive timer Node arms on finish, or it destroys the
+    // socket ~6s later and cuts a slow reader's unread tail the same way an early destroy does.
     socket.setTimeout(0);
     socket.end();
 }
-// A request that arrives while closing is never answered, so Node keeps it
-// until the socket closes, and a flood pipelined behind a held response would
-// pile up without limit. Reading stops for good instead, which lets TCP flow
-// control stop the client. Node resumes a socket after every parsed request
-// and on drain, so resume becomes a no-op. Such a socket never sees the
-// client's FIN either: the grace ends it.
+// Stops reading for good so TCP flow control stops the client, instead of
+// piling up a flood pipelined behind a held response; see docs/internals.md (Graceful close).
 function stopReading(socket) {
     socket.pause();
     socket.resume = () => socket;
@@ -117,18 +100,12 @@ function pathOf(req) {
 export class HttpTransportHost {
     opts;
     httpServer;
-    // Serialize the connect→dispatch critical section PER SERVER: a McpServer
-    // captures its transport per request (protocol.js), but the gap between
-    // connect() and the dispatch capturing it would still race under true
-    // concurrency, so all traffic to ONE server runs under one mutex. The free
-    // core has one lane (the boot server); with resolveServer each resolved
-    // server gets its own, however subjects map onto servers.
+    // Per-server dispatch mutex; see docs/internals.md.
     locks = new Map();
     // Requests holding a lane slot, per server; used only with maxQueuedPerLane.
     depth = new Map();
-    // What a graceful close waits on: open sockets, per socket the requests it
-    // has accepted whose response has not settled and the last of them, and
-    // every handle() that has not settled.
+    // What a graceful close waits on: open sockets and every handle() not yet
+    // settled; see docs/internals.md (Graceful close).
     sockets = new Set();
     pending = new Map();
     // Sockets that have accepted a request: nothing pending means the last
@@ -145,9 +122,8 @@ export class HttpTransportHost {
         const run = prev.then(fn, fn);
         const tail = run.then(() => undefined, () => undefined);
         this.locks.set(key, tail);
-        // An idle lane drops out, so the map holds only in-flight subjects rather
-        // than every subject ever seen. A request that chained on this tail has
-        // already replaced it, so the identity check never frees a live lane.
+        // An idle lane drops out of the map; the identity check below skips a
+        // later request that already replaced this tail, so it never frees a live lane.
         void tail.then(() => {
             if (this.locks.get(key) === tail)
                 this.locks.delete(key);
@@ -161,9 +137,8 @@ export class HttpTransportHost {
         const { config } = this.opts;
         const server = createServer((req, res) => {
             const socket = req.socket;
-            // Once closing, a connection ends after the last request it accepted
-            // before the close, so one arriving now is never handled (RFC 9112 9.6).
-            // Its body is left unread: nothing reads the socket again.
+            // Once closing, a request arriving now is never handled (RFC 9112 §9.6)
+            // and its body is left unread.
             if (this.closing) {
                 stopReading(socket);
                 return;
@@ -190,10 +165,8 @@ export class HttpTransportHost {
             };
             res.once('finish', settle);
             res.once('close', settle);
-            // Never rejects: close() waits on it, and a catch-all that itself threw
-            // must neither reject close() nor surface as an unhandled rejection.
-            // The thrown message can name server paths (a lock timeout does), so it
-            // goes only to the host's log.
+            // Never rejects (close() waits on it); the thrown message can name
+            // server paths, so it goes only to the host's log.
             const done = this.handle(req, res)
                 .catch((e) => {
                 try {
@@ -265,20 +238,13 @@ export class HttpTransportHost {
     }
     async closeGracefully(s, graceMs) {
         this.closing = true;
-        // Node's close() also destroys every connection it deems idle, and that
-        // includes one whose response has ended but is still flushing: a large
-        // body would be cut short. Idle sockets are closed below instead.
+        // Node's close() also destroys idle connections, which would cut short a
+        // large response still flushing; idle sockets are closed below instead.
         const nodeIdleCloser = s.closeIdleConnections;
         s.closeIdleConnections = () => undefined;
         const closed = new Promise((resolve) => s.close(() => resolve()));
         s.closeIdleConnections = nodeIdleCloser;
-        // Every request accepted before now is answered, and a connection ends
-        // after the last of them: that one says so if it has not started, and the
-        // settle hook in start() ends the socket once it finishes. Node itself
-        // destroys a socket once a Connection: close response is flushed, which
-        // resets it just as endAfterFlush explains, so that end lingers too. A
-        // socket with nothing pending may still be delivering the tail of its
-        // last response, so only one that never accepted a request is destroyed.
+        // Socket bookkeeping below; see docs/internals.md (Graceful close).
         for (const socket of this.sockets) {
             const entry = this.pending.get(socket);
             if (!entry && !this.served.has(socket)) {
@@ -357,10 +323,7 @@ export class HttpTransportHost {
         }
         if (!this.frontGuard(req, res))
             return;
-        // Registered before anything awaits: a client that leaves while its request
-        // waits on the lane must not have it dispatched once its turn comes. A
-        // response queued behind another on its connection never emits 'close', so
-        // the socket is checked too.
+        // Registered before anything awaits (client-gone skip); see docs/internals.md.
         let gone = false;
         res.once('close', () => (gone = true));
         const socket = req.socket;
@@ -375,8 +338,8 @@ export class HttpTransportHost {
             return;
         }
         const sub = auth.sub ?? 'owner';
-        // Tenant resolution (the seam EE fills): map the verified subject to ITS
-        // server. Absent resolver = the one boot server for every subject.
+        // Tenant resolution (a multi-tenant host fills this seam): map the
+        // verified subject to ITS server. Absent resolver = the one boot server for every subject.
         let target = {
             server: this.opts.server,
             argShapeFor: this.opts.argShapeFor,
@@ -400,8 +363,7 @@ export class HttpTransportHost {
                     return;
                 }
                 // An invalid shape falls through to today's exact answer rather than
-                // forwarding something unvalidated; a refusal never reaches dispatch
-                // either way.
+                // forwarding something unvalidated.
                 resolved = null;
             }
             target = resolved;
@@ -437,9 +399,8 @@ export class HttpTransportHost {
         }
     }
     async admitted(req, res, target, sub, clientGone) {
-        // Thread the verified subject to tool handlers: the Node transport forwards
-        // req.auth verbatim as ctx.http.authInfo. Token/clientId stay empty — the
-        // bearer value must not re-enter the dispatch path via handler context.
+        // Thread the verified subject to tool handlers via ctx.http.authInfo;
+        // token/clientId stay empty so the bearer value never re-enters the dispatch path.
         req.auth = {
             token: '',
             clientId: '',
@@ -457,28 +418,16 @@ export class HttpTransportHost {
         if (Array.isArray(body) && body.length > maxFrames) {
             return this.fail(res, 400, 'batch_too_large', `a JSON-RPC batch may hold at most ${maxFrames} messages`);
         }
-        // Host/Origin are enforced by the front guard above (uniformly for /mcp and
-        // the mounted AS routes), so the SDK's own DNS-rebind guard is disabled: its
-        // exact-Host match is stricter than the front guard and would 403 valid
-        // Hosts (double enforcement, differing rules).
+        // The SDK's own DNS-rebind guard is disabled: Host/Origin are already
+        // enforced above, and its stricter exact-Host match would 403 valid Hosts.
         const transport = new NodeStreamableHTTPServerTransport({
             sessionIdGenerator: undefined,
             enableJsonResponse: true,
             enableDnsRebindingProtection: false,
         });
-        // The shared McpServer holds exactly one connected transport at a time, so
-        // connect + dispatch + DISCONNECT all run inside the mutex: the next request
-        // can never hit "Already connected". The serialized section is guaranteed to
-        // settle three ways — the handler finishes, the client disconnects (res
-        // 'close'), or a dispatch deadline fires — so neither a client that holds the
-        // connection open nor a hung upstream can wedge the lock. The transport is
-        // closed in a finally (which resets server._transport) before the lock
-        // releases. (A shared initialized-state persists across stateless requests;
-        // benign for the single-owner design.)
+        // connect + dispatch + disconnect run inside the per-server mutex, keyed
+        // on the server identity, never the subject; see docs/internals.md.
         const deadlineMs = this.opts.dispatchTimeoutMs ?? DISPATCH_TIMEOUT_DEFAULT;
-        // The lock lane is the SERVER identity, never the subject: two subjects
-        // reaching one server (the boot server, or a resolver mapping several
-        // subjects to one) would otherwise race it through the connect gap.
         const { server: mcpServer, argShapeFor, strictArgs, validationEnvelope } = target;
         await this.serializeFor(mcpServer, async () => {
             if (clientGone()) {
@@ -491,16 +440,14 @@ export class HttpTransportHost {
                 timer = setTimeout(() => resolve('timeout'), deadlineMs);
                 timer.unref?.();
             });
-            // Same composition as the stdio leg: the envelope rewrite is innermost,
-            // so the tap above it still classifies the original validation prose.
+            // Envelope rewrite innermost, as on stdio; see docs/internals.md (Argument normalization).
             const enveloped = withValidationEnvelope(transport, validationEnvelope ?? {});
             const tapped = this.opts.metricsTap ? this.opts.metricsTap(enveloped) : enveloped;
             await mcpServer.connect(argShapeFor || strictArgs
                 ? withArgNormalization(tapped, argShapeFor ?? (() => undefined), this.opts.log, this.opts.onArgRename, strictArgs)
                 : tapped);
-            // Reflect the dispatch into a non-rejecting arm: if the deadline wins the
-            // race, an orphaned handler settling later must not surface as an unhandled
-            // rejection — but a genuine dispatch error still propagates (rethrown below).
+            // Non-rejecting arm: an orphaned handler settling after the deadline wins
+            // must not surface as an unhandled rejection; a real error is rethrown below.
             let dispatchErr;
             const dispatchArm = transport
                 .handleRequest(req, res, body)
@@ -538,7 +485,7 @@ export class HttpTransportHost {
     health(res) {
         const { config, ownerConfigured, version } = this.opts;
         res.writeHead(200, { 'Content-Type': 'application/json' });
-        // No secrets, no owner emails (cc-transport-hosting /health rule).
+        // No secrets, no owner emails.
         res.end(JSON.stringify({
             status: 'ok',
             transport: config.transport,

package/dist/identity.d.ts

@@ -4,8 +4,8 @@ import { hasToken, readToken, updateToken, writeToken } from './token-store.js';
 import { type Policy, type Transport } from './write-control.js';
 /**
  * The one forward-compat seam (frozen public API): the free core builds
- * exactly one context with subject "owner"; EE later instantiates N contexts
- * from N registries. Nothing here may assume a global current-account.
+ * exactly one context with subject "owner"; a multi-tenant host instantiates
+ * N contexts from N registries. Nothing here may assume a global current-account.
  * `subject` is a string (not the literal 'owner') so a context can carry a
  * tenant id; the free core still always builds 'owner'.
  */

package/dist/identity.js

@@ -2,18 +2,15 @@ import { getAccountSet, getTokenDir, refreshAccountSetIfStale } from './accounts
 import { makeGetClient } from './client.js';
 import { createTokenStore } from './token-store.js';
 import { resolvePolicy } from './write-control.js';
-// Only buildIdentityContext mints the owner brand. The subject string alone
-// never unlocks the owner-only surfaces (account wizard, host-file tools, the
-// operator diagnose report): a hand-built context claiming 'owner' stays a
-// non-owner context.
+// Only buildIdentityContext mints the owner brand: the subject string alone
+// never unlocks owner-only surfaces, so a hand-built context claiming 'owner' stays non-owner.
 const ownerContexts = new WeakSet();
 export function isOwnerContext(ctx) {
     return ctx !== undefined && ownerContexts.has(ctx);
 }
 export function buildIdentityContext(env = process.env, opts = {}) {
-    // Real closures over the single-owner state (the SAME factories EE
-    // instantiates per tenant), bound here to the global registry + token dir —
-    // behavior-identical to the module-level functions for the free core.
+    // The SAME factories a multi-tenant host instantiates per tenant, bound here
+    // to the global registry + token dir.
     const tokenStore = createTokenStore(getTokenDir());
     const ctx = {
         subject: 'owner',
@@ -22,8 +19,8 @@ export function buildIdentityContext(env = process.env, opts = {}) {
         get accounts() {
             return getAccountSet();
         },
-        // The dispatch transport rides into the resolved policy as a reserved seam
-        // (cc-write-control B14); it does not change any write-control verdict.
+        // The dispatch transport rides into the resolved policy as a reserved seam;
+        // it does not change any write-control verdict.
         policy: resolvePolicy(env, { transport: opts.transport }),
         getClient: makeGetClient('owner', {
             accounts: getAccountSet,

package/dist/index.js

@@ -1,17 +1,16 @@
 #!/usr/bin/env node
 // First import: triggers accounts.js module load (env files + registry) before
-// anything else. Named to also pull the server-only empty-registry guard (BR-4).
+// anything else. Named to also pull the server-only empty-registry guard.
 import { assertServerAccountsConfigured } from './accounts.js';
 import { accountsAssertRequired, assertNoEnvAccountsMode, assertNoEnvOptionalScopesMode, isMultiTenantBoot, mtBootGates } from './boot-gates.js';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
-import { McpServer } from "@modelcontextprotocol/server";
 import { resolveDiscoveryMode } from './registry.js';
 import { isAllowed, describePolicy } from './write-control.js';
 import { buildIdentityContext } from './identity.js';
-import { buildRegistry, requestHooksFor } from './compose.js';
+import { buildRegistry, createMcpServer, requestHooksFor } from './compose.js';
 import { registerSetupPrompt } from './setup-prompt.js';
 import { applyNetTuning } from './net-tuning.js';
 import { withArgNormalization, withValidationEnvelope } from './arg-normalize.js';
@@ -81,7 +80,7 @@ async function main() {
     if (process.argv.includes('config') && process.argv.includes('check')) {
         const ctx = buildIdentityContext();
         const policy = ctx.policy;
-        const registry = buildRegistry(new McpServer({ name: 'mcp-google-multi', version: pkg.version }), ctx);
+        const registry = buildRegistry(createMcpServer(pkg.version), ctx);
         const cud = registry.tools.filter((t) => t.cud !== 'read');
         const disabled = cud.filter((t) => !isAllowed(t, policy));
         const counts = registry.visibleCount();
@@ -140,10 +139,8 @@ async function main() {
     }
     const wantStdio = httpCfg.transport === 'stdio' || httpCfg.transport === 'both';
     const wantHttp = transportIncludesHttp(httpCfg.transport);
-    // BR-4: the SERVER never boots with an empty registry — stdio always, HTTP
-    // when single-owner. The bootstrap and diagnostic CLIs above already
-    // returned. A multi-tenant boot instead refuses the two process-wide env
-    // vectors that would leak one operator's accounts/scopes into every tenant.
+    // The SERVER never boots with an empty registry (stdio always, HTTP when
+    // single-owner); a multi-tenant boot instead refuses the two process-wide env vectors.
     const mt = isMultiTenantBoot();
     if (accountsAssertRequired(wantStdio, mt))
         assertServerAccountsConfigured();
@@ -155,9 +152,7 @@ async function main() {
     // specced "fatal at startup", never mid-dispatch.
     const { resolveMasterKey } = await import('./master-key.js');
     resolveMasterKey();
-    // Local usage metrics: fail-closed resolve, self-announcing source, null
-    // when off (no wrapper, no dir, nothing initializes). One instance per
-    // transport so `boots` keys stay honest under `both`.
+    // One Metrics instance per transport so `boots` keys stay honest under `both`.
     const envSrc = envValueSource('GOOGLE_USAGE_METRICS');
     const metricsState = resolveUsageMetrics(process.env, loadConfigFile()?.usageMetrics, envSrc?.kind === 'file' ? envSrc.file : undefined);
     if (metricsState.warning)
@@ -187,21 +182,17 @@ async function main() {
             });
         }
     }
-    // Build one McpServer + registry per transport at boot (P1 / BV gap #4:
-    // never rebuilt per request); `both` runs the two concurrently.
+    // Build one McpServer + registry per transport at boot (never
+    // rebuilt per request); `both` runs the two concurrently.
     if (wantStdio) {
-        const server = new McpServer({ name: 'mcp-google-multi', version: pkg.version });
+        const server = createMcpServer(pkg.version);
         const stdioMetrics = initMetricsFor('stdio', resolveDiscoveryMode());
         const stdioCtx = buildIdentityContext(process.env, { transport: 'stdio' });
         const registry = buildRegistry(server, stdioCtx, undefined, stdioMetrics);
         registry.installListHandler();
         registerSetupPrompt(server);
         const stdioHooks = requestHooksFor(registry, stdioCtx, stdioMetrics);
-        // Outbound runs outermost-first, so the composition is deliberate: the
-        // envelope rewrite is INNERMOST (last to touch the frame), the tap sits
-        // above it (classifying the ORIGINAL validation prose), arg normalization
-        // outermost. The tap only counts outbound JSON-RPC error frames (no
-        // handler ran) plus id->tool names.
+        // Composition order (outbound runs outermost-first): see docs/internals.md (Argument normalization).
         let transport = withValidationEnvelope(new StdioServerTransport(), stdioHooks.validationEnvelope);
         if (stdioMetrics) {
             const { tapUsageMetrics } = await import('./metrics-tap.js');
@@ -209,10 +200,8 @@ async function main() {
         }
         await server.connect(stdioHooks.argShapeFor || stdioHooks.strictArgs
             ? withArgNormalization(transport, 
-            // Gated exactly as the HTTP leg gates `argShapeFor`. Passing the
-            // shape unconditionally made stdio rename keys while
-            // GOOGLE_ARG_NORMALIZE=off, so the same call succeeded on stdio
-            // and failed on HTTP once screening rejects.
+            // Gated exactly as the HTTP leg gates argShapeFor, or GOOGLE_ARG_NORMALIZE=off
+            // would rename keys on stdio while HTTP's screening rejects the same call.
             stdioHooks.argShapeFor ?? (() => undefined), undefined, stdioMetrics ? (tool, n) => stdioMetrics.recordArgFix(tool, n) : undefined, stdioHooks.strictArgs)
             : transport);
     }
@@ -221,31 +210,30 @@ async function main() {
         const owners = parseOwnerEmails(process.env);
         const gates = mtBootGates();
         if (gates?.multiTenant) {
-            // Same fail-fast SHAPE, different condition: an ungated HTTP endpoint
-            // must never boot; under tenancy the gate is "a valid provisioning
+            // Same fail-fast shape as below, but the gate is "a valid provisioning
             // mechanism exists", not a flat owner allowlist.
             gates.assertProvisioningGate();
         }
         else {
-            // BR3 / C13: the owner allowlist is the entire multi-tenant collapse;
+            // The owner allowlist is the entire multi-tenant collapse;
             // refuse to open an ungated HTTP endpoint.
             if (owners.length === 0) {
                 process.stderr.write('E_OWNER_EMAILS_REQUIRED: MCP_TRANSPORT includes http but MCP_OWNER_EMAILS is empty. Set MCP_OWNER_EMAILS to the Google email(s) allowed to authenticate.\n');
                 process.exit(1);
             }
         }
-        // BR7: stateless HTTP cannot push tools/list_changed, so it forces curated.
+        // Stateless HTTP cannot push tools/list_changed, so it forces curated.
         const configuredMode = (process.env.GOOGLE_DISCOVERY ?? '').trim().toLowerCase();
         if (configuredMode && configuredMode !== 'curated') {
             process.stderr.write(`GOOGLE_DISCOVERY="${configuredMode}" is ignored over HTTP; the stateless transport forces "curated".\n`);
         }
-        const httpServer = new McpServer({ name: 'mcp-google-multi', version: pkg.version });
+        const httpServer = createMcpServer(pkg.version);
         const httpMetrics = initMetricsFor('http', 'curated');
         const httpCtx = buildIdentityContext(process.env, { transport: 'http' });
         const registry = buildRegistry(httpServer, httpCtx, 'curated', httpMetrics);
         registry.installListHandler();
         registerSetupPrompt(httpServer);
-        // B13: mount the OAuth 2.1 AS (legs A + B) + the Bearer authenticator.
+        // Mount the OAuth 2.1 AS (MCP-client tokens + owner login) + the Bearer authenticator.
         const { buildAuthServer, verifiedEmailFromIdToken } = await import('./oauth-as.js');
         const { jwtSecretFrom } = await import('./mcp-token.js');
         const { resolveJwtKey, resolveMasterKeyForDispatch } = await import('./master-key.js');
@@ -288,7 +276,7 @@ async function main() {
             aliasEmail: (alias) => getAccountSet().configs[alias]?.email,
             log: (l) => process.stderr.write(`[as] ${l}\n`),
         });
-        // BV-1: over HTTP, a dead/missing per-account token surfaces a clickable,
+        // Over HTTP, a dead/missing per-account token surfaces a clickable,
         // signed re-auth link into the AS's alias_reauth flow instead of a CLI hint.
         const { setHttpReauthLink } = await import('./reauth-hint.js');
         setHttpReauthLink((alias) => authServer.reauthLink(alias));
@@ -314,7 +302,7 @@ async function main() {
         });
         await host.start();
         process.stderr.write(`HTTP transport listening on http://${httpCfg.host}:${httpCfg.port} (public ${httpCfg.publicUrl})\n`);
-        // Graceful shutdown so `docker run --init` (B16) forwards SIGTERM cleanly.
+        // Graceful shutdown so `docker run --init` forwards SIGTERM cleanly.
         const shutdown = () => {
             host.close().finally(() => process.exit(0));
         };

package/dist/master-key.d.ts

@@ -15,7 +15,7 @@ export interface KeyDeps {
     hasAnyToken?: () => boolean;
 }
 export declare function __setKeychainFactoryForTest(fn: ((account: string) => KeychainEntry | null) | null): void;
-/** BR-1 single choke point: no other module may read the env vars directly.
+/** Single choke point: no other module may read the env vars directly.
  * Boot/CLI form: failures exit with a clean stderr slug ("fatal at startup"). */
 export declare function resolveMasterKey(deps?: KeyDeps): ResolvedKey;
 /** Dispatch form: identical resolution, but failures THROW (caught by the tool
@@ -28,14 +28,14 @@ export declare function peekMasterKeyProvenance(deps?: KeyDeps): KeyProvenance |
  * outstanding MCP tokens and clients re-auth silently. */
 export declare function resolveJwtKey(deps?: KeyDeps): ResolvedKey;
 /**
- * BR-5: after the FIRST successful token decrypt with an env-sourced key,
+ * After the FIRST successful token decrypt with an env-sourced key,
  * mirror it into the keychain (only when the keychain holds no entry) so the
  * key survives an env loss. Gating on a successful decrypt means a stale or
  * wrong env key is never mirrored. Best-effort: failures are doctor material,
  * never fatal.
  */
 export declare function noteSuccessfulDecrypt(): void;
-/** B6 reset: drop the generated MASTER_KEY material (0600 file + keychain
+/** Reset: drop the generated MASTER_KEY material (0600 file + keychain
  * entry) so the next run re-provisions. Never removes an env-provided key (the
  * deployer owns that; `env:true` flags it so reset can warn). The caller MUST
  * have wiped every .enc token first — regenerating with tokens present would