mcp-google-multi 6.0.0-alpha.74 → 6.0.0-alpha.75

package/README.md

@@ -4,7 +4,7 @@ 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** — 940 tools across 29 services, now including Google Analytics (GA4), + an escape hatch for anything else → [COVERAGE.md](./COVERAGE.md)
+- 🧰 **Exhaustive** — 941 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). Pull-and-up Docker Compose with optional automatic HTTPS → [remote setup](./docs/http-setup.md)

package/dist/registry.js

@@ -59,6 +59,8 @@ const CUD_OVERRIDES = {
     drive_transfer: 'create',
     // read-only resolver; the name's "resolve" verb would otherwise infer update.
     contacts_resolve: 'read',
+    // "respond" matches no write verb; it patches the event (a write).
+    calendar_respond_event: 'update',
     // Gated by anthropic/requiresUserInteraction, not write-control, so
     // onboarding works under any profile; cud=read also keeps them off fan-out.
     account_add: 'read',

package/dist/tools/admin.js

@@ -68,7 +68,12 @@ export function registerAdminTools(server, deps = {}) {
             account: accountEnum.describe('Google account alias (must be a Workspace admin)'),
             customer: z.string().default('my_customer').optional(),
             domain: z.string().optional(),
-            query: z.string().optional().describe('Search query, e.g. "name:John"'),
+            query: z.string().optional().describe('Directory search query: space-separated clauses of field+operator+value, ANDed together. ' +
+                '"=" is exact match, ":" is a contains/startsWith match. Searchable fields include email, name ' +
+                '(matches the concatenated givenName+familyName), givenName, familyName, isAdmin, isDelegatedAdmin, ' +
+                'orgName, orgTitle, orgDepartment, manager, directManager, addressCountry. Prefix/wildcard matching ' +
+                'is a trailing "*" on a ":" clause, e.g. "email:admin*" for every address starting with "admin". ' +
+                'Examples: \'name:John\', \'isAdmin=true\', \'orgTitle:Manager orgName=Engineering\'.'),
             maxResults: z.number().min(1).max(500).optional(),
             pageToken: z.string().optional(),
             orderBy: z.enum(['email', 'familyName', 'givenName']).optional(),

package/dist/tools/analytics.js

@@ -4,7 +4,7 @@ import { analyticsdata as analyticsdataClient } from '@googleapis/analyticsdata'
 import { analyticsadmin as analyticsadminClient } from '@googleapis/analyticsadmin';
 import { accountArgLive } from '../accounts.js';
 import { getClient } from '../client.js';
-import { handleGoogleApiError } from './_errors.js';
+import { handleGoogleApiError, invalidParams } from './_errors.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. */
@@ -104,6 +104,11 @@ export function shapeMetadata(data) {
 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.');
+// Accepts this server's plain string form and the native GA4 API shape ({name}),
+// so a request built against GA4's own docs works unmodified.
+const metricOrDimensionRef = z.union([z.string(), z.object({ name: z.string() })]);
+const nameOf = (ref) => (typeof ref === 'string' ? ref : ref.name);
+const dateRangeRef = z.object({ startDate: z.string(), endDate: z.string() });
 export function registerAnalyticsTools(server, deps = {}) {
     // Per-registry, live account enum + injectable client: the schema follows
     // the registry's account view at parse time, not a process-global default.
@@ -130,16 +135,19 @@ export function registerAnalyticsTools(server, deps = {}) {
         }
     });
     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.',
+        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"). Also accepts the native GA4 request shapes directly: a single dateRanges entry in place of startDate/endDate, and metrics/dimensions as {name} objects. 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())
+            startDate: z.string().optional().describe('Start date: YYYY-MM-DD or relative ("today", "yesterday", "NdaysAgo" e.g. "28daysAgo"). Required unless dateRanges is given.'),
+            endDate: z.string().optional().describe('End date: YYYY-MM-DD or relative ("today", "yesterday", "NdaysAgo"). Required unless dateRanges is given.'),
+            dateRanges: coerceJson(z.array(dateRangeRef))
                 .optional()
-                .describe('Dimension API names to group by, e.g. ["date"] or ["country","deviceCategory"]. Max 9. Omit for a single total row.'),
+                .describe('Native GA4 shape, as an alternative to startDate/endDate: exactly one {startDate, endDate} entry (this tool runs one range per call).'),
+            metrics: coerceArray(metricOrDimensionRef).describe('Metric API names, e.g. ["activeUsers","sessions","screenPageViews"], or the native GA4 [{"name":"activeUsers"}] form. Max 10. Valid names (including custom ones) come from analytics_get_metadata.'),
+            dimensions: coerceArray(metricOrDimensionRef)
+                .optional()
+                .describe('Dimension API names to group by, e.g. ["date"] or ["country","deviceCategory"], or the native GA4 {"name":...} form. 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.'),
@@ -157,19 +165,28 @@ export function registerAnalyticsTools(server, deps = {}) {
             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 }) => {
+    }, async ({ account, property, startDate, endDate, dateRanges, metrics, dimensions, dimensionFilter, metricFilter, orderBys, limit, offset, metricAggregations, keepEmptyRows, returnPropertyQuota }) => {
         const prop = normalizeProperty(property);
         if ('hint' in prop)
             return invalidProperty(prop.hint, account);
+        if (dateRanges !== undefined && dateRanges.length > 1) {
+            return invalidParams(account, `dateRanges has ${dateRanges.length} entries, but analytics_run_report runs a single range per call.`, 'Pass exactly one {startDate, endDate} entry, or call the tool once per range.');
+        }
+        const range = dateRanges?.[0];
+        const resolvedStart = range?.startDate ?? startDate;
+        const resolvedEnd = range?.endDate ?? endDate;
+        if (resolvedStart === undefined || resolvedEnd === undefined) {
+            return invalidParams(account, 'Missing a date range: pass startDate and endDate, or a single-entry dateRanges.', 'e.g. startDate: "28daysAgo", endDate: "today", or dateRanges: [{"startDate":"28daysAgo","endDate":"today"}].');
+        }
         try {
             const auth = await getClientFn(account);
             const dataApi = analyticsdataClient({ version: 'v1beta', auth });
             const requestBody = {
-                dateRanges: [{ startDate, endDate }],
-                metrics: metrics.map((name) => ({ name })),
+                dateRanges: [{ startDate: resolvedStart, endDate: resolvedEnd }],
+                metrics: metrics.map((ref) => ({ name: nameOf(ref) })),
             };
             if (dimensions?.length)
-                requestBody.dimensions = dimensions.map((name) => ({ name }));
+                requestBody.dimensions = dimensions.map((ref) => ({ name: nameOf(ref) }));
             if (dimensionFilter)
                 requestBody.dimensionFilter = dimensionFilter;
             if (metricFilter)

package/dist/tools/calendar.d.ts

@@ -8,6 +8,11 @@ export declare function registerCalendarTools(server: ToolRegistry, deps?: Curat
  * 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;
+/** The Calendar API requires timeMin/timeMax as RFC3339 with a mandatory
+ * offset; a bare local datetime is silently ambiguous rather than rejected,
+ * so catch it here with a message that names the field. */
+export declare function missingTimeZoneError(field: 'timeMin' | 'timeMax', value: string | undefined): string | null;
+export declare const MISSING_TIME_ZONE_HINT = "Add \"Z\" for UTC or an explicit offset, e.g. \"2026-04-04T00:00:00Z\" or \"2026-04-04T00:00:00+01:00\".";
 export declare function formatEvent(event: any, opts?: {
     full?: boolean;
 }): {

package/dist/tools/calendar.js

@@ -54,6 +54,9 @@ export function registerCalendarTools(server, deps = {}) {
                 .describe('Continuation token from a previous call\'s nextPageToken'),
         },
     }, async ({ account, calendarId, query, timeMin, timeMax, maxResults, pageToken }) => {
+        const tzError = missingTimeZoneError('timeMin', timeMin) ?? missingTimeZoneError('timeMax', timeMax);
+        if (tzError)
+            return invalidParams(account, tzError, MISSING_TIME_ZONE_HINT);
         const rangeError = timeRangeError(timeMin, timeMax);
         if (rangeError)
             return invalidParams(account, rangeError, TIME_RANGE_HINT);
@@ -236,6 +239,46 @@ export function registerCalendarTools(server, deps = {}) {
             return handleCalendarError(error, account);
         }
     });
+    // attendeesOmitted plus a single-entry attendees array patches only the caller's own RSVP.
+    server.registerTool('calendar_respond_event', {
+        description: 'RSVP to a calendar event as this account (accepted/declined/tentative) without touching any other attendee',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias'),
+            eventId: z.string().min(1).describe('Calendar event ID'),
+            calendarId: z.string().default('primary').optional()
+                .describe('Calendar ID (default: primary)'),
+            response: z.enum(['accepted', 'declined', 'tentative']).describe('RSVP response'),
+            comment: z.string().optional().describe('Optional comment attached to the response'),
+        },
+    }, async ({ account, eventId, calendarId, response, comment }) => {
+        try {
+            const auth = await getClientFn(account);
+            const cal = calendarClient({ version: 'v3', auth });
+            const cid = calendarId ?? 'primary';
+            const current = await cal.events.get({ calendarId: cid, eventId });
+            const attendees = current.data.attendees ?? [];
+            const accountEmail = server.accountSet().configs[account]?.email;
+            const self = attendees.find((a) => a.self)
+                ?? attendees.find((a) => a.email?.toLowerCase() === accountEmail?.toLowerCase());
+            if (!self?.email) {
+                return invalidParams(account, `Event "${eventId}" has no attendee entry for this account, so there is nothing to RSVP to.`, 'RSVP only applies to events where this account is invited as a guest; check calendar_get_event to see the attendee list.');
+            }
+            const res = await cal.events.patch({
+                calendarId: cid,
+                eventId,
+                requestBody: {
+                    attendeesOmitted: true,
+                    attendees: [{ email: self.email, responseStatus: response, ...(comment !== undefined ? { comment } : {}) }],
+                },
+            });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(formatEvent(res.data), null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleCalendarError(error, account);
+        }
+    });
     server.registerTool('calendar_delete_event', {
         description: 'Delete a Google Calendar event',
         inputSchema: {
@@ -328,6 +371,9 @@ export function registerCalendarTools(server, deps = {}) {
                 .describe('Continuation token from a previous call\'s nextPageToken'),
         },
     }, async ({ account, calendarId, eventId, timeMin, timeMax, maxResults, pageToken }) => {
+        const tzError = missingTimeZoneError('timeMin', timeMin) ?? missingTimeZoneError('timeMax', timeMax);
+        if (tzError)
+            return invalidParams(account, tzError, MISSING_TIME_ZONE_HINT);
         const rangeError = timeRangeError(timeMin, timeMax);
         if (rangeError)
             return invalidParams(account, rangeError, TIME_RANGE_HINT);
@@ -367,6 +413,9 @@ export function registerCalendarTools(server, deps = {}) {
             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 tzError = missingTimeZoneError('timeMin', timeMin) ?? missingTimeZoneError('timeMax', timeMax);
+            if (tzError)
+                return invalidParams(account, tzError, MISSING_TIME_ZONE_HINT);
             const rangeError = timeRangeError(timeMin, timeMax);
             if (rangeError)
                 return invalidParams(account, rangeError, TIME_RANGE_HINT);
@@ -440,6 +489,16 @@ export function timeRangeError(timeMin, 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".';
+const TZ_SUFFIX_RE = /(Z|[+-]\d{2}:?\d{2})$/;
+/** The Calendar API requires timeMin/timeMax as RFC3339 with a mandatory
+ * offset; a bare local datetime is silently ambiguous rather than rejected,
+ * so catch it here with a message that names the field. */
+export function missingTimeZoneError(field, value) {
+    if (value === undefined || TZ_SUFFIX_RE.test(value))
+        return null;
+    return `${field} ("${value}") has no "Z" or UTC offset, so its timezone is ambiguous.`;
+}
+export const MISSING_TIME_ZONE_HINT = 'Add "Z" for UTC or an explicit offset, e.g. "2026-04-04T00:00:00Z" or "2026-04-04T00:00:00+01:00".';
 export function formatEvent(event, opts = {}) {
     const full = opts.full ?? true;
     const description = event.description ?? '';

package/dist/tools/contacts.js

@@ -234,8 +234,8 @@ export function registerContactsTools(server, deps = {}) {
         description: 'List all contacts (paginated)',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            pageSize: z.number().min(1).max(1000).default(100).optional()
-                .describe('Number of contacts per page (default: 100)'),
+            pageSize: z.number().min(1).max(1000).default(50).optional()
+                .describe('Number of contacts per page (default: 50)'),
             pageToken: z.string().optional().describe('Page token for pagination'),
             sortOrder: z.enum([
                 'LAST_MODIFIED_ASCENDING',
@@ -244,19 +244,25 @@ export function registerContactsTools(server, deps = {}) {
                 'LAST_NAME_ASCENDING',
             ]).default('FIRST_NAME_ASCENDING').optional()
                 .describe('Sort order (default: FIRST_NAME_ASCENDING)'),
+            requireEmail: coerceBoolean.optional().describe('Only return contacts with at least one email address. Filtering happens after the page is fetched, so the returned page can hold fewer than pageSize contacts; nextPageToken still continues the underlying, unfiltered listing'),
+            requireName: coerceBoolean.optional().describe('Only return contacts with a name. Filtering happens after the page is fetched, so the returned page can hold fewer than pageSize contacts; nextPageToken still continues the underlying, unfiltered listing'),
         },
-    }, async ({ account, pageSize, pageToken, sortOrder }) => {
+    }, async ({ account, pageSize, pageToken, sortOrder, requireEmail, requireName }) => {
         try {
             const auth = await getClientFn(account);
             const people = peopleClient({ version: 'v1', auth });
             const res = await people.people.connections.list({
                 resourceName: 'people/me',
                 personFields: PERSON_FIELDS,
-                pageSize: pageSize ?? 100,
+                pageSize: pageSize ?? 50,
                 pageToken: pageToken ?? undefined,
                 sortOrder: sortOrder ?? 'FIRST_NAME_ASCENDING',
             });
-            const contacts = (res.data.connections ?? []).map(formatContact);
+            let contacts = (res.data.connections ?? []).map(formatContact);
+            if (requireEmail)
+                contacts = contacts.filter((c) => c.emails.length > 0);
+            if (requireName)
+                contacts = contacts.filter((c) => c.name !== '');
             return {
                 content: [{ type: 'text', text: JSON.stringify({
                             contacts,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.74",
+  "version": "6.0.0-alpha.75",
   "mcpName": "io.github.bakissation/mcp-google-multi",
   "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",