gmail-workspace-mcp-server 0.2.0 → 0.4.3

package/README.md

@@ -152,11 +152,11 @@ You can find the `client_email` and `private_key` values in your service account
 
 The server supports three tool groups for permission-based access control:
 
-| Group                | Tools Included                                                                     | Risk Level |
-| -------------------- | ---------------------------------------------------------------------------------- | ---------- |
-| `readonly`           | `list_email_conversations`, `get_email_conversation`, `search_email_conversations` | Low        |
-| `readwrite`          | All readonly tools + `change_email_conversation`, `draft_email`                    | Medium     |
-| `readwrite_external` | All readwrite tools + `send_email`                                                 | High       |
+| Group                | Tools Included                                                                                          | Risk Level |
+| -------------------- | ------------------------------------------------------------------------------------------------------- | ---------- |
+| `readonly`           | `list_email_conversations`, `get_email_conversation`, `search_email_conversations`, `list_draft_emails` | Low        |
+| `readwrite`          | All readonly tools + `change_email_conversation`, `upsert_draft_email`                                  | Medium     |
+| `readwrite_external` | All readwrite tools + `send_email`                                                                      | High       |
 
 By default, all tool groups are enabled. To restrict access, set the `GMAIL_ENABLED_TOOLGROUPS` environment variable:
 
