mcp-google-multi 6.0.0-alpha.3 → 6.0.0-alpha.5

package/dist/scope-catalog.d.ts

@@ -17,3 +17,4 @@ export declare const BUNDLE_ALIASES: Record<string, string>;
 export declare function resolveBundleAliases(bundles: string[]): string[];
 /** Closest catalog key for E_UNKNOWN_BUNDLE remediation (edit distance <= 2). */
 export declare function closestBundle(name: string): string | undefined;
+export declare function editDistance(a: string, b: string): number;

package/dist/scope-catalog.js

@@ -169,7 +169,7 @@ export function closestBundle(name) {
     }
     return best;
 }
-function editDistance(a, b) {
+export function editDistance(a, b) {
     const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
     for (let j = 1; j <= b.length; j++)
         dp[0][j] = j;

package/dist/tools/_errors.js

@@ -20,6 +20,10 @@ const RETRIABLE_NET_CODES = new Set([
     'EHOSTUNREACH', 'EPIPE', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET',
 ]);
 const NET_CODES = new Set([...RETRIABLE_NET_CODES, 'ENOTFOUND']);
+// Local-filesystem syscall codes from caller-supplied paths (localPath/savePath).
+// String codes, so they never collide with Google's numeric statuses; the
+// network codes above are deliberately excluded.
+const LOCAL_FS_CODES = new Set(['ENOENT', 'EACCES', 'EISDIR', 'ENOTDIR', 'EPERM', 'ELOOP', 'ENAMETOOLONG', 'ENOSPC']);
 /** First known network code on the error or its cause chain (GaxiosError.cause
  * -> FetchError; undici TypeError.cause -> AggregateError.errors). */
 function netCodeOf(error) {
@@ -137,6 +141,18 @@ export function mapGoogleError(error, account, forbiddenHint, scopeContext) {
         return { error: 'upstream_error', message, retriable: true, account };
     }
     if (status === undefined) {
+        const fsCode = typeof error?.code === 'string' && LOCAL_FS_CODES.has(error.code) ? error.code : undefined;
+        if (fsCode) {
+            const p = typeof error?.path === 'string' ? ` "${error.path}"` : '';
+            return {
+                error: 'invalid_params',
+                message: `Cannot access local path${p}: ${fsCode}`,
+                hint: 'The path must exist on the machine running this server and be accessible to it. ' +
+                    'When the server runs remotely (HTTP transport), paths on your own machine are not visible to it.',
+                retriable: false,
+                account,
+            };
+        }
         const netCode = netCodeOf(error);
         if (netCode) {
             return {

package/dist/tools/_local-files.d.ts

@@ -0,0 +1,3 @@
+import * as fs from 'fs';
+export declare function prepareLocalDest(savePath: string, filename: string): string;
+export declare function openLocalReadStream(localPath: string): Promise<fs.ReadStream>;

package/dist/tools/_local-files.js

@@ -0,0 +1,29 @@
+import * as fs from 'fs';
+import * as path from 'path';
+// path.basename() is a traversal guard — a caller-supplied filename must never escape savePath.
+export function prepareLocalDest(savePath, filename) {
+    const dest = path.join(savePath, path.basename(filename));
+    fs.mkdirSync(savePath, { recursive: true });
+    return dest;
+}
+// fs.createReadStream() reports an unopenable path as an async 'error' EVENT;
+// with no listener attached, that single event kills the whole process — fatal
+// for the shared HTTP transport. Opening the fd first turns the open-failure
+// class (ENOENT/EACCES/...) into a normal rejection the caller's try/catch can
+// map to an error envelope.
+export async function openLocalReadStream(localPath) {
+    const handle = await fs.promises.open(localPath, 'r');
+    // open() succeeds on a directory; fail it here rather than as an async read error.
+    if ((await handle.stat()).isDirectory()) {
+        await handle.close();
+        throw Object.assign(new Error(`EISDIR: illegal operation on a directory, read '${localPath}'`), {
+            code: 'EISDIR',
+            path: localPath,
+        });
+    }
+    const stream = handle.createReadStream();
+    // Mid-read errors still reach the consumer through its own listeners; this
+    // one only closes the unhandled-'error' crash path.
+    stream.on('error', () => { });
+    return stream;
+}

package/dist/tools/drive.d.ts

@@ -1,5 +1,5 @@
 import type { ToolRegistry } from '../registry.js';
-export declare function prepareLocalDest(savePath: string, filename: string): string;
+export declare function isTextualMime(mimeType: string): boolean;
 export declare const DRIVE_QUERY_HINT: string;
 export declare function normalizeDriveQuery(raw: string): string;
 export declare function isDriveInvalidQuery(error: any): boolean;

package/dist/tools/drive.js

@@ -4,6 +4,7 @@ import { drive as driveClient } from '@googleapis/drive';
 import { accountAliasSchema, getAccountSet } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
+import { openLocalReadStream, prepareLocalDest } from './_local-files.js';
 import { isAllowed, writeDisabledResult } from '../write-control.js';
 import { capText } from '../trim.js';
 import * as fs from 'fs';
@@ -24,6 +25,29 @@ const GOOGLE_WORKSPACE_TYPES = new Set([
     'application/vnd.google-apps.presentation',
     'application/vnd.google-apps.drawing',
 ]);
+// drive_read inlines only textual content. Beyond text/*, RFC 6839 structured-
+// syntax suffixes (+json/+xml/...) and a few bare application/* types are text
+// in practice — image/svg+xml was the motivating false "binary" refusal.
+const TEXTUAL_EXACT = new Set([
+    'application/json',
+    'application/xml',
+    'application/javascript',
+    'application/x-ndjson',
+    'application/yaml',
+    'application/x-yaml',
+    'application/sql',
+    'application/x-sh',
+    'application/csv',
+]);
+export function isTextualMime(mimeType) {
+    const bare = mimeType.split(';')[0].trim().toLowerCase();
+    if (bare.startsWith('text/'))
+        return true;
+    if (/\+(json|xml|yaml|toml|csv)$/.test(bare))
+        return true;
+    return TEXTUAL_EXACT.has(bare);
+}
+const BINARY_READ_HINT = 'Binary content cannot be inlined. Use drive_download to save the file to disk, or drive_export for Google Workspace files.';
 // Comment/Reply fields list — Drive API requires explicit `fields` on every call.
 const COMMENT_BASE_FIELDS = 'id,kind,content,htmlContent,createdTime,modifiedTime,resolved,anchor,author,deleted,quotedFileContent';
 const REPLY_SUBFIELDS = 'id,content,action,createdTime,modifiedTime,author,deleted';
@@ -31,12 +55,6 @@ const COMMENT_FIELDS = `${COMMENT_BASE_FIELDS},replies(${REPLY_SUBFIELDS})`;
 const COMMENT_LIST_FIELDS = `nextPageToken,comments(${COMMENT_BASE_FIELDS},replies(${REPLY_SUBFIELDS}))`;
 const REPLY_FIELDS = `kind,htmlContent,${REPLY_SUBFIELDS}`;
 const REPLY_LIST_FIELDS = `nextPageToken,replies(${REPLY_FIELDS})`;
-// path.basename() is a traversal guard — a caller-supplied filename must never escape savePath.
-export function prepareLocalDest(savePath, filename) {
-    const dest = path.join(savePath, path.basename(filename));
-    fs.mkdirSync(savePath, { recursive: true });
-    return dest;
-}
 export const DRIVE_QUERY_HINT = "Drive search syntax: a plain keyword is treated as a full-text search, but a " +
     "structured query needs an operator, e.g. \"name contains 'report'\", " +
     "\"mimeType = 'application/pdf'\", or \"'me' in owners\". " +
@@ -131,7 +149,7 @@ export function registerDriveTools(server) {
     });
     server.registerTool('drive_read', {
         _meta: { 'anthropic/maxResultSizeChars': 100_000 },
-        description: 'Read the content of a Google Drive file (returns up to maxChars characters per call; non-Google-native files over 2MB return too_large)',
+        description: 'Read the content of a Google Drive file: Workspace docs and textual types (text/*, JSON/XML/SVG and similar) inline; other binaries return error:binary (returns up to maxChars characters per call; non-Google-native files over 2MB return too_large)',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             fileId: z.string().describe('Google Drive file ID'),
@@ -184,6 +202,7 @@ export function registerDriveTools(server) {
                                 name,
                                 mimeType,
                                 error: 'binary',
+                                hint: BINARY_READ_HINT,
                                 webViewLink,
                             }, null, 2),
                         }],
@@ -204,7 +223,7 @@ export function registerDriveTools(server) {
                         }],
                 };
             }
-            if (mimeType?.startsWith('text/')) {
+            if (mimeType && isTextualMime(mimeType)) {
                 const downloaded = await drive.files.get({ fileId, alt: 'media', supportsAllDrives: true }, { responseType: 'text' });
                 return respond(String(downloaded.data));
             }
@@ -216,6 +235,7 @@ export function registerDriveTools(server) {
                             name,
                             mimeType,
                             error: 'binary',
+                            hint: BINARY_READ_HINT,
                             webViewLink,
                         }, null, 2),
                     }],
