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

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

@@ -222,11 +222,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 +252,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 +319,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 +333,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-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,62 @@
+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);
+                        }
+                    }
+                }
+            }
+            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/google-api.js

@@ -86,12 +86,15 @@ export function registerEscapeTools(registry, policy, deps = {}) {
         if (api) {
             requested = resolveApiAliases(api);
             if (!requested) {
+                registry.usageMetrics?.recordSearchApi(null);
                 return jsonResult({ error: 'unknown_api', message: `Unknown api "${api}".`, hint: `Known APIs: ${apiList}`, retriable: false }, true);
             }
             const enabled = requested.filter(apiEnabled);
             if (enabled.length === 0)
                 return toolsetDisabled(requested[0]);
             requested = enabled;
+            // Post-resolution SUPPORTED_APIS keys only (closed vocabulary).
+            registry.usageMetrics?.recordSearchApi(requested);
         }
         const apis = requested ?? enabledApis;
         const unavailable = [];
@@ -172,6 +175,7 @@ export function registerEscapeTools(registry, policy, deps = {}) {
             }
         }
         if (!method) {
+            registry.usageMetrics?.recordEscapeMethod(null);
             const near = nearestMethodIds(String(methodId), index);
             return jsonResult({
                 error: 'unknown_method',
@@ -182,6 +186,8 @@ export function registerEscapeTools(registry, policy, deps = {}) {
                 account,
             }, true);
         }
+        // The RESOLVED index id only, never the caller's methodId argument.
+        registry.usageMetrics?.recordEscapeMethod(method.id);
         const cud = cudFromMethod(method);
         const policyService = serviceForAlias(apiKey);
         const lastSegment = method.id.split('.').pop() ?? method.id;

package/dist/usage-metrics.d.ts

@@ -79,7 +79,7 @@ export declare class Metrics {
     recordEscapeMethod(idOrNull: string | null): void;
     /** Search instrument: post-resolution SUPPORTED_APIS keys, or null on failure. */
     recordSearchApi(resolvedApis: string[] | null): void;
-    recordArgFix(tool: string): void;
+    recordArgFix(tool: string, by?: number): void;
     /** Protocol-level failures (no handler ran); wired by the transport tap. */
     recordRpc(kind: 'schema_validation' | 'tool_not_found' | number, tool?: string): void;
     private rolloverIfNeeded;
@@ -91,6 +91,13 @@ export declare class Metrics {
     /** For the doctor/diagnose status line. */
     statusLine(): string;
 }
+/** Read-only description of the metrics dir for doctor/diagnose status lines
+ * (never creates anything; safe to call with the feature off). */
+export declare function describeMetricsDir(env?: NodeJS.ProcessEnv): {
+    dir: string;
+    files: number;
+    kb: number;
+};
 /**
  * null when off: no directory, no file, no timer, nothing initializes; setting
  * USAGE_METRICS_PATH alone never enables anything and never creates anything.

package/dist/usage-metrics.js

@@ -28,6 +28,7 @@ const CHARS_BOUNDS = [64, 256, 1024, 4096, 16384, 65536];
 // arbitrary strings into recorded values (spec section 1).
 const METHOD_ID_RE = /^[a-z][a-zA-Z0-9]*(\.[a-zA-Z0-9]+)+$/;
 const METHOD_ID_MAX = 128;
+const TOOL_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
 /** Union of every `error:` slug literal emitted anywhere in src/ (kept honest
  * by a set-equality grep test). Anything outside buckets to `other`. */
 export const KNOWN_ERROR_SLUGS = new Set([
@@ -411,11 +412,13 @@ export class Metrics {
         }
         catch { /* never throws outward */ }
     }
-    recordArgFix(tool) {
+    recordArgFix(tool, by = 1) {
         try {
             this.rolloverIfNeeded();
+            if (!TOOL_NAME_RE.test(tool))
+                return;
             const t = (this.deltas.tools[tool] ??= { n: 0, err: {}, hint: 0, lat: {} });
-            t.argfix = (t.argfix ?? 0) + 1;
+            t.argfix = (t.argfix ?? 0) + by;
             this.dirty = true;
         }
         catch { /* never throws outward */ }
@@ -425,7 +428,9 @@ export class Metrics {
         try {
             this.rolloverIfNeeded();
             if (kind === 'schema_validation') {
-                if (tool)
+                // The tap's name came off the wire; the shape gate keeps a weird
+                // -32602 from writing free text (registered names always pass).
+                if (tool && TOOL_NAME_RE.test(tool))
                     addInto(this.deltas.validation, tool);
             }
             else if (kind === 'tool_not_found') {
@@ -437,7 +442,8 @@ export class Metrics {
             this.events.push(JSON.stringify({
                 ts: new Date(this.now()).toISOString().slice(0, 16) + ':00Z',
                 boot: this.bootId, seq: this.seq++,
-                tool: tool ?? 'other', ok: false, ms: 0, chars: 'le64', src: 'rpc',
+                tool: tool && TOOL_NAME_RE.test(tool) ? tool : 'other',
+                ok: false, ms: 0, chars: 'le64', src: 'rpc',
             }));
             this.dirty = true;
         }
@@ -524,6 +530,29 @@ export class Metrics {
         }
     }
 }
+/** Read-only description of the metrics dir for doctor/diagnose status lines
+ * (never creates anything; safe to call with the feature off). */
+export function describeMetricsDir(env = process.env) {
+    const dir = env.USAGE_METRICS_PATH ?? path.join(stateDir(env), METRICS_DIR_NAME);
+    let files = 0;
+    let bytes = 0;
+    try {
+        const candidates = [
+            ...fs.readdirSync(path.join(dir, 'agg')).map((f) => path.join(dir, 'agg', f)),
+            path.join(dir, 'events.jsonl'),
+            path.join(dir, 'events.1.jsonl'),
+        ];
+        for (const f of candidates) {
+            try {
+                bytes += fs.statSync(f).size;
+                files += 1;
+            }
+            catch { /* absent */ }
+        }
+    }
+    catch { /* dir absent: zeros */ }
+    return { dir, files, kb: Math.round(bytes / 1024) };
+}
 /**
  * null when off: no directory, no file, no timer, nothing initializes; setting
  * USAGE_METRICS_PATH alone never enables anything and never creates anything.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.25",
+  "version": "6.0.0-alpha.26",
   "description": "Local MCP server for Google Workspace (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console, +Forms/Chat/Admin) across multiple accounts — OAuth-only, encrypted token storage, deny-by-default writes.",
   "type": "module",
   "license": "MIT",