mcp-google-multi 6.0.0-alpha.25 → 6.0.0-alpha.27

package/README.md

@@ -55,6 +55,10 @@ 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) · [Migrating to v6](./MIGRATION-v6.md) · [Security policy](./SECURITY.md) · [Roadmap](https://github.com/bakissation/mcp-google-multi/milestones)
 
+## Local usage metrics (off by default)
+
+The server can keep anonymous, **local-only** usage aggregates for its operator: tool names, error classes, latency buckets. Never arguments, payloads, message content, accounts, or identities of any kind, and **zero network egress ever** — the data cannot leave your machine unless you copy files yourself. It is off until you set `GOOGLE_USAGE_METRICS=on`; when on, the boot log and `doctor` say so and name the source. Read your own data with `mcp-google-multi metrics report`. Details, file format, and the honest threat model: [docs/usage-metrics.md](./docs/usage-metrics.md).
+
 ## Maintainer & credits
 
 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/)

package/dist/arg-normalize.d.ts

@@ -11,9 +11,9 @@ export declare function normalizeCallArguments(shape: ArgShape, args: Record<str
     args: Record<string, unknown>;
     renamed: [string, string][];
 };
-export declare function normalizeMessage(msg: JSONRPCMessage, shapeFor: (tool: string) => ArgShape | undefined, log?: (line: string) => void): JSONRPCMessage;
+export declare function normalizeMessage(msg: JSONRPCMessage, shapeFor: (tool: string) => ArgShape | undefined, log?: (line: string) => void, onRename?: (tool: string, renames: number) => void): JSONRPCMessage;
 /** Wrap a server-side transport so tools/call argument keys are normalized
  * before the SDK validates them. The Protocol assigns `onmessage` during
  * connect(); the interceptor lives in that setter, so the wrapper works
  * identically for stdio and (per-request, stateless) HTTP transports. */
-export declare function withArgNormalization(transport: Transport, shapeFor: (tool: string) => ArgShape | undefined, log?: (line: string) => void): Transport;
+export declare function withArgNormalization(transport: Transport, shapeFor: (tool: string) => ArgShape | undefined, log?: (line: string) => void, onRename?: (tool: string, renames: number) => void): Transport;

package/dist/arg-normalize.js

@@ -36,7 +36,7 @@ export function normalizeCallArguments(shape, args) {
     }
     return { args: out ?? args, renamed };
 }
