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

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,16 +26,16 @@ 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),
     hint: `add "${name}" to an account's scope profile (or legacy GOOGLE_OPTIONAL_SCOPES)`,
 });
 export const GENERATED_GATES = {
-    analytics: bundleGate('analytics'),
     appsmarket: bundleGate('appsmarket'),
     classroom: bundleGate('classroom'),
     cloudidentity: bundleGate('cloudidentity'),

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

@@ -118,20 +118,6 @@ export function registerAnalyticsGeneratedTools(registry) {
             fields: z.string().optional().describe('Response field mask.'),
         },
     });
-    registerGeneratedTool(registry, {
-        name: "analytics_account_summaries_list",
-        cud: "read",
-        description: "Returns summaries of all accounts accessible by the caller.",
-        method: { id: "analyticsadmin.accountSummaries.list", httpMethod: "GET", path: "v1beta/accountSummaries", baseUrl: "https://analyticsadmin.googleapis.com/", requiredParams: [], scopes: S_analyticsadmin_v1beta[1] },
-        params: [{ "field": "pageSize", "api": "pageSize", "location": "query" }, { "field": "pageToken", "api": "pageToken", "location": "query" }, { "field": "fields", "api": "fields", "location": "query" }],
-        hasBody: false,
-        shape: {
-            account: accountField(),
-            pageSize: z.number().describe("Optional. The maximum number of AccountSummary resources to return. The service may return fewer than this value, even if there are additional pages. If unspecified, at most 50 resources will be retur").optional(),
-            pageToken: z.string().describe("Optional. A page token, received from a previous `ListAccountSummaries` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListAccountSummaries` mus").optional(),
-            fields: z.string().optional().describe('Response field mask.'),
-        },
-    });
     registerGeneratedTool(registry, {
         name: "analytics_properties_acknowledge_user_data_collection",
         cud: "update",
@@ -881,19 +867,6 @@ export function registerAnalyticsGeneratedTools(registry) {
             fields: z.string().optional().describe('Response field mask.'),
         },
     });
-    registerGeneratedTool(registry, {
-        name: "analytics_properties_get_metadata",
-        cud: "read",
-        description: "Returns metadata for dimensions and metrics available in reporting methods. Used to explore the dimensions and metrics. In this method, a Google Analytics prope",
-        method: { id: "analyticsdata.properties.getMetadata", httpMethod: "GET", path: "v1beta/{+name}", baseUrl: "https://analyticsdata.googleapis.com/", requiredParams: ["name"], scopes: S_analyticsdata_v1beta[0] },
-        params: [{ "field": "name", "api": "name", "location": "path" }, { "field": "fields", "api": "fields", "location": "query" }],
-        hasBody: false,
-        shape: {
-            account: accountField(),
-            name: z.string().describe("Required. The resource name of the metadata to retrieve. This name field is specified in the URL path and not URL parameters. Property is a numeric Google Analytics property identifier. To learn more,"),
-            fields: z.string().optional().describe('Response field mask.'),
-        },
-    });
     registerGeneratedTool(registry, {
         name: "analytics_properties_run_pivot_report",
         cud: "read",
@@ -908,32 +881,4 @@ export function registerAnalyticsGeneratedTools(registry) {
             fields: z.string().optional().describe('Response field mask.'),
         },
     });
-    registerGeneratedTool(registry, {
-        name: "analytics_properties_run_realtime_report",
-        cud: "read",
-        description: "Returns a customized report of realtime event data for your property. Events appear in realtime reports seconds after they have been sent to the Google Analytic",
-        method: { id: "analyticsdata.properties.runRealtimeReport", httpMethod: "POST", path: "v1beta/{+property}:runRealtimeReport", baseUrl: "https://analyticsdata.googleapis.com/", requiredParams: ["property"], scopes: S_analyticsdata_v1beta[0] },
-        params: [{ "field": "property", "api": "property", "location": "path" }, { "field": "fields", "api": "fields", "location": "query" }],
-        hasBody: true,
-        shape: {
-            account: accountField(),
-            property: z.string().describe("A Google Analytics property identifier whose events are tracked. Specified in the URL path and not the body. To learn more, see [where to find your Property ID](https://developers.google.com/analytics"),
-            body: coerceJson(z.record(z.string(), z.unknown())).describe("RunRealtimeReportRequest JSON request body. Top-level fields: dimensionFilter, dimensions, limit, metricAggregations, metricFilter, metrics, minuteRanges, orderBys, returnPropertyQuota."),
-            fields: z.string().optional().describe('Response field mask.'),
-        },
-    });
-    registerGeneratedTool(registry, {
-        name: "analytics_properties_run_report",
-        cud: "read",
-        description: "Returns a customized report of your Google Analytics event data. Reports contain statistics derived from data collected by the Google Analytics tracking code. T",
-        method: { id: "analyticsdata.properties.runReport", httpMethod: "POST", path: "v1beta/{+property}:runReport", baseUrl: "https://analyticsdata.googleapis.com/", requiredParams: ["property"], scopes: S_analyticsdata_v1beta[0] },
-        params: [{ "field": "property", "api": "property", "location": "path" }, { "field": "fields", "api": "fields", "location": "query" }],
-        hasBody: true,
-        shape: {
-            account: accountField(),
-            property: z.string().describe("A Google Analytics property identifier whose events are tracked. Specified in the URL path and not the body. To learn more, see [where to find your Property ID](https://developers.google.com/analytics"),
-            body: coerceJson(z.record(z.string(), z.unknown())).describe("RunReportRequest JSON request body. Top-level fields: cohortSpec, comparisons, currencyCode, dateRanges, dimensionFilter, dimensions, keepEmptyRows, limit, metricAggregations, metricFilter, metrics, offset, +3 more."),
-            fields: z.string().optional().describe('Response field mask.'),
-        },
-    });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.12",
+  "version": "6.0.0-alpha.13",
   "description": "Local MCP server for Google Workspace (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console, +Forms/Chat/Admin) across multiple accounts — OAuth-only, encrypted token storage, deny-by-default writes.",
   "type": "module",
   "license": "MIT",
@@ -63,6 +63,8 @@
   },
   "dependencies": {
     "@googleapis/admin": "^37.0.0",
+    "@googleapis/analyticsadmin": "^22.0.0",
+    "@googleapis/analyticsdata": "^10.0.0",
     "@googleapis/calendar": "^20.0.0",
     "@googleapis/chat": "^51.0.0",
     "@googleapis/docs": "^14.0.0",