mcp-google-multi 6.0.0-alpha.19 → 6.0.0-alpha.20

package/dist/discovery-client.d.ts

@@ -2,6 +2,13 @@ export declare const SUPPORTED_APIS: Record<string, {
     id: string;
     version: string;
 }>;
+export declare const API_ALIASES: Record<string, string[]>;
+/**
+ * Resolve an `api` argument to real SUPPORTED_APIS keys: exact match, then
+ * case/punctuation-normalized ("Search-Console" -> searchconsole), then the
+ * alias map. null = genuinely unknown.
+ */
+export declare function resolveApiAliases(api: string): string[] | null;
 export interface DiscoveryParam {
     location: 'path' | 'query';
     required?: boolean;

package/dist/discovery-client.js

@@ -35,6 +35,38 @@ export const SUPPORTED_APIS = {
     vault: { id: 'vault', version: 'v1' },
     workspaceevents: { id: 'workspaceevents', version: 'v1' },
 };
+// Names agents actually type for an API, mapped to real SUPPORTED_APIS keys.
+// Motivated by observed escape-hatch misses ("analytics" is two Discovery
+// APIs, the Admin SDK is three); keep entries plural-target only when the
+// split is real.
+export const API_ALIASES = {
+    analytics: ['analyticsadmin', 'analyticsdata'],
+    ga4: ['analyticsadmin', 'analyticsdata'],
+    googleanalytics: ['analyticsadmin', 'analyticsdata'],
+    admin: ['admin_directory', 'admin_reports', 'admin_datatransfer'],
+    adminsdk: ['admin_directory', 'admin_reports', 'admin_datatransfer'],
+    directory: ['admin_directory'],
+    webmasters: ['searchconsole'],
+    gsc: ['searchconsole'],
+    contacts: ['people'],
+    appsscript: ['script'],
+    appscript: ['script'],
+    gmailpostmastertools: ['postmaster'],
+};
+/**
+ * Resolve an `api` argument to real SUPPORTED_APIS keys: exact match, then
+ * case/punctuation-normalized ("Search-Console" -> searchconsole), then the
+ * alias map. null = genuinely unknown.
+ */
+export function resolveApiAliases(api) {
+    if (SUPPORTED_APIS[api])
+        return [api];
+    const norm = api.trim().toLowerCase().replace(/[^a-z0-9]/g, '');
+    const direct = Object.keys(SUPPORTED_APIS).find((k) => k.replace(/[^a-z0-9]/g, '') === norm);
+    if (direct)
+        return [direct];
+    return API_ALIASES[norm] ?? null;
+}
 const TTL_MS = 7 * 24 * 60 * 60 * 1000;
 const STALE_RETRY_MS = 5 * 60 * 1000;
 const FETCH_TIMEOUT_MS = 10_000;

package/dist/tools/_errors.js

@@ -119,13 +119,32 @@ export function mapGoogleError(error, account, forbiddenHint, scopeContext) {
                 account,
             };
         }
-        return { error: 'forbidden', message, hint: forbiddenHint, retriable: false, account };
+        return {
+            error: 'forbidden',
+            message,
+            hint: forbiddenHint ??
+                `Google denied access at the resource level (not a scope problem): check that "${account}" actually has access to this item, e.g. it is shared with that account, and that you picked the right account alias.`,
+            retriable: false,
+            account,
+        };
     }
     if (status === 400 && /invalid[_ ]scope/i.test(message)) {
-        return { error: 'invalid_scope', message, retriable: false, account };
+        return {
+            error: 'invalid_scope',
+            message,
+            hint: 'One of the requested OAuth scopes is malformed or unavailable to this client. Run `config check` to review the account scope profile, fix it, then re-auth.',
+            retriable: false,
+            account,
+        };
     }
     if (status === 404) {
-        return { error: 'not_found', message, retriable: false, account };
+        return {
+            error: 'not_found',
+            message,
+            hint: `The ID does not exist or is not visible to "${account}". IDs are account-specific: re-fetch it with the matching list/search tool, and check the account alias is the one that owns the resource.`,
+            retriable: false,
+            account,
+        };
     }
     if (status === 429) {
         const retryAfter = error?.response?.headers?.['retry-after'];
@@ -151,7 +170,13 @@ export function mapGoogleError(error, account, forbiddenHint, scopeContext) {
         };
     }
     if (status !== undefined && status >= 500) {
-        return { error: 'upstream_error', message, retriable: true, account };
+        return {
+            error: 'upstream_error',
+            message,
+            hint: 'Google-side server error, usually transient: retry, with backoff if it repeats.',
+            retriable: true,
+            account,
+        };
     }
     if (status === undefined) {
         const fsCode = typeof error?.code === 'string' && LOCAL_FS_CODES.has(error.code) ? error.code : undefined;
@@ -178,7 +203,17 @@ export function mapGoogleError(error, account, forbiddenHint, scopeContext) {
             };
         }
     }
