gmail-workspace-mcp-server 0.1.0 → 0.1.1

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

@@ -61,6 +61,44 @@ const MOCK_EMAILS = [
         },
         sizeEstimate: 2048,
     },
+    {
+        id: 'msg_003',
+        threadId: 'thread_003',
+        labelIds: ['INBOX'],
+        snippet: 'Please find the invoice attached...',
+        historyId: '12347',
+        internalDate: String(Date.now() - 1000 * 60 * 60), // 1 hour ago
+        payload: {
+            mimeType: 'multipart/mixed',
+            headers: [
+                { name: 'Subject', value: 'Invoice Attached' },
+                { name: 'From', value: 'billing@example.com' },
+                { name: 'To', value: 'me@example.com' },
+                { name: 'Date', value: new Date(Date.now() - 1000 * 60 * 60).toISOString() },
+                { name: 'Message-ID', value: '<msg003@example.com>' },
+            ],
+            parts: [
+                {
+                    partId: '0',
+                    mimeType: 'text/plain',
+                    body: {
+                        size: 40,
+                        data: Buffer.from('Please find the invoice attached.').toString('base64url'),
+                    },
+                },
+                {
+                    partId: '1',
+                    mimeType: 'application/pdf',
+                    filename: 'invoice.pdf',
+                    body: {
+                        attachmentId: 'att_001',
+                        size: 1024,
+                    },
+                },
+            ],
+        },
+        sizeEstimate: 2048,
+    },
 ];
 const mockDrafts = [];
 let draftIdCounter = 1;
@@ -206,6 +244,16 @@ function createMockClient() {
             };
             return sentMessage;
         },
