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

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/executor.js

@@ -2,6 +2,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';
+import { checkOutboundForMethod } from './outbound-allowlist.js';
 export const MAX_RESPONSE_CHARS = 100_000;
 export function jsonResult(payload, isError = false) {
     const base = { content: [{ type: 'text', text: JSON.stringify(payload) }] };
@@ -29,6 +30,11 @@ export function resolveRequestBody(httpMethod, body) {
     return body ?? undefined;
 }
 export async function executeApiMethod(method, args, deps = {}) {
+    // Outbound allowlist: no-op when off; with it active, structured bodies are
+    // inspected for recipient fields and raw-compose methods are refused.
+    const outbound = checkOutboundForMethod(method.id, args.body, args.account);
+    if (outbound)
+        return outbound;
     if (args.queryParams?.alt === 'media') {
         return jsonResult({
             error: 'binary_unsupported',

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);

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.js

@@ -20,6 +20,19 @@ export function tapUsageMetrics(transport, metrics) {
                             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 */ }

package/dist/outbound-allowlist.d.ts

@@ -0,0 +1,34 @@
+export interface OutboundAllowlist {
+    entries: string[];
+    allows(email: string): boolean;
+}
+/** Parse GOOGLE_OUTBOUND_ALLOWLIST: comma-separated addresses and @domain
+ * suffixes ("a@b.com, @company.com"). null = feature off (nothing gated). */
+export declare function resolveOutboundAllowlist(env?: NodeJS.ProcessEnv): OutboundAllowlist | null;
+/** The addresses in `emails` the active allowlist rejects; [] when off. */
+export declare function outboundViolations(emails: string[], env?: NodeJS.ProcessEnv): string[];
+/** The standard error envelope for a blocked outbound target. */
+export declare function outboundDeniedEnvelope(kind: string, blocked: string[], account: string, env?: NodeJS.ProcessEnv): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
+/** Convenience: envelope when violations exist, else null. */
+export declare function checkOutbound(kind: string, emails: string[], account: string, env?: NodeJS.ProcessEnv): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+} | null;
+export declare function collectBodyRecipients(body: unknown): string[];
+/** Gate one escape-hatch/generated dispatch; envelope when blocked, else null. */
+export declare function checkOutboundForMethod(methodId: string, body: unknown, account: string, env?: NodeJS.ProcessEnv): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+} | null;

package/dist/outbound-allowlist.js

@@ -0,0 +1,108 @@
+// Opt-in outbound recipient allowlist for unattended deployments: a
+// prompt-injection blast-radius control (a hijacked agent cannot mail, invite
+// or share outside the operator's list), a safety feature first and an
+// enterprise checkbox second. FREE-core forever (ee-definition-v0 handoff).
+// Off by default: an unset/empty GOOGLE_OUTBOUND_ALLOWLIST gates nothing.
+/** Parse GOOGLE_OUTBOUND_ALLOWLIST: comma-separated addresses and @domain
+ * suffixes ("a@b.com, @company.com"). null = feature off (nothing gated). */
+export function resolveOutboundAllowlist(env = process.env) {
+    const raw = env.GOOGLE_OUTBOUND_ALLOWLIST;
+    if (raw === undefined || raw.trim() === '')
+        return null;
+    const entries = raw.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean);
+    if (entries.length === 0)
+        return null;
+    const exact = new Set(entries.filter((e) => !e.startsWith('@')));
+    const domains = entries.filter((e) => e.startsWith('@'));
+    return {
+        entries,
+        allows(email) {
+            const a = email.trim().toLowerCase();
+            if (exact.has(a))
+                return true;
+            return domains.some((d) => a.endsWith(d));
+        },
+    };
+}
+/** The addresses in `emails` the active allowlist rejects; [] when off. */
+export function outboundViolations(emails, env = process.env) {
+    const list = resolveOutboundAllowlist(env);
+    if (!list)
+        return [];
+    return emails.map((e) => e.trim()).filter(Boolean).filter((e) => !list.allows(e));
+}
+/** The standard error envelope for a blocked outbound target. */
+export function outboundDeniedEnvelope(kind, blocked, account, env = process.env) {
+    const list = resolveOutboundAllowlist(env);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({
+                    error: 'recipient_not_allowed',
+                    message: `${kind} blocked by the outbound allowlist: ${blocked.join(', ')}.`,
+                    hint: `GOOGLE_OUTBOUND_ALLOWLIST is active (${(list?.entries ?? []).join(', ')}). ` +
+                        'The operator must add the address (or its @domain) to the list, or unset the variable, to allow this target.',
+                    retriable: false,
+                    account,
+                }),
+            },
+        ],
+        isError: true,
+    };
+}
+/** Convenience: envelope when violations exist, else null. */
+export function checkOutbound(kind, emails, account, env = process.env) {
+    const blocked = outboundViolations(emails, env);
+    return blocked.length > 0 ? outboundDeniedEnvelope(kind, blocked, account, env) : null;
+}
+// Escape-hatch / generated-tool enforcement. Structured bodies are inspected
+// for the known recipient fields; RAW compose methods cannot be inspected
+// (base64 RFC 822), so with the allowlist active they are refused outright in
+// favor of the curated tools that enforce it.
+const RAW_SEND_METHODS = new Set(['gmail.users.messages.send', 'gmail.users.drafts.send', 'gmail.users.drafts.create', 'gmail.users.messages.insert', 'gmail.users.messages.import']);
+export function collectBodyRecipients(body) {
+    const out = [];
+    const walk = (v, depth) => {
+        if (!v || typeof v !== 'object' || depth > 4)
+            return;
+        if (Array.isArray(v)) {
+            for (const x of v)
+                walk(x, depth + 1);
+            return;
+        }
+        for (const [k, x] of Object.entries(v)) {
+            if ((k === 'emailAddress' || k === 'email') && typeof x === 'string' && x.includes('@'))
+                out.push(x);
+            else if (k === 'attendees' || k === 'permissions')
+                walk(x, depth + 1);
+            else if (typeof x === 'object')
+                walk(x, depth + 1);
+        }
+    };
+    walk(body, 0);
+    return out;
+}
+/** Gate one escape-hatch/generated dispatch; envelope when blocked, else null. */
+export function checkOutboundForMethod(methodId, body, account, env = process.env) {
+    if (!resolveOutboundAllowlist(env))
+        return null;
+    if (RAW_SEND_METHODS.has(methodId)) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        error: 'recipient_not_allowed',
+                        message: `${methodId} carries an uninspectable raw message while GOOGLE_OUTBOUND_ALLOWLIST is active.`,
+                        hint: 'Use gmail_send / gmail_create_draft, which enforce the allowlist on parsed recipients.',
+                        retriable: false,
+                        account,
+                    }),
+                },
+            ],
+            isError: true,
+        };
+    }
+    return checkOutbound(`${methodId} recipient`, collectBodyRecipients(body), account, env);
+}

