gmail-workspace-mcp-server 0.4.7 → 0.4.9

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

@@ -303,6 +303,9 @@ function createMockClient() {
                 labelIds: ['SENT'],
             };
         },
+        async getAccountEmail() {
+            return 'me@example.com';
+        },
     };
 }
 // =============================================================================

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

@@ -3,11 +3,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`
+ *   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`
+ *   ELICITATION_PREFER_HTTP_FALLBACK - "true" forces HTTP fallback over native elicitation
+ *                                      when both are available. Default: "false".
  */
 export declare function readElicitationConfig(env?: Record<string, string | undefined>): ElicitationConfig;

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

@@ -14,16 +14,20 @@ function parsePositiveInt(value, defaultValue) {
  * 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`
+ *   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`
+ *   ELICITATION_PREFER_HTTP_FALLBACK - "true" forces HTTP fallback over native elicitation
+ *                                      when both are available. Default: "false".
  */
 export function readElicitationConfig(env = process.env) {
     const enabledRaw = env.ELICITATION_ENABLED;
     const enabled = enabledRaw === undefined ? true : enabledRaw.toLowerCase() !== 'false';
+    const preferHttpFallbackRaw = env.ELICITATION_PREFER_HTTP_FALLBACK;
+    const preferHttpFallback = preferHttpFallbackRaw !== undefined && preferHttpFallbackRaw.toLowerCase() === 'true';
     const pollIntervalMs = Math.max(MIN_POLL_INTERVAL_MS, parsePositiveInt(env.ELICITATION_POLL_INTERVAL_MS, DEFAULT_POLL_INTERVAL_MS));
     return {
         enabled,
@@ -32,5 +36,6 @@ export function readElicitationConfig(env = process.env) {
         ttlMs: parsePositiveInt(env.ELICITATION_TTL_MS, DEFAULT_TTL_MS),
         pollIntervalMs,
         sessionId: env.ELICITATION_SESSION_ID,
+        preferHttpFallback,
     };
 }

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

@@ -2,12 +2,17 @@ import type { ElicitationConfig, ElicitationRequestedSchema, ElicitationResult,
 /**
  * Requests user confirmation through the best available mechanism.
  *
- * Decision tree:
+ * Decision tree (default):
  * 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.
  *
+ * When `cfg.preferHttpFallback` is true (set via `ELICITATION_PREFER_HTTP_FALLBACK=true`)
+ * AND both fallback URLs are configured, tier 3 runs before tier 2. This is intended for
+ * headless agent runtimes that falsely advertise elicitation capability but cannot actually
+ * surface the prompt to a user.
+ *
  * @param options - Configuration for the confirmation request.
  * @param config - Elicitation config (defaults to reading from env vars).
  * @returns The user's response.

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

@@ -98,15 +98,37 @@ async function pollElicitationStatus(config, requestId, expiresAt) {
     }
     return { action: 'expired' };
 }
+/**
+ * Runs the HTTP fallback flow: POST a request, then poll until resolved or expired.
+ */
+async function httpFallbackElicit(cfg, options) {
+    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);
+}
 /**
  * Requests user confirmation through the best available mechanism.
  *
- * Decision tree:
+ * Decision tree (default):
  * 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.
  *
+ * When `cfg.preferHttpFallback` is true (set via `ELICITATION_PREFER_HTTP_FALLBACK=true`)
+ * AND both fallback URLs are configured, tier 3 runs before tier 2. This is intended for
+ * headless agent runtimes that falsely advertise elicitation capability but cannot actually
+ * surface the prompt to a user.
+ *
  * @param options - Configuration for the confirmation request.
  * @param config - Elicitation config (defaults to reading from env vars).
  * @returns The user's response.
@@ -117,24 +139,18 @@ export async function requestConfirmation(options, config) {
     if (!cfg.enabled) {
         return { action: 'accept' };
     }
+    const httpFallbackAvailable = Boolean(cfg.requestUrl && cfg.pollUrl);
+    // Opt-in: prefer HTTP fallback over native elicitation when both are available.
+    if (cfg.preferHttpFallback && httpFallbackAvailable) {
+        return httpFallbackElicit(cfg, options);
+    }
     // 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);
+    if (httpFallbackAvailable) {
+        return httpFallbackElicit(cfg, options);
     }
     // Tier 4: No mechanism available
     throw new Error('Elicitation is enabled but no mechanism is available. ' +

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

@@ -64,6 +64,16 @@ export interface ElicitationConfig {
     pollIntervalMs: number;
     /** Session identifier included as `com.pulsemcp/session-id` in `_meta` of HTTP fallback requests. */
     sessionId?: string;
+    /**
+     * When true, prefer HTTP fallback (Tier 3) over native elicitation (Tier 2)
+     * when both are available. Default: false.
+     *
+     * Useful for headless agent runtimes (e.g., Claude Code under Agent Orchestrator)
+     * that advertise the `elicitation` client capability but have no real interactive
+     * user — native `elicitInput()` calls auto-cancel without ever surfacing a prompt.
+     * Forcing the HTTP fallback routes the request to an external approval UI instead.
+     */
+    preferHttpFallback?: boolean;
 }
 /**
  * The result of an elicitation request.

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

@@ -1,6 +1,6 @@
 {
   "name": "@pulsemcp/mcp-elicitation",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Elicitation support library for PulseMCP MCP servers - provides native elicitation with HTTP fallback",
   "type": "module",
   "main": "build/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gmail-workspace-mcp-server",
-  "version": "0.4.7",
+  "version": "0.4.9",
   "description": "MCP server for Gmail integration with OAuth2 and service account support",
   "main": "build/index.js",
   "type": "module",

package/shared/server.d.ts

@@ -119,6 +119,13 @@ export interface IGmailClient {
         data: string;
         size: number;
     }>;
+    /**
+     * Get the email address of the Gmail account this client reads from.
+     * Used to construct account-scoped Gmail web URLs so that links open in
+     * the correct mailbox regardless of which accounts the reader happens to
+     * be signed into in their browser.
+     */
+    getAccountEmail(): Promise<string>;
 }
 /**
  * Service account credentials structure
@@ -231,6 +238,7 @@ declare abstract class BaseGmailClient implements IGmailClient {
         data: string;
         size: number;
     }>;
+    getAccountEmail(): Promise<string>;
 }
 /**
  * Gmail API client implementation using service account with domain-wide delegation

package/shared/server.js

@@ -108,6 +108,9 @@ class BaseGmailClient {
         const { getAttachment } = await import('./gmail-client/lib/get-attachment.js');
         return getAttachment(this.baseUrl, headers, messageId, attachmentId);
     }
+    async getAccountEmail() {
+        return this.getSenderEmail();
+    }
 }
 /**
  * Gmail API client implementation using service account with domain-wide delegation

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

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { getHeader } from '../utils/email-helpers.js';
+import { buildGmailUrl, getHeader } from '../utils/email-helpers.js';
 const PARAM_DESCRIPTIONS = {
     email_id: 'The unique identifier of the email to retrieve. ' +
         'Obtain this from list_email_conversations or search_email_conversations.',
@@ -25,6 +25,7 @@ Full email details including:
 - Raw HTML body (when include_html is true and HTML content is available)
 - List of attachments (if any)
 - Labels assigned to the email
+- Account-scoped Gmail web URL (resolves to the correct mailbox regardless of the reader's browser session)
 
 **Use cases:**
 - Read the full content of an email after listing conversations
@@ -143,7 +144,11 @@ function formatFullEmail(email, options) {
     let output = `# Email Details
 
 **ID:** ${email.id}
-**Thread ID:** ${email.threadId}
+**Thread ID:** ${email.threadId}`;
+    if (options?.accountEmail) {
+        output += `\n**Gmail URL:** ${buildGmailUrl(options.accountEmail, email.id)}`;
+    }
+    output += `
 
 ## Headers
 **Subject:** ${subject}
@@ -210,11 +215,15 @@ export function getEmailConversationTool(server, clientFactory) {
             try {
                 const parsed = GetEmailConversationSchema.parse(args ?? {});
                 const client = clientFactory();
-                const email = await client.getMessage(parsed.email_id, {
-                    format: 'full',
-                });
+                const [email, accountEmail] = await Promise.all([
+                    client.getMessage(parsed.email_id, {
+                        format: 'full',
+                    }),
+                    client.getAccountEmail(),
+                ]);
                 const formattedEmail = formatFullEmail(email, {
                     includeHtml: parsed.include_html,
+                    accountEmail,
                 });
                 return {
                     content: [

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

@@ -37,6 +37,7 @@ A formatted list of email conversations with:
 - Sender (From)
 - Date received
 - Snippet preview
+- Account-scoped Gmail web URL (resolves to the correct mailbox regardless of the reader's browser session)
 
 **Use cases:**
 - Check recent inbox activity
@@ -113,18 +114,24 @@ export function listEmailConversationsTool(server, clientFactory) {
                         ],
                     };
                 }
-                // Fetch full details for each message
-                const emailDetails = await Promise.all(messages.map((msg) => client.getMessage(msg.id, {
-                    format: 'metadata',
-                    metadataHeaders: ['Subject', 'From', 'Date'],
-                })));
+                // Fetch full details for each message, plus the account email for
+                // building account-scoped Gmail URLs.
+                const [emailDetails, accountEmail] = await Promise.all([
+                    Promise.all(messages.map((msg) => client.getMessage(msg.id, {
+                        format: 'metadata',
+                        metadataHeaders: ['Subject', 'From', 'Date'],
+                    }))),
+                    client.getAccountEmail(),
+                ]);
                 // Sort based on sort_by parameter
                 const sortedEmails = [...emailDetails].sort((a, b) => {
                     const dateA = parseInt(a.internalDate, 10);
                     const dateB = parseInt(b.internalDate, 10);
                     return parsed.sort_by === 'recent' ? dateB - dateA : dateA - dateB;
                 });
-                const formattedEmails = sortedEmails.map(formatEmail).join('\n\n---\n\n');
+                const formattedEmails = sortedEmails
+                    .map((email) => formatEmail(email, accountEmail))
+                    .join('\n\n---\n\n');
                 return {
                     content: [
                         {

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

@@ -38,7 +38,7 @@ const TOOL_DESCRIPTION = `Search email conversations using Gmail's powerful sear
 - Use - to exclude: "subject:meeting -subject:canceled"
 
 **Returns:**
-A formatted list of matching emails with ID, Thread ID, Subject, From, Date, and snippet.
+A formatted list of matching emails with ID, Thread ID, Subject, From, Date, snippet, and an account-scoped Gmail web URL (resolves to the correct mailbox regardless of the reader's browser session).
 
 **Note:** Use get_email_conversation with an email ID to retrieve full message content.`;
 export function searchEmailConversationsTool(server, clientFactory) {
@@ -79,12 +79,18 @@ export function searchEmailConversationsTool(server, clientFactory) {
                         ],
                     };
                 }
-                // 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');
+                // Fetch full details for each message, plus the account email for
+                // building account-scoped Gmail URLs.
+                const [emailDetails, accountEmail] = await Promise.all([
+                    Promise.all(messages.map((msg) => client.getMessage(msg.id, {
+                        format: 'metadata',
+                        metadataHeaders: ['Subject', 'From', 'Date'],
+                    }))),
+                    client.getAccountEmail(),
+                ]);
+                const formattedEmails = emailDetails
+                    .map((email) => formatEmail(email, accountEmail))
+                    .join('\n\n---\n\n');
                 return {
                     content: [
                         {

package/shared/tools/send-email.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { getHeader } from '../utils/email-helpers.js';
+import { buildGmailUrl, 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.',
@@ -180,11 +180,15 @@ export function sendEmailTool(server, clientFactory) {
                 // Option 2: Send a draft
                 if (parsed.from_draft_id) {
                     const sentEmail = await client.sendDraft(parsed.from_draft_id);
+                    const accountEmail = await client.getAccountEmail();
                     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.`,
+                                text: `Draft sent successfully!\n\n**Message ID:** ${sentEmail.id}\n` +
+                                    `**Thread ID:** ${sentEmail.threadId}\n` +
+                                    `**Gmail URL:** ${buildGmailUrl(accountEmail, sentEmail.id)}\n\n` +
+                                    `The draft has been sent and removed from Drafts.`,
                             },
                         ],
                     };
@@ -220,7 +224,10 @@ export function sendEmailTool(server, clientFactory) {
                     inReplyTo,
                     references,
                 });
-                let responseText = `Email sent successfully!\n\n**Message ID:** ${sentEmail.id}\n**Thread ID:** ${sentEmail.threadId}`;
+                const accountEmail = await client.getAccountEmail();
+                let responseText = `Email sent successfully!\n\n**Message ID:** ${sentEmail.id}\n` +
+                    `**Thread ID:** ${sentEmail.threadId}\n` +
+                    `**Gmail URL:** ${buildGmailUrl(accountEmail, sentEmail.id)}`;
                 if (parsed.thread_id) {
                     responseText += '\n\nThis email was sent as a reply in an existing conversation.';
                 }

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

@@ -4,6 +4,22 @@ import type { Email } from '../types.js';
  */
 export declare function getHeader(email: Email, headerName: string): string | undefined;
 /**
- * Formats an email for display in tool output
+ * Builds an account-scoped Gmail web URL for a given message.
+ *
+ * Uses the `/mail/u/<account-email>/#inbox/<messageId>` path form so the link
+ * opens in the correct mailbox regardless of which accounts the reader is
+ * signed into in their browser. The user-INDEX form `/mail/u/0/` would
+ * otherwise open whichever account happens to be at index 0 in the reader's
+ * browser session, which is rarely the impersonated/OAuth account this
+ * server reads from.
+ *
+ * Gmail also accepts `?authuser=<email>` as a query-parameter fallback.
  */
