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

jxa_mail_mcp/__init__.py

@@ -0,0 +1,10 @@
+"""JXA Mail MCP - Fast Apple Mail automation via optimized JXA scripts."""
+
+from .server import mcp
+
+__all__ = ["main", "mcp"]
+
+
+def main() -> None:
+    """Entry point for the MCP server."""
+    mcp.run()

jxa_mail_mcp/builders.py

@@ -0,0 +1,243 @@
+"""
+JXA Script Builders for Apple Mail operations.
+
+These builders generate optimized JXA scripts that use batch property
+fetching for maximum performance.
+"""
+
+import json
+from dataclasses import dataclass, field
+
+# Standard email properties available for batch fetching
+EMAIL_PROPERTIES = {
+    "id": "id",
+    "subject": "subject",
+    "sender": "sender",
+    "date_received": "dateReceived",
+    "date_sent": "dateSent",
+    "read": "readStatus",
+    "flagged": "flaggedStatus",
+    "deleted": "deletedStatus",
+    "junk": "junkMailStatus",
+    "reply_to": "replyTo",
+    "message_id": "messageId",
+    "source": "source",  # Raw email source - expensive!
+}
+
+# Shorthand aliases for common property sets
+PROPERTY_SETS = {
+    "minimal": ["id", "subject", "sender", "date_received"],
+    "standard": [
+        "id",
+        "subject",
+        "sender",
+        "date_received",
+        "read",
+        "flagged",
+    ],
+    "full": [
+        "id",
+        "subject",
+        "sender",
+        "date_received",
+        "date_sent",
+        "read",
+        "flagged",
+        "reply_to",
+        "message_id",
+    ],
+}
+
+
+@dataclass
+class QueryBuilder:
+    """
+    Builder for constructing optimized email query scripts.
+
+    Uses batch property fetching for fast execution. Supports filtering,
+    limiting, and property selection.
+
+    Example:
+        query = (QueryBuilder()
+            .from_mailbox("Work", "INBOX")
+            .select("sender", "subject", "date_received", "read")
+            .where("data.dateReceived[i] >= MailCore.today()")
+            .limit(50)
+            .build())
+    """
+
+    _account: str | None = None
+    _mailbox: str = "INBOX"
+    _properties: list[str] = field(default_factory=list)
+    _filter_expr: str | None = None
+    _limit: int | None = None
+    _order_by: str | None = None
+    _descending: bool = True
+
+    def from_mailbox(
+        self, account: str | None = None, mailbox: str = "INBOX"
+    ) -> "QueryBuilder":
+        """
+        Set the source mailbox for the query.
+
+        Args:
+            account: Account name (None for first/default account)
+            mailbox: Mailbox name (default: "INBOX")
+        """
+        self._account = account
+        self._mailbox = mailbox
+        return self
+
+    def select(self, *props: str) -> "QueryBuilder":
+        """
+        Select properties to fetch.
+
+        Use property names like: id, subject, sender, date_received,
+        read, flagged, etc. Or use a preset: "minimal", "standard", "full".
+
+        Args:
+            props: Property names or preset names
+        """
+        for prop in props:
+            if prop in PROPERTY_SETS:
+                self._properties.extend(PROPERTY_SETS[prop])
+            elif prop in EMAIL_PROPERTIES:
+                self._properties.append(prop)
+            else:
+                raise ValueError(
+                    f"Unknown property: {prop}. "
+                    f"Valid: {list(EMAIL_PROPERTIES.keys())}"
+                )
+        return self
+
+    def where(self, js_expression: str) -> "QueryBuilder":
+        """
+        Add a filter expression (JavaScript).
+
+        The expression has access to:
+        - `data`: Object with arrays of fetched properties
+        - `i`: Current index in the loop
+        - `MailCore`: The MailCore utilities
+
+        Example:
+            .where("data.dateReceived[i] >= MailCore.today()")
+            .where("data.subject[i].toLowerCase().includes('urgent')")
+
+        Args:
+            js_expression: JavaScript boolean expression
+        """
+        self._filter_expr = js_expression
+        return self
+
+    def limit(self, n: int) -> "QueryBuilder":
+        """Limit the number of results."""
+        self._limit = n
+        return self
+
+    def order_by(self, prop: str, descending: bool = True) -> "QueryBuilder":
+        """
+        Order results by a property.
+
+        Args:
+            prop: Property name to sort by
+            descending: Sort descending (default: True, newest first)
+        """
+        if prop not in EMAIL_PROPERTIES:
+            raise ValueError(f"Unknown property for ordering: {prop}")
+        self._order_by = prop
+        self._descending = descending
+        return self
+
+    def build(self) -> str:
+        """
+        Generate the JXA script.
+
+        Returns:
+            JavaScript code that uses MailCore and returns JSON
+        """
+        if not self._properties:
+            # Default to standard properties
+            self._properties = PROPERTY_SETS["standard"].copy()
+
+        # Remove duplicates while preserving order
+        props = list(dict.fromkeys(self._properties))
+
+        # Map Python property names to JXA property names
+        jxa_props = [EMAIL_PROPERTIES[p] for p in props]
+
+        # Build the script
+        account_json = json.dumps(self._account)
+        mailbox_json = json.dumps(self._mailbox)
+        props_json = json.dumps(jxa_props)
+
+        lines = [
+            "// Setup",
+            f"const account = MailCore.getAccount({account_json});",
+            f"const mailbox = MailCore.getMailbox(account, {mailbox_json});",
+            "const msgs = mailbox.messages;",
+            "",
+            "// Batch fetch (optimized - single IPC per property)",
+            f"const data = MailCore.batchFetch(msgs, {props_json});",
+            "",
+            "// Build results",
+            "const results = [];",
+            f"const len = data.{jxa_props[0]}.length;",
+            "",
+        ]
+
+        # Loop with optional limit
+        if self._limit:
+            loop_cond = f"i < len && results.length < {self._limit}"
+            lines.append(f"for (let i = 0; {loop_cond}; i++) {{")
+        else:
+            lines.append("for (let i = 0; i < len; i++) {")
+
+        # Optional filter
+        if self._filter_expr:
+            lines.append(f"    if (!({self._filter_expr})) continue;")
+
+        # Build result object
+        lines.append("    results.push({")
+        for py_name, jxa_name in zip(props, jxa_props, strict=True):
+            if jxa_name in ("dateReceived", "dateSent"):
+                fmt = f"MailCore.formatDate(data.{jxa_name}[i])"
+                lines.append(f"        {py_name}: {fmt},")
+            else:
+                lines.append(f"        {py_name}: data.{jxa_name}[i],")
+        lines.append("    });")
+        lines.append("}")
+
+        # Optional sorting (in JS after collection)
+        if self._order_by:
+            direction = -1 if self._descending else 1
+            lines.append("")
+            lines.append("// Sort results")
+            lines.append("results.sort((a, b) => {")
+            lines.append(f"    const va = a.{self._order_by};")
+            lines.append(f"    const vb = b.{self._order_by};")
+            lines.append(f"    if (va < vb) return {-direction};")
+            lines.append(f"    if (va > vb) return {direction};")
+            lines.append("    return 0;")
+            lines.append("});")
+
+        lines.append("")
+        lines.append("JSON.stringify(results);")
+
+        return "\n".join(lines)
+
+
+@dataclass
+class AccountsQueryBuilder:
+    """Builder for listing accounts and mailboxes."""
+
+    def list_accounts(self) -> str:
+        """Generate script to list all mail accounts."""
+        return "JSON.stringify(MailCore.listAccounts());"
+
+    def list_mailboxes(self, account: str | None = None) -> str:
+        """Generate script to list mailboxes for an account."""
+        account_json = json.dumps(account)
+        return f"""
+const account = MailCore.getAccount({account_json});
+JSON.stringify(MailCore.listMailboxes(account));
+"""