package/dist/tools/calendar.js

@@ -3,6 +3,7 @@ import { coerceArray, coerceBoolean } from './_coerce.js';
 import { calendar as calendarClient } from '@googleapis/calendar';
 import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
+import { checkOutbound } from '../outbound-allowlist.js';
 import { handleGoogleApiError } from './_errors.js';
 import { sliceClean } from '../trim.js';
 const accountEnum = accountAliasSchema.optional();
@@ -118,6 +119,11 @@ export function registerCalendarTools(server) {
         },
     }, async ({ account, summary, start, end, description, location, attendees, calendarId, allDay }) => {
         try {
+            if (attendees) {
+                const outbound = checkOutbound('calendar attendee', attendees.split(','), String(account));
+                if (outbound)
+                    return outbound;
+            }
             const auth = await getClient(account);
             const cal = calendarClient({ version: 'v3', auth });
             const event = { summary };
@@ -168,6 +174,11 @@ export function registerCalendarTools(server) {
         },
     }, async ({ account, eventId, summary, start, end, description, location, attendees, calendarId }) => {
         try {
+            if (attendees) {
+                const outbound = checkOutbound('calendar attendee', attendees.split(','), String(account));
+                if (outbound)
+                    return outbound;
+            }
             const auth = await getClient(account);
             const cal = calendarClient({ version: 'v3', auth });
             // Fetch the event first so a 404 surfaces before we attempt the patch.

package/dist/tools/drive.js

@@ -5,6 +5,7 @@ import { accountAliasSchema, getAccountSet } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
 import { openLocalReadStream, prepareLocalDest } from './_local-files.js';
+import { checkOutbound, outboundDeniedEnvelope, resolveOutboundAllowlist } from '../outbound-allowlist.js';
 import { isAllowed, writeDisabledResult } from '../write-control.js';
 import { capText } from '../trim.js';
 import * as fs from 'fs';
@@ -628,6 +629,25 @@ export function registerDriveTools(server) {
             expirationTime: z.string().optional().describe('RFC 3339 timestamp when access expires. Only valid for role="reader" or "commenter".'),
         },
     }, async ({ account, fileId, type, role, emailAddress, domain, sendNotification, emailMessage, transferOwnership, expirationTime }) => {
+        {
+            // Outbound allowlist (off unless GOOGLE_OUTBOUND_ALLOWLIST is set):
+            // user/group grantees must match; a domain share needs its exact
+            // "@domain" entry; "anyone" (link sharing) is refused while active.
+            const list = resolveOutboundAllowlist();
+            if (list) {
+                if ((type === 'user' || type === 'group') && emailAddress) {
+                    const outbound = checkOutbound('drive_share grantee', [emailAddress], String(account));
+                    if (outbound)
+                        return outbound;
+                }
+                else if (type === 'domain' && domain && !list.entries.includes(`@${domain.trim().toLowerCase()}`)) {
+                    return outboundDeniedEnvelope('drive_share domain grantee', [`@${domain}`], String(account));
+                }
+                else if (type === 'anyone') {
+                    return outboundDeniedEnvelope('drive_share grantee', ['anyone (link sharing)'], String(account));
+                }
+            }
+        }
         try {
             const auth = await getClient(account);
             const drive = driveClient({ version: 'v3', auth });

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[];