Expand README with usage patterns, troubleshooting, and more

- Add CI badge to header
- Add Usage Patterns section with workflow examples
- Add Installation Options section (npm + from source)
- Add Known Limitations table
- Add Troubleshooting section with common issues
- Add Contributing reference
- Improve Tool Reference with examples and return descriptions
- Remove Status column from Features (all complete)
- Add horizontal rule separators between sections

README.md

@@ -2,8 +2,9 @@
 
 A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants like Claude to read, send, search, and manage emails in Apple Mail on macOS.
 
+[![npm version](https://img.shields.io/npm/v/apple-mail-mcp)](https://www.npmjs.com/package/apple-mail-mcp)
+[![CI](https://github.com/sweetrb/apple-mail-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/sweetrb/apple-mail-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![npm version](https://img.shields.io/npm/v/apple-mail-mcp.svg)](https://www.npmjs.com/package/apple-mail-mcp)
 
 ## What is This?
 
@@ -72,34 +73,39 @@ On first use, macOS will ask for permission to automate Mail.app. Click "OK" to
 
 - **macOS** - Apple Mail and AppleScript are macOS-only
 - **Node.js 20+** - Required for the MCP server
-- **Apple Mail** - Must have at least one account configured
+- **Apple Mail** - Must have at least one account configured (iCloud, Gmail, Exchange, etc.)
 
 ## Features
 
-| Feature | Status | Description |
-|---------|--------|-------------|
-| **List Messages** | ✅ | List messages in any mailbox |
-| **Search Messages** | ✅ | Find emails by sender, subject, content |
-| **Read Messages** | ✅ | Get full email content |
-| **Send Email** | ✅ | Compose and send new emails |
-| **Create Draft** | ✅ | Save emails to Drafts folder |
-| **Reply** | ✅ | Reply to messages (with reply-all support) |
-| **Forward** | ✅ | Forward messages to new recipients |
-| **Mark Read/Unread** | ✅ | Change read status |
-| **Flag/Unflag** | ✅ | Flag or unflag messages |
-| **Delete Messages** | ✅ | Move messages to trash |
-| **Move Messages** | ✅ | Organize into mailboxes |
-| **List Mailboxes** | ✅ | Show all folders with counts |
-| **List Accounts** | ✅ | Show configured accounts |
-| **Unread Count** | ✅ | Get unread counts per mailbox |
-| **Health Check** | ✅ | Verify Mail.app connectivity |
-| **Statistics** | ✅ | Message and unread counts |
+| Feature | Description |
+|---------|-------------|
+| **List Messages** | List messages in any mailbox |
+| **Search Messages** | Find emails by sender, subject, content |
+| **Read Messages** | Get full email content |
+| **Send Email** | Compose and send new emails |
+| **Create Draft** | Save emails to Drafts folder |
+| **Reply** | Reply to messages (with reply-all support) |
+| **Forward** | Forward messages to new recipients |
+| **Mark Read/Unread** | Change read status |
+| **Flag/Unflag** | Flag or unflag messages |
+| **Delete Messages** | Move messages to trash |
+| **Move Messages** | Organize into mailboxes |
+| **List Mailboxes** | Show all folders with counts |
+| **List Accounts** | Show configured accounts |
+| **Unread Count** | Get unread counts per mailbox |
+| **Health Check** | Verify Mail.app connectivity |
+| **Statistics** | Message and unread counts |
+
+---
 
 ## Tool Reference
 
+This section documents all available tools. AI agents should use these tool names and parameters exactly as specified.
+
 ### Message Operations
 
 #### `search-messages`
+
 Search for messages matching criteria.
 
 | Parameter | Type | Required | Description |
@@ -109,14 +115,22 @@ Search for messages matching criteria.
 | `account` | string | No | Account to search in |
 | `limit` | number | No | Max results (default: 50) |
 
+---
+
 #### `get-message`
+
 Get the full content of a message.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Message ID |
 
+**Returns:** Subject line and plain text body of the message.
+
+---
+
 #### `list-messages`
+
 List messages in a mailbox.
 
 | Parameter | Type | Required | Description |
@@ -125,7 +139,12 @@ List messages in a mailbox.
 | `account` | string | No | Account name |
 | `limit` | number | No | Max messages (default: 50) |
 
+**Returns:** List of messages with ID, subject, sender, date, read status, and flagged status.
+
+---
+
 #### `send-email`
+
 Send a new email immediately.
 
 | Parameter | Type | Required | Description |
@@ -137,7 +156,20 @@ Send a new email immediately.
 | `bcc` | string[] | No | BCC recipients |
 | `account` | string | No | Send from specific account |
 
+**Example:**
+```json
+{
+  "to": ["colleague@company.com"],
+  "subject": "Meeting Tomorrow",
+  "body": "Hi, just confirming our meeting at 2pm tomorrow.",
+  "account": "Work"
+}
+```
+
+---
+
 #### `create-draft`
+
 Save an email to Drafts without sending.
 
 | Parameter | Type | Required | Description |
@@ -149,7 +181,12 @@ Save an email to Drafts without sending.
 | `bcc` | string[] | No | BCC recipients |
 | `account` | string | No | Account for draft |
 
+**Returns:** Confirmation that draft was created.
+
+---
+
 #### `reply-to-message`
+
 Reply to an existing message.
 
 | Parameter | Type | Required | Description |
@@ -159,7 +196,28 @@ Reply to an existing message.
 | `replyAll` | boolean | No | Reply to all recipients (default: false) |
 | `send` | boolean | No | Send immediately (default: true, false = save as draft) |
 
+**Example - Reply to sender only:**
+```json
+{
+  "id": "12345",
+  "body": "Thanks for the update!"
+}
+```
+
+**Example - Reply all, save as draft:**
+```json
+{
+  "id": "12345",
+  "body": "I'll review this and get back to everyone.",
+  "replyAll": true,
+  "send": false
+}
+```
+
+---
+
 #### `forward-message`
+
 Forward a message to new recipients.
 
 | Parameter | Type | Required | Description |
@@ -169,28 +227,40 @@ Forward a message to new recipients.
 | `body` | string | No | Message to prepend |
 | `send` | boolean | No | Send immediately (default: true, false = save as draft) |
 
+---
+
 #### `mark-as-read` / `mark-as-unread`
+
 Change read status of a message.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Message ID |
 
+---
+
 #### `flag-message` / `unflag-message`
+
 Flag or unflag a message.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Message ID |
 
+---
+
 #### `delete-message`
+
 Delete a message (move to trash).
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `id` | string | Yes | Message ID |
 
+---
+
 #### `move-message`
+
 Move a message to a different mailbox.
 
 | Parameter | Type | Required | Description |
@@ -199,16 +269,24 @@ Move a message to a different mailbox.
 | `mailbox` | string | Yes | Destination mailbox |
 | `account` | string | No | Account containing mailbox |
 
+---
+
 ### Mailbox Operations
 
 #### `list-mailboxes`
+
 List all mailboxes for an account.
 
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `account` | string | No | Account to list from |
 
+**Returns:** List of mailbox names with unread counts.
+
+---
+
 #### `get-unread-count`
+
 Get unread message count.
 
 | Parameter | Type | Required | Description |
@@ -216,31 +294,175 @@ Get unread message count.
 | `mailbox` | string | No | Mailbox to check (omit for total) |
 | `account` | string | No | Account to check |
 
+---
+
 ### Account Operations
 
 #### `list-accounts`
+
 List all configured Mail accounts.
 
 **Parameters:** None
 
+**Returns:** List of account names (e.g., "iCloud", "Gmail", "Exchange").
+
+---
+
 ### Diagnostics
 
 #### `health-check`
+
 Verify Mail.app connectivity and permissions.
 
 **Parameters:** None
 
+**Returns:** Status of all health checks (app running, permissions, account access).
+
+---
+
 #### `get-mail-stats`
+
 Get mail statistics (total messages, unread counts per account).
 
 **Parameters:** None
 
+**Returns:** Total counts and per-account breakdown.
+
+---
+
+## Usage Patterns
+
+### Basic Workflow
+
+```
+User: "Check my inbox for new emails"
+AI: [calls list-messages with mailbox="INBOX"]
+    "You have 12 messages in your inbox. Here are the most recent..."
+
+User: "Show me emails from Sarah"
+AI: [calls search-messages with query="Sarah"]
+    "Found 3 emails from Sarah..."
+
+User: "Read the first one"
+AI: [calls get-message with id="..."]
+    "Subject: Project Update..."
+```
+
+### Working with Accounts
+
+By default, operations use the first configured account. To work with specific accounts:
+
+```
+User: "What email accounts do I have?"
+AI: [calls list-accounts]
+    "You have 3 accounts: iCloud, Gmail, Work Exchange"
+
+User: "Show unread emails in my Work account"
+AI: [calls list-messages with account="Work Exchange", mailbox="INBOX"]
+    "Your Work account has 5 unread messages..."
+```
+
+### Sending Emails Safely
+
+```
+User: "Draft an email to the team about the deadline"
+AI: [calls create-draft with to=["team@..."], subject="...", body="..."]
+    "I've created a draft. Please review it in Mail.app before sending."
+
+User: "Send it"
+AI: [User opens Mail.app and sends manually, or AI calls send-email]
+```
+
+### Organizing Messages
+
+```
+User: "Move all newsletters to Archive"
+AI: [calls search-messages to find newsletters]
+AI: [calls move-message for each, with mailbox="Archive"]
+    "Moved 8 newsletters to Archive"
+```
+
+---
+
+## Installation Options
+
+### npm (Recommended)
+
+```bash
+npm install -g apple-mail-mcp
+```
+
+### From Source
+
+```bash
+git clone https://github.com/sweetrb/apple-mail-mcp.git
+cd apple-mail-mcp
+npm install
+npm run build
+```
+
+If installed from source, use this configuration:
+```json
+{
+  "mcpServers": {
+    "apple-mail": {
+      "command": "node",
+      "args": ["/path/to/apple-mail-mcp/build/index.js"]
+    }
+  }
+}
+```
+
+---
+
 ## Security and Privacy
 
-- **Local only** - All operations happen locally via AppleScript
-- **Permission required** - macOS will prompt for automation permission
-- **No credential storage** - The server doesn't store any passwords
-- **Email safety** - Review emails before sending via `create-draft` + manual send
+- **Local only** - All operations happen locally via AppleScript. No data is sent to external servers.
+- **Permission required** - macOS will prompt for automation permission on first use.
+- **No credential storage** - The server doesn't store any passwords or authentication tokens.
+- **Email safety** - Use `create-draft` to review emails before sending.
+
+---
+
+## Known Limitations
+
+| Limitation | Reason |
+|------------|--------|
+| macOS only | Apple Mail and AppleScript are macOS-specific |
+| Plain text only | Email body is plain text; HTML formatting not supported |
+| No attachments | Cannot add or read attachments via AppleScript |
+| Message ID scope | Message IDs are searched across all mailboxes (may be slow with large mailboxes) |
+| No smart mailboxes | Cannot access Smart Mailboxes via AppleScript |
+
+---
+
+## Troubleshooting
+
+### "Mail.app not responding"
+- Ensure Mail.app is not frozen
+- Try opening Mail.app manually
+- Restart the MCP server
+
+### "Permission denied"
+- macOS needs automation permission
+- Go to System Preferences > Privacy & Security > Automation
+- Ensure your terminal/Claude has permission to control Mail
+
+### "Message not found"
+- Message may have been deleted or moved
+- Message IDs change if the message is moved between mailboxes
+- Use `search-messages` to find the current message ID
+
+### "Account not found"
+- Account names must match exactly (case-sensitive)
+- Use `list-accounts` to see exact account names
+
+### "Failed to send email"
+- Check your network connection
+- Verify Mail.app can send emails manually
+- Check if the account is configured correctly in Mail.app
+
+---
 
 ## Development
 
@@ -252,10 +474,14 @@ npm run lint     # Check code style
 npm run format   # Format code
 ```
 
+---
+
 ## Author
 
 **Rob Sweet** - President, [Superior Technologies Research](https://www.superiortech.io)
 
+A software consulting, contracting, and development company.
+
 - Email: rob@superiortech.io
 - GitHub: [@sweetrb](https://github.com/sweetrb)
 
@@ -263,6 +489,10 @@ npm run format   # Format code
 
 MIT License - see [LICENSE](LICENSE) for details.
 
+## Contributing
+
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
 ## Related Projects
 
 - [apple-notes-mcp](https://github.com/sweetrb/apple-notes-mcp) - MCP server for Apple Notes