mcp-google-multi 6.0.0-alpha.2 → 6.0.0-alpha.4

package/dist/api-probe.d.ts

@@ -0,0 +1,18 @@
+import type { ApiProbeResult } from './doctor.js';
+export interface ApiProbeSpec {
+    service: string;
+    /** console library id for the enable deep-link, e.g. "calendar-json". */
+    api: string;
+    url: string;
+    scopePrefixes: string[];
+    /** id-required APIs have no no-arg read; a 404 on a nonexistent id still
+     * proves the API is enabled (accessNotConfigured wins before routing). */
+    notFoundMeansEnabled?: boolean;
+}
+export declare const API_PROBES: ApiProbeSpec[];
+export declare function planProbes(granted: string[], probes?: ApiProbeSpec[]): ApiProbeSpec[];
+export interface ApiProbeDeps {
+    grantedScopes: (alias: string) => string[];
+    request: (alias: string, url: string) => Promise<void>;
+}
+export declare function probeApiEnablement(alias: string, deps?: ApiProbeDeps): Promise<ApiProbeResult[]>;

package/dist/api-probe.js

@@ -0,0 +1,65 @@
+import { getClient } from './client.js';
+import { readToken } from './token-store.js';
+import { mapGoogleError } from './tools/_errors.js';
+const P = 'https://www.googleapis.com/auth/';
+const BOGUS_ID = 'mcp-google-multi-probe-nonexistent';
+export const API_PROBES = [
+    { service: 'gmail', api: 'gmail', url: 'https://gmail.googleapis.com/gmail/v1/users/me/profile', scopePrefixes: [`${P}gmail.`] },
+    { service: 'drive', api: 'drive', url: 'https://www.googleapis.com/drive/v3/about?fields=user', scopePrefixes: [`${P}drive`] },
+    { service: 'calendar', api: 'calendar-json', url: 'https://www.googleapis.com/calendar/v3/users/me/calendarList?maxResults=1', scopePrefixes: [`${P}calendar`] },
+    // people/me needs profile scopes, not contacts; connections is the read the
+    // contacts grant actually authorizes.
+    { service: 'contacts', api: 'people', url: 'https://people.googleapis.com/v1/people/me/connections?personFields=names&pageSize=1', scopePrefixes: [`${P}contacts`] },
+    { service: 'sheets', api: 'sheets', url: `https://sheets.googleapis.com/v4/spreadsheets/${BOGUS_ID}`, scopePrefixes: [`${P}spreadsheets`], notFoundMeansEnabled: true },
+    { service: 'docs', api: 'docs', url: `https://docs.googleapis.com/v1/documents/${BOGUS_ID}`, scopePrefixes: [`${P}documents`], notFoundMeansEnabled: true },
+    { service: 'searchconsole', api: 'searchconsole', url: 'https://www.googleapis.com/webmasters/v3/sites', scopePrefixes: [`${P}webmasters`] },
+    { service: 'tasks', api: 'tasks', url: 'https://tasks.googleapis.com/tasks/v1/users/@me/lists?maxResults=1', scopePrefixes: [`${P}tasks`] },
+    { service: 'chat', api: 'chat', url: 'https://chat.googleapis.com/v1/spaces?pageSize=1', scopePrefixes: [`${P}chat.`] },
+    { service: 'meet', api: 'meet', url: 'https://meet.googleapis.com/v2/conferenceRecords?pageSize=1', scopePrefixes: [`${P}meetings.`] },
+    { service: 'forms', api: 'forms', url: `https://forms.googleapis.com/v1/forms/${BOGUS_ID}`, scopePrefixes: [`${P}forms.`], notFoundMeansEnabled: true },
+];
+export function planProbes(granted, probes = API_PROBES) {
+    return probes.filter((p) => granted.some((s) => p.scopePrefixes.some((prefix) => s.startsWith(prefix))));
+}
+const DEFAULT_DEPS = {
+    grantedScopes: (alias) => {
+        try {
+            const scope = readToken(alias)?.scope;
+            return typeof scope === 'string' ? scope.split(' ').filter(Boolean) : [];
+        }
+        catch {
+            return [];
+        }
+    },
+    request: async (alias, url) => {
+        const auth = await getClient(alias);
+        await auth.request({ url, timeout: 10_000 });
+    },
+};
+export async function probeApiEnablement(alias, deps = DEFAULT_DEPS) {
+    const results = [];
+    for (const spec of planProbes(deps.grantedScopes(alias))) {
+        try {
+            await deps.request(alias, spec.url);
+            results.push({ service: spec.service, api: spec.api, ok: true });
+        }
+        catch (error) {
+            const envelope = mapGoogleError(error, alias);
+            if (envelope.error === 'network_error') {
+                // One connect failure means they will all fail: abort so section 6
+                // reports a single WARN "Probe could not complete" with the code.
+                throw new Error(envelope.message, { cause: error });
+            }
+            if (envelope.error === 'api_not_enabled') {
+                results.push({ service: spec.service, api: spec.api, ok: false, notEnabled: true, message: envelope.message });
+            }
+            else if (spec.notFoundMeansEnabled && envelope.error === 'not_found') {
+                results.push({ service: spec.service, api: spec.api, ok: true });
+            }
+            else {
+                results.push({ service: spec.service, api: spec.api, ok: false, message: envelope.error });
+            }
+        }
+    }
+    return results;
+}

package/dist/doctor.js

@@ -6,6 +6,7 @@ import { deriveAccountHealth } from './tools/accounts-tool.js';
 import { peekMasterKeyProvenance, deleteMasterKeyMaterial } from './master-key.js';
 import { hasToken } from './token-store.js';
 import { configDir } from './config-file.js';
+import { probeApiEnablement } from './api-probe.js';
 const MIN_NODE_MAJOR = 22;
 const DEFAULT_DEPS = {
     nodeVersion: process.versions.node,
@@ -23,6 +24,7 @@ const DEFAULT_DEPS = {
     masterKeyProvenance: () => peekMasterKeyProvenance(),
     anyTokensExist: (aliases) => aliases.some((a) => hasToken(a)),
     fileExists: fs.existsSync,
+    probeApi: (alias) => probeApiEnablement(alias),
 };
 /** Console deep-link to enable one API (section-6 hint, error taxonomy B10). */
 export function apiEnableLink(api) {
@@ -163,6 +165,9 @@ async function sectionApiEnablement(deps, aliases) {
         // Network / transient: WARN with the target, never crash the report.
         return { id: 6, title: 'API enablement', verdict: 'warn', lines: [`Probe could not complete: ${e?.message ?? e}`] };
     }
+    if (results.length === 0) {
+        return { id: 6, title: 'API enablement', verdict: 'unknown', lines: [`No probeable service scopes granted on "${healthy}".`] };
+    }
     const disabled = results.filter((r) => r.notEnabled);
     const lines = results.map((r) => `${r.service}: ${r.ok ? 'enabled' : r.notEnabled ? 'NOT ENABLED' : `unknown (${r.message ?? 'error'})`}`);
     if (disabled.length > 0) {

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,4 @@
 import type { ToolRegistry } from '../registry.js';
-export declare function prepareLocalDest(savePath: string, filename: string): string;
 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';
@@ -31,12 +32,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\". " +
@@ -275,7 +270,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 +409,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 +1435,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/package.json

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