mcp-google-multi 6.0.0-alpha.11 → 6.0.0-alpha.13

package/README.md

@@ -4,10 +4,10 @@ The most complete **local Google Workspace MCP server**: Gmail, Drive, Calendar,
 
 [![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

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

@@ -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' },
@@ -148,9 +150,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/scope-catalog.js

@@ -108,6 +108,13 @@ export const BUNDLE_CATALOG = {
         description: 'Read Gmail Postmaster Tools deliverability data.',
         risk: 'low',
     },
+    // Read-only by design: GA4 admin writes need analytics.edit, which ships as
+    // a separate opt-in bundle only if real demand appears (plan 6.0.0 GA-1).
+    analytics: {
+        scopes: ['https://www.googleapis.com/auth/analytics.readonly'],
+        description: 'Read Google Analytics (GA4): run reports and inspect accounts, properties and their configuration.',
+        risk: 'low',
+    },
     groupssettings: {
         scopes: ['https://www.googleapis.com/auth/apps.groups.settings'],
         description: 'Change Google Groups settings for the domain.',

package/dist/services.js

@@ -11,6 +11,7 @@ import { registerSlidesTools } from './tools/slides.js';
 import { registerFormsTools } from './tools/forms.js';
 import { registerChatTools } from './tools/chat.js';
 import { registerAdminTools } from './tools/admin.js';
+import { registerAnalyticsTools } from './tools/analytics.js';
 import { getOptionalBundles, getAdminAccounts } from './auth.js';
 export const SERVICES = [
     { name: 'gmail', register: registerGmailTools },
@@ -25,9 +26,10 @@ export const SERVICES = [
     { name: 'slides', register: registerSlidesTools, enabled: () => new Set(getOptionalBundles()).has('slides') },
     { name: 'forms', register: registerFormsTools, enabled: () => new Set(getOptionalBundles()).has('forms') },
     { name: 'chat', register: registerChatTools, enabled: () => new Set(getOptionalBundles()).has('chat') },
+    { name: 'analytics', register: registerAnalyticsTools, enabled: () => new Set(getOptionalBundles()).has('analytics') },
     { name: 'admin', register: registerAdminTools, enabled: () => getAdminAccounts().length > 0 },
 ];
-// Generated-only services with opt-in scopes; admin/forms/chat reuse their curated gate in buildRegistry,
+// Generated-only services with opt-in scopes; admin/forms/chat/analytics reuse their curated gate in buildRegistry,
 // and workspaceevents is deliberately absent — no dedicated scope (subscriptions use resource scopes).
 const bundleGate = (name) => ({
     enabled: () => new Set(getOptionalBundles()).has(name),

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/generated/analytics.d.ts

@@ -0,0 +1,2 @@
+import type { ToolRegistry } from '../../registry.js';
+export declare function registerAnalyticsGeneratedTools(registry: ToolRegistry): void;