google-tools-mcp 1.2.6 → 1.2.7

package/dist/helpers.js

@@ -212,3 +212,41 @@ export const getPlainTextBody = (messagePart) => {
     }
     return '';
 };
+
+export const formatMessageClean = (message, maxBodyChars = 3000) => {
+    const headers = message.payload?.headers || [];
+    const get = (name) => findHeader(headers, name);
+    let body = getPlainTextBody(message.payload) || '';
+    const totalChars = body.length;
+    const truncated = maxBodyChars > 0 && body.length > maxBodyChars;
+    if (truncated) body = body.slice(0, maxBodyChars);
+    return {
+        id: message.id,
+        threadId: message.threadId,
+        labelIds: message.labelIds,
+        snippet: message.snippet,
+        from: get('from'),
+        to: get('to'),
+        cc: get('cc'),
+        subject: get('subject'),
+        date: get('date'),
+        body,
+        ...(truncated ? { bodyTruncated: true, totalChars } : {}),
+    };
+};
+
+export const formatMessageMetadata = (message) => {
+    const headers = message.payload?.headers || [];
+    const get = (name) => findHeader(headers, name);
+    return {
+        id: message.id,
+        threadId: message.threadId,
+        labelIds: message.labelIds,
+        snippet: message.snippet,
+        from: get('from'),
+        to: get('to'),
+        cc: get('cc'),
+        subject: get('subject'),
+        date: get('date'),
+    };
+};

package/dist/tools/drive/getRevision.js

