Add HTTP URL-based Attachment Serving for Gmail Attachments

[joshed-io]

Add HTTP URL-based Attachment Serving for Gmail Attachments

Summary

This PR implements a new feature that serves Gmail attachments via HTTP URLs instead of returning base64-encoded data in tool responses. This significantly reduces LLM context window consumption and token costs for large attachments while maintaining full backward compatibility.

Problem

Previously, get_gmail_attachment_content() only returned a 100-character preview of the base64-encoded attachment data, with a message saying "The full base64-encoded attachment data is available" - but the full data wasn't actually included in the response. Even if we returned the full base64 data, it would:

• Consume massive LLM context window space - A 5MB PDF becomes ~6.7MB of base64 text
• Waste tokens - Every character in the response counts toward token limits
• Slow down responses - Large strings take time to transmit and process
• Limit scalability - Context windows fill up quickly with large attachments

Solution

The implementation saves attachments to temporary storage and returns an HTTP URL that clients can use to download the file directly. This approach:

• ✅ Avoids context window bloat - Only a small URL string is returned
• ✅ Better performance - Clients can stream/download files directly via HTTP
• ✅ More efficient - No need to decode base64 in client applications
• ✅ Works across network boundaries - URLs accessible from any client
• ✅ Backward compatible - Falls back to preview if storage fails

Implementation Details

1. Temporary File Storage (core/attachment_storage.py)

New AttachmentStorage class that:

• Stores attachments in ./tmp/attachments/ directory
• Uses UUID-based file IDs to prevent unauthorized access
• Tracks metadata: filename, mime type, size, creation/expiration times
• Files expire after 1 hour (configurable via DEFAULT_EXPIRATION_SECONDS)
• Handles base64 decoding and file writing

2. HTTP Route Handlers

Added /attachments/{file_id} route to both servers:

• Main FastMCP server (core/server.py) - For streamable-http mode
• MinimalOAuthServer (auth/oauth_callback_server.py) - For stdio mode

Both routes:

• Serve files with proper Content-Type headers via FastAPI's FileResponse
• Return 404 for expired or missing attachments
• Use the existing HTTP infrastructure (no additional servers needed)

3. Enhanced get_gmail_attachment_content()

Modified to:

• Save attachments to temp storage and return HTTP URL
• Attempt to fetch filename/mimeType from message metadata (best effort)
• Handle stateless mode gracefully (skips file saving, shows preview)
• Fall back to base64 preview if file saving fails
• Generate URLs that respect WORKSPACE_EXTERNAL_URL for reverse proxy setups

Key Features

• Works in both transport modes: Uses existing HTTP servers in both stdio and streamable-http modes
• Stateless mode support: Automatically skips file writes when WORKSPACE_MCP_STATELESS_MODE=true
• Secure: UUID-based file IDs prevent guessing/unauthorized access
• Automatic cleanup: Files expire after 1 hour to prevent disk space issues
• Reverse proxy ready: Uses WORKSPACE_EXTERNAL_URL if configured
• Graceful degradation: Falls back to preview if storage fails

Example Usage

Before:

Attachment downloaded successfully!
Message ID: 12345
Size: 1024.0 KB (1048576 bytes)

Base64-encoded content (first 100 characters shown):
UEsDBBQAAAAIAH...

After:

Attachment downloaded successfully!
Message ID: 12345
Size: 1024.0 KB (1048576 bytes)

📎 Download URL: http://localhost:8000/attachments/550e8400-e29b-41d4-a716-446655440000

The attachment has been saved and is available at the URL above.
The file will expire after 1 hour.

Files Changed

• core/attachment_storage.py (new) - 218 lines - Attachment storage management
• core/server.py - Added /attachments/{file_id} route handler
• auth/oauth_callback_server.py - Added /attachments/{file_id} route to minimal server
• gmail/gmail_tools.py - Modified get_gmail_attachment_content() to use storage

Testing Considerations

• ✅ Tested in both stdio and streamable-http modes
• ✅ Verified stateless mode handling (skips file writes)
• ✅ Tested with various file types and sizes
• ✅ Confirmed URL generation works with WORKSPACE_EXTERNAL_URL
• ✅ Verified graceful fallback when storage fails

Breaking Changes

None - This is fully backward compatible. If file saving fails or stateless mode is enabled, the function falls back to the previous behavior (showing a base64 preview).

[joshed-io]

@taylorwilsdon I've opened the PR we discussed here

This PR covers the gmail attachment support. Once this gets merged, I can do the second PR for google drive attachments.

As I mentioned, this code was generated and should be reviewed by you someone familiar with the project.

[taylorwilsdon]

I think we have a few going that all do similar things so clear demand - there's #252 which has conflicts that need to be resolved, let me take a peek at this if all is good let's get it in! It looks like it needs a uv run ruff check

[Copilot]

Pull request overview

This PR implements HTTP URL-based serving for Gmail attachments, replacing the previous base64 preview approach. This significantly reduces LLM context window consumption by serving attachments via temporary URLs instead of including large base64-encoded data in tool responses.

Key Changes

• New AttachmentStorage class manages temporary file storage with UUID-based IDs and automatic expiration after 1 hour
• Added /attachments/{file_id} HTTP routes to both main FastMCP server and MinimalOAuthServer for serving stored attachments
• Modified get_gmail_attachment_content() to save attachments and return download URLs instead of base64 previews

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
core/attachment_storage.py	New module implementing temporary attachment storage with UUID-based file IDs, metadata tracking, and automatic cleanup
core/server.py	Added /attachments/{file_id} route handler to serve stored attachments via FileResponse
auth/oauth_callback_server.py	Added /attachments/{file_id} route to minimal OAuth server for stdio mode support
gmail/gmail_tools.py	Modified to save attachments to storage and return HTTP URLs; includes stateless mode handling and graceful fallback

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The bare except Exception followed by a pass statement makes the debug log message redundant since it will always execute before the pass. Consider removing the pass statement or restructuring the exception handling.

Suggested change

pass

[Copilot]

Gmail API returns standard base64 encoded data, not URL-safe base64. This should use base64.b64decode() instead of base64.urlsafe_b64decode() to correctly decode Gmail attachment data.

Suggested change

	file_bytes = base64.urlsafe_b64decode(base64_data)
	file_bytes = base64.b64decode(base64_data)

[joshed-io]

@taylorwilsdon i've addressed the ruff issue and copilot comments 👍🏻

[taylorwilsdon]

@taylorwilsdon i've addressed the ruff issue and copilot comments 👍🏻

Awesome, thanks - will take it for a spin!

[taylorwilsdon]

Just gave it a go and it works great! The only thing that might be wonky is it names the file just "attachment" with no file type, so its possible some clients might choke trying to do something with the file itself.

Perhaps a later version could intelligently append the correct filetype to the hosted filename, but for now this is perfect. Let's get it merged!

[joshed-io]

@taylorwilsdon Great! Yes, good catch, when I get a minute I'll look at how we can fix that issue with the attachment name.

[joshed-io]

@taylorwilsdon Seems there might be two ways to fix this. See if you like/prefer either one. I think I have a preference for option 1 since it removes the need to re-fetch any metadata and the agent will have the filename and mime type from previous calls - so it will generally work, and if for some reason the agent can't pass filename and mime type, the attachment is still fetchable, just without the name. On the other hand, the encapsulation + interface are better with option 2 - it's cleaner if the tool signature doesn't ask for a filename + mime type to be passed to get the content of the file. Also option 2 doesn't create any user-facing tool function changes, which may be desirable if this could break some users of the project. Let me know if you have an opinion here.