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

package/README.md

@@ -71,6 +71,8 @@ Now the only thing on disk is the **encrypted** token store. Pass the token via
 | `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`, `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`.
 
@@ -80,6 +82,20 @@ The server does **not** dump ~170 tool schemas into your model's context. At boo
 
 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 `forms`/`chat`/`admin` does not enable them without their `GOOGLE_OPTIONAL_SCOPES` / `GOOGLE_ADMIN_ACCOUNTS` gates.
 
+## 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 Slides), 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`; `slides`/`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:

package/dist/discovery-client.d.ts

@@ -0,0 +1,46 @@
+export declare const WORKSPACE_APIS: Record<string, {
+    id: string;
+    version: string;
+}>;
+export interface DiscoveryParam {
+    location: 'path' | 'query';
+    required?: boolean;
+    type?: string;
+    description?: string;
+}
+export interface DiscoveryMethod {
+    id: string;
+    api: string;
+    httpMethod: string;
+    path: string;
+    baseUrl: string;
+    description: string;
+    params: Record<string, DiscoveryParam>;
+    requiredParams: string[];
+    scopes: string[];
+}
+interface DiscoveryDoc {
+    baseUrl?: string;
+    rootUrl?: string;
+    servicePath?: string;
+    resources?: Record<string, unknown>;
+    methods?: Record<string, unknown>;
+}
+export interface DiscoveryDeps {
+    fetchFn?: (url: string) => Promise<{
+        ok: boolean;
+        status: number;
+        json(): Promise<unknown>;
+    }>;
+    cacheDir?: string;
+    now?: () => number;
+}
+export declare function discoveryCacheDir(env?: NodeJS.ProcessEnv): string;
+export declare function isGoogleApiUrl(url: string): boolean;
+export declare function buildMethodIndex(doc: DiscoveryDoc, api: string): DiscoveryMethod[];
+export declare function loadMethodIndex(api: string, deps?: DiscoveryDeps): Promise<DiscoveryMethod[]>;
+export declare function clearDiscoveryMemoryCache(): void;
+export declare function cudFromMethod(method: Pick<DiscoveryMethod, 'httpMethod' | 'id'>): 'read' | 'create' | 'update' | 'delete';
+export declare function expandPath(template: string, pathParams: Record<string, string>): string;
+export declare function searchMethods(index: DiscoveryMethod[], query: string, limit?: number): DiscoveryMethod[];
+export {};

package/dist/discovery-client.js

