feat: add attachment support to gmail.createDraft tool

mickey-mikey · claude · mickey-mikey · commit 23599f41ef9c · 2026-05-04T22:46:37.000+10:00
- Update MimeHelper.createMimeMessageWithAttachments to support inReplyTo
  and references headers for proper threading with attachments
- Add attachments parameter to GmailService.createDraft with file reading
  and MIME type inference from file extension
- Extend gmail.createDraft MCP tool schema to accept attachments array
- Add comprehensive tests for attachment handling, MIME type detection,
  threading with attachments, error handling, and empty attachments
- All 522 tests pass

Co-Authored-By: Claude Haiku 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
@@ -0,0 +1,11 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /c/Users/James/dev/workspace diff main HEAD -- workspace-server/src/services/GmailService.ts workspace-server/src/utils/MimeHelper.ts workspace-server/src/index.ts)",
+      "Bash(git -C /c/Users/James/dev/workspace status)",
+      "Bash(git -C /c/Users/James/dev/workspace log --oneline -5)",
+      "Bash(git *)"
+    ]
+  },
+  "enableAllProjectMcpServers": true
+}
diff --git a/.mcp.json b/.mcp.json
@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "gemini-workspace": {
+      "type": "stdio",
+      "command": "node",
+      "args": [
+        "workspace-server/dist/index.js",
+        "--use-dot-names"
+      ],
+      "env": {}
+    }
+  }
+}
diff --git a/workspace-server/src/__tests__/services/GmailService.test.ts b/workspace-server/src/__tests__/services/GmailService.test.ts
@@ -20,7 +20,7 @@ import { google } from 'googleapis';
 
 // Mock the modules
 jest.mock('googleapis');
-jest.mock('fs/promises');
+jest.mock('node:fs/promises');
 jest.mock('../../utils/logger');
 jest.mock('../../utils/MimeHelper');
 
