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

package/dist/tools/analytics.js

@@ -0,0 +1,284 @@
+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, {
+        scope: 'Needs the "analytics" bundle on this account: add it to the scope profile, then re-auth.',
+        // GA4 answers PERMISSION_DENIED for a property ACL too, and the old
+        // combined hint sent those callers to re-auth a scope they already had.
+        resource: 'The scope is not the problem: this Google account has no access to that GA4 property. Grant it in GA4 Admin > Property Access Management, or call analytics_account_summaries to see the properties it can read.',
+    });
+}

package/dist/tools/calendar.d.ts

@@ -1,5 +1,12 @@
 import type { ToolRegistry } from '../registry.js';
 export declare function registerCalendarTools(server: ToolRegistry): void;
+/** Google disagrees with itself on a backwards window: events.list answers 200
+ * with [], which reads as "nothing scheduled", while freebusy.query 400s on the
+ * identical input. Decide locally so an empty list always means empty. Returns
+ * null when either bound is absent or unparseable: those stay Google's call.
+ * Date.parse is lenient, so it is used only to SKIP the check, never to accept. */
+export declare function timeRangeError(timeMin: string | undefined, timeMax: string | undefined): string | null;
+export declare const TIME_RANGE_HINT: string;
 export declare function formatEvent(event: any, opts?: {
     full?: boolean;
 }): {

package/dist/tools/calendar.js

@@ -3,8 +3,9 @@ import { coerceArray, coerceBoolean } from './_coerce.js';
 import { calendar as calendarClient } from '@googleapis/calendar';
 import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
-import { handleGoogleApiError } from './_errors.js';
-import { sliceClean } from '../trim.js';
+import { checkOutbound } from '../outbound-allowlist.js';
+import { handleGoogleApiError, invalidParams } from './_errors.js';
+import { listResult, sliceClean } from '../trim.js';
 const accountEnum = accountAliasSchema.optional();
 export function registerCalendarTools(server) {
     server.registerTool('calendar_list_calendars', {
@@ -46,8 +47,13 @@ export function registerCalendarTools(server) {
                 .describe('End of time range (ISO 8601)'),
             maxResults: z.number().min(1).max(250).default(25).optional()
                 .describe('Max events to return (default: 25)'),
+            pageToken: z.string().min(1).optional()
+                .describe('Continuation token from a previous call\'s nextPageToken'),
         },
-    }, async ({ account, calendarId, query, timeMin, timeMax, maxResults }) => {
+    }, async ({ account, calendarId, query, timeMin, timeMax, maxResults, pageToken }) => {
+        const rangeError = timeRangeError(timeMin, timeMax);
+        if (rangeError)
+            return invalidParams(account, rangeError, TIME_RANGE_HINT);
         try {
             const auth = await getClient(account);
             const cal = calendarClient({ version: 'v3', auth });
@@ -63,13 +69,19 @@ export function registerCalendarTools(server) {
                 params.timeMin = timeMin;
             if (timeMax)
                 params.timeMax = timeMax;
-            if (!timeMin && !timeMax) {
+            if (pageToken)
+                params.pageToken = pageToken;
+            // A page token is only valid for the window that produced it, so
+            // re-evaluating the "now" default would fetch page 2 of a different query.
+            if (!timeMin && !timeMax && !pageToken) {
                 params.timeMin = new Date().toISOString();
             }
             const res = await cal.events.list(params);
             const events = (res.data.items ?? []).map((e) => formatEvent(e, { full: false }));
             return {
-                content: [{ type: 'text', text: JSON.stringify(events, null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify(listResult('events', events, {
+                            nextPageToken: res.data.nextPageToken,
+                        }), null, 2) }],
             };
         }
         catch (error) {
@@ -80,7 +92,7 @@ export function registerCalendarTools(server) {
         description: 'Get a single Google Calendar event by ID',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            eventId: z.string().describe('Calendar event ID'),
+            eventId: z.string().min(1).describe('Calendar event ID'),
             calendarId: z.string().default('primary').optional()
                 .describe('Calendar ID (default: primary)'),
         },
@@ -118,6 +130,11 @@ export function registerCalendarTools(server) {
         },
     }, async ({ account, summary, start, end, description, location, attendees, calendarId, allDay }) => {
         try {
+            if (attendees) {
+                const outbound = checkOutbound('calendar attendee', attendees.split(','), String(account));
+                if (outbound)
+                    return outbound;
+            }
             const auth = await getClient(account);
             const cal = calendarClient({ version: 'v3', auth });
             const event = { summary };
@@ -155,7 +172,7 @@ export function registerCalendarTools(server) {
         description: 'Update a Google Calendar event',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            eventId: z.string().describe('Calendar event ID'),
+            eventId: z.string().min(1).describe('Calendar event ID'),
             summary: z.string().optional().describe('New event title'),
             start: z.string().optional().describe('New start time (ISO 8601)'),
             end: z.string().optional().describe('New end time (ISO 8601)'),
@@ -168,6 +185,11 @@ export function registerCalendarTools(server) {
         },
     }, async ({ account, eventId, summary, start, end, description, location, attendees, calendarId }) => {
         try {
+            if (attendees) {
+                const outbound = checkOutbound('calendar attendee', attendees.split(','), String(account));
+                if (outbound)
+                    return outbound;
+            }
             const auth = await getClient(account);
             const cal = calendarClient({ version: 'v3', auth });
             // Fetch the event first so a 404 surfaces before we attempt the patch.
@@ -215,7 +237,7 @@ export function registerCalendarTools(server) {
         description: 'Delete a Google Calendar event',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            eventId: z.string().describe('Calendar event ID'),
+            eventId: z.string().min(1).describe('Calendar event ID'),
             calendarId: z.string().default('primary').optional()
                 .describe('Calendar ID (default: primary)'),
         },
@@ -265,9 +287,9 @@ export function registerCalendarTools(server) {
         description: 'Move an event from one calendar to another',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            calendarId: z.string().describe('Source calendar ID'),
-            eventId: z.string().describe('Event ID to move'),
-            destinationCalendarId: z.string().describe('Destination calendar ID'),
+            calendarId: z.string().min(1).describe('Source calendar ID'),
+            eventId: z.string().min(1).describe('Event ID to move'),
+            destinationCalendarId: z.string().min(1).describe('Destination calendar ID'),
             sendNotifications: coerceBoolean.optional().describe('Send notifications (default: false)'),
         },
     }, async ({ account, calendarId, eventId, destinationCalendarId, sendNotifications }) => {
@@ -294,13 +316,18 @@ export function registerCalendarTools(server) {
             account: accountEnum.describe('Google account alias'),
             calendarId: z.string().default('primary').optional()
                 .describe('Calendar ID (default: primary)'),
-            eventId: z.string().describe('ID of the recurring event series'),
+            eventId: z.string().min(1).describe('ID of the recurring event series'),
             timeMin: z.string().optional().describe('ISO 8601 — filter instances after this time'),
             timeMax: z.string().optional().describe('ISO 8601 — filter instances before this time'),
             maxResults: z.number().min(1).max(250).default(25).optional()
                 .describe('Max instances to return (default: 25)'),
+            pageToken: z.string().min(1).optional()
+                .describe('Continuation token from a previous call\'s nextPageToken'),
         },
-    }, async ({ account, calendarId, eventId, timeMin, timeMax, maxResults }) => {
+    }, async ({ account, calendarId, eventId, timeMin, timeMax, maxResults, pageToken }) => {
+        const rangeError = timeRangeError(timeMin, timeMax);
+        if (rangeError)
+            return invalidParams(account, rangeError, TIME_RANGE_HINT);
         try {
             const auth = await getClient(account);
             const cal = calendarClient({ version: 'v3', auth });
@@ -310,10 +337,13 @@ export function registerCalendarTools(server) {
                 timeMin,
                 timeMax,
                 maxResults: maxResults ?? 25,
+                ...(pageToken ? { pageToken } : {}),
             });
             const events = (res.data.items ?? []).map((e) => formatEvent(e, { full: false }));
             return {
-                content: [{ type: 'text', text: JSON.stringify(events, null, 2) }],
+                content: [{ type: 'text', text: JSON.stringify(listResult('instances', events, {
+                            nextPageToken: res.data.nextPageToken,
+                        }), null, 2) }],
             };
         }
         catch (error) {
@@ -331,6 +361,12 @@ export function registerCalendarTools(server) {
         },
     }, async ({ account, calendarIds, timeMin, timeMax, timeZone }) => {
         try {
+            if (calendarIds.length === 0) {
+                return invalidParams(account, '`calendarIds` is empty, so there is nothing to check.', 'Pass at least one calendar ID, e.g. ["primary"]. Use calendar_list_calendars to see the IDs this account can read.');
+            }
+            const rangeError = timeRangeError(timeMin, timeMax);
+            if (rangeError)
+                return invalidParams(account, rangeError, TIME_RANGE_HINT);
             const auth = await getClient(account);
             const cal = calendarClient({ version: 'v3', auth });
             const res = await cal.freebusy.query({
@@ -342,7 +378,11 @@ export function registerCalendarTools(server) {
                 },
             });
             return {
-                content: [{ type: 'text', text: JSON.stringify(res.data.calendars, null, 2) }],
+                // freebusy answers 200 with NO `calendars` key on an empty items
+                // list, and JSON.stringify(undefined) returns undefined, not a
+                // string: the SDK then rejected our own result with -32602. The
+                // value is a map keyed by calendar id, so the fallback is {}.
+                content: [{ type: 'text', text: JSON.stringify(res.data.calendars ?? {}, null, 2) }],
             };
         }
         catch (error) {
@@ -379,6 +419,26 @@ export function registerCalendarTools(server) {
 }
 const LIST_DESCRIPTION_CAP = 300;
 const TRUNCATION_MARKER = '… [truncated, use calendar_get_event]';
+/** Google disagrees with itself on a backwards window: events.list answers 200
+ * with [], which reads as "nothing scheduled", while freebusy.query 400s on the
+ * identical input. Decide locally so an empty list always means empty. Returns
+ * null when either bound is absent or unparseable: those stay Google's call.
+ * Date.parse is lenient, so it is used only to SKIP the check, never to accept. */
+export function timeRangeError(timeMin, timeMax) {
+    if (timeMin === undefined || timeMax === undefined)
+        return null;
+    const min = Date.parse(timeMin);
+    const max = Date.parse(timeMax);
+    if (Number.isNaN(min) || Number.isNaN(max))
+        return null;
+    if (min < max)
+        return null;
+    return min === max
+        ? `timeMin and timeMax are the same instant (${timeMin}), so the window contains nothing.`
+        : `timeMin (${timeMin}) is after timeMax (${timeMax}).`;
+}
+export const TIME_RANGE_HINT = 'Swap the two values or widen the window: timeMin must be strictly earlier than timeMax. ' +
+    'An empty result from this tool then always means "nothing scheduled", never "bad range".';
 export function formatEvent(event, opts = {}) {
     const full = opts.full ?? true;
     const description = event.description ?? '';

package/dist/tools/chat.js

@@ -3,7 +3,7 @@ import { coerceJson } from './_coerce.js';
 import { chat as chatClient } from '@googleapis/chat';
 import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
-import { handleGoogleApiError } from './_errors.js';
+import { handleGoogleApiError, invalidParams } from './_errors.js';
 const accountEnum = accountAliasSchema.optional();
 export function registerChatTools(server) {
     server.registerTool('chat_spaces_list', {
@@ -35,7 +35,7 @@ export function registerChatTools(server) {
         description: 'Get details about a single Chat space',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            name: z.string().describe('Space resource name, format: spaces/{space}'),
+            name: z.string().min(1).describe('Space resource name, format: spaces/{space}'),
         },
     }, async ({ account, name }) => {
         try {
@@ -63,7 +63,7 @@ export function registerChatTools(server) {
     }, async ({ account, parent, text, cardsV2, threadKey, messageReplyOption }) => {
         try {
             if (!text && (!cardsV2 || cardsV2.length === 0)) {
-                return { content: [{ type: 'text', text: JSON.stringify({ error: 'Either text or cardsV2 must be provided' }) }], isError: true };
+                return invalidParams(account, 'A message needs content: neither text nor cardsV2 was supplied.', 'Pass text for a plain message, or cardsV2 for a Card v2 payload. Both may be sent together.');
             }
             const auth = await getClient(account);
             const chat = chatClient({ version: 'v1', auth });
@@ -118,5 +118,8 @@ export function registerChatTools(server) {
     });
 }
 function handleChatError(error, account) {
-    return handleGoogleApiError(error, account, "Chat tools require the optional \"chat\" scope bundle. Add GOOGLE_OPTIONAL_SCOPES=chat and re-auth.");
+    return handleGoogleApiError(error, account, {
+        scope: 'Chat tools require the optional "chat" scope bundle: add it to this account\'s scope profile, then re-auth.',
+        resource: `Google Chat denied this space or message to "${account}". The scope is not the problem: check that the account is a member of the space, and that Chat is turned on for the Workspace.`,
+    });
 }