mcp-google-multi 6.0.0-beta.4 → 6.0.0-beta.5

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

@@ -380,35 +380,64 @@ export function registerDocsTools(server, deps = {}) {
     server.registerTool('docs_replace_text', {
         // Insert/append-capable or non-convergent: a retry duplicates content.
         annotations: { idempotentHint: false },
-        description: 'Find and replace all occurrences of text in a document',
+        description: 'Find and replace text in a document. Pass findText/replaceText for a single pair, or replacements for several pairs applied in one batchUpdate.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             documentId: z.string().min(1).describe('Google Docs document ID'),
-            findText: z.string().describe('Text to search for'),
-            replaceText: z.string().describe('Replacement text'),
+            findText: z.string().optional().describe('Text to search for. Use with replaceText; exactly one of this pair or `replacements` is required.'),
+            replaceText: z.string().optional().describe('Replacement text for findText'),
             matchCase: coerceBoolean.default(true).optional()
                 .describe('Case-sensitive match (default: true)'),
+            replacements: coerceJson(z.array(z.object({
+                findText: z.string(),
+                replaceText: z.string(),
+                matchCase: coerceBoolean.optional(),
+            })).min(1)).optional().describe('Several find/replace pairs applied in one batchUpdate, each returning its own count. Exactly one of this or findText/replaceText is required.'),
         },
-    }, async ({ account, documentId, findText, replaceText, matchCase }) => {
+    }, async ({ account, documentId, findText, replaceText, matchCase, replacements }) => {
+        const singlePair = findText !== undefined || replaceText !== undefined;
+        if (singlePair && replacements) {
+            return invalidParams(account, 'Pass either findText/replaceText or replacements, not both.', 'Use findText and replaceText for one pair, or replacements for several pairs in one call.');
+        }
+        if (!singlePair && !replacements) {
+            return invalidParams(account, 'Pass findText and replaceText, or a replacements array.', 'Use findText and replaceText for one pair, or replacements for several pairs in one call.');
+        }
+        if (singlePair && (findText === undefined || replaceText === undefined)) {
+            return invalidParams(account, 'Both findText and replaceText are required together.', 'Pass both, or use replacements for several pairs.');
+        }
+        const pairs = replacements ?? [{ findText: findText, replaceText: replaceText, matchCase }];
         try {
             const auth = await getClientFn(account);
             const docs = docsClient({ version: 'v1', auth });
             const res = await docs.documents.batchUpdate({
                 documentId,
                 requestBody: {
-                    requests: [{
-                            replaceAllText: {
-                                containsText: { text: findText, matchCase: matchCase ?? true },
-                                replaceText,
-                            },
-                        }],
+                    requests: pairs.map((p) => ({
+                        replaceAllText: {
+                            containsText: { text: p.findText, matchCase: p.matchCase ?? true },
+                            replaceText: p.replaceText,
+                        },
+                    })),
                 },
             });
-            const occurrences = res.data.replies?.[0]?.replaceAllText?.occurrencesChanged ?? 0;
+            const counts = (res.data.replies ?? []).map((r) => r?.replaceAllText?.occurrencesChanged ?? 0);
+            const warning = counts.every((c) => c === 0)
+                ? 'No occurrences were replaced; check spelling and matchCase.'
+                : undefined;
+            if (replacements) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({
+                                documentId: res.data.documentId,
+                                replacements: pairs.map((p, i) => ({ findText: p.findText, replaceText: p.replaceText, occurrencesReplaced: counts[i] })),
+                                ...(warning ? { warning } : {}),
+                            }, null, 2) }],
+                };
+            }
             return {
                 content: [{ type: 'text', text: JSON.stringify({
                             documentId: res.data.documentId,
-                            occurrencesReplaced: occurrences,
+                            occurrencesReplaced: counts[0],
+                            ...(warning ? { warning } : {}),
                         }, null, 2) }],
             };
         }

package/dist/tools/drive.js

@@ -13,11 +13,13 @@ import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
 import { pipeline } from 'node:stream/promises';