@@ -275,7 +295,7 @@ export function registerDriveTools(server) {
             const auth = await getClient(account);
             const drive = driveClient({ version: 'v3', auth });
             const resolvedMime = mimeTypeArg ?? (mime.lookup(localPath) || 'application/octet-stream');
-            const fileStream = fs.createReadStream(localPath);
+            const fileStream = await openLocalReadStream(localPath);
             const res = await drive.files.create({
                 requestBody: {
                     name: filename,
@@ -414,7 +434,7 @@ export function registerDriveTools(server) {
             if (localPathArg) {
                 params.media = {
                     mimeType: mimeTypeArg ?? (mime.lookup(localPathArg) || 'application/octet-stream'),
-                    body: fs.createReadStream(localPathArg),
+                    body: await openLocalReadStream(localPathArg),
                 };
                 if (convertTo)
                     requestBody.mimeType = convertTo;
@@ -1440,7 +1460,7 @@ async function downloadAndUpload(sourceDrive, targetDrive, fileId, sourceMime, p
             },
             media: {
                 mimeType: plan.kind === 'native' ? plan.exportMime : (sourceMime ?? 'application/octet-stream'),
-                body: fs.createReadStream(tmp),
+                body: await openLocalReadStream(tmp),
             },
             supportsAllDrives: true,
             fields: 'id,name,mimeType,webViewLink',

package/dist/tools/gmail.js

@@ -5,6 +5,7 @@ import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError, mapGoogleError } from './_errors.js';
 import { buildReplyHeaders, composeRaw, renderMarkdown, htmlToMarkdown, HeaderInjectionError } from './gmail-mime.js';
+import { prepareLocalDest } from './_local-files.js';
 import addressparser from 'nodemailer/lib/addressparser/index.js';
 import { lookup as lookupMime } from 'mime-types';
 import { configDir } from '../config-file.js';
@@ -679,8 +680,7 @@ export function registerGmailTools(server) {
             if (!data)
                 throw new Error('No attachment data returned');
             const buffer = Buffer.from(data, 'base64url');
-            // Strip path components so callers can't escape savePath via "../".
-            const fullPath = path.join(savePath, path.basename(filename));
+            const fullPath = prepareLocalDest(savePath, filename);
             await fs.promises.writeFile(fullPath, buffer, { mode: 0o600 });
             return {
                 content: [{ type: 'text', text: `Saved to ${fullPath} (${buffer.length} bytes)` }],

package/dist/tools/google-api.d.ts

@@ -2,9 +2,12 @@ import type { ToolRegistry } from '../registry.js';
 import { type Policy } from '../write-control.js';
 import { getClient } from '../client.js';
 import { type Toolsets } from '../toolsets.js';
-import { type DiscoveryDeps } from '../discovery-client.js';
+import { type DiscoveryDeps, type DiscoveryMethod } from '../discovery-client.js';
 export interface EscapeDeps extends DiscoveryDeps {
     getClientFn?: typeof getClient;
     toolsets?: Toolsets;
 }
+/** Up to three closest known ids for the unknown_method did-you-mean hint;
+ * bounded distance so unrelated ids never masquerade as suggestions. */
+export declare function nearestMethodIds(methodId: string, index: DiscoveryMethod[]): string[];
 export declare function registerEscapeTools(registry: ToolRegistry, policy: Policy, deps?: EscapeDeps): void;

package/dist/tools/google-api.js

@@ -4,6 +4,7 @@ import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
 import { coerceJson } from './_coerce.js';
 import { getToolsets, toolsetEnabled } from '../toolsets.js';
+import { editDistance } from '../scope-catalog.js';
 import { executeApiMethod, jsonResult } from '../executor.js';
 import { WORKSPACE_APIS, cudFromMethod, loadMethodIndex, searchMethods, } from '../discovery-client.js';
 const accountEnum = accountAliasSchema.optional();
@@ -29,6 +30,17 @@ const SERVICE_FOR_ALIAS = {
     admin_datatransfer: 'admin',
     groupssettings: 'groupssettings',
 };
+/** Up to three closest known ids for the unknown_method did-you-mean hint;
+ * bounded distance so unrelated ids never masquerade as suggestions. */
+export function nearestMethodIds(methodId, index) {
+    const maxDist = Math.max(3, Math.floor(methodId.length / 3));
+    return index
+        .map((m) => ({ id: m.id, d: editDistance(methodId.toLowerCase(), m.id.toLowerCase()) }))
+        .filter((x) => x.d <= maxDist)
+        .sort((a, b) => a.d - b.d)
+        .slice(0, 3)
+        .map((x) => x.id);
+}
 function describeMethod(m) {
     return {
         api: m.api,
@@ -127,12 +139,25 @@ export function registerEscapeTools(registry, policy, deps = {}) {
         catch (err) {
             return jsonResult({ error: 'discovery_unavailable', message: err.message, retriable: true, account }, true);
         }
-        const method = index.find((m) => m.id === methodId);
+        let method = index.find((m) => m.id === methodId);
+        if (!method) {
+            // Some discovery docs keep a legacy id prefix (the searchconsole doc's
+            // methods are webmasters.*): when the caller prefixed with our api
+            // alias, retry under the doc's own prefix before failing.
+            const docPrefix = index[0]?.id.split('.')[0];
+            const [head, ...rest] = String(methodId).split('.');
+            if (docPrefix && head === api && head !== docPrefix && rest.length > 0) {
+                const swapped = [docPrefix, ...rest].join('.');
+                method = index.find((m) => m.id === swapped);
+            }
+        }
         if (!method) {
+            const near = nearestMethodIds(String(methodId), index);
             return jsonResult({
                 error: 'unknown_method',
                 message: `No method "${methodId}" in ${api}.`,
-                hint: `Use google_api_search({query: "...", api: "${api}"}) to find the right method id.`,
+                hint: `${near.length ? `Did you mean: ${near.join(', ')}? ` : ''}` +
+                    `Use google_api_search({query: "...", api: "${api}"}) to find the right method id.`,
                 retriable: false,
                 account,
             }, true);

package/package.json

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