@@ -822,6 +822,9 @@ describe('GmailService', () => {
       (MimeHelper.createMimeMessage as jest.Mock) = jest
         .fn()
         .mockReturnValue('base64encodedmessage');
+      (MimeHelper.createMimeMessageWithAttachments as jest.Mock) = jest
+        .fn()
+        .mockReturnValue('base64encodedmessage-with-attachments');
     });
 
     it('should create a draft email', async () => {
@@ -994,6 +997,228 @@ describe('GmailService', () => {
       const response = JSON.parse(result.content[0].text);
       expect(response.status).toBe('draft_created');
     });
+
+    it('should create a draft with attachments using createMimeMessageWithAttachments', async () => {
+      const mockDraft = {
+        id: 'draft-attach-1',
+        message: { id: 'msg-attach-1', threadId: null, labelIds: ['DRAFT'] },
+      };
+      mockGmailAPI.users.drafts.create.mockResolvedValue({ data: mockDraft });
+
+      const mockFileBuffer = Buffer.from('PDF content');
+      (fs.readFile as any).mockResolvedValue(mockFileBuffer);
+
+      const result = await gmailService.createDraft({
+        to: 'recipient@example.com',
+        subject: 'Draft with Attachment',
+        body: 'See attached.',
+        attachments: [{ filePath: '/tmp/report.pdf', mimeType: 'application/pdf' }],
+      });
+
+      expect((fs.readFile as any).mock.calls[0][0]).toBe('/tmp/report.pdf');
+      expect(
+        MimeHelper.createMimeMessageWithAttachments as jest.Mock,
+      ).toHaveBeenCalledWith(
+        expect.objectContaining({
+          attachments: [
+            {
+              filename: 'report.pdf',
+              content: mockFileBuffer,
+              contentType: 'application/pdf',
+            },
+          ],
+          inReplyTo: undefined,
+          references: undefined,
+        }),
+      );
+      expect(MimeHelper.createMimeMessage).not.toHaveBeenCalled();
+
+      expect(mockGmailAPI.users.drafts.create).toHaveBeenCalledWith({
+        userId: 'me',
+        requestBody: { message: { raw: 'base64encodedmessage-with-attachments' } },
+      });
+
+      const response = JSON.parse(result.content[0].text);
+      expect(response.status).toBe('draft_created');
+      expect(response.id).toBe('draft-attach-1');
+    });
+
+    it('should use filename override when provided', async () => {
+      mockGmailAPI.users.drafts.create.mockResolvedValue({
+        data: { id: 'draft2', message: { id: 'msg2', threadId: null, labelIds: [] } },
+      });
+      (fs.readFile as any).mockResolvedValue(Buffer.from('data'));
+
+      await gmailService.createDraft({
+        to: 'a@example.com',
+        subject: 'S',
+        body: 'B',
+        attachments: [{ filePath: '/tmp/123abc.tmp', filename: 'custom-name.pdf' }],
+      });
+
+      expect(
+        MimeHelper.createMimeMessageWithAttachments as jest.Mock,
+      ).toHaveBeenCalledWith(
+        expect.objectContaining({
+          attachments: expect.arrayContaining([
+            expect.objectContaining({ filename: 'custom-name.pdf' }),
+          ]),
+        }),
+      );
+    });
+
+    it('should infer MIME type from extension when mimeType not provided', async () => {
+      mockGmailAPI.users.drafts.create.mockResolvedValue({
+        data: { id: 'd3', message: { id: 'm3', threadId: null, labelIds: [] } },
+      });
+      (fs.readFile as any).mockResolvedValue(Buffer.from('data'));
+
+      await gmailService.createDraft({
+        to: 'a@example.com',
+        subject: 'S',
+        body: 'B',
+        attachments: [{ filePath: '/tmp/report.xlsx' }],
+      });
+
+      expect(
+        MimeHelper.createMimeMessageWithAttachments as jest.Mock,
+      ).toHaveBeenCalledWith(
+        expect.objectContaining({
+          attachments: expect.arrayContaining([
+            expect.objectContaining({
+              contentType:
+                'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+            }),
+          ]),
+        }),
+      );
+    });
+
+    it('should fall back to application/octet-stream for unknown extension', async () => {
+      mockGmailAPI.users.drafts.create.mockResolvedValue({
+        data: { id: 'd4', message: { id: 'm4', threadId: null, labelIds: [] } },
+      });
+      (fs.readFile as any).mockResolvedValue(Buffer.from('data'));
+
+      await gmailService.createDraft({
+        to: 'a@example.com',
+        subject: 'S',
+        body: 'B',
+        attachments: [{ filePath: '/tmp/mystery.xyz' }],
+      });
+
+      expect(
+        MimeHelper.createMimeMessageWithAttachments as jest.Mock,
+      ).toHaveBeenCalledWith(
+        expect.objectContaining({
+          attachments: expect.arrayContaining([
+            expect.objectContaining({ contentType: 'application/octet-stream' }),
+          ]),
+        }),
+      );
+    });
+
+    it('should pass inReplyTo and references to createMimeMessageWithAttachments for threaded draft with attachments', async () => {
+      const mockDraft = {
+        id: 'draft-thread-attach',
+        message: { id: 'msg-ta', threadId: 'thread1', labelIds: ['DRAFT'] },
+      };
+      mockGmailAPI.users.threads.get.mockResolvedValue({
+        data: {
+          messages: [
+            {
+              payload: {
+                headers: [
+                  { name: 'Message-ID', value: '<orig@mail.example.com>' },
+                  { name: 'References', value: '<prev@mail.example.com>' },
+                ],
+              },
+            },
+          ],
+        },
+      });
+      mockGmailAPI.users.drafts.create.mockResolvedValue({ data: mockDraft });
+      (fs.readFile as any).mockResolvedValue(Buffer.from('data'));
+
+      const result = await gmailService.createDraft({
+        to: 'b@example.com',
+        subject: 'Re: Attached Reply',
+        body: 'See file.',
+        threadId: 'thread1',
+        attachments: [{ filePath: '/tmp/file.pdf' }],
+      });
+
+      expect(
+        MimeHelper.createMimeMessageWithAttachments as jest.Mock,
+      ).toHaveBeenCalledWith(
+        expect.objectContaining({
+          inReplyTo: '<orig@mail.example.com>',
+          references: '<prev@mail.example.com> <orig@mail.example.com>',
+        }),
+      );
+      expect(mockGmailAPI.users.drafts.create).toHaveBeenCalledWith({
+        userId: 'me',
+        requestBody: {
+          message: {
+            raw: 'base64encodedmessage-with-attachments',
+            threadId: 'thread1',
+          },
+        },
+      });
+
+      const response = JSON.parse(result.content[0].text);
+      expect(response.status).toBe('draft_created');
+    });
+
+    it('should reject a relative filePath and return error without calling Gmail API', async () => {
+      const result = await gmailService.createDraft({
+        to: 'a@example.com',
+        subject: 'S',
+        body: 'B',
+        attachments: [{ filePath: 'relative/path/file.pdf' }],
+      });
+
+      const response = JSON.parse(result.content[0].text);
+      expect(response.error).toContain('must be an absolute path');
+      expect(mockGmailAPI.users.drafts.create).not.toHaveBeenCalled();
+      expect((fs.readFile as any).mock.calls).toHaveLength(0);
+    });
+
+    it('should handle readFile failure (file not found) gracefully', async () => {
+      (fs.readFile as any).mockRejectedValue(
+        new Error('ENOENT: no such file'),
+      );
+
+      const result = await gmailService.createDraft({
+        to: 'a@example.com',
+        subject: 'S',
+        body: 'B',
+        attachments: [{ filePath: '/tmp/missing.pdf' }],
+      });
+
+      const response = JSON.parse(result.content[0].text);
+      expect(response.error).toContain('ENOENT');
+      expect(mockGmailAPI.users.drafts.create).not.toHaveBeenCalled();
+    });
+
+    it('should use createMimeMessage (not WithAttachments) when attachments array is empty', async () => {
+      mockGmailAPI.users.drafts.create.mockResolvedValue({
+        data: { id: 'd5', message: { id: 'm5', threadId: null, labelIds: [] } },
+      });
+
+      await gmailService.createDraft({
+        to: 'a@example.com',
+        subject: 'S',
+        body: 'B',
+        attachments: [],
+      });
+
+      expect(MimeHelper.createMimeMessage).toHaveBeenCalled();
+      expect(
+        MimeHelper.createMimeMessageWithAttachments as jest.Mock,
+      ).not.toHaveBeenCalled();
+      expect((fs.readFile as any).mock.calls).toHaveLength(0);
+    });
   });
 
   describe('sendDraft', () => {
diff --git a/workspace-server/src/__tests__/utils/MimeHelper.test.ts b/workspace-server/src/__tests__/utils/MimeHelper.test.ts
@@ -365,6 +365,74 @@ describe('MimeHelper', () => {
       expect(boundary2Match).toBeTruthy();
       expect(boundary1Match![1]).not.toBe(boundary2Match![1]);
     });
+
+    it('should include In-Reply-To and References headers when provided with attachments', () => {
+      const messageId = '<original@mail.example.com>';
+      const refs = '<earlier@mail.example.com> <original@mail.example.com>';
+      const attachments = [
+        {
+          filename: 'test.txt',
+          content: Buffer.from('hello'),
+          contentType: 'text/plain',
+        },
+      ];
+
+      const encoded = MimeHelper.createMimeMessageWithAttachments({
+        to: 'recipient@example.com',
+        subject: 'Re: Test',
+        body: 'Reply with attachment',
+        inReplyTo: messageId,
+        references: refs,
+        attachments,
+      });
+
+      const decoded = MimeHelper.decodeBase64Url(encoded);
+
+      expect(decoded).toContain(`In-Reply-To: ${messageId}`);
+      expect(decoded).toContain(`References: ${refs}`);
+      // Still multipart
+      expect(decoded).toContain('Content-Type: multipart/mixed; boundary=');
+    });
+
+    it('should include In-Reply-To and References headers when no attachments (fallback path)', () => {
+      const messageId = '<original@mail.example.com>';
+
+      const encoded = MimeHelper.createMimeMessageWithAttachments({
+        to: 'recipient@example.com',
+        subject: 'Re: Test',
+        body: 'Reply without attachment',
+        inReplyTo: messageId,
+        references: messageId,
+        // no attachments — exercises the createMimeMessage fallback
+      });
+
+      const decoded = MimeHelper.decodeBase64Url(encoded);
+
+      expect(decoded).toContain(`In-Reply-To: ${messageId}`);
+      expect(decoded).toContain(`References: ${messageId}`);
+    });
+
+    it('should not include In-Reply-To or References in multipart message when not provided', () => {
+      const attachments = [
+        {
+          filename: 'file.pdf',
+          content: Buffer.from('data'),
+          contentType: 'application/pdf',
+        },
+      ];
+
+      const encoded = MimeHelper.createMimeMessageWithAttachments({
+        to: 'recipient@example.com',
+        subject: 'New Draft',
+        body: 'Body',
+        attachments,
+      });
+
+      const decoded = MimeHelper.decodeBase64Url(encoded);
+
+      expect(decoded).not.toContain('In-Reply-To:');
+      expect(decoded).not.toContain('References:');
+    });
   });
 
   describe('decodeBase64Url', () => {
diff --git a/workspace-server/src/index.ts b/workspace-server/src/index.ts
@@ -1299,6 +1299,32 @@ System labels that can be modified:
           .describe(
             'The thread ID to create the draft as a reply to. When provided, the draft will be linked to the existing thread with appropriate reply headers.',
           ),
+        attachments: z
+          .array(
+            z.object({
+              filePath: z
+                .string()
+                .describe(
+                  'Absolute local filesystem path to the file to attach (e.g., "/Users/name/downloads/report.pdf"). Use gmail.downloadAttachment first to save an email attachment locally before referencing it here.',
+                ),
+              filename: z
+                .string()
+                .optional()
+                .describe(
+                  'Display name for the attachment in the email. Defaults to the filename portion of filePath.',
+                ),
+              mimeType: z
+                .string()
+                .optional()
+                .describe(
+                  'MIME type of the attachment (e.g., "application/pdf"). Inferred from the file extension when omitted; falls back to "application/octet-stream".',
+                ),
+            }),
+          )
+          .optional()
+          .describe(
+            'Files to attach to the draft. Each entry must reference an absolute local path. Download attachments first with gmail.downloadAttachment if needed.',
+          ),
       },
     },
     gmailService.createDraft,
diff --git a/workspace-server/src/services/GmailService.ts b/workspace-server/src/services/GmailService.ts
diff --git a/workspace-server/src/utils/MimeHelper.ts b/workspace-server/src/utils/MimeHelper.ts
