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

package/dist/discover.js

@@ -1,8 +1,33 @@
 import { z } from 'zod';
 import { describePolicy } from './write-control.js';
+import { hints } from './hint-provider.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 +36,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 +59,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,18 +81,18 @@ 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 }) => {
             const operations = registry.catalog(service, query);
             registry.reveal(service);
+            const rendered = hints()?.render({ kind: 'policy_summary', policy });
             return {
                 content: [
                     {
@@ -77,7 +100,7 @@ export function registerDiscoverTools(registry, policy) {
                         text: JSON.stringify({
                             service,
                             operations,
-                            writeControl: describePolicy(policy),
+                            writeControl: rendered?.hint ?? describePolicy(policy),
                             next: operations.length > 0
                                 ? 'Call the chosen tool by name; it is now listed and callable.'
                                 : `No ${service} operation matches "${query}". Call again without query for the full catalog.`,

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;
@@ -42,5 +49,8 @@ export declare function loadMethodIndex(api: string, deps?: DiscoveryDeps): Prom
 export declare function clearDiscoveryMemoryCache(): void;
 export declare function cudFromMethod(method: Pick<DiscoveryMethod, 'httpMethod' | 'id'>): 'read' | 'create' | 'update' | 'delete';
 export declare function expandPath(template: string, pathParams: Record<string, string>): string;
+/** Search keywords are a few words; the caps keep a caller-sized query from
+ * driving index-size x token-count substring scans on the event loop. */
+export declare const MAX_SEARCH_QUERY = 500;
 export declare function searchMethods(index: DiscoveryMethod[], query: string, limit?: number): DiscoveryMethod[];
 export {};

package/dist/discovery-client.js

@@ -1,7 +1,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as os from 'node:os';
-export const WORKSPACE_APIS = {
+export const SUPPORTED_APIS = {
     gmail: { id: 'gmail', version: 'v1' },
     drive: { id: 'drive', version: 'v3' },
     calendar: { id: 'calendar', version: 'v3' },
@@ -20,6 +20,8 @@ export const WORKSPACE_APIS = {
     admin_reports: { id: 'admin', version: 'reports_v1' },
     admin_datatransfer: { id: 'admin', version: 'datatransfer_v1' },
     groupssettings: { id: 'groupssettings', version: 'v1' },
+    analyticsadmin: { id: 'analyticsadmin', version: 'v1beta' },
+    analyticsdata: { id: 'analyticsdata', version: 'v1beta' },
     appsmarket: { id: 'appsmarket', version: 'v2' },
     classroom: { id: 'classroom', version: 'v1' },
     cloudidentity: { id: 'cloudidentity', version: 'v1' },
@@ -33,6 +35,38 @@ export const WORKSPACE_APIS = {
     vault: { id: 'vault', version: 'v1' },
     workspaceevents: { id: 'workspaceevents', version: 'v1' },
 };
+// Names agents actually type for an API, mapped to real SUPPORTED_APIS keys.
+// Motivated by observed escape-hatch misses ("analytics" is two Discovery
+// APIs, the Admin SDK is three); keep entries plural-target only when the
+// split is real.
+export const API_ALIASES = {
+    analytics: ['analyticsadmin', 'analyticsdata'],
+    ga4: ['analyticsadmin', 'analyticsdata'],
+    googleanalytics: ['analyticsadmin', 'analyticsdata'],
+    admin: ['admin_directory', 'admin_reports', 'admin_datatransfer'],
+    adminsdk: ['admin_directory', 'admin_reports', 'admin_datatransfer'],
+    directory: ['admin_directory'],
+    webmasters: ['searchconsole'],
+    gsc: ['searchconsole'],
+    contacts: ['people'],
+    appsscript: ['script'],
+    appscript: ['script'],
+    gmailpostmastertools: ['postmaster'],
+};
+/**
+ * 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 function resolveApiAliases(api) {
+    if (SUPPORTED_APIS[api])
+        return [api];
+    const norm = api.trim().toLowerCase().replace(/[^a-z0-9]/g, '');
+    const direct = Object.keys(SUPPORTED_APIS).find((k) => k.replace(/[^a-z0-9]/g, '') === norm);
+    if (direct)
+        return [direct];
+    return API_ALIASES[norm] ?? null;
+}
 const TTL_MS = 7 * 24 * 60 * 60 * 1000;
 const STALE_RETRY_MS = 5 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 10_000;
@@ -40,6 +74,21 @@ export function discoveryCacheDir(env = process.env) {
     return (env.DISCOVERY_CACHE_PATH ??
         path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'mcp-google-multi', 'discovery'));
 }
+// Default cache path only (an operator's DISCOVERY_CACHE_PATH may be shared,
+// even /tmp, and keeps its mode), only when this process owns it, and best
+// effort. Clears group/other bits and keeps setuid/setgid/sticky.
+function tightenOwnDir(dir) {
+    if (process.platform === 'win32')
+        return;
+    try {
+        const st = fs.statSync(dir);
+        if (st.uid === process.getuid?.() && (st.mode & 0o077) !== 0)
+            fs.chmodSync(dir, st.mode & ~0o077 & 0o7777);
+    }
+    catch {
+        // the cache still works with the directory's own mode
+    }
+}
 // A poisoned cache file could repoint baseUrl off-Google; refuse to send the
 // user's Bearer token anywhere but a googleapis.com host.
 export function isGoogleApiUrl(url) {
@@ -96,11 +145,12 @@ export async function loadMethodIndex(api, deps = {}) {
     const cached = memoryCache.get(api);
     if (cached && now() < cached.refreshAfter)
         return cached.index;
-    const spec = WORKSPACE_APIS[api];
+    const spec = SUPPORTED_APIS[api];
     if (!spec) {
-        throw new Error(`Unknown api "${api}". Known: ${Object.keys(WORKSPACE_APIS).join(', ')}`);
+        throw new Error(`Unknown api "${api}". Known: ${Object.keys(SUPPORTED_APIS).join(', ')}`);
     }
     const fetchFn = deps.fetchFn ?? ((url) => fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) }));
+    const defaultDir = deps.cacheDir === undefined && process.env.DISCOVERY_CACHE_PATH === undefined;
     const cacheDir = deps.cacheDir ?? discoveryCacheDir();
     const cacheFile = path.join(cacheDir, `${api}.json`);
     const readCache = () => {
@@ -124,20 +174,36 @@ export async function loadMethodIndex(api, deps = {}) {
     if (cacheFresh())
         doc = readCache();
     if (!doc) {
-        const url = `https://www.googleapis.com/discovery/v1/apis/${spec.id}/${spec.version}/rest`;
-        try {
-            const res = await fetchFn(url);
-            if (!res.ok)
-                throw new Error(`HTTP ${res.status}`);
-            doc = (await res.json());
-            fs.mkdirSync(cacheDir, { recursive: true });
-            fs.writeFileSync(cacheFile, JSON.stringify(doc), { mode: 0o600 });
+        // Newer APIs (analyticsadmin/analyticsdata) are absent from the central
+        // discovery directory (404); each service's own $discovery endpoint is
+        // authoritative, so try both — same fallback as scripts/fetch-discovery.
+        const urls = [
+            `https://www.googleapis.com/discovery/v1/apis/${spec.id}/${spec.version}/rest`,
+            `https://${spec.id}.googleapis.com/$discovery/rest?version=${spec.version}`,
+        ];
+        let fetchError;
+        for (const url of urls) {
+            try {
+                const res = await fetchFn(url);
+                if (!res.ok)
+                    throw new Error(`HTTP ${res.status}`);
+                doc = (await res.json());
+                fs.mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+                if (defaultDir)
+                    tightenOwnDir(cacheDir);
+                fs.writeFileSync(cacheFile, JSON.stringify(doc), { mode: 0o600 });
+                break;
+            }
+            catch (err) {
+                fetchError = err;
+                doc = undefined;
+            }
         }
-        catch (err) {
+        if (!doc) {
             doc = readCache();
             staleFallback = true;
             if (!doc) {
-                throw new Error(`Could not fetch the Google API Discovery document for "${api}" and no local cache exists (${err.message}). Retry when online.`, { cause: err });
+                throw new Error(`Could not fetch the Google API Discovery document for "${api}" and no local cache exists (${fetchError?.message ?? 'fetch failed'}). Retry when online.`, { cause: fetchError });
             }
         }
     }
@@ -148,9 +214,24 @@ export async function loadMethodIndex(api, deps = {}) {
 export function clearDiscoveryMemoryCache() {
     memoryCache.clear();
 }
-const POST_READ_VERB = /^(get|list|search|query|lookup|count|batchGet|generateIds|export|download|inspect)/i;
-const POST_UPDATE_VERB = /^(untrash|undelete|restore|modify|move|set|sort|merge|unmerge|replace|resize|publish|resolve|update|patch|write|format)/i;
-const POST_DELETE_VERB = /^(batch)?(delete|remove|trash|clear|empty|obliterate|purge|revoke|wipeout)/i;
+// GA4-style report execution (runReport, batchRunPivotReports, runAccessReport)
+// and check* predicates are POSTs purely for the request-body size — reads.
+const POST_READ_VERB = /^(get|list|search|query|lookup|count|batchGet|generateIds|export|download|inspect|check|suggest|(batch)?run\w*report)/i;
+// `cancelWipe` must be matched here, BEFORE `cancel` reaches the delete list:
+// it calls off a pending wipe, which is the opposite of one. Update is tested
+// before delete for exactly that reason.
+// State transitions on something that already exists: reversible, and none of
+// them creates anything, so `create` was both wrong and the most permissive
+// class available. `(batch)?` mirrors the delete list, without which every
+// `batchUpdate*` POST fell through to `create`.
+const POST_UPDATE_VERB = /^(cancelWipe|(batch)?(untrash|undelete|restore|modify|move|set|sort|merge|unmerge|replace|resize|publish|resolve|update|patch|write|format|change|close|reopen|enable|disable|hide|unhide|accept|approve|decline|reassign|reactivate|renew|mark|turn|suspend|activate|make|return|reclaim|complete))/i;
+// archive sits with the deletes: in GA4 archiving a custom dimension/metric is
+// permanent, so the most restrictive write class is the safe classification.
+// So do the teardown verbs: `stop` and `cancel` tear down a push channel or a
+// long-running operation, `wipe`/`invalidate`/`signOut` destroy device data,
+// codes and sessions, `reset` discards a configuration, and `end` terminates a
+// live conference. Each removes something that existed.
+const POST_DELETE_VERB = /^(batch)?(delete|remove|trash|clear|empty|obliterate|purge|revoke|wipeout|archive|wipe|invalidate|signOut|stop|cancel|unregister|unreserve|reset|end)/i;
 export function cudFromMethod(method) {
     switch (method.httpMethod) {
         case 'GET':
@@ -181,11 +262,32 @@ export function expandPath(template, pathParams) {
         if (value === undefined) {
             throw new Error(`Missing required path parameter "${name}"`);
         }
-        return plus ? String(value).split('/').map(encodeURIComponent).join('/') : encodeURIComponent(String(value));
+        // A blank segment collapses the path and Google routes the resulting
+        // trailing-slash URL to the COLLECTION: `sites.get` with siteUrl:"" came
+        // back as the whole site LIST, reported as success. Dot segments resolve
+        // at URL-parse time, so `../v1/contactGroups` retargets the call at a
+        // different endpoint and returns ITS response as success. Both are
+        // silent-wrong, so refuse locally rather than send a different request.
+        // `{+param}` keeps its slashes, so every segment has to be checked.
+        const segments = plus ? String(value).split('/') : [String(value)];
+        for (const segment of segments) {
+            if (segment.trim() === '') {
+                throw new Error(`Path parameter "${name}" is empty. An empty value addresses the collection, not one resource, so nothing was sent to Google.`);
+            }
+            if (segment === '.' || segment === '..') {
+                throw new Error(`Path parameter "${name}" contains a "${segment}" path segment, which would retarget the request at a different endpoint. Nothing was sent to Google.`);
+            }
+        }
+        return segments.map(encodeURIComponent).join('/');
     });
 }
+/** Search keywords are a few words; the caps keep a caller-sized query from
+ * driving index-size x token-count substring scans on the event loop. */
+export const MAX_SEARCH_QUERY = 500;
+const MAX_SEARCH_TOKENS = 16;
 export function searchMethods(index, query, limit = 10) {
-    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+    const words = query.slice(0, MAX_SEARCH_QUERY).toLowerCase().split(/\s+/).filter(Boolean);
+    const tokens = [...new Set(words)].slice(0, MAX_SEARCH_TOKENS);
     if (tokens.length === 0)
         return index.slice(0, limit);
     const scored = index

package/dist/doctor.d.ts

@@ -1,6 +1,7 @@
 import type { ToolRegistry } from './registry.js';
 import { getAccountSet } from './accounts.js';
 import { type AccountHealth } from './tools/accounts-tool.js';
+import { type IdentityContext } from './identity.js';
 import { peekMasterKeyProvenance } from './master-key.js';
 import { type HttpConfig } from './http-config.js';
 export type Verdict = 'ok' | 'warn' | 'fail' | 'unknown';
@@ -53,9 +54,14 @@ export interface HttpProbeResult {
 }
 /** Console deep-link to enable one API (section-6 hint, error taxonomy B10). */
 export declare function apiEnableLink(api: string): string;
+/** One line, state AND source, so the people being measured can see both
+ * here and in `diagnose` (metrics spec section 2). Read-only. */
+export declare function usageMetricsStatusLine(env: Record<string, string | undefined>): string;
 /** Roll section verdicts to an overall verdict. `unknown` never worsens it. */
 export declare function overallVerdict(sections: DiagnosticSection[]): Verdict;
-export declare function runDiagnostics(deps?: DiagnosticsDeps): Promise<DiagnosticsReport>;
+export declare function runDiagnostics(deps?: DiagnosticsDeps, opts?: {
+    scope?: 'operator' | 'tenant';
+}): Promise<DiagnosticsReport>;
 /** doctor CLI (brew-doctor style): glyph-coded human report. */
 export declare function renderDoctorText(report: DiagnosticsReport): string;
 /** Redacted, paste-ready bug report (BR8): verdicts + provenance labels + token
@@ -63,9 +69,15 @@ export declare function renderDoctorText(report: DiagnosticsReport): string;
 export declare function renderReport(report: DiagnosticsReport, version: string): string;
 /** Exit non-zero when any section FAILs; with strict, WARN counts too. */
 export declare function exitCodeFor(report: DiagnosticsReport, strict: boolean): number;
+export type DiagnoseContext = Pick<IdentityContext, 'subject' | 'accounts' | 'getClient' | 'tokenStore'>;
 /** Agent-callable structured health report (read-only). Mirrors `doctor`'s
- * engine; NOT alwaysLoad (the agent asks for it when diagnosing). */
-export declare function registerDiagnoseTool(registry: ToolRegistry): void;
+ * engine. Registered as a META tool, like `account_list`: it introspects this
+ * server rather than Google data, and as a normal tool it became a service of
+ * its own with no `{service}_discover` to reveal it (discover tools are built
+ * from already-registered services, and this runs after that), so it was
+ * advertised only once something else expanded the surface. The README sends
+ * people here when they are stuck, so it has to be findable. */
+export declare function registerDiagnoseTool(registry: ToolRegistry, ctx?: DiagnoseContext): void;
 export interface ResetOptions {
     account?: string;
     regenerateKey: boolean;