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

package/dist/fanout.js

@@ -1,21 +1,33 @@
 import { z } from 'zod';
-import { ACCOUNTS, getAccountSet } from './accounts.js';
+import { ACCOUNTS, getAccountSet, unknownAliasMessage } 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(',')}"` : '';
+    // The union's OWN error only fires when every branch aborts at the type
+    // check (a non-string). For a string, zod surfaces the single non-aborted
+    // branch verbatim, which is the CSV regex, so a mistyped alias used to read
+    // as "Invalid string: must match pattern /^[a-zA-Z0-9_-]+(,...)/" and never
+    // named an alias. Hence the same message on BOTH.
+    const bad = () => unknownAliasMessage(ACCOUNTS, true);
     return z
         // '*' 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)])
+        .union([z.enum(['*', ...ACCOUNTS]), z.string().regex(CSV_RE, { error: bad })], { error: bad })
         .optional()
         .describe(`${description}; "*" = all accounts${csvExample}; omit for the default account`);
 }
 export function parseAccountSelector(value, accounts = getAccountSet().aliases) {
     if (value === '*')
         return { ok: true, fanout: true, aliases: [...accounts] };
-    if (!value.includes(','))
-        return { ok: true, fanout: false, aliases: [value] };
+    // A single alias used to skip validation entirely and reach getClient, whose
+    // throw landed on the mapper's floor as an unclassified upstream_error. Same
+    // check and same envelope wherever the alias was typed.
+    if (!value.includes(',')) {
+        return accounts.includes(value)
+            ? { ok: true, fanout: false, aliases: [value] }
+            : { ok: false, invalid: [value] };
+    }
     const seen = new Set();
     const aliases = [];
     const invalid = [];
@@ -30,7 +42,9 @@ export function parseAccountSelector(value, accounts = getAccountSet().aliases)
     }
     if (invalid.length > 0)
         return { ok: false, invalid };
-    return { ok: true, fanout: aliases.length > 1, aliases };
+    // Keyed on the CSV FORM, not the deduped count: "a,a" asked for the merged
+    // multi-account envelope and used to get a bare single-account payload.
+    return { ok: true, fanout: true, aliases };
 }
 export function invalidAccountsResult(invalid, accounts = getAccountSet().aliases) {
     return {
@@ -40,8 +54,9 @@ export function invalidAccountsResult(invalid, accounts = getAccountSet().aliase
                 text: JSON.stringify({
                     error: 'validation_error',
                     message: `Unknown account alias(es): ${invalid.join(', ')}.`,
-                    hint: `Valid aliases: ${accounts.join(', ')}; or "*" for all accounts.`,
+                    hint: unknownAliasMessage(accounts, true),
                     retriable: false,
+                    account: invalid.join(','),
                 }),
             },
         ],
@@ -82,7 +97,27 @@ export async function runFanout(handler, args, aliases) {
     };
     await Promise.all(Array.from({ length: Math.min(FANOUT_CONCURRENCY, aliases.length) }, () => worker()));
     const failed = results.filter((r) => !r.ok).length;
+    if (failed === results.length && results.length > 0) {
+        // Every account failed, so this IS an error result, and used to carry
+        // `isError` with no top-level error, hint or retriable: the agent saw a
+        // successful-looking object flagged as an error, and metrics bucketed it
+        // as `other`. Hoist a real envelope, keeping the per-account detail.
+        const slugs = [...new Set(results.map((r) => r.error?.error ?? 'internal'))];
+        const hints = [...new Set(results.map((r) => r.error?.hint).filter(Boolean))];
+        const retriable = results.every((r) => r.error?.retriable === true);
+        return {
+            content: [{ type: 'text', text: JSON.stringify({
+                        error: 'fanout_failed',
+                        message: `All ${results.length} accounts failed: ${slugs.join(', ')}. Per-account detail is in results.`,
+                        hint: hints.length === 1 ? hints[0] : 'Each entry in results carries its own error and hint; they differ per account.',
+                        retriable,
+                        account: aliases.join(','),
+                        results,
+                        partial: true,
+                    }) }],
+            isError: true,
+        };
+    }
     const body = { results, partial: failed > 0 };
-    const out = { content: [{ type: 'text', text: JSON.stringify(body) }] };
-    return failed === results.length ? { ...out, isError: true } : out;
+    return { content: [{ type: 'text', text: JSON.stringify(body) }] };
 }

