mcp-macos 4.0.0 → 4.1.0

package/README.md

@@ -1,17 +1,40 @@
-# macos-mcp ![License: MIT](https://img.shields.io/badge/license-MIT-green)
+# macos-mcp ![Platform: macOS](https://img.shields.io/badge/platform-macOS-blue) ![License: MIT](https://img.shields.io/badge/license-MIT-green)
 
 > Based on [FradSer/mcp-server-apple-events](https://github.com/FradSer/mcp-server-apple-events)
 
-MCP server for Reminders, Calendar, Notes, Mail, Messages, and Contacts on macOS. Local stdio transport for Claude Desktop, Claude Code, and Cursor.
+MCP server for Reminders, Calendar, Notes, Mail, Messages, and Contacts on macOS. Local stdio transport — works with any MCP-capable client running on the same Mac (Claude Code, Claude Desktop, Cursor, Zed, Continue, ChatGPT desktop, etc.).
+
+> **Requires a Mac.** This server drives native macOS apps via EventKit, JXA (Apple Events), and SQLite reads of local Apple databases. It cannot run on Linux, Windows, iOS, Android, or in a web browser. You need a Mac (desktop or laptop) running macOS.
+
+## Design Notes
+
+- **SQLite for reads, JXA for writes.** JXA reads of Mail and Messages don't scale — 60s timeouts on real inboxes, and JXA Messages reads are broken entirely on macOS Sonoma+. This server reads `chat.db` and Mail's `Envelope Index` directly, including the Gmail `labels` join table for `[Gmail]/All Mail` accounts. Writes still go through JXA because Apple Events is the only API that triggers them. See [ADR-001](DECISION.md).
+- **Per-app hybrid backend.** Each app uses the bridge that works: Swift CLI through EventKit for Reminders and Calendar, JXA for Notes/Contacts/Mail-writes/Messages-send, SQLite for Mail and Messages reads. The architecture diagram below shows the full fan-out.
+- **Cross-tool contact enrichment.** A shared layer resolves raw phone numbers and emails to contact names across Messages, Mail, and Calendar. Bulk cache via SQLite AddressBook (<50ms for 1,100+ entries), targeted lookups via JXA `whose()`. See [ADR-002](DECISION.md).
+- **Preflight check.** `macos-mcp --check` validates macOS version, Node.js, the EventKit binary, Full Disk Access, and JXA permissions before runtime, with deep-links to the relevant System Settings panes for any failures.
 
 ## Quick Start
 
+### Install as a Claude Code plugin
+
+```
+/plugin marketplace add krmj22/macos-mcp
+/plugin install macos-mcp@krmj22-plugins
+```
+
+Run these inside Claude Code. The plugin wires up the MCP server via `npx -y mcp-macos`, so no separate install step is required.
+
 ### Install from npm
 
 ```bash
 npm install -g mcp-macos
+# or use npx via your client's MCP config (no global install needed)
 ```
 
+### Or install via MCPB (Claude Desktop)
+
+Download the `.mcpb` bundle from the [latest GitHub release](https://github.com/krmj22/macos-mcp/releases/latest) and drag it onto Claude Desktop. The bundle includes a pre-built universal Swift binary (arm64 + x86_64), so no Xcode Command Line Tools required.
+
 ### Or build from source
 
 ```bash
@@ -162,12 +185,35 @@ Production entry point (`bin/run.cjs`) requires `pnpm build`. Use `pnpm dev` for
 
 ### Architecture
 
+```mermaid
+flowchart LR
+    Client[MCP Client<br/>Claude Code, Cursor, Desktop] -->|stdio| Server[macos-mcp]
+
+    Server --> Swift[Swift CLI]
+    Server --> JXA[JXA]
+    Server --> SQLite[SQLite Readers]
+
+    Swift -->|EventKit| Reminders[Reminders]
+    Swift -->|EventKit| Calendar[Calendar]
+
+    JXA -->|Apple Events| Notes[Notes]
+    JXA -->|Apple Events| Contacts[Contacts]
+    JXA -->|writes only| Mail[Mail]
+    JXA -->|send only| Messages[Messages]
+
+    SQLite -->|Envelope Index| Mail
+    SQLite -->|chat.db| Messages
+    SQLite -->|AddressBook| Enrich[Contact<br/>Enrichment Cache]
+```
+
 Three bridges to Apple apps:
 
 - **EventKit (Swift binary)** — Reminders, Calendar. Compiled Swift CLI, returns JSON.
 - **JXA** — Notes, Mail writes, Contacts. Scripts run via `osascript -l JavaScript`.
 - **SQLite** — Messages reads (`~/Library/Messages/chat.db`), Mail reads (`~/Library/Mail/V10/MailData/Envelope Index`). JXA message reading is broken on Sonoma+; JXA mail reading is too slow for real inboxes.
 
+Mail and Messages use a hybrid path: JXA for writes (only way to trigger send/draft), SQLite for reads (the only way that scales). See [DECISION.md](DECISION.md) for architecture decision records.
+
 ### Dependencies
 
 **Runtime:** `@modelcontextprotocol/sdk`, `zod`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-macos",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "MCP server for Reminders, Calendar, Notes, Mail, Messages, and Contacts on macOS.",
   "author": "Kyle Jensen",
   "contributors": [
@@ -50,6 +50,8 @@
     "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "build:ts": "tsc -p tsconfig.json",
     "build:swift": "node scripts/build-swift.mjs",
+    "build:swift:universal": "node scripts/build-swift-universal.mjs",
+    "build:mcpb": "node scripts/build-mcpb.mjs",
     "build": "pnpm run clean && pnpm run build:ts && pnpm run build:swift",
     "dev": "node bin/dev.cjs",
     "test": "NODE_NO_WARNINGS=1 jest",
@@ -73,6 +75,7 @@
     "@babel/preset-env": "^7.29.0",
     "@biomejs/biome": "2.3.15",
     "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/exec": "^7.1.0",
     "@semantic-release/git": "^10.0.1",
     "@types/jest": "^30.0.0",
     "@types/node": "^25.2.3",