jxa-mail-mcp 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

jxa_mail_mcp/__init__.py

@@ -1,10 +1,18 @@
-"""JXA Mail MCP - Fast Apple Mail automation via optimized JXA scripts."""
+"""JXA Mail MCP - Fast Apple Mail automation via optimized JXA scripts.
 
-from .server import mcp
+Features:
+- 87x faster email fetching via batch property fetching
+- FTS5 full-text search index for ~100x faster body search
+- Fuzzy search with trigram + Levenshtein matching
 
-__all__ = ["main", "mcp"]
+Usage:
+    jxa-mail-mcp            # Run MCP server (default)
+    jxa-mail-mcp index      # Build search index from disk
+    jxa-mail-mcp status     # Show index statistics
+    jxa-mail-mcp rebuild    # Force rebuild index
+"""
 
+from .cli import main
+from .server import mcp
 
-def main() -> None:
-    """Entry point for the MCP server."""
-    mcp.run()
+__all__ = ["main", "mcp"]

jxa_mail_mcp/cli.py

@@ -0,0 +1,358 @@
+"""Command-line interface for jxa-mail-mcp.
+
+Provides commands for:
+- index: Build search index from disk (requires Full Disk Access)
+- status: Show index statistics
+- rebuild: Force rebuild the index
+- serve: Run the MCP server (default)
+
+Usage:
+    jxa-mail-mcp            # Run MCP server (default)
+    jxa-mail-mcp serve      # Run MCP server explicitly
+    jxa-mail-mcp --watch    # Run with real-time index updates
+    jxa-mail-mcp index      # Build index from disk
+    jxa-mail-mcp status     # Show index status
+    jxa-mail-mcp rebuild    # Force rebuild index
+"""
+
+import sys
+import time
+from typing import Annotated
+
+import cyclopts
+
+from .config import get_index_path
+
+app = cyclopts.App(
+    name="jxa-mail-mcp",
+    help="Fast MCP server for Apple Mail with FTS5 search index.",
+)
+
+
+def _format_size(size_mb: float) -> str:
+    """Format file size for display."""
+    if size_mb < 1:
+        return f"{size_mb * 1024:.1f} KB"
+    return f"{size_mb:.1f} MB"
+
+
+def _format_time(seconds: float) -> str:
+    """Format duration for display."""
+    if seconds < 60:
+        return f"{seconds:.1f}s"
+    minutes = int(seconds // 60)
+    secs = seconds % 60
+    return f"{minutes}m {secs:.1f}s"
+
+
+def _progress_bar(current: int, total: int | None, width: int = 40) -> str:
+    """Create a progress bar string."""
+    if total is None or total == 0:
+        # Indeterminate progress
+        return f"[{'=' * (current % width)}>]"
+
+    pct = min(current / total, 1.0)
+    filled = int(width * pct)
+    bar = "=" * filled + "-" * (width - filled)
+    return f"[{bar}] {pct * 100:.0f}%"
+
+
+def _run_serve(watch: bool = False) -> None:
+    """Internal function to run the MCP server."""
+    # Perform startup sync if index exists
+    from .index import IndexManager
+    from .server import mcp
+
+    manager = IndexManager.get_instance()
+
+    if manager.has_index():
+        try:
+            print("Syncing index...", file=sys.stderr, flush=True)
+            start = time.time()
+            count = manager.sync_updates()
+            elapsed = time.time() - start
+            if count > 0:
+                print(
+                    f"Synced {count} new emails in {_format_time(elapsed)}",
+                    file=sys.stderr,
+                )
+        except Exception as e:
+            print(f"Warning: Index sync failed: {e}", file=sys.stderr)
+
+        # Start file watcher if requested
+        if watch:
+            try:
+
+                def on_update(added: int, removed: int) -> None:
+                    if added or removed:
+                        print(
+                            f"Index updated: +{added} -{removed}",
+                            file=sys.stderr,
+                        )
+
+                if manager.start_watcher(on_update=on_update):
+                    print("File watcher started", file=sys.stderr)
+                else:
+                    print(
+                        "Warning: Could not start file watcher",
+                        file=sys.stderr,
+                    )
+            except Exception as e:
+                print(f"Warning: File watcher failed: {e}", file=sys.stderr)
+
+    mcp.run()
+
+
+@app.command
+def serve(
+    watch: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--watch", "-w"],
+            help="Watch for new emails and update index in real-time",
+        ),
+    ] = False,
+    verbose: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--verbose", "-v"],
+            help="Enable verbose output",
+        ),
+    ] = False,
+) -> None:
+    """
+    Run the MCP server.
+
+    This is the default command when no subcommand is specified.
+    The server provides email search and access tools to MCP clients.
+
+    Use --watch to enable real-time index updates when emails arrive.
+    Requires Full Disk Access for the terminal.
+    """
+    _run_serve(watch=watch)
+
+
+@app.command
+def index(
+    verbose: Annotated[
+        bool,
+        cyclopts.Parameter(name=["--verbose", "-v"], help="Show progress"),
+    ] = False,
+) -> None:
+    """
+    Build the search index from disk.
+
+    Reads .emlx files directly from ~/Library/Mail/V10/ for fast indexing.
+    This is much faster than fetching via JXA (~30x faster).
+
+    IMPORTANT: Requires Full Disk Access permission for Terminal.
+    Grant access in System Settings → Privacy & Security → Full Disk Access.
+    """
+    from .index import IndexManager
+
+    print("Building search index from disk...")
+    print(f"Index location: {get_index_path()}")
+    print()
+
+    manager = IndexManager()
+    start = time.time()
+    last_report = start
+
+    def progress(current: int, total: int | None, message: str) -> None:
+        nonlocal last_report
+        now = time.time()
+
+        # Throttle updates to avoid spam
+        if now - last_report < 0.5 and total is None:
+            return
+        last_report = now
+
+        if verbose:
+            if total:
+                bar = _progress_bar(current, total)
+                print(f"\r{bar} {message}", end="", flush=True)
+            else:
+                print(f"\r{message}", end="", flush=True)
+
+    try:
+        callback = progress if verbose else None
+        count = manager.build_from_disk(progress_callback=callback)
+        elapsed = time.time() - start
+
+        if verbose:
+            print()  # Newline after progress
+
+        print()
+        print(f"✓ Indexed {count:,} emails in {_format_time(elapsed)}")
+
+        stats = manager.get_stats()
+        print(f"  Mailboxes: {stats.mailbox_count}")
+        print(f"  Database size: {_format_size(stats.db_size_mb)}")
+
+    except PermissionError as e:
+        print(f"\n✗ Permission denied: {e}", file=sys.stderr)
+        print("\nTo fix this:", file=sys.stderr)
+        print("  1. Open System Settings", file=sys.stderr)
+        print("  2. Privacy & Security → Full Disk Access", file=sys.stderr)
+        print("  3. Add and enable Terminal.app", file=sys.stderr)
+        print("  4. Restart terminal and try again", file=sys.stderr)
+        sys.exit(1)
+
+    except FileNotFoundError as e:
+        print(f"\n✗ Not found: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    except Exception as e:
+        print(f"\n✗ Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+@app.command
+def status(
+    verbose: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--verbose", "-v"],
+            help="Enable verbose output",
+        ),
+    ] = False,
+) -> None:
+    """
+    Show index statistics.
+
+    Displays:
+    - Email count and mailbox count
+    - Last sync time and staleness
+    - Database file size
+    """
+    from .index import IndexManager
+
+    manager = IndexManager()
+
+    if not manager.has_index():
+        print("No index found.")
+        print(f"Expected location: {get_index_path()}")
+        print()
+        print("Run 'jxa-mail-mcp index' to build the index.")
+        sys.exit(1)
+
+    stats = manager.get_stats()
+
+    print("JXA Mail MCP Index Status")
+    print("=" * 40)
+    print(f"Location:     {get_index_path()}")
+    print(f"Emails:       {stats.email_count:,}")
+    print(f"Mailboxes:    {stats.mailbox_count}")
+    print(f"Database:     {_format_size(stats.db_size_mb)}")
+    print()
+
+    if stats.last_sync:
+        print(f"Last sync:    {stats.last_sync.strftime('%Y-%m-%d %H:%M:%S')}")
+        if stats.staleness_hours is not None:
+            if stats.staleness_hours < 1:
+                staleness = f"{stats.staleness_hours * 60:.0f} minutes ago"
+            elif stats.staleness_hours < 24:
+                staleness = f"{stats.staleness_hours:.1f} hours ago"
+            else:
+                staleness = f"{stats.staleness_hours / 24:.1f} days ago"
+            print(f"Staleness:    {staleness}")
+
+            if manager.is_stale():
+                print()
+                print("⚠ Index is stale. Run 'jxa-mail-mcp index' to refresh.")
+    else:
+        print("Last sync:    Never")
+        print()
+        print("⚠ No sync recorded. Run 'jxa-mail-mcp index' to build.")
+
+
+@app.command
+def rebuild(
+    account: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--account", "-a"],
+            help="Rebuild only this account (all if not specified)",
+        ),
+    ] = None,
+    mailbox: Annotated[
+        str | None,
+        cyclopts.Parameter(
+            name=["--mailbox", "-m"],
+            help="Rebuild only this mailbox (requires --account)",
+        ),
+    ] = None,
+    verbose: Annotated[
+        bool,
+        cyclopts.Parameter(name=["--verbose", "-v"], help="Show progress"),
+    ] = False,
+) -> None:
+    """
+    Force rebuild the search index.
+
+    Clears existing data and rebuilds from disk.
+    Optionally scope to a specific account or mailbox.
+    """
+    if mailbox and not account:
+        print("Error: --mailbox requires --account", file=sys.stderr)
+        sys.exit(1)
+
+    from .index import IndexManager
+
+    scope = "entire index"
+    if account and mailbox:
+        scope = f"{account}/{mailbox}"
+    elif account:
+        scope = f"account {account}"
+
+    print(f"Rebuilding {scope}...")
+
+    manager = IndexManager()
+    start = time.time()
+
+    def progress(current: int, total: int | None, message: str) -> None:
+        if verbose:
+            print(f"\r{message}", end="", flush=True)
+
+    try:
+        count = manager.rebuild(
+            account=account,
+            mailbox=mailbox,
+            progress_callback=progress if verbose else None,
+        )
+        elapsed = time.time() - start
+
+        if verbose:
+            print()
+
+        print(f"✓ Rebuilt {count:,} emails in {_format_time(elapsed)}")
+
+    except Exception as e:
+        print(f"\n✗ Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+@app.default
+def default_handler(
+    watch: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--watch", "-w"],
+            help="Watch for new emails and update index in real-time",
+        ),
+    ] = False,
+    verbose: Annotated[
+        bool,
+        cyclopts.Parameter(
+            name=["--verbose", "-v"],
+            help="Enable verbose output",
+        ),
+    ] = False,
+) -> None:
+    """Run the MCP server (default when no command specified)."""
+    _run_serve(watch=watch)
+
+
+def main() -> None:
+    """Entry point for the CLI."""
+    app()