jxa_mail_mcp/config.py

@@ -0,0 +1,29 @@
+"""Configuration for JXA Mail MCP server."""
+
+import os
+
+
+def get_default_account() -> str | None:
+    """
+    Get the default account from environment variable.
+
+    Set JXA_MAIL_DEFAULT_ACCOUNT to use a specific account by default.
+    If not set, the first account in Apple Mail will be used.
+
+    Returns:
+        Account name or None to use first account.
+    """
+    return os.environ.get("JXA_MAIL_DEFAULT_ACCOUNT")
+
+
+def get_default_mailbox() -> str:
+    """
+    Get the default mailbox from environment variable.
+
+    Set JXA_MAIL_DEFAULT_MAILBOX to use a specific mailbox by default.
+    Defaults to "INBOX".
+
+    Returns:
+        Mailbox name.
+    """
+    return os.environ.get("JXA_MAIL_DEFAULT_MAILBOX", "Inbox")

jxa_mail_mcp/executor.py

@@ -0,0 +1,84 @@
+"""JXA script execution utilities."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import TYPE_CHECKING, Any
+
+from .jxa import MAIL_CORE_JS
+
+if TYPE_CHECKING:
+    from .builders import QueryBuilder
+
+
+class JXAError(Exception):
+    """Raised when a JXA script fails to execute."""
+
+    def __init__(self, message: str, stderr: str = ""):
+        super().__init__(message)
+        self.stderr = stderr
+
+
+def run_jxa(script: str, timeout: int = 120) -> str:
+    """
+    Execute a raw JXA script and return the output.
+
+    Args:
+        script: JavaScript code to execute via osascript
+        timeout: Maximum execution time in seconds
+
+    Returns:
+        The script's stdout output (stripped)
+
+    Raises:
+        JXAError: If the script fails to execute
+        subprocess.TimeoutExpired: If execution exceeds timeout
+    """
+    result = subprocess.run(
+        ["osascript", "-l", "JavaScript", "-e", script],
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+    if result.returncode != 0:
+        raise JXAError(f"JXA script failed: {result.stderr}", result.stderr)
+    return result.stdout.strip()
+
+
+def execute_with_core(script_body: str, timeout: int = 120) -> Any:
+    """
+    Execute a JXA script with MailCore library injected.
+
+    The script should use MailCore utilities and end with a
+    JSON.stringify() call to return data.
+
+    Args:
+        script_body: JavaScript code that uses MailCore
+        timeout: Maximum execution time in seconds
+
+    Returns:
+        Parsed JSON result from the script
+
+    Raises:
+        JXAError: If execution fails
+        json.JSONDecodeError: If output isn't valid JSON
+    """
+    full_script = f"{MAIL_CORE_JS}\n\n{script_body}"
+    output = run_jxa(full_script, timeout)
+    return json.loads(output)
+
+
+def execute_query(query: QueryBuilder, timeout: int = 120) -> list[dict]:
+    """
+    Execute a QueryBuilder and return results.
+
+    Args:
+        query: A configured QueryBuilder instance
+        timeout: Maximum execution time in seconds
+
+    Returns:
+        List of email dictionaries matching the query
+    """
+    script = query.build()
+    return execute_with_core(script, timeout)

jxa_mail_mcp/jxa/__init__.py

@@ -0,0 +1,8 @@
+"""JXA script resources for Apple Mail automation."""
+
+from pathlib import Path
+
+# Path to the mail_core.js library
+MAIL_CORE_JS = (Path(__file__).parent / "mail_core.js").read_text()
+
+__all__ = ["MAIL_CORE_JS"]

jxa_mail_mcp/jxa/mail_core.js

@@ -0,0 +1,294 @@
+/**
+ * Apple Mail JXA Core Library
+ *
+ * Shared utilities for fast, batch-optimized Mail.app automation.
+ * This library is injected into all JXA scripts to provide consistent
+ * error handling, account/mailbox resolution, and batch fetching.
+ */
+
+const Mail = Application("Mail");
+
+const MailCore = {
+    /**
+     * Get an account by name, or the first account if name is null/empty.
+     * @param {string|null} name - Account name or null for default
+     * @returns {Account} Mail account object
+     */
+    getAccount(name) {
+        if (name) {
+            return Mail.accounts.byName(name);
+        }
+        const accounts = Mail.accounts();
+        if (accounts.length === 0) {
+            throw new Error("No mail accounts configured");
+        }
+        return accounts[0];
+    },
+
+    /**
+     * Get a mailbox from an account.
+     * @param {Account} account - Mail account object
+     * @param {string} name - Mailbox name (e.g., "INBOX", "Sent")
+     * @returns {Mailbox} Mailbox object
+     */
+    getMailbox(account, name) {
+        return account.mailboxes.byName(name);
+    },
+
+    /**
+     * Batch fetch multiple properties from a messages collection.
+     * This is THE critical optimization - one IPC call per property
+     * instead of one per message.
+     *
+     * @param {Messages} msgs - Messages collection from a mailbox
+     * @param {string[]} props - Property names to fetch
+     * @returns {Object} Map of property name to array of values
+     */
+    batchFetch(msgs, props) {
+        const result = {};
+        for (const prop of props) {
+            result[prop] = msgs[prop]();
+        }
+        return result;
+    },
+
+    /**
+     * Get message IDs for referencing specific messages later.
+     * @param {Messages} msgs - Messages collection
+     * @returns {string[]} Array of message IDs
+     */
+    getMessageIds(msgs) {
+        return msgs.id();
+    },
+
+    /**
+     * Get a specific message by ID.
+     * @param {string} messageId - The message ID
+     * @returns {Message} Message object
+     */
+    getMessageById(messageId) {
+        // Messages are referenced by ID across all accounts
+        return Mail.messages.byId(messageId);
+    },
+
+    /**
+     * Wrap an operation with error handling.
+     * @param {Function} fn - Function to execute
+     * @returns {Object} {ok: true, data: ...} or {ok: false, error: ...}
+     */
+    safely(fn) {
+        try {
+            return { ok: true, data: fn() };
+        } catch (e) {
+            return { ok: false, error: String(e) };
+        }
+    },
+
+    /**
+     * Get today's date at midnight for filtering.
+     * @returns {Date} Today at 00:00:00
+     */
+    today() {
+        const d = new Date();
+        d.setHours(0, 0, 0, 0);
+        return d;
+    },
+
+    /**
+     * Format a date for JSON output.
+     * @param {Date} date - Date to format
+     * @returns {string} ISO string or null if invalid
+     */
+    formatDate(date) {
+        if (!date || !(date instanceof Date)) return null;
+        return date.toISOString();
+    },
+
+    /**
+     * List all accounts.
+     * @returns {Object[]} Array of {name, id} objects
+     */
+    listAccounts() {
+        const accounts = Mail.accounts();
+        const names = Mail.accounts.name();
+        const ids = Mail.accounts.id();
+        const results = [];
+        for (let i = 0; i < accounts.length; i++) {
+            results.push({ name: names[i], id: ids[i] });
+        }
+        return results;
+    },
+
+    /**
+     * List mailboxes for an account.
+     * Note: messageCount is not available via batch fetch, only unreadCount.
+     * @param {Account} account - Mail account
+     * @returns {Object[]} Array of {name, unreadCount}
+     */
+    listMailboxes(account) {
+        const mboxes = account.mailboxes();
+        const names = account.mailboxes.name();
+        const unread = account.mailboxes.unreadCount();
+        const results = [];
+        for (let i = 0; i < mboxes.length; i++) {
+            results.push({
+                name: names[i],
+                unreadCount: unread[i],
+            });
+        }
+        return results;
+    },
+
+    // ========== Fuzzy Search Utilities ==========
+
+    /**
+     * Extract trigrams (3-character sequences) from a string.
+     * @param {string} str - Input string
+     * @returns {Set<string>} Set of trigrams
+     */
+    trigrams(str) {
+        const s = (str || "").toLowerCase().trim();
+        const result = new Set();
+        if (s.length < 3) {
+            result.add(s);
+            return result;
+        }
+        for (let i = 0; i <= s.length - 3; i++) {
+            result.add(s.substring(i, i + 3));
+        }
+        return result;
+    },
+
+    /**
+     * Calculate trigram similarity (Jaccard index).
+     * @param {Set<string>} set1 - First trigram set
+     * @param {Set<string>} set2 - Second trigram set
+     * @returns {number} Similarity score 0-1
+     */
+    trigramSimilarity(set1, set2) {
+        if (set1.size === 0 && set2.size === 0) return 1;
+        if (set1.size === 0 || set2.size === 0) return 0;
+        let intersection = 0;
+        for (const t of set1) {
+            if (set2.has(t)) intersection++;
+        }
+        const union = set1.size + set2.size - intersection;
+        return intersection / union;
+    },
+
+    /**
+     * Calculate Levenshtein edit distance between two strings.
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @returns {number} Edit distance
+     */
+    levenshtein(a, b) {
+        const s1 = (a || "").toLowerCase();
+        const s2 = (b || "").toLowerCase();
+        if (s1 === s2) return 0;
+        if (s1.length === 0) return s2.length;
+        if (s2.length === 0) return s1.length;
+
+        // Use two rows instead of full matrix for memory efficiency
+        let prev = [];
+        let curr = [];
+        for (let j = 0; j <= s2.length; j++) prev[j] = j;
+
+        for (let i = 1; i <= s1.length; i++) {
+            curr[0] = i;
+            for (let j = 1; j <= s2.length; j++) {
+                const cost = s1[i - 1] === s2[j - 1] ? 0 : 1;
+                curr[j] = Math.min(
+                    prev[j] + 1,      // deletion
+                    curr[j - 1] + 1,  // insertion
+                    prev[j - 1] + cost // substitution
+                );
+            }
+            [prev, curr] = [curr, prev];
+        }
+        return prev[s2.length];
+    },
+
+    /**
+     * Calculate normalized Levenshtein similarity (0-1).
+     * @param {string} a - First string
+     * @param {string} b - Second string
+     * @returns {number} Similarity score 0-1
+     */
+    levenshteinSimilarity(a, b) {
+        const maxLen = Math.max((a || "").length, (b || "").length);
+        if (maxLen === 0) return 1;
+        return 1 - this.levenshtein(a, b) / maxLen;
+    },
+
+    /**
+     * Fuzzy match a query against text.
+     * Uses trigrams for fast candidate filtering, Levenshtein for scoring.
+     * @param {string} query - Search query
+     * @param {string} text - Text to search in
+     * @param {number} trigramThreshold - Min trigram similarity (default 0.2)
+     * @returns {object|null} {score, matched} or null if no match
+     */
+    fuzzyMatch(query, text, trigramThreshold = 0.2) {
+        const q = (query || "").toLowerCase().trim();
+        const t = (text || "").toLowerCase();
+
+        if (!q || !t) return null;
+
+        // Exact substring match is best
+        if (t.includes(q)) {
+            return { score: 1.0, matched: q };
+        }
+
+        // Split text into words for word-level matching
+        const words = t.split(/\s+/);
+        const queryTrigrams = this.trigrams(q);
+
+        let bestScore = 0;
+        let bestMatch = null;
+
+        for (const word of words) {
+            // Quick trigram filter
+            const wordTrigrams = this.trigrams(word);
+            const trigramSim = this.trigramSimilarity(
+                queryTrigrams,
+                wordTrigrams
+            );
+
+            if (trigramSim >= trigramThreshold) {
+                // Candidate found, calculate precise score
+                const levSim = this.levenshteinSimilarity(q, word);
+                if (levSim > bestScore) {
+                    bestScore = levSim;
+                    bestMatch = word;
+                }
+            }
+        }
+
+        // Also check multi-word phrases (sliding window)
+        const queryWords = q.split(/\s+/).length;
+        if (queryWords > 1 && words.length >= queryWords) {
+            for (let i = 0; i <= words.length - queryWords; i++) {
+                const phrase = words.slice(i, i + queryWords).join(" ");
+                const phraseTrigrams = this.trigrams(phrase);
+                const trigramSim = this.trigramSimilarity(
+                    queryTrigrams,
+                    phraseTrigrams
+                );
+
+                if (trigramSim >= trigramThreshold) {
+                    const levSim = this.levenshteinSimilarity(q, phrase);
+                    if (levSim > bestScore) {
+                        bestScore = levSim;
+                        bestMatch = phrase;
+                    }
+                }
+            }
+        }
+
+        if (bestScore > 0) {
+            return { score: bestScore, matched: bestMatch };
+        }
+        return null;
+    },
+};