@@ -254,12 +254,30 @@ Modify email labels and status (read/unread, starred, archived).
 }
 ```
 
-### draft_email
+### list_draft_emails
 
-Create a draft email, optionally as a reply to an existing conversation.
+List draft emails from Gmail with optional thread filtering.
 
 **Parameters:**
 
+- `count` (number, optional): Maximum number of drafts to return (default: 10, max: 100)
+- `thread_id` (string, optional): Filter drafts by conversation thread ID
+
+**Example:**
+
+```json
+{
+  "thread_id": "18abc123def456"
+}
+```
+
+### upsert_draft_email
+
+Create a new draft email or update an existing one. Optionally as a reply to an existing conversation.
+
+**Parameters:**
+
+- `draft_id` (string, optional): ID of an existing draft to update (omit to create a new draft)
 - `to` (string, required): Recipient email address
 - `subject` (string, required): Email subject
 - `plaintext_body` (string): Plain text body content (at least one of plaintext_body or html_body required)
@@ -271,7 +289,7 @@ Create a draft email, optionally as a reply to an existing conversation.
 
 At least one of `plaintext_body` or `html_body` must be provided. If both are provided, a multipart email is sent with both versions.
 
-**Example (plain text):**
+**Example (create new draft):**
 
 ```json
 {
@@ -281,12 +299,13 @@ At least one of `plaintext_body` or `html_body` must be provided. If both are pr
 }
 ```
 
-**Example (HTML):**
+**Example (update existing draft):**
 
 ```json
 {
+  "draft_id": "r123456789",
   "to": "recipient@example.com",
-  "subject": "Meeting Follow-up",
+  "subject": "Meeting Follow-up (revised)",
   "html_body": "<p>Thanks for the meeting today! Check out <a href=\"https://example.com/notes\">the notes</a>.</p>"
 }
 ```

package/build/index.integration-with-mock.js

@@ -193,6 +193,39 @@ function createMockClient() {
             mockDrafts.push(draft);
             return draft;
         },
+        async updateDraft(draftId, options) {
+            const index = mockDrafts.findIndex((d) => d.id === draftId);
+            if (index === -1) {
+                throw new Error(`Draft not found: ${draftId}`);
+            }
+            const bodyContent = options.plaintextBody || options.htmlBody || '';
+            const updatedDraft = {
+                id: draftId,
+                message: {
+                    id: mockDrafts[index].message.id,
+                    threadId: options.threadId || mockDrafts[index].message.threadId,
+                    labelIds: ['DRAFT'],
+                    snippet: bodyContent.substring(0, 100),
+                    historyId: '12347',
+                    internalDate: String(Date.now()),
+                    payload: {
+                        mimeType: options.htmlBody ? 'text/html' : 'text/plain',
+                        headers: [
+                            { name: 'Subject', value: options.subject },
+                            { name: 'From', value: 'me@example.com' },
+                            { name: 'To', value: options.to },
+                            { name: 'Date', value: new Date().toISOString() },
+                        ],
+                        body: {
+                            size: bodyContent.length,
+                            data: Buffer.from(bodyContent).toString('base64url'),
+                        },
+                    },
+                },
+            };
+            mockDrafts[index] = updatedDraft;
+            return updatedDraft;
+        },
         async getDraft(draftId) {
             const draft = mockDrafts.find((d) => d.id === draftId);
             if (!draft) {

package/node_modules/@pulsemcp/mcp-elicitation/build/config.d.ts

@@ -0,0 +1,13 @@
+import type { ElicitationConfig } from './types.js';
+/**
+ * Reads elicitation configuration from environment variables.
+ *
+ * Environment variables:
+ *   ELICITATION_ENABLED       - "true" (default) or "false"
+ *   ELICITATION_REQUEST_URL   - POST endpoint for HTTP fallback
+ *   ELICITATION_POLL_URL      - GET endpoint for HTTP fallback polling
+ *   ELICITATION_TTL_MS        - Request TTL in milliseconds (default: 300000)
+ *   ELICITATION_POLL_INTERVAL_MS - Poll interval in milliseconds (default: 5000, min: 1000)
+ *   ELICITATION_SESSION_ID      - Session identifier for HTTP fallback `_meta`
+ */
+export declare function readElicitationConfig(env?: Record<string, string | undefined>): ElicitationConfig;

package/node_modules/@pulsemcp/mcp-elicitation/build/config.js

@@ -0,0 +1,36 @@
+const DEFAULT_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_POLL_INTERVAL_MS = 5 * 1000; // 5 seconds
+const MIN_POLL_INTERVAL_MS = 1000; // 1 second minimum to prevent tight loops
+/**
+ * Parses a positive integer from a string, returning the default if invalid.
+ */
+function parsePositiveInt(value, defaultValue) {
+    if (!value)
+        return defaultValue;
+    const parsed = parseInt(value, 10);
+    return Number.isNaN(parsed) || parsed < 0 ? defaultValue : parsed;
+}
+/**
+ * Reads elicitation configuration from environment variables.
+ *
+ * Environment variables:
+ *   ELICITATION_ENABLED       - "true" (default) or "false"
+ *   ELICITATION_REQUEST_URL   - POST endpoint for HTTP fallback
+ *   ELICITATION_POLL_URL      - GET endpoint for HTTP fallback polling
+ *   ELICITATION_TTL_MS        - Request TTL in milliseconds (default: 300000)
+ *   ELICITATION_POLL_INTERVAL_MS - Poll interval in milliseconds (default: 5000, min: 1000)
+ *   ELICITATION_SESSION_ID      - Session identifier for HTTP fallback `_meta`
+ */
+export function readElicitationConfig(env = process.env) {
+    const enabledRaw = env.ELICITATION_ENABLED;
+    const enabled = enabledRaw === undefined ? true : enabledRaw.toLowerCase() !== 'false';
+    const pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, parsePositiveInt(env.ELICITATION_POLL_INTERVAL_MS, DEFAULT_POLL_INTERVAL_MS));
+    return {
+        enabled,
+        requestUrl: env.ELICITATION_REQUEST_URL,
+        pollUrl: env.ELICITATION_POLL_URL,
+        ttlMs: parsePositiveInt(env.ELICITATION_TTL_MS, DEFAULT_TTL_MS),
+        pollIntervalMs,
+        sessionId: env.ELICITATION_SESSION_ID,
+    };
+}

package/node_modules/@pulsemcp/mcp-elicitation/build/elicitation.d.ts

@@ -0,0 +1,19 @@
+import type { ElicitationConfig, ElicitationRequestedSchema, ElicitationResult, RequestConfirmationOptions } from './types.js';
+/**
+ * Requests user confirmation through the best available mechanism.
+ *
+ * Decision tree:
+ * 1. If elicitation is disabled (`ELICITATION_ENABLED=false`), returns `accept` immediately.
+ * 2. If the client supports native elicitation, uses `server.elicitInput()`.
+ * 3. If HTTP fallback URLs are configured, posts to the external endpoint and polls.
+ * 4. Otherwise, throws an error indicating no elicitation mechanism is available.
+ *
+ * @param options - Configuration for the confirmation request.
+ * @param config - Elicitation config (defaults to reading from env vars).
+ * @returns The user's response.
+ */
+export declare function requestConfirmation(options: RequestConfirmationOptions, config?: ElicitationConfig): Promise<ElicitationResult>;
+/**
+ * Creates a simple boolean confirmation schema for common "are you sure?" prompts.
+ */
+export declare function createConfirmationSchema(title?: string, description?: string): ElicitationRequestedSchema;

package/node_modules/@pulsemcp/mcp-elicitation/build/elicitation.js

@@ -0,0 +1,137 @@
+import { randomUUID } from 'node:crypto';
+import { readElicitationConfig } from './config.js';
+/**
+ * Checks whether the connected client supports native form elicitation.
+ */
+function clientSupportsElicitation(server) {
+    const caps = server.getClientCapabilities();
+    if (!caps?.elicitation) {
+        return false;
+    }
+    // If elicitation is declared at all (even empty {}), form mode is supported
+    // per the MCP spec's backward compatibility rules.
+    return true;
+}
+/**
+ * Attempts native elicitation via the MCP SDK's `server.elicitInput()`.
+ */
+async function nativeElicit(server, message, requestedSchema) {
+    const params = {
+        mode: 'form',
+        message,
+        requestedSchema,
+    };
+    const result = await server.elicitInput(params);
+    return {
+        action: result.action,
+        content: result.content ?? undefined,
+    };
+}
+/**
+ * Posts an elicitation request to the HTTP fallback endpoint.
+ */
+async function postElicitationRequest(config, message, requestedSchema, meta) {
+    const response = await fetch(config.requestUrl, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            mode: 'form',
+            message,
+            requestedSchema,
+            _meta: meta,
+        }),
+    });
+    if (!response.ok) {
+        const body = await response.text().catch(() => '');
+        throw new Error(`Elicitation POST failed: ${response.status} ${response.statusText}${body ? ` - ${body}` : ''}`);
+    }
+    const data = (await response.json());
+    return data;
+}
+/**
+ * Polls the HTTP fallback endpoint until the request is resolved or expires.
+ */
+async function pollElicitationStatus(config, requestId, expiresAt) {
+    const pollUrl = config.pollUrl.endsWith('/')
+        ? `${config.pollUrl}${requestId}`
+        : `${config.pollUrl}/${requestId}`;
+    while (Date.now() < expiresAt) {
+        const response = await fetch(pollUrl, {
+            method: 'GET',
+            headers: { 'Content-Type': 'application/json' },
+        });
+        if (!response.ok) {
+            const body = await response.text().catch(() => '');
+            throw new Error(`Elicitation poll failed: ${response.status} ${response.statusText}${body ? ` - ${body}` : ''}`);
+        }
+        const data = (await response.json());
+        if (data.action !== 'pending') {
+            return {
+                action: data.action,
+                content: data.content ?? undefined,
+            };
+        }
+        // Wait before polling again
+        await new Promise((resolve) => setTimeout(resolve, config.pollIntervalMs));
+    }
+    return { action: 'expired' };
+}
+/**
+ * Requests user confirmation through the best available mechanism.
+ *
+ * Decision tree:
+ * 1. If elicitation is disabled (`ELICITATION_ENABLED=false`), returns `accept` immediately.
+ * 2. If the client supports native elicitation, uses `server.elicitInput()`.
+ * 3. If HTTP fallback URLs are configured, posts to the external endpoint and polls.
+ * 4. Otherwise, throws an error indicating no elicitation mechanism is available.
+ *
+ * @param options - Configuration for the confirmation request.
+ * @param config - Elicitation config (defaults to reading from env vars).
+ * @returns The user's response.
+ */
+export async function requestConfirmation(options, config) {
+    const cfg = config ?? readElicitationConfig();
+    // Tier 1: Disabled — skip confirmation entirely
+    if (!cfg.enabled) {
+        return { action: 'accept' };
+    }
+    // Tier 2: Native elicitation
+    if (clientSupportsElicitation(options.server)) {
+        return nativeElicit(options.server, options.message, options.requestedSchema);
+    }
+    // Tier 3: HTTP fallback
+    if (cfg.requestUrl && cfg.pollUrl) {
+        const clientRequestId = randomUUID();
+        const expiresAt = Date.now() + cfg.ttlMs;
+        const meta = {
+            'com.pulsemcp/request-id': clientRequestId,
+            'com.pulsemcp/expires-at': new Date(expiresAt).toISOString(),
+            ...(cfg.sessionId && { 'com.pulsemcp/session-id': cfg.sessionId }),
+            ...options.meta,
+        };
+        const postResponse = await postElicitationRequest(cfg, options.message, options.requestedSchema, meta);
+        // Use the server-provided requestId if available, otherwise fall back to the client-generated one
+        const requestId = postResponse.requestId || clientRequestId;
+        return pollElicitationStatus(cfg, requestId, expiresAt);
+    }
+    // Tier 4: No mechanism available
+    throw new Error('Elicitation is enabled but no mechanism is available. ' +
+        'Either the client must support native elicitation, or ' +
+        'ELICITATION_REQUEST_URL and ELICITATION_POLL_URL must be configured for HTTP fallback.');
+}
+/**
+ * Creates a simple boolean confirmation schema for common "are you sure?" prompts.
+ */
+export function createConfirmationSchema(title = 'Confirm', description) {
+    return {
+        type: 'object',
+        properties: {
+            confirm: {
+                type: 'boolean',
+                title,
+                ...(description ? { description } : {}),
+            },
+        },
+        required: ['confirm'],
+    };
+}

package/node_modules/@pulsemcp/mcp-elicitation/build/index.d.ts

@@ -0,0 +1,3 @@
+export { requestConfirmation, createConfirmationSchema } from './elicitation.js';
+export { readElicitationConfig } from './config.js';
+export type { ElicitationConfig, ElicitationFieldSchema, ElicitationMeta, ElicitationPollResponse, ElicitationPostResponse, ElicitationRequestedSchema, ElicitationResult, MCPServerLike, RequestConfirmationOptions, } from './types.js';

package/node_modules/@pulsemcp/mcp-elicitation/build/index.js

@@ -0,0 +1,2 @@
+export { requestConfirmation, createConfirmationSchema } from './elicitation.js';
+export { readElicitationConfig } from './config.js';

package/node_modules/@pulsemcp/mcp-elicitation/build/types.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Minimal interface for the MCP server, avoiding direct dependency on
+ * @modelcontextprotocol/sdk Server type to prevent cross-package type
+ * mismatches in monorepo setups with multiple SDK installations.
+ */
+export interface MCPServerLike {
+    getClientCapabilities(): {
+        elicitation?: unknown;
+    } | undefined;
+    elicitInput(params: unknown): Promise<{
+        action: 'accept' | 'decline' | 'cancel';
+        content?: Record<string, string | number | boolean | string[]>;
+    }>;
+}
+/**
+ * Vendor metadata for PulseMCP elicitation requests.
+ * Uses reverse-DNS prefix `com.pulsemcp/` per MCP spec conventions.
+ */
+export interface ElicitationMeta {
+    'com.pulsemcp/request-id'?: string;
+    'com.pulsemcp/tool-name'?: string;
+    'com.pulsemcp/context'?: string;
+    'com.pulsemcp/session-id'?: string;
+    'com.pulsemcp/expires-at'?: string;
+}
+/**
+ * Schema for a single field in a form elicitation request.
+ * Maps to PrimitiveSchemaDefinition in the MCP spec.
+ */
+export interface ElicitationFieldSchema {
+    type: 'string' | 'number' | 'integer' | 'boolean';
+    title?: string;
+    description?: string;
+    default?: string | number | boolean;
+    minLength?: number;
+    maxLength?: number;
+    format?: 'email' | 'uri' | 'date' | 'date-time';
+    enum?: string[];
+    minimum?: number;
+    maximum?: number;
+}
+/**
+ * Schema for the form presented to users during elicitation.
+ */
+export interface ElicitationRequestedSchema {
+    type: 'object';
+    properties: Record<string, ElicitationFieldSchema>;
+    required?: string[];
+}
+/**
+ * Configuration for the elicitation system.
+ * Read from environment variables at initialization.
+ */
+export interface ElicitationConfig {
+    /** Whether elicitation is enabled at all. Default: true (reads from ELICITATION_ENABLED env var). */
+    enabled: boolean;
+    /** POST endpoint for creating approval requests (HTTP fallback). */
+    requestUrl?: string;
+    /** Base URL for polling approval status (HTTP fallback). */
+    pollUrl?: string;
+    /** TTL for elicitation requests in milliseconds. Default: 5 minutes. */
+    ttlMs: number;
+    /** Poll interval in milliseconds. Default: 5 seconds. */
+    pollIntervalMs: number;
+    /** Session identifier included as `com.pulsemcp/session-id` in `_meta` of HTTP fallback requests. */
+    sessionId?: string;
+}
+/**
+ * The result of an elicitation request.
+ */
+export interface ElicitationResult {
+    action: 'accept' | 'decline' | 'cancel' | 'expired';
+    content?: Record<string, string | number | boolean | string[]>;
+}
+/**
+ * HTTP fallback response from the polling endpoint.
+ */
+export interface ElicitationPollResponse {
+    action: 'pending' | 'accept' | 'decline' | 'cancel' | 'expired';
+    content?: Record<string, string | number | boolean | string[]> | null;
+    _meta?: {
+        'com.pulsemcp/request-id'?: string;
+        'com.pulsemcp/responded-at'?: string | null;
+    };
+}
+/**
+ * HTTP fallback response from the POST request endpoint.
+ */
+export interface ElicitationPostResponse {
+    requestId: string;
+}
+/**
+ * Options passed to the requestConfirmation function.
+ */
+export interface RequestConfirmationOptions {
+    /** The MCP server instance (needed for native elicitation). */
+    server: MCPServerLike;
+    /** Human-readable message explaining what needs confirmation. */
+    message: string;
+    /** Schema for the form fields to present. */
+    requestedSchema: ElicitationRequestedSchema;
+    /** Optional vendor metadata. */
+    meta?: ElicitationMeta;
+}

package/node_modules/@pulsemcp/mcp-elicitation/build/types.js

@@ -0,0 +1 @@
+export {};

package/node_modules/@pulsemcp/mcp-elicitation/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@pulsemcp/mcp-elicitation",
+  "version": "1.0.1",
+  "description": "Elicitation support library for PulseMCP MCP servers - provides native elicitation with HTTP fallback",
+  "type": "module",
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "lint": "eslint . --ext .ts,.tsx",
+    "lint:fix": "eslint . --ext .ts,.tsx --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "keywords": [
+    "mcp",
+    "elicitation",
+    "pulsemcp"
+  ],
+  "author": "PulseMCP",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^24.10.12",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.3"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gmail-workspace-mcp-server",
-  "version": "0.2.0",
+  "version": "0.4.3",
   "description": "MCP server for Gmail integration with OAuth2 and service account support",
   "main": "build/index.js",
   "type": "module",
@@ -12,8 +12,13 @@
     "build/**/*.d.ts",
     "shared/**/*.js",
     "shared/**/*.d.ts",
+    "node_modules/@pulsemcp/mcp-elicitation/**/*.js",
+    "node_modules/@pulsemcp/mcp-elicitation/package.json",
     "README.md"
   ],
+  "bundledDependencies": [
+    "@pulsemcp/mcp-elicitation"
+  ],
   "scripts": {
     "build": "tsc && npm run build:integration",
     "build:integration": "tsc -p tsconfig.integration.json",
@@ -30,6 +35,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.19.1",
+    "@pulsemcp/mcp-elicitation": "file:../../../libs/elicitation",
     "google-auth-library": "^10.5.0",
     "zod": "^3.24.1"
   },

package/shared/gmail-client/lib/drafts.d.ts

@@ -36,6 +36,20 @@ export declare function listDrafts(baseUrl: string, headers: Record<string, stri
     nextPageToken?: string;
     resultSizeEstimate?: number;
 }>;
+/**
+ * Updates an existing draft email
+ */
+export declare function updateDraft(baseUrl: string, headers: Record<string, string>, from: string, draftId: string, options: {
+    to: string;
+    subject: string;
+    plaintextBody?: string;
+    htmlBody?: string;
+    cc?: string;
+    bcc?: string;
+    threadId?: string;
+    inReplyTo?: string;
+    references?: string;
+}): Promise<Draft>;
 /**
  * Deletes a draft
  */

package/shared/gmail-client/lib/drafts.js

@@ -66,6 +66,31 @@ export async function listDrafts(baseUrl, headers, options) {
         resultSizeEstimate: data.resultSizeEstimate,
     };
 }
+/**
+ * Updates an existing draft email
+ */
+export async function updateDraft(baseUrl, headers, from, draftId, options) {
+    const url = `${baseUrl}/drafts/${draftId}`;
+    const rawMessage = buildMimeMessage(from, options);
+    const encodedMessage = toBase64Url(rawMessage);
+    const requestBody = {
+        message: {
+            raw: encodedMessage,
+        },
+    };
+    if (options.threadId) {
+        requestBody.message.threadId = options.threadId;
+    }
+    const response = await fetch(url, {
+        method: 'PUT',
+        headers,
+        body: JSON.stringify(requestBody),
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'updating draft', draftId);
+    }
+    return (await response.json());
+}
 /**
  * Deletes a draft
  */

package/shared/gmail-client/lib/mime-utils.d.ts

@@ -11,6 +11,16 @@ export interface MimeMessageOptions {
     inReplyTo?: string;
     references?: string;
 }
+/**
+ * Encodes a string as an RFC 2047 encoded-word using UTF-8 and Base64.
+ * Only encodes if the string contains non-ASCII characters.
+ *
+ * Note: RFC 2047 limits encoded-words to 75 characters. Very long non-ASCII
+ * subjects should technically be split into multiple encoded-words separated
+ * by folding whitespace. In practice, Gmail handles oversized encoded-words
+ * correctly, so we encode as a single word for simplicity.
+ */
+export declare function encodeSubject(subject: string): string;
 /**
  * Builds a MIME message from email options.
  * If both plaintextBody and htmlBody are provided, creates a multipart/alternative message.

package/shared/gmail-client/lib/mime-utils.js

@@ -1,6 +1,30 @@
 /**
  * MIME message utilities for building and encoding email messages
  */
+/**
+ * Encodes a string as an RFC 2047 encoded-word using UTF-8 and Base64.
+ * Only encodes if the string contains non-ASCII characters.
+ *
+ * Note: RFC 2047 limits encoded-words to 75 characters. Very long non-ASCII
+ * subjects should technically be split into multiple encoded-words separated
+ * by folding whitespace. In practice, Gmail handles oversized encoded-words
+ * correctly, so we encode as a single word for simplicity.
+ */
+export function encodeSubject(subject) {
+    // eslint-disable-next-line no-control-regex
+    if (!/[^\x00-\x7F]/.test(subject)) {
+        return subject;
+    }
+    const encoded = Buffer.from(subject, 'utf-8').toString('base64');
+    return `=?UTF-8?B?${encoded}?=`;
+}
+/**
+ * Strips leading newline characters (\r\n, \n, and bare \r) from email body content.
+ * Prevents extra blank lines at the top of the email when displayed in Gmail.
+ */
+function stripLeadingNewlines(body) {
+    return body.replace(/^[\r\n]+/, '');
+}
 /**
  * Builds a MIME message from email options.
  * If both plaintextBody and htmlBody are provided, creates a multipart/alternative message.
@@ -10,7 +34,7 @@ export function buildMimeMessage(from, options) {
     const headers = [
         `From: ${from}`,
         `To: ${options.to}`,
-        `Subject: ${options.subject}`,
+        `Subject: ${encodeSubject(options.subject)}`,
         'MIME-Version: 1.0',
     ];
     if (options.cc) {
@@ -29,9 +53,11 @@ export function buildMimeMessage(from, options) {
     if (options.plaintextBody && options.htmlBody) {
         const boundary = `boundary_${Date.now()}_${Math.random().toString(36).substring(2)}`;
         headers.push(`Content-Type: multipart/alternative; boundary="${boundary}"`);
+        const plainBody = stripLeadingNewlines(options.plaintextBody);
+        const htmlBody = stripLeadingNewlines(options.htmlBody);
         const parts = [
-            `--${boundary}\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n${options.plaintextBody}`,
-            `--${boundary}\r\nContent-Type: text/html; charset=utf-8\r\n\r\n${options.htmlBody}`,
+            `--${boundary}\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n${plainBody}`,
+            `--${boundary}\r\nContent-Type: text/html; charset=utf-8\r\n\r\n${htmlBody}`,
             `--${boundary}--`,
         ];
         return headers.join('\r\n') + '\r\n\r\n' + parts.join('\r\n');
@@ -39,10 +65,10 @@ export function buildMimeMessage(from, options) {
     // Single content type
     if (options.htmlBody) {
         headers.push('Content-Type: text/html; charset=utf-8');
-        return headers.join('\r\n') + '\r\n\r\n' + options.htmlBody;
+        return headers.join('\r\n') + '\r\n\r\n' + stripLeadingNewlines(options.htmlBody);
     }
     headers.push('Content-Type: text/plain; charset=utf-8');
-    return headers.join('\r\n') + '\r\n\r\n' + (options.plaintextBody ?? '');
+    return headers.join('\r\n') + '\r\n\r\n' + stripLeadingNewlines(options.plaintextBody ?? '');
 }
 /**
  * Converts a string to base64url encoding (RFC 4648)

package/shared/server.d.ts

@@ -58,6 +58,20 @@ export interface IGmailClient {
         inReplyTo?: string;
         references?: string;
     }): Promise<Draft>;
+    /**
+     * Update an existing draft email
+     */
+    updateDraft(draftId: string, options: {
+        to: string;
+        subject: string;
+        plaintextBody?: string;
+        htmlBody?: string;
+        cc?: string;
+        bcc?: string;
+        threadId?: string;
+        inReplyTo?: string;
+        references?: string;
+    }): Promise<Draft>;
     /**
      * Get a draft by ID
      */
@@ -177,6 +191,17 @@ declare abstract class BaseGmailClient implements IGmailClient {
         inReplyTo?: string;
         references?: string;
     }): Promise<Draft>;
+    updateDraft(draftId: string, options: {
+        to: string;
+        subject: string;
+        plaintextBody?: string;
+        htmlBody?: string;
+        cc?: string;
+        bcc?: string;
+        threadId?: string;
+        inReplyTo?: string;
+        references?: string;
+    }): Promise<Draft>;
     getDraft(draftId: string): Promise<Draft>;
     listDrafts(options?: {
         maxResults?: number;

package/shared/server.js

@@ -71,6 +71,12 @@ class BaseGmailClient {
         const { createDraft } = await import('./gmail-client/lib/drafts.js');
         return createDraft(this.baseUrl, headers, senderEmail, options);
     }
+    async updateDraft(draftId, options) {
+        const headers = await this.getHeaders();
+        const senderEmail = await this.getSenderEmail();
+        const { updateDraft } = await import('./gmail-client/lib/drafts.js');
+        return updateDraft(this.baseUrl, headers, senderEmail, draftId, options);
+    }
     async getDraft(draftId) {
         const headers = await this.getHeaders();
         const { getDraft } = await import('./gmail-client/lib/drafts.js');

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

@@ -1,7 +1,8 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { z } from 'zod';
 import type { ClientFactory } from '../server.js';
-export declare const DraftEmailSchema: z.ZodEffects<z.ZodObject<{
+export declare const UpsertDraftEmailSchema: z.ZodEffects<z.ZodObject<{
+    draft_id: z.ZodOptional<z.ZodString>;
     to: z.ZodString;
     subject: z.ZodString;
     plaintext_body: z.ZodOptional<z.ZodString>;
@@ -13,6 +14,7 @@ export declare const DraftEmailSchema: z.ZodEffects<z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     to: string;
     subject: string;
+    draft_id?: string | undefined;
     plaintext_body?: string | undefined;
     html_body?: string | undefined;
     cc?: string | undefined;
@@ -22,6 +24,7 @@ export declare const DraftEmailSchema: z.ZodEffects<z.ZodObject<{
 }, {
     to: string;
     subject: string;
+    draft_id?: string | undefined;
     plaintext_body?: string | undefined;
     html_body?: string | undefined;
     cc?: string | undefined;
@@ -31,6 +34,7 @@ export declare const DraftEmailSchema: z.ZodEffects<z.ZodObject<{
 }>, {
     to: string;
     subject: string;
+    draft_id?: string | undefined;
     plaintext_body?: string | undefined;
     html_body?: string | undefined;
     cc?: string | undefined;
@@ -40,6 +44,7 @@ export declare const DraftEmailSchema: z.ZodEffects<z.ZodObject<{
 }, {
     to: string;
     subject: string;
+    draft_id?: string | undefined;
     plaintext_body?: string | undefined;
     html_body?: string | undefined;
     cc?: string | undefined;
@@ -47,12 +52,16 @@ export declare const DraftEmailSchema: z.ZodEffects<z.ZodObject<{
     thread_id?: string | undefined;
     reply_to_email_id?: string | undefined;
 }>;
-export declare function draftEmailTool(server: Server, clientFactory: ClientFactory): {
+export declare function upsertDraftEmailTool(server: Server, clientFactory: ClientFactory): {
     name: string;
     description: string;
     inputSchema: {
         type: "object";
         properties: {
+            draft_id: {
+                type: string;
+                description: string;
+            };
             to: {
                 type: string;
                 description: "Recipient email address(es). For multiple recipients, separate with commas.";

package/shared/tools/draft-email.js

@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import { getHeader } from '../utils/email-helpers.js';
 const PARAM_DESCRIPTIONS = {
+    draft_id: 'ID of an existing draft to update. If provided, the draft is replaced in-place ' +
+        'with the new content. If omitted, a new draft is created. ' +
+        'Get draft IDs from list_draft_emails or from a previous upsert_draft_email response.',
     to: 'Recipient email address(es). For multiple recipients, separate with commas.',
     subject: 'Subject line of the email.',
     plaintext_body: 'Plain text body content of the email. At least one of plaintext_body or html_body must be provided. If both are provided, a multipart email is sent with both versions.',
@@ -12,8 +15,9 @@ const PARAM_DESCRIPTIONS = {
     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
+export const UpsertDraftEmailSchema = z
     .object({
+    draft_id: z.string().optional().describe(PARAM_DESCRIPTIONS.draft_id),
     to: z.string().min(1).describe(PARAM_DESCRIPTIONS.to),
     subject: z.string().min(1).describe(PARAM_DESCRIPTIONS.subject),
     plaintext_body: z.string().min(1).optional().describe(PARAM_DESCRIPTIONS.plaintext_body),
@@ -28,9 +32,10 @@ export const DraftEmailSchema = z
 }, {
     message: 'At least one of plaintext_body or html_body must be provided.',
 });
-const TOOL_DESCRIPTION = `Create a draft email that can be reviewed and sent later.
+const TOOL_DESCRIPTION = `Create a new draft email or update an existing one.
 
 **Parameters:**
+- draft_id: ID of an existing draft to update (optional — omit to create a new draft)
 - to: Recipient email address(es) (required)
 - subject: Email subject line (required)
 - plaintext_body: Plain text body content (at least one of plaintext_body or html_body required)
@@ -48,19 +53,27 @@ 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
 
+**Updating a draft:**
+To update an existing draft, provide the draft_id from a previous upsert_draft_email response or from list_draft_emails. The draft is replaced in-place — all fields must be provided (not just the ones you want to change).
+
 **Use cases:**
 - Draft a new email for later review
 - Prepare a reply to an email conversation
+- Revise a draft after user feedback (without creating duplicates)
 - 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) {
+export function upsertDraftEmailTool(server, clientFactory) {
     return {
-        name: 'draft_email',
+        name: 'upsert_draft_email',
         description: TOOL_DESCRIPTION,
         inputSchema: {
             type: 'object',
             properties: {
+                draft_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.draft_id,
+                },
                 to: {
                     type: 'string',
                     description: PARAM_DESCRIPTIONS.to,
@@ -98,7 +111,7 @@ export function draftEmailTool(server, clientFactory) {
         },
         handler: async (args) => {
             try {
-                const parsed = DraftEmailSchema.parse(args ?? {});
+                const parsed = UpsertDraftEmailSchema.parse(args ?? {});
                 const client = clientFactory();
                 let inReplyTo;
                 let references;
@@ -116,7 +129,7 @@ export function draftEmailTool(server, clientFactory) {
                         references = originalReferences ? `${originalReferences} ${messageId}` : messageId;
                     }
                 }
-                const draft = await client.createDraft({
+                const draftOptions = {
                     to: parsed.to,
                     subject: parsed.subject,
                     plaintextBody: parsed.plaintext_body,
@@ -126,8 +139,13 @@ export function draftEmailTool(server, clientFactory) {
                     threadId: parsed.thread_id,
                     inReplyTo,
                     references,
-                });
-                let responseText = `Draft created successfully!\n\n**Draft ID:** ${draft.id}`;
+                };
+                const isUpdate = Boolean(parsed.draft_id);
+                const draft = isUpdate
+                    ? await client.updateDraft(parsed.draft_id, draftOptions)
+                    : await client.createDraft(draftOptions);
+                const action = isUpdate ? 'updated' : 'created';
+                let responseText = `Draft ${action} 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.';
@@ -162,7 +180,7 @@ export function draftEmailTool(server, clientFactory) {
                     content: [
                         {
                             type: 'text',
-                            text: `Error creating draft: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                            text: `Error ${args?.draft_id ? 'updating' : 'creating'} draft: ${error instanceof Error ? error.message : 'Unknown error'}`,
                         },
                     ],
                     isError: true,

package/shared/tools/list-draft-emails.d.ts

@@ -0,0 +1,44 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const ListDraftEmailsSchema: z.ZodObject<{
+    count: z.ZodDefault<z.ZodNumber>;
+    thread_id: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    count: number;
+    thread_id?: string | undefined;
+}, {
+    count?: number | undefined;
+    thread_id?: string | undefined;
+}>;
+export declare function listDraftEmailsTool(server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            count: {
+                type: string;
+                description: "Maximum number of drafts to return. Default: 10. Max: 100.";
+            };
+            thread_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/list-draft-emails.js

@@ -0,0 +1,123 @@
+import { z } from 'zod';
+import { getHeader } from '../utils/email-helpers.js';
+const PARAM_DESCRIPTIONS = {
+    count: 'Maximum number of drafts to return. Default: 10. Max: 100.',
+    thread_id: 'Filter drafts by thread ID. Only returns drafts belonging to the specified conversation thread. ' +
+        'Get thread IDs from list_email_conversations or get_email_conversation.',
+};
+export const ListDraftEmailsSchema = z.object({
+    count: z.number().positive().max(100).default(10).describe(PARAM_DESCRIPTIONS.count),
+    thread_id: z.string().optional().describe(PARAM_DESCRIPTIONS.thread_id),
+});
+const TOOL_DESCRIPTION = `List draft emails from Gmail.
+
+**Parameters:**
+- count: Maximum number of drafts to return (default: 10, max: 100)
+- thread_id: Filter drafts by conversation thread ID (optional)
+
+**Use cases:**
+- Discover existing drafts before creating a new one
+- Find a draft ID to pass to upsert_draft_email for updating
+- Check which drafts exist for a specific email conversation
+
+**Note:** Use the returned draft IDs with upsert_draft_email to update drafts, or with send_email's from_draft_id to send them.`;
+export function listDraftEmailsTool(server, clientFactory) {
+    return {
+        name: 'list_draft_emails',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                count: {
+                    type: 'number',
+                    description: PARAM_DESCRIPTIONS.count,
+                },
+                thread_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.thread_id,
+                },
+            },
+            required: [],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = ListDraftEmailsSchema.parse(args ?? {});
+                const client = clientFactory();
+                // Fetch drafts — request more than needed if filtering by thread
+                // since the Gmail API doesn't support server-side thread filtering for drafts
+                const fetchCount = parsed.thread_id ? 100 : parsed.count;
+                const { drafts } = await client.listDrafts({ maxResults: fetchCount });
+                if (drafts.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'No drafts found.',
+                            },
+                        ],
+                    };
+                }
+                // Fetch full draft details to get headers (subject, to, etc.)
+                const fullDrafts = await Promise.all(drafts.map((d) => client.getDraft(d.id)));
+                // Filter by thread_id if specified
+                let filtered = fullDrafts;
+                if (parsed.thread_id) {
+                    filtered = fullDrafts.filter((d) => d.message.threadId === parsed.thread_id);
+                }
+                // Apply count limit after filtering
+                filtered = filtered.slice(0, parsed.count);
+                if (filtered.length === 0) {
+                    let noResultsText = parsed.thread_id
+                        ? `No drafts found for thread ${parsed.thread_id}.`
+                        : 'No drafts found.';
+                    if (parsed.thread_id && drafts.length >= 100) {
+                        noResultsText +=
+                            '\n\n*Note: Only the most recent 100 drafts were searched. The draft may exist beyond this limit.*';
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: noResultsText,
+                            },
+                        ],
+                    };
+                }
+                let responseText = `Found ${filtered.length} draft(s):\n`;
+                for (const draft of filtered) {
+                    const subject = getHeader(draft.message, 'Subject') || '(No Subject)';
+                    const to = getHeader(draft.message, 'To') || '(No Recipient)';
+                    responseText += `\n---\n`;
+                    responseText += `**Draft ID:** ${draft.id}\n`;
+                    responseText += `**Thread ID:** ${draft.message.threadId}\n`;
+                    responseText += `**To:** ${to}\n`;
+                    responseText += `**Subject:** ${subject}\n`;
+                    if (draft.message.snippet) {
+                        responseText += `**Preview:** ${draft.message.snippet}\n`;
+                    }
+                }
+                responseText +=
+                    '\n---\n\nUse upsert_draft_email with a draft_id to update a draft, or send_email with from_draft_id to send one.';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: responseText,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error listing drafts: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/send-email.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { getHeader } from '../utils/email-helpers.js';
+import { requestConfirmation, createConfirmationSchema, readElicitationConfig, } from '@pulsemcp/mcp-elicitation';
 const PARAM_DESCRIPTIONS = {
     to: 'Recipient email address(es). For multiple recipients, separate with commas.',
     subject: 'Subject line of the email.',
@@ -61,7 +62,7 @@ To send a reply to an existing email:
 **Use cases:**
 - Send a new email immediately
 - Reply to an existing email conversation
-- Send a draft that was created with draft_email
+- Send a draft that was created with upsert_draft_email
 
 **Warning:** This action sends the email immediately and cannot be undone.`;
 export function sendEmailTool(server, clientFactory) {
@@ -114,6 +115,66 @@ export function sendEmailTool(server, clientFactory) {
             try {
                 const parsed = SendEmailSchema.parse(args ?? {});
                 const client = clientFactory();
+                // Build a human-readable summary for the elicitation prompt
+                const elicitationConfig = readElicitationConfig();
+                if (elicitationConfig.enabled) {
+                    let confirmMessage;
+                    if (parsed.from_draft_id) {
+                        confirmMessage = `About to send draft (ID: ${parsed.from_draft_id}). This action cannot be undone.`;
+                    }
+                    else {
+                        confirmMessage =
+                            `About to send an email:\n` +
+                                `  To: ${parsed.to}\n` +
+                                `  Subject: ${parsed.subject}\n` +
+                                (parsed.cc ? `  CC: ${parsed.cc}\n` : '') +
+                                (parsed.bcc ? `  BCC: ${parsed.bcc}\n` : '') +
+                                `\nThis action cannot be undone.`;
+                    }
+                    const confirmation = await requestConfirmation({
+                        server,
+                        message: confirmMessage,
+                        requestedSchema: createConfirmationSchema('Send this email?', 'Confirm that you want to send this email immediately.'),
+                        meta: {
+                            'com.pulsemcp/tool-name': 'send_email',
+                        },
+                    }, elicitationConfig);
+                    if (confirmation.action === 'decline' || confirmation.action === 'cancel') {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'Email sending was cancelled by the user.',
+                                },
+                            ],
+                        };
+                    }
+                    if (confirmation.action === 'expired') {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'Email sending confirmation expired. Please try again.',
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    // action === 'accept' with content.confirm === true, or
+                    // action === 'accept' from disabled mode (no content)
+                    if (confirmation.content &&
+                        'confirm' in confirmation.content &&
+                        confirmation.content.confirm === false) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'Email sending was not confirmed. The email was not sent.',
+                                },
+                            ],
+                        };
+                    }
+                }
                 // Option 2: Send a draft
                 if (parsed.from_draft_id) {
                     const sentEmail = await client.sendDraft(parsed.from_draft_id);

package/shared/tools.js

@@ -2,7 +2,8 @@ import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprot
 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 { upsertDraftEmailTool } from './tools/draft-email.js';
+import { listDraftEmailsTool } from './tools/list-draft-emails.js';
 import { sendEmailTool } from './tools/send-email.js';
 import { searchEmailConversationsTool } from './tools/search-email-conversations.js';
 import { downloadEmailAttachmentsTool } from './tools/download-email-attachments.js';
@@ -10,8 +11,8 @@ const ALL_TOOL_GROUPS = ['readonly', 'readwrite', 'readwrite_external'];
 /**
  * All available tools with their group assignments
  *
- * readonly: list_email_conversations, get_email_conversation, search_email_conversations, download_email_attachments
- * readwrite: all readonly tools + change_email_conversation, draft_email
+ * readonly: list_email_conversations, get_email_conversation, search_email_conversations, download_email_attachments, list_draft_emails
+ * readwrite: all readonly tools + change_email_conversation, upsert_draft_email
  * readwrite_external: all readwrite tools + send_email (external communication)
  */
 const ALL_TOOLS = [
@@ -26,9 +27,11 @@ const ALL_TOOLS = [
         factory: downloadEmailAttachmentsTool,
         groups: ['readonly', 'readwrite', 'readwrite_external'],
     },
+    // List drafts is read-only (doesn't modify mailbox state)
+    { factory: listDraftEmailsTool, 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'] },
+    { factory: upsertDraftEmailTool, groups: ['readwrite', 'readwrite_external'] },
     // External communication tools (only in readwrite_external - most dangerous)
     { factory: sendEmailTool, groups: ['readwrite_external'] },
 ];