gmail-workspace-mcp-server 0.0.3 → 0.0.4

package/shared/tools/send-email.d.ts

@@ -0,0 +1,104 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const SendEmailSchema: z.ZodEffects<z.ZodObject<{
+    to: z.ZodOptional<z.ZodString>;
+    subject: z.ZodOptional<z.ZodString>;
+    body: z.ZodOptional<z.ZodString>;
+    cc: z.ZodOptional<z.ZodString>;
+    bcc: z.ZodOptional<z.ZodString>;
+    thread_id: z.ZodOptional<z.ZodString>;
+    reply_to_email_id: z.ZodOptional<z.ZodString>;
+    from_draft_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    body?: string | undefined;
+    to?: string | undefined;
+    subject?: string | undefined;
+    cc?: string | undefined;
+    bcc?: string | undefined;
+    thread_id?: string | undefined;
+    reply_to_email_id?: string | undefined;
+    from_draft_id?: string | undefined;
+}, {
+    body?: string | undefined;
+    to?: string | undefined;
+    subject?: string | undefined;
+    cc?: string | undefined;
+    bcc?: string | undefined;
+    thread_id?: string | undefined;
+    reply_to_email_id?: string | undefined;
+    from_draft_id?: string | undefined;
+}>, {
+    body?: string | undefined;
+    to?: string | undefined;
+    subject?: string | undefined;
+    cc?: string | undefined;
+    bcc?: string | undefined;
+    thread_id?: string | undefined;
+    reply_to_email_id?: string | undefined;
+    from_draft_id?: string | undefined;
+}, {
+    body?: string | undefined;
+    to?: string | undefined;
+    subject?: string | undefined;
+    cc?: string | undefined;
+    bcc?: string | undefined;
+    thread_id?: string | undefined;
+    reply_to_email_id?: string | undefined;
+    from_draft_id?: string | undefined;
+}>;
+export declare function sendEmailTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            to: {
+                type: string;
+                description: "Recipient email address(es). For multiple recipients, separate with commas.";
+            };
+            subject: {
+                type: string;
+                description: "Subject line of the email.";
+            };
+            body: {
+                type: string;
+                description: "Plain text body content of the email.";
+            };
+            cc: {
+                type: string;
+                description: "CC recipient email address(es). For multiple, separate with commas.";
+            };
+            bcc: {
+                type: string;
+                description: "BCC recipient email address(es). For multiple, separate with commas.";
+            };
+            thread_id: {
+                type: string;
+                description: string;
+            };
+            reply_to_email_id: {
+                type: string;
+                description: string;
+            };
+            from_draft_id: {
+                type: string;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};

package/shared/tools/send-email.js