jxa_mail_mcp/config.py

@@ -1,6 +1,10 @@
 """Configuration for JXA Mail MCP server."""
 
 import os
+from pathlib import Path
+
+# Default index location
+DEFAULT_INDEX_PATH = Path.home() / ".jxa-mail-mcp" / "index.db"
 
 
 def get_default_account() -> str | None:
@@ -27,3 +31,51 @@ def get_default_mailbox() -> str:
         Mailbox name.
     """
     return os.environ.get("JXA_MAIL_DEFAULT_MAILBOX", "Inbox")
+
+
+# ========== Index Configuration ==========
+
+
+def get_index_path() -> Path:
+    """
+    Get the FTS5 index database path.
+
+    Set JXA_MAIL_INDEX_PATH to customize the location.
+    Defaults to ~/.jxa-mail-mcp/index.db
+
+    Returns:
+        Path to the index database file.
+    """
+    env_path = os.environ.get("JXA_MAIL_INDEX_PATH")
+    if env_path:
+        return Path(env_path).expanduser()
+    return DEFAULT_INDEX_PATH
+
+
+def get_index_max_emails() -> int:
+    """
+    Get the maximum number of emails to index per mailbox.
+
+    Set JXA_MAIL_INDEX_MAX_EMAILS to customize.
+    Defaults to 5000 emails per mailbox.
+
+    Returns:
+        Maximum emails per mailbox.
+    """
+    return int(os.environ.get("JXA_MAIL_INDEX_MAX_EMAILS", "5000"))
+
+
+def get_index_staleness_hours() -> float:
+    """
+    Get the staleness threshold for the index.
+
+    After this many hours without a sync, the index is considered stale
+    and should be refreshed.
+
+    Set JXA_MAIL_INDEX_STALENESS_HOURS to customize.
+    Defaults to 24 hours.
+
+    Returns:
+        Staleness threshold in hours.
+    """
+    return float(os.environ.get("JXA_MAIL_INDEX_STALENESS_HOURS", "24"))

jxa_mail_mcp/executor.py

@@ -1,7 +1,19 @@
-"""JXA script execution utilities."""
+"""JXA script execution utilities.
+
+Provides:
+- run_jxa() / run_jxa_async(): Execute raw JXA scripts
+- execute_with_core() / execute_with_core_async(): Execute with MailCore
+- execute_query() / execute_query_async(): Execute a QueryBuilder
+- build_account_js(): Build JXA code to get an account reference
+- build_mailbox_setup_js(): Build JXA code to set up account + mailbox
+
+The async versions use asyncio.create_subprocess_exec to avoid blocking
+the event loop, which is important for MCP server responsiveness.
+"""
 
 from __future__ import annotations
 
+import asyncio
 import json
 import subprocess
 from typing import TYPE_CHECKING, Any
@@ -20,6 +32,65 @@ class JXAError(Exception):
         self.stderr = stderr
 
 
+# ========== JXA Code Building Helpers ==========
+
+
+def build_account_js(account: str | None) -> str:
+    """
+    Build JXA expression to get an account reference.
+
+    Uses json.dumps() for safe string serialization to prevent injection.
+
+    Args:
+        account: Account name, or None for first/default account
+
+    Returns:
+        JXA expression string like: MailCore.getAccount("Work")
+
+    Example:
+        >>> build_account_js("Work")
+        'MailCore.getAccount("Work")'
+        >>> build_account_js(None)
+        'MailCore.getAccount(null)'
+    """
+    account_json = json.dumps(account)
+    return f"MailCore.getAccount({account_json})"
+
+
+def build_mailbox_setup_js(
+    account: str | None,
+    mailbox: str,
+    account_var: str = "account",
+    mailbox_var: str = "mailbox",
+) -> str:
+    """
+    Build JXA code to set up account and mailbox variables.
+
+    Uses json.dumps() for safe string serialization to prevent injection.
+
+    Args:
+        account: Account name, or None for first/default account
+        mailbox: Mailbox name
+        account_var: Variable name for account (default: "account")
+        mailbox_var: Variable name for mailbox (default: "mailbox")
+
+    Returns:
+        JXA code declaring account and mailbox variables
+
+    Example:
+        >>> build_mailbox_setup_js("Work", "INBOX")
+        'const account = MailCore.getAccount("Work");
+        const mailbox = MailCore.getMailbox(account, "INBOX");'
+    """
+    account_json = json.dumps(account)
+    mailbox_json = json.dumps(mailbox)
+    return f"""const {account_var} = MailCore.getAccount({account_json});
+const {mailbox_var} = MailCore.getMailbox({account_var}, {mailbox_json});"""
+
+
+# ========== Script Execution ==========
+
+
 def run_jxa(script: str, timeout: int = 120) -> str:
     """
     Execute a raw JXA script and return the output.
