mcp-google-multi 6.0.0-alpha.2 → 6.0.0-alpha.21

package/dist/tools/_errors.js

@@ -20,6 +20,10 @@ const RETRIABLE_NET_CODES = new Set([
     'EHOSTUNREACH', 'EPIPE', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET',
 ]);
 const NET_CODES = new Set([...RETRIABLE_NET_CODES, 'ENOTFOUND']);
+// Local-filesystem syscall codes from caller-supplied paths (localPath/savePath).
+// String codes, so they never collide with Google's numeric statuses; the
+// network codes above are deliberately excluded.
+const LOCAL_FS_CODES = new Set(['ENOENT', 'EACCES', 'EISDIR', 'ENOTDIR', 'EPERM', 'ELOOP', 'ENAMETOOLONG', 'ENOSPC']);
 /** First known network code on the error or its cause chain (GaxiosError.cause
  * -> FetchError; undici TypeError.cause -> AggregateError.errors). */
 function netCodeOf(error) {
@@ -115,16 +119,48 @@ export function mapGoogleError(error, account, forbiddenHint, scopeContext) {
                 account,
             };
         }
-        return { error: 'forbidden', message, hint: forbiddenHint, retriable: false, account };
+        return {
+            error: 'forbidden',
+            message,
+            hint: forbiddenHint ??
+                `Google denied access at the resource level (not a scope problem): check that "${account}" actually has access to this item, e.g. it is shared with that account, and that you picked the right account alias.`,
+            retriable: false,
+            account,
+        };
     }
     if (status === 400 && /invalid[_ ]scope/i.test(message)) {
-        return { error: 'invalid_scope', message, retriable: false, account };
+        return {
+            error: 'invalid_scope',
+            message,
+            hint: 'One of the requested OAuth scopes is malformed or unavailable to this client. Run `config check` to review the account scope profile, fix it, then re-auth.',
+            retriable: false,
+            account,
+        };
     }
     if (status === 404) {
-        return { error: 'not_found', message, retriable: false, account };
+        return {
+            error: 'not_found',
+            message,
+            hint: `The ID does not exist or is not visible to "${account}". IDs are account-specific: re-fetch it with the matching list/search tool, and check the account alias is the one that owns the resource.`,
+            retriable: false,
+            account,
+        };
     }
     if (status === 429) {
         const retryAfter = error?.response?.headers?.['retry-after'];
+        // GA4 quota exhaustion ("Exhausted property tokens ...") is a per-property
+        // token bucket, not a transient rate spike: shrinking the request is the
+        // lever that helps, and a blind immediate retry only burns more tokens.
+        if (/property tokens/i.test(message)) {
+            return {
+                error: 'rate_limited',
+                message,
+                hint: 'GA4 quotas are per-property token buckets that refill over the hour/day. ' +
+                    'Narrow the date range, request fewer dimensions/metrics/rows, and pass returnPropertyQuota to see the remaining tokens before retrying.',
+                retriable: true,
+                account,
+            };
+        }
         return {
             error: 'rate_limited',
             message,
@@ -134,9 +170,27 @@ export function mapGoogleError(error, account, forbiddenHint, scopeContext) {
         };
     }
     if (status !== undefined && status >= 500) {
-        return { error: 'upstream_error', message, retriable: true, account };
+        return {
+            error: 'upstream_error',
+            message,
+            hint: 'Google-side server error, usually transient: retry, with backoff if it repeats.',
+            retriable: true,
+            account,
+        };
     }
     if (status === undefined) {
+        const fsCode = typeof error?.code === 'string' && LOCAL_FS_CODES.has(error.code) ? error.code : undefined;
+        if (fsCode) {
+            const p = typeof error?.path === 'string' ? ` "${error.path}"` : '';
+            return {
+                error: 'invalid_params',
+                message: `Cannot access local path${p}: ${fsCode}`,
+                hint: 'The path must exist on the machine running this server and be accessible to it. ' +
+                    'When the server runs remotely (HTTP transport), paths on your own machine are not visible to it.',
+                retriable: false,
+                account,
+            };
+        }
         const netCode = netCodeOf(error);
         if (netCode) {
             return {
@@ -149,7 +203,17 @@ export function mapGoogleError(error, account, forbiddenHint, scopeContext) {
             };
         }
     }
-    return { error: 'upstream_error', message, retriable: false, account };
+    // Passthrough floor: still emit a hint so no envelope leaves the mapper
+    // without a next step. A 400 here is a request Google parsed and rejected.
+    return {
+        error: 'upstream_error',
+        message,
+        hint: status === 400
+            ? 'Google rejected the request as malformed: an argument is likely wrong or missing. Check IDs, enum values and formats against the tool description before retrying.'
+            : 'Unclassified error: the message above is the best signal. Retry only if it reads as transient; otherwise change the request rather than repeating it.',
+        retriable: false,
+        account,
+    };
 }
 export function handleGoogleApiError(error, account, forbiddenHint, scopeContext) {
     const envelope = mapGoogleError(error, account, forbiddenHint, scopeContext);

package/dist/tools/_local-files.d.ts

@@ -0,0 +1,3 @@
+import * as fs from 'fs';
+export declare function prepareLocalDest(savePath: string, filename: string): string;
+export declare function openLocalReadStream(localPath: string): Promise<fs.ReadStream>;

package/dist/tools/_local-files.js

@@ -0,0 +1,34 @@
+import * as fs from 'fs';
+import * as path from 'path';
+// path.basename() is a traversal guard — a caller-supplied filename must never escape savePath.
+export function prepareLocalDest(savePath, filename) {
+    const name = path.basename(filename);
+    // Agents routinely pass the intended FILE path as savePath and repeat the
+    // name in `filename`; a blind join would mkdir a directory named like the
+    // file and bury the download inside it, so strip the duplicated leaf.
+    const dir = path.basename(savePath) === name ? path.dirname(savePath) : savePath;
+    const dest = path.join(dir, name);
+    fs.mkdirSync(dir, { recursive: true });
+    return dest;
+}
+// fs.createReadStream() reports an unopenable path as an async 'error' EVENT;
+// with no listener attached, that single event kills the whole process — fatal
+// for the shared HTTP transport. Opening the fd first turns the open-failure
+// class (ENOENT/EACCES/...) into a normal rejection the caller's try/catch can
+// map to an error envelope.
+export async function openLocalReadStream(localPath) {
+    const handle = await fs.promises.open(localPath, 'r');
+    // open() succeeds on a directory; fail it here rather than as an async read error.
+    if ((await handle.stat()).isDirectory()) {
+        await handle.close();
+        throw Object.assign(new Error(`EISDIR: illegal operation on a directory, read '${localPath}'`), {
+            code: 'EISDIR',
+            path: localPath,
+        });
+    }
+    const stream = handle.createReadStream();
+    // Mid-read errors still reach the consumer through its own listeners; this
+    // one only closes the unhandled-'error' crash path.
+    stream.on('error', () => { });
+    return stream;
+}

package/dist/tools/account-wizard.d.ts

@@ -27,6 +27,16 @@ export type AddValidation = {
 /** Validate the collected form against the alias rules, dup check, and the
  * bundle catalog. Pure (no I/O) for unit testing. */
 export declare function validateAddForm(input: Partial<AddForm>, existingAliases: string[]): AddValidation;
+/** Map direct tool arguments onto the elicitation form shape: the argument-
+ * mode fallback for clients without form elicitation. All bundle picks travel
+ * through otherBundles, which validateAddForm resolves and validates. Pure. */
+export declare function argsToAddForm(a: {
+    alias?: string;
+    email?: string;
+    bundles?: string;
+    allBundles?: boolean;
+    admin?: boolean;
+}): Partial<AddForm>;
 /** Scopes requested by the profile but NOT granted at consent (granular
  * consent / unchecked bundles). Pure. */
 export declare function scopeGrantDiff(requested: string[], grantedScope: string | undefined): string[];

package/dist/tools/account-wizard.js

@@ -5,7 +5,8 @@ import { writeToken } from '../token-store.js';
 import { resolveScopesForAccount } from '../auth.js';
 import { BUNDLE_CATALOG, closestBundle, resolveBundleAliases } from '../scope-catalog.js';
 import { openUrl } from '../open-url.js';
-import { buildConsentClient, awaitLoopbackConsent, hasClientCredentials, } from '../oauth-consent.js';
+import { coerceBoolean } from './_coerce.js';
+import { buildConsentClient, openLoopbackConsent, hasClientCredentials, TESTING_MODE_WARNING, } from '../oauth-consent.js';
 import { detectClients, buildServerEntry, renderInstruction, applyFileEntry, resolveMode, DEFAULT_SERVER_NAME, } from '../client-config.js';
 // B7: the elicitation-driven account_add / account_reauth wizard. It rebuilds
 // interactive account management on the mutable config.json registry so a
@@ -70,6 +71,18 @@ export function validateAddForm(input, existingAliases) {
     }
     return { ok: true, alias, email, bundles, admin: input.admin === true };
 }
+/** Map direct tool arguments onto the elicitation form shape: the argument-
+ * mode fallback for clients without form elicitation. All bundle picks travel
+ * through otherBundles, which validateAddForm resolves and validates. Pure. */
+export function argsToAddForm(a) {
+    return {
+        alias: a.alias ?? '',
+        email: a.email ?? '',
+        allBundles: a.allBundles === true,
+        otherBundles: a.bundles ?? '',
+        admin: a.admin === true,
+    };
+}
 /** Scopes requested by the profile but NOT granted at consent (granular
  * consent / unchecked bundles). Pure. */
 export function scopeGrantDiff(requested, grantedScope) {
@@ -103,19 +116,22 @@ async function runConsent(server, alias) {
     const cfg = getAccountSet().configs[alias];
     if (!cfg)
         return { ok: false, text: `E_VALIDATION: account "${alias}" is not in the live registry (env-sourced accounts are not editable here).` };
-    const client = buildConsentClient();
+    // Bind the ephemeral loopback listener BEFORE building the auth URL: the
+    // redirect URI needs the assigned port, and listening first means the
+    // callback can't race the browser.
+    const loop = await openLoopbackConsent();
+    const client = buildConsentClient(loop.redirect);
     const expectedState = randomBytes(32).toString('hex');
     const scopes = resolveScopesForAccount(alias);
     const url = client.generateAuthUrl({ access_type: 'offline', prompt: 'consent', scope: scopes, login_hint: cfg.email, state: expectedState });
-    // Start the loopback listener BEFORE opening the browser so it can't miss the
-    // redirect. Any startup error (e.g. port in use) surfaces synchronously.
-    const consent = awaitLoopbackConsent(client, expectedState);
+    const consent = loop.finish(client, expectedState);
     const caps = server.server.getClientCapabilities?.();
     let opened = false;
     if (caps?.elicitation?.url) {
         try {
             const r = await server.server.elicitInput({ mode: 'url', message: `Authorize the "${alias}" Google account in your browser.`, url });
             if (r.action !== 'accept') {
+                loop.close();
                 return { ok: false, text: 'confirmation_declined: consent was cancelled; the account row was kept but no token was stored (doctor will show it as "missing").' };
             }
             opened = true;
@@ -138,9 +154,10 @@ async function runConsent(server, alias) {
     return { ok: true, missing: scopeGrantDiff(scopes, typeof tokens.scope === 'string' ? tokens.scope : undefined) };
 }
 function s4Text(alias, missing) {
-    if (missing.length === 0)
-        return `✔ "${alias}" authenticated; all requested scopes granted. It is now usable without a restart.`;
-    return `⚠ "${alias}" authenticated, but ${missing.length} requested scope(s) were NOT granted (E_SCOPE_NOT_GRANTED) — you may have unchecked some on the consent screen. Re-run account_reauth to grant them. The account is usable for the granted scopes.`;
+    const outcome = missing.length === 0
+        ? `✔ "${alias}" authenticated; all requested scopes granted. It is now usable without a restart.`
+        : `⚠ "${alias}" authenticated, but ${missing.length} requested scope(s) were NOT granted (E_SCOPE_NOT_GRANTED) — you may have unchecked some on the consent screen. Re-run account_reauth to grant them. The account is usable for the granted scopes.`;
+    return `${outcome}\n${TESTING_MODE_WARNING}`;
 }
 const REQUIRES_INTERACTION = { 'anthropic/requiresUserInteraction': true };
 export function registerAccountWizardTools(registry, server) {
@@ -151,9 +168,15 @@ export function registerAccountWizardTools(registry, server) {
     registerMeta('account_add', {
         _meta: REQUIRES_INTERACTION,
         annotations: { openWorldHint: true },
-        description: 'Add a new Google account interactively: collects alias/email/scope bundles via a form, writes the registry, and runs Google consent in the browser — no file editing or restart needed. Requires GOOGLE_CLIENT_ID/SECRET (run the `setup` prompt first if missing).',
-        inputSchema: {},
-    }, async () => {
+        description: 'Add a new Google account: pass alias + email directly (plus optional bundles/allBundles/admin), or pass nothing for an interactive form where the client supports elicitation. Writes the registry and runs Google consent in the browser — no file editing or restart needed. Requires GOOGLE_CLIENT_ID/SECRET (run the `setup` prompt first if missing).',
+        inputSchema: {
+            alias: z.string().optional().describe('Account alias (letters, digits, _ or -). Pass with email to add directly, skipping the form.'),
+            email: z.string().optional().describe("The account's Google address (used as the login hint)"),
+            bundles: z.string().optional().describe('Optional scope bundles, comma-separated (e.g. "forms,chat"); blank = base scopes only'),
+            allBundles: coerceBoolean.optional().describe('Grant every optional bundle (biggest consent screen); overrides bundles'),
+            admin: coerceBoolean.optional().describe('Grant Workspace admin scopes (super-admin accounts only)'),
+        },
+    }, async (args) => {
         try {
             // Env-sourced registry: GOOGLE_ACCOUNTS is the exclusive source and
             // config.json accounts are ignored, so a wizard add would be a phantom
@@ -164,16 +187,26 @@ export function registerAccountWizardTools(registry, server) {
             if (!hasClientCredentials()) {
                 return textResult('E_CLIENT_CREDENTIALS_MISSING: GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET are not set. Run the `setup` prompt (/mcp__google-multi__setup) to create an OAuth client, then set them.', true);
             }
-            const caps = server.server.getClientCapabilities?.();
-            if (!caps?.elicitation?.form) {
-                return textResult('This client does not support form elicitation. Add the account from the CLI instead: `npx mcp-google-multi account add --alias <alias> --email <email> [--profile a,b] [--admin]`.', true);
+            // S1: collect the registry row. Arguments win over the form so the
+            // wizard still works in clients without form elicitation (where the
+            // interactive path used to dead-end).
+            const a = (args ?? {});
+            let input;
+            if (a.alias?.trim() || a.email?.trim()) {
+                input = argsToAddForm(a);
             }
-            // S1: collect the registry row.
-            const form = await server.server.elicitInput({ message: 'Add a Google account', requestedSchema: addFormSchema() });
-            if (form.action !== 'accept') {
-                return textResult('confirmation_declined: no account was added.');
+            else {
+                const caps = server.server.getClientCapabilities?.();
+                if (!caps?.elicitation?.form) {
+                    return textResult('E_NO_FORM_ELICITATION: this client does not support the interactive form. Call account_add again with arguments instead, e.g. {"alias": "work", "email": "you@example.com"} (optional: "bundles" as a comma-separated list, "allBundles": true, "admin": true).', true);
+                }
+                const form = await server.server.elicitInput({ message: 'Add a Google account', requestedSchema: addFormSchema() });
+                if (form.action !== 'accept') {
+                    return textResult('confirmation_declined: no account was added.');
+                }
+                input = form.content ?? {};
             }
-            const validated = validateAddForm(form.content ?? {}, getAccountSet().aliases);
+            const validated = validateAddForm(input, getAccountSet().aliases);
             if (!validated.ok)
                 return textResult(`${validated.slug}: ${validated.message}`, true);
             // S2: atomic write + make the alias callable without a restart (BR3).

package/dist/tools/analytics.d.ts

@@ -0,0 +1,18 @@
+import type { ToolRegistry } from '../registry.js';
+/** Accepts "213025502" or "properties/213025502"; rejects the identifiers
+ * people paste by mistake (G-… measurement IDs, UA-… properties) with a
+ * pointer to the right one. */
+export declare function normalizeProperty(input: string): {
+    name: string;
+} | {
+    hint: string;
+};
+/** GA4 report rows ({dimensionValues:[{value}], metricValues:[{value}]}) are
+ * verbose; merge each row into one {name: value} object (dimension and metric
+ * API names never collide). Shared by runReport and runRealtimeReport. */
+export declare function shapeReport(data: any): Record<string, unknown>;
+export declare function shapeAccountSummaries(data: any): Record<string, unknown>;
+/** Full metadata descriptions run to paragraphs; the first ~160 chars carry
+ * the disambiguation the model needs without bloating a ~300-entry list. */
+export declare function shapeMetadata(data: any): Record<string, unknown>;
+export declare function registerAnalyticsTools(server: ToolRegistry): void;

package/dist/tools/analytics.js

@@ -0,0 +1,279 @@
+import { z } from 'zod';
+import { coerceArray, coerceBoolean, coerceJson } from './_coerce.js';
+import { analyticsdata as analyticsdataClient } from '@googleapis/analyticsdata';
+import { analyticsadmin as analyticsadminClient } from '@googleapis/analyticsadmin';
+import { accountAliasSchema } from '../accounts.js';
+import { getClient } from '../client.js';
+import { handleGoogleApiError } from './_errors.js';
+const accountEnum = accountAliasSchema.optional();
+/** Accepts "213025502" or "properties/213025502"; rejects the identifiers
+ * people paste by mistake (G-… measurement IDs, UA-… properties) with a
+ * pointer to the right one. */
+export function normalizeProperty(input) {
+    const t = input.trim();
+    if (/^properties\/\d+$/.test(t))
+        return { name: t };
+    if (/^\d+$/.test(t))
+        return { name: `properties/${t}` };
+    if (/^G-[A-Z0-9]+$/i.test(t)) {
+        return {
+            hint: `"${t}" is a measurement ID (a web data-stream tag), not a GA4 property ID. ` +
+                'Use the numeric property ID from GA Admin > Property settings, or find it with analytics_account_summaries.',
+        };
+    }
+    if (/^UA-/i.test(t)) {
+        return {
+            hint: `"${t}" is a Universal Analytics property, which the GA4 APIs cannot query. ` +
+                'Use the numeric ID of a GA4 property (find yours with analytics_account_summaries).',
+        };
+    }
+    return {
+        hint: `"${t}" is not a GA4 property reference. Pass the numeric property ID ` +
+            '(e.g. "213025502" or "properties/213025502"); find yours with analytics_account_summaries.',
+    };
+}
+/** GA4 report rows ({dimensionValues:[{value}], metricValues:[{value}]}) are
+ * verbose; merge each row into one {name: value} object (dimension and metric
+ * API names never collide). Shared by runReport and runRealtimeReport. */
+export function shapeReport(data) {
+    const dimensionHeaders = (data.dimensionHeaders ?? []).map((h) => h.name);
+    const metricHeaders = (data.metricHeaders ?? []).map((h) => ({ name: h.name, type: h.type }));
+    const mergeRow = (r) => {
+        const out = {};
+        dimensionHeaders.forEach((name, i) => {
+            out[name] = r.dimensionValues?.[i]?.value ?? '';
+        });
+        metricHeaders.forEach((h, i) => {
+            out[h.name] = r.metricValues?.[i]?.value ?? '';
+        });
+        return out;
+    };
+    const shaped = {
+        rowCount: data.rowCount ?? data.rows?.length ?? 0,
+        dimensionHeaders,
+        metricHeaders,
+        rows: (data.rows ?? []).map(mergeRow),
+    };
+    if (data.totals?.length)
+        shaped.totals = data.totals.map(mergeRow);
+    if (data.maximums?.length)
+        shaped.maximums = data.maximums.map(mergeRow);
+    if (data.minimums?.length)
+        shaped.minimums = data.minimums.map(mergeRow);
+    if (data.metadata)
+        shaped.metadata = data.metadata;
+    if (data.propertyQuota)
+        shaped.propertyQuota = data.propertyQuota;
+    return shaped;
+}
+export function shapeAccountSummaries(data) {
+    const accounts = (data.accountSummaries ?? []).map((a) => ({
+        account: a.account,
+        displayName: a.displayName,
+        properties: (a.propertySummaries ?? []).map((p) => ({
+            property: p.property,
+            displayName: p.displayName,
+            ...(p.propertyType && p.propertyType !== 'PROPERTY_TYPE_ORDINARY' ? { propertyType: p.propertyType } : {}),
+        })),
+    }));
+    return { accounts, ...(data.nextPageToken ? { nextPageToken: data.nextPageToken } : {}) };
+}
+const DESCRIPTION_CAP = 160;
+/** Full metadata descriptions run to paragraphs; the first ~160 chars carry
+ * the disambiguation the model needs without bloating a ~300-entry list. */
+export function shapeMetadata(data) {
+    const cap = (s) => typeof s === 'string' && s.length > DESCRIPTION_CAP ? `${s.slice(0, DESCRIPTION_CAP - 3)}...` : s || undefined;
+    return {
+        dimensions: (data.dimensions ?? []).map((d) => ({
+            apiName: d.apiName,
+            uiName: d.uiName,
+            category: d.category,
+            ...(d.customDefinition ? { custom: true } : {}),
+            description: cap(d.description),
+        })),
+        metrics: (data.metrics ?? []).map((m) => ({
+            apiName: m.apiName,
+            uiName: m.uiName,
+            category: m.category,
+            ...(m.type ? { type: m.type } : {}),
+            ...(m.expression ? { expression: m.expression } : {}),
+            ...(m.customDefinition ? { custom: true } : {}),
+            description: cap(m.description),
+        })),
+    };
+}
+const propertySchema = z
+    .string()
+    .describe('GA4 property: numeric ID like "213025502" or "properties/213025502" — NOT a "G-..." measurement ID and not "UA-...". Find yours with analytics_account_summaries.');
+export function registerAnalyticsTools(server) {
+    server.registerTool('analytics_account_summaries', {
+        description: 'List every Google Analytics (GA4) account and property this Google account can access, with their numeric property IDs. The starting point for any Analytics question ("what properties do I have?").',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias'),
+            pageSize: z.number().min(1).max(200).optional().describe('Summaries per page (default 50, max 200)'),
+            pageToken: z.string().optional().describe('Token from a previous page'),
+        },
+    }, async ({ account, pageSize, pageToken }) => {
+        try {
+            const auth = await getClient(account);
+            const admin = analyticsadminClient({ version: 'v1beta', auth });
+            const res = await admin.accountSummaries.list({ pageSize, pageToken });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(shapeAccountSummaries(res.data), null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleAnalyticsError(error, account);
+        }
+    });
+    server.registerTool('analytics_run_report', {
+        description: 'Run a Google Analytics (GA4) report: metrics over a date range, optionally grouped by dimensions — the workhorse for questions like "how many users last week, by country". Dates accept YYYY-MM-DD or relative forms ("today", "yesterday", "28daysAgo"). Unsure which dimension/metric names are valid? Call analytics_get_metadata first.',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias'),
+            property: propertySchema,
+            startDate: z.string().describe('Start date: YYYY-MM-DD or relative ("today", "yesterday", "NdaysAgo" e.g. "28daysAgo")'),
+            endDate: z.string().describe('End date: YYYY-MM-DD or relative ("today", "yesterday", "NdaysAgo")'),
+            metrics: coerceArray(z.string()).describe('Metric API names, e.g. ["activeUsers","sessions","screenPageViews"]. Max 10. Valid names (including custom ones) come from analytics_get_metadata.'),
+            dimensions: coerceArray(z.string())
+                .optional()
+                .describe('Dimension API names to group by, e.g. ["date"] or ["country","deviceCategory"]. Max 9. Omit for a single total row.'),
+            dimensionFilter: coerceJson(z.record(z.string(), z.unknown()))
+                .optional()
+                .describe('FilterExpression on dimensions (applies independently of metricFilter). Simple: {"filter":{"fieldName":"country","stringFilter":{"matchType":"EXACT","value":"France"}}}. AND of two: {"andGroup":{"expressions":[{"filter":{"fieldName":"country","stringFilter":{"matchType":"EXACT","value":"France"}}},{"filter":{"fieldName":"deviceCategory","stringFilter":{"matchType":"EXACT","value":"mobile"}}}]}}. matchType: EXACT | BEGINS_WITH | ENDS_WITH | CONTAINS | FULL_REGEXP (add "caseSensitive":true for case-sensitive). Also available: inListFilter, notExpression, orGroup.'),
+            metricFilter: coerceJson(z.record(z.string(), z.unknown()))
+                .optional()
+                .describe('FilterExpression on metric values, e.g. {"filter":{"fieldName":"sessions","numericFilter":{"operation":"GREATER_THAN","value":{"int64Value":"100"}}}}. operation: EQUAL | LESS_THAN | LESS_THAN_OR_EQUAL | GREATER_THAN | GREATER_THAN_OR_EQUAL; betweenFilter takes fromValue/toValue.'),
+            orderBys: coerceJson(z.array(z.record(z.string(), z.unknown())))
+                .optional()
+                .describe('Sort order, e.g. [{"metric":{"metricName":"sessions"},"desc":true}] or [{"dimension":{"dimensionName":"date"}}]. Default: unordered.'),
+            limit: z.number().min(1).max(250000).optional().describe('Max rows to return (API default 10000). Keep small for readable output.'),
+            offset: z.number().min(0).optional().describe('Zero-based row offset for pagination'),
+            metricAggregations: coerceArray(z.enum(['TOTAL', 'MINIMUM', 'MAXIMUM', 'COUNT']))
+                .optional()
+                .describe('Also return aggregate rows across all matching data (surfaced as totals/maximums/minimums)'),
+            keepEmptyRows: coerceBoolean.optional().describe('Include rows whose metrics are all zero (default false)'),
+            returnPropertyQuota: coerceBoolean.optional().describe("Include this property's remaining quota tokens in the response"),
+        },
+    }, async ({ account, property, startDate, endDate, metrics, dimensions, dimensionFilter, metricFilter, orderBys, limit, offset, metricAggregations, keepEmptyRows, returnPropertyQuota }) => {
+        const prop = normalizeProperty(property);
+        if ('hint' in prop)
+            return invalidProperty(prop.hint, account);
+        try {
+            const auth = await getClient(account);
+            const dataApi = analyticsdataClient({ version: 'v1beta', auth });
+            const requestBody = {
+                dateRanges: [{ startDate, endDate }],
+                metrics: metrics.map((name) => ({ name })),
+            };
+            if (dimensions?.length)
+                requestBody.dimensions = dimensions.map((name) => ({ name }));
+            if (dimensionFilter)
+                requestBody.dimensionFilter = dimensionFilter;
+            if (metricFilter)
+                requestBody.metricFilter = metricFilter;
+            if (orderBys?.length)
+                requestBody.orderBys = orderBys;
+            if (limit !== undefined)
+                requestBody.limit = limit;
+            if (offset !== undefined)
+                requestBody.offset = offset;
+            if (metricAggregations?.length)
+                requestBody.metricAggregations = metricAggregations;
+            if (keepEmptyRows !== undefined)
+                requestBody.keepEmptyRows = keepEmptyRows;
+            if (returnPropertyQuota !== undefined)
+                requestBody.returnPropertyQuota = returnPropertyQuota;
+            const res = await dataApi.properties.runReport({ property: prop.name, requestBody });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(shapeReport(res.data), null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleAnalyticsError(error, account);
+        }
+    });
+    server.registerTool('analytics_run_realtime_report', {
+        description: 'Run a GA4 realtime report: who is on the site right now (last 30 minutes). Realtime supports a restricted set of names, e.g. metrics activeUsers, screenPageViews, eventCount, keyEvents; dimensions country, city, deviceCategory, unifiedScreenName, eventName.',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias'),
+            property: propertySchema,
+            metrics: coerceArray(z.string()).describe('Realtime metric API names, e.g. ["activeUsers"]'),
+            dimensions: coerceArray(z.string()).optional().describe('Realtime dimension API names, e.g. ["country"] or ["unifiedScreenName"]'),
+            dimensionFilter: coerceJson(z.record(z.string(), z.unknown()))
+                .optional()
+                .describe('FilterExpression on dimensions — same shape as analytics_run_report'),
+            metricFilter: coerceJson(z.record(z.string(), z.unknown()))
+                .optional()
+                .describe('FilterExpression on metric values — same shape as analytics_run_report'),
+            minuteRanges: coerceJson(z.array(z.record(z.string(), z.unknown())))
+                .optional()
+                .describe('Up to 2 ranges of minutes-ago, e.g. [{"startMinutesAgo":29,"endMinutesAgo":0}] (default: last 30 minutes)'),
+            limit: z.number().min(1).max(250000).optional().describe('Max rows to return'),
+            returnPropertyQuota: coerceBoolean.optional().describe("Include this property's remaining realtime quota tokens"),
+        },
+    }, async ({ account, property, metrics, dimensions, dimensionFilter, metricFilter, minuteRanges, limit, returnPropertyQuota }) => {
+        const prop = normalizeProperty(property);
+        if ('hint' in prop)
+            return invalidProperty(prop.hint, account);
+        try {
+            const auth = await getClient(account);
+            const dataApi = analyticsdataClient({ version: 'v1beta', auth });
+            const requestBody = { metrics: metrics.map((name) => ({ name })) };
+            if (dimensions?.length)
+                requestBody.dimensions = dimensions.map((name) => ({ name }));
+            if (dimensionFilter)
+                requestBody.dimensionFilter = dimensionFilter;
+            if (metricFilter)
+                requestBody.metricFilter = metricFilter;
+            if (minuteRanges?.length)
+                requestBody.minuteRanges = minuteRanges;
+            if (limit !== undefined)
+                requestBody.limit = limit;
+            if (returnPropertyQuota !== undefined)
+                requestBody.returnPropertyQuota = returnPropertyQuota;
+            const res = await dataApi.properties.runRealtimeReport({ property: prop.name, requestBody });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(shapeReport(res.data), null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleAnalyticsError(error, account);
+        }
+    });
+    server.registerTool('analytics_get_metadata', {
+        description: 'List every valid dimension and metric API name for a GA4 property, including its custom definitions. Call this before analytics_run_report when unsure which names exist. Property "0" returns the standard set without property access.',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias'),
+            property: propertySchema,
+        },
+    }, async ({ account, property }) => {
+        const prop = normalizeProperty(property);
+        if ('hint' in prop)
+            return invalidProperty(prop.hint, account);
+        try {
+            const auth = await getClient(account);
+            const dataApi = analyticsdataClient({ version: 'v1beta', auth });
+            const res = await dataApi.properties.getMetadata({ name: `${prop.name}/metadata` });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(shapeMetadata(res.data), null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleAnalyticsError(error, account);
+        }
+    });
+}
+function invalidProperty(hint, account) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ error: 'invalid_params', message: 'Invalid GA4 property reference.', hint, retriable: false, account }),
+            },
+        ],
+        isError: true,
+    };
+}
+function handleAnalyticsError(error, account) {
+    return handleGoogleApiError(error, account, 'Needs the "analytics" bundle on this account (add it to the scope profile, then re-auth), and the Google account must have access to this GA4 property.');
+}

package/dist/tools/drive.d.ts

@@ -1,5 +1,6 @@
 import type { ToolRegistry } from '../registry.js';
-export declare function prepareLocalDest(savePath: string, filename: string): string;
+export declare function isTextualMime(mimeType: string): boolean;
+export declare function resolveConvertTarget(convertTo: string | undefined): string | undefined;
 export declare const DRIVE_QUERY_HINT: string;
 export declare function normalizeDriveQuery(raw: string): string;
 export declare function isDriveInvalidQuery(error: any): boolean;