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

package/README.md

@@ -4,7 +4,7 @@ The most complete **local Google Workspace MCP server**: Gmail, Drive, Calendar,
 
 [![npm](https://img.shields.io/npm/v/mcp-google-multi?label=npm&color=cb3837)](https://www.npmjs.com/package/mcp-google-multi)
 
-- 🧰 **Exhaustive** — 941 tools across 29 services, now including Google Analytics (GA4), + an escape hatch for anything else → [COVERAGE.md](./COVERAGE.md)
+- 🧰 **Exhaustive** — 942 tools across 29 services, now including Google Analytics (GA4), + an escape hatch for anything else → [COVERAGE.md](./COVERAGE.md)
 - 🔑 **Multi-account** — drive any number of Google accounts by alias, or fan one call out across all of them
 - 🔒 **Private by design** — your own OAuth app, tokens encrypted at rest (AES-256-GCM), writes deny-by-default, no telemetry, no metering — it talks only to Google
 - 🌐 **Local or remote** — runs locally over stdio, or self-hosted over HTTP with its own built-in OAuth 2.1 server (Claude Code's `/mcp` login and the claude.ai connector, zero custom UI). Pull-and-up Docker Compose with optional automatic HTTPS → [remote setup](./docs/http-setup.md)

package/dist/fs-atomic.js

@@ -10,6 +10,9 @@ const RENAME_RETRY_MS = 20;
 const LOCK_LEASE_MS = 60_000;
 // Breaking a lock takes microseconds, so an older breaker file was left by a crash.
 const BREAKER_STALE_MS = 2_000;
+// The no-hard-link fallback writes the lock in two syscalls (create, then the
+// pid); a reader can catch it empty in between. See docs/internals.md.
+const LOCK_WRITE_GRACE_MS = 2_000;
 const PROCESS_START_MS = performance.timeOrigin;
 const OWNER_NAME = /^(\d+)\.(\d+|host)\.(\d+)\.([0-9a-f]{8}|0)\.[0-9a-f]{12}\.owner$/;
 function startOf(pid) {
@@ -63,11 +66,19 @@ function sameFile(a, b) {
 function isEnoent(error) {
     return error.code === 'ENOENT';
 }
+function bindingRecord(id) {
+    return `${id.dev}:${id.ino}:${id.mtimeNs}`;
+}
+function matchesBinding(content, id) {
+    const m = /^(\d+):(\d+):(\d+)$/.exec(content);
+    return m !== null && BigInt(m[1]) === id.dev && BigInt(m[2]) === id.ino && BigInt(m[3]) === id.mtimeNs;
+}
 // Undefined when the lock changed hands while it was being read.
 function readHolder(lock) {
     const before = fs.lstatSync(lock, { bigint: true });
     const body = before.isFile() ? fs.readFileSync(lock, 'utf8') : '';
     let owner;
+    let ownerPending = false;
     if (before.isFile()) {
         const dir = path.dirname(lock);
         const prefix = `${path.basename(lock)}.`;
@@ -79,10 +90,12 @@ function readHolder(lock) {
                 continue;
             const ownerPath = path.join(dir, name);
             try {
-                if (sameFile(fs.lstatSync(ownerPath, { bigint: true }), before)) {
+                const ownerStat = fs.lstatSync(ownerPath, { bigint: true });
+                if (sameFile(ownerStat, before) || matchesBinding(fs.readFileSync(ownerPath, 'utf8'), before)) {
                     owner = { path: ownerPath, ns: m[2], start: m[3], boot: m[4] };
                     break;
                 }
+                ownerPending = true;
             }
             catch (error) {
                 if (!isEnoent(error))
@@ -93,7 +106,7 @@ function readHolder(lock) {
     const after = fs.lstatSync(lock, { bigint: true });
     if (!sameFile(before, after))
         return undefined;
-    return { body, ino: after.ino, dev: after.dev, mtimeNs: after.mtimeNs, mtimeMs: Number(after.mtimeNs) / 1e6, owner };
+    return { body, ino: after.ino, dev: after.dev, mtimeNs: after.mtimeNs, mtimeMs: Number(after.mtimeNs) / 1e6, owner, ownerPending };
 }
 // The owner file's random name tells two holders apart even when the second
 // lock reuses the first one's freed inode.
@@ -115,10 +128,21 @@ function probeDead(pid) {
         return false;
     }
 }
+// Symmetric: a clock step back must not make a write-in-progress lock look
+// permanently fresh (see docs/internals.md).
+function withinWriteGrace(now, mtimeMs) {
+    return Math.abs(now - mtimeMs) < LOCK_WRITE_GRACE_MS;
+}
 function holderDead(holder, now) {
+    if (holder.body === '' && withinWriteGrace(now, holder.mtimeMs))
+        return false;
     const pid = Number(holder.body);
     if (!(Number.isSafeInteger(pid) && pid > 0))
         return true;
+    // A same-pid owner file exists but is not yet bound (the fallback lock's two
+    // writes race a reader); give it the same grace as an empty lock.
+    if (!holder.owner && holder.ownerPending && withinWriteGrace(now, holder.mtimeMs))
+        return false;
     const leaseOver = now - holder.mtimeMs >= LOCK_LEASE_MS;
     const owner = holder.owner;
     // No owner file: an older writer, whose namespace is unknown.
@@ -196,6 +220,53 @@ function releaseBreaker(breaker, token) {
             throw error;
     }
 }
+// No hard links here (Android/Termux denies link() in private storage, some
+// filesystems lack it entirely): the lock is created directly with O_EXCL,
+// carrying the bare pid a linked owner file would carry, and the owner file
+// is bound to it by a recorded identity instead of a hard link. See docs/internals.md.
+function takeFallbackLock(lock, ownerFile) {
+    const fd = fs.openSync(lock, 'wx', 0o600);
+    let acquired;
+    try {
+        fs.writeSync(fd, String(process.pid));
+        const stat = fs.fstatSync(fd, { bigint: true });
+        acquired = { dev: stat.dev, ino: stat.ino, mtimeNs: stat.mtimeNs };
+    }
+    catch (error) {
+        // The lock is left empty; remove it only if it is still the one we just
+        // created, then rethrow so the caller never retries a write failure.
+        const stat = fs.fstatSync(fd, { bigint: true });
+        fs.closeSync(fd);
+        try {
+            if (sameFile(fs.lstatSync(lock, { bigint: true }), stat))
+                fs.rmSync(lock, { force: true });
+        }
+        catch (cleanupError) {
+            if (!isEnoent(cleanupError))
+                throw cleanupError;
+        }
+        throw error;
+    }
+    fs.closeSync(fd);
+    try {
+        fs.writeFileSync(ownerFile, bindingRecord(acquired));
+    }
+    catch (error) {
+        // The lock already exists holding our live pid; without this cleanup
+        // every other writer sees an ownerless holder and waits out the full lease.
+        try {
+            const current = fs.lstatSync(lock, { bigint: true });
+            if (sameFile(current, acquired) && current.mtimeNs === acquired.mtimeNs)
+                fs.rmSync(lock, { force: true });
+        }
+        catch (cleanupError) {
+            if (!isEnoent(cleanupError))
+                throw cleanupError;
+        }
+        throw error;
+    }
+    return acquired;
+}
 // Hardlink-based advisory lock; the lock body is the bare pid, as older
 // readers expect. See docs/internals.md.
 export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
@@ -206,17 +277,31 @@ export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
     fs.writeFileSync(ownerFile, String(process.pid), { mode: 0o600, flag: 'wx' });
     const deadline = Date.now() + LOCK_TIMEOUT_MS;
     let linked = false;
+    let acquired;
     try {
         while (true) {
             try {
                 fs.linkSync(ownerFile, lock);
                 linked = true;
+                acquired = fs.lstatSync(lock, { bigint: true });
                 break;
             }
             catch (error) {
                 const err = error;
-                if (err.code !== 'EEXIST')
+                if (err.code === 'EACCES' || err.code === 'EPERM') {
+                    try {
+                        acquired = takeFallbackLock(lock, ownerFile);
+                        linked = true;
+                        break;
+                    }
+                    catch (fbError) {
+                        if (fbError.code !== 'EEXIST')
+                            throw fbError;
+                    }
+                }
+                else if (err.code !== 'EEXIST') {
                     throw error;
+                }
                 try {
                     const holder = readHolder(lock);
                     if (holder && holderDead(holder, Date.now()) && breakLock(lock, holder))
@@ -238,23 +323,24 @@ export function withFileLock(absPath, fn, label = `lock: ${absPath}`) {
         if (!linked)
             fs.rmSync(ownerFile, { force: true });
     }
-    let bound = false;
     try {
-        // Some network and FUSE filesystems give each name of one file its own
-        // inode number; there the owner file cannot vouch for the lock.
-        bound = sameFile(fs.lstatSync(ownerFile, { bigint: true }), fs.lstatSync(lock, { bigint: true }));
         return fn();
     }
     finally {
-        releaseLock(lock, ownerFile, bound);
+        releaseLock(lock, ownerFile, acquired);
     }
 }
 // A holder whose lock was broken (its owner file removed with it) must not
-// remove its successor's lock.
-function releaseLock(lock, ownerFile, bound) {
+// remove its successor's lock: only drop the lock if it is still the exact
+// file this call created, and our own owner file is still there to vouch for it.
+function releaseLock(lock, ownerFile, acquired) {
     try {
-        if (!bound || sameFile(fs.lstatSync(ownerFile, { bigint: true }), fs.lstatSync(lock, { bigint: true })))
-            fs.rmSync(lock, { force: true });
+        if (acquired) {
+            const current = fs.lstatSync(lock, { bigint: true });
+            if (sameFile(current, acquired) && current.mtimeNs === acquired.mtimeNs && fs.existsSync(ownerFile)) {
+                fs.rmSync(lock, { force: true });
+            }
+        }
     }
     catch (error) {
         if (!isEnoent(error))

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.

package/dist/tools/sheets.d.ts

@@ -1,6 +1,15 @@
 import type { ToolRegistry } from '../registry.js';
 import { type CuratedToolDeps } from '../client.js';
 export declare function registerSheetsTools(server: ToolRegistry, deps?: CuratedToolDeps): void;
+interface GridRangeIndexes {
+    startRowIndex?: number;
+    endRowIndex?: number;
+    startColumnIndex?: number;
+    endColumnIndex?: number;
+}
+export declare function parseA1Range(a1: string): GridRangeIndexes & {
+    sheetName: string;
+};
 export declare function buildCellFormat(input: {
     backgroundColor?: {
         red?: number;
@@ -33,3 +42,4 @@ export declare function buildCellFormat(input: {
     format: any;
     fields: string;
 };
+export {};

package/dist/tools/sheets.js

@@ -369,6 +369,31 @@ export function registerSheetsTools(server, deps = {}) {
             return handleSheetsError(error, account);
         }
     });
+    server.registerTool('sheets_copy_sheet_to', {
+        description: 'Copy a tab into another spreadsheet (which may belong to a different account)',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias'),
+            spreadsheetId: z.string().min(1).describe('Source spreadsheet ID'),
+            sheetId: z.number().describe('Source sheet ID'),
+            destinationSpreadsheetId: z.string().min(1).describe('Destination spreadsheet ID'),
+        },
+    }, async ({ account, spreadsheetId, sheetId, destinationSpreadsheetId }) => {
+        try {
+            const auth = await getClientFn(account);
+            const sheets = sheetsClient({ version: 'v4', auth });
+            const res = await sheets.spreadsheets.sheets.copyTo({
+                spreadsheetId,
+                sheetId,
+                requestBody: { destinationSpreadsheetId },
+            });
+            return {
+                content: [{ type: 'text', text: JSON.stringify(res.data, null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleSheetsError(error, account);
+        }
+    });
     server.registerTool('sheets_update_sheet_properties', {
         description: 'Rename a tab, change tab color, freeze rows/columns, hide/show, or change grid dimensions',
         inputSchema: {
@@ -457,7 +482,8 @@ export function registerSheetsTools(server, deps = {}) {
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             spreadsheetId: z.string().min(1).describe('Spreadsheet ID'),
-            range: gridRangeSchema.describe('Target range (GridRange, half-open indexes)'),
+            range: z.union([gridRangeSchema, z.string().min(1)])
+                .describe('Target range: a GridRange object (half-open indexes), or an A1 string such as "Sheet1!A1:D10" (the sheet title is resolved to a sheetId with one extra call)'),
             backgroundColor: rgbColorSchema.optional().describe('Cell background (RGB 0..1)'),
             textFormat: z.object({
                 foregroundColor: rgbColorSchema.optional(),
@@ -484,12 +510,16 @@ export function registerSheetsTools(server, deps = {}) {
             if (built.fields.length === 0) {
                 return invalidParams(account, 'No formatting to apply: every optional format property was omitted.', 'Pass at least one of: backgroundColor, textFormat, horizontalAlignment, verticalAlignment, wrapStrategy, numberFormat.');
             }
+            const targetRange = typeof range === 'string' ? await resolveA1GridRange(sheets, spreadsheetId, range) : range;
+            if ('error' in targetRange) {
+                return invalidParams(account, targetRange.error, targetRange.hint);
+            }
             await sheets.spreadsheets.batchUpdate({
                 spreadsheetId,
                 requestBody: {
                     requests: [{
                             repeatCell: {
-                                range,
+                                range: targetRange,
                                 cell: { userEnteredFormat: built.format },
                                 fields: built.fields,
                             },
@@ -1118,6 +1148,83 @@ const gridRangeSchema = z.object({
     startColumnIndex: z.number().min(0).optional(),
     endColumnIndex: z.number().min(0).optional(),
 });
+function columnLettersToIndex(letters) {
+    let n = 0;
+    for (const ch of letters.toUpperCase())
+        n = n * 26 + (ch.charCodeAt(0) - 64);
+    return n - 1;
+}
+const A1_CELL_RE = /^([A-Za-z]+)?(\d+)?$/;
+// Either side of ':', and either half of a side, may be omitted: whole column, row or sheet.
+export function parseA1Range(a1) {
+    const bang = a1.lastIndexOf('!');
+    const sheetPart = bang === -1 ? a1 : a1.slice(0, bang);
+    const rangePart = bang === -1 ? '' : a1.slice(bang + 1);
+    const sheetName = sheetPart.startsWith("'") && sheetPart.endsWith("'")
+        ? sheetPart.slice(1, -1).replace(/''/g, "'")
+        : sheetPart;
+    if (rangePart === '')
+        return { sheetName };
+    const [startRaw, endRaw] = rangePart.split(':');
+    const m1 = startRaw.match(A1_CELL_RE);
+    if (!m1 || (!m1[1] && !m1[2]))
+        throw new Error(`invalid A1 range "${a1}"`);
+    const [, col1, row1] = m1;
+    const out = { sheetName };
+    if (endRaw === undefined) {
+        if (col1) {
+            const c = columnLettersToIndex(col1);
+            out.startColumnIndex = c;
+            out.endColumnIndex = c + 1;
+        }
+        if (row1) {
+            const r = Number(row1) - 1;
+            out.startRowIndex = r;
+            out.endRowIndex = r + 1;
+        }
+        return out;
+    }
+    const m2 = endRaw.match(A1_CELL_RE);
+    if (!m2 || (!m2[1] && !m2[2]))
+        throw new Error(`invalid A1 range "${a1}"`);
+    const [, col2, row2] = m2;
+    if (col1)
+        out.startColumnIndex = columnLettersToIndex(col1);
+    if (col2)
+        out.endColumnIndex = columnLettersToIndex(col2) + 1;
+    if (row1)
+        out.startRowIndex = Number(row1) - 1;
+    if (row2)
+        out.endRowIndex = Number(row2);
+    return out;
+}
+async function resolveA1GridRange(sheets, spreadsheetId, a1) {
+    let parsed;
+    try {
+        parsed = parseA1Range(a1);
+    }
+    catch {
+        return {
+            error: `Could not parse A1 range "${a1}".`,
+            hint: 'Use a form like "Sheet1!A1:D10", "Sheet1!A:D", or "Sheet1" for the whole sheet.',
+        };
+    }
+    const meta = await sheets.spreadsheets.get({ spreadsheetId, fields: 'sheets.properties(sheetId,title)' });
+    const match = meta.data.sheets?.find((s) => s.properties?.title === parsed.sheetName);
+    if (!match || match.properties?.sheetId == null) {
+        return {
+            error: `No sheet/tab named "${parsed.sheetName}" in this spreadsheet.`,
+            hint: 'Check the tab name, or use sheets_get to list sheet titles and IDs.',
+        };
+    }
+    return {
+        sheetId: match.properties.sheetId,
+        startRowIndex: parsed.startRowIndex,
+        endRowIndex: parsed.endRowIndex,
+        startColumnIndex: parsed.startColumnIndex,
+        endColumnIndex: parsed.endColumnIndex,
+    };
+}
 const borderSchema = z.object({
     style: z.enum(['DOTTED', 'DASHED', 'SOLID', 'SOLID_MEDIUM', 'SOLID_THICK', 'NONE', 'DOUBLE']),
     color: rgbColorSchema.optional(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.75",
+  "version": "6.0.0-alpha.77",
   "mcpName": "io.github.bakissation/mcp-google-multi",
   "description": "Local MCP server for Google Workspace (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console, +Forms/Chat/Admin) across multiple accounts — OAuth-only, encrypted token storage, deny-by-default writes.",
   "type": "module",