read-email-mcp 1.0.0 → 2.0.1

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 KelpHect
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 KelpHect
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,14 +4,14 @@ A read-only [Model Context Protocol](https://modelcontextprotocol.io) server tha
 
 It works with Gmail, Outlook, Yahoo, Fastmail, iCloud, Proton Mail Bridge, self-hosted mail, and any other provider that exposes standard IMAP.
 
-> **Version 1.0.0-rc.1** release candidate. The tool surface and configuration are stable for review. Please report issues.
+> **Version 2.0.1.** Please report issues.
 
 ## Why use it
 
 - **Fast browsing and search.** Email is synced once into a local SQLite mirror with full-text search. Every browse, search, and read call hits the local copy, so it is quick and never re-logs-in to IMAP per request.
 - **Read-only and safe.** It never sends, deletes, moves, flags, or marks messages. IMAP mailboxes are opened with read-only locks. Your mailbox cannot be mutated by this server.
-- **Provider agnostic.** Point it at any IMAP server with host, port, and TLS settings. No vendor lock-in.
-- **Private by design.** Credentials stay in the process environment. Passwords are never written to disk. Raw `.eml` files live under your home directory and never leave your machine.
+- **Provider agnostic.** Works with any IMAP server. Common providers are auto-detected from the email domain, and custom/self-hosted servers get automatic discovery via autoconfig, DNS, and MX records.
+- **Private by design.** Credentials live in environment variables or your password manager's CLI — nothing requires storing passwords on disk. Raw `.eml` files live under your home directory and never leave your machine.
 - **MCP native.** Exposes a clean set of tools over stdio so any MCP-compatible client can read email on your behalf.
 
 ## Requirements
@@ -22,20 +22,27 @@ It works with Gmail, Outlook, Yahoo, Fastmail, iCloud, Proton Mail Bridge, self-
 
 ## Quick start
 
+The fastest path is the account wizard — it detects your provider, fills in the IMAP settings, verifies the connection, and writes the accounts file for you:
+
+```powershell
+npx -y read-email-mcp@2.0.1 accounts add
+npx -y read-email-mcp@2.0.1 init        # prints the MCP client config to paste
+```
+
+From source instead:
+
 ```powershell
 git clone <this-repo>
 cd read-email-mcp
 npm install
 npm run build
+node dist/index.js accounts add
 ```
 
-Run the server with credentials and an IMAP host:
+Or run the server directly with credentials — the IMAP host is optional for known providers:
 
 ```powershell
-node dist/index.js `
-  --email "you@gmail.com" `
-  --password "your-app-password" `
-  --imap-host "imap.gmail.com"
+node dist/index.js --email "you@gmail.com" --password "your-app-password"
 ```
 
 Or set environment variables and omit the flags:
@@ -43,7 +50,6 @@ Or set environment variables and omit the flags:
 ```powershell
 $env:EMAIL = "you@gmail.com"
 $env:PASSWORD = "your-app-password"
-$env:IMAP_HOST = "imap.gmail.com"
 node dist/index.js
 ```
 
@@ -55,15 +61,114 @@ All settings can be passed as CLI args or environment variables. CLI args take p
 | --- | --- | --- | --- | --- |
 | Email address | yes | `EMAIL` | `--email` | none |
 | Password | yes | `PASSWORD` | `--password` | none |
-| IMAP host | yes | `IMAP_HOST` | `--imap-host` | none |
+| IMAP host | no* | `IMAP_HOST` | `--imap-host` | auto-detected for known providers |
 | IMAP port | no | `IMAP_PORT` | `--imap-port` | `993` |
 | IMAP TLS | no | `IMAP_SECURE` | `--imap-secure` | `true` |
 | IMAP login user | no | `IMAP_USER` | `--imap-user` | same as email |
+| TLS cert verification | no | `IMAP_TLS_REJECT_UNAUTHORIZED` | — | `true` (set `false` for self-signed certs) |
+| Accounts file | no | `ACCOUNTS_FILE` | `--accounts` | `~/.read-email-mcp/accounts.json` if it exists |
+| Env file | no | `ENV_FILE` | `--env-file` | `./.env` then `~/.read-email-mcp/.env` if present |
+
+*`IMAP_HOST` is only required when the email domain isn't a known provider (see "Common provider settings"). For `gmail.com`, `outlook.com`, `icloud.com`, and the other presets, host/port/TLS are filled in automatically — `EMAIL` + `PASSWORD` is enough.
 
 `IMAP_SECURE` accepts `true` or `false` (also `1`/`0`, `yes`/`no`, `on`/`off`). Use `false` with port `143` for STARTTLS or plain IMAP.
 
 `IMAP_USER` is optional. Set it only when the IMAP login name differs from the mailbox email address. When omitted, the email address is used as the IMAP username.
 
+`.env` files are loaded automatically: `./.env` first, then `~/.read-email-mcp/.env`, without overriding variables already set. Use `--env-file`/`ENV_FILE` to point at a specific file instead.
+
+> Prefer `PASSWORD` or a `.env` file over `--password`: CLI arguments are visible in process listings and shell history.
+
+### Managing accounts from the command line
+
+The binary doubles as an account-management CLI — the fastest way to get set up:
+
+```powershell
+read-email-mcp accounts add                # interactive wizard (prompts for what's missing)
+read-email-mcp accounts list               # show configured accounts
+read-email-mcp accounts remove work        # remove by name or email
+read-email-mcp accounts test               # check IMAP connectivity for every account
+read-email-mcp accounts test work          # check one account
+read-email-mcp accounts discover me@corp.example  # auto-detect IMAP settings
+read-email-mcp init                        # print a ready-to-paste MCP client config
+```
+
+`accounts add` detects the provider from the email domain, fills in IMAP settings, and offers to store the password as an env-var reference (it can save it into the `.env` file for you). Non-interactive use works too — handy for scripts:
+
+```powershell
+read-email-mcp accounts add --name work --email me@work.com `
+  --imap-host imap.work.com --password-env WORK_IMAP_PASSWORD --group work
+```
+
+Before writing the file, `accounts add` tests the connection with your credentials and reports how many mailboxes it found — wrong passwords and typos get caught immediately instead of at first sync. Use `--no-test` to skip, or `--test` to enforce the check in scripts.
+
+`accounts test` connects to each account, lists its mailboxes, and reports failures with provider hints — use it to verify credentials before wiring the server into a client.
+
+### Custom and self-hosted IMAP
+
+For domains that don't match a provider preset, `accounts add` auto-detects the IMAP settings instead of making you look them up. It tries, in order:
+
+1. **Mozilla autoconfig** — `autoconfig.<domain>` and `/.well-known/autoconfig`, the standard most cPanel/Dovecot and hosted-IMAP setups publish.
+2. **DNS SRV records** — `_imaps._tcp.<domain>` / `_imap._tcp.<domain>` (RFC 6186).
+3. **MX inference** — a company domain hosted on Google Workspace or Microsoft 365 resolves to that provider's IMAP servers.
+4. **Hostname probing** — `imap.<domain>` and `mail.<domain>` on the standard ports.
+
+Preview what would be found without creating an account:
+
+```powershell
+read-email-mcp accounts discover me@corp.example
+```
+
+You can always override the detected values with `--imap-host`, `--imap-port`, `--imap-secure`, and `--imap-user`. For servers with self-signed certificates, pass `--allow-self-signed` (or set `"imapTlsRejectUnauthorized": false` in the accounts file); if the connection test hits a certificate error, the wizard offers this retry automatically. Single-account env config supports the equivalent `IMAP_TLS_REJECT_UNAUTHORIZED=false`.
+
+### Multiple accounts
+
+Point `--accounts` (or `ACCOUNTS_FILE`) at a JSON file to mirror several mailboxes in one server. Single-account env/CLI config is ignored when an accounts file is used.
+
+```json
+{
+  "accounts": [
+    {
+      "name": "work",
+      "email": "me@work.com",
+      "passwordEnv": "WORK_IMAP_PASSWORD",
+      "imapHost": "imap.work.com",
+      "groups": ["work"]
+    },
+    {
+      "name": "personal",
+      "email": "me@gmail.com",
+      "passwordCommand": "op read op://Private/Gmail/app-password",
+      "groups": ["personal"]
+    }
+  ]
+}
+```
+
+The `personal` entry needs no `imapHost` — `gmail.com` resolves to the Gmail preset automatically. Easiest way to produce this file is `read-email-mcp accounts add`.
+
+Each entry needs `email` plus one credential method. `imapHost` is optional when the domain (or an explicit `provider`) matches a preset — see "Common provider settings". Optional fields:
+
+| Field | Purpose |
+| --- | --- |
+| `name` | Friendly name for the `account` tool parameter (defaults to the email; names and emails must be unique) |
+| `provider` | Preset id (`gmail`, `outlook`, `yahoo`, `icloud`, `fastmail`, `zoho`, `aol`, `gmx`, `proton`, `yandex`, `mailcom`) — fills in host/port/TLS |
+| `passwordEnv` | Name of an env var holding the password (preferred — secrets stay out of the file) |
+| `passwordCommand` | Shell command whose stdout is the password, e.g. `op read op://Private/Email/password` for 1Password CLI |
+| `password` | Inline password (discouraged — only for local testing) |
+| `imapHost` / `imapPort` / `imapSecure` / `imapUser` | Same meaning as the single-account settings |
+| `imapTlsRejectUnauthorized` | Set `false` for self-signed certificates (skip TLS verification — use only on servers you trust) |
+| `groups` | Labels like `["work", "clients"]` — select several accounts at once via the `accountGroup` tool parameter |
+
+Every account gets its own mirror under `~/.read-email-mcp/<account-hash>/`. Tools accept `account` (name or email), `accounts` (a list, `*` wildcard supported), or `accountGroup` (matches `groups`):
+
+- `sync_email` without a selector syncs every configured account **in parallel** and reports per-account results; a selector scopes it to a subset.
+- `get_recent_emails`, `list_emails`, `search_emails`, and `browse_email_dates` without a selector merge results across accounts into one view; each item is tagged with its account.
+- `get_email`, `get_emails`, `get_thread`, `list_attachments`, `get_attachment`, and `get_raw_email` need a single account when resolving by `id`, `ids`, or `mailbox`+`uid` (ids are per-account). `messageId` lookups search all accounts automatically.
+- `get_sync_status`, `list_mailboxes`, `get_storage_stats`, `optimize_email_store`, `get_inbox_summary`, and `check_accounts` without a selector return a per-account summary.
+
+`list_accounts` shows the configured accounts, their providers, groups, storage paths, and message counts.
+
 ### Common provider settings
 
 | Provider | IMAP host | Port | TLS | Notes |
@@ -78,7 +183,7 @@ All settings can be passed as CLI args or environment variables. CLI args take p
 
 ## MCP client configuration
 
-The server speaks MCP over stdio. Add it to any MCP-compatible client.
+The server speaks MCP over stdio. Add it to any MCP-compatible client — `read-email-mcp init` prints a ready-to-paste config block for your setup.
 
 ### Claude Desktop
 
@@ -89,13 +194,11 @@ The server speaks MCP over stdio. Add it to any MCP-compatible client.
       "command": "npx",
       "args": [
         "-y",
-        "read-email-mcp@1.0.0-rc.1",
+        "read-email-mcp",
         "--email",
         "you@gmail.com",
         "--password",
-        "your-app-password",
-        "--imap-host",
-        "imap.gmail.com"
+        "your-app-password"
       ]
     }
   }
