mcp-google-multi 4.3.0 → 4.5.0-alpha.1

package/README.md

@@ -2,6 +2,8 @@
 
 A local [MCP](https://modelcontextprotocol.io) server that gives Claude Code (and any MCP client) access to **Gmail**, **Google Drive**, **Google Calendar**, **Google Sheets**, **Google Docs**, **Google Contacts**, **Google Search Console**, **Google Tasks**, **Google Meet**, and optionally **Google Forms**, **Google Chat**, and **Google Workspace Admin** APIs across multiple Google accounts simultaneously.
 
+[![npm](https://img.shields.io/npm/v/mcp-google-multi?label=npm&color=cb3837)](https://www.npmjs.com/package/mcp-google-multi)
+
 ## Features
 
 - **Multi-account** — manage any number of Google accounts from a single server
@@ -20,9 +22,9 @@ A local [MCP](https://modelcontextprotocol.io) server that gives Claude Code (an
 | `gmail_search` | Search messages with Gmail query syntax |
 | `gmail_read` | Read a full message by ID |
 | `gmail_read_thread` | Read all messages in a thread |
-| `gmail_send` | Send an email |
+| `gmail_send` | Send an email (optional `htmlBody` for multipart/alternative) |
 | `gmail_download_attachment` | Download an email attachment to local disk |
-| `gmail_create_draft` | Create a draft |
+| `gmail_create_draft` | Create a draft (optional `htmlBody` for multipart/alternative) |
 | `gmail_modify_labels` | Add/remove labels on a message (star, archive, mark read, etc.) |
 | `gmail_trash` | Move a message to Trash (recoverable) |
 | `gmail_delete` | Permanently delete a message (irreversible) |
@@ -249,14 +251,25 @@ Enable with `GOOGLE_OPTIONAL_SCOPES=alertcenter` in `.env`.
 
 ### 2. Install & Configure
 
+**Option A — from npm (no clone):**
+
+```bash
+npm install -g mcp-google-multi    # installs the `mcp-google-multi` CLI
+# …or run on demand without installing: npx mcp-google-multi
+```
+
+Published with channel dist-tags — `@latest` (stable), `@dev` (alpha), `@staging` (beta); e.g. `npm i -g mcp-google-multi@dev` for the latest alpha.
+
+**Option B — from source:**
+
 ```bash
 git clone https://github.com/bakissation/mcp-google-multi.git
 cd mcp-google-multi
-npm install
+npm install && npm run build
 cp .env.example .env
 ```
 
-Edit `.env`:
+Create a `.env` (from source, `.env.example` is the template; from npm, make one in the directory you'll run the server from) with:
 
 ```env
 GOOGLE_CLIENT_ID=your_client_id_here
@@ -310,6 +323,24 @@ Or add it manually to your Claude Code MCP config:
 }
 ```
 
+If you installed from npm, point at the package instead and pass config via `env` (authenticate first with `mcp-google-multi auth --account <alias>`):
+
+```json
+{
+  "mcpServers": {
+    "google-multi": {
+      "command": "npx",
+      "args": ["-y", "mcp-google-multi"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "your_client_id_here",
+        "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
+        "GOOGLE_ACCOUNTS": "work:you@company.com,personal:you@gmail.com"
+      }
+    }
+  }
+}
+```
+
 ## Migrating from v3
 
 v4.0.0 grows the base OAuth scope set (Tasks and Meet are now included by default). Existing v3 tokens lack those scopes and the corresponding tools will 403.

package/dist/accounts.d.ts

@@ -1,6 +1,7 @@
 export interface AccountConfig {
     email: string;
     tokenPath: string;
+    encPath: string;
 }
 /** Tuple of account aliases (at least one) — usable with z.enum() */
 export declare const ACCOUNTS: [string, ...string[]];

package/dist/accounts.js

@@ -3,7 +3,9 @@ import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 dotenv.config({ path: path.resolve(__dirname, '..', '.env') });
-const tokenDir = path.resolve(__dirname, '..', 'tokens');
+const tokenDir = process.env.TOKEN_STORE_PATH
+    ? path.resolve(process.env.TOKEN_STORE_PATH)
+    : path.resolve(__dirname, '..', 'tokens');
 /**
  * Parse accounts from the GOOGLE_ACCOUNTS env var.
  * Format: "alias1:email1,alias2:email2,..."
@@ -39,6 +41,7 @@ function parseAccounts() {
         configs[alias] = {
             email,
             tokenPath: path.join(tokenDir, alias, 'token.json'),
+            encPath: path.join(tokenDir, `${alias}.enc`),
         };
     }
     if (aliases.length === 0) {

package/dist/auth.js

@@ -2,11 +2,10 @@ import { google } from 'googleapis';
 import http from 'node:http';
 import { URL } from 'node:url';
 import { randomBytes } from 'node:crypto';
-import fs from 'node:fs/promises';
-import path from 'node:path';
 import open from 'open';
 import destroyer from 'server-destroy';
 import { ACCOUNTS, ACCOUNT_CONFIG } from './accounts.js';
+import { writeToken } from './token-store.js';
 // ─── Scope tiers ────────────────────────────────────────────────────────
 //
 // BASE: always granted. Existing v3 surface + Tasks + Meet (added in v4.0.0).
@@ -98,6 +97,10 @@ export async function runAuthFlow(args) {
     }
     const config = ACCOUNT_CONFIG[alias];
     const scopes = resolveScopesForAccount(alias);
+    if (!process.env.MASTER_KEY) {
+        console.error('MASTER_KEY is not set. Generate one (openssl rand -base64 32) and add it to .env before authenticating.');
+        process.exit(1);
+    }
     const oauth2Client = new google.auth.OAuth2(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost:4242/oauth2callback');
     // CSRF protection for the OAuth callback (RFC 6749 §10.12).
     const expectedState = randomBytes(32).toString('hex');
@@ -145,13 +148,11 @@ export async function runAuthFlow(args) {
                         return;
                     }
                     const { tokens } = await oauth2Client.getToken(code);
-                    await fs.mkdir(path.dirname(config.tokenPath), { recursive: true });
-                    // 0o600: tokens grant full account access; keep them user-only.
-                    await fs.writeFile(config.tokenPath, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+                    writeToken(alias, tokens);
                     res.writeHead(200, { 'Content-Type': 'text/html' });
                     res.end('<h2>Authentication successful!</h2><p>You can close this tab.</p>');
                     server.destroy();
-                    console.log(`Token saved to ${config.tokenPath}`);
+                    console.log(`Token saved (encrypted) for ${alias}.`);
                     resolve();
                 }
             }

package/dist/client.js

@@ -1,6 +1,6 @@
 import { google } from 'googleapis';
-import fs from 'node:fs/promises';
 import { ACCOUNT_CONFIG } from './accounts.js';
+import { readToken, writeToken } from './token-store.js';
 export async function getClient(account) {
     const config = ACCOUNT_CONFIG[account];
     if (!process.env.GOOGLE_CLIENT_ID || !process.env.GOOGLE_CLIENT_SECRET) {
@@ -8,26 +8,15 @@ export async function getClient(account) {
             'Check that .env exists in the project root or pass them as env vars.');
     }
     const oauth2Client = new google.auth.OAuth2(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost:4242/oauth2callback');
-    let tokenData;
-    try {
-        const raw = await fs.readFile(config.tokenPath, 'utf-8');
-        tokenData = JSON.parse(raw);
-    }
-    catch {
-        throw new Error(`No token file found for account "${account}" at ${config.tokenPath}. ` +
-            `Run: node dist/index.js auth --account ${account}`);
+    const tokenData = readToken(account);
+    if (!tokenData) {
+        throw new Error(`No token found for account "${account}" (${config.email}). ` +
+            `Run: npx mcp-google-multi auth --account ${account}`);
     }
     oauth2Client.setCredentials(tokenData);
-    // 0o600: tokens grant full account access; keep them user-only.
-    oauth2Client.on('tokens', async (tokens) => {
-        try {
-            const existing = JSON.parse(await fs.readFile(config.tokenPath, 'utf-8'));
-            const merged = { ...existing, ...tokens };
-            await fs.writeFile(config.tokenPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
-        }
-        catch {
-            await fs.writeFile(config.tokenPath, JSON.stringify(tokens, null, 2), { mode: 0o600 });
-        }
+    oauth2Client.on('tokens', (tokens) => {
+        const existing = readToken(account) ?? {};
+        writeToken(account, { ...existing, ...tokens });
     });
     return oauth2Client;
 }

package/dist/index.js

@@ -26,6 +26,11 @@ async function main() {
         await runAuthFlow(process.argv);
         return;
     }
+    if (process.argv.includes('migrate-tokens')) {
+        const { runMigrateTokens } = await import('./migrate-tokens.js');
+        runMigrateTokens();
+        return;
+    }
     // MCP server mode — no console.log (stdio is the MCP channel)
     const server = new McpServer({
         name: 'mcp-google-multi',

package/dist/migrate-tokens.d.ts

@@ -0,0 +1 @@
+export declare function runMigrateTokens(): void;

package/dist/migrate-tokens.js

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+import { ACCOUNTS, ACCOUNT_CONFIG } from './accounts.js';
+import { writeToken, hasToken } from './token-store.js';
+export function runMigrateTokens() {
+    let migrated = 0;
+    let skipped = 0;
+    for (const alias of ACCOUNTS) {
+        const plain = ACCOUNT_CONFIG[alias].tokenPath;
+        if (!fs.existsSync(plain))
+            continue;
+        if (hasToken(alias)) {
+            console.log(`• ${alias}: encrypted token already exists, skipping`);
+            skipped++;
+            continue;
+        }
+        writeToken(alias, JSON.parse(fs.readFileSync(plain, 'utf8')));
+        console.log(`✓ ${alias}: migrated ${plain} → encrypted store`);
+        migrated++;
+    }
+    console.log(`Done. ${migrated} migrated, ${skipped} skipped. ` +
+        'Delete the plaintext tokens/<alias>/token.json once verified.');
+}

package/dist/token-store.d.ts

@@ -0,0 +1,7 @@
+import type { TokenData } from './types.js';
+export declare function deriveKey(masterKey: string): Buffer;
+export declare function encryptToken(data: object, masterKey: string): string;
+export declare function decryptToken(fileContents: string, masterKey: string): TokenData;
+export declare function readToken(alias: string): TokenData | null;
+export declare function writeToken(alias: string, data: object): void;
+export declare function hasToken(alias: string): boolean;

package/dist/token-store.js

@@ -0,0 +1,66 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ACCOUNT_CONFIG } from './accounts.js';
+const ENC_VERSION = 1;
+const ALGO = 'aes-256-gcm';
+export function deriveKey(masterKey) {
+    if (!masterKey) {
+        throw new Error('MASTER_KEY is required to encrypt/decrypt tokens. Generate one with: openssl rand -base64 32');
+    }
+    const raw = Buffer.from(masterKey, 'base64');
+    if (raw.length === 32)
+        return raw;
+    return createHash('sha256').update(masterKey, 'utf8').digest();
+}
+export function encryptToken(data, masterKey) {
+    const key = deriveKey(masterKey);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv(ALGO, key, iv);
+    const ciphertext = Buffer.concat([
+        cipher.update(Buffer.from(JSON.stringify(data), 'utf8')),
+        cipher.final(),
+    ]);
+    const file = {
+        v: ENC_VERSION,
+        iv: iv.toString('base64'),
+        tag: cipher.getAuthTag().toString('base64'),
+        data: ciphertext.toString('base64'),
+    };
+    return JSON.stringify(file);
+}
+export function decryptToken(fileContents, masterKey) {
+    const key = deriveKey(masterKey);
+    const file = JSON.parse(fileContents);
+    if (file.v !== ENC_VERSION) {
+        throw new Error(`Unsupported token file version: ${file.v}`);
+    }
+    const decipher = createDecipheriv(ALGO, key, Buffer.from(file.iv, 'base64'));
+    decipher.setAuthTag(Buffer.from(file.tag, 'base64'));
+    const plaintext = Buffer.concat([
+        decipher.update(Buffer.from(file.data, 'base64')),
+        decipher.final(),
+    ]);
+    return JSON.parse(plaintext.toString('utf8'));
+}
+function masterKey() {
+    return process.env.MASTER_KEY ?? '';
+}
+export function readToken(alias) {
+    let contents;
+    try {
+        contents = fs.readFileSync(ACCOUNT_CONFIG[alias].encPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    return decryptToken(contents, masterKey());
+}
+export function writeToken(alias, data) {
+    const p = ACCOUNT_CONFIG[alias].encPath;
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, encryptToken(data, masterKey()), { mode: 0o600 });
+}
+export function hasToken(alias) {
+    return fs.existsSync(ACCOUNT_CONFIG[alias].encPath);
+}

package/dist/tools/_coerce.d.ts

@@ -0,0 +1,4 @@
+import { z } from 'zod';
+export declare function coerceArray<T extends z.ZodTypeAny>(element: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodArray<T>>;
+export declare function coerceJson<T extends z.ZodTypeAny>(schema: T): z.ZodPipe<z.ZodTransform<unknown, unknown>, T>;
+export declare const coerceBoolean: z.ZodPipe<z.ZodTransform<unknown, unknown>, z.ZodBoolean>;

package/dist/tools/_coerce.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+function parseJsonLoose(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return s;
+    }
+}
+export function coerceArray(element) {
+    return z.preprocess((val) => {
+        if (typeof val !== 'string')
+            return val;
+        const t = val.trim();
+        if (t === '')
+            return [];
+        if (t.startsWith('['))
+            return parseJsonLoose(t);
+        return t.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+    }, z.array(element));
+}
+export function coerceJson(schema) {
+    return z.preprocess((val) => (typeof val === 'string' ? parseJsonLoose(val) : val), schema);
+}
+export const coerceBoolean = z.preprocess((val) => {
+    if (typeof val === 'boolean')
+        return val;
+    if (typeof val === 'string') {
+        const t = val.trim().toLowerCase();
+        if (['true', '1', 'yes', 'y'].includes(t))
+            return true;
+        if (['false', '0', 'no', 'n'].includes(t))
+            return false;
+    }
+    return val;
+}, z.boolean());

package/dist/tools/_errors.d.ts

@@ -1,5 +1,12 @@
 import type { Account } from '../accounts.js';
-/** Maps googleapis errors to MCP tool responses. 401 → re-auth instruction; 403 + hint → structured hint payload; 429 → retry-after; else → {error, code}. */
+export interface ErrorEnvelope {
+    error: string;
+    message: string;
+    hint?: string;
+    retriable: boolean;
+    account: string;
+}
+export declare function mapGoogleError(error: any, account: Account, forbiddenHint?: string): ErrorEnvelope;
 export declare function handleGoogleApiError(error: any, account: Account, forbiddenHint?: string): {
     content: {
         type: "text";

package/dist/tools/_errors.js

@@ -1,42 +1,69 @@
-/** Maps googleapis errors to MCP tool responses. 401 → re-auth instruction; 403 + hint → structured hint payload; 429 → retry-after; else → {error, code}. */
-export function handleGoogleApiError(error, account, forbiddenHint) {
-    if (error.code === 401) {
+function statusOf(error) {
+    const c = error?.code ?? error?.status ?? error?.response?.status;
+    const n = typeof c === 'string' ? Number(c) : c;
+    return Number.isFinite(n) ? n : undefined;
+}
+function reasonOf(error) {
+    return (error?.errors?.[0]?.reason ??
+        error?.response?.data?.error?.errors?.[0]?.reason ??
+        error?.response?.data?.error?.status);
+}
+function messageOf(error) {
+    return error?.response?.data?.error?.message ?? error?.message ?? String(error);
+}
+export function mapGoogleError(error, account, forbiddenHint) {
+    const status = statusOf(error);
+    const reason = reasonOf(error);
+    const message = messageOf(error);
+    if (status === 401) {
         return {
-            content: [{
-                    type: 'text',
-                    text: `Authentication error for account "${account}". Run: node dist/index.js auth --account ${account}`,
-                }],
-            isError: true,
+            error: 'auth_required',
+            message: `Authentication failed for account "${account}".`,
+            hint: `Run: npx mcp-google-multi auth --account ${account}`,
+            retriable: false,
+            account,
         };
     }
-    if (error.code === 403 && forbiddenHint) {
-        return {
-            content: [{
-                    type: 'text',
-                    text: JSON.stringify({
-                        error: 'forbidden',
-                        hint: forbiddenHint,
-                        original: error.message ?? String(error),
-                    }),
-                }],
-            isError: true,
-        };
+    if (status === 403) {
+        const scopeIssue = reason === 'insufficientPermissions' ||
+            reason === 'ACCESS_TOKEN_SCOPE_INSUFFICIENT' ||
+            /insufficient.*scope/i.test(message);
+        if (scopeIssue) {
+            return {
+                error: 'insufficient_scope',
+                message,
+                hint: forbiddenHint ?? `Re-auth "${account}" with the scope this operation needs.`,
+                retriable: false,
+                account,
+            };
+        }
+        return { error: 'forbidden', message, hint: forbiddenHint, retriable: false, account };
     }
-    if (error.code === 429) {
-        const retryAfter = error.response?.headers?.['retry-after'] ?? 'unknown';
+    if (status === 400 && /invalid[_ ]scope/i.test(message)) {
+        return { error: 'invalid_scope', message, retriable: false, account };
+    }
+    if (status === 404) {
+        return { error: 'not_found', message, retriable: false, account };
+    }
+    if (status === 429) {
+        const retryAfter = error?.response?.headers?.['retry-after'];
         return {
-            content: [{
-                    type: 'text',
-                    text: JSON.stringify({ error: 'rate_limited', retryAfter }),
-                }],
-            isError: true,
+            error: 'rate_limited',
+            message,
+            hint: retryAfter ? `Retry after ${retryAfter}s.` : 'Back off and retry.',
+            retriable: true,
+            account,
         };
     }
+    if (status !== undefined && status >= 500) {
+        return { error: 'upstream_error', message, retriable: true, account };
+    }
+    return { error: 'upstream_error', message, retriable: false, account };
+}
+export function handleGoogleApiError(error, account, forbiddenHint) {
+    const envelope = mapGoogleError(error, account, forbiddenHint);
     return {
-        content: [{
-                type: 'text',
-                text: JSON.stringify({ error: error.message ?? String(error), code: error.code }),
-            }],
+        content: [{ type: 'text', text: JSON.stringify(envelope) }],
         isError: true,
     };
 }

package/dist/tools/admin.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceBoolean } from './_coerce.js';
 import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
@@ -75,7 +76,7 @@ export function registerAdminTools(server) {
             maxResults: z.number().min(1).max(500).optional(),
             pageToken: z.string().optional(),
             orderBy: z.enum(['email', 'familyName', 'givenName']).optional(),
-            showDeleted: z.boolean().optional(),
+            showDeleted: coerceBoolean.optional(),
             projection: z.enum(['basic', 'custom', 'full']).optional(),
         },
     }, async ({ account, customer, domain, query, maxResults, pageToken, orderBy, showDeleted, projection }) => {
@@ -130,9 +131,9 @@ export function registerAdminTools(server) {
             userKey: z.string().describe('User email or ID'),
             givenName: z.string().optional(),
             familyName: z.string().optional(),
-            suspended: z.boolean().optional(),
+            suspended: coerceBoolean.optional(),
             password: z.string().optional(),
-            changePasswordAtNextLogin: z.boolean().optional(),
+            changePasswordAtNextLogin: coerceBoolean.optional(),
             orgUnitPath: z.string().optional(),
         },
     }, async ({ account, userKey, givenName, familyName, suspended, password, changePasswordAtNextLogin, orgUnitPath }) => {
@@ -217,7 +218,7 @@ export function registerAdminTools(server) {
             account: accountEnum.describe('Google account alias (must be a Workspace admin)'),
             groupKey: z.string().describe('Group email or ID'),
             roles: z.string().optional().describe('Comma-separated roles to include (OWNER, MANAGER, MEMBER)'),
-            includeDerivedMembership: z.boolean().optional(),
+            includeDerivedMembership: coerceBoolean.optional(),
             maxResults: z.number().min(1).max(200).optional(),
             pageToken: z.string().optional(),
         },

package/dist/tools/calendar.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceArray, coerceBoolean } from './_coerce.js';
 import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
@@ -111,7 +112,7 @@ export function registerCalendarTools(server) {
                 .describe('Comma-separated email addresses of attendees'),
             calendarId: z.string().default('primary').optional()
                 .describe('Calendar ID (default: primary)'),
-            allDay: z.boolean().default(false).optional()
+            allDay: coerceBoolean.default(false).optional()
                 .describe('If true, start/end are dates (YYYY-MM-DD) not datetimes'),
         },
     }, async ({ account, summary, start, end, description, location, attendees, calendarId, allDay }) => {
@@ -240,7 +241,7 @@ export function registerCalendarTools(server) {
             calendarId: z.string().default('primary').optional()
                 .describe('Calendar ID (default: primary)'),
             text: z.string().describe('Natural language event, e.g. "Lunch with Farouk Thursday 1pm at Le Boulanger"'),
-            sendNotifications: z.boolean().optional().describe('Send notifications to attendees (default: false)'),
+            sendNotifications: coerceBoolean.optional().describe('Send notifications to attendees (default: false)'),
         },
     }, async ({ account, calendarId, text, sendNotifications }) => {
         try {
@@ -266,7 +267,7 @@ export function registerCalendarTools(server) {
             calendarId: z.string().describe('Source calendar ID'),
             eventId: z.string().describe('Event ID to move'),
             destinationCalendarId: z.string().describe('Destination calendar ID'),
-            sendNotifications: z.boolean().optional().describe('Send notifications (default: false)'),
+            sendNotifications: coerceBoolean.optional().describe('Send notifications (default: false)'),
         },
     }, async ({ account, calendarId, eventId, destinationCalendarId, sendNotifications }) => {
         try {
@@ -322,7 +323,7 @@ export function registerCalendarTools(server) {
         description: 'Check free/busy times for one or more calendars within a time window. Returns only busy blocks, not event details.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            calendarIds: z.array(z.string()).describe('Calendar IDs to check, e.g. ["primary", "user@example.com"]'),
+            calendarIds: coerceArray(z.string()).describe('Calendar IDs to check, e.g. ["primary", "user@example.com"]'),
             timeMin: z.string().describe('ISO 8601 start of window'),
             timeMax: z.string().describe('ISO 8601 end of window'),
             timeZone: z.string().optional().describe('Timezone (default: UTC)'),

package/dist/tools/chat.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceJson } from './_coerce.js';
 import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
@@ -55,7 +56,7 @@ export function registerChatTools(server) {
             account: accountEnum.describe('Google account alias'),
             parent: z.string().describe('Space resource name, format: spaces/{space}'),
             text: z.string().optional().describe('Plain message text'),
-            cardsV2: z.array(z.record(z.string(), z.any())).optional().describe('Optional Card v2 payloads'),
+            cardsV2: coerceJson(z.array(z.record(z.string(), z.any()))).optional().describe('Optional Card v2 payloads'),
             threadKey: z.string().optional().describe('Thread key to group messages'),
             messageReplyOption: z.enum(['MESSAGE_REPLY_OPTION_UNSPECIFIED', 'REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD', 'REPLY_MESSAGE_OR_FAIL']).optional(),
         },

package/dist/tools/docs.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceBoolean, coerceJson } from './_coerce.js';
 import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
@@ -56,7 +57,7 @@ export function registerDocsTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             documentId: z.string().describe('Google Docs document ID'),
-            includeTabsContent: z.boolean().optional()
+            includeTabsContent: coerceBoolean.optional()
                 .describe('Include full content for every tab (default: false — first tab only)'),
             suggestionsViewMode: z.enum([
                 'DEFAULT_FOR_CURRENT_ACCESS',
@@ -154,7 +155,7 @@ export function registerDocsTools(server) {
             documentId: z.string().describe('Google Docs document ID'),
             findText: z.string().describe('Text to search for'),
             replaceText: z.string().describe('Replacement text'),
-            matchCase: z.boolean().default(true).optional()
+            matchCase: coerceBoolean.default(true).optional()
                 .describe('Case-sensitive match (default: true)'),
         },
     }, async ({ account, documentId, findText, replaceText, matchCase }) => {
@@ -224,9 +225,9 @@ export function registerDocsTools(server) {
             documentId: z.string().describe('Google Docs document ID'),
             startIndex: z.number().min(1).describe('Start index (inclusive, 1-based)'),
             endIndex: z.number().min(2).describe('End index (exclusive)'),
-            bold: z.boolean().optional().describe('Set bold'),
-            italic: z.boolean().optional().describe('Set italic'),
-            underline: z.boolean().optional().describe('Set underline'),
+            bold: coerceBoolean.optional().describe('Set bold'),
+            italic: coerceBoolean.optional().describe('Set italic'),
+            underline: coerceBoolean.optional().describe('Set underline'),
             fontSize: z.number().min(1).optional().describe('Font size in points'),
             fontFamily: z.string().optional().describe('Font family name (e.g. "Arial", "Times New Roman")'),
         },
@@ -443,9 +444,9 @@ export function registerDocsTools(server) {
             indentEnd: z.number().optional().describe('End indent in points'),
             indentFirstLine: z.number().optional().describe('First-line indent in points'),
             direction: z.enum(['LEFT_TO_RIGHT', 'RIGHT_TO_LEFT']).optional(),
-            keepLinesTogether: z.boolean().optional(),
-            keepWithNext: z.boolean().optional(),
-            avoidWidowAndOrphan: z.boolean().optional(),
+            keepLinesTogether: coerceBoolean.optional(),
+            keepWithNext: coerceBoolean.optional(),
+            avoidWidowAndOrphan: coerceBoolean.optional(),
         },
     }, async ({ account, documentId, startIndex, endIndex, ...style }) => {
         try {
@@ -489,9 +490,9 @@ export function registerDocsTools(server) {
             marginHeader: z.number().optional(),
             marginFooter: z.number().optional(),
             pageNumberStart: z.number().optional(),
-            useFirstPageHeaderFooter: z.boolean().optional(),
-            useEvenPageHeaderFooter: z.boolean().optional(),
-            useCustomHeaderFooterMargins: z.boolean().optional(),
+            useFirstPageHeaderFooter: coerceBoolean.optional(),
+            useEvenPageHeaderFooter: coerceBoolean.optional(),
+            useCustomHeaderFooterMargins: coerceBoolean.optional(),
         },
     }, async ({ account, documentId, ...style }) => {
         try {
@@ -807,8 +808,8 @@ export function registerDocsTools(server) {
             tableStartIndex: z.number().min(1).describe('Start index of the table in the document'),
             rowIndex: z.number().min(0).describe('Target row (0-based)'),
             columnIndex: z.number().min(0).describe('Target column (0-based)'),
-            insertBelow: z.boolean().optional().describe('insertRow only: insert below the target row (default: false)'),
-            insertRight: z.boolean().optional().describe('insertColumn only: insert right of the target column (default: false)'),
+            insertBelow: coerceBoolean.optional().describe('insertRow only: insert below the target row (default: false)'),
+            insertRight: coerceBoolean.optional().describe('insertColumn only: insert right of the target column (default: false)'),
             rowSpan: z.number().min(1).optional().describe('mergeCells only: how many rows the merged cell spans (default 1)'),
             columnSpan: z.number().min(1).optional().describe('mergeCells/unmergeCells: column span (default 1)'),
         },
@@ -981,7 +982,7 @@ export function registerDocsTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             documentId: z.string().describe('Google Docs document ID'),
-            requests: z.array(z.record(z.string(), z.any())).describe('Array of Request objects, each with one request-type key'),
+            requests: coerceJson(z.array(z.record(z.string(), z.any()))).describe('Array of Request objects, each with one request-type key'),
             writeControl: z.object({
                 requiredRevisionId: z.string().optional(),
                 targetRevisionId: z.string().optional(),

package/dist/tools/drive.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceArray, coerceBoolean } from './_coerce.js';
 import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
@@ -505,9 +506,9 @@ export function registerDriveTools(server) {
             role: z.enum(['reader', 'commenter', 'writer', 'fileOrganizer', 'organizer', 'owner']).describe('Permission role'),
             emailAddress: z.string().optional().describe('Required when type is "user" or "group"'),
             domain: z.string().optional().describe('Required when type is "domain"'),
-            sendNotification: z.boolean().optional().describe('Send notification email (default: true)'),
+            sendNotification: coerceBoolean.optional().describe('Send notification email (default: true)'),
             emailMessage: z.string().optional().describe('Custom message in notification email'),
-            transferOwnership: z.boolean().optional().describe('Transfer ownership to the recipient. Requires role="owner". Recipient must accept ownership.'),
+            transferOwnership: coerceBoolean.optional().describe('Transfer ownership to the recipient. Requires role="owner". Recipient must accept ownership.'),
             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 }) => {
@@ -567,9 +568,9 @@ export function registerDriveTools(server) {
                 .describe('New role'),
             expirationTime: z.string().optional()
                 .describe('New RFC 3339 expiration timestamp. Only valid for role "reader" or "commenter".'),
-            removeExpiration: z.boolean().optional()
+            removeExpiration: coerceBoolean.optional()
                 .describe('Clear the existing expirationTime'),
-            transferOwnership: z.boolean().optional()
+            transferOwnership: coerceBoolean.optional()
                 .describe('Promote to owner. Requires role="owner".'),
         },
     }, async ({ account, fileId, permissionId, role, expirationTime, removeExpiration, transferOwnership }) => {
@@ -658,7 +659,7 @@ export function registerDriveTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             fileId: z.string().describe('Google Drive file ID'),
-            includeDeleted: z.boolean().optional().describe('Include deleted comments (default: false)'),
+            includeDeleted: coerceBoolean.optional().describe('Include deleted comments (default: false)'),
             pageSize: z.number().min(1).max(100).optional().describe('Max comments per page (default: 20)'),
             pageToken: z.string().optional().describe('Token from a previous page'),
             startModifiedTime: z.string().optional().describe('Only return comments modified after this RFC 3339 timestamp'),
@@ -689,7 +690,7 @@ export function registerDriveTools(server) {
             account: accountEnum.describe('Google account alias'),
             fileId: z.string().describe('Google Drive file ID'),
             commentId: z.string().describe('Comment ID'),
-            includeDeleted: z.boolean().optional(),
+            includeDeleted: coerceBoolean.optional(),
         },
     }, async ({ account, fileId, commentId, includeDeleted }) => {
         try {
@@ -793,7 +794,7 @@ export function registerDriveTools(server) {
             account: accountEnum.describe('Google account alias'),
             fileId: z.string().describe('Google Drive file ID'),
             commentId: z.string().describe('Parent comment ID'),
-            includeDeleted: z.boolean().optional(),
+            includeDeleted: coerceBoolean.optional(),
             pageSize: z.number().min(1).max(100).optional(),
             pageToken: z.string().optional(),
         },
@@ -899,10 +900,10 @@ export function registerDriveTools(server) {
             account: accountEnum.describe('Google account alias'),
             fileId: z.string().describe('Google Drive file ID'),
             revisionId: z.string().describe('Revision ID'),
-            keepForever: z.boolean().optional().describe('Pin this revision indefinitely'),
-            published: z.boolean().optional().describe('Toggle published state (Docs only)'),
-            publishAuto: z.boolean().optional().describe('Auto-publish subsequent revisions'),
-            publishedOutsideDomain: z.boolean().optional().describe('Allow publish outside domain'),
+            keepForever: coerceBoolean.optional().describe('Pin this revision indefinitely'),
+            published: coerceBoolean.optional().describe('Toggle published state (Docs only)'),
+            publishAuto: coerceBoolean.optional().describe('Auto-publish subsequent revisions'),
+            publishedOutsideDomain: coerceBoolean.optional().describe('Allow publish outside domain'),
         },
     }, async ({ account, fileId, revisionId, keepForever, published, publishAuto, publishedOutsideDomain }) => {
         try {
@@ -984,10 +985,10 @@ export function registerDriveTools(server) {
             fileId: z.string().describe('Google Drive file ID'),
             proposalId: z.string().describe('Access proposal ID'),
             action: z.enum(['ACCEPT', 'DENY']).describe('Whether to accept or deny the proposal'),
-            role: z.array(z.enum(['reader', 'commenter', 'writer', 'fileOrganizer'])).optional()
+            role: coerceArray(z.enum(['reader', 'commenter', 'writer', 'fileOrganizer'])).optional()
                 .describe('Required when action is ACCEPT'),
             view: z.string().optional().describe('Optional view, e.g. "published"'),
-            sendNotification: z.boolean().optional()
+            sendNotification: coerceBoolean.optional()
                 .describe('Email the requester about the resolution'),
         },
     }, async ({ account, fileId, proposalId, action, role, view, sendNotification }) => {

package/dist/tools/gmail-mime.d.ts

@@ -14,3 +14,12 @@ export declare function encodeAddressHeader(value: string): string;
  * Normalize bare `\n` or `\r` to CRLF.
  */
 export declare function normalizeBodyLineEndings(body: string): string;
+/**
+ * Build a multipart/alternative body so HTML-capable clients render the rich
+ * version and plain clients fall back. Returns the header value AND the body.
+ * Caller composes the full message: headers (including this Content-Type) + CRLF + body.
+ */
+export declare function buildMultipartAlternative(plainBody: string, htmlBody: string): {
+    contentType: string;
+    body: string;
+};

package/dist/tools/gmail-mime.js

@@ -1,3 +1,4 @@
+import { randomBytes } from 'node:crypto';
 /**
  * RFC 2047 encoded-word (`=?utf-8?B?...?=`) for non-ASCII header text.
  * Long values are split into multiple <=75-char encoded-words separated
@@ -62,3 +63,37 @@ export function encodeAddressHeader(value) {
 export function normalizeBodyLineEndings(body) {
     return body.replace(/\r\n|\r|\n/g, '\r\n');
 }
+/**
+ * RFC 2046 §5.1.1 boundary token: 1-70 chars from a restricted set, no trailing space.
+ * randomBytes hex output is only [0-9a-f], all of which are bcharsnospace.
+ */
+function generateMimeBoundary() {
+    // 5-char prefix + 32 hex chars = 37 chars, well under the 70-char limit.
+    return `=_gm_${randomBytes(16).toString('hex')}`;
+}
+/**
+ * Build a multipart/alternative body so HTML-capable clients render the rich
+ * version and plain clients fall back. Returns the header value AND the body.
+ * Caller composes the full message: headers (including this Content-Type) + CRLF + body.
+ */
+export function buildMultipartAlternative(plainBody, htmlBody) {
+    const boundary = generateMimeBoundary();
+    const parts = [
+        `--${boundary}`,
+        'Content-Type: text/plain; charset="UTF-8"',
+        'Content-Transfer-Encoding: 8bit',
+        '',
+        normalizeBodyLineEndings(plainBody),
+        `--${boundary}`,
+        'Content-Type: text/html; charset="UTF-8"',
+        'Content-Transfer-Encoding: 8bit',
+        '',
+        normalizeBodyLineEndings(htmlBody),
+        `--${boundary}--`,
+        '',
+    ];
+    return {
+        contentType: `multipart/alternative; boundary="${boundary}"`,
+        body: parts.join('\r\n'),
+    };
+}

package/dist/tools/gmail.js

@@ -1,9 +1,10 @@
 import { z } from 'zod';
+import { coerceArray, coerceBoolean } from './_coerce.js';
 import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
-import { encodeAddressHeader, encodeHeaderValue, normalizeBodyLineEndings } from './gmail-mime.js';
+import { buildMultipartAlternative, encodeAddressHeader, encodeHeaderValue, normalizeBodyLineEndings } from './gmail-mime.js';
 import * as path from 'path';
 import * as fs from 'fs';
 const accountEnum = z.enum(ACCOUNTS);
@@ -163,14 +164,16 @@ export function registerGmailTools(server) {
             account: accountEnum.describe('Google account alias'),
             to: z.string().describe('Recipient(s), comma-separated'),
             subject: z.string().describe('Email subject'),
-            body: z.string().describe('Plain text body'),
+            body: z.string().describe('Plain text body (always required; also used as fallback when htmlBody is set)'),
+            htmlBody: z.string().optional()
+                .describe('Optional HTML body. When set, sends multipart/alternative so HTML-capable clients render the rich version. Use bare tags only: <p>, <a>, <br>, <strong>, <em>, <ul><li>.'),
             cc: z.string().optional().describe('CC recipients, comma-separated'),
             replyToMessageId: z.string().optional()
                 .describe('Message ID to reply to (sets In-Reply-To and References headers)'),
             replyToThreadId: z.string().optional()
                 .describe('Thread ID to send the message in'),
         },
-    }, async ({ account, to, subject, body, cc, replyToMessageId, replyToThreadId }) => {
+    }, async ({ account, to, subject, body, htmlBody, cc, replyToMessageId, replyToThreadId }) => {
         try {
             const auth = await getClient(account);
             const gmail = google.gmail({ version: 'v1', auth });
@@ -180,16 +183,25 @@ export function registerGmailTools(server) {
                 `To: ${encodeAddressHeader(to)}`,
                 `Subject: ${encodeHeaderValue(subject)}`,
                 'MIME-Version: 1.0',
-                'Content-Type: text/plain; charset="UTF-8"',
-                'Content-Transfer-Encoding: 8bit',
             ];
+            let bodyText;
+            if (htmlBody) {
+                const { contentType, body: mp } = buildMultipartAlternative(body, htmlBody);
+                headers.push(`Content-Type: ${contentType}`);
+                bodyText = mp;
+            }
+            else {
+                headers.push('Content-Type: text/plain; charset="UTF-8"');
+                headers.push('Content-Transfer-Encoding: 8bit');
+                bodyText = normalizeBodyLineEndings(body);
+            }
             if (cc)
                 headers.push(`Cc: ${encodeAddressHeader(cc)}`);
             if (replyToMessageId) {
                 headers.push(`In-Reply-To: ${replyToMessageId}`);
                 headers.push(`References: ${replyToMessageId}`);
             }
-            const rawMessage = [...headers, '', normalizeBodyLineEndings(body)].join('\r\n');
+            const rawMessage = [...headers, '', bodyText].join('\r\n');
             const encoded = Buffer.from(rawMessage, 'utf-8').toString('base64url');
             const sendParams = {
                 userId: 'me',
@@ -249,12 +261,14 @@ export function registerGmailTools(server) {
             account: accountEnum.describe('Google account alias'),
             to: z.string().describe('Recipient(s), comma-separated'),
             subject: z.string().describe('Email subject'),
-            body: z.string().describe('Plain text body'),
+            body: z.string().describe('Plain text body (always required; also used as fallback when htmlBody is set)'),
+            htmlBody: z.string().optional()
+                .describe('Optional HTML body. When set, drafts as multipart/alternative so HTML-capable clients render the rich version. Use bare tags only: <p>, <a>, <br>, <strong>, <em>, <ul><li>.'),
             cc: z.string().optional().describe('CC recipients, comma-separated'),
             replyToThreadId: z.string().optional()
                 .describe('Thread ID to associate the draft with'),
         },
-    }, async ({ account, to, subject, body, cc, replyToThreadId }) => {
+    }, async ({ account, to, subject, body, htmlBody, cc, replyToThreadId }) => {
         try {
             const auth = await getClient(account);
             const gmail = google.gmail({ version: 'v1', auth });
@@ -264,12 +278,21 @@ export function registerGmailTools(server) {
                 `To: ${encodeAddressHeader(to)}`,
                 `Subject: ${encodeHeaderValue(subject)}`,
                 'MIME-Version: 1.0',
-                'Content-Type: text/plain; charset="UTF-8"',
-                'Content-Transfer-Encoding: 8bit',
             ];
+            let bodyText;
+            if (htmlBody) {
+                const { contentType, body: mp } = buildMultipartAlternative(body, htmlBody);
+                headers.push(`Content-Type: ${contentType}`);
+                bodyText = mp;
+            }
+            else {
+                headers.push('Content-Type: text/plain; charset="UTF-8"');
+                headers.push('Content-Transfer-Encoding: 8bit');
+                bodyText = normalizeBodyLineEndings(body);
+            }
             if (cc)
                 headers.push(`Cc: ${encodeAddressHeader(cc)}`);
-            const rawMessage = [...headers, '', normalizeBodyLineEndings(body)].join('\r\n');
+            const rawMessage = [...headers, '', bodyText].join('\r\n');
             const encoded = Buffer.from(rawMessage, 'utf-8').toString('base64url');
             const draftParams = {
                 userId: 'me',
@@ -297,8 +320,8 @@ export function registerGmailTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             messageId: z.string().describe('Gmail message ID'),
-            addLabelIds: z.array(z.string()).optional().describe('Label IDs to add'),
-            removeLabelIds: z.array(z.string()).optional().describe('Label IDs to remove'),
+            addLabelIds: coerceArray(z.string()).optional().describe('Label IDs to add'),
+            removeLabelIds: coerceArray(z.string()).optional().describe('Label IDs to remove'),
         },
     }, async ({ account, messageId, addLabelIds, removeLabelIds }) => {
         try {
@@ -362,9 +385,9 @@ export function registerGmailTools(server) {
         description: 'Add/remove labels across up to 1000 Gmail messages at once. Useful for bulk archiving, marking as read, etc.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            messageIds: z.array(z.string()).describe('Message IDs (up to 1000)'),
-            addLabelIds: z.array(z.string()).optional().describe('Label IDs to add'),
-            removeLabelIds: z.array(z.string()).optional().describe('Label IDs to remove'),
+            messageIds: coerceArray(z.string()).describe('Message IDs (up to 1000)'),
+            addLabelIds: coerceArray(z.string()).optional().describe('Label IDs to add'),
+            removeLabelIds: coerceArray(z.string()).optional().describe('Label IDs to remove'),
         },
     }, async ({ account, messageIds, addLabelIds, removeLabelIds }) => {
         try {
@@ -390,7 +413,7 @@ export function registerGmailTools(server) {
         description: 'Permanently delete multiple Gmail messages. Irreversible.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            messageIds: z.array(z.string()).describe('Message IDs (up to 1000)'),
+            messageIds: coerceArray(z.string()).describe('Message IDs (up to 1000)'),
         },
     }, async ({ account, messageIds }) => {
         try {
@@ -570,7 +593,7 @@ export function registerGmailTools(server) {
             startHistoryId: z.string().describe('History ID from a previous gmail_get_profile or gmail_read response'),
             maxResults: z.number().min(1).max(500).default(100).optional()
                 .describe('Max results to return (default: 100)'),
-            historyTypes: z.array(z.enum(['messageAdded', 'messageDeleted', 'labelAdded', 'labelRemoved'])).optional()
+            historyTypes: coerceArray(z.enum(['messageAdded', 'messageDeleted', 'labelAdded', 'labelRemoved'])).optional()
                 .describe('Filter by history event types'),
         },
     }, async ({ account, startHistoryId, maxResults, historyTypes }) => {
@@ -613,13 +636,13 @@ export function registerGmailTools(server) {
         description: 'Enable or disable Gmail vacation responder with a custom message',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
-            enableAutoReply: z.boolean().describe('Whether to enable the vacation responder'),
+            enableAutoReply: coerceBoolean.describe('Whether to enable the vacation responder'),
             responseSubject: z.string().optional().describe('Subject line for auto-reply'),
             responseBodyPlainText: z.string().optional().describe('Plain text body for auto-reply'),
             startTime: z.string().optional().describe('Start time as Unix timestamp in ms'),
             endTime: z.string().optional().describe('End time as Unix timestamp in ms'),
-            restrictToContacts: z.boolean().optional().describe('Only reply to contacts (default: false)'),
-            restrictToDomain: z.boolean().optional().describe('Only reply to same domain (default: false)'),
+            restrictToContacts: coerceBoolean.optional().describe('Only reply to contacts (default: false)'),
+            restrictToDomain: coerceBoolean.optional().describe('Only reply to same domain (default: false)'),
         },
     }, async ({ account, enableAutoReply, responseSubject, responseBodyPlainText, startTime, endTime, restrictToContacts, restrictToDomain }) => {
         try {

package/dist/tools/searchconsole.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceArray, coerceJson } from './_coerce.js';
 import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
@@ -169,18 +170,18 @@ export function registerSearchConsoleTools(server) {
             siteUrl: z.string().describe('Site URL (e.g. "https://example.com/" or "sc-domain:example.com")'),
             startDate: z.string().describe('Start date (YYYY-MM-DD). Data is available starting ~3 days ago.'),
             endDate: z.string().describe('End date (YYYY-MM-DD)'),
-            dimensions: z.array(z.enum(['query', 'page', 'country', 'device', 'searchAppearance', 'date'])).optional()
+            dimensions: coerceArray(z.enum(['query', 'page', 'country', 'device', 'searchAppearance', 'date'])).optional()
                 .describe('Dimensions to group by. Common: ["query", "page"], ["date"], ["query", "date"]'),
             type: z.enum(['web', 'image', 'video', 'news', 'discover', 'googleNews']).optional()
                 .describe('Search type filter (default: web)'),
-            dimensionFilterGroups: z.array(z.object({
+            dimensionFilterGroups: coerceJson(z.array(z.object({
                 groupType: z.enum(['and']).optional(),
                 filters: z.array(z.object({
                     dimension: z.enum(['query', 'page', 'country', 'device', 'searchAppearance']),
                     operator: z.enum(['contains', 'equals', 'notContains', 'notEquals', 'includingRegex', 'excludingRegex']),
                     expression: z.string(),
                 })),
-            })).optional()
+            }))).optional()
                 .describe('Filters to narrow results. Example: filter by page containing "/blog/" or query containing "keyword"'),
             rowLimit: z.number().min(1).max(25000).optional()
                 .describe('Max rows to return (default: 1000, max: 25000)'),

package/dist/tools/sheets.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceArray, coerceBoolean, coerceJson } from './_coerce.js';
 import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
@@ -10,7 +11,7 @@ export function registerSheetsTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             title: z.string().describe('Spreadsheet title'),
-            sheetTitles: z.array(z.string()).optional()
+            sheetTitles: coerceArray(z.string()).optional()
                 .describe('Optional tab/sheet names (default: one sheet named "Sheet1")'),
         },
     }, async ({ account, title, sheetTitles }) => {
@@ -108,7 +109,7 @@ export function registerSheetsTools(server) {
             account: accountEnum.describe('Google account alias'),
             spreadsheetId: z.string().describe('Spreadsheet ID'),
             range: z.string().describe('A1 notation target range, e.g. "Sheet1!A1:C3"'),
-            values: z.array(z.array(z.any())).describe('2D array of values (rows x columns)'),
+            values: coerceJson(z.array(z.array(z.any()))).describe('2D array of values (rows x columns)'),
             valueInputOption: z.enum(['RAW', 'USER_ENTERED']).default('USER_ENTERED').optional()
                 .describe('How to interpret values: RAW (literal) or USER_ENTERED (formulas/dates parsed). Default: USER_ENTERED'),
         },
@@ -141,7 +142,7 @@ export function registerSheetsTools(server) {
             account: accountEnum.describe('Google account alias'),
             spreadsheetId: z.string().describe('Spreadsheet ID'),
             range: z.string().describe('A1 notation range to search for the table (e.g. "Sheet1")'),
-            values: z.array(z.array(z.any())).describe('2D array of rows to append'),
+            values: coerceJson(z.array(z.array(z.any()))).describe('2D array of rows to append'),
             valueInputOption: z.enum(['RAW', 'USER_ENTERED']).default('USER_ENTERED').optional()
                 .describe('How to interpret values. Default: USER_ENTERED'),
         },
@@ -200,7 +201,7 @@ export function registerSheetsTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             spreadsheetId: z.string().describe('Spreadsheet ID'),
-            ranges: z.array(z.string()).describe('Array of A1 notation ranges'),
+            ranges: coerceArray(z.string()).describe('Array of A1 notation ranges'),
             valueRenderOption: z.enum(['FORMATTED_VALUE', 'UNFORMATTED_VALUE', 'FORMULA'])
                 .default('FORMATTED_VALUE').optional()
                 .describe('How to render values. Default: FORMATTED_VALUE'),
@@ -231,10 +232,10 @@ export function registerSheetsTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             spreadsheetId: z.string().describe('Spreadsheet ID'),
-            data: z.array(z.object({
+            data: coerceJson(z.array(z.object({
                 range: z.string().describe('A1 notation range'),
-                values: z.array(z.array(z.any())).describe('2D array of values'),
-            })).describe('Array of { range, values } objects to write'),
+                values: coerceJson(z.array(z.array(z.any()))).describe('2D array of values'),
+            }))).describe('Array of { range, values } objects to write'),
             valueInputOption: z.enum(['RAW', 'USER_ENTERED']).default('USER_ENTERED').optional()
                 .describe('How to interpret values. Default: USER_ENTERED'),
         },
@@ -373,7 +374,7 @@ export function registerSheetsTools(server) {
             sheetId: z.number().describe('Sheet ID'),
             title: z.string().optional().describe('New tab title'),
             index: z.number().optional().describe('New position among tabs'),
-            hidden: z.boolean().optional().describe('Hide the tab from the UI'),
+            hidden: coerceBoolean.optional().describe('Hide the tab from the UI'),
             tabColor: rgbColorSchema.optional().describe('Tab color (RGB 0..1)'),
             frozenRowCount: z.number().min(0).optional().describe('Number of frozen header rows'),
             frozenColumnCount: z.number().min(0).optional().describe('Number of frozen header columns'),
@@ -460,10 +461,10 @@ export function registerSheetsTools(server) {
             backgroundColor: rgbColorSchema.optional().describe('Cell background (RGB 0..1)'),
             textFormat: z.object({
                 foregroundColor: rgbColorSchema.optional(),
-                bold: z.boolean().optional(),
-                italic: z.boolean().optional(),
-                underline: z.boolean().optional(),
-                strikethrough: z.boolean().optional(),
+                bold: coerceBoolean.optional(),
+                italic: coerceBoolean.optional(),
+                underline: coerceBoolean.optional(),
+                strikethrough: coerceBoolean.optional(),
                 fontFamily: z.string().optional(),
                 fontSize: z.number().min(1).optional(),
             }).optional(),
@@ -609,19 +610,19 @@ export function registerSheetsTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             spreadsheetId: z.string().describe('Spreadsheet ID'),
-            ranges: z.array(gridRangeSchema).describe('Ranges the rule applies to'),
+            ranges: coerceJson(z.array(gridRangeSchema)).describe('Ranges the rule applies to'),
             index: z.number().min(0).optional().describe('Where in the rule order to insert (0 = highest priority)'),
             booleanRule: z.object({
                 conditionType: z.string().describe(BOOLEAN_CONDITION_TYPE_DESC),
-                conditionValues: z.array(z.string()).optional().describe('Values for the condition (e.g. ["100"] for NUMBER_GREATER, or ["=A1>10"] for CUSTOM_FORMULA)'),
+                conditionValues: coerceArray(z.string()).optional().describe('Values for the condition (e.g. ["100"] for NUMBER_GREATER, or ["=A1>10"] for CUSTOM_FORMULA)'),
                 format: z.object({
                     backgroundColor: rgbColorSchema.optional(),
                     textFormat: z.object({
                         foregroundColor: rgbColorSchema.optional(),
-                        bold: z.boolean().optional(),
-                        italic: z.boolean().optional(),
-                        strikethrough: z.boolean().optional(),
-                        underline: z.boolean().optional(),
+                        bold: coerceBoolean.optional(),
+                        italic: coerceBoolean.optional(),
+                        strikethrough: coerceBoolean.optional(),
+                        underline: coerceBoolean.optional(),
                     }).optional(),
                 }).describe('Format to apply when condition is true. Conditional formatting only supports bold/italic/strikethrough/underline/foregroundColor/backgroundColor.'),
             }).optional(),
@@ -699,7 +700,7 @@ export function registerSheetsTools(server) {
             account: accountEnum.describe('Google account alias'),
             spreadsheetId: z.string().describe('Spreadsheet ID'),
             range: gridRangeSchema,
-            sortSpecs: z.array(sortSpecSchema).describe('One spec per sort column (in priority order)'),
+            sortSpecs: coerceJson(z.array(sortSpecSchema)).describe('One spec per sort column (in priority order)'),
         },
     }, async ({ account, spreadsheetId, range, sortSpecs }) => {
         try {
@@ -725,13 +726,13 @@ export function registerSheetsTools(server) {
             account: accountEnum.describe('Google account alias'),
             spreadsheetId: z.string().describe('Spreadsheet ID'),
             range: gridRangeSchema,
-            sortSpecs: z.array(sortSpecSchema).optional(),
-            filterSpecs: z.array(z.object({
+            sortSpecs: coerceJson(z.array(sortSpecSchema)).optional(),
+            filterSpecs: coerceJson(z.array(z.object({
                 columnIndex: z.number().min(0),
-                hiddenValues: z.array(z.string()).optional().describe('Values to hide in this column'),
+                hiddenValues: coerceArray(z.string()).optional().describe('Values to hide in this column'),
                 conditionType: z.string().optional().describe(BOOLEAN_CONDITION_TYPE_DESC),
-                conditionValues: z.array(z.string()).optional(),
-            })).optional(),
+                conditionValues: coerceArray(z.string()).optional(),
+            }))).optional(),
         },
     }, async ({ account, spreadsheetId, range, sortSpecs, filterSpecs }) => {
         try {
@@ -801,10 +802,10 @@ export function registerSheetsTools(server) {
             scope: z.enum(['allSheets', 'sheet', 'range']).describe('Search scope'),
             sheetId: z.number().optional().describe('Required when scope=sheet'),
             range: gridRangeSchema.optional().describe('Required when scope=range'),
-            matchCase: z.boolean().optional(),
-            matchEntireCell: z.boolean().optional(),
-            searchByRegex: z.boolean().optional(),
-            includeFormulas: z.boolean().optional(),
+            matchCase: coerceBoolean.optional(),
+            matchEntireCell: coerceBoolean.optional(),
+            searchByRegex: coerceBoolean.optional(),
+            includeFormulas: coerceBoolean.optional(),
         },
     }, async ({ account, spreadsheetId, find, replacement, scope, sheetId, range, matchCase, matchEntireCell, searchByRegex, includeFormulas }) => {
         try {
@@ -892,7 +893,7 @@ export function registerSheetsTools(server) {
             dimension: z.enum(['ROWS', 'COLUMNS']),
             startIndex: z.number().min(0).describe('0-based, inclusive'),
             endIndex: z.number().min(1).describe('0-based, exclusive'),
-            inheritFromBefore: z.boolean().optional(),
+            inheritFromBefore: coerceBoolean.optional(),
         },
     }, async ({ account, spreadsheetId, sheetId, dimension, startIndex, endIndex, inheritFromBefore }) => {
         try {
@@ -957,10 +958,10 @@ export function registerSheetsTools(server) {
             spreadsheetId: z.string().describe('Spreadsheet ID'),
             range: gridRangeSchema,
             conditionType: z.string().describe(BOOLEAN_CONDITION_TYPE_DESC),
-            conditionValues: z.array(z.string()).optional().describe('Values per condition type (list items for ONE_OF_LIST, range A1 for ONE_OF_RANGE, etc.)'),
+            conditionValues: coerceArray(z.string()).optional().describe('Values per condition type (list items for ONE_OF_LIST, range A1 for ONE_OF_RANGE, etc.)'),
             inputMessage: z.string().optional().describe('Tooltip shown when cell is selected'),
-            strict: z.boolean().optional().describe('Reject invalid input (default: false = warning only)'),
-            showCustomUi: z.boolean().optional().describe('Show dropdown UI for list-type validations'),
+            strict: coerceBoolean.optional().describe('Reject invalid input (default: false = warning only)'),
+            showCustomUi: coerceBoolean.optional().describe('Show dropdown UI for list-type validations'),
         },
     }, async ({ account, spreadsheetId, range, conditionType, conditionValues, inputMessage, strict, showCustomUi }) => {
         try {
@@ -1048,7 +1049,7 @@ export function registerSheetsTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             spreadsheetId: z.string().describe('Spreadsheet ID'),
-            ranges: z.array(z.string()).describe('Array of A1 notation ranges'),
+            ranges: coerceArray(z.string()).describe('Array of A1 notation ranges'),
         },
     }, async ({ account, spreadsheetId, ranges }) => {
         try {
@@ -1073,10 +1074,10 @@ export function registerSheetsTools(server) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             spreadsheetId: z.string().describe('Spreadsheet ID'),
-            requests: z.array(z.record(z.string(), z.any())).describe('Array of Request objects. Each object has exactly one key (the request type) like {repeatCell: {...}}, {addChart: {...}}, {updateBanding: {...}}, etc.'),
-            includeSpreadsheetInResponse: z.boolean().optional(),
-            responseRanges: z.array(z.string()).optional(),
-            responseIncludeGridData: z.boolean().optional(),
+            requests: coerceJson(z.array(z.record(z.string(), z.any()))).describe('Array of Request objects. Each object has exactly one key (the request type) like {repeatCell: {...}}, {addChart: {...}}, {updateBanding: {...}}, etc.'),
+            includeSpreadsheetInResponse: coerceBoolean.optional(),
+            responseRanges: coerceArray(z.string()).optional(),
+            responseIncludeGridData: coerceBoolean.optional(),
         },
     }, async ({ account, spreadsheetId, requests, includeSpreadsheetInResponse, responseRanges, responseIncludeGridData }) => {
         try {

package/dist/tools/tasks.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { coerceBoolean } from './_coerce.js';
 import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
@@ -119,10 +120,10 @@ export function registerTasksTools(server) {
             tasklistId: z.string().describe('Tasklist ID'),
             maxResults: z.number().min(1).max(100).optional(),
             pageToken: z.string().optional(),
-            showCompleted: z.boolean().optional().describe('Include completed tasks (default: true)'),
-            showDeleted: z.boolean().optional(),
-            showHidden: z.boolean().optional(),
-            showAssigned: z.boolean().optional(),
+            showCompleted: coerceBoolean.optional().describe('Include completed tasks (default: true)'),
+            showDeleted: coerceBoolean.optional(),
+            showHidden: coerceBoolean.optional(),
+            showAssigned: coerceBoolean.optional(),
             completedMax: z.string().optional().describe('RFC 3339 upper bound on completion date'),
             completedMin: z.string().optional(),
             dueMax: z.string().optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "4.3.0",
+  "version": "4.5.0-alpha.1",
   "description": "MCP server for Gmail, Google Drive, Calendar, Sheets, Docs, and Contacts with multi-account support",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,7 @@
     "prepublishOnly": "npm run build",
     "watch": "tsc --watch",
     "auth": "node dist/index.js auth --account",
+    "migrate-tokens": "node dist/index.js migrate-tokens",
     "lint": "eslint .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
@@ -67,6 +68,6 @@
     "semantic-release": "^25.0.3",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.1",
-    "vitest": "^4.1.5"
+    "vitest": "^3.2.4"
   }
 }