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

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.5",
+  "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",