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

package/dist/tools/account-wizard.js

@@ -0,0 +1,284 @@
+import { z } from 'zod';
+import { getAccountSet, invalidateAccountSet } from '../accounts.js';
+import { mutateConfigFile } from '../config-file.js';
+import { writeToken } from '../token-store.js';
+import { resolveScopesForAccount } from '../auth.js';
+import { BUNDLE_CATALOG, closestBundle, resolveBundleAliases } from '../scope-catalog.js';
+import { openUrl } from '../open-url.js';
+import { buildConsentClient, awaitLoopbackConsent, hasClientCredentials, } from '../oauth-consent.js';
+import { detectClients, buildServerEntry, renderInstruction, applyFileEntry, resolveMode, DEFAULT_SERVER_NAME, } from '../client-config.js';
+// B7: the elicitation-driven account_add / account_reauth wizard. It rebuilds
+// interactive account management on the mutable config.json registry so a
+// running server can add an account without the deployer editing env + running
+// a CLI. Google consent reuses the loopback flow (leg C); the HTTP-transport
+// consent path (${BASE}/authorize) is owned by the OAuth AS and lands with that
+// cluster — account_add over http is gated behind it.
+const ALIAS_RE = /^[a-zA-Z0-9_-]+$/;
+// The common optional bundles get their own checkbox (MCP elicitation has no
+// multi-select, so a boolean per bundle IS the checklist); the long tail stays
+// a comma-separated field for power users, and `allBundles` grants every one.
+const CHECKBOX_BUNDLES = ['forms', 'chat'];
+/** Every optional bundle (admin is granted via its own checkbox, not here). */
+export function allOptionalBundles() {
+    return Object.keys(BUNDLE_CATALOG).filter((n) => n !== 'admin');
+}
+/** elicitation/create form schema (flat primitives only, per the MCP spec). */
+export function addFormSchema() {
+    return {
+        type: 'object',
+        properties: {
+            alias: { type: 'string', title: 'Account alias', description: 'Short id, e.g. "work" (letters, digits, _ or -).' },
+            email: { type: 'string', title: 'Google email', description: 'The account\'s Google address (used as the login hint).' },
+            allBundles: { type: 'boolean', title: 'All optional scopes', description: 'Grant every optional bundle (biggest consent screen). Overrides the individual choices below.', default: false },
+            forms: { type: 'boolean', title: 'Google Forms', description: 'Build forms and read their responses.', default: false },
+            chat: { type: 'boolean', title: 'Google Chat', description: 'Read/send Chat messages and manage spaces (Workspace only).', default: false },
+            otherBundles: { type: 'string', title: 'Other scope bundles (comma-separated)', description: 'Advanced, optional: e.g. "slides,gmail_settings". See docs for the full list. Leave blank for base + the checkboxes above.' },
+            admin: { type: 'boolean', title: 'Grant Workspace admin scopes', description: 'Only for a Workspace super-admin account. Adds admin scopes.', default: false },
+        },
+        required: ['alias', 'email'],
+    };
+}
+/** Validate the collected form against the alias rules, dup check, and the
+ * bundle catalog. Pure (no I/O) for unit testing. */
+export function validateAddForm(input, existingAliases) {
+    const alias = (input.alias ?? '').trim();
+    const email = (input.email ?? '').trim();
+    if (!ALIAS_RE.test(alias)) {
+        return { ok: false, slug: 'E_VALIDATION', message: `Invalid alias "${alias}". Use letters, digits, "_" or "-".` };
+    }
+    if (existingAliases.includes(alias)) {
+        return { ok: false, slug: 'E_ALIAS_EXISTS', message: `Alias "${alias}" already exists; use account_reauth to re-authenticate it, or pick another name.` };
+    }
+    if (email === '') {
+        return { ok: false, slug: 'E_VALIDATION', message: 'Email is required (used as the Google login hint).' };
+    }
+    if (input.allBundles === true) {
+        // "All optional scopes" supersedes the individual picks.
+        return { ok: true, alias, email, bundles: allOptionalBundles(), admin: input.admin === true };
+    }
+    const picked = CHECKBOX_BUNDLES.filter((b) => input[b] === true);
+    const rawOther = (input.otherBundles ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+    const bundles = [...new Set(resolveBundleAliases([...picked, ...rawOther]))];
+    for (const b of bundles) {
+        if (b === 'admin') {
+            return { ok: false, slug: 'E_UNKNOWN_BUNDLE', message: '"admin" is not a bundle — use the admin checkbox instead.' };
+        }
+        if (!(b in BUNDLE_CATALOG)) {
+            const hint = closestBundle(b);
+            return { ok: false, slug: 'E_UNKNOWN_BUNDLE', message: `Unknown bundle "${b}"${hint ? ` — did you mean "${hint}"?` : ''}. Known: ${Object.keys(BUNDLE_CATALOG).filter((n) => n !== 'admin').join(', ')}.` };
+        }
+    }
+    return { ok: true, alias, email, bundles, admin: input.admin === true };
+}
+/** Scopes requested by the profile but NOT granted at consent (granular
+ * consent / unchecked bundles). Pure. */
+export function scopeGrantDiff(requested, grantedScope) {
+    const granted = new Set((grantedScope ?? '').split(' ').filter(Boolean));
+    return requested.filter((s) => !granted.has(s));
+}
+/** Persist a new account row (+ a per-account scope profile when bundles/admin
+ * were chosen) through the atomic registry mutation path (BR2). */
+function writeAccountRow(alias, email, bundles, admin) {
+    mutateConfigFile((current) => {
+        const next = { ...current, accounts: { ...(current.accounts ?? {}) } };
+        const row = { email };
+        if (bundles.length > 0) {
+            next.scopeProfiles = { ...(next.scopeProfiles ?? {}), [alias]: { bundles } };
+            row.scopeProfile = alias;
+        }
+        if (admin)
+            row.admin = true;
+        next.accounts[alias] = row;
+        return next;
+    });
+}
+function textResult(text, isError = false) {
+    return { content: [{ type: 'text', text }], ...(isError ? { isError: true } : {}) };
+}
+/** Run Google consent for `alias` and persist the token. Opens the browser via
+ * URL-mode elicitation when the client supports it, else server-side + prints
+ * the URL. Returns the granted-scope diff for the S4 report. */
+async function runConsent(server, alias) {
+    const { randomBytes } = await import('node:crypto');
+    const cfg = getAccountSet().configs[alias];
+    if (!cfg)
+        return { ok: false, text: `E_VALIDATION: account "${alias}" is not in the live registry (env-sourced accounts are not editable here).` };
+    const client = buildConsentClient();
+    const expectedState = randomBytes(32).toString('hex');
+    const scopes = resolveScopesForAccount(alias);
+    const url = client.generateAuthUrl({ access_type: 'offline', prompt: 'consent', scope: scopes, login_hint: cfg.email, state: expectedState });
+    // Start the loopback listener BEFORE opening the browser so it can't miss the
+    // redirect. Any startup error (e.g. port in use) surfaces synchronously.
+    const consent = awaitLoopbackConsent(client, expectedState);
+    const caps = server.server.getClientCapabilities?.();
+    let opened = false;
+    if (caps?.elicitation?.url) {
+        try {
+            const r = await server.server.elicitInput({ mode: 'url', message: `Authorize the "${alias}" Google account in your browser.`, url });
+            if (r.action !== 'accept') {
+                return { ok: false, text: 'confirmation_declined: consent was cancelled; the account row was kept but no token was stored (doctor will show it as "missing").' };
+            }
+            opened = true;
+        }
+        catch {
+            // fall through to server-side open
+        }
+    }
+    if (!opened) {
+        openUrl(url);
+    }
+    let tokens;
+    try {
+        tokens = await consent;
+    }
+    catch (e) {
+        return { ok: false, text: `${e.message}${opened ? '' : `\nOpen this URL to authorize:\n${url}`}` };
+    }
+    writeToken(alias, tokens);
+    return { ok: true, missing: scopeGrantDiff(scopes, typeof tokens.scope === 'string' ? tokens.scope : undefined) };
+}
+function s4Text(alias, missing) {
+    if (missing.length === 0)
+        return `✔ "${alias}" authenticated; all requested scopes granted. It is now usable without a restart.`;
+    return `⚠ "${alias}" authenticated, but ${missing.length} requested scope(s) were NOT granted (E_SCOPE_NOT_GRANTED) — you may have unchecked some on the consent screen. Re-run account_reauth to grant them. The account is usable for the granted scopes.`;
+}
+const REQUIRES_INTERACTION = { 'anthropic/requiresUserInteraction': true };
+export function registerAccountWizardTools(registry, server) {
+    // Registered as META (always-visible, like account_list) so onboarding tools
+    // are reachable in lazy mode without discover_all first; registerMeta still
+    // preserves the requiresUserInteraction clientMeta and skips the fan-out path.
+    const registerMeta = registry.registerMeta;
+    registerMeta('account_add', {
+        _meta: REQUIRES_INTERACTION,
+        annotations: { openWorldHint: true },
+        description: 'Add a new Google account interactively: collects alias/email/scope bundles via a form, writes the registry, and runs Google consent in the browser — no file editing or restart needed. Requires GOOGLE_CLIENT_ID/SECRET (run the `setup` prompt first if missing).',
+        inputSchema: {},
+    }, async () => {
+        try {
+            // Env-sourced registry: GOOGLE_ACCOUNTS is the exclusive source and
+            // config.json accounts are ignored, so a wizard add would be a phantom
+            // write. Refuse up front (BR-10) rather than write a row nothing reads.
+            if (process.env.GOOGLE_ACCOUNTS?.trim()) {
+                return textResult('E_ENV_ACCOUNTS_MODE: accounts are defined by the GOOGLE_ACCOUNTS environment variable, so new accounts cannot be added interactively (config.json is ignored while it is set). Either add the alias to GOOGLE_ACCOUNTS and run account_reauth, or run `mcp-google-multi migrate-config` to move accounts into config.json and unset GOOGLE_ACCOUNTS.', true);
+            }
+            if (!hasClientCredentials()) {
+                return textResult('E_CLIENT_CREDENTIALS_MISSING: GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET are not set. Run the `setup` prompt (/mcp__google-multi__setup) to create an OAuth client, then set them.', true);
+            }
+            const caps = server.server.getClientCapabilities?.();
+            if (!caps?.elicitation?.form) {
+                return textResult('This client does not support form elicitation. Add the account from the CLI instead: `npx mcp-google-multi account add --alias <alias> --email <email> [--profile a,b] [--admin]`.', true);
+            }
+            // S1: collect the registry row.
+            const form = await server.server.elicitInput({ message: 'Add a Google account', requestedSchema: addFormSchema() });
+            if (form.action !== 'accept') {
+                return textResult('confirmation_declined: no account was added.');
+            }
+            const validated = validateAddForm(form.content ?? {}, getAccountSet().aliases);
+            if (!validated.ok)
+                return textResult(`${validated.slug}: ${validated.message}`, true);
+            // S2: atomic write + make the alias callable without a restart (BR3).
+            writeAccountRow(validated.alias, validated.email, validated.bundles, validated.admin);
+            invalidateAccountSet();
+            // S3 + S4: consent + validate.
+            const consent = await runConsent(server, validated.alias);
+            if (!consent.ok)
+                return textResult(consent.text, true);
+            // B15: offer to register the server with another MCP client.
+            return textResult(`${s4Text(validated.alias, consent.missing)}\nTip: run account_write_config to register this server with another MCP client (Claude Desktop / Cursor / Claude Code).`);
+        }
+        catch (e) {
+            return textResult(`account_add failed: ${e.message}`, true);
+        }
+    });
+    registerMeta('account_reauth', {
+        _meta: REQUIRES_INTERACTION,
+        annotations: { openWorldHint: true },
+        description: 'Re-authenticate an existing Google account (recover a dead refresh token, or grant scopes after a profile change). Runs Google consent in the browser. Pass the account alias.',
+        inputSchema: {
+            // Plain string (NOT the account enum) so this never joins the
+            // multi-account fan-out path; validated against the registry below.
+            alias: z.string().describe('Existing account alias to re-authenticate'),
+        },
+    }, async (args) => {
+        try {
+            const alias = args.alias ?? '';
+            if (!hasClientCredentials()) {
+                return textResult('E_CLIENT_CREDENTIALS_MISSING: GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET are not set.', true);
+            }
+            if (!getAccountSet().aliases.includes(alias)) {
+                return textResult(`E_VALIDATION: unknown account "${alias}". Known: ${getAccountSet().aliases.join(', ')}. Use account_add for a new one.`, true);
+            }
+            const consent = await runConsent(server, alias);
+            if (!consent.ok)
+                return textResult(consent.text, true);
+            return textResult(s4Text(alias, consent.missing));
+        }
+        catch (e) {
+            return textResult(`account_reauth failed: ${e.message}`, true);
+        }
+    });
+    registerMeta('account_write_config', {
+        _meta: REQUIRES_INTERACTION,
+        annotations: { openWorldHint: true },
+        description: "Register this server with your MCP client (Claude Code / Claude Desktop / Cursor) so you don't hand-edit JSON. Default: returns the exact snippet/command to add. Pass write:true to write detected file-based configs in place (backs up first, never clobbers a malformed file). Secrets are never inlined.",
+        inputSchema: {
+            client: z.enum(['claude-code', 'claude-desktop', 'cursor']).optional().describe('Target one client; default = all detected'),
+            name: z.string().optional().describe('Server name in the client config (default mcp-google-multi)'),
+            write: z.boolean().optional().describe('Write file-based configs in place (default false = show the snippet only)'),
+        },
+    }, async (args) => {
+        try {
+            const a = (args ?? {});
+            const name = a.name?.trim() || DEFAULT_SERVER_NAME;
+            let mode = 'stdio';
+            let resourceUri;
+            try {
+                const { resolveHttpConfig } = await import('../http-config.js');
+                const m = resolveMode(resolveHttpConfig());
+                mode = m.mode;
+                resourceUri = m.resourceUri;
+            }
+            catch {
+                // stdio fallback on any config error
+            }
+            let entry;
+            try {
+                entry = buildServerEntry({ name, mode, resourceUri });
+            }
+            catch (e) {
+                return textResult(e.message, true);
+            }
+            let clients = detectClients();
+            if (a.client)
+                clients = clients.filter((c) => c.id === a.client);
+            const present = clients.filter((c) => c.present);
+            const targets = a.client ? clients : present.length ? present : clients;
+            const blocks = [];
+            for (const client of targets) {
+                const instr = renderInstruction(client, name, entry);
+                if (client.managed === 'cli') {
+                    blocks.push(`${client.label} — run:\n  ${instr.text}`);
+                }
+                else if (a.write) {
+                    const res = applyFileEntry(client, name, entry);
+                    blocks.push(res.ok
+                        ? `${client.label} — ${res.action} "${name}" in ${res.path}${res.backup ? ` (backup ${res.backup})` : ''}`
+                        : `${client.label} — ${res.message}\n${res.snippet ?? ''}`);
+                }
+                else {
+                    blocks.push(`${client.label} — add to ${instr.path}:\n${instr.text}`);
+                }
+            }
+            if (targets.length === 0) {
+                blocks.push(`No known MCP client detected. Add this under "mcpServers":\n${JSON.stringify({ [name]: entry }, null, 2)}`);
+            }
+            const note = mode === 'http'
+                ? `Remote HTTP (${resourceUri}); authentication is via the OAuth flow, so no secrets are stored in the client config.`
+                : 'stdio: secrets stay in ~/.config/mcp-google-multi/.env; the client entry carries none.';
+            return textResult(`${blocks.join('\n\n')}\n\n${note}`);
+        }
+        catch (e) {
+            return textResult(`account_write_config failed: ${e.message}`, true);
+        }
+    });
+}

package/dist/tools/accounts-tool.d.ts

@@ -1,4 +1,5 @@
 import type { ToolRegistry } from '../registry.js';
+import { type ScopesReport } from '../scope-observability.js';
 export interface AccountHealthDeps {
     hasToken: (alias: string) => boolean;
     readToken: (alias: string) => {
@@ -8,22 +9,24 @@ export interface AccountHealthDeps {
     } | null;
     fileExists: (p: string) => boolean;
     now: () => number;
+    /** Scopes required by registered tools — feeds doctor's tool-grained
+     * "registered but not requestable" view (B9). account_list stays compact:
+     * its report universe is profile ∪ granted only. */
+    registeredScopes?: () => string[];
 }
 export type TokenStatus = 'ok' | 'expired_refreshable' | 'needs_reauth' | 'missing' | 'decrypt_error';
 export interface AccountHealth {
     alias: string;
     email: string;
     admin: boolean;
+    source: 'config' | 'env';
+    sourceNote?: string;
     token: {
         status: TokenStatus;
         expiryDate?: string;
         hint?: string;
     };
-    scopes: {
-        configured: number;
-        granted: number;
-        missing: string[];
-    };
+    scopes: ScopesReport;
 }
 export declare function deriveAccountHealth(alias: string, deps?: AccountHealthDeps): AccountHealth;
 export declare function registerAccountTools(registry: ToolRegistry, deps?: AccountHealthDeps): void;

package/dist/tools/accounts-tool.js

@@ -1,5 +1,6 @@
 import * as fs from 'node:fs';
-import { ACCOUNTS, ACCOUNT_CONFIG } from '../accounts.js';
+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';
 const DEFAULT_DEPS = {
@@ -9,11 +10,23 @@ const DEFAULT_DEPS = {
     now: Date.now,
 };
 export function deriveAccountHealth(alias, deps = DEFAULT_DEPS) {
-    const config = ACCOUNT_CONFIG[alias];
+    const config = getAccountSet().configs[alias];
     const admin = getAdminAccounts().includes(alias);
     const configured = resolveScopesForAccount(alias);
-    const base = { alias, email: config.email, admin };
-    const noScopes = { configured: configured.length, granted: 0, missing: configured };
+    // BR-10: env-sourced accounts are not persisted in config.json, so the
+    // account wizard cannot edit them — the deployer edits env instead.
+    const base = {
+        alias,
+        email: config.email,
+        admin,
+        source: config.source,
+        ...(config.source === 'env'
+            ? { sourceNote: 'Defined by GOOGLE_ACCOUNTS env (not editable via config.json)' }
+            : {}),
+    };
+    const profileSet = new Set(configured);
+    const registered = deps.registeredScopes?.() ?? [];
+    const noScopes = buildScopesReport(new Set(), profileSet, registered);
     if (!deps.hasToken(alias)) {
         const legacy = deps.fileExists(config.tokenPath);
         return {
@@ -39,7 +52,8 @@ export function deriveAccountHealth(alias, deps = DEFAULT_DEPS) {
         };
     }
     const granted = typeof token?.scope === 'string' ? token.scope.split(' ').filter(Boolean) : [];
-    const missing = configured.filter((s) => !granted.includes(s));
+    const report = buildScopesReport(new Set(granted), profileSet, registered);
+    const missing = report.requestable;
     const expiry = typeof token?.expiry_date === 'number' ? token.expiry_date : undefined;
     const refreshable = typeof token?.refresh_token === 'string' && token.refresh_token.length > 0;
     let status;
@@ -60,21 +74,30 @@ export function deriveAccountHealth(alias, deps = DEFAULT_DEPS) {
                     ? 'Re-auth to grant the missing scopes'
                     : undefined,
         },
-        scopes: { configured: configured.length, granted: granted.length, missing },
+        scopes: report,
     };
 }
 export function registerAccountTools(registry, deps = DEFAULT_DEPS) {
-    registry.registerMeta('account_list', {
+    const registerMeta = registry.registerMeta;
+    registerMeta('account_list', {
         description: 'List the configured Google accounts: alias, email, admin flag, token health ' +
             '(ok / expired_refreshable / needs_reauth / missing / decrypt_error), and granted vs configured scopes. ' +
             'Use this to see which account aliases are available and healthy.',
         inputSchema: {},
-    }, async () => ({
-        content: [
-            {
-                type: 'text',
-                text: JSON.stringify({ accounts: ACCOUNTS.map((alias) => deriveAccountHealth(alias, deps)) }),
-            },
-        ],
-    }));
+        _meta: { 'anthropic/alwaysLoad': true },
+    }, async () => {
+        refreshAccountSetIfStale();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        defaultAccount: getAccountSet().defaultAccount ?? null,
+                        defaultAccountSource: getAccountSet().defaultAccountSource ?? null,
+                        accounts: getAccountSet().aliases.map((alias) => deriveAccountHealth(alias, deps)),
+                    }),
+                },
+            ],
+        };
+    });
 }

