gmail-workspace-mcp-server 0.0.3 → 0.0.4

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,14 @@
 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;
 }, "strip", z.ZodTypeAny, {
     email_id: string;
 }, {
     email_id: string;
 }>;
-export declare function getEmailTool(server: Server, clientFactory: ClientFactory): {
+export declare function getEmailConversationTool(server: Server, clientFactory: ClientFactory): {
     name: string;
     description: string;
     inputSchema: {

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

@@ -2,12 +2,12 @@ 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.',
 };
-export const GetEmailSchema = z.object({
+export const GetEmailConversationSchema = z.object({
     email_id: z.string().min(1).describe(PARAM_DESCRIPTIONS.email_id),
 });
-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.
 
@@ -22,11 +22,11 @@ Full email details including:
 - 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
 
-**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
  */
@@ -145,9 +145,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',
@@ -161,7 +161,7 @@ export function getEmailTool(server, clientFactory) {
         },
         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',

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;
+    }>;
+};

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

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { formatEmail } from '../utils/email-helpers.js';
+const PARAM_DESCRIPTIONS = {
+    query: 'Gmail search query. Supports all Gmail search operators. ' +
+        'Examples: "from:user@example.com", "subject:meeting", "is:unread", "has:attachment", ' +
+        '"after:2024/01/01", "before:2024/12/31", "in:inbox", "newer_than:7d".',
+    count: 'Maximum number of results to return. Default: 10. Max: 100.',
+};
+export const SearchEmailConversationsSchema = z.object({
+    query: z.string().min(1).describe(PARAM_DESCRIPTIONS.query),
+    count: z.number().positive().max(100).default(10).describe(PARAM_DESCRIPTIONS.count),
+});
+const TOOL_DESCRIPTION = `Search email conversations using Gmail's powerful search syntax.
+
+**Parameters:**
+- query: Gmail search query (required)
+- count: Maximum results to return (default: 10, max: 100)
+
+**Search operators:**
+- from:user@example.com - Emails from specific sender
+- to:user@example.com - Emails sent to specific recipient
+- subject:keyword - Emails with keyword in subject
+- is:unread / is:read - Unread or read emails
+- is:starred - Starred emails
+- has:attachment - Emails with attachments
+- filename:pdf - Emails with specific attachment type
+- after:2024/01/01 - Emails after a date
+- before:2024/12/31 - Emails before a date
+- newer_than:7d - Emails from the last 7 days
+- older_than:1m - Emails older than 1 month
+- in:inbox / in:sent / in:drafts - Emails in specific folder
+- label:work - Emails with specific label
+- "exact phrase" - Search for exact phrase
+
+**Combining operators:**
+- Use spaces to AND operators: "from:alice is:unread"
+- Use OR for alternatives: "from:alice OR from:bob"
+- Use - to exclude: "subject:meeting -subject:canceled"
+
+**Returns:**
+A formatted list of matching emails with ID, Thread ID, Subject, From, Date, and snippet.
+
+**Note:** Use get_email_conversation with an email ID to retrieve full message content.`;
+export function searchEmailConversationsTool(server, clientFactory) {
+    return {
+        name: 'search_email_conversations',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.query,
+                },
+                count: {
+                    type: 'number',
+                    default: 10,
+                    description: PARAM_DESCRIPTIONS.count,
+                },
+            },
+            required: ['query'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = SearchEmailConversationsSchema.parse(args ?? {});
+                const client = clientFactory();
+                // Search messages using the query
+                const { messages } = await client.listMessages({
+                    q: parsed.query,
+                    maxResults: parsed.count,
+                });
+                if (messages.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `No emails found matching query: "${parsed.query}"`,
+                            },
+                        ],
+                    };
+                }
+                // Fetch full details for each message
+                const emailDetails = await Promise.all(messages.map((msg) => client.getMessage(msg.id, {
+                    format: 'metadata',
+                    metadataHeaders: ['Subject', 'From', 'Date'],
+                })));
+                const formattedEmails = emailDetails.map(formatEmail).join('\n\n---\n\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${messages.length} email(s) matching "${parsed.query}":\n\n${formattedEmails}`,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error searching emails: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}