v0.1.8: Bug fixes, benchmark refresh, reframed messaging

## Bug Fixes
- Fix watcher crash on file add (broad exception catch in parse loop)
- Fix attachment cache leak (_cleanup_old_attachments now called)
- Fix attachment cache permissions (0o700 for sensitive content)
- Fix empty search error messages (actionable errors + rebuild hint)
- Fix misleading get_email timeout (context-aware error message)

## Benchmark Updates
- Add rusty_apple_mail_mcp (Rust) as new competitor
- Update patrickfreyer tool mapping (search_emails API change)
- Fix message ID discovery for nested responses + string IDs
- Add capability matrix overview chart (benchmark_overview.png)
- Re-run all benchmarks with 7 competitors

## Messaging & Docs
- Rename this_week filter to last_7_days (this_week kept as alias)
- Reframe all descriptions: lead with reliability + body search,
  not speed multipliers (87x/700-3500x removed from marketing surfaces)
- Restructure benchmarks page: capability matrix first, details second
- Update PyPI keywords: add search, claude, llm; drop fts5, automation
- Update docs homepage, README, pyproject, server.json, mkdocs.yml

## Tests
- 297 tests pass (4 new watcher tests, 2 new filter tests)
- 25/25 integration tests pass

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: imdinu

CHANGELOG.md

