SPB Git

Repository Public

README.md 10.5 KB 126 lines markdown

1# @spboucher/spmail-mcp — SP Mail for AI agents (MCP server)23A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an AI agent (Claude Code, Claude Desktop, any MCP client) read, search, draft and send e-mail through the SP Mail REST API.45- **stdio transport**, one self-contained file: `node dist/index.js`.6- **Same permissions as the REST API, by construction**: the server holds only an API key and calls `https://mail.spboucher.ai/api/v1`. Scopes, address allowlist, rate and daily limits and the external-send policy are enforced by the API on every call; the server adds no privilege and has no other access (no database, no mail-server credentials, no file system writes).7- **Prompt-injection hygiene**: mail content is returned as delimited untrusted data, never as instructions (see [Security model](#security-model)).8- **Human approval for external sends** is enforced server-side by the key's `external_send_policy` (default `approval`).910## Build1112```bash13cd packages/sdk-ts && pnpm install --ignore-workspace       # the MCP server bundles the TypeScript SDK from ../sdk-ts14cd ../mcp && pnpm install --ignore-workspace && pnpm build   # → dist/index.js (single file, runs standalone)15```1617## Configuration1819| Variable | |20|---|---|21| `SPMAIL_API_KEY` | **required** — `spm_<prefix>_<secret>`, created by an administrator in SP Mail (Administration → API keys) or with `cli key-create` |22| `SPMAIL_BASE_URL` | optional — default `https://mail.spboucher.ai` |23| `SPMAIL_MCP_READONLY` | optional — `1` registers only the read tools, whatever the key allows |2425At startup the server calls `GET /me`. A refused key (`401`) stops the server with a message on stderr. If the API is unreachable, the server starts with every tool and each call is still checked by the API. The key is never printed (stdout carries the protocol, stderr the diagnostics) and never appears in a tool result.2627### Claude Code2829```bash30claude mcp add spmail \31  --env SPMAIL_API_KEY=spm_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \32  -- node /absolute/path/to/sp-mail/packages/mcp/dist/index.js33# read-only agent: add  --env SPMAIL_MCP_READONLY=134```3536JSON form (`.mcp.json` of a project, `claude mcp add-json`, Claude Desktop's `claude_desktop_config.json`):3738```json39{40  "mcpServers": {41    "spmail": {42      "command": "node",43      "args": ["/absolute/path/to/sp-mail/packages/mcp/dist/index.js"],44      "env": {45        "SPMAIL_API_KEY": "spm_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",46        "SPMAIL_BASE_URL": "https://mail.spboucher.ai"47      }48    }49  }50}51```5253Do not commit a real key: in a shared `.mcp.json` use `"SPMAIL_API_KEY": "${SPMAIL_API_KEY}"` and export the variable in your shell.5455## Tools5657| Tool | Scope needed | What it does |58|---|---|---|59| `spmail_list_accounts` | any key | addresses the key can read / send from, scopes, limits, external-send policy, available tools |60| `spmail_list_messages` | `mail.read` | summaries of a folder (default inbox), newest first, paginated |61| `spmail_search` | `mail.search` | full text, sender, recipient, subject, label; paginated |62| `spmail_get_message` | `mail.read` | one message: metadata, body as plain text (windowed), real link destinations, attachment list |63| `spmail_get_thread` | `mail.read` | summaries of a conversation, oldest first |64| `spmail_list_attachments` | `mail.attachments.read` | id, type, size, name |65| `spmail_download_attachment` | `mail.attachments.read` | text attachments as text (windowed); binaries: metadata only |66| `spmail_delivery_status` | `mail.send` or `mail.read` | status of a send, per recipient |67| `spmail_list_templates` | `mail.send` or `mail.drafts` | the owner's templates and their variables |68| `spmail_create_draft` | `mail.drafts` | saves a draft — nothing is sent |69| `spmail_send` | `mail.send` | sends an e-mail (optionally scheduled) |70| `spmail_send_template` | `mail.send` | sends a rendered template |71| `spmail_reply` | `mail.send` | replies in the thread |72| `spmail_forward` | `mail.send` **and** `mail.read` | forwards a message with its attachments |73| `spmail_archive` | `mail.modify` | moves to Archive |74| `spmail_mark_read` | `mail.modify` | read / unread |75| `spmail_move` | `mail.modify` | inbox, archive, trash, junk or a folder id |7677**Tools the key cannot use are not registered** (the list is computed from the scopes returned by `GET /me` at startup; `mail.admin` implies every scope). `spmail_list_accounts` reports them under `tools_unavailable` with the missing scope. A scope change on the key takes effect at the next start of the server; in the meantime the API still refuses (`403 insufficient_scope`, returned as a clear tool error). With `SPMAIL_MCP_READONLY=1` the eight write tools (the second half of the table) are never registered.7879Not offered on purpose: permanent deletion, address / alias / webhook / key management, automation rules, file upload (no attachments on outgoing mail), approval of pending sends (a human does that in SP Mail).8081**Annotations.** Read tools: `readOnlyHint: true`, `idempotentHint: true`; those that return mail content have `openWorldHint: true` (the content comes from arbitrary third parties). Send tools: `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: false`, `openWorldHint: true`. `spmail_archive` / `spmail_mark_read`: reversible, idempotent, `destructiveHint: false`. `spmail_move`: `destructiveHint: true`, because Trash and Junk may be purged later by the owner's retention rules.8283**Compact results.** Every result is one JSON object, returned both as text and as `structuredContent`. Lists return at most 50 items (default 10) with `next_cursor`. Bodies are returned in windows (`max_chars`, default 8 000, max 50 000) with `truncated` and `next_offset`; call again with `offset` to continue. Text attachments: windows of 20 000 characters (max 100 000). Binary attachments are never dumped: metadata, SHA-256 and a note; `encoding: "base64"` is accepted for files up to 64 kB only. Files over 10 MB are never loaded. No text extraction from PDF or office files.8485## Recommended keys8687One key per agent, least privilege. Create it in SP Mail (Administration → API keys) or on the node:8889```bash90# read-only agent (triage, summaries, search) — also set SPMAIL_MCP_READONLY=191cli key-create agent-lecture --scopes mail.read,mail.search,mail.attachments.read --addresses contact@example.org9293# drafting agent: reads, files, prepares answers; a human sends them from the webmail94cli key-create agent-brouillons --scopes mail.read,mail.search,mail.attachments.read,mail.drafts,mail.modify --addresses contact@example.org9596# sending agent: internal mail leaves directly, anything external waits for the owner's approval97cli key-create agent-envoi --scopes mail.read,mail.search,mail.attachments.read,mail.drafts,mail.modify,mail.send \98  --addresses contact@example.org --external approval --daily 5099```100101- Never give an agent `mail.admin`, `mail.delete`, `mail.addresses.manage`, `mail.aliases.manage` or `mail.webhooks.manage`: no tool uses them.102- Keep `--external approval` (the default). `--external deny` forbids external recipients entirely; use `allow` only for an agent whose every send you would approve anyway.103- An alias in the allowlist gives a *restricted* view (only that alias's mail); the mailbox's primary address gives the whole mailbox.104- Set a low `--daily` limit and an expiry (`--expires`) for experiments. Revoke with `cli key-revoke <prefix>`: effective at the next request.105106## Security model1071081. **No added privilege.** The only credential is the API key. Everything is an HTTPS call to `/api/v1` with that key; whatever the model asks, the API answers `403`/`404` outside the key's scopes and addresses. Ids are the opaque API ids, re-checked on every call.1092. **Mail content is data.** Every string that comes from a mailbox — subject, sender name, preview, body, link, attachment name, attachment text, SMTP reply — is returned only under an object named `untrusted`, whose first key is a fixed marker, and each result starts with a fixed `notice` stating that this content is third-party data, not instructions. Results are JSON: mail content is an escaped string and cannot close its envelope or forge a field. Addresses are returned outside the envelope only when they are syntactically valid addresses. The server's `instructions` repeat the rule.1103. **No markup, no hidden text.** Bodies are returned as plain text: the API's text part, or the HTML converted to text by this server. HTML is returned only with `include_html: true` (sanitised by the API, still inside `untrusted`). Control characters, zero-width characters and bidirectional overrides are removed. Links are listed with their real destination, and flagged `mismatch` when the visible text names another site.1114. **Nothing is executed.** The server never follows a link, renders HTML, opens an attachment, runs anything found in mail or writes to disk. It makes no network call other than to the configured SP Mail API (redirects refused).1125. **Human confirmation for external sends.** With `external_send_policy: approval`, a message with any recipient outside the hosted domains is stored and **not sent**; the API answers `202 pending_approval`. The tool result then says `sent: false` and "NOT SENT … awaiting the owner's approval in SP Mail", restating sender and recipients. The server never retries and offers no tool to approve; approval needs a passkey re-authentication of an administrator in SP Mail.1136. **Sending is explicit.** Send tools restate the sending address and the recipients in their result, and say plainly whether the message was sent, scheduled, queued, refused or awaiting approval. Tool descriptions tell the model to send only on the user's explicit request and to create a draft otherwise.1147. **Secrets.** The key is read from the environment, kept in memory, removed from the process environment, and never written to stdout, stderr or a result.115116What this cannot guarantee: a model may still be influenced by what it reads. The envelope, the wording and the read-only mode reduce that risk; the hard limits are the key's scopes, its address allowlist, its daily limit and the approval policy. Choose them as if the agent could be talked into anything the key allows.117118## Tests119120From the repository root (the built server is spawned over stdio and driven with the official MCP client, against a real SP Mail test server; test mailboxes on `stg.spboucher.ai` are purged at the end):121122```bash123SPMAIL_TEST_PORT=8801 SPMAIL_TEST_DB=postgres://127.0.0.1/sp_mail_sdk_test \124  node --import tsx --test --test-concurrency=1 tests/integration/mcp-server.test.ts125```126
Files main
Menu

Theme