mcp-google-multi 5.2.0-alpha.3 → 5.2.0-alpha.5

package/README.md

@@ -1,168 +1,61 @@
 # mcp-google-multi
 
-A **local** [MCP](https://modelcontextprotocol.io) server that gives Claude Code (and any MCP client) access to your **Google Workspace** — Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console (plus optional Slides, Forms, Chat, and Workspace Admin) — across **multiple Google accounts** at once.
+The most complete **local Google Workspace MCP server**: Gmail, Drive, Calendar, Sheets, Docs, Slides, Forms, Contacts, Tasks, Chat, Meet, Classroom, Vault, Admin and more — **every OAuth-reachable Workspace API method** as a tool, across **multiple Google accounts** at once, from Claude Code or any MCP client.
 
 [![npm](https://img.shields.io/npm/v/mcp-google-multi?label=npm&color=cb3837)](https://www.npmjs.com/package/mcp-google-multi)
 
-> Open-source and **funded by [IdeaCrafters](https://github.com/IdeaCraftersHQ)** — the studio that pays for its development and upkeep.
+- 🧰 **Exhaustive** — 871 tools across 28 services + an escape hatch for anything else → [COVERAGE.md](./COVERAGE.md)
+- 🔑 **Multi-account** — drive any number of Google accounts by alias, or fan one call out across all of them
+- 🔒 **Private by design** — your own OAuth app, tokens encrypted at rest (AES-256-GCM), writes deny-by-default, no telemetry, no metering — it talks only to Google
 
-- 🔑 **Multi-account** — drive any number of your Google accounts from one server, each by a short alias.
-- 🔒 **Secure by default** — refresh tokens **encrypted at rest** (AES-256-GCM); **writes are deny-by-default**; no telemetry — it talks only to Google.
-- 📦 **npm-first** — install and run with `npx`; everything configured through env vars.
-- 🧰 **~175 tools** across 13 services → full list in **[COVERAGE.md](./COVERAGE.md)**.
+## Quick setup
 
-> v5 is **local + user-OAuth only**. Service accounts and hosting (and the APIs they unlock) are on the [roadmap](https://github.com/bakissation/mcp-google-multi/milestones). **Upgrading from v4?** Jump to [Upgrading](#upgrading-from-v4).
+You don't need to know anything about MCP or OAuth — five steps, all copy-paste:
 
-## Quick start
+1. **Install [Node.js](https://nodejs.org) 20 or newer**, then install the server:
 
-You need **Node 20+**, a Google Cloud OAuth client (~2 min — [setup below](#google-cloud-setup)), and a random 32-byte key.
+   ```bash
+   npm install -g mcp-google-multi
+   ```
 
-```bash
-# 1) install
-npm i -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) put your config + creds in the environment (see "Configuration").
-#    Easiest for a quick try — export them, or drop a .env in your working dir:
-#    GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_ACCOUNTS, MASTER_KEY, GOOGLE_PROFILE
+3. **Create a file named `.env`** in the folder you'll run from, and fill in your values:
 
-# 3) authenticate each account (opens a browser; one-time per account)
-mcp-google-multi auth --account work
-mcp-google-multi auth --account personal
+   ```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
+   ```
 
-# 4) register with Claude Code
-claude mcp add google-multi -s user -- npx -y mcp-google-multi
-```
+4. **Sign in each account** (a browser window opens; approve the permissions):
 
-Restart your MCP client and the tools appear. Tokens are written **encrypted** to `~/.config/mcp-google-multi/tokens/` (override with `TOKEN_STORE_PATH`) — useless to anyone without your `MASTER_KEY`.
+   ```bash
+   mcp-google-multi auth --account work
+   mcp-google-multi auth --account personal
+   ```
 
-Generate a key: `openssl rand -base64 32`.
+5. **Connect it to Claude Code** (any MCP client works the same way):
 
-## Recommended: keep secrets in a vault (Infisical)
+   ```bash
+   claude mcp add google-multi -s user -- npx -y mcp-google-multi
+   ```
 
-A plaintext `.env` is fine to try it out, but for a daily driver, **don't leave `GOOGLE_CLIENT_SECRET` + `MASTER_KEY` on disk** — inject them at launch from a secrets manager. The server just reads `process.env` (it has no idea where the values come from), so wrap it with [Infisical](https://infisical.com):
+Restart your client and the tools appear. Check everything with `mcp-google-multi config check`.
 
-```bash
-#!/usr/bin/env bash
-# ~/.local/bin/mcp-google-multi-run  — chmod +x, then register this as the MCP command
-set -euo pipefail
-export INFISICAL_TOKEN="$(infisical login --method=universal-auth \
-  --client-id "$YOUR_CLIENT_ID" --client-secret "$YOUR_CLIENT_SECRET" --plain --silent)"
-exec infisical run --projectId <project> --env prod --path /mcp-google-multi \
-  -- npx -y mcp-google-multi
-```
+**Go deeper:** [Configuration reference](./docs/configuration.md) · [What's covered](./COVERAGE.md) · [Features tour](./docs/features.md) · [Secrets in a vault](./docs/secrets.md) · [Upgrading from v4](./docs/upgrading-v4.md) · [Security policy](./SECURITY.md) · [Roadmap](https://github.com/bakissation/mcp-google-multi/milestones)
 
-```bash
-claude mcp add google-multi -s user -- ~/.local/bin/mcp-google-multi-run
-```
-
-Now the only thing on disk is the **encrypted** token store. Pass the token via the `INFISICAL_TOKEN` env var (as above), **not** a `--token` flag, so it never shows up in `ps`. (Any secrets manager works — Doppler, Vault, 1Password CLI, etc. — the pattern is the same.)
-
-## Configuration
-
-| Env var | Required | Description |
-|---|---|---|
-| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | ✓ | OAuth **Desktop** client from Google Cloud |
-| `GOOGLE_ACCOUNTS` | ✓ | `alias:email,…` — e.g. `work:you@co.com,personal:you@gmail.com` |
-| `MASTER_KEY` | ✓ | base64 32-byte key that encrypts the token store (`openssl rand -base64 32`) |
-| `GOOGLE_PROFILE` | — | write policy: `read-only` (default) · `safe-writes` · `full-writes` |
-| `GOOGLE_READ_ONLY` | — | `true` = hard kill-switch for all writes |
-| `GOOGLE_WRITE_ALLOW` / `GOOGLE_WRITE_DENY` | — | glob overrides, e.g. `calendar:*`, `*:delete*` |
-| `GOOGLE_OPTIONAL_SCOPES` | — | extra bundles: `slides`, `forms`, `chat` |
-| `GOOGLE_ADMIN_ACCOUNTS` | — | aliases granted Workspace-admin scopes (the account's own super-admin OAuth) |
-| `GOOGLE_TOOLSETS` | — | `all` (default) or a CSV filter of: `gmail`, `drive`, `calendar`, `sheets`, `docs`, `contacts`, `searchconsole`, `tasks`, `meet`, `slides`, `forms`, `chat`, `admin` |
-| `TOKEN_STORE_PATH` | — | override the encrypted token dir (default: `~/.config/mcp-google-multi/tokens`) |
-| `DISCOVERY_CACHE_PATH` | — | override the Discovery-doc cache dir (default: `~/.config/mcp-google-multi/discovery`) |
-| `GOOGLE_TRIM` | — | `off` (or `0`/`false`/`no`) disables compact JSON serialization of tool responses |
-
-Inspect the resolved setup any time: `mcp-google-multi config check`.
-
-## Discover-first tools (tiny idle context)
-
-The server does **not** dump ~170 tool schemas into your model's context. At boot, `tools/list` exposes only one small `{service}_discover` tool per service (plus nothing else). Calling e.g. `drive_discover` returns that service's operation catalog (name, one-line summary, arguments, read/write class), reveals the operational tools, and emits `notifications/tools/list_changed` so the client re-fetches the list. An optional `query` argument filters the catalog.
-
-Hidden is a listing concept, not a security boundary: operational tools stay callable at all times (existing prompts that call tools directly keep working), and write-control + OAuth scopes remain the real enforcement. Use `GOOGLE_TOOLSETS` to switch entire services off — it is a filter only: listing `slides`/`forms`/`chat`/`admin` does not enable them without their `GOOGLE_OPTIONAL_SCOPES` / `GOOGLE_ADMIN_ACCOUNTS` gates.
-
-## Multi-account: fan out one call across accounts
-
-Every read tool's `account` argument also accepts `"*"` (all configured accounts) or a CSV subset (`"work,personal"`). The server runs the call once per account (bounded concurrency) and returns per-account results — one account failing never hides the others:
-
-```jsonc
-{ "results": [
-    { "account": "work", "ok": true, "data": { /* … */ } },
-    { "account": "personal", "ok": false, "error": { "error": "auth_required", /* … */ } }
-  ],
-  "partial": true }
-```
-
-Fan-out is **read-only by design** (write tools take exactly one account), and the three read tools that save files to disk (`drive_download`, `drive_export`, `gmail_download_attachment`) are excluded so parallel accounts can't clobber the same path. `account_list` shows what's configured: alias, email, token health (`ok` / `expired_refreshable` / `needs_reauth` / `missing` / `decrypt_error`), and granted-vs-configured scopes — without ever touching token values.
-
-`drive_transfer` copies or moves a file between two of your accounts: server-side share+copy when possible (the temporary read grant on the source is revoked right after; the copy gets a clean name, never "Copy of"), download+upload as the fallback. `move: true` trashes the source after a successful copy — that part is **delete-gated by write-control**, so `safe-writes` can copy but never move. Comments, revision history, and permissions don't transfer; if the fallback has to change the format (Drawings export as PNG), the result is flagged `lossy` and a requested move keeps the source intact. Native files over Google's 10MB export cap and binaries over 1GB can't take the fallback path.
-
-## Escape hatch: any Workspace REST method
-
-Two eager tools cover everything the curated set doesn't: `google_api_search` finds any method in Google's API Discovery index (including APIs with no dedicated tools here, like Drive Activity), and `google_api_call` invokes a method by its Discovery id (`drive.revisions.list`, `slides.presentations.create`, …) with path/query params and a JSON body. Calls run through your account's OAuth client and the **same write-control policy** as named tools: the read/create/update/delete class is derived from the method's HTTP verb and name (POST deletes like `batchDelete`/`clear` count as deletes), and policy globs/`GOOGLE_TOOLSETS` match the same service names as named tools (`people` counts as `contacts`, `admin_*` as `admin`; `driveactivity`/`drivelabels`/`groupssettings` have no named service and are always available).
-
-Discovery documents are fetched from Google on first use and cached on disk for 7 days (`DISCOVERY_CACHE_PATH`, default `~/.config/mcp-google-multi/discovery`); a stale cache is used when offline.
-
-## Lean responses by default
-
-Tool responses are serialized compactly (no pretty-print token tax; set `GOOGLE_TRIM=off` to restore pretty JSON), and the fat readers ship sensible caps with per-call escape valves. The caps are per-call controls (`full` / `maxChars`) and are NOT affected by `GOOGLE_TRIM`:
-
-- `drive_read` returns up to `maxChars` characters (default 100k) with `truncated`/`totalChars`/`offset` for paging — this also bounds Google Doc exports, which can reach 10MB. (Non-Google-native files over 2MB are still rejected with `too_large`, not paged.)
-- `gmail_read` / `gmail_read_thread` cap each message body at 50k chars (`bodyTruncated` + `bodyTotalChars` flags); pass `full: true` for the whole body.
-- `calendar_list_events` / `calendar_list_instances` trim descriptions to ~300 chars and drop empty/audit fields (`created`/`updated`) in list view; `calendar_get_event` always returns the full event.
-
-## Write-control (deny-by-default)
-
-Reads are never gated. **Every create/update/delete is off until you opt in** — pick a profile:
-
-| `GOOGLE_PROFILE` | Allows |
-|---|---|
-| `read-only` (default) | reads only |
-| `safe-writes` | create + update (deletes still blocked) |
-| `full-writes` | everything |
-
-`GOOGLE_READ_ONLY=true` overrides all. For fine control: `GOOGLE_WRITE_ALLOW="calendar:*, sheets:update*"` and `GOOGLE_WRITE_DENY="*:delete*"` (deny wins). `mcp-google-multi config check` prints the resolved policy and exactly which tools are enabled.
-
-## What's covered
-
-~175 tools across Gmail, Drive, Calendar, Sheets, Docs, Contacts, Search Console, Tasks, Meet, and (optional) Slides, Forms, Chat, Workspace Admin. **Full per-tool list → [COVERAGE.md](./COVERAGE.md).** Every tool takes an `account` argument matching one of your aliases.
-
-## Google Cloud setup
-
-1. [Google Cloud Console](https://console.cloud.google.com) → create or select a project.
-2. Enable the APIs you'll use: Gmail, Drive, Calendar, Sheets, Docs, People, Search Console, Tasks, Meet (+ Slides / Forms / Chat / Admin SDK if you enable those bundles).
-3. **APIs & Services → Credentials → Create Credentials → OAuth client ID → Desktop app**.
-4. Add the redirect URI `http://localhost:4242/oauth2callback`.
-5. Copy the **Client ID** + **Client Secret** into your environment.
-
-## Upgrading from v4
-
-v5 is a breaking change, but the migration is a one-time, ~2-minute step:
-
-1. Update: `npm i -g mcp-google-multi@latest` (or update your client config).
-2. Add **`MASTER_KEY`** to your environment (`openssl rand -base64 32`) — now required.
-3. Encrypt existing tokens: `mcp-google-multi migrate-tokens` (reads your old `tokens/<alias>/token.json` and encrypts them) — or just re-auth each account.
-4. Writes are now **deny-by-default** — set `GOOGLE_PROFILE=safe-writes` (or `full-writes`) to keep writing. (`GOOGLE_ALLOW_ADMIN_WRITES` is gone — replaced by write-control profiles.)
-
-## Security
-
-Your OAuth, your machine. Refresh tokens are **AES-256-GCM encrypted at rest** (decryptable only with your `MASTER_KEY`), writes are deny-by-default, and the server has **no telemetry** — it connects only to Google's APIs. Found a vulnerability? Report it privately — see [SECURITY.md](./SECURITY.md), never a public issue.
-
-## Roadmap
-
-Maintainer-led. Direction is tracked publicly as **[GitHub Milestones](https://github.com/bakissation/mcp-google-multi/milestones)** (exhaustive API coverage → service accounts + hosting in v6). Not accepting unsolicited feature PRs; bug reports are welcome.
-
-## Contributing
-
-See [CONTRIBUTING.md](./CONTRIBUTING.md) and the [Code of Conduct](./CODE_OF_CONDUCT.md). Security issues go to [SECURITY.md](./SECURITY.md), never a public issue.
-
-## Credits
+## Maintainer & credits
 
 Built and maintained by **Abdelbaki Berkati** — [berkati.xyz](https://berkati.xyz) · [@bakissation](https://github.com/bakissation). [Read the case study →](https://berkati.xyz/case-studies/mcp-google-multi/)
 
 Development is **funded by [IdeaCrafters](https://ideacrafters.com)** ([@IdeaCraftersHQ](https://github.com/IdeaCraftersHQ)) — the studio that pays for this OSS to exist.
 
+Thanks to contributors [@obatried](https://github.com/obatried), [@trevor-commits](https://github.com/trevor-commits), and [@mjreddy](https://github.com/mjreddy). The project is maintainer-led (roadmap on [Milestones](https://github.com/bakissation/mcp-google-multi/milestones); bug reports welcome, feature PRs by prior agreement — see [CONTRIBUTING.md](./CONTRIBUTING.md)). Security reports go to [SECURITY.md](./SECURITY.md), never a public issue.
+
 ## License
 
 [MIT](./LICENSE)

package/dist/index.js

@@ -5,21 +5,8 @@ import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { registerGmailTools } from './tools/gmail.js';
-import { registerDriveTools } from './tools/drive.js';
-import { registerCalendarTools } from './tools/calendar.js';
-import { registerSheetsTools } from './tools/sheets.js';
-import { registerDocsTools } from './tools/docs.js';
-import { registerContactsTools } from './tools/contacts.js';
-import { registerSearchConsoleTools } from './tools/searchconsole.js';
-import { registerTasksTools } from './tools/tasks.js';
-import { registerMeetTools } from './tools/meet.js';
-import { registerSlidesTools } from './tools/slides.js';
-import { registerFormsTools } from './tools/forms.js';
-import { registerChatTools } from './tools/chat.js';
-import { registerAdminTools } from './tools/admin.js';
-import { getOptionalBundles, getAdminAccounts } from './auth.js';
 import { GENERATED_SERVICES } from './tools/generated/index.js';
+import { GENERATED_GATES, SERVICES } from './services.js';
 import { ToolRegistry } from './registry.js';
 import { registerDiscoverTools } from './discover.js';
 import { registerEscapeTools } from './tools/google-api.js';
@@ -28,45 +15,6 @@ import { getToolsets, toolsetEnabled } from './toolsets.js';
 import { resolvePolicy, isAllowed, describePolicy } from './write-control.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8'));
-const SERVICES = [
-    { name: 'gmail', register: registerGmailTools },
-    { name: 'drive', register: registerDriveTools },
-    { name: 'calendar', register: registerCalendarTools },
-    { name: 'sheets', register: registerSheetsTools },
-    { name: 'docs', register: registerDocsTools },
-    { name: 'contacts', register: registerContactsTools },
-    { name: 'searchconsole', register: registerSearchConsoleTools },
-    { name: 'tasks', register: registerTasksTools },
-    { name: 'meet', register: registerMeetTools },
-    { name: 'slides', register: registerSlidesTools, enabled: () => new Set(getOptionalBundles()).has('slides') },
-    { name: 'forms', register: registerFormsTools, enabled: () => new Set(getOptionalBundles()).has('forms') },
-    { name: 'chat', register: registerChatTools, enabled: () => new Set(getOptionalBundles()).has('chat') },
-    { name: 'admin', register: registerAdminTools, enabled: () => getAdminAccounts().length > 0 },
-];
-// Opt-in gates for generated-only services whose scopes are not granted by
-// default; shared services (admin, forms, chat) reuse their curated gate below.
-// workspaceevents has no dedicated scope (subscriptions use the underlying
-// resource scopes), so it registers ungated.
-const bundleGate = (name) => ({
-    enabled: () => new Set(getOptionalBundles()).has(name),
-    hint: `add "${name}" to GOOGLE_OPTIONAL_SCOPES`,
-});
-const GENERATED_GATES = {
-    appsmarket: bundleGate('appsmarket'),
-    classroom: bundleGate('classroom'),
-    cloudidentity: bundleGate('cloudidentity'),
-    cloudsearch: bundleGate('cloudsearch'),
-    driveactivity: bundleGate('driveactivity'),
-    drivelabels: bundleGate('drivelabels'),
-    groupsmigration: bundleGate('groupsmigration'),
-    groupssettings: bundleGate('groupssettings'),
-    keep: bundleGate('keep'),
-    licensing: bundleGate('licensing'),
-    postmaster: bundleGate('postmaster'),
-    reseller: bundleGate('reseller'),
-    script: bundleGate('script'),
-    vault: bundleGate('vault'),
-};
 function buildRegistry(server, policy) {
     const registry = new ToolRegistry(server, policy);
     const toolsets = getToolsets();

package/dist/services.d.ts

@@ -0,0 +1,11 @@
+import type { ToolRegistry } from './registry.js';
+export interface ServiceEntry {
+    name: string;
+    register: (registry: ToolRegistry) => void;
+    enabled?: () => boolean;
+}
+export declare const SERVICES: ServiceEntry[];
+export declare const GENERATED_GATES: Record<string, {
+    enabled: () => boolean;
+    hint: string;
+}>;

package/dist/services.js

@@ -0,0 +1,53 @@
+import { registerGmailTools } from './tools/gmail.js';
+import { registerDriveTools } from './tools/drive.js';
+import { registerCalendarTools } from './tools/calendar.js';
+import { registerSheetsTools } from './tools/sheets.js';
+import { registerDocsTools } from './tools/docs.js';
+import { registerContactsTools } from './tools/contacts.js';
+import { registerSearchConsoleTools } from './tools/searchconsole.js';
+import { registerTasksTools } from './tools/tasks.js';
+import { registerMeetTools } from './tools/meet.js';
+import { registerSlidesTools } from './tools/slides.js';
+import { registerFormsTools } from './tools/forms.js';
+import { registerChatTools } from './tools/chat.js';
+import { registerAdminTools } from './tools/admin.js';
+import { getOptionalBundles, getAdminAccounts } from './auth.js';
+export const SERVICES = [
+    { name: 'gmail', register: registerGmailTools },
+    { name: 'drive', register: registerDriveTools },
+    { name: 'calendar', register: registerCalendarTools },
+    { name: 'sheets', register: registerSheetsTools },
+    { name: 'docs', register: registerDocsTools },
+    { name: 'contacts', register: registerContactsTools },
+    { name: 'searchconsole', register: registerSearchConsoleTools },
+    { name: 'tasks', register: registerTasksTools },
+    { name: 'meet', register: registerMeetTools },
+    { name: 'slides', register: registerSlidesTools, enabled: () => new Set(getOptionalBundles()).has('slides') },
+    { name: 'forms', register: registerFormsTools, enabled: () => new Set(getOptionalBundles()).has('forms') },
+    { name: 'chat', register: registerChatTools, enabled: () => new Set(getOptionalBundles()).has('chat') },
+    { name: 'admin', register: registerAdminTools, enabled: () => getAdminAccounts().length > 0 },
+];
+// Opt-in gates for generated-only services whose scopes are not granted by
+// default; shared services (admin, forms, chat) reuse their curated gate in
+// buildRegistry. workspaceevents has no dedicated scope (subscriptions use the
+// underlying resource scopes), so it registers ungated.
+const bundleGate = (name) => ({
+    enabled: () => new Set(getOptionalBundles()).has(name),
+    hint: `add "${name}" to GOOGLE_OPTIONAL_SCOPES`,
+});
+export const GENERATED_GATES = {
+    appsmarket: bundleGate('appsmarket'),
+    classroom: bundleGate('classroom'),
+    cloudidentity: bundleGate('cloudidentity'),
+    cloudsearch: bundleGate('cloudsearch'),
+    driveactivity: bundleGate('driveactivity'),
+    drivelabels: bundleGate('drivelabels'),
+    groupsmigration: bundleGate('groupsmigration'),
+    groupssettings: bundleGate('groupssettings'),
+    keep: bundleGate('keep'),
+    licensing: bundleGate('licensing'),
+    postmaster: bundleGate('postmaster'),
+    reseller: bundleGate('reseller'),
+    script: bundleGate('script'),
+    vault: bundleGate('vault'),
+};

package/dist/tools/docs.d.ts

@@ -1,4 +1,26 @@
 import type { ToolRegistry } from '../registry.js';
+export declare function extractPlainTextInRange(body: any, start: number, end: number): string;
+export type HeadingLevel = 'title' | 1 | 2 | 3 | 4 | 5 | 6;
+export interface HeadingEntry {
+    i: number;
+    level: HeadingLevel;
+    text: string;
+    startIndex: number;
+    endIndex: number;
+}
+export declare function buildHeadingIndex(body: any): HeadingEntry[];
+export type HeadingResolution = {
+    match: HeadingEntry;
+} | {
+    error: 'not_found' | 'ambiguous';
+    candidates: HeadingEntry[];
+};
+export declare function resolveHeading(headings: HeadingEntry[], query: string): HeadingResolution;
+export declare function findTab(tabs: any[] | undefined, tabId: string): any | undefined;
+export declare function listTabs(tabs: any[] | undefined): {
+    tabId: string;
+    title: string;
+}[];
 export declare function registerDocsTools(server: ToolRegistry): void;
 export declare function buildParagraphStyle(input: {
     namedStyleType?: string;

package/dist/tools/docs.js

@@ -4,29 +4,129 @@ import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
+import { capText } from '../trim.js';
 const accountEnum = z.enum(ACCOUNTS);
 function extractPlainText(body) {
+    return extractPlainTextInRange(body, 0, Infinity);
+}
+export function extractPlainTextInRange(body, start, end) {
     if (!body?.content)
         return '';
     let text = '';
     for (const element of body.content) {
+        const es = element.startIndex ?? 0;
+        const ee = element.endIndex ?? Infinity;
+        if (ee <= start || es >= end)
+            continue;
         if (element.paragraph) {
             for (const pe of element.paragraph.elements ?? []) {
-                if (pe.textRun?.content) {
-                    text += pe.textRun.content;
-                }
+                const run = pe.textRun?.content;
+                if (!run)
+                    continue;
+                const ps = pe.startIndex ?? es;
+                const from = Math.max(0, start - ps);
+                const to = Math.min(run.length, end - ps);
+                if (to > from)
+                    text += run.slice(from, to);
             }
         }
         else if (element.table) {
             for (const row of element.table.tableRows ?? []) {
                 for (const cell of row.tableCells ?? []) {
-                    text += extractPlainText(cell);
+                    text += extractPlainTextInRange(cell, start, end);
                 }
             }
         }
     }
     return text;
 }
+const HEADING_RANKS = {
+    TITLE: 0,
+    HEADING_1: 1,
+    HEADING_2: 2,
+    HEADING_3: 3,
+    HEADING_4: 4,
+    HEADING_5: 5,
+    HEADING_6: 6,
+};
+export function buildHeadingIndex(body) {
+    const found = [];
+    let docEnd = 0;
+    const walk = (b) => {
+        if (!b?.content)
+            return;
+        for (const element of b.content) {
+            if (typeof element.endIndex === 'number' && element.endIndex > docEnd)
+                docEnd = element.endIndex;
+            if (element.paragraph) {
+                const rank = HEADING_RANKS[element.paragraph.paragraphStyle?.namedStyleType ?? ''];
+                if (rank !== undefined) {
+                    let text = '';
+                    for (const pe of element.paragraph.elements ?? []) {
+                        if (pe.textRun?.content)
+                            text += pe.textRun.content;
+                    }
+                    found.push({ rank, text: text.trim(), startIndex: element.startIndex ?? 0 });
+                }
+            }
+            else if (element.table) {
+                for (const row of element.table.tableRows ?? []) {
+                    for (const cell of row.tableCells ?? [])
+                        walk(cell);
+                }
+            }
+        }
+    };
+    walk(body);
+    return found.map((h, i) => {
+        let endIndex = docEnd;
+        for (let j = i + 1; j < found.length; j++) {
+            if (found[j].rank <= h.rank) {
+                endIndex = found[j].startIndex;
+                break;
+            }
+        }
+        return {
+            i,
+            level: (h.rank === 0 ? 'title' : h.rank),
+            text: h.text,
+            startIndex: h.startIndex,
+            endIndex,
+        };
+    });
+}
+export function resolveHeading(headings, query) {
+    const q = query.trim().toLowerCase();
+    const exact = headings.filter((h) => h.text.toLowerCase() === q);
+    if (exact.length === 1)
+        return { match: exact[0] };
+    if (exact.length > 1)
+        return { error: 'ambiguous', candidates: exact };
+    const partial = headings.filter((h) => h.text.toLowerCase().includes(q));
+    if (partial.length === 1)
+        return { match: partial[0] };
+    if (partial.length > 1)
+        return { error: 'ambiguous', candidates: partial };
+    return { error: 'not_found', candidates: headings };
+}
+export function findTab(tabs, tabId) {
+    for (const tab of tabs ?? []) {
+        if (tab.tabProperties?.tabId === tabId)
+            return tab;
+        const nested = findTab(tab.childTabs, tabId);
+        if (nested)
+            return nested;
+    }
+    return undefined;
+}
+export function listTabs(tabs) {
+    const out = [];
+    for (const tab of tabs ?? []) {
+        out.push({ tabId: tab.tabProperties?.tabId ?? '', title: tab.tabProperties?.title ?? '' });
+        out.push(...listTabs(tab.childTabs));
+    }
+    return out;
+}
 export function registerDocsTools(server) {
     server.registerTool('docs_create', {
         description: 'Create a new Google Docs document',
@@ -90,22 +190,100 @@ export function registerDocsTools(server) {
         }
     });
     server.registerTool('docs_read', {
-        description: 'Read document content as plain text',
+        description: 'Read document content as plain text with a heading index (returns up to maxChars characters per call). Pass heading or headingIndex to read one section, tabId to read a specific tab.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             documentId: z.string().describe('Google Docs document ID'),
+            heading: z.string().optional()
+                .describe('Read only the section under this heading (case-insensitive; exact match first, then substring)'),
+            headingIndex: z.number().int().min(0).optional()
+                .describe('Read only the section at this position in the headings array (the `i` field)'),
+            tabId: z.string().optional()
+                .describe('Read a specific tab instead of the first tab'),
+            maxChars: z.number().min(1).max(2_000_000).default(50_000).optional()
+                .describe('Max characters of text to return (default: 50000)'),
+            offset: z.number().min(0).default(0).optional()
+                .describe('Character offset to continue a truncated read'),
         },
-    }, async ({ account, documentId }) => {
+    }, async ({ account, documentId, heading, headingIndex, tabId, maxChars, offset }) => {
         try {
+            if (heading !== undefined && headingIndex !== undefined) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({
+                                error: 'invalid_params',
+                                message: 'Provide either heading or headingIndex, not both',
+                            }, null, 2) }],
+                    isError: true,
+                };
+            }
             const auth = await getClient(account);
             const docs = google.docs({ version: 'v1', auth });
-            const res = await docs.documents.get({ documentId });
-            const text = extractPlainText(res.data.body);
+            const res = await docs.documents.get({
+                documentId,
+                ...(tabId !== undefined ? { includeTabsContent: true } : {}),
+            });
+            let body = res.data.body;
+            if (tabId !== undefined) {
+                const tab = findTab(res.data.tabs, tabId);
+                if (!tab) {
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({
+                                    error: 'not_found',
+                                    message: `Tab "${tabId}" not found in document ${documentId}`,
+                                    availableTabs: listTabs(res.data.tabs),
+                                }, null, 2) }],
+                        isError: true,
+                    };
+                }
+                body = tab.documentTab?.body;
+            }
+            const headings = buildHeadingIndex(body);
+            let section;
+            if (headingIndex !== undefined) {
+                section = headings[headingIndex];
+                if (!section) {
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({
+                                    error: 'invalid_params',
+                                    message: `headingIndex ${headingIndex} is out of range (document has ${headings.length} headings)`,
+                                    headings: headings.map(({ i, level, text }) => ({ i, level, text })),
+                                }, null, 2) }],
+                        isError: true,
+                    };
+                }
+            }
+            else if (heading !== undefined) {
+                const resolved = resolveHeading(headings, heading);
+                if ('error' in resolved) {
+                    return {
+                        content: [{ type: 'text', text: JSON.stringify({
+                                    error: resolved.error === 'ambiguous' ? 'ambiguous_heading' : 'not_found',
+                                    message: resolved.error === 'ambiguous'
+                                        ? `Heading "${heading}" matches multiple headings; use headingIndex to disambiguate`
+                                        : `Heading "${heading}" not found in document ${documentId}`,
+                                    candidates: resolved.candidates.map(({ i, level, text }) => ({ i, level, text })),
+                                }, null, 2) }],
+                        isError: true,
+                    };
+                }
+                section = resolved.match;
+            }
+            const text = section
+                ? extractPlainTextInRange(body, section.startIndex, section.endIndex)
+                : extractPlainText(body);
+            const from = offset ?? 0;
+            const capped = capText(text, maxChars ?? 50_000, from);
             return {
                 content: [{ type: 'text', text: JSON.stringify({
                             documentId: res.data.documentId,
                             title: res.data.title,
-                            text,
+                            ...(tabId !== undefined ? { tabId } : {}),
+                            headings: headings.map(({ i, level, text: t }) => ({ i, level, text: t })),
+                            ...(section ? { section: { i: section.i, level: section.level, text: section.text } } : {}),
+                            text: capped.text,
+                            ...(capped.truncated || from > 0
+                                ? { truncated: capped.truncated, totalChars: capped.totalChars, offset: from }
+                                : {}),
                         }, null, 2) }],
             };
         }

package/dist/tools/generated/admin.js

@@ -1775,7 +1775,7 @@ export function registerAdminGeneratedTools(registry) {
         },
     });
     registerGeneratedTool(registry, {
-        name: "admin_users_update",
+        name: "admin_users_replace",
         cud: "update",
         description: "Updates a user. This method supports patch semantics, meaning that you only need to include the fields you wish to update. Fields that are not present in the re",
         method: { id: "directory.users.update", httpMethod: "PUT", path: "admin/directory/v1/users/{userKey}", baseUrl: "https://admin.googleapis.com/", requiredParams: ["userKey"] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "5.2.0-alpha.3",
+  "version": "5.2.0-alpha.5",
   "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",
@@ -56,7 +56,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "gen:discovery": "tsx scripts/fetch-discovery.ts",
-    "gen:tools": "tsx scripts/gen-tools.ts"
+    "gen:tools": "tsx scripts/gen-tools.ts",
+    "gen:coverage": "tsx scripts/gen-coverage.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",