mcp-google-multi 6.0.0-alpha.3 → 6.0.0-alpha.30

package/README.md

@@ -1,13 +1,13 @@
 # mcp-google-multi
 
-The most complete **local Google Workspace MCP server**: Gmail, Drive, Calendar, Sheets, Docs, Slides, Forms, Contacts, Tasks, Chat, Meet, Classroom, Vault, Admin and more — **every OAuth-reachable Workspace API method** as a tool, across **multiple Google accounts** at once, from Claude Code or any MCP client.
+The most complete **local Google Workspace MCP server**: Gmail, Drive, Calendar, Sheets, Docs, Slides, Forms, Contacts, Tasks, Chat, Meet, Analytics (GA4), Search Console, Classroom, Vault, Admin and more — **every OAuth-reachable API method** as a tool, across **multiple Google accounts** at once, from Claude Code or any MCP client.
 
 [![npm](https://img.shields.io/npm/v/mcp-google-multi?label=npm&color=cb3837)](https://www.npmjs.com/package/mcp-google-multi)
 
-- 🧰 **Exhaustive** — 874 tools across 28 services + an escape hatch for anything else → [COVERAGE.md](./COVERAGE.md)
+- 🧰 **Exhaustive** — 940 tools across 29 services, now including Google Analytics (GA4), + an escape hatch for anything else → [COVERAGE.md](./COVERAGE.md)
 - 🔑 **Multi-account** — drive any number of Google accounts by alias, or fan one call out across all of them
 - 🔒 **Private by design** — your own OAuth app, tokens encrypted at rest (AES-256-GCM), writes deny-by-default, no telemetry, no metering — it talks only to Google
-- 🌐 **Local or remote** — runs locally over stdio, or self-hosted over HTTP with its own built-in OAuth 2.1 server (Claude Code's `/mcp` login and the claude.ai connector, zero custom UI) → [remote setup](./docs/http-setup.md)
+- 🌐 **Local or remote** — runs locally over stdio, or self-hosted over HTTP with its own built-in OAuth 2.1 server (Claude Code's `/mcp` login and the claude.ai connector, zero custom UI). Pull-and-up Docker Compose with optional automatic HTTPS → [remote setup](./docs/http-setup.md)
 - ✉️ **Built for real work** — send and read email in Markdown with attachments and one-call replies, an interactive setup wizard with a `doctor` self-check, and per-account scope profiles → [features tour](./docs/features.md)
 
 ## Quick setup
@@ -20,6 +20,8 @@ New to all this? It's written for someone who just installed Claude Code and has
    npm install -g mcp-google-multi
    ```
 
+   Claude Desktop user? You can skip npm entirely: download the `mcp-google-multi.mcpb` bundle from the [latest release](https://github.com/bakissation/mcp-google-multi/releases/latest), double-click it (or drag it into Claude Desktop → Settings → Extensions), and fill in the values from step 2 when prompted.
+
 2. **Make your Google key** (the one manual part, a few minutes, because Google has no way to script it). Follow the step-by-step [Google Cloud setup](./docs/google-cloud-setup.md), or just ask Claude Code: *"walk me through creating a Google OAuth Desktop client for mcp-google-multi."* You finish with two values, a **Client ID** and a **Client Secret**. It's free and private to you.
 
 3. **Put them in a file.** In the folder you'll run from, make a file named `.env` and paste this, filling in your values:
@@ -53,6 +55,10 @@ New to all this? It's written for someone who just installed Claude Code and has
 
 **Go deeper:** [Configuration reference](./docs/configuration.md) · [What's covered](./COVERAGE.md) · [Features tour](./docs/features.md) · [Remote / HTTP setup](./docs/http-setup.md) · [Secrets in a vault](./docs/secrets.md) · [Migrating to v6](./MIGRATION-v6.md) · [Security policy](./SECURITY.md) · [Roadmap](https://github.com/bakissation/mcp-google-multi/milestones)
 
+## Local usage metrics (off by default)
+
+The server can keep anonymous, **local-only** usage aggregates for its operator: tool names, error classes, latency buckets. Never arguments, payloads, message content, accounts, or identities of any kind, and **zero network egress ever** — the data cannot leave your machine unless you copy files yourself. It is off until you set `GOOGLE_USAGE_METRICS=on`; when on, the boot log and `doctor` say so and name the source. Read your own data with `mcp-google-multi metrics report`. Details, file format, and the honest threat model: [docs/usage-metrics.md](./docs/usage-metrics.md).
+
 ## Maintainer & credits
 
 Built and maintained by **Abdelbaki Berkati** — [berkati.xyz](https://berkati.xyz) · [@bakissation](https://github.com/bakissation). [Read the case study →](https://berkati.xyz/case-studies/mcp-google-multi/)

package/dist/api-probe.js

@@ -17,6 +17,9 @@ export const API_PROBES = [
     { service: 'chat', api: 'chat', url: 'https://chat.googleapis.com/v1/spaces?pageSize=1', scopePrefixes: [`${P}chat.`] },
     { service: 'meet', api: 'meet', url: 'https://meet.googleapis.com/v2/conferenceRecords?pageSize=1', scopePrefixes: [`${P}meetings.`] },
     { service: 'forms', api: 'forms', url: `https://forms.googleapis.com/v1/forms/${BOGUS_ID}`, scopePrefixes: [`${P}forms.`], notFoundMeansEnabled: true },
+    // Probes the Admin API only: the Data API has no no-arg read (every call
+    // needs a property id), so its enablement surfaces on first report instead.
+    { service: 'analytics', api: 'analyticsadmin', url: 'https://analyticsadmin.googleapis.com/v1beta/accountSummaries?pageSize=1', scopePrefixes: [`${P}analytics`] },
 ];
 export function planProbes(granted, probes = API_PROBES) {
     return probes.filter((p) => granted.some((s) => p.scopePrefixes.some((prefix) => s.startsWith(prefix))));

package/dist/arg-normalize.d.ts

@@ -0,0 +1,19 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { JSONRPCMessage } from '@modelcontextprotocol/sdk/types.js';
+export declare function argNormalizationEnabled(env?: NodeJS.ProcessEnv): boolean;
+/** Declared scalar kind per schema key; drives value coercion on RENAMED keys
+ * only. Clients string-encode values for keys absent from the advertised
+ * schema, so a renamed key almost always arrives as a string — without
+ * coercion the rename would just move the -32602 from the key to the value. */
+export type ArgKind = 'number' | 'boolean' | 'other';
+export type ArgShape = ReadonlyMap<string, ArgKind>;
+export declare function normalizeCallArguments(shape: ArgShape, args: Record<string, unknown>): {
+    args: Record<string, unknown>;
+    renamed: [string, string][];
+};
+export declare function normalizeMessage(msg: JSONRPCMessage, shapeFor: (tool: string) => ArgShape | undefined, log?: (line: string) => void, onRename?: (tool: string, renames: number) => void): JSONRPCMessage;
+/** Wrap a server-side transport so tools/call argument keys are normalized
+ * before the SDK validates them. The Protocol assigns `onmessage` during
+ * connect(); the interceptor lives in that setter, so the wrapper works
+ * identically for stdio and (per-request, stateless) HTTP transports. */
+export declare function withArgNormalization(transport: Transport, shapeFor: (tool: string) => ArgShape | undefined, log?: (line: string) => void, onRename?: (tool: string, renames: number) => void): Transport;

package/dist/arg-normalize.js

@@ -0,0 +1,94 @@
+// Wire-level tools/call argument normalization. Clients (LLMs) recurringly
+// snake_case a camelCase parameter (thread_id for threadId) and burn a retry
+// on the -32602. A schema-level fix is off the table: SDK 1.x advertises an
+// EMPTY input schema for any non-object wrapper (pipe/preprocess), so the
+// only seam that keeps tools/list intact is the JSON-RPC message itself —
+// which is versioned MCP spec, stabler than any SDK internal. The rename is
+// provably lossless: it fires only when the sent key is NOT in the tool's
+// schema, its camelCase twin IS, and that twin was not also sent.
+export function argNormalizationEnabled(env = process.env) {
+    return !/^(0|false|off|no)$/i.test((env.GOOGLE_ARG_NORMALIZE ?? '').trim());
+}
+const snakeToCamel = (key) => key.replace(/_([a-z0-9])/g, (_m, c) => c.toUpperCase());
+function coerceRenamedValue(value, kind) {
+    if (typeof value !== 'string')
+        return value;
+    const v = value.trim();
+    if (kind === 'number' && /^-?\d+(\.\d+)?$/.test(v))
+        return Number(v);
+    if (kind === 'boolean' && /^(true|false)$/i.test(v))
+        return v.toLowerCase() === 'true';
+    return value;
+}
+export function normalizeCallArguments(shape, args) {
+    const renamed = [];
+    let out;
+    for (const key of Object.keys(args)) {
+        if (shape.has(key) || !key.includes('_'))
+            continue;
+        const camel = snakeToCamel(key);
+        if (camel !== key && shape.has(camel) && !(camel in args)) {
+            out ??= { ...args };
+            out[camel] = coerceRenamedValue(out[key], shape.get(camel));
+            delete out[key];
+            renamed.push([key, camel]);
+        }
+    }
+    return { args: out ?? args, renamed };
+}
+export function normalizeMessage(msg, shapeFor, log = (l) => process.stderr.write(`${l}\n`), onRename) {
+    const m = msg;
+    if (m.method !== 'tools/call' || typeof m.params?.name !== 'string')
+        return msg;
+    const args = m.params.arguments;
+    if (!args || typeof args !== 'object' || Array.isArray(args))
+        return msg;
+    const shape = shapeFor(m.params.name);
+    if (!shape)
+        return msg;
+    const { args: normalized, renamed } = normalizeCallArguments(shape, args);
+    if (renamed.length === 0)
+        return msg;
+    // Key names only — argument VALUES never reach the log.
+    log(`[args] ${m.params.name}: ${renamed.map(([f, t]) => `${f} -> ${t}`).join(', ')}`);
+    try {
+        onRename?.(m.params.name, renamed.length);
+    }
+    catch { /* observers never break dispatch */ }
+    return {
+        ...msg,
+        params: { ...m.params, arguments: normalized },
+    };
+}
+/** Wrap a server-side transport so tools/call argument keys are normalized
+ * before the SDK validates them. The Protocol assigns `onmessage` during
+ * connect(); the interceptor lives in that setter, so the wrapper works
+ * identically for stdio and (per-request, stateless) HTTP transports. */
+export function withArgNormalization(transport, shapeFor, log, onRename) {
+    const wrapper = {
+        start: () => transport.start(),
+        send: (message, options) => transport.send(message, options),
+        close: () => transport.close(),
+    };
+    Object.defineProperty(wrapper, 'onmessage', {
+        get: () => transport.onmessage,
+        set: (handler) => {
+            transport.onmessage = handler
+                ? (message, extra) => handler(normalizeMessage(message, shapeFor, log, onRename), extra)
+                : undefined;
+        },
+    });
+    for (const prop of ['onclose', 'onerror']) {
+        Object.defineProperty(wrapper, prop, {
+            get: () => transport[prop],
+            set: (v) => {
+                transport[prop] = v;
+            },
+        });
+    }
+    Object.defineProperty(wrapper, 'sessionId', { get: () => transport.sessionId });
+    if (transport.setProtocolVersion) {
+        wrapper.setProtocolVersion = (v) => transport.setProtocolVersion(v);
+    }
+    return wrapper;
+}

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

@@ -14,7 +14,9 @@ export async function getClient(account) {
         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.');
     }
-    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)}`);

package/dist/config-file.d.ts

@@ -17,6 +17,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

@@ -36,6 +36,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;

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;
@@ -96,9 +130,9 @@ 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 cacheDir = deps.cacheDir ?? discoveryCacheDir();
@@ -124,20 +158,34 @@ 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 });
+                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 +196,13 @@ 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;
+// 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|(batch)?run\w*report)/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;
+// archive sits with the deletes: in GA4 archiving a custom dimension/metric is
+// permanent, so the most restrictive write class is the safe classification.
+const POST_DELETE_VERB = /^(batch)?(delete|remove|trash|clear|empty|obliterate|purge|revoke|wipeout|archive)/i;
 export function cudFromMethod(method) {
     switch (method.httpMethod) {
         case 'GET':

package/dist/doctor.d.ts

@@ -2,6 +2,7 @@ import type { ToolRegistry } from './registry.js';
 import { getAccountSet } from './accounts.js';
 import { type AccountHealth } from './tools/accounts-tool.js';
 import { peekMasterKeyProvenance } from './master-key.js';
+import { type HttpConfig } from './http-config.js';
 export type Verdict = 'ok' | 'warn' | 'fail' | 'unknown';
 export interface DiagnosticSection {
     id: number;
@@ -38,9 +39,23 @@ export interface DiagnosticsDeps {
     /** Optional live section-6 probe; when absent the section reports `unknown`
      * (spec: a section that cannot run is unknown, not FAIL). */
     probeApi?: (alias: string) => Promise<ApiProbeResult[]>;
+    /** Optional live section-7 endpoint probe (PRM/AS-metadata self-fetch);
+     * when absent, section 7 stays on its offline config checks. */
+    probeHttp?: (cfg: HttpConfig) => Promise<HttpProbeResult>;
+}
+/** Live §7 probe outcome. `unreachable` = connection-level failure (server not
+ * running), reported as `unknown` rather than FAIL; `problem` = a real
+ * metadata fault at a reachable server. */
+export interface HttpProbeResult {
+    ok: boolean;
+    unreachable?: boolean;
+    problem?: string;
 }
 /** 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>;