jxa-mail-mcp 0.1.0__py3-none-any.whl

jxa_mail_mcp/server.py

@@ -0,0 +1,353 @@
+"""
+JXA Mail MCP Server
+
+Provides MCP tools for interacting with Apple Mail via optimized JXA scripts.
+Uses batch property fetching for 87x faster performance.
+"""
+
+from fastmcp import FastMCP
+
+from .builders import AccountsQueryBuilder, QueryBuilder
+from .config import get_default_account, get_default_mailbox
+from .executor import execute_query, execute_with_core
+
+mcp = FastMCP("JXA Mail")
+
+
+def _resolve_account(account: str | None) -> str | None:
+    """Resolve account, using default from env if not specified."""
+    return account if account is not None else get_default_account()
+
+
+def _resolve_mailbox(mailbox: str | None) -> str:
+    """Resolve mailbox, using default from env if not specified."""
+    return mailbox if mailbox is not None else get_default_mailbox()
+
+
+@mcp.tool
+def list_accounts() -> list[dict]:
+    """
+    List all configured email accounts in Apple Mail.
+
+    Returns:
+        List of account dictionaries with 'name' and 'id' fields.
+
+    Example:
+        >>> list_accounts()
+        [{"name": "Work", "id": "abc123"}, {"name": "Personal", "id": "def456"}]
+    """
+    script = AccountsQueryBuilder().list_accounts()
+    return execute_with_core(script)
+
+
+@mcp.tool
+def list_mailboxes(account: str | None = None) -> list[dict]:
+    """
+    List all mailboxes for an email account.
+
+    Args:
+        account: Account name. Uses JXA_MAIL_DEFAULT_ACCOUNT env var or
+                 first account if not specified.
+
+    Returns:
+        List of mailbox dictionaries with 'name' and 'unreadCount' fields.
+
+    Example:
+        >>> list_mailboxes("Work")
+        [{"name": "INBOX", "unreadCount": 5}, ...]
+    """
+    script = AccountsQueryBuilder().list_mailboxes(_resolve_account(account))
+    return execute_with_core(script)
+
+
+@mcp.tool
+def get_emails(
+    account: str | None = None,
+    mailbox: str | None = None,
+    limit: int = 50,
+) -> list[dict]:
+    """
+    Get emails from a mailbox.
+
+    Retrieves emails with standard properties: id, subject, sender,
+    date_received, read status, and flagged status.
+
+    Args:
+        account: Account name. Uses JXA_MAIL_DEFAULT_ACCOUNT env var or
+                 first account if not specified.
+        mailbox: Mailbox name. Uses JXA_MAIL_DEFAULT_MAILBOX env var or
+                 "Inbox" if not specified.
+        limit: Maximum number of emails to return (default: 50)
+
+    Returns:
+        List of email dictionaries sorted by date (newest first).
+
+    Example:
+        >>> get_emails("Work", "INBOX", limit=10)
+        [{"subject": "Meeting tomorrow", "sender": "boss@work.com", ...}, ...]
+    """
+    query = (
+        QueryBuilder()
+        .from_mailbox(_resolve_account(account), _resolve_mailbox(mailbox))
+        .select("standard")
+        .order_by("date_received", descending=True)
+        .limit(limit)
+    )
+    return execute_query(query)
+
+
+@mcp.tool
+def get_todays_emails(
+    account: str | None = None,
+    mailbox: str | None = None,
+) -> list[dict]:
+    """
+    Get all emails received today from a mailbox.
+
+    Args:
+        account: Account name. Uses JXA_MAIL_DEFAULT_ACCOUNT env var or
+                 first account if not specified.
+        mailbox: Mailbox name. Uses JXA_MAIL_DEFAULT_MAILBOX env var or
+                 "Inbox" if not specified.
+
+    Returns:
+        List of today's emails sorted by date (newest first).
+
+    Example:
+        >>> get_todays_emails("Work")
+        [{"subject": "Urgent: Review needed", "sender": "team@work.com", ...}]
+    """
+    query = (
+        QueryBuilder()
+        .from_mailbox(_resolve_account(account), _resolve_mailbox(mailbox))
+        .select("standard")
+        .where("data.dateReceived[i] >= MailCore.today()")
+        .order_by("date_received", descending=True)
+    )
+    return execute_query(query)
+
+
+@mcp.tool
+def get_unread_emails(
+    account: str | None = None,
+    mailbox: str | None = None,
+    limit: int = 50,
+) -> list[dict]:
+    """
+    Get unread emails from a mailbox.
+
+    Args:
+        account: Account name. Uses JXA_MAIL_DEFAULT_ACCOUNT env var or
+                 first account if not specified.
+        mailbox: Mailbox name. Uses JXA_MAIL_DEFAULT_MAILBOX env var or
+                 "Inbox" if not specified.
+        limit: Maximum number of emails to return (default: 50)
+
+    Returns:
+        List of unread emails sorted by date (newest first).
+
+    Example:
+        >>> get_unread_emails("Work", limit=20)
+        [{"subject": "New message", "read": false, ...}, ...]
+    """
+    query = (
+        QueryBuilder()
+        .from_mailbox(_resolve_account(account), _resolve_mailbox(mailbox))
+        .select("standard")
+        .where("data.readStatus[i] === false")
+        .order_by("date_received", descending=True)
+        .limit(limit)
+    )
+    return execute_query(query)
+
+
+@mcp.tool
+def get_flagged_emails(
+    account: str | None = None,
+    mailbox: str | None = None,
+    limit: int = 50,
+) -> list[dict]:
+    """
+    Get flagged emails from a mailbox.
+
+    Args:
+        account: Account name. Uses JXA_MAIL_DEFAULT_ACCOUNT env var or
+                 first account if not specified.
+        mailbox: Mailbox name. Uses JXA_MAIL_DEFAULT_MAILBOX env var or
+                 "Inbox" if not specified.
+        limit: Maximum number of emails to return (default: 50)
+
+    Returns:
+        List of flagged emails sorted by date (newest first).
+
+    Example:
+        >>> get_flagged_emails("Work")
+        [{"subject": "Important task", "flagged": true, ...}, ...]
+    """
+    query = (
+        QueryBuilder()
+        .from_mailbox(_resolve_account(account), _resolve_mailbox(mailbox))
+        .select("standard")
+        .where("data.flaggedStatus[i] === true")
+        .order_by("date_received", descending=True)
+        .limit(limit)
+    )
+    return execute_query(query)
+
+
+@mcp.tool
+def search_emails(
+    query: str,
+    account: str | None = None,
+    mailbox: str | None = None,
+    limit: int = 50,
+) -> list[dict]:
+    """
+    Search for emails matching a query string.
+
+    Searches in both subject and sender fields (case-insensitive).
+
+    Args:
+        query: Search term to look for
+        account: Account name. Uses JXA_MAIL_DEFAULT_ACCOUNT env var or
+                 first account if not specified.
+        mailbox: Mailbox name. Uses JXA_MAIL_DEFAULT_MAILBOX env var or
+                 "Inbox" if not specified.
+        limit: Maximum number of results (default: 50)
+
+    Returns:
+        List of matching emails sorted by date (newest first).
+
+    Example:
+        >>> search_emails("invoice", "Work")
+        [{"subject": "Invoice #123", "sender": "billing@vendor.com", ...}]
+    """
+    # Escape the query for safe JavaScript string interpolation
+    safe_query = query.lower().replace("\\", "\\\\").replace("'", "\\'")
+
+    filter_expr = f"""(
+        (data.subject[i] || '').toLowerCase().includes('{safe_query}') ||
+        (data.sender[i] || '').toLowerCase().includes('{safe_query}')
+    )"""
+
+    q = (
+        QueryBuilder()
+        .from_mailbox(_resolve_account(account), _resolve_mailbox(mailbox))
+        .select("standard")
+        .where(filter_expr)
+        .order_by("date_received", descending=True)
+        .limit(limit)
+    )
+    return execute_query(q)
+
+
+@mcp.tool
+def fuzzy_search_emails(
+    query: str,
+    account: str | None = None,
+    mailbox: str | None = None,
+    limit: int = 20,
+    threshold: float = 0.3,
+) -> list[dict]:
+    """
+    Fuzzy search for emails using trigram + Levenshtein matching.
+
+    Finds emails even with typos or partial matches. Uses trigrams for
+    fast candidate selection and Levenshtein distance for accurate ranking.
+
+    Args:
+        query: Search term (fuzzy matched against subject and sender)
+        account: Account name. Uses JXA_MAIL_DEFAULT_ACCOUNT env var or
+                 first account if not specified.
+        mailbox: Mailbox name. Uses JXA_MAIL_DEFAULT_MAILBOX env var or
+                 "Inbox" if not specified.
+        limit: Maximum number of results (default: 20)
+        threshold: Minimum similarity score 0-1 (default: 0.3)
+
+    Returns:
+        List of matching emails with similarity scores, sorted by score.
+
+    Example:
+        >>> fuzzy_search_emails("joob descrption")  # typos OK
+        [{"subject": "Job Description", "score": 0.85, ...}, ...]
+    """
+    safe_query = query.replace("\\", "\\\\").replace("'", "\\'")
+    resolved_account = _resolve_account(account)
+    resolved_mailbox = _resolve_mailbox(mailbox)
+
+    # Build account reference
+    if resolved_account:
+        safe_account = resolved_account.replace("'", "\\'")
+        account_js = f"MailCore.getAccount('{safe_account}')"
+    else:
+        account_js = "MailCore.getAccount(null)"
+
+    safe_mailbox = resolved_mailbox.replace("'", "\\'")
+
+    script = f"""
+const account = {account_js};
+const mailbox = MailCore.getMailbox(account, '{safe_mailbox}');
+const msgs = mailbox.messages;
+const query = '{safe_query}';
+const threshold = {threshold};
+
+// Batch fetch properties
+const data = MailCore.batchFetch(msgs, [
+    'id', 'subject', 'sender', 'dateReceived', 'readStatus', 'flaggedStatus'
+]);
+
+const results = [];
+const count = data.id.length;
+
+for (let i = 0; i < count; i++) {{
+    const subject = data.subject[i] || '';
+    const sender = data.sender[i] || '';
+
+    // Try matching against subject and sender
+    const subjectMatch = MailCore.fuzzyMatch(query, subject);
+    const senderMatch = MailCore.fuzzyMatch(query, sender);
+
+    // Take the best match
+    let bestScore = 0;
+    let matchedIn = null;
+    let matchedText = null;
+
+    if (subjectMatch && subjectMatch.score > bestScore) {{
+        bestScore = subjectMatch.score;
+        matchedIn = 'subject';
+        matchedText = subjectMatch.matched;
+    }}
+    if (senderMatch && senderMatch.score > bestScore) {{
+        bestScore = senderMatch.score;
+        matchedIn = 'sender';
+        matchedText = senderMatch.matched;
+    }}
+
+    if (bestScore >= threshold) {{
+        results.push({{
+            id: data.id[i],
+            subject: subject,
+            sender: sender,
+            date_received: MailCore.formatDate(data.dateReceived[i]),
+            read: data.readStatus[i],
+            flagged: data.flaggedStatus[i],
+            score: Math.round(bestScore * 100) / 100,
+            matched_in: matchedIn,
+            matched_text: matchedText
+        }});
+    }}
+}}
+
+// Sort by score descending, then by date
+results.sort((a, b) => {{
+    if (b.score !== a.score) return b.score - a.score;
+    return new Date(b.date_received) - new Date(a.date_received);
+}});
+
+JSON.stringify(results.slice(0, {limit}));
+"""
+    return execute_with_core(script)
+
+
+if __name__ == "__main__":
+    mcp.run()

