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

package/dist/env-load.js

@@ -0,0 +1,52 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Precedence: real env > CWD .env > package-root .env > ~/.config .env.
+// process.loadEnvFile never overwrites keys already in process.env (pinned by
+// tests/env-load.test.ts T4), so highest-priority file loads FIRST and real
+// env wins by already being present; the boot snapshot re-assert is a second
+// line of defense should those semantics ever change.
+export function loadEnvFiles(paths = {}) {
+    // loadEnvFile exists since 20.12, so a feature check alone would let 20.12-21.x through.
+    const major = Number(process.versions.node.split('.', 1)[0]);
+    if (major < 22 || typeof process.loadEnvFile !== 'function') {
+        process.stderr.write(`E_NODE_TOO_OLD: mcp-google-multi requires Node.js >= 22 (running ${process.versions.node}). Upgrade to Node 22 LTS or newer.\n`);
+        process.exit(1);
+    }
+    const configDir = paths.configDir ??
+        path.join(process.env.XDG_CONFIG_HOME || path.join(homedir(), '.config'), 'mcp-google-multi');
+    const explicit = process.env.MCP_GOOGLE_MULTI_ENV;
+    const candidates = explicit
+        ? [path.resolve(explicit)]
+        : [
+            path.join(paths.cwd ?? process.cwd(), '.env'),
+            path.join(paths.packageRoot ?? path.resolve(__dirname, '..'), '.env'),
+            path.join(configDir, '.env'),
+        ];
+    const boot = new Map(Object.entries(process.env).filter((e) => e[1] !== undefined));
+    const loaded = [];
+    for (const p of candidates) {
+        try {
+            process.loadEnvFile(p);
+            loaded.push(p);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT') {
+                // Node collapses every open()-stage failure (EACCES, ENOTDIR, ...) into
+                // ENOENT, so stat to tell "absent" from "present but unreadable".
+                if (explicit) {
+                    const reason = existsSync(p) ? 'exists but is not readable' : 'does not exist';
+                    process.stderr.write(`E_ENV_NOT_FOUND: MCP_GOOGLE_MULTI_ENV points to "${p}" but the file ${reason}.\n`);
+                    process.exit(1);
+                }
+                continue;
+            }
+            throw e;
+        }
+    }
+    for (const [k, v] of boot)
+        process.env[k] = v;
+    return { loaded, searched: candidates };
+}

package/dist/executor.d.ts

