hypermail-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mateo Tiedra
+
+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

@@ -0,0 +1,140 @@
+# hypermail-mcp
+
+A **Model Context Protocol** server that lets an agent operate any of the user's
+inboxes through a single, unified tool surface.
+
+The agent doesn't care whether an address is a work Outlook account, a personal
+Microsoft account, or (soon) a personal IMAP mailbox — it just calls
+`list_emails`, `search_emails`, `read_email`, `send_email` and passes the email
+address as the `account` argument. The server routes to the right backend.
+
+**v1 status:** Outlook / Microsoft 365 (personal + work) fully supported via
+Microsoft Graph. IMAP and Gmail are stubbed at the provider interface so they
+can be plugged in without touching tool definitions.
+
+## Why
+
+- Existing Outlook/M365 MCP servers (e.g. `@softeria/ms-365-mcp-server`) expose
+  ~200 raw Graph endpoints and are tied to a single signed-in user.
+- This project wraps the same proven stack (`@azure/msal-node` for auth,
+  `@microsoft/microsoft-graph-client` for HTTP) but exposes only a small,
+  provider-agnostic email API and supports **multiple accounts at once**, keyed
+  by email address.
+
+## Install / run
+
+```bash
+npm install -g hypermail-mcp     # or pnpm / npx
+hypermail-mcp --help
+```
+
+Run as a stdio MCP server (the default) — wire it into your MCP host:
+
+### Claude Desktop / Claude Code
+
+```jsonc
+{
+  "mcpServers": {
+    "hyper-email": {
+      "command": "npx",
+      "args": ["-y", "hypermail-mcp"]
+    }
+  }
+}
+```
+
+Or via the CLI:
+
+```bash
+claude mcp add hypermail -- npx -y hypermail-mcp
+```
+
+### As a hosted HTTP server
+
+```bash
+hypermail-mcp --http --port 3000 --host 0.0.0.0
+# endpoint: http://<host>:3000/mcp  (Streamable HTTP transport, session-aware)
+```
+
+When hosted you **must** set `HYPERMAIL_MCP_KEY` so the account file is
+reproducibly decryptable.
+
+## Configuration
+
+| Env var | Purpose | Default |
+| --- | --- | --- |
+| `HYPERMAIL_MCP_DATA_DIR` | Where to keep the encrypted accounts blob | `~/.hypermail-mcp` |
+| `HYPERMAIL_MCP_KEY` | 32-byte AES-256-GCM key (hex, base64, or any passphrase — derived via SHA-256). Required for hosted deployments. | auto-generated, stored via OS keychain (`keytar`) or a local `master.key` file |
+| `MS_CLIENT_ID` | Azure Entra public client (application) id used for device-code login | placeholder — **set your own for production** |
+| `MS_TENANT_ID` | Tenant for the authority URL | `common` |
+
+CLI flags: `--http`, `--port`, `--host`, `--data-dir`, `--read-only`, `--help`.
+
+## Tools
+
+All "email" tools take an `account` argument — the email address of the inbox
+to operate on. The server resolves the right provider from the encrypted
+account store.
+
+| Tool | Inputs | Notes |
+| --- | --- | --- |
+| `list_accounts` | — | Returns registered emails + provider, no secrets. |
+| `add_account` | `provider`, `email?`, `config?` | Starts device-code (Outlook). Returns `{handle, verification:{userCode, verificationUri, expiresAt}}`. |
+| `complete_add_account` | `provider`, `handle` | Returns `pending` / `ready` / `expired` / `error`. |
+| `remove_account` | `email` | Deletes tokens for the account. |
+| `list_emails` | `account`, `folder?`, `limit?`, `unreadOnly?` | Defaults: folder=`inbox`, limit=25. |
+| `search_emails` | `account`, `query`, `limit?` | KQL on Outlook. |
+| `read_email` | `account`, `id` | Returns full body + recipients + attachment metadata. |
+| `send_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `isHtml?` | Disabled under `--read-only`. |
+
+### Add-account flow (Outlook)
+
+1. Agent calls `add_account({ provider: "outlook" })`.
+2. Server returns:
+   ```json
+   {
+     "status": "pending",
+     "handle": "…uuid…",
+     "verification": {
+       "userCode": "ABCD-EFGH",
+       "verificationUri": "https://microsoft.com/devicelogin",
+       "expiresAt": "2025-…",
+       "message": "To sign in, use a web browser to open …"
+     }
+   }
+   ```
+3. The user opens the URL and enters the code.
+4. Agent polls `complete_add_account({ provider: "outlook", handle })` until
+   it returns `{ "status": "ready", "account": {...} }`.
+5. From then on, any tool can be called with `account: "<that-email>"`.
+
+## Roadmap
+
+- IMAP provider (interface already in place at `src/providers/imap/index.ts`)
+  — `imapflow` + `nodemailer`, password/app-password stored encrypted.
+- Gmail provider via Google OAuth.
+- Folder listing, attachment upload/download, mark-as-read.
+- Threading / conversations.
+
+## Project layout
+
+```
+src/
+  cli.ts                       # arg parsing + entry
+  server.ts                    # MCP server, stdio + HTTP transports
+  version.ts
+  store/account-store.ts       # encrypted multi-account store (AES-256-GCM)
+  providers/
+    types.ts                   # EmailProvider interface + shared DTOs
+    registry.ts                # routes account email → provider
+    outlook/
+      auth.ts                  # msal-node device-code flow
+      client.ts                # @microsoft/microsoft-graph-client factory
+      index.ts                 # OutlookProvider implementation
+    imap/index.ts              # stub
+  tools/index.ts               # MCP tool registrations
+```
+
+## License
+
+MIT