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

package/README.md

@@ -12,45 +12,46 @@ The most complete **local Google Workspace MCP server**: Gmail, Drive, Calendar,
 
 ## Quick setup
 
-You don't need to know anything about MCP or OAuth — five steps, all copy-paste:
+New to all this? It's written for someone who just installed Claude Code and has never made an API key. Copy-paste each step; it says what you'll see. (Already technical? The [Configuration reference](./docs/configuration.md) is the terse version.)
 
-1. **Install [Node.js](https://nodejs.org) 22 or newer**, then install the server:
+1. **Install it.** Get [Node.js](https://nodejs.org) (the green "LTS" button, version 22 or newer), then run:
 
    ```bash
    npm install -g mcp-google-multi
    ```
 
-2. **Create your (free) Google app** so the server can sign in as you — one-time, ~2 minutes: follow [Google Cloud setup](./docs/google-cloud-setup.md). You come back with a **Client ID** and **Client Secret**.
+2. **Make your Google key** (the one manual part, a few minutes, because Google has no way to script it). Follow the step-by-step [Google Cloud setup](./docs/google-cloud-setup.md), or just ask Claude Code: *"walk me through creating a Google OAuth Desktop client for mcp-google-multi."* You finish with two values, a **Client ID** and a **Client Secret**. It's free and private to you.
 
-3. **Create a file named `.env`** in the folder you'll run from, and fill in your values:
+3. **Put them in a file.** In the folder you'll run from, make a file named `.env` and paste this, filling in your values:
 
    ```bash
    GOOGLE_CLIENT_ID=paste-your-client-id
    GOOGLE_CLIENT_SECRET=paste-your-client-secret
-   # name each Google account with a short alias:
-   GOOGLE_ACCOUNTS=work:you@company.com,personal:you@gmail.com
-   # encryption key for stored tokens — generate one with: openssl rand -base64 32
-   MASTER_KEY=paste-the-generated-key
+   # any short nickname, then your Gmail address:
+   GOOGLE_ACCOUNTS=me:you@gmail.com
    ```
 
-4. **Sign in each account** (a browser window opens; approve the permissions):
+   No encryption key to make: the server generates and stores one for you.
+
+4. **Sign in.** A browser opens; pick your account and click Allow:
 
    ```bash
-   mcp-google-multi auth --account work
-   mcp-google-multi auth --account personal
+   mcp-google-multi auth --account me
    ```
 
-5. **Connect it to Claude Code** (any MCP client works the same way):
+5. **Add it to Claude Code, then restart Claude Code:**
 
    ```bash
    claude mcp add google-multi -s user -- npx -y mcp-google-multi
    ```
 
-Restart your client and the tools appear. Check everything with `mcp-google-multi config check`.
+**Stuck at any point? Run `mcp-google-multi doctor`.** It inspects every part and prints the exact fix for anything wrong (a missing sign-in, a Google API you still need to switch on, and so on). Once it reads all-green, just talk to Claude: *"summarize my unread email."*
+
+*Got more than one Google account?* Add them together, like `GOOGLE_ACCOUNTS=me:you@gmail.com,work:you@company.com`, and run step 4 once per nickname.
 
-**Running it remotely?** To reach the server from [claude.ai](https://claude.ai) as a custom connector or from another machine, run it over HTTP — it ships its own OAuth 2.1 server, so no bearer tokens to paste. Follow [Remote HTTP setup](./docs/http-setup.md) (Cloudflare named tunnel, Docker, or one-click Render/Railway). Coming from v5? See the [v6 migration guide](./MIGRATION-v6.md).
+*On a server or from claude.ai?* Advanced path: [Remote / HTTP setup](./docs/http-setup.md). *Coming from v5?* [v6 migration guide](./MIGRATION-v6.md).
 
-**Go deeper:** [Configuration reference](./docs/configuration.md) · [What's covered](./COVERAGE.md) · [Features tour](./docs/features.md) · [Remote / HTTP setup](./docs/http-setup.md) · [Secrets in a vault](./docs/secrets.md) · [Migrating to v6](./MIGRATION-v6.md) · [Upgrading from v4](./docs/upgrading-v4.md) · [Security policy](./SECURITY.md) · [Roadmap](https://github.com/bakissation/mcp-google-multi/milestones)
+**Go deeper:** [Configuration reference](./docs/configuration.md) · [What's covered](./COVERAGE.md) · [Features tour](./docs/features.md) · [Remote / HTTP setup](./docs/http-setup.md) · [Secrets in a vault](./docs/secrets.md) · [Migrating to v6](./MIGRATION-v6.md) · [Security policy](./SECURITY.md) · [Roadmap](https://github.com/bakissation/mcp-google-multi/milestones)
 
 ## Maintainer & credits
 

package/dist/api-probe.d.ts

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

package/dist/api-probe.js

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

package/dist/doctor.js

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

package/dist/index.js

@@ -19,6 +19,8 @@ import { getToolsets, toolsetEnabled } from './toolsets.js';
 import { isAllowed, describePolicy } from './write-control.js';
 import { buildIdentityContext } from './identity.js';
 import { registerSetupPrompt } from './setup-prompt.js';
+import { applyNetTuning } from './net-tuning.js';
+applyNetTuning();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8'));
 function buildRegistry(server, ctx, mode) {

package/dist/net-tuning.d.ts

@@ -0,0 +1,8 @@
+export declare const CONNECT_ATTEMPT_TIMEOUT_MS = 2000;
+/** Pure decision: the timeout to apply, or null to leave Node's setting alone. */
+export declare function decideConnectAttemptTimeout(opts: {
+    execArgv: readonly string[];
+    nodeOptions: string | undefined;
+    current: number;
+}): number | null;
+export declare function applyNetTuning(): void;

package/dist/net-tuning.js

@@ -0,0 +1,25 @@
+import net from 'node:net';
+// Node's happy-eyeballs gives each address family 250ms per connect attempt on
+// every LTS line (raised to 500ms only in v25.2+); on high-latency or
+// broken-IPv6 links that aborts EVERY Google call while curl works. Raise the
+// process default unless the user tuned it themselves. Why: docs/internals.md.
+export const CONNECT_ATTEMPT_TIMEOUT_MS = 2000;
+const USER_FLAGS = ['--network-family-autoselection-attempt-timeout', '--no-network-family-autoselection'];
+/** Pure decision: the timeout to apply, or null to leave Node's setting alone. */
+export function decideConnectAttemptTimeout(opts) {
+    const userArgs = [...opts.execArgv, opts.nodeOptions ?? ''].join(' ');
+    if (USER_FLAGS.some((f) => userArgs.includes(f)))
+        return null;
+    if (opts.current >= CONNECT_ATTEMPT_TIMEOUT_MS)
+        return null;
+    return CONNECT_ATTEMPT_TIMEOUT_MS;
+}
+export function applyNetTuning() {
+    const timeout = decideConnectAttemptTimeout({
+        execArgv: process.execArgv,
+        nodeOptions: process.env.NODE_OPTIONS,
+        current: net.getDefaultAutoSelectFamilyAttemptTimeout(),
+    });
+    if (timeout !== null)
+        net.setDefaultAutoSelectFamilyAttemptTimeout(timeout);
+}

package/dist/tools/_errors.js

@@ -12,6 +12,28 @@ function reasonOf(error) {
 function messageOf(error) {
     return error?.response?.data?.error?.message ?? error?.message ?? String(error);
 }
+// Connect/DNS syscall codes. ENOTFOUND (no such name) is the one non-transient
+// member. node-fetch flattens the happy-eyeballs AggregateError to a bare code
+// with an empty message, so the code is the only surviving signal to surface.
+const RETRIABLE_NET_CODES = new Set([
+    'ETIMEDOUT', 'ECONNRESET', 'ECONNREFUSED', 'ECONNABORTED', 'ENETUNREACH',
+    'EHOSTUNREACH', 'EPIPE', 'EAI_AGAIN', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET',
+]);
+const NET_CODES = new Set([...RETRIABLE_NET_CODES, 'ENOTFOUND']);
+/** First known network code on the error or its cause chain (GaxiosError.cause
+ * -> FetchError; undici TypeError.cause -> AggregateError.errors). */
+function netCodeOf(error) {
+    for (let e = error, depth = 0; e && depth < 5; e = e.cause ?? e.error, depth++) {
+        if (typeof e.code === 'string' && NET_CODES.has(e.code))
+            return e.code;
+        if (Array.isArray(e.errors)) {
+            const sub = e.errors.find((x) => typeof x?.code === 'string' && NET_CODES.has(x.code));
+            if (sub)
+                return sub.code;
+        }
+    }
+    return undefined;
+}
 /** Console deep-link to enable one API (noob-proofing hint, B10). */
 function apiEnableLink(api) {
     return `https://console.cloud.google.com/apis/library/${api}.googleapis.com`;
@@ -114,6 +136,19 @@ export function mapGoogleError(error, account, forbiddenHint, scopeContext) {
     if (status !== undefined && status >= 500) {
         return { error: 'upstream_error', message, retriable: true, account };
     }
+    if (status === undefined) {
+        const netCode = netCodeOf(error);
+        if (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.',
+                retriable: RETRIABLE_NET_CODES.has(netCode),
+                account,
+            };
+        }
+    }
     return { error: 'upstream_error', message, retriable: false, account };
 }
 export function handleGoogleApiError(error, account, forbiddenHint, scopeContext) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.1",
+  "version": "6.0.0-alpha.3",
   "description": "Local MCP server for Google Workspace (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console, +Forms/Chat/Admin) across multiple accounts — OAuth-only, encrypted token storage, deny-by-default writes.",
   "type": "module",
   "license": "MIT",