@@ -8,6 +8,8 @@ export interface ApiMethodRef {
     path: string;
     baseUrl: string;
     requiredParams: string[];
+    /** Escape hatch: from runtime Discovery. Generated tools: baked at gen time. */
+    scopes?: readonly string[];
 }
 export interface ExecuteDeps {
     getClientFn?: typeof getClient;

package/dist/executor.js

@@ -1,6 +1,7 @@
 import { getClient } from './client.js';
 import { expandPath, isGoogleApiUrl } from './discovery-client.js';
 import { handleGoogleApiError } from './tools/_errors.js';
+import { scopeHintForMethod } from './scope-observability.js';
 export const MAX_RESPONSE_CHARS = 100_000;
 export function jsonResult(payload, isError = false) {
     const base = { content: [{ type: 'text', text: JSON.stringify(payload) }] };
@@ -91,6 +92,6 @@ export async function executeApiMethod(method, args, deps = {}) {
         return { content: [{ type: 'text', text }] };
     }
     catch (error) {
-        return handleGoogleApiError(error, args.account);
+        return handleGoogleApiError(error, args.account, undefined, () => method.scopes?.length ? scopeHintForMethod(method.scopes, args.account) : null);
     }
 }

package/dist/fanout.js

@@ -1,14 +1,17 @@
 import { z } from 'zod';
-import { ACCOUNTS } from './accounts.js';
+import { ACCOUNTS, getAccountSet } from './accounts.js';
 export const CSV_RE = /^[a-zA-Z0-9_-]+(\s*,\s*[a-zA-Z0-9_-]+)+$/;
 const FANOUT_CONCURRENCY = 5;
 export function fanoutAccountField(description) {
     const csvExample = ACCOUNTS.length > 1 ? `; or a CSV subset like "${ACCOUNTS.slice(0, 2).join(',')}"` : '';
     return z
-        .union([z.enum([...ACCOUNTS, '*']), z.string().regex(CSV_RE)])
-        .describe(`${description}; "*" = all accounts${csvExample}`);
+        // '*' first so the tuple is statically non-empty even when ACCOUNTS is empty
+        // (a fresh install): z.enum requires [string, ...string[]].
+        .union([z.enum(['*', ...ACCOUNTS]), z.string().regex(CSV_RE)])
+        .optional()
+        .describe(`${description}; "*" = all accounts${csvExample}; omit for the default account`);
 }
-export function parseAccountSelector(value, accounts = ACCOUNTS) {
+export function parseAccountSelector(value, accounts = getAccountSet().aliases) {
     if (value === '*')
         return { ok: true, fanout: true, aliases: [...accounts] };
     if (!value.includes(','))
@@ -29,7 +32,7 @@ export function parseAccountSelector(value, accounts = ACCOUNTS) {
         return { ok: false, invalid };
     return { ok: true, fanout: aliases.length > 1, aliases };
 }
-export function invalidAccountsResult(invalid, accounts = ACCOUNTS) {
+export function invalidAccountsResult(invalid, accounts = getAccountSet().aliases) {
     return {
         content: [
             {

package/dist/fs-atomic.d.ts

@@ -0,0 +1,3 @@
+export declare function withFileLock<T>(absPath: string, fn: () => T, label?: string): T;
+export declare function atomicWriteFileSync(absPath: string, contents: string, mode?: number): void;
+export declare function atomicWriteWithLock(absPath: string, contents: string, mode?: number): void;

package/dist/fs-atomic.js

@@ -0,0 +1,123 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+const LOCK_TIMEOUT_MS = 5_000;
+const LOCK_RETRY_MS = 10;
+const RENAME_ATTEMPTS = 5;
+const RENAME_RETRY_MS = 20;
+function sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+// Hardlink-based advisory lock, generalized path-keyed from the token store's
+// alias-keyed original (same mechanics: dead-owner recovery via signal-0 probe,
+// EPERM = alive, corrupt lock content recovered as dead, 5s timeout).
+export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
+    const dir = path.dirname(absPath);
+    const lock = path.join(dir, `.${path.basename(absPath)}.lock`);
+    const ownerFile = `${lock}.${process.pid}.${randomBytes(6).toString('hex')}.owner`;
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(ownerFile, String(process.pid), { mode: 0o600, flag: 'wx' });
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    try {
+        while (true) {
+            try {
+                fs.linkSync(ownerFile, lock);
+                break;
+            }
+            catch (error) {
+                const err = error;
+                if (err.code !== 'EEXIST')
+                    throw error;
+                try {
+                    const observedOwner = fs.readFileSync(lock, 'utf8');
+                    const owner = Number(observedOwner);
+                    let ownerDead = !(Number.isSafeInteger(owner) && owner > 0);
+                    if (!ownerDead) {
+                        try {
+                            process.kill(owner, 0);
+                        }
+                        catch (ownerError) {
+                            const code = ownerError.code;
+                            // EPERM: PID exists but is not signalable (recycled by another
+                            // user); treat as alive, never break a lock we cannot verify.
+                            if (code === 'ESRCH')
+                                ownerDead = true;
+                            else if (code !== 'EPERM')
+                                throw ownerError;
+                        }
+                    }
+                    if (ownerDead) {
+                        if (fs.readFileSync(lock, 'utf8') === observedOwner)
+                            fs.rmSync(lock, { force: true });
+                        continue;
+                    }
+                }
+                catch (readError) {
+                    if (readError.code === 'ENOENT') {
+                        continue;
+                    }
+                    throw readError;
+                }
+                if (Date.now() >= deadline) {
+                    throw new Error(`Timed out waiting for ${label}`, { cause: error });
+                }
+                sleep(LOCK_RETRY_MS);
+            }
+        }
+    }
+    finally {
+        fs.rmSync(ownerFile, { force: true });
+    }
+    try {
+        return fn();
+    }
+    finally {
+        fs.rmSync(lock, { force: true });
+    }
+}
+export function atomicWriteFileSync(absPath, contents, mode = 0o600) {
+    const dir = path.dirname(absPath);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const tmp = path.join(dir, `.${path.basename(absPath)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
+    try {
+        fs.writeFileSync(tmp, contents, { mode, flag: 'wx' });
+        // Open read-write, not read-only: on Windows fsync maps to
+        // FlushFileBuffers, which returns EPERM on a read-only handle.
+        const fd = fs.openSync(tmp, 'r+');
+        try {
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        renameWithRetry(tmp, absPath);
+    }
+    finally {
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch {
+            // force only suppresses ENOENT; a Windows handle-holder can make this
+            // throw and mask the real write error. The orphan tmp is harmless.
+        }
+    }
+}
+// Windows only: renaming over a momentarily-open file throws transient EPERM/EACCES/EBUSY (reads take no lock); see docs/internals.md.
+function renameWithRetry(from, to) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            fs.renameSync(from, to);
+            return;
+        }
+        catch (error) {
+            const code = error.code;
+            const transient = code === 'EPERM' || code === 'EACCES' || code === 'EBUSY';
+            if (!transient || attempt >= RENAME_ATTEMPTS)
+                throw error;
+            sleep(RENAME_RETRY_MS * attempt);
+        }
+    }
+}
+export function atomicWriteWithLock(absPath, contents, mode = 0o600) {
+    withFileLock(absPath, () => atomicWriteFileSync(absPath, contents, mode));
+}

package/dist/http-config.d.ts

@@ -0,0 +1,35 @@
+export type Transport = 'stdio' | 'http' | 'both';
+export declare const DEFAULT_HTTP_HOST = "127.0.0.1";
+export declare const DEFAULT_HTTP_PORT = 4243;
+export declare const CLAUDE_AI_ORIGIN = "https://claude.ai";
+/** Slug-carrying boot-time config failure; caller surfaces the message. */
+export declare class HttpConfigError extends Error {
+    readonly slug: string;
+    constructor(slug: string, message: string);
+}
+export interface HttpConfig {
+    transport: Transport;
+    host: string;
+    port: number;
+    /** Canonical public base URL (BR4): lowercase scheme+host, no default port,
+     *  no trailing slash, no fragment/query. The issuer and every advertised
+     *  endpoint derive from this. */
+    publicUrl: string;
+    /** `${publicUrl}/mcp` — the canonical resource URI (JWT `aud` / PRM `resource`). */
+    resourceUri: string;
+    /** DNS-rebind Host allowlist. Both host[:port] and bare-host forms are
+     *  included: the Host header may or may not carry the port depending on the
+     *  client/proxy, and a too-narrow allowlist is a silent 403. */
+    allowedHosts: string[];
+    /** Origin allowlist for the front guard (publicUrl origin + claude.ai + extras). */
+    allowedOrigins: string[];
+}
+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
+ * 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.
+ */
+export declare function canonicalizePublicUrl(raw: string): string;
+export declare function resolveHttpConfig(env?: NodeJS.ProcessEnv): HttpConfig;

package/dist/http-config.js

@@ -0,0 +1,113 @@
+// 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.
+export const DEFAULT_HTTP_HOST = '127.0.0.1';
+export const DEFAULT_HTTP_PORT = 4243;
+export const CLAUDE_AI_ORIGIN = 'https://claude.ai';
+/** Slug-carrying boot-time config failure; caller surfaces the message. */
+export class HttpConfigError extends Error {
+    slug;
+    constructor(slug, message) {
+        super(message);
+        this.slug = slug;
+        this.name = 'HttpConfigError';
+    }
+}
+export function transportIncludesHttp(t) {
+    return t === 'http' || t === 'both';
+}
+export function resolveTransport(env = process.env) {
+    const raw = (env.MCP_TRANSPORT ?? '').trim().toLowerCase();
+    if (raw === '')
+        return 'stdio';
+    if (raw === 'stdio' || raw === 'http' || raw === 'both')
+        return raw;
+    // Load-bearing (decides whether a port opens): fail fast rather than silently
+    // downgrade — a user who set `http` and got stdio would be badly confused.
+    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
+ * 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.
+ */
+export function canonicalizePublicUrl(raw) {
+    let u;
+    try {
+        u = new URL(raw);
+    }
+    catch {
+        throw new HttpConfigError('E_PUBLIC_URL_INVALID', `MCP_PUBLIC_URL is not a valid absolute URL: "${raw}"`);
+    }
+    if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+        throw new HttpConfigError('E_PUBLIC_URL_INVALID', `MCP_PUBLIC_URL must be http(s) (got "${raw}")`);
+    }
+    u.hash = '';
+    u.search = '';
+    u.username = '';
+    u.password = '';
+    const path = u.pathname.replace(/\/+$/, '');
+    return `${u.protocol}//${u.host}${path}`;
+}
+function resolvePort(raw) {
+    const s = (raw ?? '').trim();
+    if (s === '')
+        return DEFAULT_HTTP_PORT;
+    const n = Number(s);
+    if (!Number.isInteger(n) || n < 1 || n > 65535) {
+        throw new HttpConfigError('E_INVALID_HTTP_PORT', `MCP_HTTP_PORT must be an integer 1-65535 (got "${raw}")`);
+    }
+    return n;
+}
+/** `host:port`, bracketing a bare IPv6 literal so it is a valid URL authority. */
+function hostPort(host, port) {
+    const h = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+    return `${h}:${port}`;
+}
+function deriveAllowedHosts(publicUrl, host, port) {
+    const pu = new URL(publicUrl);
+    const set = new Set();
+    set.add(pu.host); // hostname[:port]
+    set.add(pu.hostname); // bare hostname
+    set.add(host);
+    set.add(hostPort(host, port));
+    return [...set];
+}
+function deriveAllowedOrigins(publicUrl, extra) {
+    const set = new Set();
+    set.add(new URL(publicUrl).origin);
+    set.add(CLAUDE_AI_ORIGIN);
+    for (const raw of (extra ?? '').split(',').map((s) => s.trim()).filter(Boolean)) {
+        let o;
+        try {
+            o = new URL(raw).origin;
+        }
+        catch {
+            throw new HttpConfigError('E_INVALID_ORIGIN', `MCP_ALLOWED_ORIGINS entry is not a valid URL: "${raw}"`);
+        }
+        if (o === 'null') {
+            throw new HttpConfigError('E_INVALID_ORIGIN', `MCP_ALLOWED_ORIGINS entry has no usable origin: "${raw}"`);
+        }
+        set.add(o);
+    }
+    return [...set];
+}
+export function resolveHttpConfig(env = process.env) {
+    const transport = resolveTransport(env);
+    const host = (env.MCP_HTTP_HOST ?? '').trim() || DEFAULT_HTTP_HOST;
+    const port = resolvePort(env.MCP_HTTP_PORT);
+    const rawPublic = (env.MCP_PUBLIC_URL ?? '').trim() || `http://${hostPort(host, port)}`;
+    const publicUrl = canonicalizePublicUrl(rawPublic);
+    return {
+        transport,
+        host,
+        port,
+        publicUrl,
+        resourceUri: `${publicUrl}/mcp`,
+        allowedHosts: deriveAllowedHosts(publicUrl, host, port),
+        allowedOrigins: deriveAllowedOrigins(publicUrl, env.MCP_ALLOWED_ORIGINS),
+    };
+}

package/dist/http-transport.d.ts

@@ -0,0 +1,59 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { HttpConfig } from './http-config.js';
+export type AuthOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    status: number;
+    body: string;
+    headers?: Record<string, string>;
+};
+/** Bearer / owner check for POST /mcp. B12 default = loopback-owner; B13 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. */
+export type RouteHandler = (req: IncomingMessage, res: ServerResponse, url: URL) => boolean | Promise<boolean>;
+export interface HttpHostOptions {
+    /** The ONE McpServer + registry built at boot (P1 / BV gap #4: never per request). */
+    server: McpServer;
+    config: HttpConfig;
+    version: string;
+    ownerConfigured: boolean;
+    authenticate: Authenticator;
+    /** Extra routes keyed by exact pathname (AS endpoints mount here in B13). */
+    routes?: Record<string, RouteHandler>;
+    log?: (line: string) => void;
+    /** Max /mcp JSON body bytes (DoS guard). */
+    maxBodyBytes?: number;
+    /** Deadline for a single /mcp dispatch; a hung handler past this releases the
+     * shared lock instead of wedging the transport (default 120s). */
+    dispatchTimeoutMs?: number;
+}
+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). */
+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. */
+export declare function jsonRpcMethod(body: unknown): string;
+export declare class HttpTransportHost {
+    private readonly opts;
+    private httpServer?;
+    private lock;
+    constructor(opts: HttpHostOptions);
+    private serialize;
+    private log;
+    start(): Promise<void>;
+    close(): Promise<void>;
+    /** The bound port (useful when listening on port 0 in tests). */
+    address(): {
+        port: number;
+    } | undefined;
+    private handle;
+    private frontGuard;
+    private mcp;
+    private health;
+    private readJson;
+    private fail;
+}