-    return { error: 'upstream_error', message, retriable: false, account };
+    // Passthrough floor: still emit a hint so no envelope leaves the mapper
+    // without a next step. A 400 here is a request Google parsed and rejected.
+    return {
+        error: 'upstream_error',
+        message,
+        hint: status === 400
+            ? 'Google rejected the request as malformed: an argument is likely wrong or missing. Check IDs, enum values and formats against the tool description before retrying.'
+            : 'Unclassified error: the message above is the best signal. Retry only if it reads as transient; otherwise change the request rather than repeating it.',
+        retriable: false,
+        account,
+    };
 }
 export function handleGoogleApiError(error, account, forbiddenHint, scopeContext) {
     const envelope = mapGoogleError(error, account, forbiddenHint, scopeContext);

package/dist/tools/_local-files.js

@@ -2,8 +2,13 @@ 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 });
+    const name = path.basename(filename);
+    // Agents routinely pass the intended FILE path as savePath and repeat the
+    // name in `filename`; a blind join would mkdir a directory named like the
+    // file and bury the download inside it, so strip the duplicated leaf.
+    const dir = path.basename(savePath) === name ? path.dirname(savePath) : savePath;
+    const dest = path.join(dir, name);
+    fs.mkdirSync(dir, { recursive: true });
     return dest;
 }
 // fs.createReadStream() reports an unopenable path as an async 'error' EVENT;

package/dist/tools/google-api.js

@@ -6,7 +6,7 @@ import { coerceJson } from './_coerce.js';
 import { getToolsets, toolsetEnabled } from '../toolsets.js';
 import { editDistance } from '../scope-catalog.js';
 import { executeApiMethod, jsonResult } from '../executor.js';
-import { SUPPORTED_APIS, cudFromMethod, loadMethodIndex, searchMethods, } from '../discovery-client.js';
+import { SUPPORTED_APIS, resolveApiAliases, cudFromMethod, loadMethodIndex, searchMethods, } from '../discovery-client.js';
 const accountEnum = accountAliasSchema.optional();
 // Policy/toolset namespace for each API alias must match the NAMED tools' service
 // names, or user deny globs and GOOGLE_TOOLSETS silently miss escape-hatch calls.