+import { Readable } from 'node:stream';
 import mime from 'mime-types';
 // drive_transfer's two-account form is the sanctioned schema exception and
 // stays REQUIRED: omission must fail at the schema, not as a runtime riddle.
 const MAX_FILE_SIZE = 2 * 1024 * 1024; // 2MB
 const FALLBACK_MAX_BYTES = 1024 * 1024 * 1024; // 1GB
+const MAX_UPLOAD_BASE64_BYTES = 10 * 1024 * 1024; // 10MB decoded
 const GOOGLE_WORKSPACE_TYPES = new Set([
     'application/vnd.google-apps.document',
     'application/vnd.google-apps.spreadsheet',
@@ -135,8 +137,10 @@ export function registerDriveTools(server, deps = {}) {
             driveId: z.string().optional().describe('Optional shared drive ID'),
             pageToken: z.string().min(1).optional()
                 .describe('Continuation token from a previous call\'s nextPageToken'),
+            orderBy: z.string().optional()
+                .describe('Sort key(s) for files.list, e.g. "modifiedTime desc" or "folder,name". Default: Drive\'s relevance ranking for the query, an arbitrary stable order otherwise.'),
         },
-    }, async ({ account, query, maxResults, driveId, pageToken }) => {
+    }, async ({ account, query, maxResults, driveId, pageToken, orderBy }) => {
         try {
             // normalizeDriveQuery trims to '' and Drive reads that as "everything", so
             // a blank query would list the whole drive as a "search" result.
@@ -160,6 +164,8 @@ export function registerDriveTools(server, deps = {}) {
             }
             if (pageToken)
                 params.pageToken = pageToken;
+            if (orderBy)
+                params.orderBy = orderBy;
             const res = await drive.files.list(params);
             const incomplete = res.data.incompleteSearch === true;
             return {
@@ -337,22 +343,55 @@ export function registerDriveTools(server, deps = {}) {
         }
     });
     // ─── Write / upload / download ─────────────────────────────────────────
-    registerHostFileTool('drive_upload', {
-        description: 'Upload a local file to Google Drive. Pass `convertTo` to import it as a native, editable Google Doc/Sheet/Slides/Drawing instead of storing the raw bytes.',
+    server.registerTool('drive_upload', {
+        description: 'Upload a file to Google Drive, from inline base64 content or (when this server exposes the host filesystem) a local path. Pass `convertTo` to import it as a native, editable Google Doc/Sheet/Slides/Drawing instead of storing the raw bytes.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            localPath: z.string().min(1).describe('Absolute path of the SOURCE file on disk to upload (on the machine running the server; this is not savePath)'),
             filename: z.string().describe('Name as it appears in Drive'),
-            mimeType: z.string().optional().describe('Source MIME type of the local file (inferred from extension if omitted). With `convertTo`, this is the format Drive imports from.'),
+            contentBase64: z.string().optional().describe(`Base64-encoded file content. Exactly one of contentBase64${localFiles ? ' or localPath' : ''} is required. Decoded size is capped at ${MAX_UPLOAD_BASE64_BYTES / (1024 * 1024)} MB.`),
+            ...(localFiles
+                ? {
+                    localPath: z.string().min(1).optional().describe('Absolute path of the SOURCE file on disk to upload (on the machine running the server; this is not savePath). Exactly one of contentBase64 or localPath is required.'),
+                }
+                : {}),
+            mimeType: z.string().optional().describe('Source MIME type of the content (inferred from filename if omitted). With `convertTo`, this is the format Drive imports from.'),
             convertTo: z.enum(CONVERT_TO_VALUES).optional().describe('Convert the upload into this native Google Workspace type on import: "document" | "spreadsheet" | "presentation" | "drawing" (full application/vnd.google-apps.* ids also accepted). E.g. upload .md/.html/.docx/.txt with convertTo=document to get a real Google Doc. Source must be an importable format. Omit to store the file as-is.'),
             parentFolderId: z.string().optional().describe('Parent folder ID, not parentId. Defaults to My Drive root'),
         },
-    }, async ({ account, localPath, filename, mimeType: mimeTypeArg, convertTo, parentFolderId }) => {
+    }, async (args) => {
+        const { account, filename, contentBase64, mimeType: mimeTypeArg, convertTo, parentFolderId } = args;
+        // Declared only when the context may read host files (see the shape).
+        const { localPath: localPathArg } = args;
+        if (localPathArg && !localFiles)
+            return hostFilesRefused(account, 'localPath');
+        const hasBase64 = contentBase64 !== undefined;
+        const hasLocalPath = !!localPathArg;
+        if (hasBase64 === hasLocalPath) {
+            return invalidParams(account, `Pass exactly one of contentBase64${localFiles ? ' or localPath' : ''}.`, localFiles
+                ? 'Use contentBase64 for inline content, or localPath for a file already on the machine running the server.'
+                : 'Pass contentBase64 with the file\'s base64-encoded content.');
+        }
         try {
+            let media;
+            if (hasBase64) {
+                const maxB64Length = Math.ceil(MAX_UPLOAD_BASE64_BYTES / 3) * 4 + 4;
+                if (contentBase64.length > maxB64Length) {
+                    return invalidParams(account, `Base64-encoded contentBase64 string length ${contentBase64.length} exceeds the ${maxB64Length} character limit (implies decoded size over ${MAX_UPLOAD_BASE64_BYTES} bytes).`, 'Upload a smaller file, or use localPath if this server exposes the host filesystem.');
+                }
+                const buf = Buffer.from(contentBase64, 'base64');
+                if (buf.length > MAX_UPLOAD_BASE64_BYTES) {
+                    return invalidParams(account, `Decoded contentBase64 is ${buf.length} bytes, over the ${MAX_UPLOAD_BASE64_BYTES} byte cap.`, 'Upload a smaller file, or use localPath if this server exposes the host filesystem.');
+                }
+                media = { mimeType: mimeTypeArg ?? (mime.lookup(filename) || 'application/octet-stream'), body: Readable.from(buf) };
+            }
+            else {
+                media = {
+                    mimeType: mimeTypeArg ?? (mime.lookup(localPathArg) || 'application/octet-stream'),
+                    body: await openLocalReadStream(localPathArg),
+                };
+            }
             const auth = await getClientFn(account);
             const drive = driveClient({ version: 'v3', auth });
-            const resolvedMime = mimeTypeArg ?? (mime.lookup(localPath) || 'application/octet-stream');
-            const fileStream = await openLocalReadStream(localPath);
             const res = await drive.files.create({
                 requestBody: {
                     name: filename,
@@ -360,10 +399,7 @@ export function registerDriveTools(server, deps = {}) {
                     // Setting a google-apps target type makes Drive convert the media on import.
                     ...(convertTo ? { mimeType: resolveConvertTarget(convertTo) } : {}),
                 },
-                media: {
-                    mimeType: resolvedMime,
-                    body: fileStream,
-                },
+                media,
                 fields: 'id,name,mimeType,webViewLink,size',
                 supportsAllDrives: true,
             });
@@ -676,6 +712,12 @@ export function registerDriveTools(server, deps = {}) {
             expirationTime: z.string().optional().describe('RFC 3339 timestamp when access expires. Only valid for role="reader" or "commenter".'),
         },
     }, async ({ account, fileId, type, role, emailAddress, domain, sendNotification, emailMessage, transferOwnership, expirationTime }) => {
+        if ((type === 'user' || type === 'group') && !emailAddress) {
+            return invalidParams(account, `type is "${type}" but emailAddress was not supplied.`, 'Pass emailAddress, the grantee to share with.');
+        }
+        if (type === 'domain' && !domain) {
+            return invalidParams(account, 'type is "domain" but domain was not supplied.', 'Pass domain, e.g. "example.com".');
+        }
         {
             // Outbound allowlist (off unless GOOGLE_OUTBOUND_ALLOWLIST is set): user/group
             // grantees must match, a domain share needs its exact "@domain" entry, "anyone" is refused while active.