mcp-google-multi 6.0.0-alpha.4 → 6.0.0-alpha.41

package/dist/arg-strict.js

@@ -0,0 +1,163 @@
+// Unknown-argument screening (backlog item 14). zod strips undeclared keys
+// before a handler runs, so a misremembered argument name used to produce a
+// SUCCESS response with wrong behavior: `parentId` on drive_create_folder was
+// dropped and the folder landed in My Drive root. Field-reported, then
+// reproduced: the typo, the correct name and a wholly invented key all
+// returned byte-identical responses.
+//
+// This module is pure and holds no registry reference. It never rewrites a key
+// and never touches a VALUE: it only decides that a key is undeclared, and
+// suggests what the caller probably meant. Rewriting would risk sending a real
+// value to Google on a guess, which is strictly worse than refusing.
+import { editDistance } from './scope-catalog.js';
+/**
+ * `GOOGLE_ARG_UNKNOWN`: reject | warn | off. A typo in the VALUE still falls
+ * back to `warn`, not to the default: an operator who misspells the setting
+ * has said nothing about which behavior they want, and guessing the strict
+ * one would turn a config typo into failing tool calls.
+ */
+export function unknownArgMode(env = process.env) {
+    const raw = (env.GOOGLE_ARG_UNKNOWN ?? '').trim().toLowerCase();
+    if (raw === '')
+        return DEFAULT_MODE;
+    if (raw === 'reject' || raw === 'warn' || raw === 'off')
+        return raw;
+    process.stderr.write(`GOOGLE_ARG_UNKNOWN="${raw}" is not valid (reject | warn | off); using warn\n`);
+    return 'warn';
+}
+// The staged rollout is over: `warn` shipped first as pure observability, and
+// this is the flip it was staging for. An undeclared argument is dropped by
+// zod before the handler runs, so `warn` means the CLIENT sees a confident
+// success for a call the server did not perform: drive_list with a misspelled
+// folder key returned the My Drive root, byte-identical to no argument at all.
+// A wrong answer that reads as right is the failure mode agents recover from
+// worst, so the default refuses the call and says what it probably meant.
+const DEFAULT_MODE = 'reject';
+/** Tools that legitimately accept open-ended top-level keys. Empty at 6.0.0:
+ * the escape hatch is NOT one, because its open-endedness lives in the VALUES
+ * of queryParams/body, never in its six fixed top-level keys. */
+export const STRICT_EXEMPT_TOOLS = new Set();
+/** Keys a CLIENT adds on its own, not keys the model chose. `random_string`
+ * is the long-standing probe some clients send to a tool they read as taking
+ * no arguments; the others are call-plumbing that bridges and proxies have
+ * been observed to fold into `arguments` instead of `params._meta`, where the
+ * spec puts them. Rejecting these would fail a call the model got right.
+ * Measured against the full 978-tool surface: none is a declared key. */
+const CLIENT_ARTIFACT_KEYS = new Set([
+    'random_string',
+    'toolCallId',
+    'tool_call_id',
+    'tool_call_description',
+]);
+/** Metadata a client may legitimately attach. Measured against all registered
+ * tools: no declared key starts with `_` or contains `/`, so neither rule can
+ * shadow a real parameter. */
+export function isExemptKey(key) {
+    return key.startsWith('_') || key.includes('/') || CLIENT_ARTIFACT_KEYS.has(key);
+}
+/** Generic words that must never be offered as a suggestion on containment
+ * alone; they match far too much to be useful. */
+const GENERIC = new Set(['id', 'name', 'title', 'body', 'parent', 'text', 'content', 'type', 'value', 'key', 'data']);
+const flatten = (s) => s.toLowerCase().replace(/[^a-z0-9]/g, '');
+function tokens(s) {
+    return s
+        .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+        .split(/[\s_\-.]+/)
+        .map((t) => t.toLowerCase())
+        .filter(Boolean);
+}
+/**
+ * Rank declared keys for an unknown key. Tiers, best non-empty tier wins:
+ *   0 same key modulo case and separators
+ *   1 every token of the unknown key appears in the declared key
+ *   2 substring containment of the flattened forms
+ *   3 a genuine typo by edit distance
+ * Plain edit distance alone cannot carry this: parentid -> parentfolderid is
+ * distance 6, well past any sane threshold, which is why tier 1 exists.
+ */
+export function suggestKeys(unknown, declared, limit = 2) {
+    const uFlat = flatten(unknown);
+    const uTok = tokens(unknown);
+    const tiers = [[], [], [], []];
+    for (const key of declared) {
+        const kFlat = flatten(key);
+        const kTok = tokens(key);
+        if (kFlat === uFlat) {
+            tiers[0].push({ key, rank: 0 });
+            continue;
+        }
+        if (uTok.length >= 2 && uTok.every((t) => kTok.includes(t))) {
+            tiers[1].push({ key, rank: Math.abs(kTok.length - uTok.length) });
+            continue;
+        }
+        if (uFlat.length >= 4 && !GENERIC.has(kFlat) && (kFlat.includes(uFlat) || uFlat.includes(kFlat))) {
+            tiers[2].push({ key, rank: Math.abs(kFlat.length - uFlat.length) });
+            continue;
+        }
+        const d = editDistance(uFlat, kFlat);
+        if (d <= Math.max(1, Math.floor(uFlat.length / 4)))
+            tiers[3].push({ key, rank: d });
+    }
+    const tier = tiers.find((t) => t.length > 0);
+    if (!tier)
+        return [];
+    // Stable: declaration order breaks rank ties.
+    return tier
+        .map((e, i) => ({ ...e, i }))
+        .sort((a, b) => a.rank - b.rank || a.i - b.i)
+        .slice(0, limit)
+        .map((e) => e.key);
+}
+/**
+ * Split a call's post-rename keys into declared, redundant-duplicate and
+ * genuinely unknown. `declared` is the tool's full declared key list.
+ */
+export function screenArguments(tool, args, declared) {
+    const out = { unknown: [], redundant: [] };
+    if (STRICT_EXEMPT_TOOLS.has(tool) || declared.length === 0)
+        return out;
+    const declaredSet = new Set(declared);
+    for (const key of Object.keys(args)) {
+        if (declaredSet.has(key) || isExemptKey(key))
+            continue;
+        const suggestions = suggestKeys(key, declared);
+        // The caller sent both spellings, so the declared one already won and the
+        // outcome is what it has always been. Never fail a call that works today.
+        if (suggestions.some((s) => s in args)) {
+            out.redundant.push(key);
+            continue;
+        }
+        out.unknown.push({ sent: key, suggestions });
+    }
+    return out;
+}
+/** The agent-facing envelope. Values are never included, only key names. */
+export function unknownArgEnvelope(tool, unknown, declared, account, siblings = []) {
+    const names = unknown.map((u) => `"${u.sent}"`).join(', ');
+    const accepts = `This tool accepts: ${declared.join(', ')}.`;
+    const suggested = unknown.flatMap((u) => u.suggestions);
+    let hint;
+    if (suggested.length > 0) {
+        const did = unknown
+            .filter((u) => u.suggestions.length > 0)
+            .map((u) => u.suggestions.map((s) => `"${s}"`).join(' or '))
+            .join(', ');
+        hint = `Did you mean ${did}? ${accepts}`;
+    }
+    else if (siblings.length > 0) {
+        const spelled = siblings
+            .map((s) => `"${s.key}" (${s.tools.slice(0, 3).join(', ')})`)
+            .join(' and ');
+        hint = `${accepts} Other tools in this service spell a similar argument ${spelled}.`;
+    }
+    else {
+        hint = accepts;
+    }
+    return {
+        error: 'unknown_argument',
+        message: `${tool} does not accept ${names}. Nothing was sent to Google.`,
+        hint,
+        retriable: false,
+        ...(account !== undefined ? { account } : {}),
+    };
+}

