mcp-google-multi 6.0.0-alpha.68 → 6.0.0-alpha.69

package/dist/discover.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { describePolicy } from './write-control.js';
+import { hints } from './hint-provider.js';
 // The description budget is the whole point of lazy mode: a full op list per
 // service put lazy tools/list at ~11.5k tokens (RQ2), so descriptions carry a
 // CAPPED vocabulary and the complete catalog stays in this tool's RESULT.
@@ -91,6 +92,7 @@ export function registerDiscoverTools(registry, policy) {
         }, async ({ query }) => {
             const operations = registry.catalog(service, query);
             registry.reveal(service);
+            const rendered = hints()?.render({ kind: 'policy_summary', policy });
             return {
                 content: [
                     {
@@ -98,7 +100,7 @@ export function registerDiscoverTools(registry, policy) {
                         text: JSON.stringify({
                             service,
                             operations,
-                            writeControl: describePolicy(policy),
+                            writeControl: rendered?.hint ?? describePolicy(policy),
                             next: operations.length > 0
                                 ? 'Call the chosen tool by name; it is now listed and callable.'
                                 : `No ${service} operation matches "${query}". Call again without query for the full catalog.`,

package/dist/doctor.js

@@ -14,6 +14,7 @@ import { apiProbeDepsFor, probeApiEnablement } from './api-probe.js';
 import { safeMessage, stringifyEnvelope } from './tools/_errors.js';
 import { resolveHttpConfig, HttpConfigError } from './http-config.js';
 import { parseOwnerEmails } from './http-transport.js';
+import { hints } from './hint-provider.js';
 const MIN_NODE_MAJOR = 22;
 const DEFAULT_DEPS = {
     nodeVersion: process.versions.node,
@@ -70,9 +71,22 @@ export function apiEnableLink(api) {
     return `https://console.cloud.google.com/apis/library/${api}.googleapis.com`;
 }
 const LEGACY_ENV_KEYS = ['GOOGLE_ACCOUNTS', 'GOOGLE_OPTIONAL_SCOPES', 'GOOGLE_ADMIN_ACCOUNTS'];
-function sectionRuntime(deps) {
+function sectionRuntime(deps, tenantScope = false) {
     const major = Number.parseInt(deps.nodeVersion.split('.')[0] ?? '0', 10);
     if (!Number.isFinite(major) || major < MIN_NODE_MAJOR) {
+        if (tenantScope) {
+            // The host version is operator infrastructure, not the tenant's (E7
+            // residue): no version string, and the fix is the operator's to apply.
+            const rendered = hints()?.render({ kind: 'operator_only', slug: 'E_NODE_TOO_OLD' });
+            return {
+                id: 1,
+                title: 'Runtime',
+                verdict: 'fail',
+                slug: 'E_NODE_TOO_OLD',
+                lines: ['Runtime below the supported version'],
+                hint: rendered?.hint ?? 'Tell the server operator the code E_NODE_TOO_OLD.',
+            };
+        }
         return {
             id: 1,
             title: 'Runtime',
@@ -82,7 +96,12 @@ function sectionRuntime(deps) {
             hint: `Upgrade to Node ${MIN_NODE_MAJOR} LTS or newer.`,
         };
     }
-    return { id: 1, title: 'Runtime', verdict: 'ok', lines: [`Node.js ${deps.nodeVersion} (>= ${MIN_NODE_MAJOR})`] };
+    return {
+        id: 1,
+        title: 'Runtime',
+        verdict: 'ok',
+        lines: [tenantScope ? 'Runtime ok' : `Node.js ${deps.nodeVersion} (>= ${MIN_NODE_MAJOR})`],
+    };
 }
 function sectionConfig(deps, set, tenantScope = false) {
     const lines = [];
@@ -90,13 +109,16 @@ function sectionConfig(deps, set, tenantScope = false) {
     let hint;
     let slug;
     if (!set || set.aliases.length === 0) {
+        const tenantHint = tenantScope ? (hints()?.render({ kind: 'no_accounts' })?.hint ?? '') : undefined;
         return {
             id: 2,
             title: 'Config',
             verdict: 'fail',
             slug: 'E_NO_ACCOUNTS_CONFIGURED',
             lines: ['No accounts configured.'],
-            ...(tenantScope ? {} : { hint: 'Add an account: run `npx mcp-google-multi migrate-config` or set GOOGLE_ACCOUNTS.' }),
+            ...(tenantScope
+                ? (tenantHint ? { hint: tenantHint } : {})
+                : { hint: 'Add an account: run `npx mcp-google-multi migrate-config` or set GOOGLE_ACCOUNTS.' }),
         };
     }
     // The config file, process env, working directory and metrics store below
@@ -188,7 +210,8 @@ function sectionsTokensAndScopes(deps, aliases) {
             if (scopeVerdict === 'ok')
                 scopeVerdict = 'warn';
             scopeLines.push(`${alias}: ${r.callable.length} callable, ${r.requestable.length} requested-not-granted`);
-            scopeHint = `Re-auth to grant missing scopes. ${reauthHint(alias)}`;
+            const rendered = hints()?.render({ kind: 'scopes_missing', account: alias });
+            scopeHint = rendered?.hint ?? `Re-auth to grant missing scopes. ${reauthHint(alias)}`;
         }
         else {
             scopeLines.push(`${alias}: ${r.callable.length} callable, all profile scopes granted`);
@@ -199,7 +222,7 @@ function sectionsTokensAndScopes(deps, aliases) {
         { id: 5, title: 'Scopes', verdict: scopeVerdict, lines: scopeLines, ...(scopeHint ? { hint: scopeHint } : {}), ...(scopeVerdict === 'warn' ? { slug: 'E_SCOPE_NOT_GRANTED' } : {}) },
     ];
 }
-async function sectionApiEnablement(deps, aliases) {
+async function sectionApiEnablement(deps, aliases, tenantScope = false) {
     if (!deps.probeApi) {
         return { id: 6, title: 'API enablement', verdict: 'unknown', lines: ['Probe not run (no live account probe configured).'] };
     }
@@ -216,8 +239,15 @@ async function sectionApiEnablement(deps, aliases) {
         results = await deps.probeApi(healthy);
     }
     catch (e) {
-        // 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}`] };
+        // Network / transient: WARN with the target, never crash the report. The
+        // raw text can name an egress or proxy host (E7 residue): tenant scope
+        // drops it.
+        return {
+            id: 6,
+            title: 'API enablement',
+            verdict: 'warn',
+            lines: [tenantScope ? 'Probe could not complete.' : `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}".`] };
@@ -225,13 +255,14 @@ async function sectionApiEnablement(deps, aliases) {
     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) {
+        const rendered = hints()?.render({ kind: 'apis_disabled', services: disabled.map((r) => ({ service: r.service, api: r.api })) });
         return {
             id: 6,
             title: 'API enablement',
             verdict: 'fail',
             slug: 'E_API_NOT_ENABLED',
             lines,
-            hint: disabled.map((r) => `Enable ${r.service}: ${apiEnableLink(r.api)}`).join('\n'),
+            hint: rendered?.hint ?? disabled.map((r) => `Enable ${r.service}: ${apiEnableLink(r.api)}`).join('\n'),
         };
     }
     return { id: 6, title: 'API enablement', verdict: 'ok', lines: lines.length ? lines : ['(probed account, all enabled)'] };
@@ -313,7 +344,7 @@ export async function runDiagnostics(deps = DEFAULT_DEPS, opts = {}) {
     // the context's own account count.
     const tenantScope = opts.scope === 'tenant';
     const sections = [];
-    sections.push(sectionRuntime(deps));
+    sections.push(sectionRuntime(deps, tenantScope));
     const set = deps.accountSet();
     sections.push(sectionConfig(deps, set, tenantScope));
     const aliases = set?.aliases ?? [];
@@ -322,7 +353,7 @@ export async function runDiagnostics(deps = DEFAULT_DEPS, opts = {}) {
     if (aliases.length > 0) {
         const [tokens, scopes] = sectionsTokensAndScopes(deps, aliases);
         sections.push(tokens, scopes);
-        sections.push(await sectionApiEnablement(deps, aliases));
+        sections.push(await sectionApiEnablement(deps, aliases, tenantScope));
     }
     if (!tenantScope) {
         const http = await sectionHttp(deps, aliases);

package/dist/executor.js

@@ -4,6 +4,7 @@ import { expandPath, isGoogleApiUrl } from './discovery-client.js';
 import { handleGoogleApiError } from './tools/_errors.js';
 import { scopeHintForMethod } from './scope-observability.js';
 import { checkOutboundForMethod } from './outbound-allowlist.js';
+import { hints } from './hint-provider.js';
 export const MAX_RESPONSE_CHARS = 100_000;
 export function jsonResult(payload, isError = false) {
     const base = { content: [{ type: 'text', text: JSON.stringify(payload) }] };
@@ -70,10 +71,11 @@ export async function executeApiMethod(method, args, deps = {}) {
         }, true);
     }
     if (!isGoogleApiUrl(url)) {
+        const rendered = hints()?.render({ kind: 'untrusted_host' });
         return jsonResult({
             error: 'untrusted_host',
             message: `Refusing to send credentials to a non-googleapis.com host for "${method.id}".`,
-            hint: 'The discovery cache may be corrupt; delete DISCOVERY_CACHE_PATH and retry.',
+            hint: rendered?.hint ?? 'The discovery cache may be corrupt; delete DISCOVERY_CACHE_PATH and retry.',
             retriable: false,
             account: args.account,
         }, true);

package/dist/fanout.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import { getAccountSet, liveAccountCheck, unknownAliasMessage } from './accounts.js';
 import { echoName, echoNames, MAX_SUGGESTED_KEYS } from './arg-strict.js';
+import { hints } from './hint-provider.js';
 export const CSV_RE = /^[a-zA-Z0-9_-]+(\s*,\s*[a-zA-Z0-9_-]+)+$/;
 const FANOUT_CONCURRENCY = 5;
 // `aliases` is required (no global default): the field is baked into a
@@ -113,10 +114,17 @@ export async function runFanout(handler, args, aliases) {
                 results[i] = res?.isError ? { account, ok: false, error: payload } : { account, ok: true, data: payload };
             }
             catch (err) {
+                const rendered = hints()?.render({ kind: 'internal', account });
                 results[i] = {
                     account,
                     ok: false,
-                    error: { error: 'internal', message: err.message, retriable: false, account },
+                    error: {
+                        error: 'internal',
+                        message: rendered?.message ?? err.message,
+                        hint: rendered?.hint,
+                        retriable: false,
+                        account,
+                    },
                 };
             }
         }

package/dist/hint-provider.d.ts

@@ -0,0 +1,129 @@
+import type { DenyReason, Policy } from './write-control.js';
+export type HintCase = {
+    kind: 'reauth';
+    account: string;
+} | {
+    kind: 'legacy_plaintext_token';
+    account: string;
+} | {
+    kind: 'dead_refresh_token';
+    account: string;
+} | {
+    kind: 'token_unreadable';
+    account: string;
+} | {
+    kind: 'scopes_missing';
+    account: string;
+} | {
+    kind: 'scope_not_granted';
+    account: string;
+    scope: string;
+} | {
+    kind: 'scope_needs_bundle';
+    account: string;
+    scope: string;
+    bundle: string;
+} | {
+    kind: 'scope_base_excluded';
+    account: string;
+    scope: string;
+} | {
+    kind: 'scope_account_type';
+    account: string;
+    scope: string;
+} | {
+    kind: 'scope_unknown_scope';
+    scope: string;
+} | {
+    kind: 'scope_unknown';
+    account: string;
+    serviceText?: string;
+    bundle?: string;
+} | {
+    kind: 'write_denied';
+    tool: {
+        name: string;
+        service: string;
+        cud: string;
+    };
+    reason: DenyReason;
+    policy: Policy;
+} | {
+    kind: 'policy_summary';
+    policy: Policy;
+} | {
+    kind: 'outbound_denied';
+    what: string;
+    blocked: string[];
+    entries: string[];
+} | {
+    kind: 'no_default_account';
+    aliases: string[];
+} | {
+    kind: 'no_accounts';
+} | {
+    kind: 'api_not_enabled';
+    api?: string;
+    service?: string;
+    project?: string;
+    googleMessage: string;
+} | {
+    kind: 'apis_disabled';
+    services: {
+        service: string;
+        api: string;
+    }[];
+} | {
+    kind: 'daily_quota';
+} | {
+    kind: 'project_suspended';
+    account: string;
+} | {
+    kind: 'invalid_scope';
+    account: string;
+} | {
+    kind: 'no_oauth_client';
+} | {
+    kind: 'network_error';
+    code: string;
+} | {
+    kind: 'local_path';
+    code: string;
+    path?: string;
+} | {
+    kind: 'internal';
+    account?: string;
+} | {
+    kind: 'untrusted_host';
+} | {
+    kind: 'toolset_disabled';
+    api: string;
+    service: string;
+} | {
+    kind: 'service_not_enabled';
+    tool: string;
+    service: string;
+    bundle?: string;
+    aliases: string[];
+    admin: boolean;
+    toolsetOff: boolean;
+    awaitingRestart: boolean;
+} | {
+    kind: 'operator_only';
+    slug: string;
+};
+export declare const HINT_KINDS: readonly ["reauth", "legacy_plaintext_token", "dead_refresh_token", "token_unreadable", "scopes_missing", "scope_not_granted", "scope_needs_bundle", "scope_base_excluded", "scope_account_type", "scope_unknown_scope", "scope_unknown", "write_denied", "policy_summary", "outbound_denied", "no_default_account", "no_accounts", "api_not_enabled", "apis_disabled", "daily_quota", "project_suspended", "invalid_scope", "no_oauth_client", "network_error", "local_path", "internal", "untrusted_host", "toolset_disabled", "service_not_enabled", "operator_only"];
+/** `message` only for the kinds whose message leaks today (write_denied,
+ * no_oauth_client, local_path, internal, toolset_disabled); every other call
+ * site ignores it. `retriable` only where it may legitimately differ from
+ * the owner's default (scope_not_granted). */
+export interface Rendered {
+    hint: string;
+    message?: string;
+    retriable?: boolean;
+}
+export interface HintProvider {
+    render(c: HintCase): Rendered;
+}
+export declare function setHintProvider(p: HintProvider | null): void;
+export declare function hints(): HintProvider | null;

package/dist/hint-provider.js

@@ -0,0 +1,64 @@
+// A plain array literal, not derived from the union: deriving it would need a
+// value-level mirror of the type anyway, and this way a missing member is
+// caught by the completeness check below instead of silently compiling.
+// `as const` so that check narrows to the literal tuple rather than widening
+// every element back to the whole HintCase['kind'] union (which would make
+// it pass trivially, whatever was listed).
+export const HINT_KINDS = [
+    'reauth',
+    'legacy_plaintext_token',
+    'dead_refresh_token',
+    'token_unreadable',
+    'scopes_missing',
+    'scope_not_granted',
+    'scope_needs_bundle',
+    'scope_base_excluded',
+    'scope_account_type',
+    'scope_unknown_scope',
+    'scope_unknown',
+    'write_denied',
+    'policy_summary',
+    'outbound_denied',
+    'no_default_account',
+    'no_accounts',
+    'api_not_enabled',
+    'apis_disabled',
+    'daily_quota',
+    'project_suspended',
+    'invalid_scope',
+    'no_oauth_client',
+    'network_error',
+    'local_path',
+    'internal',
+    'untrusted_host',
+    'toolset_disabled',
+    'service_not_enabled',
+    'operator_only',
+];
+const _hintKindsComplete = true;
+void _hintKindsComplete;
+// Process-global, like the HTTP reauth linker: one process is either the
+// single owner or one multi-tenant host, never both.
+let installed = null;
+export function setHintProvider(p) {
+    installed = p;
+}
+// A throwing provider must never take down the call site: every call site
+// does `hints()?.render(...)?.hint ?? <default>`, so a render that cannot
+// produce a Rendered falls back to the same literal a missing provider
+// would, and the provider's own error text never reaches a client.
+export function hints() {
+    if (!installed)
+        return null;
+    const provider = installed;
+    return {
+        render(c) {
+            try {
+                return provider.render(c);
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}

package/dist/http-transport.d.ts

@@ -42,7 +42,17 @@ export interface HttpHostOptions {
      * registry, never another subject's. */
     resolveServer?: (claims: {
         sub: string;
-    }) => Promise<ServerTarget | null> | ServerTarget | null;
+    }) => Promise<ServerTarget | null | {
+        refused: {
+            error: string;
+            message: string;
+        };
+    }> | ServerTarget | null | {
+        refused: {
+            error: string;
+            message: string;
+        };
+    };
     /** Extra routes keyed by exact pathname (AS endpoints mount here in B13). */
     routes?: Record<string, RouteHandler>;
     log?: (line: string) => void;

package/dist/http-transport.js

@@ -16,6 +16,24 @@ const DISPATCH_TIMEOUT_DEFAULT = 120_000;
  * of a batch synchronously in one tick: without a cap one body multiplies the
  * per-call work by however many frames fit in it. */
 const MAX_BATCH_FRAMES = 16;
+// A resolveServer refusal's body reaches the wire verbatim (H3 PR1): validated
+// so a host cannot accidentally leak an operator path/env var through a wrongly
+// shaped slug or an overlong message. No new slug literal enters core itself —
+// the slug is always the host's own value.
+const REFUSAL_SLUG_RE = /^[a-z][a-z0-9_]{0,39}$/;
+const MAX_REFUSAL_MESSAGE_CHARS = 300;
+// C0/C1 controls, format chars (includes bidi overrides like U+202E and
+// zero-width joiners) and the line/paragraph separators; ordinary non-ASCII
+// letters stay allowed.
+const NON_PRINTABLE_RE = /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u;
+function isValidRefusal(r) {
+    return (typeof r.error === 'string' &&
+        REFUSAL_SLUG_RE.test(r.error) &&
+        typeof r.message === 'string' &&
+        r.message.length > 0 &&
+        r.message.length <= MAX_REFUSAL_MESSAGE_CHARS &&
+        !NON_PRINTABLE_RE.test(r.message));
+}
 export function parseOwnerEmails(env = process.env) {
     return (env.MCP_OWNER_EMAILS ?? '')
         .split(',')
@@ -366,12 +384,27 @@ export class HttpTransportHost {
             validationEnvelope: this.opts.validationEnvelope,
         };
         if (this.opts.resolveServer) {
+            let resolved;
             try {
-                target = await this.opts.resolveServer({ sub });
+                resolved = await this.opts.resolveServer({ sub });
             }
             catch {
-                target = null;
+                resolved = null;
+            }
+            if (resolved && 'refused' in resolved) {
+                const { refused } = resolved;
+                if (isValidRefusal(refused)) {
+                    res.writeHead(403, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: refused.error, message: refused.message }));
+                    this.log(`403 ${refused.error} path=/mcp`);
+                    return;
+                }
+                // An invalid shape falls through to today's exact answer rather than
+                // forwarding something unvalidated; a refusal never reaches dispatch
+                // either way.
+                resolved = null;
             }
+            target = resolved;
             if (!target) {
                 res.writeHead(403, { 'Content-Type': 'application/json' });
                 res.end(JSON.stringify({ error: 'tenant_not_found', message: 'no tenant is provisioned for this subject' }));

package/dist/oauth-as.d.ts

@@ -107,7 +107,11 @@ export interface AuthServerDeps {
         hd?: string;
     }) => {
         sub: string;
-    } | null;
+    } | null | {
+        denied: {
+            description: string;
+        };
+    };
     /** alias_add completion: persist the new alias's config row and tokens under
      * its tenant. /callback awaits it only after a successful Google exchange.
      * A returned refusal answers 403 with its slug; a throw or rejection answers

package/dist/oauth-as.js

@@ -22,6 +22,11 @@ export const DCR_MAX_REDIRECT_URIS = 10;
 const DCR_MAX_URI_LEN = 2048;
 const OIDC_SUB = /^[\x21-\x7e]{1,255}$/;
 const HOSTED_DOMAIN = /^[a-z0-9-]+(\.[a-z0-9-]+)+$/i;
+// RFC 6749's error_description charset: %x20-21 / %x23-5B / %x5D-7E (printable
+// ASCII minus the backslash and double-quote that would need escaping in the
+// query string). A resolveSubject denial outside this set is dropped rather
+// than forwarded unvalidated (H3 PR1).
+const ERROR_DESCRIPTION_RE = /^[\x20-\x21\x23-\x5b\x5d-\x7e]{1,200}$/;
 /** Only trust the id_token identity when Google marks the email verified (#8).
  * The token comes straight from Google's token endpoint, so its claims are
  * read unsigned. A malformed sub or hd is dropped, never passed on. */
@@ -570,12 +575,15 @@ export function buildAuthServer(config, deps = {}) {
         // signed into the authz code and flows into every token minted from it.
         const email = (exchanged.email ?? '').toLowerCase();
         const iss = encodeURIComponent(base);
-        const subject = email ? resolveSubject(email, { sub: exchanged.sub, hd: exchanged.hd }) : null;
-        if (!subject) {
+        const resolved = email ? resolveSubject(email, { sub: exchanged.sub, hd: exchanged.hd }) : null;
+        if (!resolved || 'denied' in resolved) {
             const sep = st.redirect_uri.includes('?') ? '&' : '?';
             const s = st.client_state ? `&state=${encodeURIComponent(st.client_state)}` : '';
-            return redirect(res, `${st.redirect_uri}${sep}error=access_denied${s}&iss=${iss}`);
+            const desc = resolved && 'denied' in resolved ? resolved.denied.description : undefined;
+            const d = desc !== undefined && ERROR_DESCRIPTION_RE.test(desc) ? `&error_description=${encodeURIComponent(desc)}` : '';
+            return redirect(res, `${st.redirect_uri}${sep}error=access_denied${d}${s}&iss=${iss}`);
         }
+        const subject = resolved;
         const authzCode = await signAuthzCode({ redirect_uri: st.redirect_uri, code_challenge: st.code_challenge, resource: st.resource, sub: subject.sub }, base, flowSecret, nowSec());
         log('callback ok flow=owner_gate');
         const sep = st.redirect_uri.includes('?') ? '&' : '?';

package/dist/outbound-allowlist.js

@@ -3,6 +3,7 @@
 // or share outside the operator's list), a safety feature first and an
 // enterprise checkbox second. FREE-core forever (ee-definition-v0 handoff).
 // Off by default: an unset/empty GOOGLE_OUTBOUND_ALLOWLIST gates nothing.
+import { hints } from './hint-provider.js';
 /** Parse GOOGLE_OUTBOUND_ALLOWLIST: comma-separated addresses and @domain
  * suffixes ("a@b.com, @company.com"). null = feature off (nothing gated). */
 export function resolveOutboundAllowlist(env = process.env) {
@@ -34,6 +35,7 @@ export function outboundViolations(emails, env = process.env) {
 /** The standard error envelope for a blocked outbound target. */
 export function outboundDeniedEnvelope(kind, blocked, account, env = process.env) {
     const list = resolveOutboundAllowlist(env);
+    const rendered = hints()?.render({ kind: 'outbound_denied', what: kind, blocked, entries: list?.entries ?? [] });
     return {
         content: [
             {
@@ -41,8 +43,9 @@ export function outboundDeniedEnvelope(kind, blocked, account, env = process.env
                 text: JSON.stringify({
                     error: 'recipient_not_allowed',
                     message: `${kind} blocked by the outbound allowlist: ${blocked.join(', ')}.`,
-                    hint: `GOOGLE_OUTBOUND_ALLOWLIST is active (${(list?.entries ?? []).join(', ')}). ` +
-                        'The operator must add the address (or its @domain) to the list, or unset the variable, to allow this target.',
+                    hint: rendered?.hint ??
+                        (`GOOGLE_OUTBOUND_ALLOWLIST is active (${(list?.entries ?? []).join(', ')}). ` +
+                            'The operator must add the address (or its @domain) to the list, or unset the variable, to allow this target.'),
                     retriable: false,
                     account,
                 }),

package/dist/reauth-hint.js

@@ -3,11 +3,15 @@
 // user cannot run a CLI, so the hint becomes a clickable, server-signed link
 // into the AS's clientless alias_reauth flow (AuthServer.reauthLink). The HTTP
 // bootstrap installs the linker when the AS starts; stdio never does.
+import { hints } from './hint-provider.js';
 let httpReauthLink = null;
 export function setHttpReauthLink(linker) {
     httpReauthLink = linker;
 }
 export function reauthHint(account) {
+    const rendered = hints()?.render({ kind: 'reauth', account });
+    if (rendered)
+        return rendered.hint;
     if (httpReauthLink) {
         return `Re-authenticate "${account}" in your browser, then retry: ${httpReauthLink(account)}`;
     }

package/dist/registry.js

@@ -6,6 +6,7 @@ import { fanoutAccountField, invalidAccountsResult, noAccountsResult, parseAccou
 import { MAX_RESPONSE_CHARS } from './executor.js';
 import { MAX_SUGGESTED_KEYS, suggestKeys } from './arg-strict.js';
 import { classifyScope } from './scope-observability.js';
+import { hints } from './hint-provider.js';
 /** Nothing granted, no profile: asks the BUNDLE CATALOG whether a scope is
  * reachable at all, independently of any account. */
 const EMPTY_SCOPES = new Set();
@@ -206,6 +207,8 @@ export class ToolRegistry {
                     refreshAccountSetIfStale();
                     const def = this.accounts().defaultAccount;
                     if (!def) {
+                        const aliases = this.accounts().aliases;
+                        const rendered = hints()?.render({ kind: 'no_default_account', aliases });
                         return {
                             content: [
                                 {
@@ -213,7 +216,7 @@ export class ToolRegistry {
                                     text: JSON.stringify({
                                         error: 'E_NO_DEFAULT_ACCOUNT',
                                         message: 'No "account" given and no default account is configured.',
-                                        hint: `Pass account explicitly (valid: ${this.accounts().aliases.join(', ')}), or set GOOGLE_DEFAULT_ACCOUNT / "defaultAccount" in config.json.`,
+                                        hint: rendered?.hint ?? `Pass account explicitly (valid: ${aliases.join(', ')}), or set GOOGLE_DEFAULT_ACCOUNT / "defaultAccount" in config.json.`,
                                         retriable: false,
                                     }),
                                 },

package/dist/scope-observability.js

@@ -2,6 +2,7 @@ import { ADMIN_SCOPES, BUNDLE_CATALOG } from './scope-catalog.js';
 import { BASE_SCOPES, resolveScopesForAccount } from './auth.js';
 import { readToken } from './token-store.js';
 import { reauthHint } from './reauth-hint.js';
+import { hints } from './hint-provider.js';
 // Reverse index scope -> bundles offering it, narrowest bundle first (fewest
 // scopes) so the remediation names the smallest grant. BASE_SCOPES map to the
 // pseudo-bundle "base" (outside a profile only via includesBase:false).
@@ -72,40 +73,54 @@ export function classifyMethodScopes(alternatives, granted, profile) {
  */
 export function scopeHint(scope, c, alias) {
     switch (c.state) {
-        case 'requestable_not_granted':
+        case 'requestable_not_granted': {
+            const rendered = hints()?.render({ kind: 'scope_not_granted', account: alias, scope });
             return {
-                hint: `Scope ${scope} is in ${alias}'s profile but not granted (you unchecked it at consent). ` +
-                    reauthHint(alias),
-                retriable: true,
+                hint: rendered?.hint ??
+                    (`Scope ${scope} is in ${alias}'s profile but not granted (you unchecked it at consent). ` +
+                        reauthHint(alias)),
+                // The ONE kind whose retriable the host may flip (Decision 3): the
+                // owner keeps true, a multi-tenant host may report false because the
+                // fix needs the user in a browser.
+                retriable: rendered?.retriable ?? true,
             };
+        }
         case 'not_requestable':
             if (c.reason === 'add_bundle') {
                 // "base" is a pseudo-bundle (BASE_SCOPES excluded by includesBase:
                 // false), NOT a catalog key — telling users to add it to bundles[]
                 // would fail boot with E_UNKNOWN_BUNDLE.
                 if (c.bundle === 'base') {
+                    const rendered = hints()?.render({ kind: 'scope_base_excluded', account: alias, scope });
                     return {
-                        hint: `Scope ${scope} is a base scope excluded by "includesBase": false in ${alias}'s profile. ` +
-                            `Set includesBase back to true (or remove it) in config.json, then npx mcp-google-multi auth --account ${alias}`,
+                        hint: rendered?.hint ??
+                            (`Scope ${scope} is a base scope excluded by "includesBase": false in ${alias}'s profile. ` +
+                                `Set includesBase back to true (or remove it) in config.json, then npx mcp-google-multi auth --account ${alias}`),
                         retriable: false,
                     };
                 }
+                const rendered = hints()?.render({ kind: 'scope_needs_bundle', account: alias, scope, bundle: c.bundle });
                 return {
-                    hint: `Scope ${scope} needs the "${c.bundle}" bundle, which is not in ${alias}'s profile. ` +
-                        `Add it: set ${alias}'s profile bundles to include "${c.bundle}" in config.json, then npx mcp-google-multi auth --account ${alias}`,
+                    hint: rendered?.hint ??
+                        (`Scope ${scope} needs the "${c.bundle}" bundle, which is not in ${alias}'s profile. ` +
+                            `Add it: set ${alias}'s profile bundles to include "${c.bundle}" in config.json, then npx mcp-google-multi auth --account ${alias}`),
                     retriable: false,
                 };
             }
             if (c.reason === 'account_type') {
+                const rendered = hints()?.render({ kind: 'scope_account_type', account: alias, scope });
                 return {
-                    hint: `Scope ${scope} requires a Google Workspace account; ${alias} is a personal account and will 403. Use a Workspace alias. Do not retry.`,
+                    hint: rendered?.hint ?? `Scope ${scope} requires a Google Workspace account; ${alias} is a personal account and will 403. Use a Workspace alias. Do not retry.`,
+                    retriable: false,
+                };
+            }
+            {
+                const rendered = hints()?.render({ kind: 'scope_unknown_scope', scope });
+                return {
+                    hint: rendered?.hint ?? `Scope ${scope} is not offered by this server (no bundle grants it). Not requestable. Do not retry.`,
                     retriable: false,
                 };
             }
-            return {
-                hint: `Scope ${scope} is not offered by this server (no bundle grants it). Not requestable. Do not retry.`,
-                retriable: false,
-            };
         default:
             return { hint: '', retriable: true };
     }

package/dist/services.js

@@ -18,6 +18,7 @@ import { getToolsets, toolsetEnabled } from './toolsets.js';
 import { GENERATED_SERVICES } from './tools/generated/index.js';
 import { suggestKeys } from './arg-strict.js';
 import { sliceClean } from './trim.js';
+import { hints } from './hint-provider.js';
 export const SERVICES = [
     { name: 'gmail', register: registerGmailTools },
     { name: 'drive', register: registerDriveTools },
@@ -73,16 +74,30 @@ export function unknownToolMessage(registry, rawName) {
     const service = serviceOf(name);
     const known = SERVICES.some((s) => s.name === service) || GENERATED_SERVICES.some((s) => s.name === service);
     if (known && !registry.services().includes(service)) {
+        const aliases = registry.accountSet().aliases;
         if (!toolsetEnabled(getToolsets(), service)) {
-            return `Tool ${name} not found: the "${service}" service is turned off in this deployment (GOOGLE_TOOLSETS).`;
+            const rendered = hints()?.render({ kind: 'service_not_enabled', tool: name, service, aliases, admin: false, toolsetOff: true, awaitingRestart: false });
+            return rendered?.hint ?? `Tool ${name} not found: the "${service}" service is turned off in this deployment (GOOGLE_TOOLSETS).`;
         }
         if (servicesAwaitingRestart(registry).includes(service)) {
-            return `Tool ${name} not found: the "${service}" service was enabled after this server started, and tools register at startup. Restart the server to use them. Until then, google_api_call can reach the same API.`;
+            const rendered = hints()?.render({ kind: 'service_not_enabled', tool: name, service, aliases, admin: false, toolsetOff: false, awaitingRestart: true });
+            return rendered?.hint ?? `Tool ${name} not found: the "${service}" service was enabled after this server started, and tools register at startup. Restart the server to use them. Until then, google_api_call can reach the same API.`;
         }
-        const hint = service === 'admin'
+        const isAdmin = service === 'admin';
+        const hint = isAdmin
             ? 'set admin on an account/profile (or GOOGLE_ADMIN_ACCOUNTS), then re-auth'
             : (GENERATED_GATES[service]?.hint ?? `add "${service}" to an account's scope profile (or legacy GOOGLE_OPTIONAL_SCOPES), then re-auth`);
-        return `Tool ${name} not found: the "${service}" service is not enabled in this deployment. To enable it, ${hint}. Until then, google_api_call can reach the same API.`;
+        const rendered = hints()?.render({
+            kind: 'service_not_enabled',
+            tool: name,
+            service,
+            bundle: isAdmin ? undefined : service,
+            aliases,
+            admin: isAdmin,
+            toolsetOff: false,
+            awaitingRestart: false,
+        });
+        return rendered?.hint ?? `Tool ${name} not found: the "${service}" service is not enabled in this deployment. To enable it, ${hint}. Until then, google_api_call can reach the same API.`;
     }
     const near = suggestKeys(rawName, registry.toolNames(), 3);
     if (near.length > 0)

package/dist/tools/_errors.d.ts

@@ -6,6 +6,9 @@ import type { Account } from '../accounts.js';
 export interface ServiceHints {
     scope?: string;
     resource?: string;
+    /** The scope bundle the scope hint is about, when known; carried through to
+     * a host-supplied provider so it can name the bundle in-band. */
+    bundle?: string;
 }
 export interface ErrorEnvelope {
     error: string;

package/dist/tools/_errors.js

@@ -1,5 +1,6 @@
 import { reauthHint } from '../reauth-hint.js';
 import { sliceClean, sliceEncoded } from '../trim.js';
+import { hints as hintProvider } from '../hint-provider.js';
 const MAX_ERROR_MESSAGE_CHARS = 1000;
 const MAX_ERROR_ENVELOPE_CHARS = 4000;
 const MAX_BODY_PARSE_CHARS = 64_000;
@@ -175,10 +176,11 @@ function rateLimited(error, message, account, reason) {
         };
     }
     if (reason === 'dailyLimitExceeded') {
+        const rendered = hintProvider()?.render({ kind: 'daily_quota' });
         return {
             error: 'rate_limited',
             message,
-            hint: 'A per-day project quota, not a burst limit: it resets at midnight Pacific. Reduce call volume or raise the quota in the Cloud Console; a tight retry loop will not clear it.',
+            hint: rendered?.hint ?? 'A per-day project quota, not a burst limit: it resets at midnight Pacific. Reduce call volume or raise the quota in the Cloud Console; a tight retry loop will not clear it.',
             retriable: true,
             account,
         };
@@ -222,21 +224,24 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
         .filter(Boolean)
         .join(' ');
     if ((status === 400 || status === 401) && /invalid_grant/i.test(grantHaystack)) {
+        const rendered = hintProvider()?.render({ kind: 'dead_refresh_token', account });
         return {
             error: 'reauth_required',
             message,
-            hint: `Refresh token for "${account}" is dead (often the 7-day Testing-mode trap). ` +
-                'Set Publishing status to In production at https://console.cloud.google.com/auth/audience, ' +
-                `then ${reauthHint(account)}`,
+            hint: rendered?.hint ??
+                (`Refresh token for "${account}" is dead (often the 7-day Testing-mode trap). ` +
+                    'Set Publishing status to In production at https://console.cloud.google.com/auth/audience, ' +
+                    `then ${reauthHint(account)}`),
             retriable: false,
             account,
         };
     }
     if (status === 401) {
+        const rendered = hintProvider()?.render({ kind: 'reauth', account });
         return {
             error: 'auth_required',
             message: `Authentication failed for account "${account}".`,
-            hint: reauthHint(account),
+            hint: rendered?.hint ?? reauthHint(account),
             retriable: false,
             account,
         };
@@ -252,7 +257,14 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
             reason === 'SERVICE_DISABLED' ||
             /has not been used in project|accessNotConfigured|SERVICE_DISABLED|it is disabled/i.test(message);
         if (notEnabled) {
-            return { error: 'api_not_enabled', message, hint: enableHint(info, message), retriable: false, account };
+            const rendered = hintProvider()?.render({
+                kind: 'api_not_enabled',
+                api: disabledApiId(message) ?? undefined,
+                service: info?.metadata?.service,
+                project: info?.metadata?.consumer?.replace(/^projects\//, ''),
+                googleMessage: message,
+            });
+            return { error: 'api_not_enabled', message, hint: rendered?.hint ?? enableHint(info, message), retriable: false, account };
         }
         // The scope hint fires ONLY on the machine-readable token. A coarse AIP
         // status of PERMISSION_DENIED is equally true of a resource denial, and
@@ -262,10 +274,13 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
             /\bACCESS_TOKEN_SCOPE_INSUFFICIENT\b/.test(message);
         if (scopeIssue) {
             const enriched = scopeContext?.() ?? null;
+            const fallback = enriched
+                ? null
+                : hintProvider()?.render({ kind: 'scope_unknown', account, serviceText: hints.scope, bundle: hints.bundle });
             return {
                 error: 'insufficient_scope',
                 message,
-                hint: enriched?.hint ?? hints.scope ?? `Re-auth "${account}" with the scope this operation needs. ${reauthHint(account)}`,
+                hint: enriched?.hint ?? fallback?.hint ?? hints.scope ?? `Re-auth "${account}" with the scope this operation needs. ${reauthHint(account)}`,
                 retriable: enriched?.retriable ?? false,
                 account,
             };
@@ -274,7 +289,8 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
             return { error: 'forbidden', message, hint: `Drive storage for "${account}" is full. Free space or use another account; retrying will not help.`, retriable: false, account };
         }
         if (reason === 'CONSUMER_SUSPENDED' || reason === 'accountSuspended') {
-            return { error: 'forbidden', message, hint: `Google has suspended the project or the account behind "${account}". Check the Cloud Console notifications; no change to the request will fix this.`, retriable: false, account };
+            const rendered = hintProvider()?.render({ kind: 'project_suspended', account });
+            return { error: 'forbidden', message, hint: rendered?.hint ?? `Google has suspended the project or the account behind "${account}". Check the Cloud Console notifications; no change to the request will fix this.`, retriable: false, account };
         }
         if (reason === 'domainPolicy' || reason === 'ORG_RESTRICTION_VIOLATION') {
             return { error: 'forbidden', message, hint: `A Workspace admin policy blocks this operation for the domain of "${account}". A super-admin has to allow the app or the feature; re-auth will not change it.`, retriable: false, account };
@@ -289,10 +305,11 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
         };
     }
     if (status === 400 && /invalid[_ ]scope/i.test(message)) {
+        const rendered = hintProvider()?.render({ kind: 'invalid_scope', 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.',
+            hint: rendered?.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,
         };
@@ -335,13 +352,15 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
         // The server's own preconditions, tagged at the throw site in client.ts.
         // Untagged they reached the floor and were reported as Google failures.
         if (error?.code === 'E_NO_TOKEN') {
-            return { error: 'auth_required', message, hint: reauthHint(account), retriable: false, account };
+            const rendered = hintProvider()?.render({ kind: 'reauth', account });
+            return { error: 'auth_required', message, hint: rendered?.hint ?? reauthHint(account), retriable: false, account };
         }
         if (error?.code === 'E_NO_OAUTH_CLIENT') {
+            const rendered = hintProvider()?.render({ kind: 'no_oauth_client' });
             return {
                 error: 'invalid_client',
                 message,
-                hint: 'Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET (see docs/google-cloud-setup.md), then restart the server.',
+                hint: rendered?.hint ?? 'Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET (see docs/google-cloud-setup.md), then restart the server.',
                 retriable: false,
                 account,
             };
@@ -357,23 +376,30 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
         }
         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}"` : '';
+            const p = typeof error?.path === 'string' ? error.path : undefined;
+            const rendered = hintProvider()?.render({ kind: 'local_path', code: fsCode, path: p });
             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.',
+                message: rendered?.message ?? `Cannot access local path${p ? ` "${p}"` : ''}: ${fsCode}`,
+                hint: rendered?.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) {
+            const rendered = hintProvider()?.render({ kind: 'network_error', code: netCode });
             return {
                 error: 'network_error',
                 message: message.includes(netCode) ? message : message.endsWith('reason: ') ? `${message}${netCode}` : `${message} (${netCode})`,
-                hint: `Network failure (${netCode}) before reaching Google - not an auth or API problem. Usually transient: retry. ` +
-                    'If it persists on a high-latency or broken-IPv6 link, raise the happy-eyeballs budget: NODE_OPTIONS=--network-family-autoselection-attempt-timeout=4000 (server default 2000ms), and check connectivity with curl.',
+                hint: rendered?.hint ??
+                    (`Network failure (${netCode}) before reaching Google - not an auth or API problem. Usually transient: retry. ` +
+                        'If it persists on a high-latency or broken-IPv6 link, raise the happy-eyeballs budget: NODE_OPTIONS=--network-family-autoselection-attempt-timeout=4000 (server default 2000ms), and check connectivity with curl.'),
+                // Not an override site (C5 is the only kind whose retriable the host
+                // may flip): a multi-tenant host keeps core's retriable codes for
+                // network_error.
                 retriable: RETRIABLE_NET_CODES.has(netCode),
                 account,
             };
@@ -392,13 +418,16 @@ export function mapGoogleError(error, account, serviceHints, scopeContext) {
             account,
         };
     }
-    return {
-        error: 'internal',
-        message,
-        hint: 'This failed inside the MCP server, before any request was sent. The message above is the signal: it is most often a configuration problem such as a missing key or credential. Retrying the same call will fail the same way.',
-        retriable: false,
-        account,
-    };
+    {
+        const rendered = hintProvider()?.render({ kind: 'internal', account });
+        return {
+            error: 'internal',
+            message: rendered?.message ?? message,
+            hint: rendered?.hint ?? 'This failed inside the MCP server, before any request was sent. The message above is the signal: it is most often a configuration problem such as a missing key or credential. Retrying the same call will fail the same way.',
+            retriable: false,
+            account,
+        };
+    }
 }
 /** Bound the SERIALIZED envelope, not just the message: an authored hint can
  * be long too, and the error path had no cap at all before this. */

package/dist/tools/accounts-tool.js

@@ -4,6 +4,7 @@ import { getAccountSet, refreshAccountSetIfStale } from '../accounts.js';
 import { buildScopesReport } from '../scope-observability.js';
 import { getAdminAccounts, resolveScopesForAccount } from '../auth.js';
 import { hasToken, readToken } from '../token-store.js';
+import { hints } from '../hint-provider.js';
 /** Health deps over one context's token store (and, optionally, its account
  * view); the module-level functions are the single owner's store. */
 export function accountHealthDepsFor(store, accounts) {
@@ -37,13 +38,17 @@ export function deriveAccountHealth(alias, deps = DEFAULT_DEPS) {
     const noScopes = buildScopesReport(new Set(), profileSet, registered);
     if (!deps.hasToken(alias)) {
         const legacy = deps.fileExists(config.tokenPath);
+        const rendered = legacy
+            ? hints()?.render({ kind: 'legacy_plaintext_token', account: alias })
+            : hints()?.render({ kind: 'reauth', account: alias });
         return {
             ...base,
             token: {
                 status: 'missing',
-                hint: legacy
-                    ? 'Plaintext token.json found — run: npx mcp-google-multi migrate-tokens'
-                    : reauthHint(alias),
+                hint: rendered?.hint ??
+                    (legacy
+                        ? 'Plaintext token.json found — run: npx mcp-google-multi migrate-tokens'
+                        : reauthHint(alias)),
             },
             scopes: noScopes,
         };
@@ -53,9 +58,10 @@ export function deriveAccountHealth(alias, deps = DEFAULT_DEPS) {
         token = deps.readToken(alias);
     }
     catch {
+        const rendered = hints()?.render({ kind: 'token_unreadable', account: alias });
         return {
             ...base,
-            token: { status: 'decrypt_error', hint: 'Wrong MASTER_KEY or corrupt token file — re-auth or restore the key.' },
+            token: { status: 'decrypt_error', hint: rendered?.hint ?? 'Wrong MASTER_KEY or corrupt token file — re-auth or restore the key.' },
             scopes: noScopes,
         };
     }
@@ -77,9 +83,9 @@ export function deriveAccountHealth(alias, deps = DEFAULT_DEPS) {
             status,
             expiryDate: expiry !== undefined ? new Date(expiry).toISOString() : undefined,
             hint: status === 'needs_reauth'
-                ? reauthHint(alias)
+                ? (hints()?.render({ kind: 'reauth', account: alias })?.hint ?? reauthHint(alias))
                 : missing.length > 0
-                    ? 'Re-auth to grant the missing scopes'
+                    ? (hints()?.render({ kind: 'scopes_missing', account: alias })?.hint ?? 'Re-auth to grant the missing scopes')
                     : undefined,
         },
         scopes: report,

package/dist/tools/admin.d.ts

@@ -1,3 +1,11 @@
 import type { ToolRegistry } from '../registry.js';
+import type { Account } from '../accounts.js';
 import { type CuratedToolDeps } from '../client.js';
 export declare function registerAdminTools(server: ToolRegistry, deps?: CuratedToolDeps): void;
+export declare function handleAdminError(error: any, account: Account): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};

package/dist/tools/admin.js

@@ -227,7 +227,7 @@ export function registerAdminTools(server, deps = {}) {
         }
     });
 }
-function handleAdminError(error, account) {
+export function handleAdminError(error, account) {
     const admin = 'Admin tools require Workspace super-admin privileges AND the account must be listed as an admin account (then re-authenticated). Personal Gmail accounts cannot use these endpoints.';
-    return handleGoogleApiError(error, account, { scope: admin, resource: admin });
+    return handleGoogleApiError(error, account, { scope: admin, resource: admin, bundle: 'admin' });
 }

package/dist/tools/analytics.d.ts

@@ -1,4 +1,5 @@
 import type { ToolRegistry } from '../registry.js';
+import type { Account } from '../accounts.js';
 import { type CuratedToolDeps } from '../client.js';
 /** Accepts "213025502" or "properties/213025502"; rejects the identifiers
  * people paste by mistake (G-… measurement IDs, UA-… properties) with a
@@ -17,3 +18,10 @@ export declare function shapeAccountSummaries(data: any): Record<string, unknown
  * the disambiguation the model needs without bloating a ~300-entry list. */
 export declare function shapeMetadata(data: any): Record<string, unknown>;
 export declare function registerAnalyticsTools(server: ToolRegistry, deps?: CuratedToolDeps): void;
+export declare function handleAnalyticsError(error: any, account: Account): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};

package/dist/tools/analytics.js

@@ -278,11 +278,12 @@ function invalidProperty(hint, account) {
         isError: true,
     };
 }
-function handleAnalyticsError(error, account) {
+export function handleAnalyticsError(error, account) {
     return handleGoogleApiError(error, account, {
         scope: 'Needs the "analytics" bundle on this account: add it to the scope profile, then re-auth.',
         // GA4 answers PERMISSION_DENIED for a property ACL too, and the old
         // combined hint sent those callers to re-auth a scope they already had.
         resource: 'The scope is not the problem: this Google account has no access to that GA4 property. Grant it in GA4 Admin > Property Access Management, or call analytics_account_summaries to see the properties it can read.',
+        bundle: 'analytics',
     });
 }

package/dist/tools/chat.d.ts

@@ -1,3 +1,11 @@
 import type { ToolRegistry } from '../registry.js';
+import type { Account } from '../accounts.js';
 import { type CuratedToolDeps } from '../client.js';
 export declare function registerChatTools(server: ToolRegistry, deps?: CuratedToolDeps): void;
+export declare function handleChatError(error: any, account: Account): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};

package/dist/tools/chat.js

@@ -121,9 +121,10 @@ export function registerChatTools(server, deps = {}) {
         }
     });
 }
-function handleChatError(error, account) {
+export function handleChatError(error, account) {
     return handleGoogleApiError(error, account, {
         scope: 'Chat tools require the optional "chat" scope bundle: add it to this account\'s scope profile, then re-auth.',
         resource: `Google Chat denied this space or message to "${account}". The scope is not the problem: check that the account is a member of the space, and that Chat is turned on for the Workspace.`,
+        bundle: 'chat',
     });
 }

package/dist/tools/forms.d.ts

@@ -1,3 +1,11 @@
 import type { ToolRegistry } from '../registry.js';
+import type { Account } from '../accounts.js';
 import { type CuratedToolDeps } from '../client.js';
 export declare function registerFormsTools(server: ToolRegistry, deps?: CuratedToolDeps): void;
+export declare function handleFormsError(error: any, account: Account): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};

package/dist/tools/forms.js

@@ -190,6 +190,9 @@ export function registerFormsTools(server, deps = {}) {
         }
     });
 }
-function handleFormsError(error, account) {
-    return handleGoogleApiError(error, account, "Forms tools require the optional \"forms\" scope bundle. Add GOOGLE_OPTIONAL_SCOPES=forms (or include \"forms\" in the list) and re-auth.");
+export function handleFormsError(error, account) {
+    return handleGoogleApiError(error, account, {
+        scope: "Forms tools require the optional \"forms\" scope bundle. Add GOOGLE_OPTIONAL_SCOPES=forms (or include \"forms\" in the list) and re-auth.",
+        bundle: 'forms',
+    });
 }

package/dist/tools/google-api.js

@@ -7,6 +7,7 @@ import { getToolsets, toolsetEnabled } from '../toolsets.js';
 import { editDistance, SUGGEST_MAX_INPUT } from '../scope-catalog.js';
 import { executeApiMethod, jsonResult } from '../executor.js';
 import { SUPPORTED_APIS, resolveApiAliases, cudFromMethod, loadMethodIndex, searchMethods, MAX_SEARCH_QUERY, } from '../discovery-client.js';
+import { hints } from '../hint-provider.js';
 // 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.
 const SERVICE_FOR_ALIAS = {
@@ -73,12 +74,15 @@ export function registerEscapeTools(registry, policy, deps = {}) {
     };
     const enabledApis = Object.keys(SUPPORTED_APIS).filter(apiEnabled);
     const apiList = enabledApis.join(', ');
-    const toolsetDisabled = (alias) => jsonResult({
-        error: 'toolset_disabled',
-        message: `API "${alias}" maps to service "${serviceForAlias(alias)}", which is excluded by GOOGLE_TOOLSETS.`,
-        hint: 'Add the service to GOOGLE_TOOLSETS (or unset it) to use this API.',
-        retriable: false,
-    }, true);
+    const toolsetDisabled = (alias) => {
+        const rendered = hints()?.render({ kind: 'toolset_disabled', api: alias, service: serviceForAlias(alias) });
+        return jsonResult({
+            error: 'toolset_disabled',
+            message: rendered?.message ?? `API "${alias}" maps to service "${serviceForAlias(alias)}", which is excluded by GOOGLE_TOOLSETS.`,
+            hint: rendered?.hint ?? 'Add the service to GOOGLE_TOOLSETS (or unset it) to use this API.',
+            retriable: false,
+        }, true);
+    };
     registry.registerMeta('google_api_search', {
         description: 'Search the Google API Discovery index for any Workspace REST method, including ones with no ' +
             'dedicated tool here. Returns method ids + parameters to invoke via google_api_call. ' +

package/dist/tools/meet.d.ts

@@ -1,3 +1,11 @@
 import type { ToolRegistry } from '../registry.js';
+import type { Account } from '../accounts.js';
 import { type CuratedToolDeps } from '../client.js';
 export declare function registerMeetTools(server: ToolRegistry, deps?: CuratedToolDeps): void;
+export declare function handleMeetError(error: any, account: Account): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};

package/dist/tools/meet.js

@@ -132,7 +132,7 @@ export function registerMeetTools(server, deps = {}) {
         }
     });
 }
-function handleMeetError(error, account) {
+export function handleMeetError(error, account) {
     return handleGoogleApiError(error, account, {
         scope: 'Meet needs the meetings.space.readonly scope and the Google Meet API enabled in Cloud Console. Confirm both for this account.',
         resource: `Meet denied this conference record to "${account}". Meet exposes records only to the organizer or a participant, so check which account hosted the meeting.`,

package/dist/tools/slides.d.ts

@@ -1,5 +1,13 @@
 import type { ToolRegistry } from '../registry.js';
+import type { Account } from '../accounts.js';
 import { type CuratedToolDeps } from '../client.js';
 export declare function registerSlidesTools(server: ToolRegistry, deps?: CuratedToolDeps): void;
 export declare function extractPageText(elements: Array<Record<string, any>> | undefined): string;
 export declare function summarizePresentation(p: Record<string, any>): Record<string, unknown>;
+export declare function handleSlidesError(error: any, account: Account): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};

package/dist/tools/slides.js

@@ -184,6 +184,9 @@ export function summarizePresentation(p) {
         hint: 'Pass full:true for the raw Presentation JSON, or slides_page_get for one slide.',
     };
 }
-function handleSlidesError(error, account) {
-    return handleGoogleApiError(error, account, "Slides tools require the optional \"slides\" scope bundle. Add GOOGLE_OPTIONAL_SCOPES=slides (or include \"slides\" in the list) and re-auth.");
+export function handleSlidesError(error, account) {
+    return handleGoogleApiError(error, account, {
+        scope: "Slides tools require the optional \"slides\" scope bundle. Add GOOGLE_OPTIONAL_SCOPES=slides (or include \"slides\" in the list) and re-auth.",
+        bundle: 'slides',
+    });
 }

package/dist/write-control.js

@@ -1,3 +1,4 @@
+import { hints } from './hint-provider.js';
 const PROFILES = ['read-only', 'safe-writes', 'full-writes'];
 /** The irreversible set (frozen, cc-write-control): real sends leave the
  * user's (or org's) identity unrecallably; permanent deletes bypass Trash.
@@ -155,10 +156,17 @@ export function writeDisabledResult(tool, policy, account) {
     // Recomputed rather than passed in: every call site has already run
     // isAllowed, and a hint that disagrees with the verdict is worse than none.
     const reason = denyReason(tool, policy) ?? { rule: 'profile', profile: policy.profile };
+    const rendered = hints()?.render({
+        kind: 'write_denied',
+        tool: { name: tool.name, service: tool.service, cud: tool.cud },
+        reason,
+        policy,
+    });
     const envelope = {
         error: 'write_disabled',
-        message: `"${tool.name}" (${tool.cud}) is disabled by the current write-control policy (profile: ${policy.profile}${policy.readOnly ? ', GOOGLE_READ_ONLY=true' : ''}).`,
-        hint: denyHint(tool, reason),
+        message: rendered?.message ??
+            `"${tool.name}" (${tool.cud}) is disabled by the current write-control policy (profile: ${policy.profile}${policy.readOnly ? ', GOOGLE_READ_ONLY=true' : ''}).`,
+        hint: rendered?.hint ?? denyHint(tool, reason),
         retriable: false,
         ...(account ? { account } : {}),
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.68",
+  "version": "6.0.0-alpha.69",
   "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",
@@ -32,6 +32,7 @@
     "./auth": "./dist/auth.js",
     "./usage-metrics": "./dist/usage-metrics.js",
     "./metrics-tap": "./dist/metrics-tap.js",
+    "./hint-provider": "./dist/hint-provider.js",
     "./package.json": "./package.json"
   },
   "files": [