package/dist/tools/admin.js

@@ -1,10 +1,10 @@
 import { z } from 'zod';
 import { coerceBoolean } from './_coerce.js';
 import { admin as adminClient } from '@googleapis/admin';
-import { ACCOUNTS } from '../accounts.js';
+import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
-const accountEnum = z.enum(ACCOUNTS);
+const accountEnum = accountAliasSchema.optional();
 // Admin SDK requires Workspace super-admin (or delegated admin) on the account — personal @gmail.com accounts 403 on every endpoint.
 export function registerAdminTools(server) {
     // ─── Reports / audit log ───────────────────────────────────────────────

package/dist/tools/calendar.js

@@ -1,11 +1,11 @@
 import { z } from 'zod';
 import { coerceArray, coerceBoolean } from './_coerce.js';
 import { calendar as calendarClient } from '@googleapis/calendar';
-import { ACCOUNTS } from '../accounts.js';
+import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
 import { sliceClean } from '../trim.js';
-const accountEnum = z.enum(ACCOUNTS);
+const accountEnum = accountAliasSchema.optional();
 export function registerCalendarTools(server) {
     server.registerTool('calendar_list_calendars', {
         description: 'List all calendars for a Google account',

package/dist/tools/chat.js

@@ -1,10 +1,10 @@
 import { z } from 'zod';
 import { coerceJson } from './_coerce.js';
 import { chat as chatClient } from '@googleapis/chat';
-import { ACCOUNTS } from '../accounts.js';
+import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
-const accountEnum = z.enum(ACCOUNTS);
+const accountEnum = accountAliasSchema.optional();
 export function registerChatTools(server) {
     server.registerTool('chat_spaces_list', {
         description: 'List Google Chat spaces the user is a member of',

package/dist/tools/contacts.d.ts

@@ -1,2 +1,42 @@
 import type { ToolRegistry } from '../registry.js';
+export interface ResolveCandidate {
+    resourceName: string;
+    displayName: string;
+    source: 'contacts' | 'otherContacts';
+    emails: {
+        value: string;
+        type?: string;
+        primary?: boolean;
+    }[];
+    hasOrg: boolean;
+}
+/** Rank candidates and return one confident match, an explicit ambiguous list,
+ * or null. Candidates without any email are dropped first. Pure (no I/O) so the
+ * tie-break is unit-testable. */
+export declare function resolveContacts(candidates: ResolveCandidate[], name: string, maxCandidates: number): {
+    query: string;
+    resolved: null;
+    ambiguous?: undefined;
+    candidates?: undefined;
+} | {
+    query: string;
+    resolved: {
+        name: string;
+        email: string;
+        resourceName: string;
+        source: "contacts" | "otherContacts";
+    };
+    ambiguous?: undefined;
+    candidates?: undefined;
+} | {
+    query: string;
+    ambiguous: true;
+    candidates: {
+        name: string;
+        email: string;
+        resourceName: string;
+        source: "contacts" | "otherContacts";
+    }[];
+    resolved?: undefined;
+};
 export declare function registerContactsTools(server: ToolRegistry): void;

package/dist/tools/contacts.js

@@ -1,9 +1,10 @@
 import { z } from 'zod';
 import { people as peopleClient } from '@googleapis/people';
-import { ACCOUNTS } from '../accounts.js';
+import { accountAliasSchema } from '../accounts.js';
 import { getClient } from '../client.js';
+import { coerceBoolean } from './_coerce.js';
 import { handleGoogleApiError } from './_errors.js';
-const accountEnum = z.enum(ACCOUNTS);
+const accountEnum = accountAliasSchema.optional();
 const PERSON_FIELDS = 'names,emailAddresses,phoneNumbers,organizations,addresses,photos,memberships';
 function formatContact(person) {
     return {
@@ -31,6 +32,94 @@ function formatContact(person) {
         photo: person.photos?.[0]?.url ?? '',
     };
 }
+/** Accent-fold + lowercase for name comparison ("Rym" == "Rÿm"). */
+const foldName = (s) => s.normalize('NFD').replace(/\p{Diacritic}/gu, '').toLowerCase().trim();
+/** Canonical-address preference within one contact: explicit primary, then
+ * People type order work > home > other. */
+function emailRank(e) {
+    if (e.primary)
+        return 3;
+    const t = (e.type ?? '').toLowerCase();
+    if (t === 'work')
+        return 2;
+    if (t === 'home')
+        return 1;
+    return 0;
+}
+function pickEmail(c) {
+    return [...c.emails].sort((a, b) => emailRank(b) - emailRank(a))[0];
+}
+/** Deterministic rank tuple; higher wins, compared lexicographically so the
+ * first discriminating rule decides (A10 tie-break table). */
+function scoreTuple(c, foldedQuery) {
+    const exact = foldName(c.displayName) === foldedQuery ? 1 : 0; // 1. exact over prefix
+    const saved = c.source === 'contacts' ? 1 : 0; // 2. saved over other-contact
+    const bestEmail = c.emails.length ? Math.max(...c.emails.map(emailRank)) : 0; // 3. canonical address
+    const complete = c.hasOrg ? 1 : 0; // 4. fuller record
+    return [exact, saved, bestEmail, complete];
+}
+function cmpTuple(a, b) {
+    for (let i = 0; i < a.length; i++) {
+        if (a[i] !== b[i])
+            return b[i] - a[i];
+    }
+    return 0;
+}
+const projectCandidate = (c) => ({
+    name: c.displayName,
+    email: pickEmail(c).value,
+    resourceName: c.resourceName,
+    source: c.source,
+});
+/** Rank candidates and return one confident match, an explicit ambiguous list,
+ * or null. Candidates without any email are dropped first. Pure (no I/O) so the
+ * tie-break is unit-testable. */
+export function resolveContacts(candidates, name, maxCandidates) {
+    const withEmail = candidates.filter((c) => c.emails.some((e) => e.value));
+    if (withEmail.length === 0)
+        return { query: name, resolved: null };
+    const folded = foldName(name);
+    const ranked = withEmail
+        .map((c) => ({ c, t: scoreTuple(c, folded) }))
+        .sort((a, b) => cmpTuple(a.t, b.t));
+    const top = ranked[0];
+    const tiedTop = ranked.filter((r) => cmpTuple(r.t, top.t) === 0);
+    if (tiedTop.length === 1) {
+        return { query: name, resolved: projectCandidate(top.c) };
+    }
+    return {
+        query: name,
+        ambiguous: true,
+        candidates: tiedTop.slice(0, maxCandidates).map((r) => projectCandidate(r.c)),
+    };
+}
+/** People person -> ResolveCandidate projection. */
+function toCandidate(person, source) {
+    return {
+        resourceName: person?.resourceName ?? '',
+        displayName: person?.names?.[0]?.displayName ?? '',
+        source,
+        emails: (person?.emailAddresses ?? []).map((e) => ({
+            value: e.value ?? '',
+            type: e.type ?? '',
+            primary: e.metadata?.primary === true,
+        })),
+        hasOrg: (person?.organizations?.length ?? 0) > 0,
+    };
+}
+/** Merge saved + other contacts, deduped by resourceName (a saved match wins
+ * over the same person surfaced as an other-contact). */
+function dedupeCandidates(list) {
+    const byResource = new Map();
+    for (const c of list) {
+        const key = c.resourceName || `${c.source}:${c.displayName}:${c.emails[0]?.value ?? ''}`;
+        const existing = byResource.get(key);
+        if (!existing || (existing.source === 'otherContacts' && c.source === 'contacts')) {
+            byResource.set(key, c);
+        }
+    }
+    return [...byResource.values()];
+}
 export function registerContactsTools(server) {
     server.registerTool('contacts_search', {
         description: 'Search contacts by name, email, phone, or organization',
@@ -63,6 +152,50 @@ export function registerContactsTools(server) {
             return handleContactsError(error, account);
         }
     });
+    server.registerTool('contacts_resolve', {
+        annotations: { openWorldHint: true },
+        description: 'Resolve a free-text name/alias to ONE canonical email address (ranked + tie-broken), so you need not hand-expand transliteration OR-queries. Returns a single confident match, an explicit ambiguous candidate list, or null when nothing matches. For picking a recipient before gmail_send.',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias'),
+            name: z.string().min(1).describe('Free-text name or alias to resolve (e.g. "Rym")'),
+            maxCandidates: z.number().min(1).max(10).default(5).optional()
+                .describe('Max candidates to return when ambiguous (1-10, default: 5)'),
+            includeOtherContacts: coerceBoolean.optional()
+                .describe('Also search auto-saved "other contacts" (people you have emailed but not saved). Default true.'),
+        },
+    }, async ({ account, name, maxCandidates, includeOtherContacts }) => {
+        try {
+            const auth = await getClient(account);
+            const people = peopleClient({ version: 'v1', auth });
+            // Warmup request required by the People API before searchContacts returns hits.
+            await people.people.searchContacts({ query: '', readMask: 'names' });
+            const saved = await people.people.searchContacts({
+                query: name,
+                readMask: 'names,emailAddresses,organizations',
+            });
+            const candidates = (saved.data.results ?? [])
+                .map((r) => toCandidate(r.person, 'contacts'));
+            if (includeOtherContacts !== false) {
+                try {
+                    const other = await people.otherContacts.search({
+                        query: name,
+                        readMask: 'names,emailAddresses',
+                    });
+                    candidates.push(...(other.data.results ?? []).map((r) => toCandidate(r.person, 'otherContacts')));
+                }
+                catch {
+                    // otherContacts unavailable (scope/5xx): degrade to saved-contacts only.
+                }
+            }
+            const result = resolveContacts(dedupeCandidates(candidates), name, maxCandidates ?? 5);
+            return {
+                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (error) {
+            return handleContactsError(error, account);
+        }
+    });
     server.registerTool('contacts_get', {
         description: 'Get a single contact by resource name',
         inputSchema: {

package/dist/tools/docs.d.ts

@@ -1,4 +1,7 @@
 import type { ToolRegistry } from '../registry.js';
+export declare const DOCS_INSERT_CHUNK = 5000;
+export declare function splitInsertText(text: string, maxLen?: number): string[];
+export declare function buildInsertRequests(text: string, index?: number): any[];
 export declare function extractPlainTextInRange(body: any, start: number, end: number): string;
 export type HeadingLevel = 'title' | 1 | 2 | 3 | 4 | 5 | 6;
 export interface HeadingEntry {