mcp-google-multi 6.0.0-alpha.73 → 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/discover.js

@@ -96,9 +96,8 @@ export function registerDiscoverTools(registry, policy) {
                             service,
                             operations,
                             writeControl: rendered?.hint ?? describePolicy(policy),
-                            next: operations.length > 0
-                                ? 'Call the chosen tool by name; it is now listed and callable.'
-                                : `No ${service} operation matches "${query}". Call again without query for the full catalog.`,
+                            // catalog() falls back to a full one-line listing when nothing matches, so this is never empty.
+                            next: 'Call the chosen tool by its exact name. A client that loads tools on demand may need its own tool-search or load step before the call succeeds.',
                         }),
                     },
                 ],

package/dist/hint-provider.d.ts

@@ -58,7 +58,10 @@ export type HintCase = {
     entries: string[];
 } | {
     kind: 'no_default_account';
-    aliases: string[];
+    accounts: {
+        alias: string;
+        email: string;
+    }[];
 } | {
     kind: 'no_accounts';
 } | {

package/dist/oauth-as.js

@@ -425,7 +425,7 @@ export function buildAuthServer(config, deps = {}) {
             res.end(`<!doctype html><meta charset=utf-8><title>Authorize access</title>` +
                 `<body style="font-family:system-ui,sans-serif;max-width:36em;margin:3em auto;line-height:1.5">` +
                 `<h2>Authorize access?</h2>` +
-                `<p>A newly-registered application (<code>${escapeHtml(clientId)}</code>) is requesting access to your Google Workspace through this server.</p>` +
+                `<p>An application (<code>${escapeHtml(clientId)}</code>) asks to connect to this server as you.</p>` +
                 `<p>If approved, it will receive an authorization redirected to:<br><code>${escapeHtml(redirectUri)}</code></p>` +
                 `<p><strong>If you did not start this, close this window.</strong></p>` +
                 `<form method="POST" action="/authorize"><input type="hidden" name="pending" value="${escapeHtml(pendingToken)}">` +
@@ -498,7 +498,7 @@ export function buildAuthServer(config, deps = {}) {
             }
             log(`callback ok flow=alias_add alias=${logSafe(st.alias, 64)}`);
             res.writeHead(200, { 'Content-Type': 'text/html' });
-            res.end(`<!doctype html><meta charset=utf-8><p>Connected "${escapeHtml(st.alias)}". You can close this window and retry your request.</p>`);
+            res.end(`<!doctype html><meta charset=utf-8><p>Linked "${escapeHtml(st.alias)}" to this server. Start a new chat to use it.</p>`);
             return true;
         }
         if (st.flow === 'alias_reauth') {

package/dist/registry.d.ts

@@ -38,6 +38,8 @@ export interface CatalogOperation {
      * real scope error rather than a bare "not found". */
     unreachable?: true;
 }
+/** The leading sentence of a (possibly multi-sentence) tool description. */
+export declare function firstSentence(text: string): string;
 /** The service a tool name belongs to: its prefix, unless overridden. */
 export declare function serviceOf(name: string): string;
 export declare function inferCud(name: string): Cud;

package/dist/registry.js

@@ -23,11 +23,44 @@ export function resolveDiscoveryMode(env = process.env) {
     }
     return DISCOVERY_MODES.includes(raw) ? raw : 'lazy';
 }
+/** The leading sentence of a (possibly multi-sentence) tool description. */
+export function firstSentence(text) {
+    let openParens = 0;
+    let i = 0;
+    const abbrevs = /^(e\.g|i\.e|etc|vs)\.$/i;
+    while (i < text.length) {
+        const char = text[i];
+        if (char === '(') {
+            openParens++;
+        }
+        else if (char === ')') {
+            openParens = Math.max(0, openParens - 1);
+        }
+        else if (char === '.' && i + 1 < text.length && text[i + 1] === ' ' && openParens === 0) {
+            // Found a period-space outside parentheses
+            // Check if it's preceded by an abbreviation (e.g., i.e., etc, vs)
+            // Find the word before this period
+            let wordStart = i - 1;
+            while (wordStart > 0 && /[a-zA-Z.]/.test(text[wordStart - 1])) {
+                wordStart--;
+            }
+            const word = text.slice(wordStart, i + 1);
+            if (!abbrevs.test(word)) {
+                // Not an abbreviation, so this is a valid sentence boundary
+                return text.slice(0, i + 1);
+            }
+        }
+        i++;
+    }
+    return text;
+}
 const CUD_OVERRIDES = {
     drive_untrash: 'update',
     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',
@@ -196,8 +229,10 @@ export class ToolRegistry {
                     refreshAccountSetIfStale();
                     const def = this.accounts().defaultAccount;
                     if (!def) {
-                        const aliases = this.accounts().aliases;
-                        const rendered = hints()?.render({ kind: 'no_default_account', aliases });
+                        const accountSet = this.accounts();
+                        const accounts = accountSet.aliases.map((alias) => ({ alias, email: accountSet.configs[alias]?.email ?? '' }));
+                        const rendered = hints()?.render({ kind: 'no_default_account', accounts });
+                        const pairs = accounts.map((a) => `${a.alias}=${a.email}`).join(', ');
                         return {
                             content: [
                                 {
@@ -205,7 +240,7 @@ export class ToolRegistry {
                                     text: JSON.stringify({
                                         error: 'E_NO_DEFAULT_ACCOUNT',
                                         message: 'No "account" given and no default account is configured.',
-                                        hint: rendered?.hint ?? `Pass account explicitly (valid: ${aliases.join(', ')}), or set GOOGLE_DEFAULT_ACCOUNT / "defaultAccount" in config.json.`,
+                                        hint: rendered?.hint ?? `Pass account explicitly (valid: ${pairs}), or set GOOGLE_DEFAULT_ACCOUNT / "defaultAccount" in config.json.`,
                                         retriable: false,
                                     }),
                                 },
@@ -313,17 +348,31 @@ export class ToolRegistry {
             .map(([key, e]) => ({ key, tools: e.tools }));
     }
     catalog(service, query) {
-        const q = query?.trim().toLowerCase();
-        return this.tools
-            .filter((t) => !t.meta && t.service === service)
-            .filter((t) => !q || t.name.toLowerCase().includes(q) || t.description.toLowerCase().includes(q))
-            .map((t) => ({
+        const candidates = this.tools.filter((t) => !t.meta && t.service === service);
+        const toOp = (t, summary = t.description) => ({
             tool: t.name,
-            summary: t.description,
+            summary,
             args: Object.keys(t.inputShape),
             cud: t.cud,
             ...(this.isUngrantable(t) ? { unreachable: true } : {}),
-        }));
+        });
+        const q = query?.trim().toLowerCase();
+        if (!q)
+            return candidates.map((t) => toOp(t));
+        // Tokenized OR-match (a strict superset of a plain substring test: a full-string
+        // hit implies every one of its tokens also hits) ranked by how many tokens matched.
+        const ranked = candidates
+            .map((t) => {
+            const hay = `${t.name} ${t.description}`.toLowerCase();
+            return { t, matched: q.split(/\s+/).filter(Boolean).filter((tok) => hay.includes(tok)).length };
+        })
+            .filter((r) => r.matched > 0)
+            .sort((a, b) => b.matched - a.matched);
+        if (ranked.length > 0)
+            return ranked.map((r) => toOp(r.t));
+        // Nothing matched: list the whole service so the agent can still browse,
+        // one-line summaries only so a wide miss doesn't blow the response budget.
+        return candidates.map((t) => toOp(t, firstSentence(t.description)));
     }
     /** The metrics recorder, for hook sites (escape hatch); null when off. */
     get usageMetrics() {

package/dist/tools/accounts-tool.d.ts

@@ -36,4 +36,11 @@ export interface AccountHealth {
     scopes: ScopesReport;
 }
 export declare function deriveAccountHealth(alias: string, deps?: AccountHealthDeps): AccountHealth;
+export interface AccountSummary {
+    alias: string;
+    email: string;
+    admin: boolean;
+    tokenStatus: TokenStatus;
+    default: boolean;
+}
 export declare function registerAccountTools(registry: ToolRegistry, deps?: AccountHealthDeps): void;

package/dist/tools/accounts-tool.js

@@ -5,6 +5,7 @@ import { buildScopesReport } from '../scope-observability.js';
 import { getAdminAccounts, resolveScopesForAccount } from '../auth.js';
 import { hasToken, readToken } from '../token-store.js';
 import { hints } from '../hint-provider.js';
+import { coerceBoolean } from './_coerce.js';
 /** Health deps over one context's token store (and, optionally, its account
  * view); the module-level functions are the single owner's store. */
 export function accountHealthDepsFor(store, accounts) {
@@ -91,18 +92,28 @@ export function deriveAccountHealth(alias, deps = DEFAULT_DEPS) {
         scopes: report,
     };
 }
+function summarizeAccountHealth(health, isDefault) {
+    return {
+        alias: health.alias,
+        email: health.email,
+        admin: health.admin,
+        tokenStatus: health.token.status,
+        default: isDefault,
+    };
+}
 export function registerAccountTools(registry, deps = DEFAULT_DEPS) {
     const registerMeta = registry.registerMeta;
     registerMeta('account_list', {
-        description: 'List the configured Google accounts: alias, email, admin flag, token health ' +
-            '(ok / expired_refreshable / needs_reauth / missing / decrypt_error), and granted vs configured scopes. ' +
-            'Use this to see which account aliases are available and healthy.',
-        inputSchema: {},
+        description: 'List the configured Google accounts: alias, email, admin flag, token status ' +
+            '(ok / expired_refreshable / needs_reauth / missing / decrypt_error), and which one is the default. ' +
+            'Pass verbose: true for the full per-account report (granted vs configured scopes).',
+        inputSchema: { verbose: coerceBoolean.optional().describe('Return the full scope report instead of the terse default') },
         _meta: { 'anthropic/alwaysLoad': true },
-    }, async () => {
+    }, async ({ verbose }) => {
         refreshAccountSetIfStale();
         const set = registry.accountSet();
         const health = { ...deps, accounts: () => set };
+        const reports = set.aliases.map((alias) => deriveAccountHealth(alias, health));
         return {
             content: [
                 {
@@ -110,7 +121,7 @@ export function registerAccountTools(registry, deps = DEFAULT_DEPS) {
                     text: JSON.stringify({
                         defaultAccount: set.defaultAccount ?? null,
                         defaultAccountSource: set.defaultAccountSource ?? null,
-                        accounts: set.aliases.map((alias) => deriveAccountHealth(alias, health)),
+                        accounts: verbose ? reports : reports.map((r) => summarizeAccountHealth(r, r.alias === set.defaultAccount)),
                     }),
                 },
             ],

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/dist/tools/generated/gmail.js

@@ -18,20 +18,6 @@ export function registerGmailGeneratedTools(registry, deps = {}) {
         ["https://mail.google.com/", "https://www.googleapis.com/auth/gmail.metadata", "https://www.googleapis.com/auth/gmail.modify", "https://www.googleapis.com/auth/gmail.readonly"],
         ["https://mail.google.com/"],
     ];
-    registerGeneratedTool(registry, {
-        name: "gmail_users_drafts_delete",
-        cud: "delete",
-        description: "Immediately and permanently deletes the specified draft. Does not simply trash it. For more information, see [Create and send draft emails](https://developers.g",
-        method: { id: "gmail.users.drafts.delete", httpMethod: "DELETE", path: "gmail/v1/users/{userId}/drafts/{id}", baseUrl: "https://gmail.googleapis.com/", requiredParams: ["userId", "id"], scopes: S_gmail_v1[0] },
-        params: [{ "field": "id", "api": "id", "location": "path" }, { "field": "userId", "api": "userId", "location": "path" }, { "field": "fields", "api": "fields", "location": "query" }],
-        hasBody: false,
-        shape: {
-            account: accountField(() => registry.accountAliases()),
-            id: z.string().min(1).describe("The ID of the draft to delete."),
-            userId: z.string().min(1).describe("The user's email address. The special value `me` can be used to indicate the authenticated user."),
-            fields: z.string().optional().describe('Response field mask.'),
-        },
-    }, deps);
     registerGeneratedTool(registry, {
         name: "gmail_users_drafts_update",
         cud: "update",

package/dist/tools/generated/method-map.js

@@ -550,7 +550,6 @@ export const GENERATED_METHOD_TOOLS = {
     "forms.forms.watches.create": "forms_forms_watches_create",
     "forms.forms.watches.delete": "forms_forms_watches_delete",
     "forms.forms.watches.renew": "forms_forms_watches_renew",
-    "gmail.users.drafts.delete": "gmail_users_drafts_delete",
     "gmail.users.drafts.update": "gmail_users_drafts_update",
     "gmail.users.labels.get": "gmail_users_labels_get",
     "gmail.users.labels.patch": "gmail_users_labels_patch",
@@ -818,6 +817,7 @@ export const CURATED_METHOD_IDS = [
     "forms.forms.setPublishSettings",
     "forms.forms.watches.list",
     "gmail.users.drafts.create",
+    "gmail.users.drafts.delete",
     "gmail.users.drafts.get",
     "gmail.users.drafts.list",
     "gmail.users.drafts.send",

package/dist/tools/gmail.d.ts

@@ -33,7 +33,7 @@ export declare function parseMessage(msg: any, bodyCap?: number, opts?: {
  * is rethrown so the caller maps it to a whole-call isError. Returns the
  * ordered per-id entries followed by a trailing counts summary.
  */
-export declare function readBatch(gmail: any, account: Account, ids: string[], full: boolean, rawHtml: boolean): Promise<any[]>;
+export declare function readBatch(gmail: any, account: Account, ids: string[], full: boolean, rawHtml: boolean, metaHeaders?: string[]): Promise<any[]>;
 /** Compact gmail_search row: just the pick-one-message selection signal, with
  * the snippet flattened to one bounded line. Pure. */
 export declare function compactMessageRow(m: GmailMessageHeader): {

package/dist/tools/gmail.js

@@ -17,6 +17,12 @@ import * as fs from 'fs';
 function getHeader(headers, name) {
     return headers?.find((h) => h.name?.toLowerCase() === name.toLowerCase())?.value ?? '';
 }
+function pickHeaders(headers, names) {
+    const out = {};
+    for (const name of names)
+        out[name] = getHeader(headers, name);
+    return out;
+}
 function collectTextParts(part, plain, html, topLevel = false) {
     if (!part)
         return;
@@ -176,6 +182,21 @@ export async function resolveReply(gmail, account, primaryEmail, replyToMessageI
         subject: deriveReplySubject(getHeader(headers, 'Subject')),
     };
 }
+// Gmail's after:/before: operators take epoch seconds; Date.parse accepts both
+// an ISO date and a full date-time, so one parse covers both input shapes.
+function parseEpochSeconds(value) {
+    // A date-only value is interpreted as 00:00 UTC.
+    // A date-time must include Z or an offset (+HH:MM or -HH:MM) to be unambiguous.
+    if (value.includes('T')) {
+        const hasZ = value.endsWith('Z');
+        const hasOffset = /[+-]\d{2}:\d{2}$/.test(value);
+        if (!hasZ && !hasOffset) {
+            return null;
+        }
+    }
+    const ms = Date.parse(value);
+    return Number.isNaN(ms) ? null : Math.floor(ms / 1000);
+}
 const BODY_CAP_CHARS = 50_000;
 // gmail_read_batch aggregate ceiling: bounds the summed serialized output so a
 // 100-message batch can't blow the context window (per-message bodies are capped at BODY_CAP_CHARS first).
@@ -331,13 +352,14 @@ export function parseMessage(msg, bodyCap, opts) {
  * is rethrown so the caller maps it to a whole-call isError. Returns the
  * ordered per-id entries followed by a trailing counts summary.
  */
-export async function readBatch(gmail, account, ids, full, rawHtml) {
+export async function readBatch(gmail, account, ids, full, rawHtml, metaHeaders) {
     if (ids.length === 0) {
         throw new GmailComposeError('validation_error', '`ids` must be a non-empty array of 1..100 message IDs.');
     }
     if (ids.length > 100) {
         throw new GmailComposeError('validation_error', `\`ids\` accepts at most 100 message IDs per call (got ${ids.length}).`);
     }
+    const metadataMode = metaHeaders !== undefined && metaHeaders.length > 0;
     const cap = full ? undefined : BODY_CAP_CHARS;
     const CHUNK_SIZE = 10;
     const entries = new Array(ids.length);
@@ -347,7 +369,9 @@ export async function readBatch(gmail, account, ids, full, rawHtml) {
         const slice = ids.slice(i, i + CHUNK_SIZE);
         const settled = await Promise.all(slice.map(async (id, j) => {
             try {
-                const res = await gmail.users.messages.get({ userId: 'me', id, format: 'full' });
+                const res = metadataMode
+                    ? await gmail.users.messages.get({ userId: 'me', id, format: 'metadata', metadataHeaders: metaHeaders })
+                    : await gmail.users.messages.get({ userId: 'me', id, format: 'full' });
                 return { idx: i + j, id, ok: true, data: res.data };
             }
             catch (err) {
@@ -356,7 +380,14 @@ export async function readBatch(gmail, account, ids, full, rawHtml) {
         }));
         for (const s of settled) {
             if (s.ok) {
-                entries[s.idx] = parseMessage(s.data, cap, { rawHtml });
+                entries[s.idx] = metadataMode
+                    ? {
+                        id: s.data.id ?? '',
+                        threadId: s.data.threadId ?? '',
+                        labelIds: s.data.labelIds ?? [],
+                        headers: pickHeaders(s.data.payload?.headers, metaHeaders),
+                    }
+                    : parseMessage(s.data, cap, { rawHtml });
                 ok++;
             }
             else {
@@ -374,10 +405,11 @@ export async function readBatch(gmail, account, ids, full, rawHtml) {
     }
     // Aggregate guard: walk in order accumulating serialized size; once the running
     // total would exceed the budget, cap this and every later success body so the batch never blows the context window.
+    // Metadata-mode entries carry no body, so there is nothing to cap.
     let running = 0;
     let truncatedAny = false;
     let exhausted = false;
-    for (const e of entries) {
+    for (const e of metadataMode ? [] : entries) {
         if (!e || e.error) {
             running += JSON.stringify(e ?? {}).length;
             continue;
@@ -434,27 +466,50 @@ export function registerGmailTools(server, deps = {}) {
     const registerHostFileTool = localFiles ? server.registerTool : (() => undefined);
     server.registerTool('gmail_search', {
         description: 'Search messages in a Gmail account. Returns compact rows (id, from, subject, date, snippet); ' +
-            'pass full=true for threadId, to, labelIds and the untruncated snippet.',
+            'pass full=true for threadId, to, labelIds and the untruncated snippet. ' +
+            'For a recurring "what is new" sweep, prefer gmail_list_history over polling this with since.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             query: z.string().describe('Gmail search syntax, e.g. "from:alice is:unread"'),
             maxResults: coerceNumber(z.number().min(1).max(100)).optional()
                 .describe('Max results to return (default: 20, max: 100)'),
             full: coerceBoolean.optional().describe('Return the full row shape instead of the compact default'),
+            since: z.string().optional()
+                .describe('Only messages on/after this ISO 8601 date (00:00 UTC) or date-time with Z or offset, added to the query as after:<epoch seconds>'),
+            until: z.string().optional()
+                .describe('Only messages before this ISO 8601 date (00:00 UTC) or date-time with Z or offset, added to the query as before:<epoch seconds>'),
+            includeSpamTrash: coerceBoolean.optional()
+                .describe('Include Spam and Trash in the search. Gmail excludes both by default, even for in:anywhere.'),
         },
-    }, async ({ account, query, maxResults, full }) => {
+    }, async ({ account, query, maxResults, full, since, until, includeSpamTrash }) => {
         try {
             // Gmail treats a blank `q` as no filter, so a caller passing an unset
             // variable got the whole mailbox back as if it had matched.
             if (query.trim() === '') {
                 return invalidParams(account, '`query` is empty, and Gmail reads an empty query as "match everything".', 'Pass a real Gmail search term such as "is:unread" or "from:someone@example.com". Returning the whole mailbox for a blank query would look like a successful search.');
             }
+            let effectiveQuery = query;
+            if (since !== undefined) {
+                const epoch = parseEpochSeconds(since);
+                if (epoch === null) {
+                    return invalidParams(account, `\`since\` is not a parsable ISO 8601 date or date-time: "${since}".`, 'Pass an ISO 8601 date (e.g. "2026-01-01") or a date-time with Z or offset (e.g. "2026-01-01T09:00:00Z").');
+                }
+                effectiveQuery = `${effectiveQuery} after:${epoch}`;
+            }
+            if (until !== undefined) {
+                const epoch = parseEpochSeconds(until);
+                if (epoch === null) {
+                    return invalidParams(account, `\`until\` is not a parsable ISO 8601 date or date-time: "${until}".`, 'Pass an ISO 8601 date (e.g. "2026-01-01") or a date-time with Z or offset (e.g. "2026-01-01T09:00:00Z").');
+                }
+                effectiveQuery = `${effectiveQuery} before:${epoch}`;
+            }
             const auth = await getClientFn(account);
             const gmail = gmailClient({ version: 'v1', auth });
             const listRes = await gmail.users.messages.list({
                 userId: 'me',
-                q: query,
+                q: effectiveQuery,
                 maxResults: maxResults ?? 20,
+                ...(includeSpamTrash !== undefined ? { includeSpamTrash } : {}),
             });
             const messages = listRes.data.messages ?? [];
             const results = [];
@@ -495,18 +550,38 @@ export function registerGmailTools(server, deps = {}) {
     });
     server.registerTool('gmail_read', {
         _meta: { 'anthropic/maxResultSizeChars': 50_000 },
-        description: 'Read a full Gmail message by ID (body capped at 50k chars unless full=true)',
+        description: 'Read a full Gmail message by ID (body capped at 50k chars unless full=true). ' +
+            'Pass `headers` for metadata mode: no body decoding, just id, threadId, labelIds and the named headers.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             messageId: z.string().min(1).describe('Gmail message ID'),
             full: coerceBoolean.optional().describe('Return the entire body without the character cap'),
             rawHtml: coerceBoolean.optional()
                 .describe('Return the HTML body unconverted instead of the plain-text rendering (HTML-only messages)'),
+            headers: coerceArray(z.string()).optional()
+                .describe('Header names to fetch in metadata mode instead of the full body (e.g. ["Subject", "From"])'),
         },
-    }, async ({ account, messageId, full, rawHtml }) => {
+    }, async ({ account, messageId, full, rawHtml, headers }) => {
         try {
             const auth = await getClientFn(account);
             const gmail = gmailClient({ version: 'v1', auth });
+            if (headers !== undefined && headers.length > 0) {
+                const metaRes = await gmail.users.messages.get({
+                    userId: 'me',
+                    id: messageId,
+                    format: 'metadata',
+                    metadataHeaders: headers,
+                });
+                const metaResult = {
+                    id: metaRes.data.id ?? '',
+                    threadId: metaRes.data.threadId ?? '',
+                    labelIds: metaRes.data.labelIds ?? [],
+                    headers: pickHeaders(metaRes.data.payload?.headers, headers),
+                };
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(metaResult, null, 2) }],
+                };
+            }
             const res = await gmail.users.messages.get({
                 userId: 'me',
                 id: messageId,
@@ -576,19 +651,21 @@ export function registerGmailTools(server, deps = {}) {
     server.registerTool('gmail_read_batch', {
         _meta: { 'anthropic/maxResultSizeChars': BATCH_MAX_RESULT_CHARS },
         annotations: { readOnlyHint: true, openWorldHint: true },
-        description: 'Read many Gmail messages by ID in one call, collapsing the search→read triage loop. Bodies are capped at 50k chars each (unless full=true) and the aggregate output is bounded. Returns one ordered entry per id plus a trailing counts summary; a single failed id does NOT fail the batch.',
+        description: 'Read many Gmail messages by ID in one call, collapsing the search→read triage loop. Bodies are capped at 50k chars each (unless full=true) and the aggregate output is bounded. Returns one ordered entry per id plus a trailing counts summary; a single failed id does NOT fail the batch. Pass `headers` for metadata mode: no body decoding, just id, threadId, labelIds and the named headers per entry.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             ids: coerceArray(z.string()).describe('Gmail message IDs to read (1..100). Comma-separated string or JSON array.'),
             full: coerceBoolean.optional().describe('Return entire bodies without the per-message 50k character cap'),
             rawHtml: coerceBoolean.optional()
                 .describe('Return HTML bodies unconverted instead of the plain-text rendering (HTML-only messages)'),
+            headers: coerceArray(z.string()).optional()
+                .describe('Header names to fetch in metadata mode instead of full bodies (e.g. ["Subject", "From"])'),
         },
-    }, async ({ account, ids, full, rawHtml }) => {
+    }, async ({ account, ids, full, rawHtml, headers }) => {
         try {
             const auth = await getClientFn(account);
             const gmail = gmailClient({ version: 'v1', auth });
-            const result = await readBatch(gmail, account, ids ?? [], full === true, rawHtml === true);
+            const result = await readBatch(gmail, account, ids ?? [], full === true, rawHtml === true, headers);
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
             };
@@ -993,6 +1070,26 @@ export function registerGmailTools(server, deps = {}) {
             return mapped ?? handleGmailError(error, account);
         }
     });
+    server.registerTool('gmail_delete_draft', {
+        description: 'Permanently delete a Gmail draft by its draft ID',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias'),
+            draftId: z.string().min(1).describe('Draft ID to delete'),
+        },
+    }, async ({ account, draftId }) => {
+        try {
+            const auth = await getClientFn(account);
+            const gmail = gmailClient({ version: 'v1', auth });
+            await gmail.users.drafts.delete({ userId: 'me', id: draftId });
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ deleted: true, draftId }, null, 2) }],
+            };
+        }
+        catch (error) {
+            const mapped = composeErrorResult(error, account);
+            return mapped ?? handleGmailError(error, account);
+        }
+    });
     server.registerTool('gmail_list_labels', {
         description: 'List all Gmail labels (system and user-defined). Use to get label IDs for gmail_modify_labels.',
         inputSchema: {

package/dist/write-control.js

@@ -13,12 +13,12 @@ export const IRREVERSIBLE_TOOLS = new Set([
     'gmail_send',
     'gmail_send_draft',
     'gmail_delete',
+    'gmail_delete_draft',
     'gmail_batch_delete',
     'drive_delete',
     'drive_empty_trash',
     // generated twins (permanent deletes / real sends)
     'gmail_users_threads_delete',
-    'gmail_users_drafts_delete',
     'chat_spaces_messages_delete',
     'cloudidentity_customers_userinvitations_send',
     'vault_matters_holds_delete',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.73",
+  "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",