+        async getAttachment(_messageId, attachmentId) {
+            const mockData = {
+                att_001: Buffer.from('Mock PDF content').toString('base64url'),
+            };
+            const data = mockData[attachmentId];
+            if (!data) {
+                throw new Error(`Attachment not found: ${attachmentId}`);
+            }
+            return { data, size: Buffer.from(data, 'base64url').length };
+        },
         async sendDraft(draftId) {
             const draft = mockDrafts.find((d) => d.id === draftId);
             if (!draft) {

package/package.json

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

package/shared/gmail-client/lib/get-attachment.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Attachment data returned by the Gmail API
+ */
+export interface AttachmentData {
+    /** Base64url-encoded attachment data */
+    data: string;
+    /** Size of the attachment in bytes */
+    size: number;
+}
+/**
+ * Gets attachment data for a specific attachment on a message
+ * Uses the Gmail API: GET /messages/{messageId}/attachments/{attachmentId}
+ */
+export declare function getAttachment(baseUrl: string, headers: Record<string, string>, messageId: string, attachmentId: string): Promise<AttachmentData>;

package/shared/gmail-client/lib/get-attachment.js

@@ -0,0 +1,16 @@
+import { handleApiError } from './api-errors.js';
+/**
+ * Gets attachment data for a specific attachment on a message
+ * Uses the Gmail API: GET /messages/{messageId}/attachments/{attachmentId}
+ */
+export async function getAttachment(baseUrl, headers, messageId, attachmentId) {
+    const url = `${baseUrl}/messages/${messageId}/attachments/${attachmentId}`;
+    const response = await fetch(url, {
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'getting attachment', attachmentId);
+    }
+    return (await response.json());
+}

package/shared/server.d.ts

@@ -96,6 +96,13 @@ export interface IGmailClient {
      * Send a draft
      */
     sendDraft(draftId: string): Promise<Email>;
+    /**
+     * Get attachment data by message ID and attachment ID
+     */
+    getAttachment(messageId: string, attachmentId: string): Promise<{
+        data: string;
+        size: number;
+    }>;
 }
 /**
  * Service account credentials structure
@@ -191,6 +198,10 @@ declare abstract class BaseGmailClient implements IGmailClient {
         references?: string;
     }): Promise<Email>;
     sendDraft(draftId: string): Promise<Email>;
+    getAttachment(messageId: string, attachmentId: string): Promise<{
+        data: string;
+        size: number;
+    }>;
 }
 /**
  * Gmail API client implementation using service account with domain-wide delegation

package/shared/server.js

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

package/shared/tools/download-email-attachments.d.ts

@@ -0,0 +1,50 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { ClientFactory } from '../server.js';
+export declare const DownloadEmailAttachmentsSchema: z.ZodObject<{
+    email_id: z.ZodString;
+    filename: z.ZodOptional<z.ZodString>;
+    inline: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    email_id: string;
+    inline: boolean;
+    filename?: string | undefined;
+}, {
+    email_id: string;
+    filename?: string | undefined;
+    inline?: boolean | undefined;
+}>;
+export declare function downloadEmailAttachmentsTool(_server: Server, clientFactory: ClientFactory): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            email_id: {
+                type: string;
+                description: string;
+            };
+            filename: {
+                type: string;
+                description: string;
+            };
+            inline: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};

package/shared/tools/download-email-attachments.js

@@ -0,0 +1,276 @@
+import { writeFile, mkdir } from 'fs/promises';
+import { join, basename, extname } from 'path';
+import { z } from 'zod';
+/** Maximum total size (in bytes) for inline attachments (25 MB) */
+const MAX_INLINE_SIZE = 25 * 1024 * 1024;
+const PARAM_DESCRIPTIONS = {
+    email_id: 'The unique identifier of the email containing the attachment(s). ' +
+        'Obtain this from list_email_conversations, search_email_conversations, or get_email_conversation.',
+    filename: 'Optional filename to download a specific attachment. ' +
+        'If omitted, all attachments on the email are downloaded.',
+    inline: 'When true, return attachment content directly in the response (text-based files as text, binary as base64). ' +
+        'When false (default), save attachments to /tmp/ and return file paths.',
+};
+export const DownloadEmailAttachmentsSchema = z.object({
+    email_id: z.string().min(1).describe(PARAM_DESCRIPTIONS.email_id),
+    filename: z.string().optional().describe(PARAM_DESCRIPTIONS.filename),
+    inline: z.boolean().optional().default(false).describe(PARAM_DESCRIPTIONS.inline),
+});
+const TOOL_DESCRIPTION = `Download attachment content from a specific email.
+
+By default, saves all attachments to /tmp/ and returns the file paths. Use the inline parameter to return content directly in the response instead.
+
+**Parameters:**
+- email_id: The unique identifier of the email (required)
+- filename: Download only the attachment matching this filename (optional)
+- inline: If true, return content in the response instead of saving to files (optional, default: false)
+
+**Default behavior (inline=false):**
+Saves attachments as files to /tmp/ and returns the full file paths. Best for binary files or large attachments where you need to process the file afterward.
+
+**Inline behavior (inline=true):**
+Returns content directly. Text-based attachments (text/*, JSON, XML) are decoded to text. Binary attachments (PDF, images, etc.) are returned as base64. Total size is capped at 25 MB.
+
+**Use cases:**
+- Download invoices, receipts, or documents attached to emails
+- Extract data from CSV or text file attachments
+- Access PDF attachments for processing
+- Batch-download all attachments from an email in one call
+
+**Note:** Use get_email_conversation first to see attachment metadata (filenames, sizes, types) before downloading.`;
+/**
+ * Recursively extracts attachment info (including attachmentId) from email parts
+ */
+function getAttachmentInfos(parts) {
+    if (!parts)
+        return [];
+    const attachments = [];
+    for (const part of parts) {
+        if (part.filename && part.body?.attachmentId) {
+            attachments.push({
+                filename: part.filename,
+                mimeType: part.mimeType,
+                size: part.body.size,
+                attachmentId: part.body.attachmentId,
+            });
+        }
+        if (part.parts) {
+            attachments.push(...getAttachmentInfos(part.parts));
+        }
+    }
+    return attachments;
+}
+/**
+ * Converts base64url to standard base64
+ */
+function base64UrlToBase64(data) {
+    return data.replace(/-/g, '+').replace(/_/g, '/');
+}
+/**
+ * Returns true if the MIME type represents text-based content
+ */
+function isTextMimeType(mimeType) {
+    if (mimeType.startsWith('text/'))
+        return true;
+    if (mimeType === 'application/json')
+        return true;
+    if (mimeType === 'application/xml')
+        return true;
+    if (mimeType.endsWith('+json') || mimeType.endsWith('+xml'))
+        return true;
+    return false;
+}
+/**
+ * Builds inline response with attachment content in the response text
+ */
+function buildInlineResponse(results) {
+    const outputParts = [];
+    const summaryLines = results.map((r, i) => {
+        const sizeKb = Math.round(r.size / 1024);
+        return `${i + 1}. ${r.filename} (${r.mimeType}, ${sizeKb} KB)`;
+    });
+    outputParts.push(`# Downloaded Attachments (${results.length})\n\n${summaryLines.join('\n')}`);
+    for (const result of results) {
+        const base64Data = base64UrlToBase64(result.data);
+        if (isTextMimeType(result.mimeType)) {
+            const textContent = Buffer.from(base64Data, 'base64').toString('utf-8');
+            outputParts.push(`---\n## ${result.filename}\n\n${textContent}`);
+        }
+        else {
+            outputParts.push(`---\n## ${result.filename}\n\n` +
+                `**MIME Type:** ${result.mimeType}\n` +
+                `**Encoding:** base64\n\n` +
+                `\`\`\`\n${base64Data}\n\`\`\``);
+        }
+    }
+    return {
+        content: [{ type: 'text', text: outputParts.join('\n\n') }],
+    };
+}
+/**
+ * Sanitizes a filename to prevent path traversal attacks.
+ * Strips directory components and falls back to 'attachment' if empty.
+ */
+function sanitizeFilename(filename) {
+    return basename(filename) || 'attachment';
+}
+/**
+ * Returns a unique filename, appending (1), (2), etc. if the name already exists.
+ */
+function deduplicateFilename(name, usedNames) {
+    if (!usedNames.has(name)) {
+        usedNames.add(name);
+        return name;
+    }
+    const ext = extname(name);
+    const base = name.slice(0, name.length - ext.length);
+    let counter = 1;
+    let candidate;
+    do {
+        candidate = `${base} (${counter})${ext}`;
+        counter++;
+    } while (usedNames.has(candidate));
+    usedNames.add(candidate);
+    return candidate;
+}
+/**
+ * Saves attachments to /tmp/ and returns file paths
+ */
+async function buildFileResponse(results, emailId) {
+    const safeEmailId = emailId.replace(/[^a-zA-Z0-9_-]/g, '_');
+    const dir = join('/tmp', `gmail-attachments-${safeEmailId}`);
+    await mkdir(dir, { recursive: true });
+    const savedFiles = [];
+    const usedNames = new Set();
+    for (const result of results) {
+        const base64Data = base64UrlToBase64(result.data);
+        const buffer = Buffer.from(base64Data, 'base64');
+        const safeName = deduplicateFilename(sanitizeFilename(result.filename), usedNames);
+        const filePath = join(dir, safeName);
+        await writeFile(filePath, buffer);
+        savedFiles.push({
+            filename: result.filename,
+            path: filePath,
+            mimeType: result.mimeType,
+            size: buffer.length,
+        });
+    }
+    const outputParts = [];
+    const summaryLines = savedFiles.map((f, i) => {
+        const sizeKb = Math.round(f.size / 1024);
+        return `${i + 1}. ${f.filename} (${f.mimeType}, ${sizeKb} KB)`;
+    });
+    outputParts.push(`# Downloaded Attachments (${savedFiles.length})\n\n${summaryLines.join('\n')}`);
+    outputParts.push('## Saved Files\n');
+    for (const file of savedFiles) {
+        outputParts.push(`- **${file.filename}**: \`${file.path}\``);
+    }
+    return {
+        content: [{ type: 'text', text: outputParts.join('\n') }],
+    };
+}
+export function downloadEmailAttachmentsTool(_server, clientFactory) {
+    return {
+        name: 'download_email_attachments',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                email_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.email_id,
+                },
+                filename: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.filename,
+                },
+                inline: {
+                    type: 'boolean',
+                    description: PARAM_DESCRIPTIONS.inline,
+                },
+            },
+            required: ['email_id'],
+        },
+        handler: async (args) => {
+            try {
+                const parsed = DownloadEmailAttachmentsSchema.parse(args ?? {});
+                const client = clientFactory();
+                // Fetch the email to discover attachments
+                const email = await client.getMessage(parsed.email_id, { format: 'full' });
+                const allAttachments = [];
+                // Check payload-level attachment (single-part email with attachment)
+                if (email.payload?.filename && email.payload?.body?.attachmentId) {
+                    allAttachments.push({
+                        filename: email.payload.filename,
+                        mimeType: email.payload.mimeType,
+                        size: email.payload.body.size,
+                        attachmentId: email.payload.body.attachmentId,
+                    });
+                }
+                // Check nested parts for attachments
+                allAttachments.push(...getAttachmentInfos(email.payload?.parts));
+                if (allAttachments.length === 0) {
+                    return {
+                        content: [{ type: 'text', text: 'No attachments found on this email.' }],
+                    };
+                }
+                // Filter by filename if specified
+                let targetAttachments = allAttachments;
+                if (parsed.filename) {
+                    targetAttachments = allAttachments.filter((a) => a.filename === parsed.filename);
+                    if (targetAttachments.length === 0) {
+                        const available = allAttachments.map((a) => a.filename).join(', ');
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Attachment "${parsed.filename}" not found. Available attachments: ${available}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
+                // For inline mode, enforce size limit
+                if (parsed.inline) {
+                    const totalSize = targetAttachments.reduce((sum, a) => sum + a.size, 0);
+                    if (totalSize > MAX_INLINE_SIZE) {
+                        const totalMb = (totalSize / (1024 * 1024)).toFixed(1);
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Total attachment size (${totalMb} MB) exceeds the 25 MB limit for inline mode. ` +
+                                        `Use inline=false (default) to save to files, or use the filename parameter to download individually.`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
+                // Download all target attachments concurrently
+                const results = await Promise.all(targetAttachments.map(async (att) => {
+                    const data = await client.getAttachment(parsed.email_id, att.attachmentId);
+                    return { ...att, data: data.data };
+                }));
+                if (parsed.inline) {
+                    return buildInlineResponse(results);
+                }
+                else {
+                    return await buildFileResponse(results, parsed.email_id);
+                }
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error downloading attachment(s): ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools.d.ts

@@ -2,7 +2,8 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ClientFactory } from './server.js';
 /**
  * Available tool groups for Gmail MCP server
- * - readonly: Read-only operations (list, get, search emails)
+ * - readonly: Read-only Gmail operations (list, get, search, download_attachments)
+ *   Note: download_email_attachments writes to local /tmp/ but does not modify mailbox state
  * - readwrite: Read and write operations (includes readonly + modify, draft)
  * - readwrite_external: External communication operations (includes readwrite + send_email)
  */

package/shared/tools.js

@@ -5,11 +5,12 @@ import { changeEmailConversationTool } from './tools/change-email-conversation.j
 import { draftEmailTool } from './tools/draft-email.js';
 import { sendEmailTool } from './tools/send-email.js';
 import { searchEmailConversationsTool } from './tools/search-email-conversations.js';
+import { downloadEmailAttachmentsTool } from './tools/download-email-attachments.js';
 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
+ * readonly: list_email_conversations, get_email_conversation, search_email_conversations, download_email_attachments
  * readwrite: all readonly tools + change_email_conversation, draft_email
  * readwrite_external: all readwrite tools + send_email (external communication)
  */
@@ -21,6 +22,10 @@ const ALL_TOOLS = [
         factory: searchEmailConversationsTool,
         groups: ['readonly', 'readwrite', 'readwrite_external'],
     },
+    {
+        factory: downloadEmailAttachmentsTool,
+        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'] },