-export declare function formatEmail(email: Email): string;
+export declare function buildGmailUrl(accountEmail: string, messageId: string): string;
+/**
+ * Formats an email for display in tool output.
+ *
+ * When `accountEmail` is provided, an account-scoped Gmail web URL is
+ * appended so the user can click through to the correct mailbox.
+ */
+export declare function formatEmail(email: Email, accountEmail?: string): string;

package/shared/utils/email-helpers.js

@@ -6,17 +6,39 @@ export function getHeader(email, headerName) {
         ?.value;
 }
 /**
- * Formats an email for display in tool output
+ * Builds an account-scoped Gmail web URL for a given message.
+ *
+ * Uses the `/mail/u/<account-email>/#inbox/<messageId>` path form so the link
+ * opens in the correct mailbox regardless of which accounts the reader is
+ * signed into in their browser. The user-INDEX form `/mail/u/0/` would
+ * otherwise open whichever account happens to be at index 0 in the reader's
+ * browser session, which is rarely the impersonated/OAuth account this
+ * server reads from.
+ *
+ * Gmail also accepts `?authuser=<email>` as a query-parameter fallback.
  */
-export function formatEmail(email) {
+export function buildGmailUrl(accountEmail, messageId) {
+    return `https://mail.google.com/mail/u/${encodeURIComponent(accountEmail)}/#inbox/${messageId}`;
+}
+/**
+ * Formats an email for display in tool output.
+ *
+ * When `accountEmail` is provided, an account-scoped Gmail web URL is
+ * appended so the user can click through to the correct mailbox.
+ */
+export function formatEmail(email, accountEmail) {
     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}
+    let output = `**ID:** ${email.id}
 **Thread ID:** ${email.threadId}
 **Subject:** ${subject}
 **From:** ${from}
 **Date:** ${date}
 **Preview:** ${snippet}`;
+    if (accountEmail) {
+        output += `\n**Gmail URL:** ${buildGmailUrl(accountEmail, email.id)}`;
+    }
+    return output;
 }