@@ -61,12 +132,20 @@ def execute_with_core(script_body: str, timeout: int = 120) -> Any:
         Parsed JSON result from the script
 
     Raises:
-        JXAError: If execution fails
-        json.JSONDecodeError: If output isn't valid JSON
+        JXAError: If execution fails or 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)
+
+    try:
+        return json.loads(output)
+    except json.JSONDecodeError as e:
+        # Truncate long output for the error message
+        preview = output[:500] + "..." if len(output) > 500 else output
+        raise JXAError(
+            f"Failed to parse JXA output as JSON: {e}\nOutput: {preview}",
+            stderr=output,
+        ) from e
 
 
 def execute_query(query: QueryBuilder, timeout: int = 120) -> list[dict]:
@@ -82,3 +161,98 @@ def execute_query(query: QueryBuilder, timeout: int = 120) -> list[dict]:
     """
     script = query.build()
     return execute_with_core(script, timeout)
+
+
+# ========== Async Script Execution ==========
+
+
+async def run_jxa_async(script: str, timeout: int = 120) -> str:
+    """
+    Execute a raw JXA script asynchronously.
+
+    Uses asyncio.create_subprocess_exec to avoid blocking the event loop.
+    This is preferred for MCP server tools to maintain responsiveness.
+
+    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
+        asyncio.TimeoutError: If execution exceeds timeout
+    """
+    process = await asyncio.create_subprocess_exec(
+        "osascript",
+        "-l",
+        "JavaScript",
+        "-e",
+        script,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+
+    try:
+        stdout, stderr = await asyncio.wait_for(
+            process.communicate(), timeout=timeout
+        )
+    except TimeoutError:
+        process.kill()
+        await process.wait()
+        raise
+
+    if process.returncode != 0:
+        stderr_text = stderr.decode("utf-8", errors="replace")
+        raise JXAError(f"JXA script failed: {stderr_text}", stderr_text)
+
+    return stdout.decode("utf-8", errors="replace").strip()
+
+
+async def execute_with_core_async(script_body: str, timeout: int = 120) -> Any:
+    """
+    Execute a JXA script with MailCore library injected (async version).
+
+    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 or output isn't valid JSON
+    """
+    full_script = f"{MAIL_CORE_JS}\n\n{script_body}"
+    output = await run_jxa_async(full_script, timeout)
+
+    try:
+        return json.loads(output)
+    except json.JSONDecodeError as e:
+        # Truncate long output for the error message
+        preview = output[:500] + "..." if len(output) > 500 else output
+        raise JXAError(
+            f"Failed to parse JXA output as JSON: {e}\nOutput: {preview}",
+            stderr=output,
+        ) from e
+
+
+async def execute_query_async(
+    query: QueryBuilder, timeout: int = 120
+) -> list[dict]:
+    """
+    Execute a QueryBuilder asynchronously 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 await execute_with_core_async(script, timeout)

jxa_mail_mcp/index/__init__.py

@@ -0,0 +1,14 @@
+"""FTS5 search index for fast email body search.
+
+This module provides:
+- IndexManager: Main interface for building, syncing, and searching the index
+- IndexWatcher: Real-time file watcher for automatic index updates
+- Pre-indexing from disk via CLI (requires Full Disk Access)
+- Incremental sync via JXA for new emails
+- FTS5 full-text search with BM25 ranking
+"""
+
+from .manager import IndexManager, IndexStats, SearchResult
+from .watcher import IndexWatcher
+
+__all__ = ["IndexManager", "IndexStats", "IndexWatcher", "SearchResult"]