apple-mail-mcp 2.8.2 → 2.8.4

package/README.md

@@ -98,6 +98,25 @@ npm install -g github:sweetrb/apple-mail-mcp
 
 On first use, macOS will ask for permission to automate Mail.app. Click "OK" to allow.
 
+## Configuring email (IMAP & SMTP)
+
+The server works out of the box over AppleScript with **no configuration**. Two
+**opt-in** power features take a one-time setup:
+
+- **Fast IMAP reads** — server-side search, counts, and large-mailbox handling
+  that AppleScript is too slow for (it times out on big Gmail mailboxes).
+- **Clean SMTP sending** — `send-email` submits clean MIME directly, avoiding the
+  macOS 15+ Mail.app `<blockquote>` wrapping that otherwise makes sent mail look
+  quoted/indented like a reply.
+
+Both are driven by non-secret `APPLE_MAIL_MCP_*` settings — supplied via an `env`
+block **or** a `config.json` file (for hosts like Claude Desktop that strip `env`)
+— with passwords kept in the macOS **Keychain**, never in config.
+
+👉 **[IMAP / SMTP Setup Guide](docs/IMAP-SETUP.md)** — step-by-step: app passwords,
+Keychain, both config methods, multi-account, SMTP, verification with the `doctor`
+tool, and troubleshooting. Verify any time by running the **`doctor`** tool.
+
 ## Requirements
 
 - **macOS** - Apple Mail and AppleScript are macOS-only
@@ -1122,10 +1141,10 @@ npm install -g github:sweetrb/apple-mail-mcp
 ```bash
 git clone https://github.com/sweetrb/apple-mail-mcp.git
 cd apple-mail-mcp
-npm install
-npm run build
 ```
 
+The repo ships prebuilt, dependency-free `build/index.js` and `build/cli.js` bundles, so a bare clone runs with nothing but Node installed. `npm install` and `npm run build` are only needed when you change the source.
+
 If installed from source, use this configuration:
 ```json
 {
@@ -1140,7 +1159,7 @@ If installed from source, use this configuration:
 
 #### Running from a clone in Claude Code (project-scope `.mcp.json`)
 
-This repo ships a `.mcp.json` at its root so that, when you run `claude` from inside a clone, the server is registered automatically as a **project-scope** server — no manual config needed. After `npm run build`, just launch Claude Code from the repo directory and approve the server when prompted.
+This repo ships a `.mcp.json` at its root so that, when you run `claude` from inside a clone, the server is registered automatically as a **project-scope** server — no manual config needed. Just launch Claude Code from the repo directory and approve the server when prompted (the bundled `build/index.js` is committed, so no build step is required).
 
 The entrypoint is written as:
 
@@ -1265,7 +1284,7 @@ The `\\\\` in JSON becomes `\\` in the actual string, which represents a single
 
 ### `apple-mail` server fails to connect when run from a clone
 - The root `.mcp.json` resolves its entrypoint via `${CLAUDE_PROJECT_DIR:-.}/build/index.js`. **Launch `claude` from inside the repo directory** — `CLAUDE_PROJECT_DIR` only resolves to the repo root in that case; the bare `.` fallback uses the launching shell's working directory and will point at the wrong place otherwise.
-- Run `npm run build` first — the server is `build/index.js`, which doesn't exist until you build.
+- If you've been editing the source, rerun `npm run build` — the server is `build/index.js`, and the committed bundle only reflects your changes after a rebuild.
 - Run `claude mcp list` to check status. If you see a *conflicting scopes* warning for `apple-mail`, you have it registered at more than one scope; project-scope wins. See [Running from a clone](#running-from-a-clone-in-claude-code-project-scope-mcpjson) for how scope precedence resolves.
 - If `claude mcp get apple-mail` shows **⏸ Pending approval**, approve the project-scope server (Claude Code prompts on startup, or run it again after approving).
 
@@ -1275,7 +1294,7 @@ The `\\\\` in JSON becomes `\\` in the actual string, which represents a single
 
 ```bash
 npm install            # Install dependencies
-npm run build          # Compile TypeScript
+npm run build          # Typecheck, then bundle src/index.ts + src/cli.ts into build/ (esbuild)
 npm test               # Run unit tests
 npm run test:integration  # Run integration tests (requires Mail.app)
 npm run test:all       # Run all tests (unit + integration)