@@ -0,0 +1,57 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'getRevision',
+        description: 'Gets details about a specific revision of a Drive file, including who made it, when, and an optional temporary download link to retrieve the content at that point in time.',
+        parameters: z.object({
+            fileId: z.string().describe('The ID of the Drive file.'),
+            revisionId: z.string().describe('The revision ID (from listRevisions).'),
+            includeDownloadLink: z.boolean().optional().default(false).describe('If true, includes a short-lived download URL for the revision content.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Getting revision ${args.revisionId} for file: ${args.fileId}`);
+            try {
+                const fields = [
+                    'id', 'modifiedTime', 'lastModifyingUser(displayName,emailAddress)',
+                    'keepForever', 'published', 'publishedOutsideDomain', 'publishAuto',
+                    'mimeType', 'size',
+                    ...(args.includeDownloadLink ? ['exportLinks', 'downloadUrl'] : []),
+                ].join(',');
+                const response = await drive.revisions.get({
+                    fileId: args.fileId,
+                    revisionId: args.revisionId,
+                    fields,
+                });
+                const r = response.data;
+                const result = {
+                    revisionId: r.id,
+                    modifiedTime: r.modifiedTime,
+                    modifiedBy: r.lastModifyingUser?.displayName || null,
+                    modifiedByEmail: r.lastModifyingUser?.emailAddress || null,
+                    mimeType: r.mimeType,
+                    sizeBytes: r.size ? parseInt(r.size, 10) : null,
+                    keepForever: r.keepForever || false,
+                    published: r.published || false,
+                    publishedOutsideDomain: r.publishedOutsideDomain || false,
+                    publishAuto: r.publishAuto || false,
+                    ...(args.includeDownloadLink ? {
+                        downloadUrl: r.downloadUrl || null,
+                        exportLinks: r.exportLinks || null,
+                    } : {}),
+                };
+                return JSON.stringify(result, null, 2);
+            }
+            catch (error) {
+                log.error(`Error getting revision: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`File or revision not found (fileId: ${args.fileId}, revisionId: ${args.revisionId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have access to this file.');
+                throw new UserError(`Failed to get revision: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/index.js

@@ -19,6 +19,9 @@ import { register as listPermissions } from './listPermissions.js';
 import { register as addPermission } from './addPermission.js';
 import { register as removePermission } from './removePermission.js';
 import { register as updatePermission } from './updatePermission.js';
+import { register as listRevisions } from './listRevisions.js';
+import { register as getRevision } from './getRevision.js';
+import { register as updateRevision } from './updateRevision.js';
 export function registerDriveTools(server) {
     listDriveFiles(server);
     searchGoogleDocs(server);
@@ -41,4 +44,7 @@ export function registerDriveTools(server) {
     addPermission(server);
     removePermission(server);
     updatePermission(server);
+    listRevisions(server);
+    getRevision(server);
+    updateRevision(server);
 }

package/dist/tools/drive/listRevisions.js

@@ -0,0 +1,50 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'listRevisions',
+        description: 'Lists all saved versions (revision history) of a Drive file such as a Google Doc, Sheet, or Slide. Returns each revision\'s ID, modifier, timestamp, and whether it is kept forever.',
+        parameters: z.object({
+            fileId: z.string().describe('The ID of the Drive file to list revisions for.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Listing revisions for file: ${args.fileId}`);
+            try {
+                const revisions = [];
+                let pageToken;
+                do {
+                    const response = await drive.revisions.list({
+                        fileId: args.fileId,
+                        fields: 'nextPageToken,revisions(id,modifiedTime,lastModifyingUser(displayName,emailAddress),keepForever,published,size)',
+                        pageSize: 200,
+                        ...(pageToken ? { pageToken } : {}),
+                    });
+                    const page = response.data.revisions || [];
+                    revisions.push(...page);
+                    pageToken = response.data.nextPageToken;
+                } while (pageToken);
+                const result = revisions.map((r, i) => ({
+                    revisionId: r.id,
+                    index: i + 1,
+                    modifiedTime: r.modifiedTime,
+                    modifiedBy: r.lastModifyingUser?.displayName || null,
+                    modifiedByEmail: r.lastModifyingUser?.emailAddress || null,
+                    keepForever: r.keepForever || false,
+                    published: r.published || false,
+                    sizeBytes: r.size ? parseInt(r.size, 10) : null,
+                }));
+                return JSON.stringify({ total: result.length, revisions: result }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing revisions: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`File not found (ID: ${args.fileId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Make sure you have access to this file.');
+                throw new UserError(`Failed to list revisions: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/drive/updateRevision.js

@@ -0,0 +1,51 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getDriveClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'updateRevision',
+        description: 'Updates metadata for a specific revision of a Drive file. Use this to pin a revision so it is kept forever (never auto-deleted by Drive), or to control publishing settings for Google Docs/Slides.',
+        parameters: z.object({
+            fileId: z.string().describe('The ID of the Drive file.'),
+            revisionId: z.string().describe('The revision ID to update (from listRevisions).'),
+            keepForever: z.boolean().optional().describe('If true, this revision is kept indefinitely and will not be automatically deleted. Only applies to files with a binary content type; Google Docs revisions are always kept.'),
+            published: z.boolean().optional().describe('Whether this revision is published. Only applies to Google Docs and Slides.'),
+            publishAuto: z.boolean().optional().describe('Whether subsequent revisions are automatically republished. Only applies to Google Docs and Slides.'),
+        }),
+        execute: async (args, { log }) => {
+            const drive = await getDriveClient();
+            log.info(`Updating revision ${args.revisionId} for file: ${args.fileId}`);
+            const body = {};
+            if (args.keepForever !== undefined) body.keepForever = args.keepForever;
+            if (args.published !== undefined) body.published = args.published;
+            if (args.publishAuto !== undefined) body.publishAuto = args.publishAuto;
+            if (Object.keys(body).length === 0) {
+                throw new UserError('No fields to update. Provide at least one of: keepForever, published, publishAuto.');
+            }
+            try {
+                const response = await drive.revisions.update({
+                    fileId: args.fileId,
+                    revisionId: args.revisionId,
+                    fields: 'id,keepForever,published,publishAuto,modifiedTime',
+                    requestBody: body,
+                });
+                const r = response.data;
+                return JSON.stringify({
+                    revisionId: r.id,
+                    modifiedTime: r.modifiedTime,
+                    keepForever: r.keepForever || false,
+                    published: r.published || false,
+                    publishAuto: r.publishAuto || false,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error updating revision: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`File or revision not found (fileId: ${args.fileId}, revisionId: ${args.revisionId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. You need edit access to update revisions.');
+                throw new UserError(`Failed to update revision: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/gmail/labels.js

@@ -80,24 +80,4 @@ export function register(server) {
         },
     });
 
-    server.addTool({
-        name: 'update_label',
-        description: 'Update an existing label',
-        parameters: z.object({
-            id: z.string().describe("The ID of the label to update"),
-            name: z.string().optional().describe("The display name of the label"),
-            messageListVisibility: z.enum(['show', 'hide']).optional().describe("Visibility of messages with this label"),
-            labelListVisibility: z.enum(['labelShow', 'labelShowIfUnread', 'labelHide']).optional().describe("Visibility of the label in the label list"),
-            color: z.object({
-                textColor: z.string().describe("The text color as hex string"),
-                backgroundColor: z.string().describe("The background color as hex string"),
-            }).optional().describe("The color settings for the label"),
-        }),
-        execute: async (params) => {
-            const { id, ...labelData } = params;
-            const gmail = await getGmailClient();
-            const { data } = await gmail.users.labels.update({ userId: 'me', id, requestBody: labelData });
-            return JSON.stringify(data);
-        },
-    });
 }

package/dist/tools/gmail/messages.js

@@ -1,7 +1,7 @@
 // Gmail Message tools
 import { z } from 'zod';
 import { getGmailClient } from '../../clients.js';
-import { processMessagePart, constructRawMessage, constructRawMessageWithAttachments, findHeader, formatEmailList, getNestedHistory, getPlainTextBody, isHtmlBody, wrapTextBody } from '../../helpers.js';
+import { processMessagePart, constructRawMessage, constructRawMessageWithAttachments, findHeader, formatEmailList, getNestedHistory, getPlainTextBody, isHtmlBody, wrapTextBody, formatMessageClean, formatMessageMetadata } from '../../helpers.js';
 
 export function register(server) {
     server.addTool({
@@ -279,42 +279,60 @@ export function register(server) {
 
     server.addTool({
         name: 'get_message',
-        description: 'Get a specific message by ID with format options',
+        description: 'Get a specific message by ID. format="clean" (default) returns from/to/subject/date/body as a flat object. format="metadata" returns headers only, no body. format="full" returns the raw MIME tree (current legacy behavior).',
         parameters: z.object({
             id: z.string().describe("The ID of the message to retrieve"),
-            includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body"),
+            format: z.enum(['full', 'clean', 'metadata']).optional().default('clean').describe("Response format: clean (default), metadata (headers only), or full (raw MIME tree)"),
+            maxBodyChars: z.number().optional().default(3000).describe("Max body characters in clean mode. 0 = unlimited. Truncated responses include bodyTruncated: true."),
+            includeBodyHtml: z.boolean().optional().describe("In full mode only: whether to include parsed HTML body parts"),
         }),
         execute: async (params) => {
             const gmail = await getGmailClient();
             const { data } = await gmail.users.messages.get({ userId: 'me', id: params.id, format: 'full' });
-            if (data.payload) {
-                data.payload = processMessagePart(data.payload, params.includeBodyHtml);
-            }
+            if (params.format === 'clean') return JSON.stringify(formatMessageClean(data, params.maxBodyChars));
+            if (params.format === 'metadata') return JSON.stringify(formatMessageMetadata(data));
+            if (data.payload) data.payload = processMessagePart(data.payload, params.includeBodyHtml);
             return JSON.stringify(data);
         },
     });
 
     server.addTool({
         name: 'list_messages',
-        description: 'List messages in the user\'s mailbox with optional filtering',
+        description: 'List messages in the user\'s mailbox with optional filtering. format="metadata" (default) auto-fetches message details for each result. format="clean" includes the message body. format="full" returns raw MIME data. Omit format to get bare IDs only.',
         parameters: z.object({
             maxResults: z.number().optional().describe("Maximum number of messages to return (1-500)"),
             pageToken: z.string().optional().describe("Page token to retrieve a specific page of results"),
             q: z.string().optional().describe("Only return messages matching the specified query (same format as Gmail search box)"),
             labelIds: z.array(z.string()).optional().describe("Only return messages with labels that match all specified label IDs"),
             includeSpamTrash: z.boolean().optional().describe("Include messages from SPAM and TRASH"),
-            includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body"),
+            format: z.enum(['full', 'clean', 'metadata']).optional().describe("When set, auto-fetches full message details. metadata=headers only (default when set), clean=with body, full=raw MIME tree."),
+            maxBodyChars: z.number().optional().default(3000).describe("Max body characters in clean mode. 0 = unlimited."),
+            includeBodyHtml: z.boolean().optional().describe("In full mode only: whether to include parsed HTML body parts"),
         }),
         execute: async (params) => {
             const gmail = await getGmailClient();
-            const { data } = await gmail.users.messages.list({ userId: 'me', ...params });
-            if (data.messages) {
-                data.messages = data.messages.map(message => {
-                    if (message.payload) {
-                        message.payload = processMessagePart(message.payload, params.includeBodyHtml);
-                    }
-                    return message;
-                });
+            const { data } = await gmail.users.messages.list({
+                userId: 'me',
+                maxResults: params.maxResults,
+                pageToken: params.pageToken,
+                q: params.q,
+                labelIds: params.labelIds,
+                includeSpamTrash: params.includeSpamTrash,
+            });
+            if (params.format && data.messages?.length) {
+                data.messages = await Promise.all(
+                    data.messages.map(async ({ id }) => {
+                        try {
+                            const { data: msg } = await gmail.users.messages.get({ userId: 'me', id, format: 'full' });
+                            if (params.format === 'clean') return formatMessageClean(msg, params.maxBodyChars);
+                            if (params.format === 'metadata') return formatMessageMetadata(msg);
+                            if (msg.payload) msg.payload = processMessagePart(msg.payload, params.includeBodyHtml);
+                            return msg;
+                        } catch (e) {
+                            return { id, error: e.message || 'Failed to retrieve message' };
+                        }
+                    })
+                );
             }
             return JSON.stringify(data);
         },
@@ -322,98 +340,61 @@ export function register(server) {
 
     server.addTool({
         name: 'modify_message',
-        description: 'Modify the labels on a message',
+        description: 'Modify the labels on one or more messages. Pass a single id or an array of ids.',
         parameters: z.object({
-            id: z.string().describe("The ID of the message to modify"),
+            ids: z.union([z.string(), z.array(z.string())]).describe("Message ID or array of message IDs to modify"),
             addLabelIds: z.array(z.string()).optional().describe("Label IDs to add"),
             removeLabelIds: z.array(z.string()).optional().describe("Label IDs to remove"),
         }),
         execute: async (params) => {
             const gmail = await getGmailClient();
-            const { data } = await gmail.users.messages.modify({
-                userId: 'me', id: params.id,
-                requestBody: { addLabelIds: params.addLabelIds, removeLabelIds: params.removeLabelIds }
+            const ids = Array.isArray(params.ids) ? params.ids : [params.ids];
+            const { data } = await gmail.users.messages.batchModify({
+                userId: 'me',
+                requestBody: { ids, addLabelIds: params.addLabelIds, removeLabelIds: params.removeLabelIds },
             });
-            return JSON.stringify(data);
+            return JSON.stringify(data || { success: true });
         },
     });
 
     server.addTool({
         name: 'delete_message',
-        description: 'Immediately and permanently delete a message',
+        description: 'Immediately and permanently delete one or more messages. Pass a single id or an array of ids.',
         parameters: z.object({
-            id: z.string().describe("The ID of the message to delete"),
+            ids: z.union([z.string(), z.array(z.string())]).describe("Message ID or array of message IDs to delete"),
         }),
         execute: async (params) => {
             const gmail = await getGmailClient();
-            const { data } = await gmail.users.messages.delete({ userId: 'me', id: params.id });
+            const ids = Array.isArray(params.ids) ? params.ids : [params.ids];
+            const { data } = await gmail.users.messages.batchDelete({ userId: 'me', requestBody: { ids } });
             return JSON.stringify(data || { success: true });
         },
     });
 
     server.addTool({
         name: 'trash_message',
-        description: 'Move a message to the trash',
-        parameters: z.object({
-            id: z.string().describe("The ID of the message to move to trash"),
-        }),
-        execute: async (params) => {
-            const gmail = await getGmailClient();
-            const { data } = await gmail.users.messages.trash({ userId: 'me', id: params.id });
-            return JSON.stringify(data);
-        },
-    });
-
-    server.addTool({
-        name: 'untrash_message',
-        description: 'Remove a message from the trash',
+        description: 'Move a message to the trash or restore it. Use action="trash" to move to trash, action="untrash" to restore.',
         parameters: z.object({
-            id: z.string().describe("The ID of the message to remove from trash"),
+            id: z.string().describe("The ID of the message"),
+            action: z.enum(['trash', 'untrash']).describe("'trash' to move to trash, 'untrash' to restore"),
         }),
         execute: async (params) => {
             const gmail = await getGmailClient();
-            const { data } = await gmail.users.messages.untrash({ userId: 'me', id: params.id });
+            const fn = params.action === 'untrash' ? 'untrash' : 'trash';
+            const { data } = await gmail.users.messages[fn]({ userId: 'me', id: params.id });
             return JSON.stringify(data);
         },
     });
 
-    server.addTool({
-        name: 'batch_delete_messages',
-        description: 'Delete multiple messages',
-        parameters: z.object({
-            ids: z.array(z.string()).describe("The IDs of the messages to delete"),
-        }),
-        execute: async (params) => {
-            const gmail = await getGmailClient();
-            const { data } = await gmail.users.messages.batchDelete({ userId: 'me', requestBody: { ids: params.ids } });
-            return JSON.stringify(data || { success: true });
-        },
-    });
-
-    server.addTool({
-        name: 'batch_modify_messages',
-        description: 'Modify the labels on multiple messages',
-        parameters: z.object({
-            ids: z.array(z.string()).describe("The IDs of the messages to modify"),
-            addLabelIds: z.array(z.string()).optional().describe("Label IDs to add"),
-            removeLabelIds: z.array(z.string()).optional().describe("Label IDs to remove"),
-        }),
-        execute: async (params) => {
-            const gmail = await getGmailClient();
-            const { data } = await gmail.users.messages.batchModify({
-                userId: 'me',
-                requestBody: { ids: params.ids, addLabelIds: params.addLabelIds, removeLabelIds: params.removeLabelIds }
-            });
-            return JSON.stringify(data || { success: true });
-        },
-    });
 
     server.addTool({
         name: 'batch_get_messages',
         description: 'Get multiple messages by ID in parallel. More efficient than calling get_message multiple times.',
         parameters: z.object({
             ids: z.array(z.string()).describe("The IDs of the messages to retrieve"),
-            includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body"),
+            format: z.enum(['full', 'clean', 'metadata']).optional().default('clean').describe("Response format: clean (default), metadata (headers only), or full (raw MIME tree)"),
+            maxBodyChars: z.number().optional().default(3000).describe("Max body characters in clean mode. 0 = unlimited."),
+            includeBodyHtml: z.boolean().optional().describe("In full mode only: whether to include parsed HTML body parts"),
         }),
         execute: async (params) => {
             const gmail = await getGmailClient();
@@ -421,9 +402,9 @@ export function register(server) {
                 params.ids.map(async (id) => {
                     try {
                         const { data } = await gmail.users.messages.get({ userId: 'me', id, format: 'full' });
-                        if (data.payload) {
-                            data.payload = processMessagePart(data.payload, params.includeBodyHtml);
-                        }
+                        if (params.format === 'clean') return formatMessageClean(data, params.maxBodyChars);
+                        if (params.format === 'metadata') return formatMessageMetadata(data);
+                        if (data.payload) data.payload = processMessagePart(data.payload, params.includeBodyHtml);
                         return data;
                     } catch (error) {
                         return { id, error: error.message || 'Failed to retrieve message' };

package/dist/tools/gmail/threads.js

@@ -1,24 +1,26 @@
 // Gmail Thread tools
 import { z } from 'zod';
 import { getGmailClient } from '../../clients.js';
-import { processMessagePart } from '../../helpers.js';
+import { processMessagePart, formatMessageClean, formatMessageMetadata } from '../../helpers.js';
 
 export function register(server) {
     server.addTool({
         name: 'get_thread',
-        description: 'Get a specific thread by ID',
+        description: 'Get a specific thread by ID. format="clean" (default) returns each message as from/to/subject/date/body. format="metadata" returns headers only. format="full" returns raw MIME trees.',
         parameters: z.object({
             id: z.string().describe("The ID of the thread to retrieve"),
-            includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body"),
+            format: z.enum(['full', 'clean', 'metadata']).optional().default('clean').describe("Response format for each message: clean (default), metadata (headers only), or full (raw MIME tree)"),
+            maxBodyChars: z.number().optional().default(3000).describe("Max body characters per message in clean mode. 0 = unlimited."),
+            includeBodyHtml: z.boolean().optional().describe("In full mode only: whether to include parsed HTML body parts"),
         }),
         execute: async (params) => {
             const gmail = await getGmailClient();
             const { data } = await gmail.users.threads.get({ userId: 'me', id: params.id, format: 'full' });
             if (data.messages) {
                 data.messages = data.messages.map(message => {
-                    if (message.payload) {
-                        message.payload = processMessagePart(message.payload, params.includeBodyHtml);
-                    }
+                    if (params.format === 'clean') return formatMessageClean(message, params.maxBodyChars);
+                    if (params.format === 'metadata') return formatMessageMetadata(message);
+                    if (message.payload) message.payload = processMessagePart(message.payload, params.includeBodyHtml);
                     return message;
                 });
             }
@@ -28,30 +30,46 @@ export function register(server) {
 
     server.addTool({
         name: 'list_threads',
-        description: 'List threads in the user\'s mailbox',
+        description: 'List threads in the user\'s mailbox. format="metadata" (default) auto-fetches thread details with headers only. format="clean" includes message bodies. format="full" returns raw MIME data. Omit format to get bare thread stubs (id/snippet only).',
         parameters: z.object({
             maxResults: z.number().optional().describe("Maximum number of threads to return"),
             pageToken: z.string().optional().describe("Page token to retrieve a specific page of results"),
             q: z.string().optional().describe("Only return threads matching the specified query"),
             labelIds: z.array(z.string()).optional().describe("Only return threads with labels that match all specified label IDs"),
             includeSpamTrash: z.boolean().optional().describe("Include threads from SPAM and TRASH"),
-            includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body"),
+            format: z.enum(['full', 'clean', 'metadata']).optional().describe("When set, auto-fetches full thread details. metadata=headers only (default when set), clean=with bodies, full=raw MIME tree."),
+            maxBodyChars: z.number().optional().default(3000).describe("Max body characters per message in clean mode. 0 = unlimited."),
+            includeBodyHtml: z.boolean().optional().describe("In full mode only: whether to include parsed HTML body parts"),
         }),
         execute: async (params) => {
             const gmail = await getGmailClient();
-            const { data } = await gmail.users.threads.list({ userId: 'me', ...params });
-            if (data.threads) {
-                data.threads = data.threads.map(thread => {
-                    if (thread.messages) {
-                        thread.messages = thread.messages.map(message => {
-                            if (message.payload) {
-                                message.payload = processMessagePart(message.payload, params.includeBodyHtml);
+            const { data } = await gmail.users.threads.list({
+                userId: 'me',
+                maxResults: params.maxResults,
+                pageToken: params.pageToken,
+                q: params.q,
+                labelIds: params.labelIds,
+                includeSpamTrash: params.includeSpamTrash,
+            });
+            if (params.format && data.threads?.length) {
+                data.threads = await Promise.all(
+                    data.threads.map(async ({ id }) => {
+                        try {
+                            const { data: thread } = await gmail.users.threads.get({ userId: 'me', id, format: 'full' });
+                            if (thread.messages) {
+                                thread.messages = thread.messages.map(message => {
+                                    if (params.format === 'clean') return formatMessageClean(message, params.maxBodyChars);
+                                    if (params.format === 'metadata') return formatMessageMetadata(message);
+                                    if (message.payload) message.payload = processMessagePart(message.payload, params.includeBodyHtml);
+                                    return message;
+                                });
                             }
-                            return message;
-                        });
-                    }
-                    return thread;
-                });
+                            return thread;
+                        } catch (e) {
+                            return { id, error: e.message || 'Failed to retrieve thread' };
+                        }
+                    })
+                );
             }
             return JSON.stringify(data);
         },
@@ -62,7 +80,9 @@ export function register(server) {
         description: 'Get multiple threads by ID in parallel. More efficient than calling get_thread multiple times.',
         parameters: z.object({
             ids: z.array(z.string()).describe("The IDs of the threads to retrieve"),
-            includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body"),
+            format: z.enum(['full', 'clean', 'metadata']).optional().default('clean').describe("Response format for each message: clean (default), metadata (headers only), or full (raw MIME tree)"),
+            maxBodyChars: z.number().optional().default(3000).describe("Max body characters per message in clean mode. 0 = unlimited."),
+            includeBodyHtml: z.boolean().optional().describe("In full mode only: whether to include parsed HTML body parts"),
         }),
         execute: async (params) => {
             const gmail = await getGmailClient();
@@ -72,9 +92,9 @@ export function register(server) {
                         const { data } = await gmail.users.threads.get({ userId: 'me', id, format: 'full' });
                         if (data.messages) {
                             data.messages = data.messages.map(message => {
-                                if (message.payload) {
-                                    message.payload = processMessagePart(message.payload, params.includeBodyHtml);
-                                }
+                                if (params.format === 'clean') return formatMessageClean(message, params.maxBodyChars);
+                                if (params.format === 'metadata') return formatMessageMetadata(message);
+                                if (message.payload) message.payload = processMessagePart(message.payload, params.includeBodyHtml);
                                 return message;
                             });
                         }
@@ -119,26 +139,15 @@ export function register(server) {
 
     server.addTool({
         name: 'trash_thread',
-        description: 'Move a thread to the trash',
-        parameters: z.object({
-            id: z.string().describe("The ID of the thread to move to trash"),
-        }),
-        execute: async (params) => {
-            const gmail = await getGmailClient();
-            const { data } = await gmail.users.threads.trash({ userId: 'me', id: params.id });
-            return JSON.stringify(data);
-        },
-    });
-
-    server.addTool({
-        name: 'untrash_thread',
-        description: 'Remove a thread from the trash',
+        description: 'Move a thread to the trash or restore it. Use action="trash" to move to trash, action="untrash" to restore.',
         parameters: z.object({
-            id: z.string().describe("The ID of the thread to remove from trash"),
+            id: z.string().describe("The ID of the thread"),
+            action: z.enum(['trash', 'untrash']).describe("'trash' to move to trash, 'untrash' to restore"),
         }),
         execute: async (params) => {
             const gmail = await getGmailClient();
-            const { data } = await gmail.users.threads.untrash({ userId: 'me', id: params.id });
+            const fn = params.action === 'untrash' ? 'untrash' : 'trash';
+            const { data } = await gmail.users.threads[fn]({ userId: 'me', id: params.id });
             return JSON.stringify(data);
         },
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "google-tools-mcp",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "The easiest MCP server for Google Workspace — Drive, Docs, Sheets, Gmail, Calendar, and Forms. 153 tools with one-click browser auth. Read Word docs, PDFs, and spreadsheets straight from Drive.",
   "type": "module",
   "bin": {