jxa-mail-mcp 0.1.0__tar.gz → 0.2.0__tar.gz

{jxa_mail_mcp-0.1.0 → jxa_mail_mcp-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jxa-mail-mcp
-Version: 0.1.0
+Version: 0.2.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
@@ -33,15 +33,27 @@ A fast MCP (Model Context Protocol) server for Apple Mail, using optimized JXA (
 - **list_accounts** - List all configured email accounts
 - **list_mailboxes** - List mailboxes for an account
 - **get_emails** - Fetch emails from any mailbox with pagination
+- **get_email** - Fetch a single email with full body content
 - **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
+- **search_email_bodies** - Fuzzy search within email body content
 
 ## Installation
 
-### With pipx (recommended)
+### No installation required
+
+Use `pipx run` to run directly from PyPI:
+
+```bash
+pipx run jxa-mail-mcp
+```
+
+### With pipx (optional)
+
+For faster startup, install globally:
 
 ```bash
 pipx install jxa-mail-mcp
@@ -61,26 +73,26 @@ uv sync
 
 ### Add to Claude Code
 
-After installing with pipx:
+Using `pipx run` (no installation required):
 
 ```json
 {
   "mcpServers": {
     "mail": {
-      "command": "jxa-mail-mcp"
+      "command": "pipx",
+      "args": ["run", "jxa-mail-mcp"]
     }
   }
 }
 ```
 
-Or from source:
+Or if installed with `pipx install jxa-mail-mcp`:
 
 ```json
 {
   "mcpServers": {
     "mail": {
-      "command": "uv",
-      "args": ["run", "--directory", "/path/to/jxa-mail-mcp", "jxa-mail-mcp"]
+      "command": "jxa-mail-mcp"
     }
   }
 }
@@ -89,6 +101,8 @@ Or from source:
 ### Run directly
 
 ```bash
+pipx run jxa-mail-mcp
+# or after installing
 jxa-mail-mcp
 ```
 
@@ -119,13 +133,26 @@ Or in Claude Code config:
 ### Test in Python
 
 ```python
-from jxa_mail_mcp.server import get_todays_emails, search_emails, fuzzy_search_emails
+from jxa_mail_mcp.server import (
+    get_todays_emails,
+    search_emails,
+    fuzzy_search_emails,
+    search_email_bodies,
+    get_email,
+)
 
 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"
+
+# Search within email bodies (slower but searches full content)
+results = search_email_bodies("project deadline", account="Work", limit=10)
+
+# Get full email content
+email = get_email(message_id=12345, account="Work", mailbox="INBOX")
+print(email["content"])  # Full body text
 ```
 
 ## Architecture
@@ -203,6 +230,20 @@ The trigram pre-filtering keeps fuzzy search fast by avoiding expensive Levensht
 
 **Example**: Searching for "reserch studies" (typo) correctly finds "research studies" with 0.94 similarity score.
 
+### Body Search Performance
+
+Body search (`search_email_bodies`) fetches full email content, which is slower than metadata-only search but enables searching within email text:
+
+| Search Type | Time (20 emails) | Notes |
+|-------------|------------------|-------|
+| Metadata search | ~0.1s | Subject/sender only |
+| Body search | ~7s | Full content fetch + fuzzy match |
+| Single email fetch | ~0.3s | `get_email()` with full body |
+
+Body search uses a tiered matching approach:
+1. **Exact substring** (score 0.95) - Fast, catches most searches
+2. **Trigram similarity** (score 0.25-0.72) - Tolerates typos without expensive Levenshtein on long text
+
 ## Development
 
 ```bash

{jxa_mail_mcp-0.1.0 → jxa_mail_mcp-0.2.0}/README.md

@@ -7,15 +7,27 @@ A fast MCP (Model Context Protocol) server for Apple Mail, using optimized JXA (
 - **list_accounts** - List all configured email accounts
 - **list_mailboxes** - List mailboxes for an account
 - **get_emails** - Fetch emails from any mailbox with pagination
+- **get_email** - Fetch a single email with full body content
 - **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
+- **search_email_bodies** - Fuzzy search within email body content
 
 ## Installation
 
-### With pipx (recommended)
+### No installation required
+
+Use `pipx run` to run directly from PyPI:
+
+```bash
+pipx run jxa-mail-mcp
+```
+
+### With pipx (optional)
+
+For faster startup, install globally:
 
 ```bash
 pipx install jxa-mail-mcp
@@ -35,26 +47,26 @@ uv sync
 
 ### Add to Claude Code
 
-After installing with pipx:
+Using `pipx run` (no installation required):
 
 ```json
 {
   "mcpServers": {
     "mail": {
-      "command": "jxa-mail-mcp"
+      "command": "pipx",
+      "args": ["run", "jxa-mail-mcp"]
     }
   }
 }
 ```
 
-Or from source:
+Or if installed with `pipx install jxa-mail-mcp`:
 
 ```json
 {
   "mcpServers": {
     "mail": {
-      "command": "uv",
-      "args": ["run", "--directory", "/path/to/jxa-mail-mcp", "jxa-mail-mcp"]
+      "command": "jxa-mail-mcp"
     }
   }
 }
@@ -63,6 +75,8 @@ Or from source:
 ### Run directly
 
 ```bash
+pipx run jxa-mail-mcp
+# or after installing
 jxa-mail-mcp
 ```
 
@@ -93,13 +107,26 @@ Or in Claude Code config:
 ### Test in Python
 
 ```python
-from jxa_mail_mcp.server import get_todays_emails, search_emails, fuzzy_search_emails
+from jxa_mail_mcp.server import (
+    get_todays_emails,
+    search_emails,
+    fuzzy_search_emails,
+    search_email_bodies,
+    get_email,
+)
 
 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"
+
+# Search within email bodies (slower but searches full content)
+results = search_email_bodies("project deadline", account="Work", limit=10)
+
+# Get full email content
+email = get_email(message_id=12345, account="Work", mailbox="INBOX")
+print(email["content"])  # Full body text
 ```
 
 ## Architecture
@@ -177,6 +204,20 @@ The trigram pre-filtering keeps fuzzy search fast by avoiding expensive Levensht
 
 **Example**: Searching for "reserch studies" (typo) correctly finds "research studies" with 0.94 similarity score.
 
+### Body Search Performance
+
+Body search (`search_email_bodies`) fetches full email content, which is slower than metadata-only search but enables searching within email text:
+
+| Search Type | Time (20 emails) | Notes |
+|-------------|------------------|-------|
+| Metadata search | ~0.1s | Subject/sender only |
+| Body search | ~7s | Full content fetch + fuzzy match |
+| Single email fetch | ~0.3s | `get_email()` with full body |
+
+Body search uses a tiered matching approach:
+1. **Exact substring** (score 0.95) - Fast, catches most searches
+2. **Trigram similarity** (score 0.25-0.72) - Tolerates typos without expensive Levenshtein on long text
+
 ## Development
 
 ```bash

{jxa_mail_mcp-0.1.0 → jxa_mail_mcp-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "jxa-mail-mcp"
-version = "0.1.0"
+version = "0.2.0"
 description = "Fast MCP server for Apple Mail via optimized JXA scripts"
 readme = "README.md"
 license = "GPL-3.0-or-later"

{jxa_mail_mcp-0.1.0 → jxa_mail_mcp-0.2.0}/src/jxa_mail_mcp/jxa/mail_core.js

@@ -291,4 +291,72 @@ const MailCore = {
         }
         return null;
     },
+
+    /**
+     * Fast body search - optimized for long text.
+     * Uses substring match first, then trigram-only (skips expensive Levenshtein).
+     *
+     * @param {string} query - Search query
+     * @param {string} body - Email body content
+     * @param {number} maxChars - Max characters to search (default 2000)
+     * @returns {object|null} {score, matched, tier} or null if no match
+     */
+    fuzzyMatchBody(query, body, maxChars = 2000) {
+        const q = (query || "").toLowerCase().trim();
+        const b = (body || "").toLowerCase().substring(0, maxChars);
+
+        if (!q || !b) return null;
+
+        // Tier 1: Exact substring match (fastest, best result)
+        const exactIndex = b.indexOf(q);
+        if (exactIndex !== -1) {
+            // Extract context around the match
+            const start = Math.max(0, exactIndex - 20);
+            const end = Math.min(b.length, exactIndex + q.length + 20);
+            const context = b.substring(start, end).trim();
+            return { score: 0.95, matched: context, tier: "exact" };
+        }
+
+        // Tier 2: Word-level trigram matching (no Levenshtein)
+        // Find words that share enough trigrams with query
+        const queryTrigrams = this.trigrams(q);
+        const words = b.split(/\s+/);
+        let bestSim = 0;
+        let bestWord = null;
+
+        for (const word of words) {
+            if (word.length < 2) continue;
+            const wordTrigrams = this.trigrams(word);
+            const sim = this.trigramSimilarity(queryTrigrams, wordTrigrams);
+            if (sim > bestSim) {
+                bestSim = sim;
+                bestWord = word;
+            }
+        }
+
+        // Also check multi-word phrases for multi-word queries
+        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 sim = this.trigramSimilarity(queryTrigrams, phraseTrigrams);
+                if (sim > bestSim) {
+                    bestSim = sim;
+                    bestWord = phrase;
+                }
+            }
+        }
+
+        // Require higher threshold for trigram-only matching
+        if (bestSim >= 0.25) {
+            return {
+                score: Math.round(bestSim * 0.85 * 100) / 100,
+                matched: bestWord,
+                tier: "trigram",
+            };
+        }
+
+        return null;
+    },
 };

