mcp-google-multi 6.0.0-alpha.9 → 6.0.0-beta.2

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/registry.d.ts

@@ -1,6 +1,8 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer } from "@modelcontextprotocol/server";
 import { z } from 'zod';
 import { type Policy } from './write-control.js';
+import type { ArgShape } from './arg-normalize.js';
+import type { Metrics } from './usage-metrics.js';
 export type Cud = 'read' | 'create' | 'update' | 'delete';
 export type DiscoveryMode = 'lazy' | 'curated' | 'eager';
 export declare function resolveDiscoveryMode(env?: NodeJS.ProcessEnv): DiscoveryMode;
@@ -29,15 +31,25 @@ export interface CatalogOperation {
     summary: string;
     args: string[];
     cud: Cud;
+    /** Present only when no scope bundle in the catalog can authorize this
+     * method, so the call cannot succeed on any account however it is
+     * configured. The tool stays callable: graceful dispatch then returns the
+     * real scope error rather than a bare "not found". */
+    unreachable?: true;
 }
 export declare function inferCud(name: string): Cud;
 export declare class ToolRegistry {
     private readonly server;
+    private readonly metrics;
     readonly tools: ToolEntry[];
     readonly policy: Policy;
     readonly registerTool: McpServer['registerTool'];
     private readonly revealed;
     private readonly jsonSchemaCache;
+    private readonly argShapeCache;
+    /** Memoized isUngrantable verdict per tool: the answer depends on the frozen
+     * bundle catalog only, so it never changes within a process. */
+    private readonly ungrantable;
     private readonly compactOutput;
     private registeringMeta;
     /** Configured visibility mode (GOOGLE_DISCOVERY); default lazy = v5 exact. */
@@ -45,10 +57,41 @@ export declare class ToolRegistry {
     /** Agent-toggled runtime overlay (discover_all / discover_reset): lifts a
      * lazy surface to curated without touching the configured mode. */
     private expanded;
-    constructor(server: McpServer, policy: Policy, mode?: DiscoveryMode);
+    constructor(server: McpServer, policy: Policy, mode?: DiscoveryMode, metrics?: Metrics | null);
     registerMeta: McpServer['registerTool'];
     services(): string[];
+    /** Declared input-schema keys + scalar kinds for one tool (tools/call arg
+     * normalization; the kind drives value coercion on renamed keys). */
+    argShape(name: string): ArgShape | undefined;
+    /** Declared argument keys for a tool, in declaration order; undefined when
+     * the tool is not registered. Backs unknown-argument screening, which needs
+     * the full key list rather than argShape's scalar-kind subset view. */
+    declaredKeys(name: string): readonly string[] | undefined;
+    /** Keys spelling a similar concept elsewhere in the same service, for the
+     * hint on a call whose key matched nothing. Kept only when a key is declared
+     * by at least two tools in the service or by a curated one, so one-off
+     * generated parameters do not become advice. */
+    siblingSpellings(tool: string, unknownKeys: string[]): Array<{
+        key: string;
+        tools: string[];
+    }>;
     catalog(service: string, query?: string): CatalogOperation[];
+    /** The metrics recorder, for hook sites (escape hatch); null when off. */
+    get usageMetrics(): Metrics | null;
+    /** Every registered tool name, hidden ones included: they stay callable, so
+     * a did-you-mean may legitimately point at one. */
+    toolNames(): string[];
+    /** Membership test against the REGISTERED tool set (hidden tools included:
+     * they stay callable). The metrics tap uses this so a client-supplied name
+     * can never enter the closed vocabulary. */
+    hasTool(name: string): boolean;
+    /** 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. */
+    opNames(service: string): {
+        curated: string[];
+        generated: string[];
+    };
     reveal(service: string): boolean;
     /** discover_all: advertise the full curated set at once. Idempotent. */
     expand(): boolean;
@@ -58,6 +101,15 @@ export declare class ToolRegistry {
      * dispatch), zero correctness impact. */
     collapse(): boolean;
     private effectiveMode;
+    /**
+     * True when NO bundle in the catalog grants any of the method's alternative
+     * scopes, so the call cannot succeed on any account under any configuration.
+     * Static: it asks the catalog, not an account, so it is safe to cache.
+     * `classifyScope` with nothing granted and no profile reports `add_bundle`
+     * for a scope some bundle could supply and `unknown_scope` only when none
+     * can, which is exactly the distinction wanted here.
+     */
+    isUngrantable(tool: ToolEntry): boolean;
     isVisible(tool: ToolEntry): boolean;
     visibleCount(): {
         eager: number;

package/dist/registry.js

@@ -1,10 +1,14 @@
-import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { isAllowed, writeDisabledResult, IRREVERSIBLE_TOOLS } from './write-control.js';
 import { getAccountSet, refreshAccountSetIfStale } from './accounts.js';
 import { compactResult, trimEnabled } from './trim.js';
 import { fanoutAccountField, invalidAccountsResult, parseAccountSelector, runFanout } from './fanout.js';
 import { MAX_RESPONSE_CHARS } from './executor.js';
+import { suggestKeys } from './arg-strict.js';
+import { classifyScope } from './scope-observability.js';
+/** Nothing granted, no profile: asks the BUNDLE CATALOG whether a scope is
+ * reachable at all, independently of any account. */
+const EMPTY_SCOPES = new Set();
 // Client-side result budget advertised for tools that do not declare their own
 // (fat readers do; see trim.ts). ~50k chars stays well inside a default client
 // context limit while leaving room for real list payloads.
@@ -38,6 +42,28 @@ const SERVICE_OVERRIDES = {
 };
 // read tools that write local files — same savePath fanned across accounts would clobber
 const FANOUT_EXCLUDE = new Set(['gmail_download_attachment', 'drive_download', 'drive_export']);
+/** Account-management tools: the `account` they take is the SUBJECT of the
+ * operation, not the identity it runs as, so injecting the configured default
+ * would silently retarget them. `account_add` would adopt the default as the
+ * new alias, and `account_reauth` would re-authenticate the wrong account. */
+const DEFAULT_ACCOUNT_EXCLUDE = new Set(['account_add', 'account_reauth']);
+/** Unwrap optional/default/nullable to the declared scalar kind (zod 4 defs). */
+function scalarKindOf(field) {
+    let cur = field;
+    for (let i = 0; i < 4 && cur?._zod?.def; i++) {
+        const def = cur._zod.def;
+        if (def.type === 'number')
+            return 'number';
+        if (def.type === 'boolean')
+            return 'boolean';
+        if (def.type === 'optional' || def.type === 'default' || def.type === 'nullable') {
+            cur = def.innerType;
+            continue;
+        }
+        return 'other';
+    }
+    return 'other';
+}
 function isAccountEnum(field) {
     const def = field?._zod?.def;
     if (!def)
@@ -64,11 +90,16 @@ export function inferCud(name) {
 }
 export class ToolRegistry {
     server;
+    metrics;
     tools = [];
     policy;
     registerTool;
     revealed = new Set();
     jsonSchemaCache = new Map();
+    argShapeCache = new Map();
+    /** Memoized isUngrantable verdict per tool: the answer depends on the frozen
+     * bundle catalog only, so it never changes within a process. */
+    ungrantable = new Map();
     compactOutput = trimEnabled();
     registeringMeta = false;
     /** Configured visibility mode (GOOGLE_DISCOVERY); default lazy = v5 exact. */
@@ -76,8 +107,9 @@ export class ToolRegistry {
     /** Agent-toggled runtime overlay (discover_all / discover_reset): lifts a
      * lazy surface to curated without touching the configured mode. */
     expanded = false;
-    constructor(server, policy, mode = resolveDiscoveryMode()) {
+    constructor(server, policy, mode = resolveDiscoveryMode(), metrics = null) {
         this.server = server;
+        this.metrics = metrics;
         this.policy = policy;
         this.mode = mode;
         this.registerTool = ((name, config, handler) => {
@@ -107,7 +139,7 @@ export class ToolRegistry {
             // never fan out meta tools: google_api_call infers cud=read but executes writes
             let inputShape = config.inputSchema ?? {};
             let baseHandler = handler;
-            const hasAccountField = 'account' in inputShape;
+            const hasAccountField = 'account' in inputShape && !DEFAULT_ACCOUNT_EXCLUDE.has(name);
             if (cud === 'read' && !this.registeringMeta && !FANOUT_EXCLUDE.has(name) && isAccountEnum(inputShape.account)) {
                 const description = inputShape.account.description ?? 'Google account alias';
                 inputShape = { ...inputShape, account: fanoutAccountField(description) };
@@ -136,9 +168,11 @@ export class ToolRegistry {
             });
             const guarded = cud === 'read'
                 ? baseHandler
-                : (...args) => isAllowed({ name, service, cud }, policy)
+                : (...args) => isAllowed({ name, service, cud, scopes: config.requiredScopes }, policy)
                     ? baseHandler(...args)
-                    : writeDisabledResult({ name, service, cud }, policy);
+                    : writeDisabledResult({ name, service, cud, scopes: config.requiredScopes }, policy, 
+                    // Concrete by here: default-account injection wraps this.
+                    args[0]?.account);
             // A2: the ONE default-account injection site — outside the CUD gate and
             // the fan-out parse so both observe a concrete alias; NOT meta-skipped
             // (that is what covers google_api_call with zero bespoke code). Explicit
@@ -176,8 +210,21 @@ export class ToolRegistry {
             const finalHandler = this.compactOutput
                 ? async (...args) => compactResult(await withDefault(...args))
                 : withDefault;
+            // Usage metrics wrap OUTERMOST and only when enabled: off means no
+            // wrapper exists and the chain is byte-identical to the pre-metrics
+            // chain. Fan-out width is derived here (bucketed in the module) so the
+            // metrics module never imports fanout.
+            const instrumented = this.metrics
+                ? this.metrics.wrap({ name, service, meta: this.registeringMeta, generated: config.cud !== undefined }, finalHandler, (a) => {
+                    const v = a?.account;
+                    if (typeof v !== 'string' || (v !== '*' && !v.includes(',')))
+                        return 1;
+                    const sel = parseAccountSelector(v);
+                    return sel.ok ? sel.aliases.length : 1;
+                })
+                : finalHandler;
             const { cud: _cud, ...sdkConfig } = config;
-            return server.registerTool(name, { ...sdkConfig, inputSchema: inputShape, annotations }, finalHandler);
+            return server.registerTool(name, { ...sdkConfig, inputSchema: inputShape, annotations }, instrumented);
         });
     }
     registerMeta = ((name, config, handler) => {
@@ -192,6 +239,66 @@ export class ToolRegistry {
     services() {
         return [...new Set(this.tools.filter((t) => !t.meta).map((t) => t.service))];
     }
+    /** Declared input-schema keys + scalar kinds for one tool (tools/call arg
+     * normalization; the kind drives value coercion on renamed keys). */
+    argShape(name) {
+        const cached = this.argShapeCache.get(name);
+        if (cached)
+            return cached;
+        const entry = this.tools.find((t) => t.name === name);
+        if (!entry)
+            return undefined;
+        const shape = new Map();
+        for (const [key, field] of Object.entries(entry.inputShape))
+            shape.set(key, scalarKindOf(field));
+        this.argShapeCache.set(name, shape);
+        return shape;
+    }
+    /** Declared argument keys for a tool, in declaration order; undefined when
+     * the tool is not registered. Backs unknown-argument screening, which needs
+     * the full key list rather than argShape's scalar-kind subset view. */
+    declaredKeys(name) {
+        const entry = this.tools.find((t) => t.name === name);
+        return entry ? Object.keys(entry.inputShape) : undefined;
+    }
+    /** Keys spelling a similar concept elsewhere in the same service, for the
+     * hint on a call whose key matched nothing. Kept only when a key is declared
+     * by at least two tools in the service or by a curated one, so one-off
+     * generated parameters do not become advice. */
+    siblingSpellings(tool, unknownKeys) {
+        const self = this.tools.find((t) => t.name === tool);
+        if (!self)
+            return [];
+        const declared = new Set(Object.keys(self.inputShape));
+        const byKey = new Map();
+        for (const t of this.tools) {
+            // Only tools the agent can actually see in tools/list. A hint naming a
+            // registered-but-unadvertised generated tool turns a recoverable error
+            // into a dead end: in curated mode 353 tools are registered and 181 are
+            // advertised, and the hint used to reach for any of them.
+            if (t.service !== self.service || t.name === tool || !this.isVisible(t))
+                continue;
+            for (const key of Object.keys(t.inputShape)) {
+                if (declared.has(key))
+                    continue;
+                const e = byKey.get(key) ?? { tools: [], curated: false };
+                e.tools.push(t.name);
+                if (!t.generated)
+                    e.curated = true;
+                byKey.set(key, e);
+            }
+        }
+        const candidates = [...byKey.entries()].filter(([, e]) => e.tools.length >= 2 || e.curated);
+        // Reuse the tiered matcher rather than a substring test: the motivating
+        // case (parentId against parentFolderId) fails containment and edit
+        // distance alike, which is the whole reason that matcher exists.
+        const keys = candidates.map(([key]) => key);
+        const hits = new Set(unknownKeys.flatMap((k) => suggestKeys(k, keys)));
+        return candidates
+            .filter(([key]) => hits.has(key))
+            .slice(0, 2)
+            .map(([key, e]) => ({ key, tools: e.tools }));
+    }
     catalog(service, query) {
         const q = query?.trim().toLowerCase();
         return this.tools
@@ -202,8 +309,38 @@ export class ToolRegistry {
             summary: t.description,
             args: Object.keys(t.inputShape),
             cud: t.cud,
+            ...(this.isUngrantable(t) ? { unreachable: true } : {}),
         }));
     }
+    /** The metrics recorder, for hook sites (escape hatch); null when off. */
+    get usageMetrics() {
+        return this.metrics;
+    }
+    /** Every registered tool name, hidden ones included: they stay callable, so
+     * a did-you-mean may legitimately point at one. */
+    toolNames() {
+        return this.tools.map((t) => t.name);
+    }
+    /** Membership test against the REGISTERED tool set (hidden tools included:
+     * they stay callable). The metrics tap uses this so a client-supplied name
+     * can never enter the closed vocabulary. */
+    hasTool(name) {
+        return this.tools.some((t) => t.name === name);
+    }
+    /** 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. */
+    opNames(service) {
+        const strip = (n) => (n.startsWith(`${service}_`) ? n.slice(service.length + 1) : n);
+        const curated = [];
+        const generated = [];
+        for (const t of this.tools) {
+            if (t.meta || t.service !== service)
+                continue;
+            (t.generated ? generated : curated).push(strip(t.name));
+        }
+        return { curated: [...new Set(curated)], generated: [...new Set(generated)] };
+    }
     reveal(service) {
         if (this.revealed.has(service))
             return false;
@@ -236,8 +373,40 @@ export class ToolRegistry {
             return this.mode;
         return this.expanded ? 'curated' : 'lazy';
     }
+    /**
+     * True when NO bundle in the catalog grants any of the method's alternative
+     * scopes, so the call cannot succeed on any account under any configuration.
+     * Static: it asks the catalog, not an account, so it is safe to cache.
+     * `classifyScope` with nothing granted and no profile reports `add_bundle`
+     * for a scope some bundle could supply and `unknown_scope` only when none
+     * can, which is exactly the distinction wanted here.
+     */
+    isUngrantable(tool) {
+        if (!tool.requiredScopes || tool.requiredScopes.length === 0)
+            return false;
+        const cached = this.ungrantable.get(tool.name);
+        if (cached !== undefined)
+            return cached;
+        // EVERY alternative must be ungrantable. `classifyMethodScopes` cannot
+        // answer this: `add_bundle` and `unknown_scope` share the
+        // `not_requestable` rank, so its first-best match hides a grantable
+        // alternative that appears later in the list. Discovery scope lists are
+        // ANY-OF, so one grantable alternative makes the method reachable.
+        const verdict = tool.requiredScopes.every((scope) => {
+            const c = classifyScope(scope, EMPTY_SCOPES, EMPTY_SCOPES);
+            return c.state === 'not_requestable' && c.reason === 'unknown_scope';
+        });
+        this.ungrantable.set(tool.name, verdict);
+        return verdict;
+    }
     isVisible(tool) {
         const mode = this.effectiveMode();
+        // Advertising a tool that can never succeed spends context budget to hand
+        // the agent a dead end. It stays registered and callable, so calling it by
+        // name still produces the real scope error plus its remediation, and
+        // {service}_discover still lists it, marked.
+        if (!tool.meta && this.isUngrantable(tool))
+            return false;
         return (tool.meta ||
             mode === 'eager' ||
             this.revealed.has(tool.service) ||
@@ -254,7 +423,11 @@ export class ToolRegistry {
         if (this.tools.length === 0) {
             throw new Error('installListHandler() requires at least one registered tool');
         }
-        this.server.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        this.server.server.setRequestHandler('tools/list', async () => ({
+            // The wire Tool is hand-built because the SDK's own types drop the
+            // anthropic/* _meta keys honoring clients read. z.toJSONSchema emits a
+            // valid draft-7 object schema by construction, which the SDK's recursive
+            // JSON-Schema type cannot infer from our cached `unknown`.
             tools: this.tools.filter((t) => this.isVisible(t)).map((t) => this.toToolJson(t)),
         }));
     }

package/dist/scope-catalog.js

@@ -108,6 +108,22 @@ export const BUNDLE_CATALOG = {
         description: 'Read Gmail Postmaster Tools deliverability data.',
         risk: 'low',
     },
+    analytics: {
+        scopes: ['https://www.googleapis.com/auth/analytics.readonly'],
+        description: 'Read Google Analytics (GA4): run reports and inspect accounts, properties and their configuration.',
+        risk: 'low',
+    },
+    // Includes readonly so it is self-sufficient: analytics.edit alone does not
+    // authorize Data API reads. The smaller `analytics` bundle stays the hint
+    // target for read scopes (scope-observability sorts bundles by size).
+    analytics_write: {
+        scopes: [
+            'https://www.googleapis.com/auth/analytics.readonly',
+            'https://www.googleapis.com/auth/analytics.edit',
+        ],
+        description: 'Edit Google Analytics (GA4) configuration: properties, data streams, key events, custom dimensions and metrics. Includes read access.',
+        risk: 'medium',
+    },
     groupssettings: {
         scopes: ['https://www.googleapis.com/auth/apps.groups.settings'],
         description: 'Change Google Groups settings for the domain.',

package/dist/services.d.ts

@@ -9,3 +9,11 @@ export declare const GENERATED_GATES: Record<string, {
     enabled: () => boolean;
     hint: string;
 }>;
+/**
+ * Message for a `tools/call` naming a tool that is not registered. The SDK's
+ * own answer is a bare "Tool X not found", which reads identically for a typo,
+ * for a service gated behind a scope bundle, and for an API this server has
+ * never heard of. Those need different next steps, and the server knows which
+ * is which: it composed the enabled-service list at boot.
+ */
+export declare function unknownToolMessage(registry: ToolRegistry, name: string): string;

package/dist/services.js

@@ -11,7 +11,10 @@ import { registerSlidesTools } from './tools/slides.js';
 import { registerFormsTools } from './tools/forms.js';
 import { registerChatTools } from './tools/chat.js';
 import { registerAdminTools } from './tools/admin.js';
+import { registerAnalyticsTools } from './tools/analytics.js';
 import { getOptionalBundles, getAdminAccounts } from './auth.js';
+import { GENERATED_SERVICES } from './tools/generated/index.js';
+import { suggestKeys } from './arg-strict.js';
 export const SERVICES = [
     { name: 'gmail', register: registerGmailTools },
     { name: 'drive', register: registerDriveTools },
@@ -25,9 +28,10 @@ export const SERVICES = [
     { name: 'slides', register: registerSlidesTools, enabled: () => new Set(getOptionalBundles()).has('slides') },
     { name: 'forms', register: registerFormsTools, enabled: () => new Set(getOptionalBundles()).has('forms') },
     { name: 'chat', register: registerChatTools, enabled: () => new Set(getOptionalBundles()).has('chat') },
+    { name: 'analytics', register: registerAnalyticsTools, enabled: () => { const b = new Set(getOptionalBundles()); return b.has('analytics') || b.has('analytics_write'); } },
     { name: 'admin', register: registerAdminTools, enabled: () => getAdminAccounts().length > 0 },
 ];
-// Generated-only services with opt-in scopes; admin/forms/chat reuse their curated gate in buildRegistry,
+// Generated-only services with opt-in scopes; admin/forms/chat/analytics reuse their curated gate in buildRegistry,
 // and workspaceevents is deliberately absent — no dedicated scope (subscriptions use resource scopes).
 const bundleGate = (name) => ({
     enabled: () => new Set(getOptionalBundles()).has(name),
@@ -49,3 +53,26 @@ export const GENERATED_GATES = {
     script: bundleGate('script'),
     vault: bundleGate('vault'),
 };
+/**
+ * Message for a `tools/call` naming a tool that is not registered. The SDK's
+ * own answer is a bare "Tool X not found", which reads identically for a typo,
+ * for a service gated behind a scope bundle, and for an API this server has
+ * never heard of. Those need different next steps, and the server knows which
+ * is which: it composed the enabled-service list at boot.
+ */
+export function unknownToolMessage(registry, name) {
+    const near = suggestKeys(name, registry.toolNames(), 3);
+    if (near.length > 0)
+        return `Tool ${name} not found. Did you mean: ${near.join(', ')}?`;
+    // A service that EXISTS in the build but registered nothing is gated, not
+    // misspelled, and the fix is a scope bundle rather than a different name.
+    const service = name.split('_')[0];
+    const known = SERVICES.some((s) => s.name === service) || GENERATED_SERVICES.some((s) => s.name === service);
+    if (known && !registry.services().includes(service)) {
+        const hint = service === 'admin'
+            ? 'set admin on an account/profile (or GOOGLE_ADMIN_ACCOUNTS), then re-auth'
+            : (GENERATED_GATES[service]?.hint ?? `add "${service}" to an account's scope profile (or legacy GOOGLE_OPTIONAL_SCOPES), then re-auth`);
+        return `Tool ${name} not found: the "${service}" service is not enabled in this deployment. To enable it, ${hint}. Until then, google_api_call can reach the same API.`;
+    }
+    return `Tool ${name} not found. Call {service}_discover to list a service's tools, or google_api_search to find a method on any Google API.`;
+}

package/dist/setup-prompt.d.ts

@@ -1,4 +1,4 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { McpServer } from "@modelcontextprotocol/server";
 export interface SetupOptions {
     /** Public base URL when serving over HTTP; used for the Web client redirect. */
     publicUrl?: string;

package/dist/setup-prompt.js

@@ -47,7 +47,7 @@ export function registerSetupPrompt(server) {
     server.registerPrompt('setup', {
         title: 'Set up mcp-google-multi',
         description: 'Guided Google Cloud Console prelude: project, APIs, consent screen, OAuth client, and credentials. The one-time browser setup that has no API.',
-        argsSchema: { publicUrl: z.string().optional().describe('Public base URL when serving over HTTP (for the Web OAuth client redirect). Omit for stdio.') },
+        argsSchema: z.object({ publicUrl: z.string().optional().describe('Public base URL when serving over HTTP (for the Web OAuth client redirect). Omit for stdio.') }),
     }, (args) => ({
         messages: [
             {

package/dist/tools/_coerce.d.ts

@@ -1,4 +1,9 @@
 import { z } from 'zod';
 export declare function coerceArray<T extends z.ZodTypeAny>(element: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<T>>;
 export declare function coerceJson<T extends z.ZodTypeAny>(schema: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, T>;
+/** Numeric args arrive string-encoded from some clients. Arg normalization
+ * runs on BOTH transports, but it only coerces keys it RENAMED, so a value
+ * sent under the correct key never passes through it and the coercion has to
+ * live in the schema. */
+export declare function coerceNumber<T extends z.ZodTypeAny>(schema: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, T>;
 export declare const coerceBoolean: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>;

package/dist/tools/_coerce.js

@@ -22,6 +22,17 @@ export function coerceArray(element) {
 export function coerceJson(schema) {
     return z.preprocess((val) => (typeof val === 'string' ? parseJsonLoose(val) : val), schema);
 }
+/** Numeric args arrive string-encoded from some clients. Arg normalization
+ * runs on BOTH transports, but it only coerces keys it RENAMED, so a value
+ * sent under the correct key never passes through it and the coercion has to
+ * live in the schema. */
+export function coerceNumber(schema) {
+    return z.preprocess((val) => {
+        if (typeof val === 'string' && val.trim() !== '' && !Number.isNaN(Number(val)))
+            return Number(val);
+        return val;
+    }, schema);
+}
 export const coerceBoolean = z.preprocess((val) => {
     if (typeof val === 'boolean')
         return val;