@triffon/google-docs-mcp 1.11.3-triffon

package/dist/tools/gmail/getDraft.js

@@ -0,0 +1,52 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getGmailClient } from '../../clients.js';
+import { findHeaderValue, extractMessageBody } from './helpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'getDraft',
+        description: 'Fetches a single Gmail draft by ID with full headers and body. Use listDrafts to discover draft IDs.',
+        parameters: z.strictObject({
+            draftId: z.string().describe('The Gmail draft ID, typically from listDrafts results.'),
+        }),
+        execute: async (args, { log }) => {
+            const gmail = await getGmailClient();
+            log.info(`Getting Gmail draft ${args.draftId}`);
+            try {
+                const response = await gmail.users.drafts.get({
+                    userId: 'me',
+                    id: args.draftId,
+                    format: 'full',
+                });
+                const draft = response.data;
+                const msg = draft.message;
+                const headers = msg?.payload?.headers;
+                const { text, html } = extractMessageBody(msg?.payload);
+                return JSON.stringify({
+                    draftId: draft.id,
+                    messageId: msg?.id,
+                    threadId: msg?.threadId,
+                    labelIds: msg?.labelIds ?? [],
+                    snippet: msg?.snippet ?? '',
+                    headers: {
+                        from: findHeaderValue(headers, 'From'),
+                        to: findHeaderValue(headers, 'To'),
+                        cc: findHeaderValue(headers, 'Cc'),
+                        bcc: findHeaderValue(headers, 'Bcc'),
+                        subject: findHeaderValue(headers, 'Subject'),
+                        date: findHeaderValue(headers, 'Date'),
+                    },
+                    body: { text, html },
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error getting draft: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Draft not found (ID: ${args.draftId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the gmail.modify scope was granted.');
+                throw new UserError(`Failed to get draft: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/gmail/getMessage.js

@@ -0,0 +1,92 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getGmailClient } from '../../clients.js';
+import { findHeaderValue, extractMessageBody } from './helpers.js';
+function collectAttachments(payload) {
+    const out = [];
+    if (!payload)
+        return out;
+    const walk = (part) => {
+        if (part.filename && part.body?.attachmentId) {
+            out.push({
+                partId: part.partId ?? null,
+                filename: part.filename,
+                mimeType: part.mimeType ?? 'application/octet-stream',
+                size: part.body.size ?? 0,
+                attachmentId: part.body.attachmentId ?? null,
+            });
+        }
+        if (part.parts)
+            for (const sub of part.parts)
+                walk(sub);
+    };
+    walk(payload);
+    return out;
+}
+export function register(server) {
+    server.addTool({
+        name: 'getMessage',
+        description: 'Fetches a single Gmail message by ID with headers, decoded plain-text body, HTML body, and a list of attachments (metadata only). Use listMessages to discover message IDs.',
+        parameters: z.strictObject({
+            messageId: z.string().describe('The Gmail message ID, typically from listMessages results.'),
+            format: z
+                .enum(['full', 'metadata', 'minimal'])
+                .optional()
+                .default('full')
+                .describe('"full" returns headers + body + attachments; "metadata" returns headers only; "minimal" returns just labels/snippet.'),
+        }),
+        execute: async (args, { log }) => {
+            const gmail = await getGmailClient();
+            log.info(`Getting Gmail message ${args.messageId} (format=${args.format})`);
+            try {
+                const response = await gmail.users.messages.get({
+                    userId: 'me',
+                    id: args.messageId,
+                    format: args.format,
+                });
+                const msg = response.data;
+                const headers = msg.payload?.headers;
+                const base = {
+                    id: msg.id,
+                    threadId: msg.threadId,
+                    labelIds: msg.labelIds ?? [],
+                    snippet: msg.snippet ?? '',
+                    historyId: msg.historyId,
+                    internalDate: msg.internalDate,
+                    sizeEstimate: msg.sizeEstimate,
+                };
+                if (args.format === 'minimal') {
+                    return JSON.stringify(base, null, 2);
+                }
+                const headerSummary = {
+                    from: findHeaderValue(headers, 'From'),
+                    to: findHeaderValue(headers, 'To'),
+                    cc: findHeaderValue(headers, 'Cc'),
+                    bcc: findHeaderValue(headers, 'Bcc'),
+                    subject: findHeaderValue(headers, 'Subject'),
+                    date: findHeaderValue(headers, 'Date'),
+                    messageIdHeader: findHeaderValue(headers, 'Message-Id'),
+                };
+                if (args.format === 'metadata') {
+                    return JSON.stringify({ ...base, headers: headerSummary }, null, 2);
+                }
+                const { text, html } = extractMessageBody(msg.payload);
+                const attachments = collectAttachments(msg.payload);
+                return JSON.stringify({
+                    ...base,
+                    headers: headerSummary,
+                    body: { text, html },
+                    attachments,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error getting Gmail message: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Gmail message not found (ID: ${args.messageId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the gmail.modify scope was granted.');
+                throw new UserError(`Failed to get Gmail message: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/gmail/helpers.js

@@ -0,0 +1,113 @@
+export function findHeaderValue(headers, name) {
+    if (!headers)
+        return null;
+    return headers.find((h) => h.name?.toLowerCase() === name.toLowerCase())?.value ?? null;
+}
+export function encodeHeader(value) {
+    // RFC 2047 encoded-word for any non-ASCII content in headers.
+    if (/^[\x00-\x7F]*$/.test(value))
+        return value;
+    return `=?UTF-8?B?${Buffer.from(value, 'utf-8').toString('base64')}?=`;
+}
+export function buildMimeMessage(opts) {
+    const lines = [];
+    lines.push(`To: ${opts.to.join(', ')}`);
+    if (opts.cc && opts.cc.length > 0)
+        lines.push(`Cc: ${opts.cc.join(', ')}`);
+    if (opts.bcc && opts.bcc.length > 0)
+        lines.push(`Bcc: ${opts.bcc.join(', ')}`);
+    lines.push(`Subject: ${encodeHeader(opts.subject)}`);
+    lines.push('MIME-Version: 1.0');
+    lines.push('Content-Type: text/plain; charset="UTF-8"');
+    lines.push('Content-Transfer-Encoding: 8bit');
+    if (opts.inReplyTo)
+        lines.push(`In-Reply-To: ${opts.inReplyTo}`);
+    if (opts.references)
+        lines.push(`References: ${opts.references}`);
+    lines.push('');
+    lines.push(opts.body);
+    return lines.join('\r\n');
+}
+export function encodeRawMessage(mime) {
+    return Buffer.from(mime, 'utf-8').toString('base64url');
+}
+/**
+ * Fetches the original message and returns the headers needed to build a
+ * threaded reply (Message-Id for In-Reply-To, References chain, threadId).
+ */
+export async function getReplyContext(gmail, messageId) {
+    const original = await gmail.users.messages.get({
+        userId: 'me',
+        id: messageId,
+        format: 'metadata',
+        metadataHeaders: ['Message-Id', 'References', 'Subject'],
+    });
+    const threadId = original.data.threadId ?? undefined;
+    const origHeaders = original.data.payload?.headers;
+    const inReplyTo = findHeaderValue(origHeaders, 'Message-Id');
+    const origRefs = findHeaderValue(origHeaders, 'References');
+    const references = [origRefs, inReplyTo].filter(Boolean).join(' ') || null;
+    return { threadId, inReplyTo, references };
+}
+/**
+ * Resolves reply threading context (if any), builds the MIME message, and
+ * returns the base64url-encoded raw + threadId ready for messages.send,
+ * drafts.create, or drafts.update. Centralizes the compose pipeline so all
+ * three call sites stay in sync on threading and MIME formatting.
+ */
+export async function prepareMimeRequest(gmail, args) {
+    const toList = Array.isArray(args.to) ? args.to : [args.to];
+    let threadId;
+    let inReplyTo = null;
+    let references = null;
+    if (args.replyToMessageId) {
+        const ctx = await getReplyContext(gmail, args.replyToMessageId);
+        threadId = ctx.threadId;
+        inReplyTo = ctx.inReplyTo;
+        references = ctx.references;
+    }
+    const raw = encodeRawMessage(buildMimeMessage({
+        to: toList,
+        cc: args.cc,
+        bcc: args.bcc,
+        subject: args.subject,
+        body: args.body,
+        inReplyTo,
+        references,
+    }));
+    return { raw, threadId, toList };
+}
+export function decodeBase64Url(data) {
+    if (!data)
+        return '';
+    return Buffer.from(data, 'base64url').toString('utf-8');
+}
+/**
+ * Walks a Gmail message payload tree and accumulates all text/plain and
+ * text/html parts. Returns both representations so callers can pick the
+ * one they want (text for processing, html for display).
+ */
+export function extractMessageBody(payload) {
+    let text = '';
+    let html = '';
+    if (!payload)
+        return { text, html };
+    const walk = (part) => {
+        const mime = part.mimeType ?? '';
+        if (mime === 'text/plain' && part.body?.data)
+            text += decodeBase64Url(part.body.data);
+        else if (mime === 'text/html' && part.body?.data)
+            html += decodeBase64Url(part.body.data);
+        if (part.parts)
+            for (const sub of part.parts)
+                walk(sub);
+    };
+    walk(payload);
+    return { text, html };
+}
+export function extractDomain(fromHeader) {
+    if (!fromHeader)
+        return null;
+    const match = fromHeader.match(/<?([^@<>\s]+)@([^>\s]+)>?/);
+    return match ? match[2].toLowerCase() : null;
+}

package/dist/tools/gmail/index.js

@@ -0,0 +1,28 @@
+import { register as listMessages } from './listMessages.js';
+import { register as getMessage } from './getMessage.js';
+import { register as sendEmail } from './sendEmail.js';
+import { register as trashMessage } from './trashMessage.js';
+import { register as modifyMessageLabels } from './modifyMessageLabels.js';
+import { register as listLabels } from './listLabels.js';
+import { register as createDraft } from './createDraft.js';
+import { register as listDrafts } from './listDrafts.js';
+import { register as getDraft } from './getDraft.js';
+import { register as updateDraft } from './updateDraft.js';
+import { register as sendDraft } from './sendDraft.js';
+import { register as deleteDraft } from './deleteDraft.js';
+import { register as triageInbox } from './triageInbox.js';
+export function registerGmailTools(server) {
+    listMessages(server);
+    getMessage(server);
+    sendEmail(server);
+    trashMessage(server);
+    modifyMessageLabels(server);
+    listLabels(server);
+    createDraft(server);
+    listDrafts(server);
+    getDraft(server);
+    updateDraft(server);
+    sendDraft(server);
+    deleteDraft(server);
+    triageInbox(server);
+}

package/dist/tools/gmail/listDrafts.js

@@ -0,0 +1,74 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getGmailClient } from '../../clients.js';
+import { findHeaderValue } from './helpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'listDrafts',
+        description: 'Lists Gmail drafts for the authenticated user. Returns draft IDs along with the recipient, subject, snippet, and date for each. Use sendDraft, updateDraft, or deleteDraft to act on a returned draft.',
+        parameters: z.strictObject({
+            maxResults: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .default(25)
+                .describe('Maximum number of drafts to return (1-100). Defaults to 25.'),
+            q: z
+                .string()
+                .optional()
+                .describe('Optional Gmail search query to filter drafts (e.g. "subject:proposal").'),
+        }),
+        execute: async (args, { log }) => {
+            const gmail = await getGmailClient();
+            log.info(`Listing Gmail drafts (max=${args.maxResults})`);
+            try {
+                const listResponse = await gmail.users.drafts.list({
+                    userId: 'me',
+                    maxResults: args.maxResults,
+                    q: args.q,
+                });
+                const draftRefs = listResponse.data.drafts ?? [];
+                if (draftRefs.length === 0) {
+                    return JSON.stringify({
+                        drafts: [],
+                        resultSizeEstimate: listResponse.data.resultSizeEstimate ?? 0,
+                        nextPageToken: listResponse.data.nextPageToken ?? null,
+                    }, null, 2);
+                }
+                const detailed = await Promise.all(draftRefs.map((ref) => gmail.users.drafts.get({
+                    userId: 'me',
+                    id: ref.id,
+                    format: 'metadata',
+                })));
+                const drafts = detailed.map((response) => {
+                    const draft = response.data;
+                    const msg = draft.message;
+                    const headers = msg?.payload?.headers;
+                    return {
+                        draftId: draft.id,
+                        messageId: msg?.id,
+                        threadId: msg?.threadId,
+                        snippet: msg?.snippet ?? '',
+                        to: findHeaderValue(headers, 'To'),
+                        cc: findHeaderValue(headers, 'Cc'),
+                        subject: findHeaderValue(headers, 'Subject'),
+                        date: findHeaderValue(headers, 'Date'),
+                    };
+                });
+                return JSON.stringify({
+                    drafts,
+                    resultSizeEstimate: listResponse.data.resultSizeEstimate ?? drafts.length,
+                    nextPageToken: listResponse.data.nextPageToken ?? null,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing drafts: ${error.message || error}`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the gmail.modify scope was granted.');
+                throw new UserError(`Failed to list drafts: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/gmail/listLabels.js

@@ -0,0 +1,31 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getGmailClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'listLabels',
+        description: 'Lists all Gmail labels for the authenticated user, including system labels (INBOX, SENT, STARRED, UNREAD, etc.) and custom user-created labels. Use the returned IDs with modifyMessageLabels or listMessages labelIds filter.',
+        parameters: z.strictObject({}),
+        execute: async (_args, { log }) => {
+            const gmail = await getGmailClient();
+            log.info('Listing Gmail labels');
+            try {
+                const response = await gmail.users.labels.list({ userId: 'me' });
+                const labels = (response.data.labels ?? []).map((label) => ({
+                    id: label.id,
+                    name: label.name,
+                    type: label.type,
+                    messageListVisibility: label.messageListVisibility,
+                    labelListVisibility: label.labelListVisibility,
+                }));
+                return JSON.stringify({ labels, count: labels.length }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing Gmail labels: ${error.message || error}`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the gmail.modify scope was granted.');
+                throw new UserError(`Failed to list Gmail labels: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/gmail/listMessages.js

@@ -0,0 +1,87 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getGmailClient } from '../../clients.js';
+import { findHeaderValue } from './helpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'listMessages',
+        description: 'Lists Gmail messages for the authenticated user. Supports the full Gmail search syntax via the q parameter (e.g. "is:unread", "from:alice@example.com", "subject:invoice newer_than:7d"). Returns message IDs with sender, subject, date, and snippet for each result.',
+        parameters: z.strictObject({
+            maxResults: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .default(10)
+                .describe('Maximum number of messages to return (1-100). Defaults to 10.'),
+            q: z
+                .string()
+                .optional()
+                .describe('Gmail search query using the same syntax as the Gmail search box. Examples: "is:unread", "from:boss@acme.com", "has:attachment newer_than:3d".'),
+            labelIds: z
+                .array(z.string())
+                .optional()
+                .describe('Only return messages with these label IDs (e.g. ["INBOX"], ["STARRED"]). Use listLabels to discover custom label IDs.'),
+            includeSpamTrash: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, also include messages from SPAM and TRASH.'),
+        }),
+        execute: async (args, { log }) => {
+            const gmail = await getGmailClient();
+            log.info(`Listing Gmail messages (max=${args.maxResults}, q=${args.q ?? 'none'}, labels=${args.labelIds?.join(',') ?? 'none'})`);
+            try {
+                const listResponse = await gmail.users.messages.list({
+                    userId: 'me',
+                    maxResults: args.maxResults,
+                    q: args.q,
+                    labelIds: args.labelIds,
+                    includeSpamTrash: args.includeSpamTrash,
+                });
+                const messageRefs = listResponse.data.messages ?? [];
+                if (messageRefs.length === 0) {
+                    return JSON.stringify({
+                        messages: [],
+                        resultSizeEstimate: listResponse.data.resultSizeEstimate ?? 0,
+                        nextPageToken: listResponse.data.nextPageToken ?? null,
+                    }, null, 2);
+                }
+                const detailed = await Promise.all(messageRefs.map((ref) => gmail.users.messages.get({
+                    userId: 'me',
+                    id: ref.id,
+                    format: 'metadata',
+                    metadataHeaders: ['From', 'To', 'Subject', 'Date'],
+                })));
+                const messages = detailed.map((response) => {
+                    const msg = response.data;
+                    const headers = msg.payload?.headers;
+                    return {
+                        id: msg.id,
+                        threadId: msg.threadId,
+                        labelIds: msg.labelIds ?? [],
+                        snippet: msg.snippet ?? '',
+                        from: findHeaderValue(headers, 'From'),
+                        to: findHeaderValue(headers, 'To'),
+                        subject: findHeaderValue(headers, 'Subject'),
+                        date: findHeaderValue(headers, 'Date'),
+                    };
+                });
+                return JSON.stringify({
+                    messages,
+                    resultSizeEstimate: listResponse.data.resultSizeEstimate ?? messages.length,
+                    nextPageToken: listResponse.data.nextPageToken ?? null,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error listing Gmail messages: ${error.message || error}`);
+                if (error.code === 401)
+                    throw new UserError('Gmail authorization failed. Re-authorize the MCP server (scopes may have changed).');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the Gmail API is enabled and the gmail.modify scope was granted during consent.');
+                throw new UserError(`Failed to list Gmail messages: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/gmail/modifyMessageLabels.js

@@ -0,0 +1,54 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getGmailClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'modifyMessageLabels',
+        description: 'Adds and/or removes labels on a Gmail message. Use this to star (add STARRED), archive (remove INBOX), mark read (remove UNREAD), or apply custom labels. Discover label IDs with listLabels. At least one of addLabelIds or removeLabelIds must be provided.',
+        parameters: z
+            .object({
+            messageId: z.string().describe('The Gmail message ID to modify.'),
+            addLabelIds: z
+                .array(z.string())
+                .optional()
+                .describe('Label IDs to add (e.g. ["STARRED"], ["IMPORTANT"], or a custom label ID from listLabels).'),
+            removeLabelIds: z
+                .array(z.string())
+                .optional()
+                .describe('Label IDs to remove (e.g. ["INBOX"] to archive, ["UNREAD"] to mark as read).'),
+        })
+            .refine((v) => (v.addLabelIds && v.addLabelIds.length > 0) ||
+            (v.removeLabelIds && v.removeLabelIds.length > 0), { message: 'Provide at least one of addLabelIds or removeLabelIds.' }),
+        execute: async (args, { log }) => {
+            const gmail = await getGmailClient();
+            log.info(`Modifying labels on ${args.messageId} (add=${args.addLabelIds?.join(',') ?? 'none'}, remove=${args.removeLabelIds?.join(',') ?? 'none'})`);
+            try {
+                const response = await gmail.users.messages.modify({
+                    userId: 'me',
+                    id: args.messageId,
+                    requestBody: {
+                        addLabelIds: args.addLabelIds,
+                        removeLabelIds: args.removeLabelIds,
+                    },
+                });
+                return JSON.stringify({
+                    success: true,
+                    id: response.data.id,
+                    threadId: response.data.threadId,
+                    labelIds: response.data.labelIds ?? [],
+                    message: `Labels updated on message ${args.messageId}.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error modifying labels: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Gmail message or label not found. Verify messageId and label IDs (use listLabels).`);
+                if (error.code === 400)
+                    throw new UserError(`Gmail rejected the label change: ${error.message || 'Bad request'}. Some system labels (e.g. DRAFT, SENT) cannot be applied manually.`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. Confirm the gmail.modify scope was granted.');
+                throw new UserError(`Failed to modify labels: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/gmail/sendDraft.js

@@ -0,0 +1,42 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getGmailClient } from '../../clients.js';
+export function register(server) {
+    server.addTool({
+        name: 'sendDraft',
+        description: 'Sends an existing Gmail draft. After sending, the draft is removed and the message appears in Sent. This is the second half of the compose-review-send flow that pairs with createDraft.',
+        parameters: z.strictObject({
+            draftId: z.string().describe('The Gmail draft ID to send (from createDraft or listDrafts).'),
+        }),
+        execute: async (args, { log }) => {
+            const gmail = await getGmailClient();
+            log.info(`Sending Gmail draft ${args.draftId}`);
+            try {
+                const response = await gmail.users.drafts.send({
+                    userId: 'me',
+                    requestBody: {
+                        id: args.draftId,
+                    },
+                });
+                return JSON.stringify({
+                    success: true,
+                    draftId: args.draftId,
+                    messageId: response.data.id,
+                    threadId: response.data.threadId,
+                    labelIds: response.data.labelIds ?? [],
+                    message: `Draft ${args.draftId} sent. Message ID: ${response.data.id}.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error sending draft: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError(`Draft not found (ID: ${args.draftId}).`);
+                if (error.code === 403)
+                    throw new UserError('Permission denied. The account does not have permission to send mail via this OAuth client.');
+                if (error.code === 400)
+                    throw new UserError(`Gmail rejected the send: ${error.message || 'Bad request'}. Verify the draft has at least one recipient and a subject.`);
+                throw new UserError(`Failed to send draft: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/gmail/sendEmail.js

@@ -0,0 +1,56 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getGmailClient } from '../../clients.js';
+import { prepareMimeRequest } from './helpers.js';
+export function register(server) {
+    server.addTool({
+        name: 'sendEmail',
+        description: 'Sends a plain-text email from the authenticated Gmail account. Supports cc/bcc and optional threading by passing replyToMessageId (which copies threadId and sets In-Reply-To/References so the reply lands in the same thread).',
+        parameters: z.strictObject({
+            to: z
+                .union([z.string(), z.array(z.string()).min(1)])
+                .describe('Recipient email address, or an array of recipient email addresses.'),
+            subject: z.string().describe('Email subject line.'),
+            body: z.string().describe('Plain-text body of the email.'),
+            cc: z.array(z.string()).optional().describe('Optional list of Cc recipients.'),
+            bcc: z.array(z.string()).optional().describe('Optional list of Bcc recipients.'),
+            replyToMessageId: z
+                .string()
+                .optional()
+                .describe('Optional Gmail message ID to reply to. When set, the new email is threaded with the original and uses In-Reply-To/References headers.'),
+        }),
+        execute: async (args, { log }) => {
+            const gmail = await getGmailClient();
+            try {
+                const { raw, threadId, toList } = await prepareMimeRequest(gmail, args);
+                log.info(`Sending Gmail message to ${toList.join(', ')}${args.replyToMessageId ? ` (reply to ${args.replyToMessageId})` : ''}`);
+                const send = await gmail.users.messages.send({
+                    userId: 'me',
+                    requestBody: {
+                        raw,
+                        ...(threadId ? { threadId } : {}),
+                    },
+                });
+                return JSON.stringify({
+                    success: true,
+                    id: send.data.id,
+                    threadId: send.data.threadId,
+                    labelIds: send.data.labelIds ?? [],
+                    to: toList,
+                    subject: args.subject,
+                    message: `Email sent to ${toList.join(', ')}.`,
+                }, null, 2);
+            }
+            catch (error) {
+                log.error(`Error sending Gmail message: ${error.message || error}`);
+                if (error.code === 401)
+                    throw new UserError('Gmail authorization failed. Re-authorize to grant the gmail.modify scope.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. The account does not have permission to send mail via this OAuth client.');
+                if (error.code === 400)
+                    throw new UserError(`Gmail rejected the message: ${error.message || 'Bad request'}`);
+                throw new UserError(`Failed to send email: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}