-export function normalizeMessage(msg, shapeFor, log = (l) => process.stderr.write(`${l}\n`)) {
+export function normalizeMessage(msg, shapeFor, log = (l) => process.stderr.write(`${l}\n`), onRename) {
     const m = msg;
     if (m.method !== 'tools/call' || typeof m.params?.name !== 'string')
         return msg;
@@ -51,6 +51,10 @@ export function normalizeMessage(msg, shapeFor, log = (l) => process.stderr.writ
         return msg;
     // Key names only — argument VALUES never reach the log.
     log(`[args] ${m.params.name}: ${renamed.map(([f, t]) => `${f} -> ${t}`).join(', ')}`);
+    try {
+        onRename?.(m.params.name, renamed.length);
+    }
+    catch { /* observers never break dispatch */ }
     return {
         ...msg,
         params: { ...m.params, arguments: normalized },
@@ -60,7 +64,7 @@ export function normalizeMessage(msg, shapeFor, log = (l) => process.stderr.writ
  * before the SDK validates them. The Protocol assigns `onmessage` during
  * connect(); the interceptor lives in that setter, so the wrapper works
  * identically for stdio and (per-request, stateless) HTTP transports. */
-export function withArgNormalization(transport, shapeFor, log) {
+export function withArgNormalization(transport, shapeFor, log, onRename) {
     const wrapper = {
         start: () => transport.start(),
         send: (message, options) => transport.send(message, options),
@@ -70,7 +74,7 @@ export function withArgNormalization(transport, shapeFor, log) {
         get: () => transport.onmessage,
         set: (handler) => {
             transport.onmessage = handler
-                ? (message, extra) => handler(normalizeMessage(message, shapeFor, log), extra)
+                ? (message, extra) => handler(normalizeMessage(message, shapeFor, log, onRename), extra)
                 : undefined;
         },
     });

package/dist/doctor.d.ts

@@ -53,6 +53,9 @@ export interface HttpProbeResult {
 }
 /** Console deep-link to enable one API (section-6 hint, error taxonomy B10). */
 export declare function apiEnableLink(api: string): string;
+/** One line, state AND source, so the people being measured can see both
+ * here and in `diagnose` (metrics spec section 2). Read-only. */
+export declare function usageMetricsStatusLine(env: Record<string, string | undefined>): string;
 /** Roll section verdicts to an overall verdict. `unknown` never worsens it. */
 export declare function overallVerdict(sections: DiagnosticSection[]): Verdict;
 export declare function runDiagnostics(deps?: DiagnosticsDeps): Promise<DiagnosticsReport>;

package/dist/doctor.js

@@ -5,7 +5,9 @@ import { getAccountSet } from './accounts.js';
 import { deriveAccountHealth } from './tools/accounts-tool.js';
 import { peekMasterKeyProvenance, deleteMasterKeyMaterial } from './master-key.js';
 import { hasToken } from './token-store.js';
-import { configDir } from './config-file.js';
+import { configDir, loadConfigFile } from './config-file.js';
+import { envValueSource } from './env-load.js';
+import { describeMetricsDir, resolveUsageMetrics, sourceLabel } from './usage-metrics.js';
 import { probeApiEnablement } from './api-probe.js';
 import { resolveHttpConfig, HttpConfigError } from './http-config.js';
 import { parseOwnerEmails } from './http-transport.js';
@@ -114,8 +116,24 @@ function sectionConfig(deps, set) {
             hint = (hint ? `${hint} ` : '') + `Move it: \`mv ${envFile} ${target}\`.`;
         }
     }
+    lines.push(usageMetricsStatusLine(deps.env));
     return { id: 2, title: 'Config', verdict, lines, ...(hint ? { hint } : {}), ...(slug ? { slug } : {}) };
 }
+/** One line, state AND source, so the people being measured can see both
+ * here and in `diagnose` (metrics spec section 2). Read-only. */
+export function usageMetricsStatusLine(env) {
+    const envSrc = envValueSource('GOOGLE_USAGE_METRICS');
+    let configValue;
+    try {
+        configValue = loadConfigFile(undefined, 'throw')?.usageMetrics;
+    }
+    catch { /* invalid config is section 2's business, not this line's */ }
+    const state = resolveUsageMetrics(env, configValue, envSrc?.kind === 'file' ? envSrc.file : undefined);
+    if (!state.enabled)
+        return `local usage metrics: off ${sourceLabel(state.source)}`;
+    const d = describeMetricsDir(env);
+    return `local usage metrics: on ${sourceLabel(state.source)} -> ${d.dir} (${d.files} files, ${d.kb} KB)`;
+}
 function sectionKeys(deps, aliases) {
     const provenance = deps.masterKeyProvenance();
     const tokensExist = deps.anyTokensExist(aliases);

package/dist/http-transport.d.ts

@@ -2,6 +2,7 @@ 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 { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 export type AuthOutcome = {
     ok: true;
 } | {
@@ -31,6 +32,10 @@ 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;
+    /** Usage-metrics argfix observer, forwarded into arg normalization. */
+    onArgRename?: (tool: string, renames: number) => void;
 }
 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

@@ -183,7 +183,8 @@ 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);
+            const tapped = this.opts.metricsTap ? this.opts.metricsTap(transport) : transport;
+            await this.opts.server.connect(this.opts.argShapeFor ? withArgNormalization(tapped, this.opts.argShapeFor, this.opts.log, this.opts.onArgRename) : 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

@@ -103,6 +103,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);
@@ -222,11 +238,20 @@ async function main() {
     // 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' }), undefined, initMetricsFor('stdio', resolveDiscoveryMode()));
+        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);
+        // Tap sits under arg normalization at the same wrap site; it only counts
+        // outbound JSON-RPC error frames (no handler ran) plus id->tool names.
+        let transport = new StdioServerTransport();
+        if (stdioMetrics) {
+            const { tapUsageMetrics } = await import('./metrics-tap.js');
+            transport = tapUsageMetrics(transport, stdioMetrics);
+        }
+        await server.connect(argNormalizationEnabled()
+            ? withArgNormalization(transport, (n) => registry.argShape(n), undefined, stdioMetrics ? (tool, n) => stdioMetrics.recordArgFix(tool, n) : undefined)
+            : transport);
     }
     if (wantHttp) {
         const { HttpTransportHost, parseOwnerEmails } = await import('./http-transport.js');
@@ -243,7 +268,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', initMetricsFor('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.
@@ -309,6 +335,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);
+        }
         const host = new HttpTransportHost({
             server: httpServer,
             config: httpCfg,
@@ -318,6 +349,8 @@ async function main() {
             routes: authServer.routes,
             log: (l) => process.stderr.write(`[http] ${l}\n`),
             argShapeFor: argNormalizationEnabled() ? (n) => registry.argShape(n) : undefined,
+            metricsTap: httpTap,
+            onArgRename: httpMetrics ? (tool, n) => httpMetrics.recordArgFix(tool, n) : undefined,
         });
         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,3 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Metrics } from './usage-metrics.js';
+export declare function tapUsageMetrics(transport: Transport, metrics: Metrics): Transport;

package/dist/metrics-tap.js

@@ -0,0 +1,75 @@
+const PENDING_CAP = 1_000;
+export function tapUsageMetrics(transport, metrics) {
+    const pending = new Map();
+    const wrapper = {
+        start: () => transport.start(),
+        send: (message, options) => {
+            try {
+                const m = message;
+                if (m.id !== undefined) {
+                    const tool = pending.get(m.id);
+                    pending.delete(m.id);
+                    if (m.error && typeof m.error.code === 'number') {
+                        if (m.error.code === -32602) {
+                            if (/unknown tool|not found/i.test(m.error.message ?? ''))
+                                metrics.recordRpc('tool_not_found');
+                            else
+                                metrics.recordRpc('schema_validation', tool);
+                        }
+                        else {
+                            metrics.recordRpc(m.error.code);
+                        }
+                    }
+                    else if (m.result?.isError === true) {
+                        // SDK 1.x synthesizes input-validation failures as isError RESULTS
+                        // ("MCP error -32602: ..."), skipping the handler entirely, so the
+                        // registry wrapper never sees them either. Handler envelopes are
+                        // JSON text and never carry this prefix, so nothing double counts.
+                        const first = m.result.content?.[0]?.text;
+                        if (typeof first === 'string' && first.startsWith('MCP error -32602:')) {
+                            if (/tool \S+ not found|unknown tool/i.test(first))
+                                metrics.recordRpc('tool_not_found');
+                            else
+                                metrics.recordRpc('schema_validation', tool);
+                        }
+                    }
+                }
+            }
+            catch { /* the tap may never break the wire */ }
+            return transport.send(message, options);
+        },
+        close: () => transport.close(),
+    };
+    Object.defineProperty(wrapper, 'onmessage', {
+        get: () => transport.onmessage,
+        set: (handler) => {
+            transport.onmessage = handler
+                ? (message, extra) => {
+                    try {
+                        const m = message;
+                        if (m.id !== undefined && m.method === 'tools/call' && typeof m.params?.name === 'string') {
+                            if (pending.size >= PENDING_CAP)
+                                pending.clear();
+                            pending.set(m.id, m.params.name);
+                        }
+                    }
+                    catch { /* never break the wire */ }
+                    handler(message, extra);
+                }
+                : undefined;
+        },
+    });
+    for (const prop of ['onclose', 'onerror']) {
+        Object.defineProperty(wrapper, prop, {
+            get: () => transport[prop],
+            set: (v) => {
+                transport[prop] = v;
+            },
+        });
+    }
+    Object.defineProperty(wrapper, 'sessionId', { get: () => transport.sessionId });
+    if (transport.setProtocolVersion) {
+        wrapper.setProtocolVersion = (v) => transport.setProtocolVersion(v);
+    }
+    return wrapper;
+}

package/dist/registry.d.ts

@@ -56,6 +56,8 @@ export declare class ToolRegistry {
      * normalization; the kind drives value coercion on renamed keys). */
     argShape(name: string): ArgShape | undefined;
     catalog(service: string, query?: string): CatalogOperation[];
+    /** The metrics recorder, for hook sites (escape hatch); null when off. */
+    get usageMetrics(): Metrics | null;
     /** Op-name vocabulary for a service, split by provenance so the capped
      * discover descriptions can list curated ops and only summarize the
      * generated long tail. */

package/dist/registry.js

@@ -252,6 +252,10 @@ export class ToolRegistry {
             cud: t.cud,
         }));
     }
+    /** The metrics recorder, for hook sites (escape hatch); null when off. */
+    get usageMetrics() {
+        return this.metrics;
+    }
     /** Op-name vocabulary for a service, split by provenance so the capped
      * discover descriptions can list curated ops and only summarize the
      * generated long tail. */

package/dist/tools/generated/method-map.d.ts

@@ -0,0 +1,2 @@
+export declare const GENERATED_METHOD_TOOLS: Record<string, string>;
+export declare const CURATED_METHOD_IDS: readonly string[];