package/dist/auth.js

@@ -1,12 +1,10 @@
-import { OAuth2Client } from 'googleapis-common';
-import http from 'node:http';
-import { URL } from 'node:url';
 import { randomBytes } from 'node:crypto';
 import { openUrl } from './open-url.js';
 import { ACCOUNTS, getAccountSet } from './accounts.js';
 import { ADMIN_SCOPES, BUNDLE_CATALOG, closestBundle, resolveBundleAliases } from './scope-catalog.js';
 import { resolveMasterKey } from './master-key.js';
 import { writeToken } from './token-store.js';
+import { buildConsentClient, openLoopbackConsent, TESTING_MODE_WARNING } from './oauth-consent.js';
 // Personal (non-Workspace) accounts 403 on admin scopes; ADMIN_SCOPES stays per-account opt-in, never granted by default.
 export const BASE_SCOPES = [
     'https://www.googleapis.com/auth/gmail.modify',
@@ -134,7 +132,11 @@ export async function runAuthFlow(args) {
     // Auto-provisions on a fresh install (env > keychain > file > generate);
     // resolves eagerly so a provisioning failure surfaces before the browser opens.
     resolveMasterKey();
-    const oauth2Client = new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost:4242/oauth2callback');
+    // Shared ephemeral-port loopback flow (oauth-consent.ts): listen first, then
+    // build the auth URL from the assigned redirect. CLI gets a patient timeout;
+    // errors propagate to main()'s fatal handler like every other CLI failure.
+    const loop = await openLoopbackConsent({ timeoutMs: 10 * 60_000 });
+    const oauth2Client = buildConsentClient(loop.redirect);
     // CSRF protection for the OAuth callback (RFC 6749 §10.12).
     const expectedState = randomBytes(32).toString('hex');
     const authorizeUrl = oauth2Client.generateAuthUrl({
@@ -149,72 +151,13 @@ export async function runAuthFlow(args) {
     if (getAdminAccounts().includes(alias)) {
         console.log('  ⚠ Admin scopes included — this account will be granted Workspace admin access.');
     }
-    console.log(`Opening browser for authorization...`);
-    return new Promise((resolve, reject) => {
-        const server = http
-            .createServer(async (req, res) => {
-            try {
-                if (req.url && req.url.startsWith('/oauth2callback')) {
-                    const qs = new URL(req.url, 'http://localhost:4242').searchParams;
-                    const error = qs.get('error');
-                    if (error) {
-                        res.writeHead(400, { 'Content-Type': 'text/plain' });
-                        res.end(`Authorization denied: ${error}`);
-                        server.close();
-                        server.closeAllConnections();
-                        reject(new Error(`Authorization denied: ${error}`));
-                        return;
-                    }
-                    const code = qs.get('code');
-                    if (!code) {
-                        res.writeHead(400, { 'Content-Type': 'text/plain' });
-                        res.end('No authorization code received.');
-                        server.close();
-                        server.closeAllConnections();
-                        reject(new Error('No authorization code received'));
-                        return;
-                    }
-                    const returnedState = qs.get('state');
-                    if (returnedState !== expectedState) {
-                        res.writeHead(400, { 'Content-Type': 'text/plain' });
-                        res.end('State mismatch — possible CSRF attempt. Aborting.');
-                        server.close();
-                        server.closeAllConnections();
-                        reject(new Error('OAuth state token mismatch'));
-                        return;
-                    }
-                    const { tokens } = await oauth2Client.getToken(code);
-                    writeToken(alias, tokens);
-                    res.writeHead(200, { 'Content-Type': 'text/html' });
-                    res.end('<h2>Authentication successful!</h2><p>You can close this tab.</p>');
-                    server.close();
-                    server.closeAllConnections();
-                    console.log(`Token saved (encrypted) for ${alias}.`);
-                    console.log('Next: authenticate your other aliases, then verify with: mcp-google-multi config check');
-                    resolve();
-                }
-            }
-            catch (e) {
-                res.writeHead(500, { 'Content-Type': 'text/plain' });
-                res.end('Internal error during authentication.');
-                server.close();
-                server.closeAllConnections();
-                reject(e);
-            }
-        })
-            // Bind to loopback only — never expose the OAuth callback to the local network.
-            .listen(4242, '127.0.0.1', () => {
-            // Always print the URL first: the browser launch is best-effort and
-            // silently does nothing on headless/SSH sessions.
-            console.log(`Opening your browser to authorize "${alias}". If nothing opens, visit:\n${authorizeUrl}`);
-            openUrl(authorizeUrl);
-        });
-        server.on('error', (err) => {
-            if (err.code === 'EADDRINUSE') {
-                console.error('Port 4242 is already in use. Close the process using it and retry.');
-                process.exit(1);
-            }
-            reject(err);
-        });
-    });
+    // Always print the URL first: the browser launch is best-effort and
+    // silently does nothing on headless/SSH sessions.
+    console.log(`Opening your browser to authorize "${alias}". If nothing opens, visit:\n${authorizeUrl}`);
+    openUrl(authorizeUrl);
+    const tokens = await loop.finish(oauth2Client, expectedState);
+    writeToken(alias, tokens);
+    console.log(`Token saved (encrypted) for ${alias}.`);
+    console.log(TESTING_MODE_WARNING);
+    console.log('Next: authenticate your other aliases, then verify with: mcp-google-multi config check');
 }

package/dist/boot-gates.d.ts

@@ -0,0 +1,26 @@
+export interface MtBootGates {
+    /** True = multi-tenant deployment: the server boots with zero accounts
+     * (tenants provision in-band) and the provisioning gate below replaces the
+     * flat owner-allowlist requirement. */
+    multiTenant: boolean;
+    /** Fail-fast replacement for the E_OWNER_EMAILS_REQUIRED check. MUST refuse
+     * (exit/throw) when no valid provisioning mechanism is configured — an
+     * ungated HTTP endpoint must never boot, whatever the condition checked. */
+    assertProvisioningGate: () => void;
+}
+export declare function setMtBootGates(g: MtBootGates | null): void;
+export declare function mtBootGates(): MtBootGates | null;
+export declare function isMultiTenantBoot(): boolean;
+/** BR-4 applies to stdio always, and to HTTP only when single-owner: a
+ * multi-tenant HTTP deploy starts empty by design. */
+export declare function accountsAssertRequired(wantStdio: boolean, multiTenant: boolean): boolean;
+/** A set GOOGLE_ACCOUNTS on a multi-tenant boot is refused at DEPLOY time:
+ * the env registry is process-wide, so it would graft one operator's accounts
+ * onto every tenant and turn every tenant's first wizard call into a dead
+ * end (the per-call E_ENV_ACCOUNTS_MODE guard), N confusing failures instead
+ * of one clear one. */
+export declare function assertNoEnvAccountsMode(env?: NodeJS.ProcessEnv): void;
+/** Same class, second vector: GOOGLE_OPTIONAL_SCOPES is a process-wide legacy
+ * global scope profile, so on a multi-tenant box one operator's scope choice
+ * would silently apply to every tenant's consent. */
+export declare function assertNoEnvOptionalScopesMode(env?: NodeJS.ProcessEnv): void;

package/dist/boot-gates.js

@@ -0,0 +1,38 @@
+// S1.16: multi-tenant boot gates. The free core never sets these — every
+// helper reduces to today's single-owner behavior when no gates are
+// installed. Deliberately a side-effect-free module (accounts.ts/auth.ts
+// resolve env at import time) so the tenancy module can import it cheaply.
+import { failStartup } from './config-file.js';
+let gates = null;
+export function setMtBootGates(g) {
+    gates = g;
+}
+export function mtBootGates() {
+    return gates;
+}
+export function isMultiTenantBoot() {
+    return gates?.multiTenant === true;
+}
+/** BR-4 applies to stdio always, and to HTTP only when single-owner: a
+ * multi-tenant HTTP deploy starts empty by design. */
+export function accountsAssertRequired(wantStdio, multiTenant) {
+    return wantStdio || !multiTenant;
+}
+/** A set GOOGLE_ACCOUNTS on a multi-tenant boot is refused at DEPLOY time:
+ * the env registry is process-wide, so it would graft one operator's accounts
+ * onto every tenant and turn every tenant's first wizard call into a dead
+ * end (the per-call E_ENV_ACCOUNTS_MODE guard), N confusing failures instead
+ * of one clear one. */
+export function assertNoEnvAccountsMode(env = process.env) {
+    if (env.GOOGLE_ACCOUNTS?.trim()) {
+        failStartup('E_ENV_ACCOUNTS_MODE_MT', 'GOOGLE_ACCOUNTS must not be set on a multi-tenant deployment; accounts are linked in-band per tenant. Unset it and restart.');
+    }
+}
+/** Same class, second vector: GOOGLE_OPTIONAL_SCOPES is a process-wide legacy
+ * global scope profile, so on a multi-tenant box one operator's scope choice
+ * would silently apply to every tenant's consent. */
+export function assertNoEnvOptionalScopesMode(env = process.env) {
+    if (env.GOOGLE_OPTIONAL_SCOPES?.trim()) {
+        failStartup('E_ENV_OPTIONAL_SCOPES_MT', 'GOOGLE_OPTIONAL_SCOPES must not be set on a multi-tenant deployment; scopes are chosen per tenant at consent. Unset it and restart.');
+    }
+}

package/dist/client.js

@@ -2,22 +2,32 @@ import { OAuth2Client } from 'googleapis-common';
 import { getAccountSet, refreshAccountSetIfStale } from './accounts.js';
 import { readToken, updateToken } from './token-store.js';
 import { reauthHint } from './reauth-hint.js';
+/** A local precondition failure, carrying a code the error mapper classifies
+ * on. Without it these land on the generic floor and read as Google errors. */
+function tagged(message, code) {
+    return Object.assign(new Error(message), { code });
+}
 export async function getClient(account) {
     // BR-7: lazy cross-process reload — one stat per dispatch, no watcher;
     // reload failures keep the last-good registry, never kill the server.
     refreshAccountSetIfStale();
     const config = getAccountSet().configs[account];
     if (!config) {
-        throw new Error(`Unknown account "${account}". Valid aliases: ${getAccountSet().aliases.join(', ')}`);
+        // Tagged so mapGoogleError can classify it. Untagged, a caller's typo in
+        // an alias came back as `upstream_error` with "Unclassified error", i.e.
+        // the server blaming Google for a local argument mistake.
+        throw tagged(`Unknown account "${account}". Valid aliases: ${getAccountSet().aliases.join(', ')}`, 'E_UNKNOWN_ACCOUNT');
     }
     if (!process.env.GOOGLE_CLIENT_ID || !process.env.GOOGLE_CLIENT_SECRET) {
-        throw new Error('GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET must be set. ' +
-            'Check that .env exists in the project root or pass them as env vars.');
+        throw tagged('GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET must be set. ' +
+            'Check that .env exists in the project root or pass them as env vars.', 'E_NO_OAUTH_CLIENT');
     }
-    const oauth2Client = new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost:4242/oauth2callback');
+    // Redirect URI is unused on the refresh-token grant; consent flows bind an
+    // ephemeral loopback port at auth time (oauth-consent.ts).
+    const oauth2Client = new OAuth2Client(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost/oauth2callback');
     const tokenData = readToken(account);
     if (!tokenData) {
-        throw new Error(`No token found for account "${account}" (${config.email}). ${reauthHint(account)}`);
+        throw tagged(`No token found for account "${account}" (${config.email}). ${reauthHint(account)}`, 'E_NO_TOKEN');
     }
     oauth2Client.setCredentials(tokenData);
     oauth2Client.on('tokens', (tokens) => {

package/dist/config-file.d.ts

@@ -1,7 +1,20 @@
 export declare const CONFIG_VERSION = 1;
 export declare function configDir(env?: NodeJS.ProcessEnv): string;
 export declare function configFilePath(env?: NodeJS.ProcessEnv): string;
+export declare function tenantsDir(env?: NodeJS.ProcessEnv): string;
+export declare function tenantConfigFilePath(tenantId: string, env?: NodeJS.ProcessEnv): string;
+export declare function tenantTokenDir(tenantId: string, env?: NodeJS.ProcessEnv): string;
+/** Create and permission-harden the tenant directory chain. mkdirSync's
+ * recursive mode only stamps the DEEPEST newly-created dir, so every level
+ * gets an explicit chmod: the shared tenants/ root (created by whichever
+ * tenant provisions first) must never stay group-readable. */
+export declare function ensureTenantDirs(tenantId: string, env?: NodeJS.ProcessEnv): {
+    configFile: string;
+    tokenDir: string;
+};
 export declare const ALIAS_RE: RegExp;
+export declare const RESERVED_ALIASES: string[];
+export declare function isReservedAlias(name: string): boolean;
 export interface ConfigFile {
     version: number;
     accounts?: Record<string, {
@@ -17,6 +30,7 @@ export interface ConfigFile {
     defaultAccount?: string;
     discovery?: 'lazy' | 'curated' | 'eager';
     toolsets?: string;
+    usageMetrics?: boolean;
 }
 export declare function failStartup(slug: string, message: string): never;
 export declare class ConfigFileError extends Error {

package/dist/config-file.js

@@ -10,6 +10,38 @@ export function configDir(env = process.env) {
 export function configFilePath(env = process.env) {
     return path.join(configDir(env), 'config.json');
 }
+export function tenantsDir(env = process.env) {
+    return path.join(configDir(env), 'tenants');
+}
+// A tenant id becomes a filesystem path segment exactly like an account
+// alias, so it rides the same traversal guard.
+function assertTenantId(tenantId) {
+    if (!ALIAS_RE.test(tenantId) || isReservedAlias(tenantId)) {
+        throw new Error(`E_TENANT_ID_INVALID: invalid tenant id "${tenantId}".`);
+    }
+}
+export function tenantConfigFilePath(tenantId, env = process.env) {
+    assertTenantId(tenantId);
+    return path.join(tenantsDir(env), tenantId, 'config.json');
+}
+export function tenantTokenDir(tenantId, env = process.env) {
+    assertTenantId(tenantId);
+    return path.join(tenantsDir(env), tenantId, 'tokens');
+}
+/** Create and permission-harden the tenant directory chain. mkdirSync's
+ * recursive mode only stamps the DEEPEST newly-created dir, so every level
+ * gets an explicit chmod: the shared tenants/ root (created by whichever
+ * tenant provisions first) must never stay group-readable. */
+export function ensureTenantDirs(tenantId, env = process.env) {
+    const tokenDir = tenantTokenDir(tenantId, env);
+    const levels = [configDir(env), tenantsDir(env), path.join(tenantsDir(env), tenantId), tokenDir];
+    for (const dir of levels) {
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        if (process.platform !== 'win32')
+            fs.chmodSync(dir, 0o700);
+    }
+    return { configFile: tenantConfigFilePath(tenantId, env), tokenDir };
+}
 // Alias charset is load-bearing security, not cosmetics: the alias becomes a
 // tokenDir path segment (encPath), so this guard blocks path traversal.
 export const ALIAS_RE = /^[a-zA-Z0-9_-]+$/;
@@ -22,7 +54,10 @@ const accountEntrySchema = z.strictObject({
 // masterKey, jwtKey, clientId) fails validation, structurally enforcing
 // secrets-env-only. scopeProfiles/defaultAccount/discovery/toolsets are part
 // of the frozen envelope; their consumers land in later slices.
-const RESERVED_ALIASES = ['__proto__', 'constructor', 'prototype'];
+export const RESERVED_ALIASES = ['__proto__', 'constructor', 'prototype'];
+export function isReservedAlias(name) {
+    return RESERVED_ALIASES.includes(name);
+}
 const configSchema = z.strictObject({
     version: z.number().int(),
     accounts: z.record(z.string().regex(ALIAS_RE), accountEntrySchema).optional(),
@@ -36,6 +71,10 @@ const configSchema = z.strictObject({
     defaultAccount: z.string().optional(),
     discovery: z.enum(['lazy', 'curated', 'eager']).optional(),
     toolsets: z.string().optional(),
+    // Local usage metrics (metrics-feature-spec): absent = off. Downgrade rule:
+    // a pre-6.0 build reading a config carrying this key fails E_CONFIG_INVALID
+    // (strictObject); remove the key first.
+    usageMetrics: z.boolean().optional(),
 });
 export function failStartup(slug, message) {
     process.stderr.write(`${slug}: ${message}\n`);

package/dist/discover.js

@@ -1,8 +1,32 @@
 import { z } from 'zod';
 import { describePolicy } from './write-control.js';
+// The description budget is the whole point of lazy mode: a full op list per
+// service put lazy tools/list at ~11.5k tokens (RQ2), so descriptions carry a
+// CAPPED vocabulary and the complete catalog stays in this tool's RESULT.
+const CURATED_OPS_CAP = 10;
+const GENERATED_GROUPS_CAP = 6;
 function opVocabulary(registry, service) {
-    const ops = registry.catalog(service).map((o) => o.tool.startsWith(`${service}_`) ? o.tool.slice(service.length + 1) : o.tool);
-    return [...new Set(ops)].join(', ');
+    const { curated, generated } = registry.opNames(service);
+    const parts = [];
+    if (curated.length > 0) {
+        const shown = curated.slice(0, CURATED_OPS_CAP);
+        const more = curated.length - shown.length;
+        parts.push(`${shown.join(', ')}${more > 0 ? ` +${more} more` : ''}`);
+    }
+    if (generated.length > 0) {
+        // The generated long tail compresses to its resource groups: denser and
+        // more selective than any truncated name list.
+        const counts = new Map();
+        for (const op of generated) {
+            const group = op.split('_')[0];
+            counts.set(group, (counts.get(group) ?? 0) + 1);
+        }
+        const groups = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+        const shown = groups.slice(0, GENERATED_GROUPS_CAP).map(([g]) => g);
+        const more = groups.length - shown.length;
+        parts.push(`${generated.length} generated ops: ${shown.join(', ')}${more > 0 ? ` +${more} areas` : ''}`);
+    }
+    return parts.join('; ');
 }
 export function registerDiscoverTools(registry, policy) {
     const registerMeta = registry.registerMeta;
@@ -11,9 +35,8 @@ export function registerDiscoverTools(registry, policy) {
     // name/schema context budget after. stdio-only semantics — over stateless
     // HTTP the mode is forced curated and these are no-ops.
     registerMeta('discover_all', {
-        description: 'Reveal ALL curated Google tools at once (instead of per-service discovery). ' +
-            'Use when starting substantial Google work so the shaped, high-quality tools are ' +
-            'directly callable; prefer them over google_api_call. Pair with discover_reset when done.',
+        description: 'Reveal ALL curated Google tools at once (instead of per-service discovery). Use when ' +
+            'starting substantial Google work; prefer these over google_api_call. Pair with discover_reset.',
         inputSchema: {},
         _meta: { 'anthropic/alwaysLoad': true },
     }, async () => {
@@ -35,9 +58,8 @@ export function registerDiscoverTools(registry, policy) {
         };
     });
     registerMeta('discover_reset', {
-        description: 'Collapse the tool surface back to the configured default (lean meta-tools-only under the ' +
-            'default lazy mode), reclaiming context budget after heavy Google work. All tools remain ' +
-            'callable by name after collapsing.',
+        description: 'Collapse the tool surface back to the configured default, reclaiming context budget ' +
+            'after heavy Google work. All tools remain callable by name after collapsing.',
         inputSchema: {},
         _meta: { 'anthropic/alwaysLoad': true },
     }, async () => {
@@ -58,13 +80,12 @@ export function registerDiscoverTools(registry, policy) {
     });
     for (const service of registry.services()) {
         registerMeta(`${service}_discover`, {
-            description: `List the available ${service} operations. ` +
-                (registry.mode === 'lazy'
-                    ? `Operational ${service} tools are hidden until discovered — call this first, then call the tool you need by name. `
-                    : `Returns the ${service} catalog (and reveals any still-hidden ${service} tools). `) +
-                `Operations: ${opVocabulary(registry, service)}.`,
+            description: (registry.mode === 'lazy'
+                ? `Discover ${service}: lists the catalog and reveals its hidden tools; call first, then call the tool by name. `
+                : `List the ${service} catalog (reveals any still-hidden ${service} tools). `) +
+                `Ops: ${opVocabulary(registry, service)}.`,
             inputSchema: {
-                query: z.string().optional().describe('Keyword to filter the returned operations'),
+                query: z.string().optional().describe('Filter keyword'),
             },
             _meta: { 'anthropic/alwaysLoad': true },
         }, async ({ query }) => {

package/dist/discovery-client.d.ts

@@ -1,7 +1,14 @@
-export declare const WORKSPACE_APIS: Record<string, {
+export declare const SUPPORTED_APIS: Record<string, {
     id: string;
     version: string;
 }>;
+export declare const API_ALIASES: Record<string, string[]>;
+/**
+ * Resolve an `api` argument to real SUPPORTED_APIS keys: exact match, then
+ * case/punctuation-normalized ("Search-Console" -> searchconsole), then the
+ * alias map. null = genuinely unknown.
+ */
+export declare function resolveApiAliases(api: string): string[] | null;
 export interface DiscoveryParam {
     location: 'path' | 'query';
     required?: boolean;