gmail-workspace-mcp-server 0.0.3 → 0.0.5

package/shared/gmail-client/lib/send-message.d.ts

@@ -0,0 +1,18 @@
+import type { Email } from '../../types.js';
+/**
+ * Sends an email directly
+ */
+export declare function sendMessage(baseUrl: string, headers: Record<string, string>, from: string, options: {
+    to: string;
+    subject: string;
+    body: string;
+    cc?: string;
+    bcc?: string;
+    threadId?: string;
+    inReplyTo?: string;
+    references?: string;
+}): Promise<Email>;
+/**
+ * Sends a draft (and deletes it)
+ */
+export declare function sendDraft(baseUrl: string, headers: Record<string, string>, draftId: string): Promise<Email>;

package/shared/gmail-client/lib/send-message.js

@@ -0,0 +1,40 @@
+import { handleApiError } from './api-errors.js';
+import { buildMimeMessage, toBase64Url } from './mime-utils.js';
+/**
+ * Sends an email directly
+ */
+export async function sendMessage(baseUrl, headers, from, options) {
+    const url = `${baseUrl}/messages/send`;
+    const rawMessage = buildMimeMessage(from, options);
+    const encodedMessage = toBase64Url(rawMessage);
+    const requestBody = {
+        raw: encodedMessage,
+    };
+    if (options.threadId) {
+        requestBody.threadId = options.threadId;
+    }
+    const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(requestBody),
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'sending message');
+    }
+    return (await response.json());
+}
+/**
+ * Sends a draft (and deletes it)
+ */
+export async function sendDraft(baseUrl, headers, draftId) {
+    const url = `${baseUrl}/drafts/send`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({ id: draftId }),
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'sending draft', draftId);
+    }
+    return (await response.json());
+}

package/shared/index.d.ts

@@ -1,4 +1,4 @@
-export { createMCPServer, createDefaultClient, ServiceAccountGmailClient, type IGmailClient, type ClientFactory, type ServiceAccountCredentials, } from './server.js';
-export { createRegisterTools, registerTools } from './tools.js';
+export { createMCPServer, createDefaultClient, ServiceAccountGmailClient, type IGmailClient, type ClientFactory, type ServiceAccountCredentials, type CreateMCPServerOptions, type Draft, } from './server.js';
+export { createRegisterTools, registerTools, parseEnabledToolGroups, getAvailableToolGroups, type ToolGroup, } from './tools.js';
 export { logServerStart, logError, logWarning, logDebug } from './logging.js';
 export type { Email, EmailListItem, EmailHeader, EmailPart, Label, Thread, PaginatedResponse, } from './types.js';

package/shared/index.js

@@ -1,7 +1,7 @@
 // Main exports for Gmail MCP Server
 // Server and client
 export { createMCPServer, createDefaultClient, ServiceAccountGmailClient, } from './server.js';
-// Tools
-export { createRegisterTools, registerTools } from './tools.js';
+// Tools and tool groups
+export { createRegisterTools, registerTools, parseEnabledToolGroups, getAvailableToolGroups, } from './tools.js';
 // Logging utilities
 export { logServerStart, logError, logWarning, logDebug } from './logging.js';

package/shared/server.d.ts