@@ -0,0 +1,181 @@
+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 email to an existing conversation. ' +
+        'Get this from get_email_conversation. If provided, the email will be a reply in that thread.',
+    reply_to_email_id: 'Email ID to reply to. If provided, the email will be formatted as a reply ' +
+        'with proper In-Reply-To and References headers. Also requires thread_id.',
+    from_draft_id: 'Draft ID to send. If provided, sends the specified draft instead of composing a new email. ' +
+        'When using this, other parameters (to, subject, body, etc.) are ignored.',
+};
+export const SendEmailSchema = z
+    .object({
+    to: z.string().optional().describe(PARAM_DESCRIPTIONS.to),
+    subject: z.string().optional().describe(PARAM_DESCRIPTIONS.subject),
+    body: z.string().optional().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),
+    from_draft_id: z.string().optional().describe(PARAM_DESCRIPTIONS.from_draft_id),
+})
+    .refine((data) => {
+    // Either from_draft_id is provided, OR to, subject, and body are all provided
+    if (data.from_draft_id) {
+        return true;
+    }
+    return data.to && data.subject && data.body;
+}, {
+    message: 'Either provide from_draft_id to send a draft, or provide to, subject, and body to send a new email.',
+});
+const TOOL_DESCRIPTION = `Send an email immediately or send a previously created draft.
+
+**Option 1: Send a new email**
+- 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)
+
+**Option 2: Send a draft**
+- from_draft_id: ID of the draft to send (all other parameters are ignored)
+
+**Sending a reply:**
+To send a 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:**
+- Send a new email immediately
+- Reply to an existing email conversation
+- Send a draft that was created with draft_email
+
+**Warning:** This action sends the email immediately and cannot be undone.`;
+export function sendEmailTool(server, clientFactory) {
+    return {
+        name: 'send_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,
+                },
+                from_draft_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.from_draft_id,
+                },
+            },
+            required: [],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = SendEmailSchema.parse(args ?? {});
+                const client = clientFactory();
+                // Option 2: Send a draft
+                if (parsed.from_draft_id) {
+                    const sentEmail = await client.sendDraft(parsed.from_draft_id);
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Draft sent successfully!\n\n**Message ID:** ${sentEmail.id}\n**Thread ID:** ${sentEmail.threadId}\n\nThe draft has been sent and removed from Drafts.`,
+                            },
+                        ],
+                    };
+                }
+                // Option 1: Send a new email
+                // TypeScript knows these are defined due to the refine check
+                const to = parsed.to;
+                const subject = parsed.subject;
+                const body = parsed.body;
+                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 sentEmail = await client.sendMessage({
+                    to,
+                    subject,
+                    body,
+                    cc: parsed.cc,
+                    bcc: parsed.bcc,
+                    threadId: parsed.thread_id,
+                    inReplyTo,
+                    references,
+                });
+                let responseText = `Email sent successfully!\n\n**Message ID:** ${sentEmail.id}\n**Thread ID:** ${sentEmail.threadId}`;
+                if (parsed.thread_id) {
+                    responseText += '\n\nThis email was sent as a reply in an existing conversation.';
+                }
+                responseText += `\n\n**To:** ${to}`;
+                responseText += `\n**Subject:** ${subject}`;
+                if (parsed.cc) {
+                    responseText += `\n**CC:** ${parsed.cc}`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error sending email: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools.d.ts

@@ -1,9 +1,26 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ClientFactory } from './server.js';
 /**
- * Creates a function to register all tools with the server
+ * Available tool groups for Gmail MCP server
+ * - readonly: Read-only operations (list, get, search emails)
+ * - readwrite: Read and write operations (includes readonly + modify, draft)
+ * - readwrite_external: External communication operations (includes readwrite + send_email)
  */
-export declare function createRegisterTools(clientFactory: ClientFactory): (server: Server) => void;
+export type ToolGroup = 'readonly' | 'readwrite' | 'readwrite_external';
+/**
+ * Parses the ENABLED_TOOLGROUPS environment variable
+ * @param enabledGroupsParam - Comma-separated list of tool groups
+ * @returns Array of valid tool groups
+ */
+export declare function parseEnabledToolGroups(enabledGroupsParam?: string): ToolGroup[];
+/**
+ * Gets all available tool group names
+ */
+export declare function getAvailableToolGroups(): ToolGroup[];
+/**
+ * Creates a function to register tools with the server based on enabled groups
+ */
+export declare function createRegisterTools(clientFactory: ClientFactory, enabledGroups?: ToolGroup[]): (server: Server) => void;
 /**
  * Backward compatibility export
  */

package/shared/tools.js

@@ -1,17 +1,65 @@
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-import { listRecentEmailsTool } from './tools/list-recent-emails.js';
-import { getEmailTool } from './tools/get-email.js';
+import { listEmailConversationsTool } from './tools/list-email-conversations.js';
+import { getEmailConversationTool } from './tools/get-email-conversation.js';
+import { changeEmailConversationTool } from './tools/change-email-conversation.js';
+import { draftEmailTool } from './tools/draft-email.js';
+import { sendEmailTool } from './tools/send-email.js';
+import { searchEmailConversationsTool } from './tools/search-email-conversations.js';
+const ALL_TOOL_GROUPS = ['readonly', 'readwrite', 'readwrite_external'];
 /**
- * All available tools
+ * All available tools with their group assignments
+ *
+ * readonly: list_email_conversations, get_email_conversation, search_email_conversations
+ * readwrite: all readonly tools + change_email_conversation, draft_email
+ * readwrite_external: all readwrite tools + send_email (external communication)
  */
-const ALL_TOOLS = [listRecentEmailsTool, getEmailTool];
+const ALL_TOOLS = [
+    // Read-only tools (available in all groups)
+    { factory: listEmailConversationsTool, groups: ['readonly', 'readwrite', 'readwrite_external'] },
+    { factory: getEmailConversationTool, groups: ['readonly', 'readwrite', 'readwrite_external'] },
+    {
+        factory: searchEmailConversationsTool,
+        groups: ['readonly', 'readwrite', 'readwrite_external'],
+    },
+    // Write tools (available in readwrite and readwrite_external)
+    { factory: changeEmailConversationTool, groups: ['readwrite', 'readwrite_external'] },
+    { factory: draftEmailTool, groups: ['readwrite', 'readwrite_external'] },
+    // External communication tools (only in readwrite_external - most dangerous)
+    { factory: sendEmailTool, groups: ['readwrite_external'] },
+];
 /**
- * Creates a function to register all tools with the server
+ * Parses the ENABLED_TOOLGROUPS environment variable
+ * @param enabledGroupsParam - Comma-separated list of tool groups
+ * @returns Array of valid tool groups
  */
-export function createRegisterTools(clientFactory) {
+export function parseEnabledToolGroups(enabledGroupsParam) {
+    if (!enabledGroupsParam) {
+        return ALL_TOOL_GROUPS; // All groups enabled by default
+    }
+    const requestedGroups = enabledGroupsParam.split(',').map((g) => g.trim().toLowerCase());
+    const validGroups = requestedGroups.filter((g) => ALL_TOOL_GROUPS.includes(g));
+    if (validGroups.length === 0) {
+        console.error(`Warning: No valid tool groups found in "${enabledGroupsParam}". ` +
+            `Valid groups: ${ALL_TOOL_GROUPS.join(', ')}. Using all groups.`);
+        return ALL_TOOL_GROUPS;
+    }
+    return validGroups;
+}
+/**
+ * Gets all available tool group names
+ */
+export function getAvailableToolGroups() {
+    return [...ALL_TOOL_GROUPS];
+}
+/**
+ * Creates a function to register tools with the server based on enabled groups
+ */
+export function createRegisterTools(clientFactory, enabledGroups) {
+    // Parse enabled groups from environment or use provided array
+    const groups = enabledGroups || parseEnabledToolGroups(process.env.GMAIL_ENABLED_TOOLGROUPS);
     return (server) => {
-        // Create tool instances
-        const tools = ALL_TOOLS.map((factory) => factory(server, clientFactory));
+        // Filter tools by enabled groups and create instances
+        const tools = ALL_TOOLS.filter((def) => def.groups.some((g) => groups.includes(g))).map((def) => def.factory(server, clientFactory));
         // List available tools
         server.setRequestHandler(ListToolsRequestSchema, async () => {
             return {

package/shared/utils/email-helpers.d.ts

@@ -3,3 +3,7 @@ import type { Email } from '../types.js';
  * Extracts a header value from an email by header name (case-insensitive)
  */
 export declare function getHeader(email: Email, headerName: string): string | undefined;
+/**
+ * Formats an email for display in tool output
+ */
+export declare function formatEmail(email: Email): string;

package/shared/utils/email-helpers.js

@@ -5,3 +5,18 @@ export function getHeader(email, headerName) {
     return email.payload?.headers?.find((h) => h.name.toLowerCase() === headerName.toLowerCase())
         ?.value;
 }
+/**
+ * Formats an email for display in tool output
+ */
+export function formatEmail(email) {
+    const subject = getHeader(email, 'Subject') || '(No Subject)';
+    const from = getHeader(email, 'From') || 'Unknown';
+    const date = getHeader(email, 'Date') || 'Unknown date';
+    const snippet = email.snippet || '';
+    return `**ID:** ${email.id}
+**Thread ID:** ${email.threadId}
+**Subject:** ${subject}
+**From:** ${from}
+**Date:** ${date}
+**Preview:** ${snippet}`;
+}

package/shared/tools/list-recent-emails.js

@@ -1,133 +0,0 @@
-import { z } from 'zod';
-import { getHeader } from '../utils/email-helpers.js';
-const PARAM_DESCRIPTIONS = {
-    hours: 'Time horizon in hours to look back for emails. Default: 24. ' +
-        'Example: 48 for the last 2 days.',
-    labels: 'Comma-separated list of label IDs to filter by. Default: INBOX. ' +
-        'Common labels: INBOX, SENT, DRAFTS, SPAM, TRASH, STARRED, IMPORTANT, UNREAD.',
-    max_results: 'Maximum number of emails to return. Default: 10. Max: 100.',
-};
-export const ListRecentEmailsSchema = z.object({
-    hours: z.number().positive().default(24).describe(PARAM_DESCRIPTIONS.hours),
-    labels: z.string().optional().default('INBOX').describe(PARAM_DESCRIPTIONS.labels),
-    max_results: z.number().positive().max(100).default(10).describe(PARAM_DESCRIPTIONS.max_results),
-});
-const TOOL_DESCRIPTION = `List recent emails from Gmail within a specified time horizon.
-
-Returns a list of recent emails with their subject, sender, date, and a snippet preview. Use get_email to retrieve the full content of a specific email.
-
-**Parameters:**
-- hours: How far back to look for emails (default: 24 hours)
-- labels: Which labels/folders to search (default: INBOX)
-- max_results: Maximum emails to return (default: 10, max: 100)
-
-**Returns:**
-A formatted list of emails with:
-- Email ID (needed for get_email)
-- Subject line
-- Sender (From)
-- Date received
-- Snippet preview
-
-**Use cases:**
-- Check recent inbox activity
-- Monitor for new emails in a time window
-- List recent emails from specific labels like SENT or STARRED
-
-**Note:** This tool only returns email metadata and snippets. Use get_email with an email ID to retrieve the full message content.`;
-/**
- * Formats an email for display
- */
-function formatEmail(email) {
-    const subject = getHeader(email, 'Subject') || '(No Subject)';
-    const from = getHeader(email, 'From') || 'Unknown';
-    const date = getHeader(email, 'Date') || 'Unknown date';
-    const snippet = email.snippet || '';
-    return `**ID:** ${email.id}
-**Subject:** ${subject}
-**From:** ${from}
-**Date:** ${date}
-**Preview:** ${snippet}`;
-}
-export function listRecentEmailsTool(server, clientFactory) {
-    return {
-        name: 'gmail_list_recent_emails',
-        description: TOOL_DESCRIPTION,
-        inputSchema: {
-            type: 'object',
-            properties: {
-                hours: {
-                    type: 'number',
-                    default: 24,
-                    description: PARAM_DESCRIPTIONS.hours,
-                },
-                labels: {
-                    type: 'string',
-                    default: 'INBOX',
-                    description: PARAM_DESCRIPTIONS.labels,
-                },
-                max_results: {
-                    type: 'number',
-                    default: 10,
-                    description: PARAM_DESCRIPTIONS.max_results,
-                },
-            },
-            required: [],
-        },
-        handler: async (args) => {
-            try {
-                const parsed = ListRecentEmailsSchema.parse(args ?? {});
-                const client = clientFactory();
-                // Calculate the timestamp for the time horizon
-                const now = new Date();
-                const cutoffDate = new Date(now.getTime() - parsed.hours * 60 * 60 * 1000);
-                const afterTimestamp = Math.floor(cutoffDate.getTime() / 1000);
-                // Build the Gmail query
-                const query = `after:${afterTimestamp}`;
-                // Parse labels
-                const labelIds = parsed.labels.split(',').map((l) => l.trim().toUpperCase());
-                // List messages
-                const { messages } = await client.listMessages({
-                    q: query,
-                    maxResults: parsed.max_results,
-                    labelIds,
-                });
-                if (messages.length === 0) {
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: `No emails found in the last ${parsed.hours} hour(s) 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'],
-                })));
-                const formattedEmails = emailDetails.map(formatEmail).join('\n\n---\n\n');
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Found ${messages.length} email(s) in the last ${parsed.hours} hour(s):\n\n${formattedEmails}`,
-                        },
-                    ],
-                };
-            }
-            catch (error) {
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `Error listing emails: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                        },
-                    ],
-                    isError: true,
-                };
-            }
-        },
-    };
-}