@@ -0,0 +1,185 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+export const WORKSPACE_APIS = {
+    gmail: { id: 'gmail', version: 'v1' },
+    drive: { id: 'drive', version: 'v3' },
+    calendar: { id: 'calendar', version: 'v3' },
+    sheets: { id: 'sheets', version: 'v4' },
+    docs: { id: 'docs', version: 'v1' },
+    slides: { id: 'slides', version: 'v1' },
+    forms: { id: 'forms', version: 'v1' },
+    people: { id: 'people', version: 'v1' },
+    searchconsole: { id: 'searchconsole', version: 'v1' },
+    tasks: { id: 'tasks', version: 'v1' },
+    chat: { id: 'chat', version: 'v1' },
+    meet: { id: 'meet', version: 'v2' },
+    driveactivity: { id: 'driveactivity', version: 'v2' },
+    drivelabels: { id: 'drivelabels', version: 'v2' },
+    admin_directory: { id: 'admin', version: 'directory_v1' },
+    admin_reports: { id: 'admin', version: 'reports_v1' },
+    groupssettings: { id: 'groupssettings', version: 'v1' },
+};
+const TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const STALE_RETRY_MS = 5 * 60 * 1000;
+const FETCH_TIMEOUT_MS = 10_000;
+export function discoveryCacheDir(env = process.env) {
+    return (env.DISCOVERY_CACHE_PATH ??
+        path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'mcp-google-multi', 'discovery'));
+}
+// A poisoned cache file could repoint baseUrl off-Google; refuse to send the
+// user's Bearer token anywhere but a googleapis.com host.
+export function isGoogleApiUrl(url) {
+    try {
+        const u = new URL(url);
+        return u.protocol === 'https:' && (u.hostname === 'googleapis.com' || u.hostname.endsWith('.googleapis.com'));
+    }
+    catch {
+        return false;
+    }
+}
+const memoryCache = new Map();
+export function buildMethodIndex(doc, api) {
+    const baseUrl = doc.baseUrl ?? `${doc.rootUrl ?? ''}${doc.servicePath ?? ''}`;
+    const out = [];
+    const walk = (node) => {
+        for (const m of Object.values(node.methods ?? {})) {
+            const method = m;
+            if (!method.id || !method.httpMethod || !method.path)
+                continue;
+            const params = method.parameters ?? {};
+            out.push({
+                id: method.id,
+                api,
+                httpMethod: method.httpMethod.toUpperCase(),
+                path: method.path,
+                baseUrl,
+                description: (method.description ?? '').split('\n')[0].slice(0, 160),
+                params,
+                requiredParams: Object.entries(params)
+                    .filter(([, p]) => p.required)
+                    .map(([name]) => name),
+                scopes: method.scopes ?? [],
+            });
+        }
+        for (const r of Object.values(node.resources ?? {})) {
+            walk(r);
+        }
+    };
+    walk(doc);
+    return out;
+}
+export async function loadMethodIndex(api, deps = {}) {
+    const now = deps.now ?? Date.now;
+    const cached = memoryCache.get(api);
+    if (cached && now() < cached.refreshAfter)
+        return cached.index;
+    const spec = WORKSPACE_APIS[api];
+    if (!spec) {
+        throw new Error(`Unknown api "${api}". Known: ${Object.keys(WORKSPACE_APIS).join(', ')}`);
+    }
+    const fetchFn = deps.fetchFn ?? ((url) => fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) }));
+    const cacheDir = deps.cacheDir ?? discoveryCacheDir();
+    const cacheFile = path.join(cacheDir, `${api}.json`);
+    const readCache = () => {
+        try {
+            return JSON.parse(fs.readFileSync(cacheFile, 'utf-8'));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const cacheFresh = () => {
+        try {
+            return now() - fs.statSync(cacheFile).mtimeMs < TTL_MS;
+        }
+        catch {
+            return false;
+        }
+    };
+    let doc;
+    let staleFallback = false;
+    if (cacheFresh())
+        doc = readCache();
+    if (!doc) {
+        const url = `https://www.googleapis.com/discovery/v1/apis/${spec.id}/${spec.version}/rest`;
+        try {
+            const res = await fetchFn(url);
+            if (!res.ok)
+                throw new Error(`HTTP ${res.status}`);
+            doc = (await res.json());
+            fs.mkdirSync(cacheDir, { recursive: true });
+            fs.writeFileSync(cacheFile, JSON.stringify(doc), { mode: 0o600 });
+        }
+        catch (err) {
+            doc = readCache();
+            staleFallback = true;
+            if (!doc) {
+                throw new Error(`Could not fetch the Google API Discovery document for "${api}" and no local cache exists (${err.message}). Retry when online.`, { cause: err });
+            }
+        }
+    }
+    const index = buildMethodIndex(doc, api);
+    memoryCache.set(api, { index, refreshAfter: now() + (staleFallback ? STALE_RETRY_MS : TTL_MS) });
+    return index;
+}
+export function clearDiscoveryMemoryCache() {
+    memoryCache.clear();
+}
+const POST_READ_VERB = /^(get|list|search|query|lookup|count|batchGet|generateIds|export|download|inspect)/i;
+const POST_UPDATE_VERB = /^(untrash|undelete|restore|modify|move|set|sort|merge|unmerge|replace|resize|publish|resolve|update|patch|write|format)/i;
+const POST_DELETE_VERB = /^(batch)?(delete|remove|trash|clear|empty|obliterate|purge|revoke|wipeout)/i;
+export function cudFromMethod(method) {
+    switch (method.httpMethod) {
+        case 'GET':
+        case 'HEAD':
+            return 'read';
+        case 'DELETE':
+            return 'delete';
+        case 'PUT':
+        case 'PATCH':
+            return 'update';
+        default: {
+            // POST carries reads (batchGet), updates (modify) and permanent deletes
+            // (batchDelete, clear, obliterate) — classify by verb or write-control misfires.
+            const lastSegment = method.id.split('.').pop() ?? '';
+            if (POST_READ_VERB.test(lastSegment))
+                return 'read';
+            if (POST_UPDATE_VERB.test(lastSegment))
+                return 'update';
+            if (POST_DELETE_VERB.test(lastSegment))
+                return 'delete';
+            return 'create';
+        }
+    }
+}
+export function expandPath(template, pathParams) {
+    return template.replace(/\{(\+?)([^}]+)\}/g, (_match, plus, name) => {
+        const value = pathParams[name];
+        if (value === undefined) {
+            throw new Error(`Missing required path parameter "${name}"`);
+        }
+        return plus ? String(value).split('/').map(encodeURIComponent).join('/') : encodeURIComponent(String(value));
+    });
+}
+export function searchMethods(index, query, limit = 10) {
+    const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
+    if (tokens.length === 0)
+        return index.slice(0, limit);
+    const scored = index
+        .map((m) => {
+        const id = m.id.toLowerCase();
+        const desc = m.description.toLowerCase();
+        let score = 0;
+        for (const t of tokens) {
+            if (id.includes(t))
+                score += 3;
+            if (desc.includes(t))
+                score += 1;
+        }
+        return { m, score };
+    })
+        .filter((s) => s.score > 0);
+    scored.sort((a, b) => b.score - a.score || a.m.id.localeCompare(b.m.id));
+    return scored.slice(0, limit).map((s) => s.m);
+}

