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

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,11 @@ 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;
@@ -81,12 +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. */
@@ -94,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) => {
@@ -125,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) };
@@ -154,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
@@ -194,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) => {
@@ -225,6 +254,51 @@ export class ToolRegistry {
         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
@@ -235,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;
@@ -269,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) ||
@@ -287,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;

package/dist/tools/_errors.d.ts

@@ -1,16 +1,34 @@
 import type { Account } from '../accounts.js';
+/** A 403 means "missing scope" and "you cannot touch this resource" alike, and
+ * a single hint slot for both is what told callers to add a bundle they had
+ * already granted. Services now supply one hint per meaning. A bare string
+ * stays accepted and keeps its old meaning, the scope one. */
+export interface ServiceHints {
+    scope?: string;
+    resource?: string;
+}
 export interface ErrorEnvelope {
     error: string;
     message: string;
     hint?: string;
     retriable: boolean;
-    account: string;
+    /** Optional because some failures genuinely precede account resolution (an
+     * undeclared argument, a wizard step before the alias is known). Every
+     * producer that HAS an account must still pass it. */
+    account?: string;
 }
-export declare function mapGoogleError(error: any, account: Account, forbiddenHint?: string, scopeContext?: () => {
+/** The ONE extraction point for every Google-originated message. Without the
+ * raw-body guard, gaxios copies the entire response body into error.message,
+ * which put 8.5 KB of Google's HTML front-end page inside a JSON envelope. */
+export declare function safeMessage(error: any, payload?: any, status?: number | undefined): string;
+export declare function mapGoogleError(error: any, account: Account, serviceHints?: string | ServiceHints, scopeContext?: () => {
     hint: string;
     retriable: boolean;
 } | null): ErrorEnvelope;
-export declare function handleGoogleApiError(error: any, account: Account, forbiddenHint?: string, scopeContext?: () => {
+/** Bound the SERIALIZED envelope, not just the message: an authored hint can
+ * be long too, and the error path had no cap at all before this. */
+export declare function stringifyEnvelope(envelope: ErrorEnvelope): string;
+export declare function handleGoogleApiError(error: any, account: Account, serviceHints?: string | ServiceHints, scopeContext?: () => {
     hint: string;
     retriable: boolean;
 } | null): {
@@ -20,3 +38,13 @@ export declare function handleGoogleApiError(error: any, account: Account, forbi
     }[];
     isError: true;
 };
+/** Local argument rejection, before any Google call. Same envelope as
+ * mapGoogleError so a caller parses one shape. The slug literal stays inline
+ * because the KNOWN_ERROR_SLUGS honesty test greps for `error: '<slug>'`. */
+export declare function invalidParams(account: Account | undefined, message: string, hint: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};