jxa_mail_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: jxa-mail-mcp
+Version: 0.1.0
+Summary: Fast MCP server for Apple Mail via optimized JXA scripts
+Project-URL: Homepage, https://github.com/imdinu/jxa-mail-mcp
+Project-URL: Repository, https://github.com/imdinu/jxa-mail-mcp
+Project-URL: Issues, https://github.com/imdinu/jxa-mail-mcp/issues
+Author-email: Ioan-Mihail Dinu <iodinu@icloud.com>
+License-Expression: GPL-3.0-or-later
+License-File: LICENSE
+Keywords: apple-mail,automation,email,jxa,macos,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: JavaScript
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Communications :: Email
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.13
+Requires-Dist: cyclopts>=5.0.0a1
+Requires-Dist: fastmcp<4,>=3.0.0b1
+Description-Content-Type: text/markdown
+
+# JXA Mail MCP
+
+A fast MCP (Model Context Protocol) server for Apple Mail, using optimized JXA (JavaScript for Automation) scripts with batch property fetching for **87x faster** performance.
+
+## Features
+
+- **list_accounts** - List all configured email accounts
+- **list_mailboxes** - List mailboxes for an account
+- **get_emails** - Fetch emails from any mailbox with pagination
+- **get_todays_emails** - Fetch all emails received today
+- **get_unread_emails** - Fetch unread emails
+- **get_flagged_emails** - Fetch flagged emails
+- **search_emails** - Search emails by subject or sender
+- **fuzzy_search_emails** - Typo-tolerant search using trigram + Levenshtein matching
+
+## Installation
+
+### With pipx (recommended)
+
+```bash
+pipx install jxa-mail-mcp
+```
+
+### From source
+
+Requires Python 3.13+ and [uv](https://docs.astral.sh/uv/):
+
+```bash
+git clone https://github.com/imdinu/jxa-mail-mcp
+cd jxa-mail-mcp
+uv sync
+```
+
+## Usage
+
+### Add to Claude Code
+
+After installing with pipx:
+
+```json
+{
+  "mcpServers": {
+    "mail": {
+      "command": "jxa-mail-mcp"
+    }
+  }
+}
+```
+
+Or from source:
+
+```json
+{
+  "mcpServers": {
+    "mail": {
+      "command": "uv",
+      "args": ["run", "--directory", "/path/to/jxa-mail-mcp", "jxa-mail-mcp"]
+    }
+  }
+}
+```
+
+### Run directly
+
+```bash
+jxa-mail-mcp
+```
+
+### Configuration
+
+Set default account and mailbox via environment variables:
+
+```bash
+export JXA_MAIL_DEFAULT_ACCOUNT="Work"
+export JXA_MAIL_DEFAULT_MAILBOX="Inbox"
+```
+
+Or in Claude Code config:
+
+```json
+{
+  "mcpServers": {
+    "mail": {
+      "command": "jxa-mail-mcp",
+      "env": {
+        "JXA_MAIL_DEFAULT_ACCOUNT": "Work"
+      }
+    }
+  }
+}
+```
+
+### Test in Python
+
+```python
+from jxa_mail_mcp.server import get_todays_emails, search_emails, fuzzy_search_emails
+
+emails = get_todays_emails(account="iCloud", mailbox="Inbox")
+results = search_emails("meeting", account="Work", limit=10)
+
+# Fuzzy search - tolerates typos
+results = fuzzy_search_emails("meetting nottes", limit=10)  # finds "meeting notes"
+```
+
+## Architecture
+
+```
+src/jxa_mail_mcp/
+├── __init__.py         # Exports mcp instance and main()
+├── server.py           # FastMCP server and MCP tools
+├── config.py           # Environment variable configuration
+├── builders.py         # QueryBuilder for constructing JXA scripts
+├── executor.py         # JXA script execution utilities
+└── jxa/
+    ├── __init__.py     # Exports MAIL_CORE_JS
+    └── mail_core.js    # Shared JXA utilities library
+```
+
+### Design Principles
+
+1. **Separation of concerns**: Python handles logic/types, JavaScript handles Mail.app interaction
+2. **Builder pattern**: `QueryBuilder` constructs optimized JXA scripts programmatically
+3. **Shared JS library**: `mail_core.js` provides reusable utilities injected into all scripts
+4. **Type safety**: Python type hints ensure correct usage
+
+## Performance
+
+### The Problem
+
+Naive AppleScript/JXA iteration is extremely slow:
+
+```javascript
+// SLOW: ~54 seconds for a few hundred messages
+for (let msg of inbox.messages()) {
+    results.push({
+        from: msg.sender(),      // IPC call to Mail.app
+        subject: msg.subject(),  // IPC call to Mail.app
+    });
+}
+```
+
+Each property access triggers a separate Apple Event IPC round-trip.
+
+### The Solution: Batch Property Fetching
+
+JXA supports fetching a property from all elements at once:
+
+```javascript
+// FAST: ~0.6 seconds (87x faster)
+const msgs = inbox.messages;
+const senders = msgs.sender();   // Single IPC call returns array
+const subjects = msgs.subject(); // Single IPC call returns array
+
+for (let i = 0; i < senders.length; i++) {
+    results.push({ from: senders[i], subject: subjects[i] });
+}
+```
+
+### Benchmark Results
+
+| Method | Time | Speedup |
+|--------|------|---------|
+| AppleScript (per-message) | 54.1s | 1x |
+| JXA (per-message) | 53.9s | 1x |
+| **JXA (batch fetching)** | **0.62s** | **87x** |
+
+### Fuzzy Search Performance
+
+Fuzzy search uses trigrams for fast candidate selection and Levenshtein distance for accurate ranking. Tested on a mailbox with ~6,000 emails:
+
+| Search Type | Time | Overhead |
+|-------------|------|----------|
+| Regular search | ~360ms | - |
+| Fuzzy search | ~480ms | +33% |
+
+The trigram pre-filtering keeps fuzzy search fast by avoiding expensive Levenshtein calculations on non-matching words.
+
+**Example**: Searching for "reserch studies" (typo) correctly finds "research studies" with 0.94 similarity score.
+
+## Development
+
+```bash
+uv sync
+uv run ruff check src/
+uv run ruff format src/
+
+# Test
+uv run python -c "
+from jxa_mail_mcp.server import list_accounts, get_todays_emails
+print('Accounts:', len(list_accounts()))
+print('Today:', len(get_todays_emails()))
+"
+```
+
+## License
+
+GPL-3.0-or-later

jxa_mail_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+jxa_mail_mcp/__init__.py,sha256=99llxfT4C82jO2bvqHNz8wjXcNhAW9yA1z8BdD7zNHw,205
+jxa_mail_mcp/builders.py,sha256=-dApdhFAndaCBnm6Lgt_isDjhGfbIfQO9xrB6JSG2zM,7571
+jxa_mail_mcp/config.py,sha256=yfzTGnfyu_9veyUxgNlSqgcci2fYe1v3rHbroUnPDxM,726
+jxa_mail_mcp/executor.py,sha256=fsIX59V1h0V2PWMiGstwAtS9MoX4mKDTDJdlTVLzYIg,2214
+jxa_mail_mcp/server.py,sha256=ZcBpTyRot7tKlzDs6YDVpjqangc22xzXx8TLYhHF5fE,10658
+jxa_mail_mcp/jxa/__init__.py,sha256=9UOQfRfZQNh-Z11msvBPYY34zFZALXXuk4moloqRT38,212
+jxa_mail_mcp/jxa/mail_core.js,sha256=D-ne9ZclJFOS0qCsQO9oEEyP2Wn4ie2KNxQLVEv5O_4,9230
+jxa_mail_mcp-0.1.0.dist-info/METADATA,sha256=idSfMCjy0sKWYbD5qYWLA5EWIs2REqI8EiVPRqHrI6s,5895
+jxa_mail_mcp-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+jxa_mail_mcp-0.1.0.dist-info/entry_points.txt,sha256=02Yq1vcKewiaIMcukAPh43Q2f4FmxhSzMGvwhD_7iJk,51
+jxa_mail_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
+jxa_mail_mcp-0.1.0.dist-info/RECORD,,

jxa_mail_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

jxa_mail_mcp-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+jxa-mail-mcp = jxa_mail_mcp:main