@aidalinfo/email-mcp 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# @aidalinfo/email-mcp
+
+MCP server that lets an agent **send email** through **Scaleway Transactional Email (TEM)**, from
+**one fixed sender** (e.g. `noreply@pulsemyit.fr`) to an **allowlist of recipients** only.
+
+```text
+Agent Pulse / Claude
+        │  MCP (stdio)
+        ▼
+@aidalinfo/email-mcp ── allowlist ── preview → human approval → confirm ── quota ── audit (JSON lines)
+        │  X-Auth-Token (dedicated IAM application)
+        ▼
+Scaleway TEM  POST /transactional-email/v1alpha1/regions/{region}/emails
+```
+
+Guarantees, all enforced server-side:
+
+- **The sender is configuration, not an argument.** `EMAIL_FROM` / `EMAIL_FROM_NAME` / `EMAIL_REPLY_TO`
+  come from the environment; no tool parameter can change them.
+- **Allowlisted recipients only.** `EMAIL_ALLOWED_RECIPIENTS` lists exact addresses and whole
+  domains (`@pulsemyit.fr` — not its subdomains). No wildcard. Empty → the server refuses to start.
+  A single recipient outside the list (in `to` or `cc`) refuses the whole email. There is **no bcc**.
+- **Two steps.** Without `confirmToken`, `email_send` only **previews**: full headers, full text
+  body, HTML source, message digest — nothing is sent. The token it returns is an HMAC bound to the
+  **exact message** (sender, recipients, subject, bodies) and to the sender domain's state, valid
+  5 minutes, **single use** (a replayed token never sends twice), and only for this process.
+- **Sender domain checked** before every preview and every send: it must exist in the configured
+  project and be `checked` (SPF + DKIM verified).
+- **Limits:** recipients per email (`EMAIL_MAX_RECIPIENTS`, default 10, hard cap 50) and sends per
+  sliding hour (`EMAIL_MAX_PER_HOUR`, default 20, hard cap 500), per process.
+- **Kill switch:** when `EMAIL_KILL_SWITCH_FILE` exists, every send is refused at once — checked
+  at the preview and again right before sending.
+- **Audit:** one JSON line per preview / send / refusal / failure on stderr (and `EMAIL_AUDIT_LOG_FILE`):
+  sender, recipients, subject, message digest, TEM email ids, error code, Pulse approval id.
+  **Bodies are never logged** — the digest ties an entry to its preview.
+- **No raw API tool, no attachments, no custom headers**: the server can make exactly three
+  Scaleway calls (find the sender domain, create an email, read an email).
+- **Header injection:** bare addresses only (no display names), subjects with line breaks or
+  control characters are refused.
+
+## Tools
+
+| Tool | What |
+|---|---|
+| `email_config` | Sender, Reply-To, sender domain status, allowed recipients, limits, quota left this hour, kill switch. **Start here.** |
+| `email_send` | `to[]`, `cc[]?`, `subject`, `text` (required), `html?`, `approvalId?`, `confirmToken?`. Preview, then send with the token. |
+| `email_status` | Delivery status of an email **sent by this sender** (TEM id from `email_send`): `new`, `sending`, `sent`, `failed`, `canceled`, with the last attempts. Other emails of the project (e.g. an application's) are reported `not_found`. |
+
+### The two-step protocol
+
+1. `email_send({ to, subject, text })` → preview + `confirmToken`. **Nothing is sent.**
+2. Show the preview to the human (in Pulse Chat) and wait for an explicit approval.
+3. `email_send({ to, subject, text, confirmToken, approvalId })` with the **same arguments** → sent.
+   Any change (one more recipient, a reworded sentence) → `confirmation_invalid`: preview again.
+
+The token proves the message is the one previewed; it does **not** prove a human approved it
+(the agent holds the token). The human approval is Pulse's own gate — `approvalId` is recorded
+in the audit trail for correlation (`verified: false`), it is not an authorisation.
+
+### Error codes
+
+`invalid_request` · `recipient_not_allowed` · `domain_not_ready` · `rate_limited` · `refused`
+(kill switch) · `confirmation_invalid` · `permission_missing` (API key lacks TEM rights) ·
+`not_found` · `transient` · **`unknown_outcome`** — the send request was cut off (timeout, network,
+5xx): the email **may have left**. The token is consumed and the quota slot kept; check
+`email_status` or the TEM console before sending again — never retry blindly.
+
+## Scaleway setup
+
+1. **Domain:** Scaleway console → Transactional Email → add `pulsemyit.fr` in the chosen project
+   and region, publish the SPF, DKIM (and MX/DMARC recommended) records, wait for status
+   **`checked`**. `email_config` (or `list_tem_domains` of `@aidalinfo/scaleway-mcp`) shows it.
+2. **Identity:** IAM → create a **dedicated application** (e.g. `email-mcp`), a policy granting it
+   Transactional Email permissions **scoped to that project only**, and an API key for it. Do not
+   reuse a personal key or the key of another MCP.
+3. **Allowlist:** start narrow (`@pulsemyit.fr,@aidalinfo.fr`), add external addresses one by one.
+
+## Configuration
+
+See [`.env.example`](.env.example). Every missing or ambiguous setting stops the server at
+startup (fail-closed) instead of guessing.
+
+| Variable | Required | Default | |
+|---|---|---|---|
+| `SCW_SECRET_KEY` | yes | | Secret key of the dedicated IAM application |
+| `EMAIL_PROJECT_ID` | yes | `SCW_DEFAULT_PROJECT_ID` | Project of the TEM domain |
+| `EMAIL_REGION` | | `fr-par` | `fr-par`, `nl-ams`, `pl-waw` |
+| `EMAIL_FROM` | yes | | Bare address, e.g. `noreply@pulsemyit.fr` |
+| `EMAIL_FROM_NAME` | | | Display name, e.g. `Pulse myIT` |
+| `EMAIL_REPLY_TO` | | | Fixed Reply-To (sent as an additional header) |
+| `EMAIL_ALLOWED_RECIPIENTS` | yes | | `a@x.fr,@domain.fr` — no wildcard |
+| `EMAIL_MAX_RECIPIENTS` | | 10 | to + cc, hard cap 50 |
+| `EMAIL_MAX_PER_HOUR` | | 20 | sliding hour, per process, hard cap 500 |
+| `EMAIL_KILL_SWITCH_FILE` | | | `touch` it to stop all sends |
+| `EMAIL_AUDIT_LOG_FILE` | | | JSON lines, mode 600 |
+
+## Register in Claude Code
+
+```bash
+claude mcp add email --scope user \
+  -e SCW_SECRET_KEY=... \
+  -e EMAIL_PROJECT_ID=<project-uuid> \
+  -e EMAIL_FROM=noreply@pulsemyit.fr -e EMAIL_FROM_NAME="Pulse myIT" \
+  -e EMAIL_ALLOWED_RECIPIENTS=@pulsemyit.fr,@aidalinfo.fr \
+  -e EMAIL_KILL_SWITCH_FILE=$HOME/.email-mcp.stop \
+  -- npx -y @aidalinfo/email-mcp
+```
+
+Emergency stop, no restart needed:
+
+```bash
+touch ~/.email-mcp.stop
+```
+
+## Development
+
+```bash
+npm install                      # at the repo root (npm workspaces)
+npm test -w @aidalinfo/email-mcp # tsc + jest (TEM is faked, nothing is sent)
+npm run build -w @aidalinfo/email-mcp
+node packages/email-mcp/smoke.mjs  # starts the server over stdio and lists its tools; SMOKE_CALL_CONFIG=1 also calls email_config
+```
+
+`smoke.mjs` never sends anything. To test a real send, register the server with an allowlist
+holding only your own address and go through the preview → confirm flow.

package/dist/audit.js

@@ -0,0 +1,67 @@
+import { appendFileSync } from "node:fs";
+/**
+ * One JSON object per line on stderr (stdout is the MCP transport) and, optionally, appended to
+ * EMAIL_AUDIT_LOG_FILE. Bodies are never logged: the digest is enough to match an entry to its preview.
+ */
+export class AuditLogger {
+    file;
+    sink;
+    now;
+    entries = [];
+    constructor(file, sink = (l) => process.stderr.write(`${l}\n`), now = () => new Date()) {
+        this.file = file;
+        this.sink = sink;
+        this.now = now;
+    }
+    log(e) {
+        const { approvalId, ...rest } = e;
+        const entry = {
+            timestamp: this.now().toISOString(),
+            ...rest,
+            approvalRef: approvalId ? { id: approvalId, verified: false } : undefined,
+        };
+        const line = JSON.stringify(entry);
+        this.sink(line);
+        if (this.file) {
+            try {
+                appendFileSync(this.file, `${line}\n`, { mode: 0o600 });
+            }
+            catch (err) {
+                process.stderr.write(`⚠ audit log file not writable (${err.code ?? "error"}) — entry kept on stderr only\n`);
+            }
+        }
+        this.entries.push(entry);
+        if (this.entries.length > 200)
+            this.entries.shift();
+        return entry;
+    }
+}
+/** Sliding one-hour window of sends, per process. */
+export class RateLimiter {
+    maxPerHour;
+    now;
+    sends = [];
+    constructor(maxPerHour, now = Date.now) {
+        this.maxPerHour = maxPerHour;
+        this.now = now;
+    }
+    prune() {
+        const floor = this.now() - 3_600_000;
+        while (this.sends.length && this.sends[0] <= floor)
+            this.sends.shift();
+    }
+    remaining() {
+        this.prune();
+        return Math.max(0, this.maxPerHour - this.sends.length);
+    }
+    /** Takes a slot; returns a function giving it back (for a send that certainly did not leave). */
+    reserve() {
+        const t = this.now();
+        this.sends.push(t);
+        return () => {
+            const i = this.sends.lastIndexOf(t);
+            if (i >= 0)
+                this.sends.splice(i, 1);
+        };
+    }
+}

package/dist/config.js

@@ -0,0 +1,102 @@
+export const REGIONS = ["fr-par", "nl-ams", "pl-waw"];
+export const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const DOMAIN = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+";
+const DOMAIN_RE = new RegExp(`^${DOMAIN}$`, "i");
+/** Bare address only: no display name, no comment, no quoted local part. */
+const ADDRESS_RE = new RegExp(`^[a-z0-9.!#$%&'*+/=?^_\`{|}~-]{1,64}@${DOMAIN}$`, "i");
+/** Lower-cased address, or null when it is not a plain, sane address. */
+export function normalizeAddress(raw) {
+    const a = raw.trim().toLowerCase();
+    if (a.length > 254 || !ADDRESS_RE.test(a))
+        return null;
+    const local = a.slice(0, a.indexOf("@"));
+    if (local.startsWith(".") || local.endsWith(".") || local.includes(".."))
+        return null;
+    return a;
+}
+export const domainOf = (address) => address.slice(address.lastIndexOf("@") + 1);
+export function isAllowed(list, address) {
+    return list.addresses.has(address) || list.domains.has(domainOf(address));
+}
+export const DEFAULT_MAX_RECIPIENTS = 10;
+export const HARD_MAX_RECIPIENTS = 50;
+export const DEFAULT_MAX_PER_HOUR = 20;
+export const HARD_MAX_PER_HOUR = 500;
+const get = (env, k) => env[k]?.trim() || undefined;
+function intIn(raw, name, def, max, warnings) {
+    if (raw === undefined)
+        return def;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n < 1)
+        throw new Error(`${name} must be a positive integer (got "${raw}")`);
+    if (n > max) {
+        warnings.push(`⚠ ${name}=${n} is above the hard limit — capped to ${max}`);
+        return max;
+    }
+    return n;
+}
+/**
+ * Fail-closed: any missing or ambiguous setting stops the server at startup instead of
+ * guessing. The sender and the allowlist come from here only — no tool argument can change them.
+ */
+export function loadConfig(env) {
+    const warnings = [];
+    const secretKey = get(env, "SCW_SECRET_KEY");
+    if (!secretKey)
+        throw new Error("Missing required env var: SCW_SECRET_KEY");
+    const projectId = get(env, "EMAIL_PROJECT_ID") ?? get(env, "SCW_DEFAULT_PROJECT_ID");
+    if (!projectId)
+        throw new Error("Missing required env var: EMAIL_PROJECT_ID (Scaleway project holding the TEM domain)");
+    if (!UUID_RE.test(projectId))
+        throw new Error(`EMAIL_PROJECT_ID is not a Scaleway project id: "${projectId}"`);
+    const region = (get(env, "EMAIL_REGION") ?? "fr-par");
+    if (!REGIONS.includes(region))
+        throw new Error(`EMAIL_REGION must be one of ${REGIONS.join(", ")} (got "${region}")`);
+    const fromRaw = get(env, "EMAIL_FROM");
+    if (!fromRaw)
+        throw new Error("Missing required env var: EMAIL_FROM (e.g. noreply@pulsemyit.fr)");
+    const fromEmail = normalizeAddress(fromRaw);
+    if (!fromEmail)
+        throw new Error(`EMAIL_FROM is not a plain email address: "${fromRaw}" (put the display name in EMAIL_FROM_NAME)`);
+    const fromName = get(env, "EMAIL_FROM_NAME");
+    if (fromName && (fromName.length > 100 || /[\u0000-\u001f\u007f"<>]/.test(fromName))) {
+        throw new Error("EMAIL_FROM_NAME must be ≤ 100 characters without control characters, quotes or angle brackets");
+    }
+    const replyToRaw = get(env, "EMAIL_REPLY_TO");
+    const replyTo = replyToRaw ? normalizeAddress(replyToRaw) : undefined;
+    if (replyToRaw && !replyTo)
+        throw new Error(`EMAIL_REPLY_TO is not a plain email address: "${replyToRaw}"`);
+    const addresses = new Set();
+    const domains = new Set();
+    for (const entry of (get(env, "EMAIL_ALLOWED_RECIPIENTS") ?? "").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean)) {
+        if (entry.includes("*"))
+            throw new Error(`EMAIL_ALLOWED_RECIPIENTS: wildcards are not supported ("${entry}") — list addresses or @domains`);
+        if (entry.startsWith("@")) {
+            if (!DOMAIN_RE.test(entry.slice(1)))
+                throw new Error(`EMAIL_ALLOWED_RECIPIENTS: invalid domain "${entry}"`);
+            domains.add(entry.slice(1));
+        }
+        else {
+            const a = normalizeAddress(entry);
+            if (!a)
+                throw new Error(`EMAIL_ALLOWED_RECIPIENTS: invalid address "${entry}"`);
+            addresses.add(a);
+        }
+    }
+    if (!addresses.size && !domains.size) {
+        throw new Error("EMAIL_ALLOWED_RECIPIENTS is empty — list the addresses and/or @domains the agent may write to");
+    }
+    return {
+        secretKey,
+        projectId: projectId.toLowerCase(),
+        region,
+        from: { email: fromEmail, name: fromName },
+        replyTo: replyTo ?? undefined,
+        allowlist: { addresses, domains },
+        maxRecipients: intIn(get(env, "EMAIL_MAX_RECIPIENTS"), "EMAIL_MAX_RECIPIENTS", DEFAULT_MAX_RECIPIENTS, HARD_MAX_RECIPIENTS, warnings),
+        maxPerHour: intIn(get(env, "EMAIL_MAX_PER_HOUR"), "EMAIL_MAX_PER_HOUR", DEFAULT_MAX_PER_HOUR, HARD_MAX_PER_HOUR, warnings),
+        killSwitchFile: get(env, "EMAIL_KILL_SWITCH_FILE"),
+        auditFile: get(env, "EMAIL_AUDIT_LOG_FILE"),
+        warnings,
+    };
+}

package/dist/confirm.js

@@ -0,0 +1,71 @@
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { EmailError } from "./errors.js";
+export const CONFIRM_TTL_MS = 5 * 60_000;
+/** JSON with sorted keys, so the same message always hashes the same. */
+export function stableStringify(v) {
+    if (Array.isArray(v))
+        return `[${v.map(stableStringify).join(",")}]`;
+    if (v && typeof v === "object") {
+        return `{${Object.keys(v)
+            .sort()
+            .filter((k) => v[k] !== undefined)
+            .map((k) => `${JSON.stringify(k)}:${stableStringify(v[k])}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(v ?? null);
+}
+export const digest = (v) => createHash("sha256").update(stableStringify(v)).digest("base64url");
+/**
+ * Two-step confirmation tokens, same scheme as @aidalinfo/m365-mcp: the preview issues a short-lived
+ * HMAC token (per-process random key) bound to the tool, the sender state and the full message;
+ * the send must present it with the same arguments. Single use — a replayed token never sends twice.
+ */
+export class Confirmations {
+    now;
+    key;
+    used = new Map();
+    constructor(now = Date.now, key) {
+        this.now = now;
+        this.key = key ?? randomBytes(32);
+    }
+    issue(b) {
+        const exp = this.now() + CONFIRM_TTL_MS;
+        const nonce = randomBytes(6).toString("base64url");
+        const token = `c1.${exp.toString(36)}.${nonce}.${this.mac(b, exp, nonce)}`;
+        return { token, expiresAt: new Date(exp).toISOString() };
+    }
+    /** Throws `confirmation_invalid` unless the token was issued for exactly this binding and is still valid. */
+    verify(token, b) {
+        const m = /^c1\.([0-9a-z]+)\.([\w-]+)\.([\w-]+)$/.exec(token);
+        if (!m)
+            throw new EmailError("confirmation_invalid", "confirmation_invalid: malformed confirmation token");
+        const exp = parseInt(m[1], 36);
+        // one canonical spelling only: "0abc" and "abc" decode to the same expiry and must not be two tokens
+        if (!Number.isSafeInteger(exp) || exp.toString(36) !== m[1]) {
+            throw new EmailError("confirmation_invalid", "confirmation_invalid: malformed confirmation token");
+        }
+        const expected = Buffer.from(this.mac(b, exp, m[2]));
+        const given = Buffer.from(m[3]);
+        if (expected.length !== given.length || !timingSafeEqual(expected, given)) {
+            throw new EmailError("confirmation_invalid", "confirmation_invalid: the message, its recipients or the sender state differ from the preview — run the preview again");
+        }
+        if (this.now() > exp)
+            throw new EmailError("confirmation_invalid", "confirmation_invalid: the confirmation token expired — run the preview again");
+        // replay protection keyed by the MAC (unique per issued token), not by the string received
+        if (this.used.has(m[3]))
+            throw new EmailError("confirmation_invalid", "confirmation_invalid: this confirmation token was already used");
+        this.gc();
+        this.used.set(m[3], exp);
+    }
+    mac(b, exp, nonce) {
+        return createHmac("sha256", this.key)
+            .update(stableStringify({ tool: b.tool, state: digest(b.state), plan: digest(b.plan), exp, nonce }))
+            .digest("base64url");
+    }
+    gc() {
+        const now = this.now();
+        for (const [t, exp] of this.used)
+            if (exp < now)
+                this.used.delete(t);
+    }
+}

package/dist/errors.js

@@ -0,0 +1,19 @@
+export class EmailError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = "EmailError";
+    }
+}
+export function toEmailError(err) {
+    if (err instanceof EmailError)
+        return err;
+    return new EmailError("unexpected", `unexpected: ${err instanceof Error ? err.message : String(err)}`);
+}
+export function errorResult(err) {
+    const e = toEmailError(err);
+    return { isError: true, content: [{ type: "text", text: e.message.startsWith(`${e.code}:`) ? e.message : `${e.code}: ${e.message}` }] };
+}

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { TemClient } from "./tem-client.js";
+import { createContext, registerTools, SERVER_INSTRUCTIONS } from "./tools.js";
+const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+// stdout is the MCP transport: everything human-readable goes to stderr.
+const log = (msg) => process.stderr.write(`${msg}\n`);
+try {
+    const config = loadConfig(process.env);
+    const ctx = createContext(config, new TemClient(config.secretKey, config.projectId, config.region));
+    const server = new McpServer({ name: "email", version: pkg.version }, { instructions: SERVER_INSTRUCTIONS });
+    registerTools(server, ctx);
+    for (const w of config.warnings)
+        log(w);
+    await server.connect(new StdioServerTransport());
+    const a = config.allowlist;
+    log(`email-mcp v${pkg.version} ready (sender: ${config.from.email}, TEM ${config.region} project ${config.projectId}, ` +
+        `allowlist: ${a.addresses.size} address(es) + ${a.domains.size} domain(s), ${config.maxRecipients} recipients/email, ${config.maxPerHour}/hour, ` +
+        `kill switch: ${config.killSwitchFile ?? "not configured"})`);
+}
+catch (err) {
+    log(`email-mcp: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+}

package/dist/tem-client.js

@@ -0,0 +1,76 @@
+import { EmailError } from "./errors.js";
+const API_BASE = "https://api.scaleway.com";
+export const TIMEOUT_MS = 30_000;
+export function redactSecret(text, secret) {
+    return (secret.length >= 8 ? text.split(secret).join("[REDACTED]") : text).replace(/(x-auth-token["']?\s*[:=]\s*["']?)[^"'\s,}]+/gi, "$1[REDACTED]");
+}
+function httpError(status, what, body) {
+    const detail = body.slice(0, 300);
+    if (status === 401 || status === 403) {
+        return new EmailError("permission_missing", `permission_missing: ${what} → ${status} — the API key needs Transactional Email permissions on the project (${detail})`, status);
+    }
+    if (status === 404)
+        return new EmailError("not_found", `not_found: ${what} → 404`, status);
+    if (status === 429 || status >= 500)
+        return new EmailError("transient", `transient: ${what} → ${status} — retry later (${detail})`, status);
+    return new EmailError("invalid_request", `invalid_request: ${what} → ${status}: ${detail}`, status);
+}
+export class TemClient {
+    secretKey;
+    projectId;
+    region;
+    fetchImpl;
+    constructor(secretKey, projectId, region, fetchImpl = fetch) {
+        this.secretKey = secretKey;
+        this.projectId = projectId;
+        this.region = region;
+        this.fetchImpl = fetchImpl;
+    }
+    get base() {
+        return `${API_BASE}/transactional-email/v1alpha1/regions/${this.region}`;
+    }
+    async call(method, url, what, body) {
+        let res;
+        try {
+            res = await this.fetchImpl(url, {
+                method,
+                headers: {
+                    "X-Auth-Token": this.secretKey,
+                    Accept: "application/json",
+                    ...(body ? { "Content-Type": "application/json" } : {}),
+                },
+                body: body ? JSON.stringify(body) : undefined,
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            const msg = redactSecret(err instanceof Error ? err.message : String(err), this.secretKey);
+            // a POST cut off in flight may have been accepted: never let the caller assume it was not
+            if (method === "POST") {
+                throw new EmailError("unknown_outcome", `unknown_outcome: ${what} was interrupted (${msg}) — the email may have been sent; check the TEM console before sending again`);
+            }
+            throw new EmailError("transient", `transient: ${what} failed (${msg})`);
+        }
+        const text = await res.text();
+        if (!res.ok) {
+            const e = httpError(res.status, what, redactSecret(text, this.secretKey));
+            if (method === "POST" && res.status >= 500) {
+                throw new EmailError("unknown_outcome", `unknown_outcome: ${what} → ${res.status} — the email may have been sent; check the TEM console before sending again`, res.status);
+            }
+            throw e;
+        }
+        return (text ? JSON.parse(text) : {});
+    }
+    async findDomain(name) {
+        const qs = new URLSearchParams({ project_id: this.projectId, name, page_size: "10" });
+        const res = await this.call("GET", `${this.base}/domains?${qs}`, "list TEM domains");
+        return (res.domains ?? []).find((d) => d.name.toLowerCase() === name && d.project_id === this.projectId) ?? null;
+    }
+    async createEmail(body) {
+        const res = await this.call("POST", `${this.base}/emails`, "send email", body);
+        return res.emails ?? [];
+    }
+    async getEmail(id) {
+        return this.call("GET", `${this.base}/emails/${encodeURIComponent(id)}`, "get email");
+    }
+}

package/dist/tools.js

@@ -0,0 +1,212 @@
+import { existsSync } from "node:fs";
+import { z } from "zod";
+import { domainOf, isAllowed, normalizeAddress, UUID_RE } from "./config.js";
+import { Confirmations, digest } from "./confirm.js";
+import { AuditLogger, RateLimiter } from "./audit.js";
+import { EmailError, errorResult, toEmailError } from "./errors.js";
+export const MAX_SUBJECT = 200;
+export const MAX_TEXT = 100_000;
+export const MAX_HTML = 200_000;
+/** Above this, the preview shows the start of the HTML only (the digest still covers all of it). */
+const PREVIEW_HTML = 20_000;
+export const SERVER_INSTRUCTIONS = "Sends email from ONE fixed sender (set by the operator, not by you) to an allowlist of recipients, through Scaleway Transactional Email. " +
+    "Call email_config first to see the sender, the allowed recipients and the remaining hourly quota. " +
+    "email_send works in two steps: without confirmToken it only previews (nothing is sent) and returns a token; show the preview to the human, " +
+    "and only after their explicit approval call email_send again with the SAME arguments plus confirmToken. Never confirm on your own initiative. " +
+    "Recipients outside the allowlist are refused — do not try to work around it.";
+export function createContext(config, tem) {
+    return {
+        config,
+        tem,
+        confirmations: new Confirmations(),
+        audit: new AuditLogger(config.auditFile),
+        limiter: new RateLimiter(config.maxPerHour),
+        killSwitchActive: () => !!config.killSwitchFile && existsSync(config.killSwitchFile),
+    };
+}
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const json = (v) => "```json\n" + JSON.stringify(v, null, 2) + "\n```";
+const fence = (s) => {
+    const ticks = "`".repeat(Math.max(3, ...[...s.matchAll(/`+/g)].map((m) => m[0].length + 1)));
+    return `${ticks}\n${s}\n${ticks}`;
+};
+/** Validates the arguments into the exact message that will be sent. Throws on any guard. */
+export function buildMessage(config, a) {
+    const seen = new Set();
+    const norm = (list, field) => list.map((raw) => {
+        const addr = normalizeAddress(raw);
+        if (!addr)
+            throw new EmailError("invalid_request", `invalid_request: ${field} contains an invalid address "${raw.slice(0, 100)}" (bare addresses only, no display name)`);
+        if (seen.has(addr))
+            throw new EmailError("invalid_request", `invalid_request: ${addr} appears more than once`);
+        seen.add(addr);
+        return addr;
+    });
+    const to = norm(a.to, "to");
+    const cc = norm(a.cc ?? [], "cc");
+    if (!to.length)
+        throw new EmailError("invalid_request", "invalid_request: at least one recipient in to");
+    if (seen.size > config.maxRecipients) {
+        throw new EmailError("invalid_request", `invalid_request: ${seen.size} recipients, the maximum is ${config.maxRecipients} (EMAIL_MAX_RECIPIENTS)`);
+    }
+    const denied = [...seen].filter((r) => !isAllowed(config.allowlist, r));
+    if (denied.length) {
+        throw new EmailError("recipient_not_allowed", `recipient_not_allowed: ${denied.join(", ")} not in EMAIL_ALLOWED_RECIPIENTS — nothing was sent`);
+    }
+    if (!a.subject.trim())
+        throw new EmailError("invalid_request", "invalid_request: empty subject");
+    // a line break in a header value is how header injection starts
+    if (/[\u0000-\u001f\u007f]/.test(a.subject))
+        throw new EmailError("invalid_request", "invalid_request: the subject must not contain line breaks or control characters");
+    if (!a.text.trim())
+        throw new EmailError("invalid_request", "invalid_request: empty text body (a plain-text version is always required)");
+    if (a.html !== undefined && !a.html.trim())
+        throw new EmailError("invalid_request", "invalid_request: html is empty — omit it instead");
+    return { from: config.from, replyTo: config.replyTo, to, cc, subject: a.subject, text: a.text, html: a.html };
+}
+function header(m) {
+    const from = m.from.name ? `${m.from.name} <${m.from.email}>` : m.from.email;
+    return [`From: ${from}`, m.replyTo ? `Reply-To: ${m.replyTo}` : "", `To: ${m.to.join(", ")}`, m.cc.length ? `Cc: ${m.cc.join(", ")}` : "", `Subject: ${m.subject}`]
+        .filter(Boolean)
+        .join("\n");
+}
+export async function sendEmail(ctx, a) {
+    const tool = "email_send";
+    const { config } = ctx;
+    const base = { tool, from: config.from.email, approvalId: a.approvalId };
+    let msg;
+    let messageDigest;
+    try {
+        if (ctx.killSwitchActive())
+            throw new EmailError("refused", `refused: sending is disabled by the kill switch (${config.killSwitchFile} exists)`);
+        msg = buildMessage(config, a);
+        messageDigest = digest(msg);
+        const domain = await ctx.tem.findDomain(domainOf(config.from.email));
+        if (!domain) {
+            throw new EmailError("domain_not_ready", `domain_not_ready: ${domainOf(config.from.email)} is not a TEM domain of project ${config.projectId} (${config.region})`);
+        }
+        if (domain.status !== "checked") {
+            throw new EmailError("domain_not_ready", `domain_not_ready: TEM domain ${domain.name} is "${domain.status}", it must be "checked" (SPF/DKIM verified) before sending`);
+        }
+        if (ctx.limiter.remaining() <= 0) {
+            throw new EmailError("rate_limited", `rate_limited: ${config.maxPerHour} emails already sent in the last hour (EMAIL_MAX_PER_HOUR)`);
+        }
+        const binding = { tool, state: { domainId: domain.id, status: domain.status }, plan: msg };
+        const who = { to: msg.to, cc: msg.cc.length ? msg.cc : undefined, subject: msg.subject, messageDigest };
+        if (!a.confirmToken) {
+            const { token, expiresAt } = ctx.confirmations.issue(binding);
+            ctx.audit.log({ ...base, ...who, result: "preview" });
+            const html = msg.html === undefined
+                ? ""
+                : `\n\nHTML body (${msg.html.length} characters${msg.html.length > PREVIEW_HTML ? `, first ${PREVIEW_HTML} shown` : ""}):\n${fence(msg.html.slice(0, PREVIEW_HTML))}`;
+            return text(`# Preview — ${tool} (nothing sent yet)\n\n${fence(header(msg))}\n\nText body:\n${fence(msg.text)}${html}\n\n` +
+                `Message digest: sha256:${messageDigest} · quota left this hour: ${ctx.limiter.remaining()}/${config.maxPerHour}\n\n` +
+                `Show this preview to the human. Only after their explicit approval, call ${tool} again with the same arguments and ` +
+                `confirmToken: "${token}" (valid until ${expiresAt}, single use).`);
+        }
+        ctx.confirmations.verify(a.confirmToken, binding);
+        // the switch may have been set while the human was reading the preview
+        if (ctx.killSwitchActive())
+            throw new EmailError("refused", `refused: sending is disabled by the kill switch (${config.killSwitchFile} exists)`);
+        const release = ctx.limiter.reserve();
+        let emails;
+        try {
+            emails = await ctx.tem.createEmail({
+                from: msg.from,
+                to: msg.to.map((email) => ({ email })),
+                cc: msg.cc.map((email) => ({ email })),
+                subject: msg.subject,
+                text: msg.text,
+                html: msg.html,
+                project_id: config.projectId,
+                additional_headers: msg.replyTo ? [{ key: "Reply-To", value: msg.replyTo }] : undefined,
+            });
+        }
+        catch (err) {
+            // a send that may have left keeps its quota slot
+            if (toEmailError(err).code !== "unknown_outcome")
+                release();
+            throw err;
+        }
+        const ids = emails.map((e) => e.id);
+        ctx.audit.log({ ...base, ...who, result: "sent", temEmailIds: ids });
+        return text(`# ${tool} — accepted by Scaleway TEM\n\n${fence(header(msg))}\n\n` +
+            json(emails.map((e) => ({ id: e.id, rcptTo: e.rcpt_to, rcptType: e.rcpt_type, status: e.status }))) +
+            `\n\nDelivery is asynchronous: check it with email_status. Quota left this hour: ${ctx.limiter.remaining()}/${config.maxPerHour}.`);
+    }
+    catch (err) {
+        const e = toEmailError(err);
+        const result = e.code === "unknown_outcome" ? "unknown_outcome" : ["invalid_request", "recipient_not_allowed", "domain_not_ready", "rate_limited", "refused", "confirmation_invalid"].includes(e.code) ? "refused" : "failed";
+        ctx.audit.log({ ...base, to: msg?.to, cc: msg?.cc.length ? msg.cc : undefined, subject: msg?.subject, messageDigest, result, errorCode: e.code });
+        return errorResult(e);
+    }
+}
+const addressOf = (s) => (/<([^>]+)>/.exec(s)?.[1] ?? s).trim().toLowerCase();
+export async function emailStatus(ctx, emailId) {
+    try {
+        if (!UUID_RE.test(emailId))
+            throw new EmailError("invalid_request", "invalid_request: emailId must be a TEM email id (UUID) as returned by email_send");
+        const e = await ctx.tem.getEmail(emailId.toLowerCase());
+        // only this server's own sends: the project may also carry other applications' mail
+        if (e.project_id !== ctx.config.projectId || addressOf(e.mail_from ?? "") !== ctx.config.from.email) {
+            throw new EmailError("not_found", "not_found: no email with this id was sent by this sender");
+        }
+        return text(json({
+            id: e.id,
+            status: e.status,
+            statusDetails: e.status_details || undefined,
+            rcptTo: e.rcpt_to,
+            rcptType: e.rcpt_type,
+            subject: e.subject,
+            createdAt: e.created_at,
+            updatedAt: e.updated_at,
+            tryCount: e.try_count,
+            lastTries: e.last_tries?.map((t) => ({ triedAt: t.tried_at, code: t.code, message: t.message })),
+        }));
+    }
+    catch (err) {
+        return errorResult(err);
+    }
+}
+export async function emailConfig(ctx) {
+    const c = ctx.config;
+    let domain;
+    try {
+        const d = await ctx.tem.findDomain(domainOf(c.from.email));
+        domain = d ? { name: d.name, status: d.status, readyToSend: d.status === "checked" } : { name: domainOf(c.from.email), status: "not found in project" };
+    }
+    catch (err) {
+        domain = { name: domainOf(c.from.email), error: toEmailError(err).message };
+    }
+    return text(json({
+        sender: c.from.name ? `${c.from.name} <${c.from.email}>` : c.from.email,
+        replyTo: c.replyTo,
+        domain,
+        provider: { name: "Scaleway Transactional Email", region: c.region, projectId: c.projectId },
+        allowedRecipients: { addresses: [...c.allowlist.addresses], domains: [...c.allowlist.domains].map((d) => `@${d}`) },
+        limits: { maxRecipientsPerEmail: c.maxRecipients, maxPerHour: c.maxPerHour, remainingThisHour: ctx.limiter.remaining(), subjectChars: MAX_SUBJECT, textChars: MAX_TEXT, htmlChars: MAX_HTML },
+        killSwitch: c.killSwitchFile ? { file: c.killSwitchFile, active: ctx.killSwitchActive() } : "not configured",
+    }));
+}
+const address = z.string().min(3).max(254);
+export function registerTools(server, ctx) {
+    server.tool("email_config", "Sender address, allowed recipients, per-email and hourly limits, sender domain status and kill switch. Start here.", {}, async () => emailConfig(ctx));
+    server.tool("email_send", `[SEND] Send an email from the fixed sender ${ctx.config.from.email} to allowlisted recipients. Two steps: call without confirmToken to preview (nothing is sent), show the preview to the human, then — only after their explicit approval — call again with the same arguments and the returned confirmToken.`, {
+        to: z.array(address).min(1).max(50).describe("Recipient addresses (bare addresses, each must be allowed by EMAIL_ALLOWED_RECIPIENTS)"),
+        cc: z.array(address).max(50).optional().describe("Carbon-copy addresses, same rules as to. There is no bcc."),
+        subject: z.string().min(1).max(MAX_SUBJECT),
+        text: z.string().min(1).max(MAX_TEXT).describe("Plain-text body (always required)"),
+        html: z.string().max(MAX_HTML).optional().describe("Optional HTML body; the plain-text body stays the fallback"),
+        confirmToken: z
+            .string()
+            .max(200)
+            .optional()
+            .describe("Omit for the preview. Then the token from the preview, with the SAME arguments, to send. Single use, valid 5 minutes."),
+        approvalId: z
+            .string()
+            .regex(/^[\w.:-]{1,128}$/)
+            .optional()
+            .describe("Pulse Chat approval id, recorded in the audit trail for correlation (not an authorisation)."),
+    }, async (args) => sendEmail(ctx, args));
+    server.tool("email_status", "Delivery status of an email sent by this server (TEM email id returned by email_send): new, sending, sent, failed, canceled, with the last delivery attempts.", { emailId: z.string().max(64).describe("TEM email id (UUID)") }, async ({ emailId }) => emailStatus(ctx, emailId));
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@aidalinfo/email-mcp",
+  "version": "0.1.0",
+  "description": "Outbound email MCP server over Scaleway Transactional Email (TEM) — fixed sender from config, recipient allowlist, two-step confirmed, rate-limited and audited sends",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "email-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Aidalinfo / Pulse myIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aidalinfo/cloud-mcp.git",
+    "directory": "packages/email-mcp"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "email",
+    "scaleway",
+    "transactional-email",
+    "tem",
+    "typescript"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "npm run build",
+    "start": "node dist/index.js",
+    "test": "tsc && tsc -p tsconfig.test.json && NODE_OPTIONS=--experimental-vm-modules jest",
+    "typecheck": "tsc -p tsconfig.test.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.3.0",
+    "@types/node": "^22.0.0",
+    "jest": "^30.3.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "^5.7.0"
+  }
+}