@@ -5,7 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.7] - Unreleased
+## [0.1.8] - Unreleased
+
+### Fixed
+
+- **Watcher crash on file add** — `parse_emlx()` exceptions beyond `OSError`/`ValueError`/`UnicodeDecodeError` (e.g. malformed plist, missing headers) no longer kill the watcher thread. The watcher now skips unparseable files and continues processing.
+- **Attachment cache leak** — `_cleanup_old_attachments()` is now called automatically when extracting attachments, preventing unbounded disk usage from cached files.
+- **Attachment cache permissions** — cache directory is now created with `0o700` permissions to protect sensitive email attachment content.
+- **Empty search error messages** — search index errors (corrupt DB, SQLite issues) now return actionable error messages instead of empty strings. Suggests `apple-mail-mcp rebuild` when the index is broken.
+- **Misleading get_email timeout message** — when `get_email` times out, the error now checks whether account/mailbox were already provided and gives context-appropriate advice instead of always saying "Provide account/mailbox".
+
+### Changed
+
+- **Renamed `this_week` filter to `last_7_days`** — the filter returns a rolling 7-day window, not the current calendar week. `this_week` is still accepted as an alias for backwards compatibility. (#49)
+- **Updated patrickfreyer benchmark config** — `search_email_content` tool renamed to `search_emails` with new parameter names to match their latest API.
+- **Added `rusty_apple_mail_mcp` to benchmarks** — Rust-based competitor that reads Apple's Envelope Index directly (no JXA). First non-AppleScript competitor in the benchmark suite.
+
+## [0.1.7] - 2026-03-11
 
 ### Added
 
@@ -100,7 +116,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Disk-based sync for index building
 - Real-time file watcher for index updates
 
-[0.1.7]: https://github.com/imdinu/apple-mail-mcp/compare/v0.1.6...HEAD
+[0.1.8]: https://github.com/imdinu/apple-mail-mcp/compare/v0.1.7...HEAD
+[0.1.7]: https://github.com/imdinu/apple-mail-mcp/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/imdinu/apple-mail-mcp/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/imdinu/apple-mail-mcp/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/imdinu/apple-mail-mcp/compare/v0.1.3...v0.1.4

CLAUDE.md

@@ -2,7 +2,7 @@
 
 ## Project Overview
 
-Fast MCP server for Apple Mail with disk-first email reads (~1-5ms via .emlx parsing), batch JXA property fetching for 87x faster multi-email performance, and an FTS5 search index for **700-3500x faster** body search (~2ms vs ~7s).
+The only Apple Mail MCP server with full-text email search. Reliable on large mailboxes (30K+) where other servers timeout. Disk-first email reads (~5ms via .emlx parsing), batch JXA property fetching, and an FTS5 search index for full-text body search (~20ms).
 
 ## Project Structure
 
@@ -33,7 +33,7 @@ src/apple_mail_mcp/
 |------|---------|----------------|
 | `list_accounts()` | List email accounts | - |
 | `list_mailboxes(account?)` | List mailboxes | account (optional) |
-| `get_emails(...)` | Unified listing | filter: all/unread/flagged/today/this_week |
+| `get_emails(...)` | Unified listing | filter: all/unread/flagged/today/last_7_days |
 | `get_email(id)` | Full email content + attachments | message_id |
 | `search(query, ...)` | Unified search | scope: all/subject/sender/body/attachments |
 | `get_attachment(id, filename)` | Extract attachment content | message_id, filename |
@@ -45,7 +45,7 @@ get_emails()                      # All emails (default)
 get_emails(filter="unread")       # Unread only
 get_emails(filter="flagged")      # Flagged only
 get_emails(filter="today")        # Received today
-get_emails(filter="this_week")    # Last 7 days
+get_emails(filter="last_7_days")  # Last 7 days
 ```
 
 ### search() Scopes
@@ -280,7 +280,7 @@ With the consolidated API, extend `get_emails()` filters or `search()` scopes:
 @mcp.tool
 async def get_emails(
     ...
-    filter: Literal["all", "unread", "flagged", "today", "this_week", "starred"] = "all",
+    filter: Literal["all", "unread", "flagged", "today", "last_7_days", "starred"] = "all",
     ...
 ):
     ...
@@ -311,7 +311,7 @@ JSON.stringify({{success: true, id: {message_id}}});
 MailCore.today()  // Date
 
 // Get N days ago at midnight
-MailCore.daysAgo(7)  // Date (for "this_week" filter)
+MailCore.daysAgo(7)  // Date (for "last_7_days" filter)
 
 // Format for JSON
 MailCore.formatDate(date)  // ISO string or null

README.md

@@ -9,7 +9,7 @@
 [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
 [![CI](https://github.com/imdinu/apple-mail-mcp/actions/workflows/lint.yml/badge.svg)](https://github.com/imdinu/apple-mail-mcp/actions/workflows/lint.yml)
 
-A fast MCP server for Apple Mail — disk-first email reading, **87x faster** batch fetching via JXA, and an FTS5 search index for **700–3500x faster** body search (~2ms vs ~7s).
+The only Apple Mail MCP server with **full-text email search**. Reliable on large mailboxes where other servers timeout — with 6 tools for reading, searching, and extracting email content.
 
 **[Read the docs](https://imdinu.github.io/apple-mail-mcp/)** for the full guide.
 
@@ -46,22 +46,21 @@ apple-mail-mcp index --verbose
 |------|---------|
 | `list_accounts()` | List email accounts |
 | `list_mailboxes(account?)` | List mailboxes |
-| `get_emails(filter?, limit?)` | Get emails — all, unread, flagged, today, this_week |
+| `get_emails(filter?, limit?)` | Get emails — all, unread, flagged, today, last_7_days |
 | `get_email(message_id)` | Get single email with full content + attachments |
 | `search(query, scope?)` | Search — all, subject, sender, body, attachments |
-| `get_attachment(message_id, filename)` | Extract attachment content (base64) |
+| `get_attachment(message_id, filename)` | Extract attachment to disk, or extract links |
 
 ## Performance
 
-| Scenario | Apple Mail MCP | Best alternative | Speedup |
-|----------|---------------|-----------------|---------|
-| Fetch single email | 6ms | unsupported | **Only one** (disk-first) |
-| Fetch 50 emails | 301ms | 13,800ms+ | **46x faster** |
-| Search (subject) | 10ms | 148ms | **15x faster** |
-| Search (body) | 22ms | unsupported | **Only one** |
-| List accounts | 118ms | 134ms | Fastest |
+Tested against [6 other Apple Mail MCP servers](https://imdinu.github.io/apple-mail-mcp/benchmarks/) on a 30K+ email mailbox:
 
-> Benchmarked against [5 other Apple Mail MCP servers](https://imdinu.github.io/apple-mail-mcp/benchmarks/) at the MCP protocol level.
+- **Only server** that completes all operations without timing out
+- **Only server** with full-text body search (FTS5 index, ~20ms)
+- **5ms** single email fetch via disk-first `.emlx` reading
+- **7–9ms** subject search via FTS5 (vs 230ms+ for AppleScript-based servers)
+
+![Capability Matrix](benchmark_overview.png)
 
 ## Configuration
 
@@ -97,7 +96,7 @@ If you used [supermemoryai/apple-mcp](https://github.com/supermemoryai/apple-mcp
 | `search_emails` | `search(query, scope?)` — 5 scopes: all, subject, sender, body, attachments |
 | `send_email` | Not yet supported (planned) |
 
-**What's different:** available on PyPI (`pipx install apple-mail-mcp`), disk-first single-email reads (~1-5ms via .emlx parsing), 87x faster batch fetching via JXA, FTS5 search index for ~2ms body search, and disk-based sync that avoids JXA timeouts and false-success responses.
+**What's different:** available on PyPI (`pipx install apple-mail-mcp`), full-text body search via FTS5 (~20ms), disk-first single-email reads (~5ms), reliable on large mailboxes (30K+) where AppleScript-based servers timeout.
 
 ## Development
 

benchmarks/charts.py

@@ -169,6 +169,164 @@ def generate_chart(
     return png_path
 
 
+# ─── Overview (capability matrix) ────────────────────────────
+
+# Friendly display names for the overview chart
+COMPETITOR_LABELS = {
+    "imdinu": "apple-mail-mcp (ours)",
+    "rusty": "rusty (Rust)",
+    "patrickfreyer": "patrickfreyer",
+    "dhravya": "dhravya (archived)",
+    "smorgan": "s-morgan-jeffries",
+    "attilagyorffy": "attilagyorffy (Go)",
+    "che-apple-mail": "che (Swift)",
+}
+
+# Display order: us first, then by interest
+COMPETITOR_ORDER = [
+    "imdinu",
+    "rusty",
+    "patrickfreyer",
+    "attilagyorffy",
+    "smorgan",
+    "dhravya",
+]
+
+SCENARIO_SHORT = {
+    "cold_start": "Cold Start",
+    "list_accounts": "List\nAccounts",
+    "get_emails": "Fetch 50\nEmails",
+    "get_email": "Fetch\nSingle Email",
+    "search_subject": "Search\nSubject",
+    "search_body": "Search\nBody",
+}
+
+# Color codes: 0 = success, 1 = timeout/error, 2 = not supported
+COLOR_MAP = {0: "#22c55e", 1: "#ef4444", 2: "#d1d5db"}
+
+
+def _classify_result(
+    results: list[dict], competitor: str, scenario: str
+) -> tuple[int, str]:
+    """Classify a benchmark result as (code, label).
+
+    Returns (0, "Xms"), (1, "TIMEOUT"), (1, "ERROR"), or (2, "—").
+    """
+    matches = [
+        r
+        for r in results
+        if r["competitor"] == competitor and r["scenario"] == scenario
+    ]
+    if not matches:
+        return 2, "—"
+    r = matches[0]
+    if r["success"]:
+        return 0, f"{r['median_ms']:.0f}ms"
+    err = r.get("error", "")
+    if "Not supported" in err:
+        return 2, "—"
+    if "No such file" in err:
+        return 2, "N/A"
+    if "timeout" in err.lower() or "too slow" in err.lower():
+        return 1, "TIMEOUT"
+    return 1, "ERROR"
+
+
+def generate_overview_chart(
+    results: list[dict],
+    output_dir: Path,
+) -> Path:
+    """Generate the capability matrix overview chart."""
+    scenarios = list(SCENARIO_SHORT.keys())
+    # Filter to competitors present in results
+    present = {r["competitor"] for r in results}
+    competitors = [c for c in COMPETITOR_ORDER if c in present]
+
+    # Build grid (rows = competitors, cols = scenarios)
+    # Reverse so "ours" appears at top in the chart
+    z_values: list[list[int]] = []
+    annotations: list[list[str]] = []
+    for comp in reversed(competitors):
+        row_z = []
+        row_a = []
+        for sc in scenarios:
+            code, label = _classify_result(results, comp, sc)
+            row_z.append(code)
+            row_a.append(label)
+        z_values.append(row_z)
+        annotations.append(row_a)
+
+    y_labels = [
+        COMPETITOR_LABELS.get(c, c) for c in reversed(competitors)
+    ]
+    x_labels = [SCENARIO_SHORT[s] for s in scenarios]
+
+    # Custom colorscale: 0=green, 0.5=red, 1=gray
+    colorscale = [
+        [0.0, COLOR_MAP[0]],
+        [0.33, COLOR_MAP[0]],
+        [0.34, COLOR_MAP[1]],
+        [0.66, COLOR_MAP[1]],
+        [0.67, COLOR_MAP[2]],
+        [1.0, COLOR_MAP[2]],
+    ]
+
+    fig = go.Figure(
+        data=go.Heatmap(
+            z=z_values,
+            x=x_labels,
+            y=y_labels,
+            colorscale=colorscale,
+            showscale=False,
+            zmin=0,
+            zmax=2,
+            xgap=3,
+            ygap=3,
+        )
+    )
+
+    # Add text annotations
+    for i, row in enumerate(annotations):
+        for j, text in enumerate(row):
+            font_color = "#ffffff" if z_values[i][j] < 2 else "#6b7280"
+            fig.add_annotation(
+                x=x_labels[j],
+                y=y_labels[i],
+                text=f"<b>{text}</b>",
+                showarrow=False,
+                font=dict(size=13, color=font_color),
+            )
+
+    fig.update_layout(
+        title=dict(
+            text="Apple Mail MCP Servers — Capability Matrix (30K+ mailbox)",
+            font=dict(size=16, color="#111827"),
+            x=0.0,
+        ),
+        xaxis=dict(
+            side="top",
+            tickfont=dict(size=11),
+        ),
+        yaxis=dict(
+            tickfont=dict(size=12),
+            automargin=True,
+        ),
+        plot_bgcolor=COLOR_BG,
+        paper_bgcolor=COLOR_BG,
+        margin=dict(l=10, r=20, t=80, b=30),
+        height=max(300, 50 * len(competitors) + 120),
+        width=750,
+    )
+
+    png_path = output_dir / "benchmark_overview.png"
+    fig.write_image(str(png_path), scale=2)
+
+    html_path = RESULTS_DIR / "benchmark_overview.html"
+    fig.write_html(str(html_path), include_plotlyjs="cdn")
+
+    return png_path
+
+
 def main() -> None:
     parser = argparse.ArgumentParser(
         description="Generate benchmark charts from results"
@@ -208,6 +366,13 @@ def main() -> None:
     ]
 
     generated = []
+
+    # Overview chart (capability matrix)
+    overview = generate_overview_chart(results, output_dir)
+    print(f"  Generated {overview.name}")
+    generated.append(overview)
+
+    # Per-scenario charts
     for scenario in scenarios:
         png = generate_chart(scenario, results, output_dir)
         if png:

benchmarks/competitors.py

@@ -105,19 +105,17 @@ def _register(c: Competitor) -> None:
                 {"email_id": None},
             ),  # email_id discovered at runtime
             "search_subject": ToolCall(
-                "search_email_content",
+                "search_emails",
                 {
                     "account": BENCHMARK_ACCOUNT,
-                    "search_text": SEARCH_QUERY,
+                    "subject": SEARCH_QUERY,
                 },
             ),
             "search_body": ToolCall(
-                "search_email_content",
+                "search_emails",
                 {
                     "account": BENCHMARK_ACCOUNT,
-                    "search_text": SEARCH_QUERY,
-                    "search_subject": False,
-                    "search_body": True,
+                    "body": SEARCH_QUERY,
                 },
             ),
         },
@@ -227,3 +225,32 @@ def _register(c: Competitor) -> None:
         notes="Go binary, no list_accounts or body search",
     )
 )
+
+# 7. like-a-freedom/rusty_apple_mail_mcp (Rust, reads Envelope Index)
+_register(
+    Competitor(
+        name="rusty_apple_mail_mcp",
+        key="rusty",
+        command=[
+            f"{CACHE_DIR}/rusty-apple-mail-mcp"
+            "/target/release/rusty_apple_mail_mcp",
+        ],
+        tool_mapping={
+            "list_accounts": ToolCall(
+                "list_accounts", {"include_mailboxes": False}
+            ),
+            "get_emails": ToolCall(
+                "search_messages",
+                {"mailbox": "INBOX", "limit": 50},
+            ),
+            "get_email": ToolCall(
+                "get_message", {"message_id": None}
+            ),  # message_id is a string, not int
+            "search_subject": ToolCall(
+                "search_messages",
+                {"subject_query": SEARCH_QUERY, "limit": 50},
+            ),
+        },
+        notes="Rust binary, reads Apple Envelope Index directly",
+    )
+)