{jxa_mail_mcp-0.1.0 → jxa_mail_mcp-0.2.0}/src/jxa_mail_mcp/server.py

@@ -349,5 +349,217 @@ JSON.stringify(results.slice(0, {limit}));
     return execute_with_core(script)
 
 
+@mcp.tool
+def search_email_bodies(
+    query: str,
+    account: str | None = None,
+    mailbox: str | None = None,
+    limit: int = 20,
+    threshold: float = 0.3,
+) -> list[dict]:
+    """
+    Search within email body content using fuzzy matching.
+
+    Searches the full text content of emails, not just metadata.
+    Uses a fast two-tier approach: exact substring matching first,
+    then trigram similarity for typo tolerance.
+
+    Note: Slower than metadata-only search due to fetching email bodies.
+    Use search_emails() or fuzzy_search_emails() for faster metadata search.
+
+    Args:
+        query: Search term to find in email bodies
+        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 scores, sorted by relevance.
+        Includes 'matched_in' field indicating where match was found
+        (subject, sender, or body) and 'matched_text' showing the match.
+
+    Example:
+        >>> search_email_bodies("project deadline")
+        [{"subject": "Re: Updates", "score": 0.95, "matched_in": "body",
+          "matched_text": "...project deadline is...", ...}]
+    """
+    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 INCLUDING content
+const data = MailCore.batchFetch(msgs, [
+    'id', 'subject', 'sender', 'content',
+    '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] || '';
+    const content = data.content[i] || '';
+
+    // Try matching against subject, sender, and body
+    const subjectMatch = MailCore.fuzzyMatch(query, subject);
+    const senderMatch = MailCore.fuzzyMatch(query, sender);
+    const bodyMatch = MailCore.fuzzyMatchBody(query, content);
+
+    // Take the best match across all fields
+    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 (bodyMatch && bodyMatch.score > bestScore) {{
+        bestScore = bodyMatch.score;
+        matchedIn = 'body';
+        matchedText = bodyMatch.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)
+
+
+@mcp.tool
+def get_email(
+    message_id: int,
+    account: str | None = None,
+    mailbox: str | None = None,
+) -> dict:
+    """
+    Get a single email with full content.
+
+    Retrieves complete email details including the full body text.
+    Use this after finding an email via search to read its content.
+
+    Args:
+        message_id: The email's unique ID (from search results)
+        account: Account name (optional, helps find message faster)
+        mailbox: Mailbox name (optional, helps find message faster)
+
+    Returns:
+        Email dictionary with full content including:
+        - id, subject, sender, date_received, date_sent
+        - content: Full plain text body
+        - read, flagged status
+        - reply_to, message_id (email Message-ID header)
+
+    Example:
+        >>> get_email(12345)
+        {"id": 12345, "subject": "Meeting notes",
+         "content": "Hi team,\\n\\nHere are the notes...", ...}
+    """
+    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 targetId = {message_id};
+
+// Try to find the message in the specified mailbox first
+let msg = null;
+const account = {account_js};
+const mailbox = MailCore.getMailbox(account, '{safe_mailbox}');
+
+// Search in specified mailbox
+const ids = mailbox.messages.id();
+const idx = ids.indexOf(targetId);
+if (idx !== -1) {{
+    msg = mailbox.messages[idx];
+}}
+
+// If not found, search all mailboxes in the account
+if (!msg) {{
+    const allMailboxes = account.mailboxes();
+    for (let i = 0; i < allMailboxes.length && !msg; i++) {{
+        const mb = allMailboxes[i];
+        const mbIds = mb.messages.id();
+        const mbIdx = mbIds.indexOf(targetId);
+        if (mbIdx !== -1) {{
+            msg = mb.messages[mbIdx];
+        }}
+    }}
+}}
+
+if (!msg) {{
+    throw new Error('Message not found with ID: ' + targetId);
+}}
+
+JSON.stringify({{
+    id: msg.id(),
+    subject: msg.subject(),
+    sender: msg.sender(),
+    content: msg.content(),
+    date_received: MailCore.formatDate(msg.dateReceived()),
+    date_sent: MailCore.formatDate(msg.dateSent()),
+    read: msg.readStatus(),
+    flagged: msg.flaggedStatus(),
+    reply_to: msg.replyTo(),
+    message_id: msg.messageId()
+}});
+"""
+    return execute_with_core(script)
+
+
 if __name__ == "__main__":
     mcp.run()