@@ -1,5 +1,12 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import type { Email, EmailListItem } from './types.js';
+/**
+ * Draft message structure
+ */
+export interface Draft {
+    id: string;
+    message: Email;
+}
 /**
  * Gmail API client interface
  * Defines all methods for interacting with the Gmail API
@@ -25,6 +32,65 @@ export interface IGmailClient {
         format?: 'minimal' | 'full' | 'raw' | 'metadata';
         metadataHeaders?: string[];
     }): Promise<Email>;
+    /**
+     * Modify labels on a message (add/remove labels)
+     */
+    modifyMessage(messageId: string, options: {
+        addLabelIds?: string[];
+        removeLabelIds?: string[];
+    }): Promise<Email>;
+    /**
+     * Create a draft email
+     */
+    createDraft(options: {
+        to: string;
+        subject: string;
+        body: string;
+        cc?: string;
+        bcc?: string;
+        threadId?: string;
+        inReplyTo?: string;
+        references?: string;
+    }): Promise<Draft>;
+    /**
+     * Get a draft by ID
+     */
+    getDraft(draftId: string): Promise<Draft>;
+    /**
+     * List drafts
+     */
+    listDrafts(options?: {
+        maxResults?: number;
+        pageToken?: string;
+    }): Promise<{
+        drafts: Array<{
+            id: string;
+            message: EmailListItem;
+        }>;
+        nextPageToken?: string;
+        resultSizeEstimate?: number;
+    }>;
+    /**
+     * Delete a draft
+     */
+    deleteDraft(draftId: string): Promise<void>;
+    /**
+     * Send an email (either directly or from a draft)
+     */
+    sendMessage(options: {
+        to: string;
+        subject: string;
+        body: string;
+        cc?: string;
+        bcc?: string;
+        threadId?: string;
+        inReplyTo?: string;
+        references?: string;
+    }): Promise<Email>;
+    /**
+     * Send a draft
+     */
+    sendDraft(draftId: string): Promise<Email>;
 }
 /**
  * Service account credentials structure
@@ -68,8 +134,49 @@ export declare class ServiceAccountGmailClient implements IGmailClient {
         format?: 'minimal' | 'full' | 'raw' | 'metadata';
         metadataHeaders?: string[];
     }): Promise<Email>;
+    modifyMessage(messageId: string, options: {
+        addLabelIds?: string[];
+        removeLabelIds?: string[];
+    }): Promise<Email>;
+    createDraft(options: {
+        to: string;
+        subject: string;
+        body: string;
+        cc?: string;
+        bcc?: string;
+        threadId?: string;
+        inReplyTo?: string;
+        references?: string;
+    }): Promise<Draft>;
+    getDraft(draftId: string): Promise<Draft>;
+    listDrafts(options?: {
+        maxResults?: number;
+        pageToken?: string;
+    }): Promise<{
+        drafts: Array<{
+            id: string;
+            message: EmailListItem;
+        }>;
+        nextPageToken?: string;
+        resultSizeEstimate?: number;
+    }>;
+    deleteDraft(draftId: string): Promise<void>;
+    sendMessage(options: {
+        to: string;
+        subject: string;
+        body: string;
+        cc?: string;
+        bcc?: string;
+        threadId?: string;
+        inReplyTo?: string;
+        references?: string;
+    }): Promise<Email>;
+    sendDraft(draftId: string): Promise<Email>;
 }
 export type ClientFactory = () => IGmailClient;
+export interface CreateMCPServerOptions {
+    version: string;
+}
 /**
  * Creates the default Gmail client based on environment variables.
  * Uses service account with domain-wide delegation:
@@ -78,7 +185,7 @@ export type ClientFactory = () => IGmailClient;
  *   - GMAIL_IMPERSONATE_EMAIL: Email address to impersonate
  */
 export declare function createDefaultClient(): IGmailClient;