@@ -111,51 +214,90 @@ Set credentials in the server environment and pass only the binary:
   "mcpServers": {
     "read-email": {
       "command": "npx",
-      "args": ["-y", "read-email-mcp@1.0.0-rc.1"],
+      "args": ["-y", "read-email-mcp"],
       "env": {
         "EMAIL": "you@gmail.com",
-        "PASSWORD": "your-app-password",
-        "IMAP_HOST": "imap.gmail.com"
+        "PASSWORD": "your-app-password"
       }
     }
   }
 }
 ```
 
-> On npm, pre-release versions like `1.0.0-rc.1` are not selected by `@latest`. Pin the exact version as shown above, or install from source after building.
+### opencode
+
+`read-email-mcp init` also prints this block. Add it to `opencode.json` (or `.opencode.json`):
+
+```json
+{
+  "mcp": {
+    "read-email": {
+      "type": "local",
+      "command": ["npx", "-y", "read-email-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+### Devin CLI
+
+```powershell
+devin mcp add read-email -- npx -y read-email-mcp --accounts "C:\path\to\accounts.json"
+```
+
+Add `-e EMAIL=you@gmail.com -e PASSWORD=app-password` for a single-account env config instead of `--accounts`.
+
+> Pin a version (e.g. `read-email-mcp@2.0.1`) or install from source after building.
 
 ## Tools
 
-The server exposes 12 tools. All read from the local mirror except `sync_email`, which pulls from IMAP.
+The server exposes 19 tools. All read from the local mirror except `sync_email` and `check_accounts`, which talk to IMAP.
 
-- `sync_email`: pull new messages from IMAP into the local mirror. Call this first, or after a gap, before browsing or searching. Start with a small limit on one mailbox to verify credentials, then sync more.
+- `sync_email`: pull messages from IMAP into the local mirror. Call this first, or after a gap, before browsing or searching. Default is incremental (only new UIDs); pass `uids`, `search`, or `since` for a targeted fetch of specific messages, or `refreshFlags` to re-sync read/flagged state. Multiple accounts sync in parallel. See "How sync works" below.
+- `list_accounts`: list configured accounts with providers, groups, storage paths, and message counts.
+- `check_accounts`: test IMAP connectivity per account (connect, list mailboxes, disconnect) — diagnose auth or network problems.
 - `get_sync_status`: show account, storage path, total messages, latest message date, per-mailbox counts, and the last sync result. Good first check to see whether a sync is needed.
 - `list_mailboxes`: list locally known mailboxes (INBOX, Sent, Drafts, and so on) with message counts and last-sync time.
-- `get_recent_emails`: show the latest emails, newest first, with optional `unreadOnly` and `flaggedOnly`. This is the everyday tool for checking what is new.
+- `get_inbox_summary`: one-call triage briefing per account — total/unread/flagged counts, mailbox count, latest message date, and the newest unread summaries.
+- `get_recent_emails`: show the latest emails, newest first, with optional `unreadOnly`, `flaggedOnly`, and `last` lookback windows. This is the everyday tool for checking what is new.
 - `browse_email_dates`: summarize message volume as counts per day, week, or month. Useful for finding a busy period before drilling in with a date range.
-- `search_emails`: full-text search across subject, sender and recipient addresses, preview, and body, with filters and keyset pagination.
+- `search_emails`: full-text search across subject, sender and recipient addresses, preview, and body, with filters and pagination. `sort: "relevance"` ranks hits by match quality and interleaves each account's best results first.
 - `list_emails`: list email summaries in chronological order with filters and pagination, without full-text search. Prefer this when browsing by sender, date, or mailbox.
-- `get_email`: return full metadata and body (text and HTML) for a single message, by id, Message-ID, or mailbox plus UID.
+- `list_senders`: rank senders by message count with per-sender unread counts, merged across the selected accounts — good for "who emails me most" or finding a person.
+- `get_email`: return metadata and body for a single message, by id, Message-ID, or mailbox plus UID. `format` (`full`/`text`/`headers`/`summary`) and `maxBodyChars` keep responses sized for context windows.
+- `get_emails`: read a group of up to 25 messages in one call by id. Prefer this over looping `get_email` for several full bodies.
 - `get_thread`: return all locally known messages in one conversation, matched by Message-ID, In-Reply-To, and References headers.
+- `list_attachments`: list a message's attachments (index, filename, type, size) without downloading them.
+- `get_attachment`: extract one attachment by index or filename — returns base64 up to `maxBytes`, or writes to disk with `saveTo`.
 - `get_raw_email`: return raw RFC822/MIME source for one message, byte-limited. Use this only when you need original headers or MIME structure.
 - `get_storage_stats`: report SQLite database, WAL, and page statistics for the local mirror.
 - `optimize_email_store`: run lightweight SQLite and FTS maintenance to keep queries fast. Safe to run after large syncs.
 
-`search_emails`, `list_emails`, and `get_recent_emails` accept unread and flagged filters. `search_emails` and `list_emails` use `limit`, `cursor`, and `nextCursor` for keyset pagination.
+`search_emails`, `list_emails`, and `get_recent_emails` accept `mailbox`/`mailboxes`, unread, and flagged filters; `search_emails` and `list_emails` add `from`/`to`/`cc`/`subject`, date ranges (`startDate`/`endDate`) or relative `last` windows like `"7d"`, and `limit`/`cursor`/`nextCursor` pagination — pagination works across merged multi-account results too.
 
 ## Typical workflow
 
-1. Run `sync_email` with a small limit on one mailbox to verify credentials.
-2. Run `get_sync_status` to confirm the mirror is fresh.
-3. Run `get_recent_emails` with `unreadOnly: true` to see what is new.
-4. Run `get_email` to read a message, or `get_thread` to follow a conversation.
-5. Run `search_emails` or `list_emails` to find older messages by sender, subject, date range, or unread and flagged state.
+1. Run `check_accounts` to verify credentials and connectivity (or `read-email-mcp accounts test` outside the client).
+2. Run `sync_email` with a small limit on one mailbox, then `get_sync_status` to confirm the mirror is fresh.
+3. Run `get_inbox_summary` for unread counts and the newest unread per account, or `get_recent_emails` with `unreadOnly: true`.
+4. Run `get_email` (with `format`/`maxBodyChars` to keep responses small) or `get_thread` to follow a conversation.
+5. Run `search_emails` (optionally `sort: "relevance"`) or `list_emails` to find older messages by sender, subject, date range, or unread and flagged state.
 
 ## How sync works
 
-Sync connects to IMAP, lists selectable mailboxes, and fetches new messages by tracking the highest UID already seen per mailbox. If a mailbox UIDVALIDITY changes, the local copy for that mailbox is reset and refetched. Raw RFC822 source is written to disk, parsed metadata and body text go into SQLite, and a full-text search index is maintained alongside.
+Sync connects to IMAP, lists selectable mailboxes, and fetches new messages by tracking the highest UID already seen per mailbox. If a mailbox UIDVALIDITY changes, the local copy for that mailbox is reset and refetched (stale raw files are removed). Raw RFC822 source is written to disk, parsed metadata and body text go into SQLite, and a full-text search index is maintained alongside.
+
+Sync has two modes:
+
+- **Incremental** (default): only fetches UIDs above the stored high-water mark per mailbox. `resetMailbox: true` restarts the scan from UID 1 without losing the local copy (upserts refresh rows in place).
+- **Targeted**: pass `uids` (a set like `"12,15,20-30"`, requires one mailbox), `search` (server-side IMAP criteria: `from`, `to`, `cc`, `subject`, `since`, `before`, `unseen`, `flagged`), or `since` (shorthand for `search.since`). Targeted syncs fetch exactly the matching messages and never move the incremental cursor, so they are safe for backfills and one-off fetches.
+
+Mailbox selection: `mailbox`/`mailboxes` include specific folders, `excludeMailboxes` drops names (`*` wildcard supported), and `excludeFlags` drops folders by IMAP special-use flag — the default `["\\All"]` avoids double-mirroring Gmail's All Mail. Pass `excludeFlags: []` to sync everything.
+
+Flag freshness: incremental sync does not revisit already-synced messages, so `\Seen`/`\Flagged` changes and server-side deletions go stale over time. `refreshFlags: true` performs a cheap flags-only pass over synced UIDs, updating stored flags; `pruneExpunged` (default true alongside `refreshFlags`) also removes local copies of messages deleted on the server.
 
-Sync is incremental. Subsequent calls only fetch messages with UIDs higher than the stored high-water mark. Mailboxes are opened read-only, so flags and read state on the server are never changed.
+Mailboxes are opened read-only, so flags and read state on the server are never changed.
 
 ## Local storage
 
@@ -194,9 +336,10 @@ Tests use fixtures and fake IMAP clients, so they do not require real credential
 
 - No sending, replying, or composing email.
 - No deleting, moving, flagging, or marking messages read.
-- No OAuth. App passwords or direct passwords only.
+- No OAuth. App passwords, direct passwords, or `passwordCommand` credential helpers only.
 - No background daemon. Sync runs when the client calls `sync_email`.
-- Attachment bytes are summarized but not extracted to separate files.
+- Threads are assembled within one account's mirror; conversations spanning accounts are not merged.
+- `get_attachment` re-parses the stored `.eml` on demand, so extraction speed depends on message size.
 
 ## License
 

package/dist/accounts-cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(argv: string[]): Promise<number>;