feat(gmail): Add flexible attachment support to send_gmail_message

[loserbcc]

Description

Adds flexible attachment support to the Gmail send_gmail_message tool with two modes of operation:

1. Local File Attachments (default) - Reads files from filesystem and attaches using proper multipart MIME
2. Public URL Attachments - Embeds clickable download links in HTML email body

Motivation

Email without attachment support is significantly limited. This feature fills a critical gap in the Google Workspace MCP Gmail functionality, making it feature-complete for email operations.

Related PRs

• PR Fix: Gmail send_message now respects user_google_email for From header #249: From header fix for multi-account support
• PR Fix multi-user credential switching in same session #253: Credential switching fix for multi-user sessions

These PRs work together to enable:

• Correct From header based on user_google_email (PR Fix: Gmail send_message now respects user_google_email for From header #249)
• Proper credential caching and switching (PR Fix multi-user credential switching in same session #253)
• File and URL attachment support (this PR)

Changes

• Added attachments parameter: Optional[List[str]] for file paths or URLs
• Added use_public_links parameter: bool to switch between modes
• Created helper function _prepare_gmail_message_with_file_attachments() (~130 lines)
• Created helper function _prepare_gmail_message_with_url_attachments() (~100 lines)
• Enhanced _prepare_gmail_message() with routing logic
• Added comprehensive documentation with usage examples

Features

✅ Auto-detects MIME types from file extensions
✅ Base64 encoding for binary files
✅ Graceful error handling (missing files logged, not fatal)
✅ Backward compatible (existing code unchanged)
✅ Well documented with examples
✅ Supports multiple attachments
✅ Works with threading/replies
✅ Integrates with multi-user credential system (PR #253)

Usage Examples

Local file attachments:

send_gmail_message(
    user_google_email="[email protected]",
    to="[email protected]",
    subject="Report Attached",
    body="Please review the attached report.",
    attachments=["/path/to/report.pdf", "/path/to/data.xlsx"]
)

Public URL attachments:

send_gmail_message(
    user_google_email="[email protected]",
    to="[email protected]",
    subject="Shared Files",
    body="Download files below.",
    attachments=["https://example.com/file.pdf"],
    use_public_links=True
)

Testing

• ✅ Code compiles without syntax errors
• ✅ Manual testing with local file attachments (image successfully sent)
• ✅ Multi-user credential switching verified ([email protected] → [email protected])
• ✅ Backward compatibility verified (no attachments works)
• ✅ Error handling verified (missing files logged gracefully)

Breaking Changes

None - all new parameters are optional with sensible defaults.

---

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]

[TYRONEMICHAEL]

Quick question whats the difference between this PR and #237