-export declare function createMCPServer(): {
+export declare function createMCPServer(options: CreateMCPServerOptions): {
     server: Server<{
         method: string;
         params?: {

package/shared/server.js

@@ -16,7 +16,12 @@ export class ServiceAccountGmailClient {
         this.jwtClient = new JWT({
             email: credentials.client_email,
             key: credentials.private_key,
-            scopes: ['https://www.googleapis.com/auth/gmail.readonly'],
+            scopes: [
+                'https://www.googleapis.com/auth/gmail.readonly',
+                'https://www.googleapis.com/auth/gmail.modify',
+                'https://www.googleapis.com/auth/gmail.compose',
+                'https://www.googleapis.com/auth/gmail.send',
+            ],
             subject: impersonateEmail,
         });
     }
@@ -59,6 +64,41 @@ export class ServiceAccountGmailClient {
         const { getMessage } = await import('./gmail-client/lib/get-message.js');
         return getMessage(this.baseUrl, headers, messageId, options);
     }
+    async modifyMessage(messageId, options) {
+        const headers = await this.getHeaders();
+        const { modifyMessage } = await import('./gmail-client/lib/modify-message.js');
+        return modifyMessage(this.baseUrl, headers, messageId, options);
+    }
+    async createDraft(options) {
+        const headers = await this.getHeaders();
+        const { createDraft } = await import('./gmail-client/lib/drafts.js');
+        return createDraft(this.baseUrl, headers, this.impersonateEmail, options);
+    }
+    async getDraft(draftId) {
+        const headers = await this.getHeaders();
+        const { getDraft } = await import('./gmail-client/lib/drafts.js');
+        return getDraft(this.baseUrl, headers, draftId);
+    }
+    async listDrafts(options) {
+        const headers = await this.getHeaders();
+        const { listDrafts } = await import('./gmail-client/lib/drafts.js');
+        return listDrafts(this.baseUrl, headers, options);
+    }
+    async deleteDraft(draftId) {
+        const headers = await this.getHeaders();
+        const { deleteDraft } = await import('./gmail-client/lib/drafts.js');
+        return deleteDraft(this.baseUrl, headers, draftId);
+    }
+    async sendMessage(options) {
+        const headers = await this.getHeaders();
+        const { sendMessage } = await import('./gmail-client/lib/send-message.js');
+        return sendMessage(this.baseUrl, headers, this.impersonateEmail, options);
+    }
+    async sendDraft(draftId) {
+        const headers = await this.getHeaders();
+        const { sendDraft } = await import('./gmail-client/lib/send-message.js');
+        return sendDraft(this.baseUrl, headers, draftId);
+    }
 }
 /**
  * Creates the default Gmail client based on environment variables.
@@ -98,10 +138,10 @@ export function createDefaultClient() {
     };
     return new ServiceAccountGmailClient(credentials, impersonateEmail);
 }
-export function createMCPServer() {
+export function createMCPServer(options) {
     const server = new Server({
         name: 'gmail-workspace-mcp-server',
-        version: '0.0.2',
+        version: options.version,
     }, {
         capabilities: {
             tools: {},

package/shared/tools/change-email-conversation.d.ts

@@ -0,0 +1,66 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const ChangeEmailConversationSchema: z.ZodObject<{
+    email_id: z.ZodString;
+    status: z.ZodOptional<z.ZodEnum<["read", "unread", "archived"]>>;
+    labels: z.ZodOptional<z.ZodString>;
+    remove_labels: z.ZodOptional<z.ZodString>;
+    is_starred: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    email_id: string;
+    labels?: string | undefined;
+    status?: "read" | "unread" | "archived" | undefined;
+    remove_labels?: string | undefined;
+    is_starred?: boolean | undefined;
+}, {
+    email_id: string;
+    labels?: string | undefined;
+    status?: "read" | "unread" | "archived" | undefined;
+    remove_labels?: string | undefined;
+    is_starred?: boolean | undefined;
+}>;
+export declare function changeEmailConversationTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            email_id: {
+                type: string;
+                description: string;
+            };
+            status: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            labels: {
+                type: string;
+                description: string;
+            };
+            remove_labels: {
+                type: string;
+                description: string;
+            };
+            is_starred: {
+                type: string;
+                description: "Star or unstar the email. Set to true to star, false to unstar.";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};

package/shared/tools/change-email-conversation.js

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    email_id: 'The unique identifier of the email to modify. ' +
+        'Obtain this from list_email_conversations or search_email_conversations.',
+    status: 'Mark the email as read, unread, or archived. ' + 'Options: read, unread, archived.',
+    labels: 'Labels to add to the email. Comma-separated list. ' +
+        'Common labels: STARRED, IMPORTANT. User labels should be the label ID.',
+    remove_labels: 'Labels to remove from the email. Comma-separated list. ' +
+        'Common labels: STARRED, IMPORTANT, UNREAD. User labels should be the label ID.',
+    is_starred: 'Star or unstar the email. Set to true to star, false to unstar.',
+};
+export const ChangeEmailConversationSchema = z.object({
+    email_id: z.string().min(1).describe(PARAM_DESCRIPTIONS.email_id),
+    status: z.enum(['read', 'unread', 'archived']).optional().describe(PARAM_DESCRIPTIONS.status),
+    labels: z.string().optional().describe(PARAM_DESCRIPTIONS.labels),
+    remove_labels: z.string().optional().describe(PARAM_DESCRIPTIONS.remove_labels),
+    is_starred: z.boolean().optional().describe(PARAM_DESCRIPTIONS.is_starred),
+});
+const TOOL_DESCRIPTION = `Modify an email conversation's status, labels, or starred state.
+
+**Parameters:**
+- email_id: The unique identifier of the email (required)
+- status: Mark as "read", "unread", or "archived" (optional)
+- labels: Comma-separated labels to add (optional)
+- remove_labels: Comma-separated labels to remove (optional)
+- is_starred: Set to true to star, false to unstar (optional)
+
+**Label operations:**
+- Adding STARRED marks the email as starred
+- Removing INBOX archives the email
+- Adding/removing UNREAD marks email as unread/read
+
+**Use cases:**
+- Mark an email as read/unread
+- Star important emails
+- Archive emails (remove from inbox)
+- Apply custom labels for organization
+
+**Note:** Get email_id from list_email_conversations or search_email_conversations first.`;
+export function changeEmailConversationTool(server, clientFactory) {
+    return {
+        name: 'change_email_conversation',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                email_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.email_id,
+                },
+                status: {
+                    type: 'string',
+                    enum: ['read', 'unread', 'archived'],
+                    description: PARAM_DESCRIPTIONS.status,
+                },
+                labels: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.labels,
+                },
+                remove_labels: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.remove_labels,
+                },
+                is_starred: {
+                    type: 'boolean',
+                    description: PARAM_DESCRIPTIONS.is_starred,
+                },
+            },
+            required: ['email_id'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = ChangeEmailConversationSchema.parse(args ?? {});
+                const client = clientFactory();
+                const addLabelIds = [];
+                const removeLabelIds = [];
+                // Handle status
+                if (parsed.status === 'read') {
+                    removeLabelIds.push('UNREAD');
+                }
+                else if (parsed.status === 'unread') {
+                    addLabelIds.push('UNREAD');
+                }
+                else if (parsed.status === 'archived') {
+                    removeLabelIds.push('INBOX');
+                }
+                // Handle is_starred
+                if (parsed.is_starred === true) {
+                    addLabelIds.push('STARRED');
+                }
+                else if (parsed.is_starred === false) {
+                    removeLabelIds.push('STARRED');
+                }
+                // Handle labels to add
+                if (parsed.labels) {
+                    const labels = parsed.labels.split(',').map((l) => l.trim());
+                    addLabelIds.push(...labels);
+                }
+                // Handle labels to remove
+                if (parsed.remove_labels) {
+                    const labels = parsed.remove_labels.split(',').map((l) => l.trim());
+                    removeLabelIds.push(...labels);
+                }
+                // Only make API call if there are changes to make
+                if (addLabelIds.length === 0 && removeLabelIds.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'No changes specified. Provide at least one of: status, labels, remove_labels, or is_starred.',
+                            },
+                        ],
+                    };
+                }
+                const updatedEmail = await client.modifyMessage(parsed.email_id, {
+                    addLabelIds: addLabelIds.length > 0 ? addLabelIds : undefined,
+                    removeLabelIds: removeLabelIds.length > 0 ? removeLabelIds : undefined,
+                });
+                const changes = [];
+                if (addLabelIds.length > 0) {
+                    changes.push(`Added labels: ${addLabelIds.join(', ')}`);
+                }
+                if (removeLabelIds.length > 0) {
+                    changes.push(`Removed labels: ${removeLabelIds.join(', ')}`);
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Email ${parsed.email_id} updated successfully.\n\n${changes.join('\n')}\n\nCurrent labels: ${updatedEmail.labelIds?.join(', ') || 'None'}`,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error modifying email: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

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

@@ -0,0 +1,79 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const DraftEmailSchema: z.ZodObject<{
+    to: z.ZodString;
+    subject: z.ZodString;
+    body: 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>;
+}, "strip", z.ZodTypeAny, {
+    body: string;
+    to: string;
+    subject: string;
+    cc?: string | undefined;
+    bcc?: string | undefined;
+    thread_id?: string | undefined;
+    reply_to_email_id?: string | undefined;
+}, {
+    body: string;
+    to: string;
+    subject: string;
+    cc?: string | undefined;
+    bcc?: string | undefined;
+    thread_id?: string | undefined;
+    reply_to_email_id?: string | undefined;
+}>;
+export declare function draftEmailTool(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;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};