@n24q02m/better-email-mcp 1.32.3-beta.2 → 1.33.0-beta.2

package/README.md

@@ -2,7 +2,7 @@
 
 mcp-name: io.github.n24q02m/better-email-mcp
 
-**IMAP/SMTP email server for AI agents -- 7 composite tools with multi-account and auto-discovery**
+**IMAP/SMTP email for AI agents -- read, send, organize folders, and manage attachments across multiple accounts, with auto-discovery.**
 
 <!-- Badge Row 1: Status -->
 [![CI](https://github.com/n24q02m/better-email-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/n24q02m/better-email-mcp/actions/workflows/ci.yml)
@@ -24,20 +24,21 @@ mcp-name: io.github.n24q02m/better-email-mcp
 
 | Project | Tagline | Tag |
 |---|---|---|
-| [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | Knowledge graph for token-efficient code reviews -- fixed search, configurabl... | MCP |
-| [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | IMAP/SMTP email server for AI agents -- 6 composite tools with multi-account ... | MCP |
-| [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Composite MCP server for Godot Engine -- 17 mega-tools for AI-assisted game d... | MCP |
-| [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | Markdown-first Notion API server for AI agents -- 10 composite tools replacin... | MCP |
-| [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | MCP server for Telegram with dual-mode support: Bot API (httpx) for quick bot... | MCP |
-| [claude-plugins](https://github.com/n24q02m/claude-plugins) | Full documentation: mcp.n24q02m.com — unified docs for all 8 servers + the mc... | Marketplace |
-| [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | Production-grade MCP server for image and video understanding + generation ac... | MCP |
+| [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |
+| [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |
+| [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |
+| [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |
+| [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |
+| [claude-plugins](https://github.com/n24q02m/claude-plugins) | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |
+| [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |
 | [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |
-| [mcp-core](https://github.com/n24q02m/mcp-core) | Unified MCP Streamable HTTP 2025-11-25 transport, OAuth 2.1 Authorization Ser... | MCP |
+| [mcp-core](https://github.com/n24q02m/mcp-core) | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP |
 | [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP |
 | [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library |
 | [skret](https://github.com/n24q02m/skret) | Secrets without the server. | CLI |
+| [tacet](https://github.com/n24q02m/tacet) | TACET: a self-distilling neuro-symbolic cascade that amortises LLM cost in kn... | Tooling |
 | [web-core](https://github.com/n24q02m/web-core) | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |
-| [wet-mcp](https://github.com/n24q02m/wet-mcp) | Open-source MCP Server for web search, content extraction, library docs & mul... | MCP |
+| [wet-mcp](https://github.com/n24q02m/wet-mcp) | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |
 
 </details>
 <!-- END: AUTO-GENERATED-CROSS-PROMO -->
@@ -67,7 +68,7 @@ mcp-name: io.github.n24q02m/better-email-mcp
 
 - **Multi-account support** -- manage 6+ email accounts (Gmail, Outlook, Yahoo, iCloud, Zoho, ProtonMail, custom IMAP)
 - **App Passwords** -- no OAuth2 setup required for most providers; clone and run in 1 minute
-- **7 composite tools** with 20 actions -- search, read, send, reply, forward, organize, credential setup in single calls
+- **7 composite tools** with 21 actions -- search, read, send, reply, forward, organize, credential setup in single calls
 - **Auto-discovery** -- provider settings detected from email address, custom IMAP host supported
 - **Thread-aware** -- reply/forward maintains In-Reply-To and References headers
 - **Tiered token optimization** -- compressed descriptions + on-demand `help` tool + MCP Resources
@@ -97,7 +98,7 @@ mcp-name: io.github.n24q02m/better-email-mcp
 Full docs at **[mcp.n24q02m.com/servers/better-email-mcp/setup/](https://mcp.n24q02m.com/servers/better-email-mcp/setup/)**:
 
 - [Setup](https://mcp.n24q02m.com/servers/better-email-mcp/setup/) -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
-- [Modes overview](https://mcp.n24q02m.com/get-started/modes-overview/) -- stdio / local-relay / remote-relay / remote-oauth
+- [Modes overview](https://mcp.n24q02m.com/get-started/modes-overview/) -- stdio (default) and HTTP (opt-in, multi-user with OAuth 2.1)
 - [Multi-user setup](https://mcp.n24q02m.com/get-started/multi-user/) -- per-JWT-sub credential model
 
 **Install with AI agent** -- paste this to your AI coding agent:
@@ -165,11 +166,29 @@ Single multi-user mode (relay form for App-Password providers + bundled Outlook
 docker run -p 8080:8080 \
   -e PORT=8080 \
   -e PUBLIC_URL=https://your-domain.com \
-  -e CREDENTIAL_SECRET=$(openssl rand -hex 32) \
   n24q02m/better-email-mcp:latest
 ```
 
-Users provide their own email credentials through the OAuth flow / paste form. No server-side `EMAIL_CREDENTIALS` needed. Outlook OAuth uses the bundled public Azure client (`d56f8c71-9f7c-43f4-9934-be29cb6e77b0`, Thunderbird-pattern) -- no user-side Azure app registration needed.
+Users provide their own email credentials through the OAuth flow / paste form. No server-side `EMAIL_CREDENTIALS` needed. With the default Docker self-host, per-user credentials are held in an in-memory store (cleared on restart); users re-submit after a restart. Outlook OAuth uses the bundled public Azure client (`d56f8c71-9f7c-43f4-9934-be29cb6e77b0`, Thunderbird-pattern) -- no user-side Azure app registration needed.
+
+### Cloudflare serverless mode (KV-only)
+
+Deploy a per-user serverless instance at `https://email.n24q02m.com`: each JWT `sub`
+gets its own Container Durable Object, and all credentials AND Outlook OAuth tokens are
+AES-256-GCM encrypted into Workers KV (one `subs/<sub>/config` blob per user) so they
+**survive scale-to-zero / container recreate with no re-auth**. The JWT signing key is
+derived deterministically from `CREDENTIAL_SECRET` (EdDSA), so the user's identity is
+stable across recreate. Required secrets: `CREDENTIAL_SECRET` (per-sub vault + EdDSA),
+`MCP_RELAY_PASSWORD` (form gate), `MCP_DCR_SERVER_SECRET` (intentional multi-user
+deploy). See `wrangler.jsonc`.
+
+> Keying Outlook tokens by JWT `sub` (in the per-sub KV blob) resolves the former
+> email-keyed `tokens.json` ambiguity (CLAUDE.md Known Bug #4): two users' Outlook
+> accounts can no longer collide.
+
+> Caveat: `localhost` IMAP accounts (`email:pass:localhost:1993`) are valid for
+> local / VM deployments but CANNOT work on Cloudflare — there is no co-located IMAP
+> proxy inside the container. Use a publicly-reachable IMAP host on CF.
 
 ## Outlook OAuth Device Code (HTTP mode)
 
@@ -178,7 +197,7 @@ In HTTP mode, Outlook/Hotmail/Live accounts use OAuth2 device-code automatically
 1. The server prints a device code and a Microsoft login URL
 2. Open the URL in a browser and enter the code
 3. Sign in and authorize the app
-4. Tokens are persisted per JWT sub (`tokens/<sub>.json`)
+4. Tokens are persisted per JWT sub — in the encrypted Cloudflare KV credential blob (`subs/<sub>/config`) on the serverless deploy, or in `~/.better-email-mcp/tokens.json` for single-user / stdio
 
 OAuth uses the bundled public Azure client (`d56f8c71-9f7c-43f4-9934-be29cb6e77b0`, Thunderbird-pattern) -- no user-side Azure registration needed.
 
@@ -192,7 +211,6 @@ In **stdio mode**, Outlook accounts use an **App Password** instead (Outlook Acc
 | `EMAIL_USER` | Alternative (stdio, single-account) | - | Email address. Used with `EMAIL_APP_PASSWORD` as a per-field alternative to `EMAIL_CREDENTIALS`; merged into `EMAIL_CREDENTIALS` at boot |
 | `EMAIL_APP_PASSWORD` | Alternative (stdio, single-account) | - | App password (Gmail/Yahoo/iCloud) or Outlook App Password; used with `EMAIL_USER` |
 | `PUBLIC_URL` | No (http) | - | Server's public URL for relay / OAuth redirect links |
-| `CREDENTIAL_SECRET` | No (http) | auto-generated | Secret used to encrypt the per-user credential store; if unset, a random 32-byte secret is generated and persisted to a 0600 file |
 | `PORT` | No | `0` (OS-assigned) | Server port (http mode); set explicitly (e.g. `8080`) to bind a fixed port |
 | `HOST` | No | - | Bind address (http mode) |
 | `MCP_AUTH_DISABLE` | No (http) | - | Set to `1` to skip Bearer JWT verification when behind an external auth gateway |
@@ -267,9 +285,9 @@ This plugin implements **TC-NearZK** (in-memory, ephemeral). See the [mcp-core t
 
 | Mode | Storage | Encryption | Who can read your data? |
 |---|---|---|---|
-| HTTP n24q02m-hosted (default) | In-memory `Map<sub, OAuthToken>` | In-process only | Server process (cleared on restart) |
+| HTTP remote (hosted) | In-memory `Map<sub, OAuthToken>` | In-process only | Server process (cleared on restart) |
 | HTTP self-host | Same as hosted | Same | Only you (admin = user) |
-| stdio proxy | `~/.better-email-mcp/config.json` | AES-GCM, machine-bound key | Only your OS user (file perm 0600) |
+| stdio | platformdirs `mcp` config dir (`config.enc`; e.g. `%APPDATA%\mcp\Config\config.enc` on Windows) | AES-GCM, machine-bound key | Only your OS user (file perm 0600) |
 
 ## License