package/dist/http-transport.d.ts

@@ -1,7 +1,7 @@
+import type { McpServer, Transport } from "@modelcontextprotocol/server";
 import { type IncomingMessage, type ServerResponse } from 'node:http';
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { HttpConfig } from './http-config.js';
-import { type ArgShape } from './arg-normalize.js';
+import { type ArgShape, type StrictArgOptions, type ValidationEnvelopeOptions } from './arg-normalize.js';
 export type AuthOutcome = {
     ok: true;
 } | {
@@ -31,6 +31,15 @@ export interface HttpHostOptions {
     dispatchTimeoutMs?: number;
     /** tools/call argument-key normalization lookup (arg-normalize.ts); absent = off. */
     argShapeFor?: (tool: string) => ArgShape | undefined;
+    /** Usage-metrics transport tap (metrics-tap.ts); absent = off. */
+    metricsTap?: (t: Transport) => Transport;
+    /** Wired identically on both transports so a schema rejection reads the same
+     * over stdio and over HTTP. */
+    validationEnvelope?: ValidationEnvelopeOptions;
+    /** Usage-metrics argfix observer, forwarded into arg normalization. */
+    onArgRename?: (tool: string, renames: number) => void;
+    /** Unknown-argument screening (arg-strict.ts); absent = off. */
+    strictArgs?: StrictArgOptions;
 }
 export declare function parseOwnerEmails(env?: NodeJS.ProcessEnv): string[];
 /** Front guard: an Origin, if present, must be allowlisted; a Host must be

package/dist/http-transport.js

@@ -1,11 +1,10 @@
-// B12: the Streamable HTTP transport host (cc-transport-hosting T2/T3). Owns the
+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 { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { withArgNormalization } from './arg-normalize.js';
+import { withArgNormalization, withValidationEnvelope } from './arg-normalize.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.
@@ -161,7 +160,7 @@ export class HttpTransportHost {
         // 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).
-        const transport = new StreamableHTTPServerTransport({
+        const transport = new NodeStreamableHTTPServerTransport({
             sessionIdGenerator: undefined,
             enableJsonResponse: true,
             enableDnsRebindingProtection: false,
@@ -183,7 +182,13 @@ export class HttpTransportHost {
                 timer = setTimeout(() => resolve('timeout'), deadlineMs);
                 timer.unref?.();
             });
-            await this.opts.server.connect(this.opts.argShapeFor ? withArgNormalization(transport, this.opts.argShapeFor, this.opts.log) : transport);
+            // Same composition as the stdio leg: the envelope rewrite is innermost,
+            // so the tap above it still classifies the original validation prose.
+            const enveloped = withValidationEnvelope(transport, this.opts.validationEnvelope ?? {});
+            const tapped = this.opts.metricsTap ? this.opts.metricsTap(enveloped) : enveloped;
+            await this.opts.server.connect(this.opts.argShapeFor || this.opts.strictArgs
+                ? withArgNormalization(tapped, this.opts.argShapeFor ?? (() => undefined), this.opts.log, this.opts.onArgRename, this.opts.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).

package/dist/index.js

@@ -1,15 +1,15 @@
 #!/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).
-import { assertServerAccountsConfigured } from './accounts.js';
+import { assertServerAccountsConfigured, getAccountSet } from './accounts.js';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { McpServer } from "@modelcontextprotocol/server";
 import { GENERATED_SERVICES } from './tools/generated/index.js';
-import { GENERATED_GATES, SERVICES } from './services.js';
-import { ToolRegistry } from './registry.js';
+import { GENERATED_GATES, SERVICES, unknownToolMessage } from './services.js';
+import { ToolRegistry, resolveDiscoveryMode } from './registry.js';
 import { registerDiscoverTools } from './discover.js';
 import { registerEscapeTools } from './tools/google-api.js';
 import { registerAccountTools } from './tools/accounts-tool.js';
@@ -20,13 +20,31 @@ import { isAllowed, describePolicy } from './write-control.js';
 import { buildIdentityContext } from './identity.js';
 import { registerSetupPrompt } from './setup-prompt.js';
 import { applyNetTuning } from './net-tuning.js';
-import { argNormalizationEnabled, withArgNormalization } from './arg-normalize.js';
+import { argNormalizationEnabled, withArgNormalization, withValidationEnvelope } from './arg-normalize.js';
+import { unknownArgMode } from './arg-strict.js';
+import { envValueSource } from './env-load.js';
+import { loadConfigFile } from './config-file.js';
+import { initUsageMetrics, resolveUsageMetrics, sourceLabel } from './usage-metrics.js';
 applyNetTuning();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8'));
-function buildRegistry(server, ctx, mode) {
+/** Unknown-argument screening options, or undefined when the feature is off.
+ * Shared by both transports so a mistyped argument behaves identically. */
+function strictArgOptions(registry, metrics) {
+    const mode = unknownArgMode();
+    if (mode === 'off')
+        return undefined;
+    return {
+        mode,
+        declaredFor: (tool) => registry.declaredKeys(tool),
+        siblingsFor: (tool, keys) => registry.siblingSpellings(tool, keys),
+        unknownTool: (name) => unknownToolMessage(registry, name),
+        onDrop: metrics ? (tool, keys) => metrics.recordArgDrop(tool, keys) : undefined,
+    };
+}
+function buildRegistry(server, ctx, mode, metrics = null) {
     const policy = ctx.policy;
-    const registry = new ToolRegistry(server, policy, mode);
+    const registry = new ToolRegistry(server, policy, mode, metrics);
     const toolsets = getToolsets();
     if (toolsets !== 'all') {
         const known = new Set([...SERVICES.map((s) => s.name), ...GENERATED_SERVICES.map((s) => s.name)]);
@@ -100,6 +118,22 @@ async function main() {
         process.exitCode = await runResetCli(process.argv);
         return;
     }
+    if (process.argv.includes('metrics')) {
+        const { runMetricsCli } = await import('./metrics-cli.js');
+        const { GENERATED_METHOD_TOOLS, CURATED_METHOD_IDS } = await import('./tools/generated/method-map.js');
+        const envSrc = envValueSource('GOOGLE_USAGE_METRICS');
+        let configValue;
+        try {
+            configValue = loadConfigFile(undefined, 'throw')?.usageMetrics;
+        }
+        catch { /* an invalid config never blocks reading local metrics files */ }
+        const state = resolveUsageMetrics(process.env, configValue, envSrc?.kind === 'file' ? envSrc.file : undefined);
+        process.exitCode = runMetricsCli(process.argv, {
+            enabled: state.enabled,
+            promotion: { methodMap: GENERATED_METHOD_TOOLS, curatedIds: CURATED_METHOD_IDS },
+        });
+        return;
+    }
     if (process.argv.includes('write-client-config')) {
         const { runWriteClientConfigCli } = await import('./client-config.js');
         process.exitCode = await runWriteClientConfigCli(process.argv);
@@ -183,15 +217,68 @@ async function main() {
     }
     const wantStdio = httpCfg.transport === 'stdio' || httpCfg.transport === 'both';
     const wantHttp = transportIncludesHttp(httpCfg.transport);
+    // 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`.
+    const envSrc = envValueSource('GOOGLE_USAGE_METRICS');
+    const metricsState = resolveUsageMetrics(process.env, loadConfigFile()?.usageMetrics, envSrc?.kind === 'file' ? envSrc.file : undefined);
+    if (metricsState.warning)
+        process.stderr.write(metricsState.warning);
+    const metricsInstances = [];
+    const initMetricsFor = (transport, mode) => {
+        const m = initUsageMetrics(metricsState, { version: pkg.version, mode, transport });
+        if (m) {
+            metricsInstances.push(m);
+            process.stderr.write(`local usage metrics: on ${sourceLabel(metricsState.source)} -> ${m.statusLine()}\n`);
+        }
+        return m;
+    };
+    if (!metricsState.enabled && metricsState.source.kind !== 'default') {
+        process.stderr.write(`local usage metrics: off ${sourceLabel(metricsState.source)}\n`);
+    }
+    const flushMetrics = () => { for (const m of metricsInstances)
+        m.shutdown(); };
+    process.on('exit', flushMetrics);
+    if (metricsState.enabled) {
+        for (const sig of ['SIGTERM', 'SIGINT']) {
+            process.once(sig, () => {
+                flushMetrics();
+                // stdio has no other signal handler; preserve terminate-on-signal.
+                if (!wantHttp)
+                    process.exit(sig === 'SIGINT' ? 130 : 143);
+            });
+        }
+    }
     // Build one McpServer + registry per transport at boot (P1 / BV gap #4:
     // never rebuilt per request); `both` runs the two concurrently.
     if (wantStdio) {
         const server = new McpServer({ name: 'mcp-google-multi', version: pkg.version });
-        const registry = buildRegistry(server, buildIdentityContext(process.env, { transport: 'stdio' }));
+        const stdioMetrics = initMetricsFor('stdio', resolveDiscoveryMode());
+        const registry = buildRegistry(server, buildIdentityContext(process.env, { transport: 'stdio' }), undefined, stdioMetrics);
         registry.installListHandler();
         registerSetupPrompt(server);
-        const stdioTransport = new StdioServerTransport();
-        await server.connect(argNormalizationEnabled() ? withArgNormalization(stdioTransport, (n) => registry.argShape(n)) : stdioTransport);
+        // 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.
+        let transport = withValidationEnvelope(new StdioServerTransport(), {
+            isKnownTool: (n) => registry.hasTool(n),
+            defaultAccount: () => getAccountSet().defaultAccount,
+        });
+        if (stdioMetrics) {
+            const { tapUsageMetrics } = await import('./metrics-tap.js');
+            transport = tapUsageMetrics(transport, stdioMetrics, (n) => registry.hasTool(n));
+        }
+        const strictStdio = strictArgOptions(registry, stdioMetrics);
+        await server.connect(argNormalizationEnabled() || strictStdio
+            ? 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.
+            argNormalizationEnabled() ? (n) => registry.argShape(n) : () => undefined, undefined, stdioMetrics ? (tool, n) => stdioMetrics.recordArgFix(tool, n) : undefined, strictStdio)
+            : transport);
     }
     if (wantHttp) {
         const { HttpTransportHost, parseOwnerEmails } = await import('./http-transport.js');
@@ -208,7 +295,8 @@ async function main() {
             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 registry = buildRegistry(httpServer, buildIdentityContext(process.env, { transport: 'http' }), 'curated');
+        const httpMetrics = initMetricsFor('http', 'curated');
+        const registry = buildRegistry(httpServer, buildIdentityContext(process.env, { transport: 'http' }), 'curated', httpMetrics);
         registry.installListHandler();
         registerSetupPrompt(httpServer);
         // B13: mount the OAuth 2.1 AS (legs A + B) + the Bearer authenticator.
@@ -274,6 +362,11 @@ async function main() {
         // re-auth link into the AS's alias_reauth flow instead of a stdio CLI hint.
         const { setHttpReauthBase } = await import('./reauth-hint.js');
         setHttpReauthBase(httpCfg.publicUrl);
+        let httpTap;
+        if (httpMetrics) {
+            const { tapUsageMetrics } = await import('./metrics-tap.js');
+            httpTap = (t) => tapUsageMetrics(t, httpMetrics, (n) => registry.hasTool(n));
+        }
         const host = new HttpTransportHost({
             server: httpServer,
             config: httpCfg,
@@ -283,6 +376,13 @@ async function main() {
             routes: authServer.routes,
             log: (l) => process.stderr.write(`[http] ${l}\n`),
             argShapeFor: argNormalizationEnabled() ? (n) => registry.argShape(n) : undefined,
+            metricsTap: httpTap,
+            validationEnvelope: {
+                isKnownTool: (n) => registry.hasTool(n),
+                defaultAccount: () => getAccountSet().defaultAccount,
+            },
+            onArgRename: httpMetrics ? (tool, n) => httpMetrics.recordArgFix(tool, n) : undefined,
+            strictArgs: strictArgOptions(registry, httpMetrics),
         });
         await host.start();
         process.stderr.write(`HTTP transport listening on http://${httpCfg.host}:${httpCfg.port} (public ${httpCfg.publicUrl})\n`);

package/dist/metrics-cli.d.ts

@@ -0,0 +1,21 @@
+import { type DayAgg } from './usage-metrics.js';
+export interface PromotionData {
+    methodMap: Record<string, string>;
+    curatedIds: readonly string[];
+}
+export interface MetricsCliDeps {
+    enabled: boolean;
+    promotion: PromotionData;
+    env?: NodeJS.ProcessEnv;
+    out?: (line: string) => void;
+}
+interface PromotionRow {
+    methodId: string;
+    tool?: string;
+    calls: number;
+    kind: 'curation-candidate' | 'visibility-failure' | 'generation-gap';
+}
+/** The promotion-queue view: ranked evidence, a human decides (spec section 5). */
+export declare function classifyPromotion(merged: DayAgg, data: PromotionData): PromotionRow[];
+export declare function runMetricsCli(argv: string[], deps: MetricsCliDeps): number;
+export {};

package/dist/metrics-cli.js

@@ -0,0 +1,206 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { describeMetricsDir, mergeDay } from './usage-metrics.js';
+function loadDayDocs(dir, sinceDays) {
+    const aggDir = path.join(dir, 'agg');
+    let files;
+    try {
+        files = fs.readdirSync(aggDir).filter((f) => /^\d{4}-\d{2}-\d{2}\.json$/.test(f)).sort();
+    }
+    catch {
+        return [];
+    }
+    const cutoff = sinceDays !== undefined ? Date.now() - sinceDays * 86_400_000 : undefined;
+    const docs = [];
+    for (const f of files) {
+        if (cutoff !== undefined && Date.parse(`${f.slice(0, 10)}T00:00:00Z`) < cutoff)
+            continue;
+        try {
+            const doc = JSON.parse(fs.readFileSync(path.join(aggDir, f), 'utf-8'));
+            if (doc && doc.v === 1)
+                docs.push(doc);
+        }
+        catch { /* unreadable day file: skip, the report is best-effort */ }
+    }
+    return docs;
+}
+function sum(docs) {
+    return docs.reduce((a, b) => mergeDay(a, b));
+}
+function parseSince(argv) {
+    const i = argv.indexOf('--since');
+    if (i === -1 || !argv[i + 1])
+        return undefined;
+    const m = argv[i + 1].match(/^(\d+)d$/);
+    return m ? Number(m[1]) : undefined;
+}
+const pct = (num, den) => (den === 0 ? '-' : `${Math.round((num / den) * 100)}%`);
+const top = (m, n) => Object.entries(m).filter(([k]) => k !== '_overflow').sort((a, b) => b[1] - a[1]).slice(0, n);
+function renderReport(merged, days, out) {
+    out(`local usage metrics: ${days} day file(s), ${merged.calls} calls, node ${merged.node}`);
+    out(`boots: ${Object.entries(merged.boots).map(([k, v]) => `${k}=${v}`).join('  ') || '(none)'}`);
+    out('');
+    out('tool                              calls   err  err%  hint  top slug');
+    for (const [name, t] of Object.entries(merged.tools).sort((a, b) => b[1].n - a[1].n).slice(0, 30)) {
+        const errs = Object.values(t.err).reduce((s, v) => s + v, 0);
+        const slug = top(t.err, 1)[0]?.[0] ?? '';
+        out(`${name.padEnd(34)}${String(t.n).padStart(5)}${String(errs).padStart(6)}${pct(errs, t.n).padStart(6)}${String(t.hint).padStart(6)}  ${slug}`);
+    }
+    const hintRows = Object.entries(merged.hints);
+    if (hintRows.length > 0) {
+        out('');
+        out('hint coverage per error class (hinted/total)');
+        for (const [slug, h] of hintRows.sort((a, b) => b[1].hinted + b[1].unhinted - a[1].hinted - a[1].unhinted)) {
+            out(`  ${slug.padEnd(24)}${h.hinted}/${h.hinted + h.unhinted} (${pct(h.hinted, h.hinted + h.unhinted)})`);
+        }
+    }
+    const retryRows = Object.entries(merged.retries);
+    if (retryRows.length > 0) {
+        out('');
+        out('retry self-correction per error class (ok/total after hinted vs unhinted errors)');
+        for (const [slug, r] of retryRows) {
+            out(`  ${slug.padEnd(24)}hinted ${r.hintedOk}/${r.hintedOk + r.hintedFail} (${pct(r.hintedOk, r.hintedOk + r.hintedFail)})  unhinted ${r.unhintedOk}/${r.unhintedOk + r.unhintedFail} (${pct(r.unhintedOk, r.unhintedOk + r.unhintedFail)})`);
+        }
+    }
+    const esc = merged.escape;
+    if (Object.keys(esc.methods).length > 0 || esc.unknown_method > 0 || esc.unknown_api > 0) {
+        out('');
+        out(`escape hatch: unknown_method=${esc.unknown_method} unknown_api=${esc.unknown_api} overflow=${esc._overflow}`);
+        for (const [id, n] of top(esc.methods, 20))
+            out(`  ${id.padEnd(50)}${n}`);
+        const apis = top(esc.apis_searched, 10).map(([k, v]) => `${k}=${v}`).join('  ');
+        if (apis)
+            out(`  searched: ${apis}`);
+    }
+    if (Object.keys(merged.validation).length > 0) {
+        out('');
+        out('schema validation rejections (never reached a handler)');
+        for (const [tool, n] of top(merged.validation, 15))
+            out(`  ${tool.padEnd(34)}${n}`);
+    }
+    const bigrams = top(merged.bigrams, 10);
+    if (bigrams.length > 0) {
+        out('');
+        out('top tool bigrams');
+        for (const [pair, n] of bigrams)
+            out(`  ${pair.padEnd(50)}${n}`);
+    }
+}
+const tail = (id) => id.split('.').slice(1).join('.');
+/** The promotion-queue view: ranked evidence, a human decides (spec section 5). */
+export function classifyPromotion(merged, data) {
+    const curated = new Set();
+    for (const id of data.curatedIds) {
+        curated.add(id);
+        curated.add(tail(id));
+    }
+    const byId = new Map();
+    const byTail = new Map();
+    const toolToId = new Map();
+    for (const [id, tool] of Object.entries(data.methodMap)) {
+        byId.set(id, tool);
+        byTail.set(tail(id), tool);
+        toolToId.set(tool, id);
+    }
+    const rows = [];
+    // (a) generated tools with real traffic = curation candidates.
+    for (const [tool, t] of Object.entries(merged.tools)) {
+        const id = toolToId.get(tool);
+        if (id && !curated.has(id) && !curated.has(tail(id))) {
+            rows.push({ methodId: id, tool, calls: t.n, kind: 'curation-candidate' });
+        }
+    }
+    // (b)/(c) escape methodIds; the tail join covers legacy doc prefixes.
+    for (const [id, calls] of Object.entries(merged.escape.methods)) {
+        if (curated.has(id) || curated.has(tail(id)))
+            continue; // already curated: drops out
+        const twin = byId.get(id) ?? byTail.get(tail(id));
+        rows.push(twin
+            ? { methodId: id, tool: twin, calls, kind: 'visibility-failure' }
+            : { methodId: id, calls, kind: 'generation-gap' });
+    }
+    return rows.sort((a, b) => b.calls - a.calls);
+}
+function renderPromotion(rows, out) {
+    const section = (kind, title, note) => {
+        const list = rows.filter((r) => r.kind === kind);
+        if (list.length === 0)
+            return;
+        out(`### ${title}`);
+        out(note);
+        out('');
+        out('| methodId | tool | calls |');
+        out('|---|---|---|');
+        for (const r of list)
+            out(`| ${r.methodId} | ${r.tool ?? '(none)'} | ${r.calls} |`);
+        out('');
+    };
+    if (rows.length === 0) {
+        out('No promotion evidence yet: no generated-tool traffic and no escape-hatch methodIds recorded.');
+        return;
+    }
+    section('curation-candidate', 'Curation candidates', 'Generated tools with real traffic; a curated wrapper may be earned.');
+    section('visibility-failure', 'Visibility failures', 'The escape hatch was used where a generated tool exists; discovery/naming problem, not a coverage gap.');
+    section('generation-gap', 'Generation gaps', 'Escape methodIds with no tool at all.');
+}
+export function runMetricsCli(argv, deps) {
+    const out = deps.out ?? ((l) => process.stdout.write(`${l}\n`));
+    const env = deps.env ?? process.env;
+    const json = argv.includes('--json');
+    const sub = argv.includes('merge') ? 'merge' : 'report';
+    let merged;
+    let dayCount = 0;
+    if (sub === 'merge') {
+        const files = argv.slice(argv.indexOf('merge') + 1).filter((a) => !a.startsWith('--'));
+        if (files.length === 0) {
+            out('usage: mcp-google-multi metrics merge <file...> [--json]');
+            return 2;
+        }
+        const docs = [];
+        for (const f of files) {
+            let parsed;
+            try {
+                parsed = JSON.parse(fs.readFileSync(f, 'utf-8'));
+            }
+            catch (e) {
+                out(`cannot read ${f}: ${e.message}`);
+                return 2;
+            }
+            // A report wrapper carries {v, days, agg}; a raw day doc carries tools.
+            const doc = parsed.agg?.v === 1 ? parsed.agg : parsed.v === 1 && parsed.tools ? parsed : undefined;
+            if (!doc || doc.v !== 1) {
+                out(`${f} is neither a day aggregate nor a metrics report --json output`);
+                return 2;
+            }
+            docs.push(doc);
+            dayCount += 1;
+        }
+        merged = sum(docs);
+    }
+    else {
+        const dir = describeMetricsDir(env).dir;
+        const docs = loadDayDocs(dir, parseSince(argv));
+        if (docs.length === 0) {
+            out(deps.enabled
+                ? `local usage metrics are on but no day files exist yet under ${dir}`
+                : 'local usage metrics are off (default); enable with GOOGLE_USAGE_METRICS=on');
+            return 0;
+        }
+        merged = sum(docs);
+        dayCount = docs.length;
+    }
+    if (argv.includes('--promotion')) {
+        const rows = classifyPromotion(merged, deps.promotion);
+        if (json)
+            out(JSON.stringify({ v: 1, days: dayCount, promotion: rows }));
+        else
+            renderPromotion(rows, out);
+        return 0;
+    }
+    if (json) {
+        out(JSON.stringify({ v: 1, days: dayCount, agg: merged }));
+        return 0;
+    }
+    renderReport(merged, dayCount, out);
+    return 0;
+}

package/dist/metrics-tap.d.ts

@@ -0,0 +1,12 @@
+import type { Transport } from "@modelcontextprotocol/server";
+import type { Metrics } from './usage-metrics.js';
+import { isSchemaValidationText } from './arg-normalize.js';
+export { isSchemaValidationText };
+/**
+ * @param isKnownTool membership test against the REGISTERED tool set. The
+ * name on a `tools/call` frame is client-supplied, so a shape check alone
+ * would let a shape-valid but invented name reach disk and break the
+ * closed-vocabulary guarantee. A validation failure against a name the server
+ * never registered is a not-found, and is counted as one.
+ */
+export declare function tapUsageMetrics(transport: Transport, metrics: Metrics, isKnownTool?: (name: string) => boolean): Transport;