npm - mcp-google-multi - Versions diffs - 5.2.0-alpha.4 → 5.2.0-alpha.5 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/package.json CHANGED Viewed

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