SPB Git

Repository Public

README.md 10.5 KB

# @spboucher/spmail-mcp — SP Mail for AI agents (MCP server)

A Model Context Protocol 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.

  • stdio transport, one self-contained file: node dist/index.js.
  • 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).
  • Prompt-injection hygiene: mail content is returned as delimited untrusted data, never as instructions (see Security model).
  • Human approval for external sends is enforced server-side by the key's external_send_policy (default approval).

# Build

bash
cd packages/sdk-ts && pnpm install --ignore-workspace       # the MCP server bundles the TypeScript SDK from ../sdk-ts
cd ../mcp && pnpm install --ignore-workspace && pnpm build   # → dist/index.js (single file, runs standalone)

# Configuration

Variable
SPMAIL_API_KEY required — spm_<prefix>_<secret>, created by an administrator in SP Mail (Administration → API keys) or with cli key-create
SPMAIL_BASE_URL optional — default https://mail.spboucher.ai
SPMAIL_MCP_READONLY optional — 1 registers only the read tools, whatever the key allows

At 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.

# Claude Code

bash
claude mcp add spmail \
  --env SPMAIL_API_KEY=spm_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -- node /absolute/path/to/sp-mail/packages/mcp/dist/index.js
# read-only agent: add  --env SPMAIL_MCP_READONLY=1

JSON form (.mcp.json of a project, claude mcp add-json, Claude Desktop's claude_desktop_config.json):

json
{
  "mcpServers": {
    "spmail": {
      "command": "node",
      "args": ["/absolute/path/to/sp-mail/packages/mcp/dist/index.js"],
      "env": {
        "SPMAIL_API_KEY": "spm_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "SPMAIL_BASE_URL": "https://mail.spboucher.ai"
      }
    }
  }
}

Do not commit a real key: in a shared .mcp.json use "SPMAIL_API_KEY": "${SPMAIL_API_KEY}" and export the variable in your shell.

# Tools

Tool Scope needed What it does
spmail_list_accounts any key addresses the key can read / send from, scopes, limits, external-send policy, available tools
spmail_list_messages mail.read summaries of a folder (default inbox), newest first, paginated
spmail_search mail.search full text, sender, recipient, subject, label; paginated
spmail_get_message mail.read one message: metadata, body as plain text (windowed), real link destinations, attachment list
spmail_get_thread mail.read summaries of a conversation, oldest first
spmail_list_attachments mail.attachments.read id, type, size, name
spmail_download_attachment mail.attachments.read text attachments as text (windowed); binaries: metadata only
spmail_delivery_status mail.send or mail.read status of a send, per recipient
spmail_list_templates mail.send or mail.drafts the owner's templates and their variables
spmail_create_draft mail.drafts saves a draft — nothing is sent
spmail_send mail.send sends an e-mail (optionally scheduled)
spmail_send_template mail.send sends a rendered template
spmail_reply mail.send replies in the thread
spmail_forward mail.send and mail.read forwards a message with its attachments
spmail_archive mail.modify moves to Archive
spmail_mark_read mail.modify read / unread
spmail_move mail.modify inbox, archive, trash, junk or a folder id

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.

Not 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).

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.

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.

One key per agent, least privilege. Create it in SP Mail (Administration → API keys) or on the node:

bash
# read-only agent (triage, summaries, search) — also set SPMAIL_MCP_READONLY=1
cli key-create agent-lecture --scopes mail.read,mail.search,mail.attachments.read --addresses contact@example.org

# drafting agent: reads, files, prepares answers; a human sends them from the webmail
cli key-create agent-brouillons --scopes mail.read,mail.search,mail.attachments.read,mail.drafts,mail.modify --addresses contact@example.org

# sending agent: internal mail leaves directly, anything external waits for the owner's approval
cli key-create agent-envoi --scopes mail.read,mail.search,mail.attachments.read,mail.drafts,mail.modify,mail.send \
  --addresses contact@example.org --external approval --daily 50
  • Never give an agent mail.admin, mail.delete, mail.addresses.manage, mail.aliases.manage or mail.webhooks.manage: no tool uses them.
  • Keep --external approval (the default). --external deny forbids external recipients entirely; use allow only for an agent whose every send you would approve anyway.
  • An alias in the allowlist gives a restricted view (only that alias's mail); the mailbox's primary address gives the whole mailbox.
  • Set a low --daily limit and an expiry (--expires) for experiments. Revoke with cli key-revoke <prefix>: effective at the next request.

# Security model

  1. 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.
  2. 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.
  3. 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.
  4. 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).
  5. 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.
  6. 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.
  7. 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.

What 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.

# Tests

From 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):

bash
SPMAIL_TEST_PORT=8801 SPMAIL_TEST_DB=postgres://127.0.0.1/sp_mail_sdk_test \
  node --import tsx --test --test-concurrency=1 tests/integration/mcp-server.test.ts
Files main
Menu

Theme