package/dist/index.js

@@ -20,6 +20,7 @@ import { registerAdminTools } from './tools/admin.js';
 import { getOptionalBundles, getAdminAccounts } from './auth.js';
 import { ToolRegistry } from './registry.js';
 import { registerDiscoverTools } from './discover.js';
+import { registerEscapeTools } from './tools/google-api.js';
 import { getToolsets, toolsetEnabled } from './toolsets.js';
 import { resolvePolicy, isAllowed, describePolicy } from './write-control.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -61,12 +62,13 @@ function buildRegistry(server, policy) {
         }
         svc.register(registry);
     }
-    registerDiscoverTools(registry, policy);
-    if (registry.tools.length === 0) {
+    if (registry.services().length === 0) {
         throw new Error(`GOOGLE_TOOLSETS="${process.env.GOOGLE_TOOLSETS ?? ''}" selected no enabled services. ` +
             `Known services: ${SERVICES.map((s) => s.name).join(', ')}. ` +
             `Note: forms/chat require GOOGLE_OPTIONAL_SCOPES, admin requires GOOGLE_ADMIN_ACCOUNTS.`);
     }
+    registerDiscoverTools(registry, policy);
+    registerEscapeTools(registry, policy);
     return registry;
 }
 async function main() {
@@ -90,7 +92,8 @@ async function main() {
         console.log(`CUD tools enabled: ${cud.length - disabled.length}/${cud.length}`);
         console.log(`Disabled: ${disabled.map((t) => t.name).join(', ') || '(none)'}`);
         console.log(`Services: ${registry.services().join(', ')}`);
-        console.log(`Tool surface: ${counts.eager} eager (discover), ${counts.hidden} deferred until discovery`);
+        console.log(`Tool surface: ${counts.eager} eager (discover + escape hatch), ${counts.hidden} deferred until discovery`);
+        console.log(`Escape hatch: google_api_call CUD verdicts follow profile=${policy.profile} and your allow/deny globs`);
         return;
     }
     const policy = resolvePolicy();

package/dist/registry.d.ts

@@ -24,6 +24,7 @@ export declare class ToolRegistry {
     readonly registerTool: McpServer['registerTool'];
     private readonly revealed;
     private readonly jsonSchemaCache;
+    private readonly compactOutput;
     private registeringMeta;
     constructor(server: McpServer, policy: Policy);
     registerMeta: McpServer['registerTool'];

package/dist/registry.js

@@ -1,6 +1,7 @@
 import { ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { isAllowed, writeDisabledResult } from './write-control.js';
+import { compactResult, trimEnabled } from './trim.js';
 const CUD_OVERRIDES = {
     drive_untrash: 'update',
 };
@@ -28,6 +29,7 @@ export class ToolRegistry {
     registerTool;
     revealed = new Set();
     jsonSchemaCache = new Map();
+    compactOutput = trimEnabled();
     registeringMeta = false;
     constructor(server, policy) {
         this.server = server;
@@ -54,7 +56,10 @@ export class ToolRegistry {
                 : (...args) => isAllowed({ name, service, cud }, policy)
                     ? handler(...args)
                     : writeDisabledResult({ name, service, cud }, policy);
-            return server.registerTool(name, { ...config, annotations }, guarded);
+            const finalHandler = this.compactOutput
+                ? async (...args) => compactResult(await guarded(...args))
+                : guarded;
+            return server.registerTool(name, { ...config, annotations }, finalHandler);
         });
     }
     registerMeta = ((name, config, handler) => {

package/dist/tools/calendar.d.ts

@@ -1,2 +1,22 @@
 import type { ToolRegistry } from '../registry.js';
 export declare function registerCalendarTools(server: ToolRegistry): void;
+export declare function formatEvent(event: any, opts?: {
+    full?: boolean;
+}): {
+    id: any;
+    summary: any;
+    description: string;
+    location: any;
+    start: any;
+    end: any;
+    status: any;
+    htmlLink: any;
+    organizer: any;
+    attendees: any;
+    recurringEventId: any;
+    hangoutLink: any;
+    created: any;
+    updated: any;
+} | {
+    [k: string]: any;
+};

package/dist/tools/calendar.js

@@ -4,6 +4,7 @@ import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
+import { sliceClean } from '../trim.js';
 const accountEnum = z.enum(ACCOUNTS);
 export function registerCalendarTools(server) {
     server.registerTool('calendar_list_calendars', {
@@ -33,7 +34,7 @@ export function registerCalendarTools(server) {
         }
     });
     server.registerTool('calendar_list_events', {
-        description: 'List events from a Google Calendar',
+        description: 'List events from a Google Calendar (trimmed view: descriptions capped, created/updated and empty fields omitted — use calendar_get_event for a full event)',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             calendarId: z.string().default('primary').optional()
@@ -66,7 +67,7 @@ export function registerCalendarTools(server) {
                 params.timeMin = new Date().toISOString();
             }
             const res = await cal.events.list(params);
-            const events = (res.data.items ?? []).map(formatEvent);
+            const events = (res.data.items ?? []).map((e) => formatEvent(e, { full: false }));
             return {
                 content: [{ type: 'text', text: JSON.stringify(events, null, 2) }],
             };
@@ -288,7 +289,7 @@ export function registerCalendarTools(server) {
         }
     });
     server.registerTool('calendar_list_instances', {
-        description: 'List all occurrences of a recurring calendar event',
+        description: 'List all occurrences of a recurring calendar event (trimmed view like calendar_list_events — use calendar_get_event for a full event)',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             calendarId: z.string().default('primary').optional()
@@ -310,7 +311,7 @@ export function registerCalendarTools(server) {
                 timeMax,
                 maxResults: maxResults ?? 25,
             });
-            const events = (res.data.items ?? []).map(formatEvent);
+            const events = (res.data.items ?? []).map((e) => formatEvent(e, { full: false }));
             return {
                 content: [{ type: 'text', text: JSON.stringify(events, null, 2) }],
             };
@@ -376,11 +377,19 @@ export function registerCalendarTools(server) {
         }
     });
 }
-function formatEvent(event) {
-    return {
+const LIST_DESCRIPTION_CAP = 300;
+const TRUNCATION_MARKER = '… [truncated, use calendar_get_event]';
+export function formatEvent(event, opts = {}) {
+    const full = opts.full ?? true;
+    const description = event.description ?? '';
+    // Slack margin: truncating a 301-char description to 300 + 37-char marker would GROW it.
+    const cappedDescription = full || description.length <= LIST_DESCRIPTION_CAP + TRUNCATION_MARKER.length
+        ? description
+        : `${sliceClean(description, LIST_DESCRIPTION_CAP)}${TRUNCATION_MARKER}`;
+    const base = {
         id: event.id,
         summary: event.summary ?? '',
-        description: event.description ?? '',
+        description: cappedDescription,
         location: event.location ?? '',
         start: event.start?.dateTime ?? event.start?.date ?? '',
         end: event.end?.dateTime ?? event.end?.date ?? '',
@@ -391,9 +400,14 @@ function formatEvent(event) {
             email: a.email,
             responseStatus: a.responseStatus,
         })),
-        created: event.created,
-        updated: event.updated,
+        recurringEventId: event.recurringEventId,
+        hangoutLink: event.hangoutLink,
+        created: full ? event.created : undefined,
+        updated: full ? event.updated : undefined,
     };
+    if (full)
+        return base;
+    return Object.fromEntries(Object.entries(base).filter(([, v]) => v !== undefined && v !== '' && !(Array.isArray(v) && v.length === 0)));
 }
 function handleCalendarError(error, account) {
     return handleGoogleApiError(error, account);

package/dist/tools/drive.js

@@ -4,6 +4,7 @@ import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
+import { capText } from '../trim.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { pipeline } from 'node:stream/promises';
@@ -59,12 +60,16 @@ export function registerDriveTools(server) {
         }
     });
     server.registerTool('drive_read', {
-        description: 'Read the content of a Google Drive file',
+        description: 'Read the content of a Google Drive file (returns up to maxChars characters per call; non-Google-native files over 2MB return too_large)',
         inputSchema: {
             account: accountEnum.describe('Google account alias'),
             fileId: z.string().describe('Google Drive file ID'),
+            maxChars: z.number().min(1).max(2_000_000).default(100_000).optional()
+                .describe('Max characters of content to return (default: 100000)'),
+            offset: z.number().min(0).default(0).optional()
+                .describe('Character offset to continue a truncated read (Google Docs/Sheets/Slides exports page fine; plain files >2MB are rejected, not paged)'),
         },
-    }, async ({ account, fileId }) => {
+    }, async ({ account, fileId, maxChars, offset }) => {
         try {
             const auth = await getClient(account);
             const drive = google.drive({ version: 'v3', auth });
@@ -74,11 +79,9 @@ export function registerDriveTools(server) {
                 supportsAllDrives: true,
             });
             const { name, mimeType, size, webViewLink } = meta.data;
-            if (mimeType && GOOGLE_WORKSPACE_TYPES.has(mimeType)) {
-                const exported = await drive.files.export({
-                    fileId,
-                    mimeType: 'text/plain',
-                });
+            const respond = (raw) => {
+                const from = offset ?? 0;
+                const capped = capText(raw, maxChars ?? 100_000, from);
                 return {
                     content: [{
                             type: 'text',
@@ -86,10 +89,20 @@ export function registerDriveTools(server) {
                                 id: fileId,
                                 name,
                                 mimeType,
-                                content: String(exported.data),
+                                content: capped.text,
+                                ...(capped.truncated || from > 0
+                                    ? { truncated: capped.truncated, totalChars: capped.totalChars, offset: from }
+                                    : {}),
                             }, null, 2),
                         }],
                 };
+            };
+            if (mimeType && GOOGLE_WORKSPACE_TYPES.has(mimeType)) {
+                const exported = await drive.files.export({
+                    fileId,
+                    mimeType: 'text/plain',
+                });
+                return respond(String(exported.data));
             }
             if (mimeType === 'application/pdf') {
                 return {
@@ -122,17 +135,7 @@ export function registerDriveTools(server) {
             }
             if (mimeType?.startsWith('text/')) {
                 const downloaded = await drive.files.get({ fileId, alt: 'media', supportsAllDrives: true }, { responseType: 'text' });
-                return {
-                    content: [{
-                            type: 'text',
-                            text: JSON.stringify({
-                                id: fileId,
-                                name,
-                                mimeType,
-                                content: String(downloaded.data),
-                            }, null, 2),
-                        }],
-                };
+                return respond(String(downloaded.data));
             }
             return {
                 content: [{

package/dist/tools/gmail.d.ts

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

package/dist/tools/gmail.js

@@ -5,6 +5,7 @@ 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 { sliceClean } from '../trim.js';
 import * as path from 'path';
 import * as fs from 'fs';
 const accountEnum = z.enum(ACCOUNTS);
@@ -52,8 +53,11 @@ function getAttachments(payload) {
     }
     return attachments;
 }
-function parseMessage(msg) {
+const BODY_CAP_CHARS = 50_000;
+export function parseMessage(msg, bodyCap) {
     const headers = msg.payload?.headers ?? [];
+    const body = decodeBody(msg.payload);
+    const capped = bodyCap !== undefined && body.length > bodyCap;
     return {
         id: msg.id ?? '',
         threadId: msg.threadId ?? '',
@@ -62,7 +66,8 @@ function parseMessage(msg) {
         to: getHeader(headers, 'To'),
         cc: getHeader(headers, 'Cc'),
         date: getHeader(headers, 'Date'),
-        body: decodeBody(msg.payload),
+        body: capped ? sliceClean(body, bodyCap) : body,
+        ...(capped ? { bodyTruncated: true, bodyTotalChars: body.length } : {}),
         attachments: getAttachments(msg.payload),
     };
 }
@@ -111,12 +116,13 @@ export function registerGmailTools(server) {
         }
     });
     server.registerTool('gmail_read', {
-        description: 'Read a full Gmail message by ID',
+        description: 'Read a full Gmail message by ID (body capped at 50k chars unless full=true)',
         inputSchema: {
             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'),
         },
-    }, async ({ account, messageId }) => {
+    }, async ({ account, messageId, full }) => {
         try {
             const auth = await getClient(account);
             const gmail = google.gmail({ version: 'v1', auth });
@@ -125,7 +131,7 @@ export function registerGmailTools(server) {
                 id: messageId,
                 format: 'full',
             });
-            const result = parseMessage(res.data);
+            const result = parseMessage(res.data, full ? undefined : BODY_CAP_CHARS);
             return {
                 content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
             };
@@ -135,12 +141,13 @@ export function registerGmailTools(server) {
         }
     });
     server.registerTool('gmail_read_thread', {
-        description: 'Read all messages in a Gmail thread',
+        description: 'Read all messages in a Gmail thread (bodies capped at 50k chars each unless full=true)',
         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'),
         },
-    }, async ({ account, threadId }) => {
+    }, async ({ account, threadId, full }) => {
         try {
             const auth = await getClient(account);
             const gmail = google.gmail({ version: 'v1', auth });
@@ -149,7 +156,7 @@ export function registerGmailTools(server) {
                 id: threadId,
                 format: 'full',
             });
-            const messages = (res.data.messages ?? []).map(parseMessage);
+            const messages = (res.data.messages ?? []).map((m) => parseMessage(m, full ? undefined : BODY_CAP_CHARS));
             return {
                 content: [{ type: 'text', text: JSON.stringify(messages, null, 2) }],
             };

package/dist/tools/google-api.d.ts

@@ -0,0 +1,10 @@
+import type { ToolRegistry } from '../registry.js';
+import { type Policy } from '../write-control.js';
+import { getClient } from '../client.js';
+import { type Toolsets } from '../toolsets.js';
+import { type DiscoveryDeps } from '../discovery-client.js';
+export interface EscapeDeps extends DiscoveryDeps {
+    getClientFn?: typeof getClient;
+    toolsets?: Toolsets;
+}
+export declare function registerEscapeTools(registry: ToolRegistry, policy: Policy, deps?: EscapeDeps): void;

package/dist/tools/google-api.js

@@ -0,0 +1,211 @@
+import { z } from 'zod';
+import { isAllowed, writeDisabledResult } from '../write-control.js';
+import { ACCOUNTS } from '../accounts.js';
+import { getClient } from '../client.js';
+import { handleGoogleApiError } from './_errors.js';
+import { coerceJson } from './_coerce.js';
+import { getToolsets, toolsetEnabled } from '../toolsets.js';
+import { WORKSPACE_APIS, cudFromMethod, expandPath, isGoogleApiUrl, loadMethodIndex, searchMethods, } from '../discovery-client.js';
+const accountEnum = z.enum(ACCOUNTS);
+const MAX_RESPONSE_CHARS = 100_000;
+// Policy/toolset namespace for each API alias must match the NAMED tools' service
+// names, or user deny globs and GOOGLE_TOOLSETS silently miss escape-hatch calls.
+const SERVICE_FOR_ALIAS = {
+    gmail: 'gmail',
+    drive: 'drive',
+    calendar: 'calendar',
+    sheets: 'sheets',
+    docs: 'docs',
+    slides: null,
+    forms: 'forms',
+    people: 'contacts',
+    searchconsole: 'searchconsole',
+    tasks: 'tasks',
+    chat: 'chat',
+    meet: 'meet',
+    driveactivity: null,
+    drivelabels: null,
+    admin_directory: 'admin',
+    admin_reports: 'admin',
+    groupssettings: null,
+};
+function buildQueryString(queryParams) {
+    const usp = new URLSearchParams();
+    const merged = { alt: 'json', ...queryParams };
+    for (const [key, value] of Object.entries(merged)) {
+        if (Array.isArray(value)) {
+            for (const v of value)
+                usp.append(key, String(v));
+        }
+        else {
+            usp.append(key, String(value));
+        }
+    }
+    return usp.toString();
+}
+function jsonResult(payload, isError = false) {
+    const base = { content: [{ type: 'text', text: JSON.stringify(payload) }] };
+    return isError ? { ...base, isError: true } : base;
+}
+function describeMethod(m) {
+    return {
+        api: m.api,
+        methodId: m.id,
+        httpMethod: m.httpMethod,
+        path: m.path,
+        description: m.description,
+        requiredParams: m.requiredParams,
+        cud: cudFromMethod(m),
+    };
+}
+export function registerEscapeTools(registry, policy, deps = {}) {
+    const getClientFn = deps.getClientFn ?? getClient;
+    const toolsets = deps.toolsets ?? getToolsets();
+    const apiEnabled = (alias) => {
+        const service = SERVICE_FOR_ALIAS[alias];
+        return service === null || service === undefined || toolsetEnabled(toolsets, service);
+    };
+    const enabledApis = Object.keys(WORKSPACE_APIS).filter(apiEnabled);
+    const apiList = enabledApis.join(', ');
+    const toolsetDisabled = (alias) => jsonResult({
+        error: 'toolset_disabled',
+        message: `API "${alias}" maps to service "${SERVICE_FOR_ALIAS[alias]}", which is excluded by GOOGLE_TOOLSETS.`,
+        hint: 'Add the service to GOOGLE_TOOLSETS (or unset it) to use this API.',
+        retriable: false,
+    }, true);
+    registry.registerMeta('google_api_search', {
+        description: 'Search the Google API Discovery index for any Workspace REST method, including ones with no ' +
+            'dedicated tool here. Returns method ids + parameters to invoke via google_api_call. ' +
+            `APIs: ${apiList}.`,
+        inputSchema: {
+            query: z.string().describe('Keywords, e.g. "slides create presentation" or "drive revisions"'),
+            api: z.string().optional().describe('Restrict the search to one API alias'),
+            maxResults: z.number().min(1).max(25).default(10).optional(),
+        },
+        annotations: { openWorldHint: true },
+    }, async ({ query, api, maxResults }) => {
+        if (api && !WORKSPACE_APIS[api]) {
+            return jsonResult({ error: 'unknown_api', message: `Unknown api "${api}".`, hint: `Known APIs: ${apiList}`, retriable: false }, true);
+        }
+        if (api && !apiEnabled(api))
+            return toolsetDisabled(api);
+        const apis = api ? [api] : enabledApis;
+        const unavailable = [];
+        const indexes = await Promise.all(apis.map(async (a) => {
+            try {
+                return await loadMethodIndex(a, deps);
+            }
+            catch {
+                unavailable.push(a);
+                return [];
+            }
+        }));
+        const matches = searchMethods(indexes.flat(), query, maxResults ?? 10);
+        return jsonResult({
+            methods: matches.map(describeMethod),
+            ...(unavailable.length > 0 ? { unavailableApis: unavailable } : {}),
+            next: 'Invoke with google_api_call({account, api, methodId, pathParams, queryParams, body}).',
+        });
+    });
+    registry.registerMeta('google_api_call', {
+        description: 'Invoke any Google Workspace REST method by Discovery id (escape hatch for operations without a ' +
+            'dedicated tool). Find methods with google_api_search first. Subject to the same write-control ' +
+            'policy as named tools.',
+        inputSchema: {
+            account: accountEnum.describe('Google account alias'),
+            api: z.string().describe(`API alias: ${apiList}`),
+            methodId: z.string().describe('Discovery method id, e.g. "drive.revisions.list"'),
+            pathParams: coerceJson(z.record(z.string(), z.union([z.string(), z.number()])).optional())
+                .describe('Values for {placeholders} in the method path'),
+            queryParams: coerceJson(z
+                .record(z.string(), z.union([
+                z.string(),
+                z.number(),
+                z.boolean(),
+                z.array(z.union([z.string(), z.number(), z.boolean()])),
+            ]))
+                .optional()).describe('Query-string parameters; use an array for repeated params (e.g. resourceNames)'),
+            body: coerceJson(z.record(z.string(), z.unknown()).optional()).describe('JSON request body'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    }, async ({ account, api, methodId, pathParams, queryParams, body }) => {
+        if (!WORKSPACE_APIS[api]) {
+            return jsonResult({ error: 'unknown_api', message: `Unknown api "${api}".`, hint: `Known APIs: ${apiList}`, retriable: false }, true);
+        }
+        if (!apiEnabled(api))
+            return toolsetDisabled(api);
+        if (queryParams?.alt === 'media') {
+            return jsonResult({
+                error: 'binary_unsupported',
+                message: 'Binary media download (alt=media) returns no usable JSON through the escape hatch.',
+                hint: 'Use drive_download / drive_export for file content.',
+                retriable: false,
+            }, true);
+        }
+        let index;
+        try {
+            index = await loadMethodIndex(api, deps);
+        }
+        catch (err) {
+            return jsonResult({ error: 'discovery_unavailable', message: err.message, retriable: true }, true);
+        }
+        const method = index.find((m) => m.id === methodId);
+        if (!method) {
+            return jsonResult({
+                error: 'unknown_method',
+                message: `No method "${methodId}" in ${api}.`,
+                hint: `Use google_api_search({query: "...", api: "${api}"}) to find the right method id.`,
+                retriable: false,
+            }, true);
+        }
+        const cud = cudFromMethod(method);
+        const policyService = SERVICE_FOR_ALIAS[api] ?? api;
+        const lastSegment = method.id.split('.').pop() ?? method.id;
+        const toolRef = { name: `${policyService}_${lastSegment}`, service: policyService, cud };
+        if (cud !== 'read' && !isAllowed(toolRef, policy)) {
+            return writeDisabledResult(toolRef, policy);
+        }
+        let url;
+        try {
+            url = method.baseUrl + expandPath(method.path, pathParams ?? {});
+        }
+        catch (err) {
+            return jsonResult({
+                error: 'invalid_params',
+                message: err.message,
+                hint: `Required params for ${method.id}: ${method.requiredParams.join(', ') || '(none)'}`,
+                retriable: false,
+            }, true);
+        }
+        if (!isGoogleApiUrl(url)) {
+            return jsonResult({
+                error: 'untrusted_host',
+                message: `Refusing to send credentials to a non-googleapis.com host for "${method.id}".`,
+                hint: 'The discovery cache may be corrupt; delete DISCOVERY_CACHE_PATH and retry.',
+                retriable: false,
+            }, true);
+        }
+        try {
+            const auth = await getClientFn(account);
+            const res = await auth.request({
+                // query string built by hand: gaxios comma-joins arrays, Google needs repeated keys
+                url: `${url}?${buildQueryString(queryParams)}`,
+                method: method.httpMethod,
+                data: body ?? undefined,
+            });
+            const text = JSON.stringify(res.data ?? null);
+            if (text.length > MAX_RESPONSE_CHARS) {
+                return jsonResult({
+                    truncated: true,
+                    totalChars: text.length,
+                    head: text.slice(0, MAX_RESPONSE_CHARS),
+                    hint: 'Narrow the request (fields mask, pageSize) to get complete JSON.',
+                });
+            }
+            return { content: [{ type: 'text', text }] };
+        }
+        catch (error) {
+            return handleGoogleApiError(error, account);
+        }
+    });
+}

package/dist/trim.d.ts

@@ -0,0 +1,16 @@
+export declare function trimEnabled(env?: NodeJS.ProcessEnv): boolean;
+export interface CappedText {
+    text: string;
+    truncated: boolean;
+    totalChars: number;
+}
+export declare function capText(text: string, maxChars: number, offset?: number): CappedText;
+export declare function sliceClean(text: string, max: number): string;
+interface ToolResult {
+    content?: {
+        type?: string;
+        text?: string;
+    }[];
+}
+export declare function compactResult<T extends ToolResult>(result: T): T;
+export {};

package/dist/trim.js

@@ -0,0 +1,29 @@
+export function trimEnabled(env = process.env) {
+    return !/^(0|false|off|no)$/i.test((env.GOOGLE_TRIM ?? '').trim());
+}
+export function capText(text, maxChars, offset = 0) {
+    const slice = text.slice(offset, offset + maxChars);
+    return { text: slice, truncated: offset + slice.length < text.length, totalChars: text.length };
+}
+// For permanent (non-paging) caps: dropping a trailing lone high surrogate keeps
+// the truncated string well-formed Unicode instead of ending in mojibake.
+export function sliceClean(text, max) {
+    const sliced = text.slice(0, max);
+    return /[\uD800-\uDBFF]$/.test(sliced) ? sliced.slice(0, -1) : sliced;
+}
+// Pretty-printed JSON costs ~20-30% extra tokens; re-serialize compactly.
+export function compactResult(result) {
+    if (!result || !Array.isArray(result.content))
+        return result;
+    for (const item of result.content) {
+        if (item?.type === 'text' && typeof item.text === 'string' && /^[\s]*[[{]/.test(item.text)) {
+            try {
+                item.text = JSON.stringify(JSON.parse(item.text));
+            }
+            catch {
+                // not JSON — leave untouched
+            }
+        }
+    }
+    return result;
+}

package/dist/types.d.ts

@@ -27,6 +27,8 @@ export interface GmailMessageFull {
     cc: string;
     date: string;
     body: string;
+    bodyTruncated?: boolean;
+    bodyTotalChars?: number;
     attachments: GmailAttachment[];
 }
 export interface DriveFile {

package/package.json

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