gmail-workspace-mcp-server 0.0.3 → 0.0.5

package/shared/tools/draft-email.js

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { getHeader } from '../utils/email-helpers.js';
+const PARAM_DESCRIPTIONS = {
+    to: 'Recipient email address(es). For multiple recipients, separate with commas.',
+    subject: 'Subject line of the email.',
+    body: 'Plain text body content of the email.',
+    cc: 'CC recipient email address(es). For multiple, separate with commas.',
+    bcc: 'BCC recipient email address(es). For multiple, separate with commas.',
+    thread_id: 'Thread ID to add this draft to an existing conversation. ' +
+        'Get this from get_email_conversation. If provided, the draft will be a reply in that thread.',
+    reply_to_email_id: 'Email ID to reply to. If provided, the draft will be formatted as a reply ' +
+        'with proper In-Reply-To and References headers. Also requires thread_id.',
+};
+export const DraftEmailSchema = z.object({
+    to: z.string().min(1).describe(PARAM_DESCRIPTIONS.to),
+    subject: z.string().min(1).describe(PARAM_DESCRIPTIONS.subject),
+    body: z.string().min(1).describe(PARAM_DESCRIPTIONS.body),
+    cc: z.string().optional().describe(PARAM_DESCRIPTIONS.cc),
+    bcc: z.string().optional().describe(PARAM_DESCRIPTIONS.bcc),
+    thread_id: z.string().optional().describe(PARAM_DESCRIPTIONS.thread_id),
+    reply_to_email_id: z.string().optional().describe(PARAM_DESCRIPTIONS.reply_to_email_id),
+});
+const TOOL_DESCRIPTION = `Create a draft email that can be reviewed and sent later.
+
+**Parameters:**
+- to: Recipient email address(es) (required)
+- subject: Email subject line (required)
+- body: Plain text body content (required)
+- cc: CC recipients (optional)
+- bcc: BCC recipients (optional)
+- thread_id: Thread ID to reply to an existing conversation (optional)
+- reply_to_email_id: Email ID to reply to, sets proper reply headers (optional)
+
+**Creating a reply:**
+To create a draft reply to an existing email:
+1. Get the thread_id and email_id from get_email_conversation
+2. Provide both thread_id and reply_to_email_id parameters
+
+**Use cases:**
+- Draft a new email for later review
+- Prepare a reply to an email conversation
+- Save an email without sending it immediately
+
+**Note:** The draft will be saved in Gmail's Drafts folder. Use send_email with from_draft_id to send it.`;
+export function draftEmailTool(server, clientFactory) {
+    return {
+        name: 'draft_email',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                to: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.to,
+                },
+                subject: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.subject,
+                },
+                body: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.body,
+                },
+                cc: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.cc,
+                },
+                bcc: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.bcc,
+                },
+                thread_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.thread_id,
+                },
+                reply_to_email_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.reply_to_email_id,
+                },
+            },
+            required: ['to', 'subject', 'body'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = DraftEmailSchema.parse(args ?? {});
+                const client = clientFactory();
+                let inReplyTo;
+                let references;
+                // If replying to an email, get the Message-ID for proper threading
+                if (parsed.reply_to_email_id && parsed.thread_id) {
+                    const originalEmail = await client.getMessage(parsed.reply_to_email_id, {
+                        format: 'metadata',
+                        metadataHeaders: ['Message-ID', 'References'],
+                    });
+                    const messageId = getHeader(originalEmail, 'Message-ID');
+                    const originalReferences = getHeader(originalEmail, 'References');
+                    if (messageId) {
+                        inReplyTo = messageId;
+                        // Build references chain
+                        references = originalReferences ? `${originalReferences} ${messageId}` : messageId;
+                    }
+                }
+                const draft = await client.createDraft({
+                    to: parsed.to,
+                    subject: parsed.subject,
+                    body: parsed.body,
+                    cc: parsed.cc,
+                    bcc: parsed.bcc,
+                    threadId: parsed.thread_id,
+                    inReplyTo,
+                    references,
+                });
+                let responseText = `Draft created successfully!\n\n**Draft ID:** ${draft.id}`;
+                if (parsed.thread_id) {
+                    responseText += `\n**Thread ID:** ${parsed.thread_id}`;
+                    responseText += '\n\nThis draft is a reply in an existing conversation.';
+                }
+                responseText += `\n\n**To:** ${parsed.to}`;
+                responseText += `\n**Subject:** ${parsed.subject}`;
+                if (parsed.cc) {
+                    responseText += `\n**CC:** ${parsed.cc}`;
+                }
+                if (parsed.bcc) {
+                    responseText += `\n**BCC:** ${parsed.bcc}`;
+                }
+                responseText +=
+                    "\n\nUse send_email with from_draft_id parameter to send this draft, or find it in Gmail's Drafts folder.";
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error creating draft: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/{get-email.d.ts → get-email-conversation.d.ts}

@@ -1,14 +1,17 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { z } from 'zod';
 import type { ClientFactory } from '../server.js';
-export declare const GetEmailSchema: z.ZodObject<{
+export declare const GetEmailConversationSchema: z.ZodObject<{
     email_id: z.ZodString;
+    include_html: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     email_id: string;
+    include_html?: boolean | undefined;
 }, {
     email_id: string;
+    include_html?: boolean | undefined;
 }>;
-export declare function getEmailTool(server: Server, clientFactory: ClientFactory): {
+export declare function getEmailConversationTool(server: Server, clientFactory: ClientFactory): {
     name: string;
     description: string;
     inputSchema: {
@@ -18,6 +21,10 @@ export declare function getEmailTool(server: Server, clientFactory: ClientFactor
                 type: string;
                 description: string;
             };
+            include_html: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };

package/shared/tools/{get-email.js → get-email-conversation.js}

@@ -2,31 +2,38 @@ import { z } from 'zod';
 import { getHeader } from '../utils/email-helpers.js';
 const PARAM_DESCRIPTIONS = {
     email_id: 'The unique identifier of the email to retrieve. ' +
-        'Obtain this from gmail_list_recent_emails.',
+        'Obtain this from list_email_conversations or search_email_conversations.',
+    include_html: 'When true, includes the raw HTML body of the email (if available) in addition to the plain text. ' +
+        'Useful for rendering emails with original formatting, creating screenshots, or archival workflows.',
 };
-export const GetEmailSchema = z.object({
+export const GetEmailConversationSchema = z.object({
     email_id: z.string().min(1).describe(PARAM_DESCRIPTIONS.email_id),
+    include_html: z.boolean().optional().describe(PARAM_DESCRIPTIONS.include_html),
 });
-const TOOL_DESCRIPTION = `Retrieve the full content of a specific email by its ID.
+const TOOL_DESCRIPTION = `Retrieve the full content of a specific email conversation by its ID.
 
 Returns the complete email including headers, body content, and attachment information.
 
 **Parameters:**
 - email_id: The unique identifier of the email (required)
+- include_html: When true, includes raw HTML body in addition to plain text (optional)
 
 **Returns:**
 Full email details including:
 - Subject, From, To, Cc, Date headers
 - Full message body (plain text preferred, HTML as fallback)
+- Raw HTML body (when include_html is true and HTML content is available)
 - List of attachments (if any)
 - Labels assigned to the email
 
 **Use cases:**
-- Read the full content of an email after listing recent emails
+- Read the full content of an email after listing conversations
 - Extract specific information from an email body
 - Check attachment details
+- Render emails with original HTML formatting (use include_html: true)
+- Create email screenshots or archives with original styling
 
-**Note:** Use gmail_list_recent_emails first to get email IDs.`;
+**Note:** Use list_email_conversations or search_email_conversations first to get email IDs.`;
 /**
  * Decodes base64url encoded content
  */
@@ -84,6 +91,22 @@ function getEmailBody(email) {
     }
     return '(No body content available)';
 }
+/**
+ * Gets the raw HTML body content from an email (if available)
+ */
+function getEmailHtmlBody(email) {
+    // Check if body is directly on payload and it's HTML
+    if (email.payload?.body?.data && email.payload.mimeType === 'text/html') {
+        return decodeBase64Url(email.payload.body.data);
+    }
+    // Try to extract HTML from parts
+    if (email.payload?.parts) {
+        const html = extractBodyContent(email.payload.parts, 'text/html');
+        if (html)
+            return html;
+    }
+    return null;
+}
 /**
  * Extracts attachment information from email parts
  */
@@ -108,7 +131,7 @@ function getAttachments(parts) {
 /**
  * Formats an email for display
  */
-function formatFullEmail(email) {
+function formatFullEmail(email, options) {
     const subject = getHeader(email, 'Subject') || '(No Subject)';
     const from = getHeader(email, 'From') || 'Unknown';
     const to = getHeader(email, 'To') || 'Unknown';
@@ -136,6 +159,26 @@ function formatFullEmail(email) {
 ## Body
 
 ${body}`;
+    // Include raw HTML body if requested
+    if (options?.includeHtml) {
+        const htmlBody = getEmailHtmlBody(email);
+        if (htmlBody) {
+            output += `
+
+## HTML Body
+
+\`\`\`html
+${htmlBody}
+\`\`\``;
+        }
+        else {
+            output += `
+
+## HTML Body
+
+(No HTML content available)`;
+        }
+    }
     if (attachments.length > 0) {
         output += `\n\n## Attachments (${attachments.length})\n`;
         attachments.forEach((att, i) => {
@@ -145,9 +188,9 @@ ${body}`;
     }
     return output;
 }
-export function getEmailTool(server, clientFactory) {
+export function getEmailConversationTool(server, clientFactory) {
     return {
-        name: 'gmail_get_email',
+        name: 'get_email_conversation',
         description: TOOL_DESCRIPTION,
         inputSchema: {
             type: 'object',
@@ -156,17 +199,23 @@ export function getEmailTool(server, clientFactory) {
                     type: 'string',
                     description: PARAM_DESCRIPTIONS.email_id,
                 },
+                include_html: {
+                    type: 'boolean',
+                    description: PARAM_DESCRIPTIONS.include_html,
+                },
             },
             required: ['email_id'],
         },
         handler: async (args) => {
             try {
-                const parsed = GetEmailSchema.parse(args ?? {});
+                const parsed = GetEmailConversationSchema.parse(args ?? {});
                 const client = clientFactory();
                 const email = await client.getMessage(parsed.email_id, {
                     format: 'full',
                 });
-                const formattedEmail = formatFullEmail(email);
+                const formattedEmail = formatFullEmail(email, {
+                    includeHtml: parsed.include_html,
+                });
                 return {
                     content: [
                         {

package/shared/tools/{list-recent-emails.d.ts → list-email-conversations.d.ts}

@@ -1,39 +1,54 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { z } from 'zod';
 import type { ClientFactory } from '../server.js';
-export declare const ListRecentEmailsSchema: z.ZodObject<{
-    hours: z.ZodDefault<z.ZodNumber>;
+export declare const ListEmailConversationsSchema: z.ZodObject<{
+    count: z.ZodDefault<z.ZodNumber>;
     labels: z.ZodDefault<z.ZodOptional<z.ZodString>>;
-    max_results: z.ZodDefault<z.ZodNumber>;
+    sort_by: z.ZodDefault<z.ZodEnum<["recent", "oldest"]>>;
+    after: z.ZodOptional<z.ZodString>;
+    before: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    hours: number;
+    count: number;
     labels: string;
-    max_results: number;
+    sort_by: "recent" | "oldest";
+    after?: string | undefined;
+    before?: string | undefined;
 }, {
-    hours?: number | undefined;
+    count?: number | undefined;
     labels?: string | undefined;
-    max_results?: number | undefined;
+    sort_by?: "recent" | "oldest" | undefined;
+    after?: string | undefined;
+    before?: string | undefined;
 }>;
-export declare function listRecentEmailsTool(server: Server, clientFactory: ClientFactory): {
+export declare function listEmailConversationsTool(server: Server, clientFactory: ClientFactory): {
     name: string;
     description: string;
     inputSchema: {
         type: "object";
         properties: {
-            hours: {
+            count: {
                 type: string;
                 default: number;
-                description: string;
+                description: "Maximum number of email conversations to return. Default: 10. Max: 100.";
             };
             labels: {
                 type: string;
                 default: string;
                 description: string;
             };
-            max_results: {
+            sort_by: {
                 type: string;
-                default: number;
-                description: "Maximum number of emails to return. Default: 10. Max: 100.";
+                enum: string[];
+                default: string;
+                description: string;
+            };
+            after: {
+                type: string;
+                description: string;
+            };
+            before: {
+                type: string;
+                description: string;
             };
         };
         required: never[];

package/shared/tools/list-email-conversations.js

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+import { formatEmail } from '../utils/email-helpers.js';
+const PARAM_DESCRIPTIONS = {
+    count: 'Maximum number of email conversations to return. Default: 10. Max: 100.',
+    labels: 'Comma-separated list of label IDs to filter by. Default: INBOX. ' +
+        'Common labels: INBOX, SENT, DRAFTS, SPAM, TRASH, STARRED, IMPORTANT, UNREAD.',
+    sort_by: 'Sort order for results. Default: recent. ' +
+        'Options: recent (newest first), oldest (oldest first).',
+    after: 'Only return emails after this datetime (exclusive). ' +
+        'ISO 8601 format in UTC (e.g., 2024-01-15T14:30:00Z).',
+    before: 'Only return emails before this datetime (exclusive). ' +
+        'ISO 8601 format in UTC (e.g., 2024-01-15T14:30:00Z).',
+};
+export const ListEmailConversationsSchema = z.object({
+    count: z.number().positive().max(100).default(10).describe(PARAM_DESCRIPTIONS.count),
+    labels: z.string().optional().default('INBOX').describe(PARAM_DESCRIPTIONS.labels),
+    sort_by: z.enum(['recent', 'oldest']).default('recent').describe(PARAM_DESCRIPTIONS.sort_by),
+    after: z.string().optional().describe(PARAM_DESCRIPTIONS.after),
+    before: z.string().optional().describe(PARAM_DESCRIPTIONS.before),
+});
+const TOOL_DESCRIPTION = `List email conversations from Gmail.
+
+Returns a list of email conversations with their subject, sender, date, and a snippet preview. Use get_email_conversation to retrieve the full content of a specific conversation.
+
+**Parameters:**
+- count: Maximum conversations to return (default: 10, max: 100)
+- labels: Which labels/folders to search (default: INBOX)
+- sort_by: Sort order - "recent" (newest first) or "oldest" (default: recent)
+- after: Only return emails after this datetime, exclusive (ISO 8601 UTC, e.g., 2024-01-15T14:30:00Z)
+- before: Only return emails before this datetime, exclusive (ISO 8601 UTC, e.g., 2024-01-15T14:30:00Z)
+
+**Returns:**
+A formatted list of email conversations with:
+- Email ID (needed for get_email_conversation)
+- Thread ID
+- Subject line
+- Sender (From)
+- Date received
+- Snippet preview
+
+**Use cases:**
+- Check recent inbox activity
+- List emails from specific labels like SENT or STARRED
+- Get oldest emails first for processing backlogs
+- Filter emails by date/time range using after and/or before
+
+**Note:** This tool only returns email metadata and snippets. Use get_email_conversation with an email ID to retrieve the full message content.`;
+export function listEmailConversationsTool(server, clientFactory) {
+    return {
+        name: 'list_email_conversations',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                count: {
+                    type: 'number',
+                    default: 10,
+                    description: PARAM_DESCRIPTIONS.count,
+                },
+                labels: {
+                    type: 'string',
+                    default: 'INBOX',
+                    description: PARAM_DESCRIPTIONS.labels,
+                },
+                sort_by: {
+                    type: 'string',
+                    enum: ['recent', 'oldest'],
+                    default: 'recent',
+                    description: PARAM_DESCRIPTIONS.sort_by,
+                },
+                after: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.after,
+                },
+                before: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.before,
+                },
+            },
+            required: [],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = ListEmailConversationsSchema.parse(args ?? {});
+                const client = clientFactory();
+                // Parse labels
+                const labelIds = parsed.labels.split(',').map((l) => l.trim().toUpperCase());
+                // Build query string for datetime filtering
+                // Gmail uses Unix timestamps (seconds since epoch) for after: and before: operators
+                const queryParts = [];
+                if (parsed.after) {
+                    const timestamp = Math.floor(new Date(parsed.after).getTime() / 1000);
+                    queryParts.push(`after:${timestamp}`);
+                }
+                if (parsed.before) {
+                    const timestamp = Math.floor(new Date(parsed.before).getTime() / 1000);
+                    queryParts.push(`before:${timestamp}`);
+                }
+                const query = queryParts.length > 0 ? queryParts.join(' ') : undefined;
+                // List messages
+                const { messages } = await client.listMessages({
+                    maxResults: parsed.count,
+                    labelIds,
+                    q: query,
+                });
+                if (messages.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `No email conversations found with labels: ${labelIds.join(', ')}`,
+                            },
+                        ],
+                    };
+                }
+                // Fetch full details for each message
+                const emailDetails = await Promise.all(messages.map((msg) => client.getMessage(msg.id, {
+                    format: 'metadata',
+                    metadataHeaders: ['Subject', 'From', 'Date'],
+                })));
+                // Sort based on sort_by parameter
+                const sortedEmails = [...emailDetails].sort((a, b) => {
+                    const dateA = parseInt(a.internalDate, 10);
+                    const dateB = parseInt(b.internalDate, 10);
+                    return parsed.sort_by === 'recent' ? dateB - dateA : dateA - dateB;
+                });
+                const formattedEmails = sortedEmails.map(formatEmail).join('\n\n---\n\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${messages.length} email conversation(s):\n\n${formattedEmails}`,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error listing email conversations: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/search-email-conversations.d.ts

@@ -0,0 +1,45 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const SearchEmailConversationsSchema: z.ZodObject<{
+    query: z.ZodString;
+    count: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    count: number;
+    query: string;
+}, {
+    query: string;
+    count?: number | undefined;
+}>;
+export declare function searchEmailConversationsTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            query: {
+                type: string;
+                description: string;
+            };
+            count: {
+                type: string;
+                default: number;
+                description: "Maximum number of results to return. Default: 10. Max: 100.";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};