mcp-google-multi 5.2.0-alpha.4 → 5.2.0-alpha.6

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.
-- 🧰 **Exhaustive coverage** — every OAuth-reachable Workspace API method is a named tool: **871 tools across 28 services** (182 hand-curated + 689 generated from Google's API Discovery), plus an escape hatch for anything else → 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
-
-Every OAuth-reachable Workspace API method is a named tool — 871 across 28 services. Core services (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Search Console, Tasks, Meet) are on by default; Slides, Forms, Chat, Classroom, Vault, Keep, Apps Script, Cloud Search, Drive Labels and more enable via `GOOGLE_OPTIONAL_SCOPES` bundles, and Workspace Admin APIs via `GOOGLE_ADMIN_ACCOUNTS`. Curated tools give shaped, token-lean responses for everyday operations; generated tools (from Google's API Discovery documents) cover the long tail with the same write-control and account fan-out. **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/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/gmail-mime.d.ts

@@ -14,6 +14,20 @@ export declare function encodeAddressHeader(value: string): string;
  * Normalize bare `\n` or `\r` to CRLF.
  */
 export declare function normalizeBodyLineEndings(body: string): string;
+/**
+ * Best-effort HTML→plain-text for reading HTML-only emails. Regex-based on
+ * purpose — no HTML parser dependency, and mail HTML is flat enough for it.
+ */
+export declare function htmlToText(html: string): string;
+/**
+ * RFC 5322 threading: In-Reply-To/References must carry the parent's real
+ * Message-ID header, not the Gmail API id. Falls back to the API id when the
+ * header is missing so replies still thread inside Gmail.
+ */
+export declare function buildReplyHeaders(fallbackId: string, parentMessageIdHeader: string, parentReferences: string): {
+    inReplyTo: string;
+    references: string;
+};
 /**
  * Build a multipart/alternative body so HTML-capable clients render the rich
  * version and plain clients fall back. Returns the header value AND the body.

package/dist/tools/gmail-mime.js

@@ -63,6 +63,95 @@ export function encodeAddressHeader(value) {
 export function normalizeBodyLineEndings(body) {
     return body.replace(/\r\n|\r|\n/g, '\r\n');
 }
+const NAMED_ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' ',
+};
+function codePointToChar(code, fallback) {
+    if (Number.isNaN(code) || code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff))
+        return fallback;
+    return String.fromCodePoint(code);
+}
+function decodeEntities(text) {
+    return text.replace(/&(?:#(\d+)|#[xX]([0-9a-fA-F]+)|([a-zA-Z][a-zA-Z0-9]*));/g, (match, dec, hex, named) => {
+        if (dec)
+            return codePointToChar(parseInt(dec, 10), match);
+        if (hex)
+            return codePointToChar(parseInt(hex, 16), match);
+        return NAMED_ENTITIES[named.toLowerCase()] ?? match;
+    });
+}
+// Fixpoint tag strip: one pass can reassemble a tag from a removed span's
+// edges (<scr<b>ipt> -> <script>).
+function stripTags(input, replacement = '') {
+    let out = input;
+    for (let previous = ''; previous !== out;) {
+        previous = out;
+        out = out.replace(/<[^>]*>/g, replacement);
+    }
+    return out;
+}
+/**
+ * Best-effort HTML→plain-text for reading HTML-only emails. Regex-based on
+ * purpose — no HTML parser dependency, and mail HTML is flat enough for it.
+ */
+export function htmlToText(html) {
+    // Repeat until stable: single-pass removal can leave behind sequences
+    // reassembled from the removed span's edges (<scr<script>ipt>).
+    let text = html;
+    for (let previous = ''; previous !== text;) {
+        previous = text;
+        text = text
+            // --!> is a valid comment terminator per WHATWG
+            .replace(/<!--[\s\S]*?--!?>/g, '')
+            // an unterminated comment consumes the rest of the document per spec
+            .replace(/<!--[\s\S]*$/, '')
+            .replace(/<(style|script|head)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, '');
+    }
+    // All comment content is gone; drop any stray bare delimiters too.
+    text = text.replace(/<!--|--!?>/g, '');
+    // Source whitespace (incl. newlines) is insignificant in HTML; real line
+    // structure is reintroduced from block tags below.
+    text = text.replace(/\s+/g, ' ');
+    text = text.replace(/<a\b[^>]*?href\s*=\s*(?:"([^"]*)"|'([^']*)')[^>]*>([\s\S]*?)<\/a\s*>/gi, (_match, dq, sq, inner) => {
+        const href = (dq ?? sq ?? '').trim();
+        const innerText = stripTags(inner, ' ').replace(/\s+/g, ' ').trim();
+        const redundant = href === '' ||
+            href.startsWith('#') ||
+            href === innerText ||
+            href === `mailto:${innerText}`;
+        return redundant ? inner : `${inner} (${href})`;
+    });
+    text = text
+        .replace(/<(?:br|hr)\b[^>]*>/gi, '\n')
+        .replace(/<\/t[dh]\s*>/gi, ' ')
+        .replace(/<(?:p|h[1-6])\b[^>]*>/gi, '\n')
+        .replace(/<\/(?:p|div|h[1-6]|li|tr|table|ul|ol|blockquote|pre|section|article|header|footer|address|figure|dl|dt|dd)\s*>/gi, '\n');
+    text = stripTags(text);
+    return decodeEntities(text)
+        .replace(/[ \t]*\n[ \t]*/g, '\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/**
+ * RFC 5322 threading: In-Reply-To/References must carry the parent's real
+ * Message-ID header, not the Gmail API id. Falls back to the API id when the
+ * header is missing so replies still thread inside Gmail.
+ */
+export function buildReplyHeaders(fallbackId, parentMessageIdHeader, parentReferences) {
+    const parentId = parentMessageIdHeader.trim();
+    if (parentId === '')
+        return { inReplyTo: fallbackId, references: fallbackId };
+    const refs = parentReferences.trim().replace(/\s+/g, ' ');
+    return {
+        inReplyTo: parentId,
+        references: refs === '' ? parentId : `${refs} ${parentId}`,
+    };
+}
 /**
  * RFC 2046 §5.1.1 boundary token: 1-70 chars from a restricted set, no trailing space.
  * randomBytes hex output is only [0-9a-f], all of which are bcharsnospace.

package/dist/tools/gmail.d.ts

@@ -1,4 +1,6 @@
 import type { ToolRegistry } from '../registry.js';
 import type { GmailMessageFull } from '../types.js';
-export declare function parseMessage(msg: any, bodyCap?: number): GmailMessageFull;
+export declare function parseMessage(msg: any, bodyCap?: number, opts?: {
+    rawHtml?: boolean;
+}): GmailMessageFull;
 export declare function registerGmailTools(server: ToolRegistry): void;

package/dist/tools/gmail.js

@@ -4,7 +4,7 @@ import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
-import { buildMultipartAlternative, encodeAddressHeader, encodeHeaderValue, normalizeBodyLineEndings } from './gmail-mime.js';
+import { buildMultipartAlternative, buildReplyHeaders, encodeAddressHeader, encodeHeaderValue, htmlToText, normalizeBodyLineEndings } from './gmail-mime.js';
 import { sliceClean } from '../trim.js';
 import * as path from 'path';
 import * as fs from 'fs';
@@ -12,38 +12,50 @@ const accountEnum = z.enum(ACCOUNTS);
 function getHeader(headers, name) {
     return headers?.find((h) => h.name?.toLowerCase() === name.toLowerCase())?.value ?? '';
 }
-function decodeBody(payload) {
-    if (payload.body?.data) {
-        return Buffer.from(payload.body.data, 'base64url').toString('utf-8');
+function collectTextParts(part, plain, html, topLevel = false) {
+    if (!part)
+        return;
+    const isAttachment = Boolean(part.filename) || Boolean(part.body?.attachmentId);
+    if (!isAttachment && part.body?.data) {
+        const decoded = Buffer.from(part.body.data, 'base64url').toString('utf-8');
+        if (part.mimeType === 'text/html')
+            html.push(decoded);
+        // Simple (non-multipart) messages can carry any mimeType at the top level;
+        // returning their raw body preserves pre-collect behavior.
+        else if (part.mimeType === 'text/plain' || !part.mimeType || topLevel)
+            plain.push(decoded);
     }
-    if (payload.parts) {
-        for (const part of payload.parts) {
-            if (part.mimeType === 'text/plain' && part.body?.data) {
-                return Buffer.from(part.body.data, 'base64url').toString('utf-8');
-            }
-        }
-        for (const part of payload.parts) {
-            if (part.mimeType === 'text/html' && part.body?.data) {
-                return Buffer.from(part.body.data, 'base64url').toString('utf-8');
-            }
-        }
-        for (const part of payload.parts) {
-            if (part.parts) {
-                const result = decodeBody(part);
-                if (result)
-                    return result;
-            }
-        }
+    for (const child of part.parts ?? []) {
+        collectTextParts(child, plain, html);
     }
-    return '';
+}
+function decodeBody(payload, rawHtml = false) {
+    const plain = [];
+    const html = [];
+    collectTextParts(payload, plain, html, true);
+    // Concatenating every plain leaf keeps forwarded/mixed messages whole;
+    // any plain content beats HTML because alternatives duplicate the same body.
+    if (plain.length > 0)
+        return { body: plain.join('\n\n'), bodyOrigin: 'text/plain' };
+    if (html.length > 0) {
+        const joined = html.join('\n\n');
+        return { body: rawHtml ? joined : htmlToText(joined), bodyOrigin: 'text/html' };
+    }
+    return { body: '' };
 }
 function getAttachments(payload) {
     const attachments = [];
     if (payload.filename && payload.body?.attachmentId) {
+        const disposition = getHeader(payload.headers, 'Content-Disposition');
+        const inline = disposition.toLowerCase().startsWith('inline')
+            || getHeader(payload.headers, 'Content-ID') !== '';
         attachments.push({
             filename: payload.filename,
             attachmentId: payload.body.attachmentId,
             mimeType: payload.mimeType ?? 'application/octet-stream',
+            ...(typeof payload.body.size === 'number' ? { sizeBytes: payload.body.size } : {}),
+            ...(payload.partId ? { partId: payload.partId } : {}),
+            ...(inline ? { inline: true } : {}),
         });
     }
     if (payload.parts) {
@@ -53,11 +65,30 @@ function getAttachments(payload) {
     }
     return attachments;
 }
+async function resolveReplyHeaders(gmail, replyToMessageId) {
+    try {
+        const meta = await gmail.users.messages.get({
+            userId: 'me',
+            id: replyToMessageId,
+            format: 'metadata',
+            metadataHeaders: ['Message-ID', 'References'],
+        });
+        const headers = meta.data.payload?.headers;
+        return buildReplyHeaders(replyToMessageId, getHeader(headers, 'Message-ID'), getHeader(headers, 'References'));
+    }
+    catch {
+        // Degrade to the API id (pre-lookup behavior) rather than blocking the send.
+        return { inReplyTo: replyToMessageId, references: replyToMessageId };
+    }
+}
 const BODY_CAP_CHARS = 50_000;
-export function parseMessage(msg, bodyCap) {
+export function parseMessage(msg, bodyCap, opts) {
     const headers = msg.payload?.headers ?? [];
-    const body = decodeBody(msg.payload);
+    const { body, bodyOrigin } = decodeBody(msg.payload, opts?.rawHtml === true);
     const capped = bodyCap !== undefined && body.length > bodyCap;
+    const messageIdHeader = getHeader(headers, 'Message-ID');
+    const inReplyTo = getHeader(headers, 'In-Reply-To');
+    const references = getHeader(headers, 'References');
     return {
         id: msg.id ?? '',
         threadId: msg.threadId ?? '',
@@ -67,7 +98,13 @@ export function parseMessage(msg, bodyCap) {
         cc: getHeader(headers, 'Cc'),
         date: getHeader(headers, 'Date'),
         body: capped ? sliceClean(body, bodyCap) : body,
+        ...(bodyOrigin ? { bodyOrigin } : {}),
         ...(capped ? { bodyTruncated: true, bodyTotalChars: body.length } : {}),
+        ...(messageIdHeader ? { messageIdHeader } : {}),
+        ...(inReplyTo ? { inReplyTo } : {}),
+        ...(references ? { references } : {}),
+        ...(msg.labelIds ? { labelIds: msg.labelIds } : {}),
+        ...(msg.internalDate ? { internalDate: msg.internalDate } : {}),
         attachments: getAttachments(msg.payload),
     };
 }
@@ -91,21 +128,28 @@ export function registerGmailTools(server) {
             });
             const messages = listRes.data.messages ?? [];
             const results = [];
-            for (const m of messages) {
-                const detail = await gmail.users.messages.get({
+            // Bounded parallelism: chunked Promise.all keeps order and avoids
+            // hammering the per-user quota with an unbounded fan-out.
+            const CHUNK_SIZE = 10;
+            for (let i = 0; i < messages.length; i += CHUNK_SIZE) {
+                const details = await Promise.all(messages.slice(i, i + CHUNK_SIZE).map((m) => gmail.users.messages.get({
                     userId: 'me',
                     id: m.id,
                     format: 'metadata',
-                    metadataHeaders: ['From', 'Subject', 'Date'],
-                });
-                results.push({
-                    id: detail.data.id ?? '',
-                    threadId: detail.data.threadId ?? '',
-                    subject: getHeader(detail.data.payload?.headers, 'Subject'),
-                    from: getHeader(detail.data.payload?.headers, 'From'),
-                    date: getHeader(detail.data.payload?.headers, 'Date'),
-                    snippet: detail.data.snippet ?? '',
-                });
+                    metadataHeaders: ['From', 'To', 'Subject', 'Date'],
+                })));
+                for (const detail of details) {
+                    results.push({
+                        id: detail.data.id ?? '',
+                        threadId: detail.data.threadId ?? '',
+                        subject: getHeader(detail.data.payload?.headers, 'Subject'),
+                        from: getHeader(detail.data.payload?.headers, 'From'),
+                        to: getHeader(detail.data.payload?.headers, 'To'),
+                        date: getHeader(detail.data.payload?.headers, 'Date'),
+                        snippet: detail.data.snippet ?? '',
+                        labelIds: detail.data.labelIds ?? [],
+                    });
+                }
             }
             return {
                 content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
@@ -121,8 +165,10 @@ export function registerGmailTools(server) {
             account: accountEnum.describe('Google account alias'),
             messageId: z.string().describe('Gmail message ID'),
             full: coerceBoolean.optional().describe('Return the entire body without the character cap'),
+            rawHtml: coerceBoolean.optional()
+                .describe('Return the HTML body unconverted instead of the plain-text rendering (HTML-only messages)'),
         },
-    }, async ({ account, messageId, full }) => {
+    }, async ({ account, messageId, full, rawHtml }) => {
         try {
             const auth = await getClient(account);
             const gmail = google.gmail({ version: 'v1', auth });
@@ -131,7 +177,7 @@ export function registerGmailTools(server) {
                 id: messageId,
                 format: 'full',
             });
-            const result = parseMessage(res.data, full ? undefined : BODY_CAP_CHARS);
+            const result = parseMessage(res.data, full ? undefined : BODY_CAP_CHARS, { rawHtml });
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
             };
@@ -141,22 +187,46 @@ export function registerGmailTools(server) {
         }
     });
     server.registerTool('gmail_read_thread', {
-        description: 'Read all messages in a Gmail thread (bodies capped at 50k chars each unless full=true)',
+        description: 'Read all messages in a Gmail thread (bodies capped at 50k chars each unless full=true). mode=summary returns headers + snippets only.',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             threadId: z.string().describe('Gmail thread ID'),
             full: coerceBoolean.optional().describe('Return entire bodies without the character cap'),
+            rawHtml: coerceBoolean.optional()
+                .describe('Return HTML bodies unconverted instead of the plain-text rendering (HTML-only messages)'),
+            mode: z.enum(['full', 'summary']).default('full')
+                .describe('full = complete bodies; summary = per-message headers and snippet only'),
         },
-    }, async ({ account, threadId, full }) => {
+    }, async ({ account, threadId, full, rawHtml, mode }) => {
         try {
             const auth = await getClient(account);
             const gmail = google.gmail({ version: 'v1', auth });
+            if (mode === 'summary') {
+                const res = await gmail.users.threads.get({
+                    userId: 'me',
+                    id: threadId,
+                    format: 'metadata',
+                    metadataHeaders: ['From', 'To', 'Subject', 'Date', 'Message-ID'],
+                });
+                const summaries = (res.data.messages ?? []).map((m) => ({
+                    id: m.id ?? '',
+                    from: getHeader(m.payload?.headers, 'From'),
+                    to: getHeader(m.payload?.headers, 'To'),
+                    subject: getHeader(m.payload?.headers, 'Subject'),
+                    date: getHeader(m.payload?.headers, 'Date'),
+                    snippet: m.snippet ?? '',
+                    labelIds: m.labelIds ?? [],
+                }));
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(summaries, null, 2) }],
+                };
+            }
             const res = await gmail.users.threads.get({
                 userId: 'me',
                 id: threadId,
                 format: 'full',
             });
-            const messages = (res.data.messages ?? []).map((m) => parseMessage(m, full ? undefined : BODY_CAP_CHARS));
+            const messages = (res.data.messages ?? []).map((m) => parseMessage(m, full ? undefined : BODY_CAP_CHARS, { rawHtml }));
             return {
                 content: [{ type: 'text', text: JSON.stringify(messages, null, 2) }],
             };
@@ -205,8 +275,9 @@ export function registerGmailTools(server) {
             if (cc)
                 headers.push(`Cc: ${encodeAddressHeader(cc)}`);
             if (replyToMessageId) {
-                headers.push(`In-Reply-To: ${replyToMessageId}`);
-                headers.push(`References: ${replyToMessageId}`);
+                const { inReplyTo, references } = await resolveReplyHeaders(gmail, replyToMessageId);
+                headers.push(`In-Reply-To: ${inReplyTo}`);
+                headers.push(`References: ${references}`);
             }
             const rawMessage = [...headers, '', bodyText].join('\r\n');
             const encoded = Buffer.from(rawMessage, 'utf-8').toString('base64url');
@@ -272,10 +343,12 @@ export function registerGmailTools(server) {
             htmlBody: z.string().optional()
                 .describe('Optional HTML body. When set, drafts as multipart/alternative so HTML-capable clients render the rich version. Use bare tags only: <p>, <a>, <br>, <strong>, <em>, <ul><li>.'),
             cc: z.string().optional().describe('CC recipients, comma-separated'),
+            replyToMessageId: z.string().optional()
+                .describe('Message ID to reply to (sets In-Reply-To and References headers)'),
             replyToThreadId: z.string().optional()
                 .describe('Thread ID to associate the draft with'),
         },
-    }, async ({ account, to, subject, body, htmlBody, cc, replyToThreadId }) => {
+    }, async ({ account, to, subject, body, htmlBody, cc, replyToMessageId, replyToThreadId }) => {
         try {
             const auth = await getClient(account);
             const gmail = google.gmail({ version: 'v1', auth });
@@ -299,6 +372,11 @@ export function registerGmailTools(server) {
             }
             if (cc)
                 headers.push(`Cc: ${encodeAddressHeader(cc)}`);
+            if (replyToMessageId) {
+                const { inReplyTo, references } = await resolveReplyHeaders(gmail, replyToMessageId);
+                headers.push(`In-Reply-To: ${inReplyTo}`);
+                headers.push(`References: ${references}`);
+            }
             const rawMessage = [...headers, '', bodyText].join('\r\n');
             const encoded = Buffer.from(rawMessage, 'utf-8').toString('base64url');
             const draftParams = {

package/dist/types.d.ts

@@ -10,13 +10,18 @@ export interface GmailMessageHeader {
     threadId: string;
     subject: string;
     from: string;
+    to: string;
     date: string;
     snippet: string;
+    labelIds: string[];
 }
 export interface GmailAttachment {
     filename: string;
     attachmentId: string;
     mimeType: string;
+    sizeBytes?: number;
+    partId?: string;
+    inline?: boolean;
 }
 export interface GmailMessageFull {
     id: string;
@@ -27,8 +32,14 @@ export interface GmailMessageFull {
     cc: string;
     date: string;
     body: string;
+    bodyOrigin?: 'text/plain' | 'text/html';
     bodyTruncated?: boolean;
     bodyTotalChars?: number;
+    messageIdHeader?: string;
+    inReplyTo?: string;
+    references?: string;
+    labelIds?: string[];
+    internalDate?: string;
     attachments: GmailAttachment[];
 }
 export interface DriveFile {

package/package.json

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