v1.3.0: Plugin Architecture Refactor & Smart Thread Optimization

🚀 Major Features

• Split attachment-analyzer into 3 specialized commands/skills

  • analyze-email: Quick single email overview
  • analyze-thread: Full conversation analysis with truncation handling
  • analyze-attachments: Deep file extraction with 3 modes (Quick/Interactive/Auto)

• Smart quote stripping reduces thread token usage by ~80%

  • Preserves first 10 lines of each quote block for context
  • Removes redundant quoted content automatically

• Configurable truncation limits

  • Thread emails: 1200 chars (configurable via MAIL_THREAD_MAX_BODY_LENGTH)
  • Single emails: 10000 chars (configurable via MAIL_SINGLE_MAX_BODY_LENGTH)
  • Automatic truncation detection and classification

• Enhanced attachment analysis

  • Importance classification (High/Medium/Low)
  • Three analysis modes for different use cases
  • Auto-cleanup of temporary files

📦 New Components

Skills

• plugins/mail-attachment-analyzer/skills/analyze-email/SKILL.md
• plugins/mail-attachment-analyzer/skills/analyze-thread/SKILL.md
• plugins/mail-attachment-analyzer/skills/analyze-attachments/SKILL.md

Commands

• plugins/mail-attachment-analyzer/commands/analyze-email.md
• plugins/mail-attachment-analyzer/commands/analyze-thread.md
• plugins/mail-attachment-analyzer/commands/analyze-attachments.md

Core Code

• src/quote_stripper.py: Intelligent quote detection and removal (249 lines)

⚙️ Environment Variables

{
  "MAIL_THREAD_MAX_BODY_LENGTH": "1200",    // Thread email limit
  "MAIL_SINGLE_MAX_BODY_LENGTH": "10000",   // Single email limit
  "MAIL_KEEP_QUOTE_LINES": "10",            // Quote context preservation
  "MAIL_ATTACHMENT_PATH": "/tmp"            // Extraction directory
}

📚 Documentation

• Comprehensive usage examples with 3 invocation methods
• Truncation handling guides for large threads
• Keyboard shortcut integration (⌘⇧C via Automator)
• Thread-specific email selection instructions
• Behavior differences between Slash Commands and Extension Skills

🐛 Performance

• 37-email thread: 365KB → 60KB (83.6% reduction)
• Automatic truncation detection: Classifies by importance (Critical/High/Medium)
• Smart attachment levels: High (gov/legal/finance), Medium (docs), Low (images)

🎯 User Experience

Three Invocation Methods

1. Natural Language: Direct prompts like "Analyze this email "
2. Slash Commands: /analyze-email, /analyze-thread, /analyze-attachments
3. Extension Skills: Auto-triggered with context memory

UX Improvements

• Automator Quick Action support (⌘⇧C shortcut)
• Thread email selection via "Show → Expand All Conversations"
• Auto-cleanup prevents disk space issues
• Context-aware mode selection (Quick/Interactive/Auto)

📊 Architecture Changes

Before: Single attachment-analyzer (388 lines)
After:  3 specialized skills + commands (~900 lines total)
         - Better separation of concerns
         - More focused functionality
         - Easier to maintain and extend

🔧 Migration Notes

• No breaking changes to MCP tools
• Old attachment-analyzer skill removed
• New skills automatically installed with Claude Code plugin
• Environment variables are optional (sensible defaults provided)

📝 Files Changed

• 14 files changed, 1621 insertions(+), 613 deletions(-)
• 3 new skills, 3 new commands
• 1 new core module (quote_stripper.py)
• Updated documentation (README_zh.md, TOOLS.md)
• Environment variables synced to mcp.json

🔒 Privacy

Updated example scenarios to use fictional data instead of real information

---

Full changelog: v1.2.0...v1.3.0

v1.1.0: Email Attachment Extraction

🎉 New Features

Email Attachment Extraction

• Extract email attachments for AI analysis (PDFs, documents, images)
• Attachment metadata in read_email output (filename, type, size)
• Cleanup tool for managing temporary attachment files

Technical Improvements

• Dual-source extraction: MIME payload + filesystem (for large attachments)
• Fuzzy filename matching to handle Mail.app's character sanitization
• Organized temp directory: {MAIL_ATTACHMENT_PATH}/mail-mcp-attachments/{message-id}/
• Project reorganized: All source code moved to src/ directory
• English documentation: mcp.json with English descriptions

📚 Documentation Updates

• Updated README.md and README_zh.md with attachment feature examples
• Complete API documentation in TOOLS.md
• Configuration examples with optional MAIL_ATTACHMENT_PATH environment variable

🔄 Migration from v1.0

If upgrading from v1.0, update your Claude Desktop config:

{
  "mcpServers": {
    "mail": {
      "command": "python3",
      "args": [
        "/path/to/mail-mcp-bridge/src/mail_mcp_server.py"
      ]
    }
  }
}

📖 Full Changelog

• feat: add email attachment extraction support
• refactor: reorganize project structure with src/ directory

---

Compare with v1.0

v1.0: Initial Stable Release

🎉 Mail MCP Bridge v1.0

First stable release of Mail MCP Bridge - connect macOS Mail to AI through Model Context Protocol.

✨ Key Features

• 📧 Direct Email Access: AI assistants (Claude, ChatGPT) can directly read your macOS Mail emails
• 🧵 Thread Support: Retrieve entire email conversations with one Message-ID
• ⚡ Lightning Fast: Millisecond-level query response
• 🎯 AI-Optimized: Clean plain text extraction, perfect for AI analysis
• 🔒 Privacy First: Local processing only, emails never leave your Mac

🛠️ MCP Tools

• get_email_path: Get single email file path by Message-ID
• get_thread_paths: Get all paths in an email thread
• read_email: Parse and read single email content
• read_thread: Read entire email thread

🚀 Quick Start

# Clone the repository
git clone https://github.com/fatbobman/mail-mcp-bridge.git
cd mail-mcp-bridge

# Install MCP dependencies
pip3 install mcp

# Configure Claude Desktop
# Edit ~/Library/Application Support/Claude/claude_desktop_config.json
# Add mail-mcp-bridge to mcpServers

# Setup Automator Quick Action for copying Message-ID
# See README.md for detailed instructions

📖 Documentation

• Quick Start Guide
• 中文文档
• API Reference
• Technical Architecture

🔧 Technical Highlights

• Mail V10 Database Support: Works on macOS 12.0+ (Monterey through Tahoe)
• ROWID Discovery: Critical finding that email filename = SQLite ROWID (not remote_id)
• Smart Parsing: Handles multipart emails, various encodings, Base64, quoted-printable
• Threading Headers: Extracts References and In-Reply-To for conversation analysis

🙏 Acknowledgments

Built for the MCP (Model Context Protocol) ecosystem. Inspired by the need to bridge email and AI.

📮 Feedback

• Issues: https://github.com/fatbobman/mail-mcp-bridge/issues
• Author: Fatbobman (Xu Yang)

---

Made with ❤️ for the AI community