@@ -80,12 +80,20 @@ export function registerEscapeTools(registry, policy, deps = {}) {
         },
         annotations: { openWorldHint: true },
     }, async ({ query, api, maxResults }) => {
-        if (api && !SUPPORTED_APIS[api]) {
-            return jsonResult({ error: 'unknown_api', message: `Unknown api "${api}".`, hint: `Known APIs: ${apiList}`, retriable: false }, true);
+        // Alias resolution: "analytics" fans out to both GA4 Discovery APIs
+        // instead of dead-ending on unknown_api.
+        let requested = null;
+        if (api) {
+            requested = resolveApiAliases(api);
+            if (!requested) {
+                return jsonResult({ error: 'unknown_api', message: `Unknown api "${api}".`, hint: `Known APIs: ${apiList}`, retriable: false }, true);
+            }
+            const enabled = requested.filter(apiEnabled);
+            if (enabled.length === 0)
+                return toolsetDisabled(requested[0]);
+            requested = enabled;
         }
-        if (api && !apiEnabled(api))
-            return toolsetDisabled(api);
-        const apis = api ? [api] : enabledApis;
+        const apis = requested ?? enabledApis;
         const unavailable = [];
         const indexes = await Promise.all(apis.map(async (a) => {
             try {
@@ -98,6 +106,9 @@ export function registerEscapeTools(registry, policy, deps = {}) {
         }));
         const matches = searchMethods(indexes.flat(), query, maxResults ?? 10);
         return jsonResult({
+            // Teach the resolved keys whenever the input wasn't already one, so the
+            // follow-up google_api_call uses a real key.
+            ...(requested && (requested.length > 1 || requested[0] !== api) ? { resolvedApi: requested } : {}),
             methods: matches.map(describeMethod),
             ...(unavailable.length > 0 ? { unavailableApis: unavailable } : {}),
             next: 'Invoke with google_api_call({account, api, methodId, pathParams, queryParams, body}).',
@@ -129,14 +140,20 @@ export function registerEscapeTools(registry, policy, deps = {}) {
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
         _meta: { 'anthropic/maxResultSizeChars': 100_000 },
     }, async ({ account, api, methodId, pathParams, queryParams, body }) => {
-        if (!SUPPORTED_APIS[api]) {
+        const resolved = resolveApiAliases(api);
+        if (!resolved) {
             return jsonResult({ error: 'unknown_api', message: `Unknown api "${api}".`, hint: `Known APIs: ${apiList}`, retriable: false, account }, true);
         }
-        if (!apiEnabled(api))
-            return toolsetDisabled(api);
+        if (resolved.length > 1) {
+            // A call targets exactly one Discovery doc; only search can fan out.
+            return jsonResult({ error: 'unknown_api', message: `"${api}" maps to ${resolved.length} APIs.`, hint: `Pass one of: ${resolved.join(', ')} (method ids differ per API; google_api_search({query, api: "${api}"}) finds the right one).`, retriable: false, account }, true);
+        }
+        const apiKey = resolved[0];
+        if (!apiEnabled(apiKey))
+            return toolsetDisabled(apiKey);
         let index;
         try {
-            index = await loadMethodIndex(api, deps);
+            index = await loadMethodIndex(apiKey, deps);
         }
         catch (err) {
             return jsonResult({ error: 'discovery_unavailable', message: err.message, retriable: true, account }, true);
@@ -148,7 +165,7 @@ export function registerEscapeTools(registry, policy, deps = {}) {
             // 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) {
+            if (docPrefix && (head === apiKey || head === api) && head !== docPrefix && rest.length > 0) {
                 const swapped = [docPrefix, ...rest].join('.');
                 method = index.find((m) => m.id === swapped);
             }
@@ -157,15 +174,15 @@ export function registerEscapeTools(registry, policy, deps = {}) {
             const near = nearestMethodIds(String(methodId), index);
             return jsonResult({
                 error: 'unknown_method',
-                message: `No method "${methodId}" in ${api}.`,
+                message: `No method "${methodId}" in ${apiKey}.`,
                 hint: `${near.length ? `Did you mean: ${near.join(', ')}? ` : ''}` +
-                    `Use google_api_search({query: "...", api: "${api}"}) to find the right method id.`,
+                    `Use google_api_search({query: "...", api: "${apiKey}"}) to find the right method id.`,
                 retriable: false,
                 account,
             }, true);
         }
         const cud = cudFromMethod(method);
-        const policyService = serviceForAlias(api);
+        const policyService = serviceForAlias(apiKey);
         const lastSegment = method.id.split('.').pop() ?? method.id;
         const toolRef = { name: `${policyService}_${lastSegment}`, service: policyService, cud };
         if (cud !== 'read' && !isAllowed(toolRef, policy)) {

package/package.json

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