hypermail-mcp 0.1.0

package/dist/cli.js

@@ -0,0 +1,1101 @@
+#!/usr/bin/env node
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { randomUUID as randomUUID2 } from "crypto";
+import { createServer as createHttpServer } from "http";
+
+// src/store/account-store.ts
+import {
+  createCipheriv,
+  createDecipheriv,
+  randomBytes,
+  createHash
+} from "crypto";
+import { promises as fs } from "fs";
+import { homedir } from "os";
+import path from "path";
+var FILE_NAME = "accounts.json.enc";
+var ALGO = "aes-256-gcm";
+var KEY_LEN = 32;
+var AccountStore = class _AccountStore {
+  constructor(filePath, key, data) {
+    this.filePath = filePath;
+    this.key = key;
+    this.data = data;
+  }
+  filePath;
+  key;
+  data;
+  static async open(opts = {}) {
+    const dataDir = resolveDataDir(opts.dataDir);
+    await fs.mkdir(dataDir, { recursive: true, mode: 448 });
+    const filePath = path.join(dataDir, FILE_NAME);
+    const key = opts.key ?? await resolveKey(dataDir);
+    let data;
+    try {
+      const buf = await fs.readFile(filePath);
+      data = decrypt(buf, key);
+    } catch (err) {
+      if (err.code === "ENOENT") {
+        data = { version: 1, accounts: [] };
+      } else {
+        throw err;
+      }
+    }
+    return new _AccountStore(filePath, key, data);
+  }
+  listAccounts() {
+    return this.data.accounts.map((a) => ({ ...a }));
+  }
+  getAccount(email) {
+    const norm = email.trim().toLowerCase();
+    const rec = this.data.accounts.find((a) => a.email.toLowerCase() === norm);
+    return rec ? { ...rec } : void 0;
+  }
+  async upsertAccount(rec) {
+    const norm = rec.email.trim().toLowerCase();
+    const next = { ...rec, email: norm };
+    const idx = this.data.accounts.findIndex((a) => a.email.toLowerCase() === norm);
+    if (idx >= 0) this.data.accounts[idx] = next;
+    else this.data.accounts.push(next);
+    await this.flush();
+    return { ...next };
+  }
+  async removeAccount(email) {
+    const norm = email.trim().toLowerCase();
+    const before = this.data.accounts.length;
+    this.data.accounts = this.data.accounts.filter((a) => a.email.toLowerCase() !== norm);
+    if (this.data.accounts.length === before) return false;
+    await this.flush();
+    return true;
+  }
+  async flush() {
+    const buf = encrypt(this.data, this.key);
+    const tmp = `${this.filePath}.${process.pid}.${Date.now()}.tmp`;
+    await fs.writeFile(tmp, buf, { mode: 384 });
+    await fs.rename(tmp, this.filePath);
+  }
+};
+function encrypt(data, key) {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv(ALGO, key, iv);
+  const plaintext = Buffer.from(JSON.stringify(data), "utf8");
+  const ct = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([Buffer.from([1]), iv, tag, ct]);
+}
+function decrypt(buf, key) {
+  if (buf.length < 1 + 12 + 16 + 1) throw new Error("accounts file truncated");
+  const v = buf[0];
+  if (v !== 1) throw new Error(`unsupported accounts file version: ${v}`);
+  const iv = buf.subarray(1, 13);
+  const tag = buf.subarray(13, 29);
+  const ct = buf.subarray(29);
+  const decipher = createDecipheriv(ALGO, key, iv);
+  decipher.setAuthTag(tag);
+  const pt = Buffer.concat([decipher.update(ct), decipher.final()]);
+  const parsed = JSON.parse(pt.toString("utf8"));
+  if (parsed.version !== 1 || !Array.isArray(parsed.accounts)) {
+    throw new Error("accounts file is malformed");
+  }
+  return parsed;
+}
+function resolveDataDir(explicit) {
+  if (explicit && explicit.length > 0) return path.resolve(explicit);
+  const env = process.env.HYPERMAIL_MCP_DATA_DIR;
+  if (env && env.length > 0) return path.resolve(env);
+  return path.join(homedir(), ".hypermail-mcp");
+}
+function parseEnvKey(raw) {
+  const s = raw.trim();
+  if (/^[0-9a-fA-F]{64}$/.test(s)) return Buffer.from(s, "hex");
+  try {
+    const buf = Buffer.from(s, "base64");
+    if (buf.length === KEY_LEN) return buf;
+  } catch {
+  }
+  return createHash("sha256").update(s, "utf8").digest();
+}
+async function resolveKey(dataDir) {
+  const env = process.env.HYPERMAIL_MCP_KEY;
+  if (env && env.length > 0) {
+    const k = parseEnvKey(env);
+    if (k) return k;
+  }
+  const fromKeytar = await tryKeytarGet();
+  if (fromKeytar) return fromKeytar;
+  const keyFile = path.join(dataDir, "master.key");
+  try {
+    const existing = await fs.readFile(keyFile);
+    if (existing.length === KEY_LEN) return existing;
+  } catch {
+  }
+  const gen = randomBytes(KEY_LEN);
+  await fs.writeFile(keyFile, gen, { mode: 384 });
+  await tryKeytarSet(gen);
+  return gen;
+}
+async function tryKeytarGet() {
+  try {
+    const mod = await import("keytar");
+    const val = await mod.getPassword("hypermail-mcp", "master");
+    if (val) {
+      const buf = Buffer.from(val, "base64");
+      if (buf.length === KEY_LEN) return buf;
+    }
+  } catch {
+  }
+  return void 0;
+}
+async function tryKeytarSet(key) {
+  try {
+    const mod = await import("keytar");
+    await mod.setPassword("hypermail-mcp", "master", key.toString("base64"));
+  } catch {
+  }
+}
+
+// src/providers/outlook/index.ts
+import { randomUUID } from "crypto";
+import { writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join as pathJoin } from "path";
+import { ResponseType } from "@microsoft/microsoft-graph-client";
+
+// src/providers/outlook/client.ts
+import "isomorphic-fetch";
+import {
+  Client
+} from "@microsoft/microsoft-graph-client";
+
+// src/providers/outlook/auth.ts
+import {
+  PublicClientApplication
+} from "@azure/msal-node";
+var DEFAULT_CLIENT_ID = "084a3e9f-a9f4-43f7-89f9-d229cf97853e";
+var DEFAULT_SCOPES = [
+  "offline_access",
+  "User.Read",
+  "Mail.ReadWrite",
+  "Mail.Send"
+];
+function makeConfig(prevCacheJson) {
+  const clientId = process.env.MS_CLIENT_ID || DEFAULT_CLIENT_ID;
+  const tenant = process.env.MS_TENANT_ID || "common";
+  return {
+    auth: {
+      clientId,
+      authority: `https://login.microsoftonline.com/${tenant}`
+    },
+    cache: prevCacheJson ? {
+      // msal-node supports an in-memory cache plugin; we hydrate manually
+      // below via deserialize after construction.
+    } : void 0
+  };
+}
+function buildPca(prevCacheJson) {
+  const pca = new PublicClientApplication(makeConfig(prevCacheJson));
+  if (prevCacheJson) {
+    pca.getTokenCache().deserialize(prevCacheJson);
+  }
+  return pca;
+}
+function beginDeviceCode(scopes = DEFAULT_SCOPES) {
+  const pca = buildPca();
+  let resolve;
+  let reject;
+  const result = new Promise(
+    (res, rej) => {
+      resolve = res;
+      reject = rej;
+    }
+  );
+  let userCode = "";
+  let verificationUri = "";
+  let message = "";
+  let expiresAt = new Date(Date.now() + 15 * 6e4).toISOString();
+  let aborted = false;
+  const ready = new Promise((r) => {
+    pca.acquireTokenByDeviceCode({
+      scopes,
+      deviceCodeCallback: (info) => {
+        if (!info.userCode || !info.verificationUri) {
+          reject(
+            new Error(
+              "Microsoft device-code endpoint returned no code. Check MS_CLIENT_ID is a valid Azure Entra public-client application."
+            )
+          );
+          return;
+        }
+        userCode = info.userCode;
+        verificationUri = info.verificationUri;
+        message = info.message;
+        if (info.expiresIn) {
+          expiresAt = new Date(Date.now() + info.expiresIn * 1e3).toISOString();
+        }
+        r();
+      }
+    }).then((authResult) => {
+      if (aborted) return;
+      if (!authResult || !authResult.account) {
+        reject(new Error("device-code flow returned no account"));
+        return;
+      }
+      const cache = pca.getTokenCache().serialize();
+      const tokens = {
+        msalCache: cache,
+        homeAccountId: authResult.account.homeAccountId,
+        tenantId: authResult.account.tenantId,
+        username: authResult.account.username,
+        scopes
+      };
+      resolve({ tokens, account: authResult.account });
+    }).catch((err) => {
+      if (!aborted) reject(err);
+    });
+  });
+  return {
+    // these are placeholders until ready resolves
+    get userCode() {
+      return userCode;
+    },
+    get verificationUri() {
+      return verificationUri;
+    },
+    get message() {
+      return message;
+    },
+    get expiresAt() {
+      return expiresAt;
+    },
+    result,
+    cancel() {
+      aborted = true;
+    },
+    // hidden helper for the caller to await initial code
+    // (typed via a cast below where used)
+    ...{ _ready: ready }
+  };
+}
+async function awaitDeviceCodeReady(b) {
+  const r = b._ready;
+  await r;
+}
+async function acquireAccessToken(tokens, scopes = DEFAULT_SCOPES) {
+  const pca = buildPca(tokens.msalCache);
+  const cache = pca.getTokenCache();
+  const account = await cache.getAccountByHomeId(tokens.homeAccountId) ?? (await cache.getAllAccounts()).find((a) => a.username === tokens.username);
+  if (!account) {
+    throw new Error("no MSAL account in cache \u2014 re-run add_account");
+  }
+  const res = await pca.acquireTokenSilent({ account, scopes });
+  if (!res?.accessToken) {
+    throw new Error("acquireTokenSilent returned no access token");
+  }
+  const next = {
+    ...tokens,
+    msalCache: cache.serialize(),
+    scopes
+  };
+  return { accessToken: res.accessToken, tokens: next };
+}
+
+// src/providers/outlook/client.ts
+var OutlookClientFactory = class {
+  constructor(store) {
+    this.store = store;
+  }
+  store;
+  cache = /* @__PURE__ */ new Map();
+  get(account) {
+    const key = account.email.toLowerCase();
+    const existing = this.cache.get(key);
+    if (existing) return existing;
+    const store = this.store;
+    const provider = {
+      getAccessToken: async () => {
+        const fresh = store.getAccount(account.email) ?? account;
+        const tokens = fresh.tokens;
+        const { accessToken, tokens: nextTokens } = await acquireAccessToken(tokens);
+        if (nextTokens.msalCache !== tokens.msalCache) {
+          store.upsertAccount({
+            ...fresh,
+            tokens: nextTokens
+          }).catch(() => {
+          });
+        }
+        return accessToken;
+      }
+    };
+    const client = Client.initWithMiddleware({ authProvider: provider });
+    this.cache.set(key, client);
+    return client;
+  }
+  /** Drop a cached client (e.g. after removeAccount). */
+  invalidate(email) {
+    this.cache.delete(email.toLowerCase());
+  }
+};
+
+// src/providers/outlook/index.ts
+var OutlookProvider = class {
+  constructor(opts) {
+    this.opts = opts;
+    this.clients = new OutlookClientFactory(opts.store);
+  }
+  opts;
+  id = "outlook";
+  clients;
+  pending = /* @__PURE__ */ new Map();
+  // ---------- account lifecycle ----------
+  async addAccount(input) {
+    const begin = beginDeviceCode();
+    await awaitDeviceCodeReady(begin);
+    const handle = randomUUID();
+    const flow = {
+      begin,
+      emailHint: input.email,
+      startedAt: Date.now(),
+      settled: "pending"
+    };
+    this.pending.set(handle, flow);
+    begin.result.then(async ({ tokens, account }) => {
+      const email = (account.username || input.email || "").toLowerCase();
+      if (!email) {
+        flow.settled = "error";
+        flow.error = "no email returned from Microsoft account";
+        return;
+      }
+      const rec = {
+        email,
+        provider: "outlook",
+        displayName: account.name ?? void 0,
+        tokens,
+        addedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      const saved = await this.opts.store.upsertAccount(rec);
+      flow.account = saved;
+      flow.settled = "ready";
+    }).catch((err) => {
+      flow.settled = "error";
+      flow.error = err instanceof Error ? err.message : String(err);
+    });
+    return {
+      status: "pending",
+      handle,
+      verification: {
+        userCode: begin.userCode,
+        verificationUri: begin.verificationUri,
+        expiresAt: begin.expiresAt,
+        message: begin.message
+      }
+    };
+  }
+  async completeAddAccount(handle) {
+    const flow = this.pending.get(handle);
+    if (!flow) return { status: "error", error: "unknown handle" };
+    if (Date.now() - flow.startedAt > 20 * 6e4 && flow.settled === "pending") {
+      flow.settled = "expired";
+      flow.begin.cancel();
+    }
+    if (flow.settled === "ready" && flow.account) {
+      this.pending.delete(handle);
+      return { status: "ready", account: flow.account };
+    }
+    if (flow.settled === "error") {
+      this.pending.delete(handle);
+      return { status: "error", error: flow.error ?? "unknown error" };
+    }
+    if (flow.settled === "expired") {
+      this.pending.delete(handle);
+      return { status: "expired" };
+    }
+    return { status: "pending" };
+  }
+  // ---------- email ops ----------
+  async listEmails(account, opts) {
+    const client = this.clients.get(account);
+    const limit = clampLimit(opts.limit, 25, 100);
+    const folder = opts.folder ?? "inbox";
+    const filterParts = [];
+    if (opts.unreadOnly) filterParts.push("isRead eq false");
+    let req = client.api(`/me/mailFolders/${encodeURIComponent(folder)}/messages`).top(limit).select([
+      "id",
+      "subject",
+      "from",
+      "toRecipients",
+      "receivedDateTime",
+      "bodyPreview",
+      "isRead",
+      "hasAttachments"
+    ].join(",")).orderby("receivedDateTime DESC");
+    if (filterParts.length > 0) req = req.filter(filterParts.join(" and "));
+    const res = await req.get();
+    return res.value.map((m) => mapSummary(m, folder));
+  }
+  async searchEmails(account, query, opts) {
+    const client = this.clients.get(account);
+    const limit = clampLimit(opts.limit, 25, 100);
+    const res = await client.api("/me/messages").header("ConsistencyLevel", "eventual").top(limit).search(`"${query.replace(/"/g, '\\"')}"`).select(
+      [
+        "id",
+        "subject",
+        "from",
+        "toRecipients",
+        "receivedDateTime",
+        "bodyPreview",
+        "isRead",
+        "hasAttachments"
+      ].join(",")
+    ).get();
+    return res.value.map((m) => mapSummary(m));
+  }
+  async readEmail(account, id) {
+    const client = this.clients.get(account);
+    const m = await client.api(`/me/messages/${encodeURIComponent(id)}`).select(
+      [
+        "id",
+        "subject",
+        "from",
+        "toRecipients",
+        "ccRecipients",
+        "bccRecipients",
+        "receivedDateTime",
+        "bodyPreview",
+        "isRead",
+        "hasAttachments",
+        "body"
+      ].join(",")
+    ).get();
+    let attachments = void 0;
+    if (m.hasAttachments) {
+      try {
+        const attRes = await client.api(`/me/messages/${encodeURIComponent(id)}/attachments`).select("id,name,contentType,size").get();
+        attachments = attRes.value.map((a) => ({
+          id: a.id,
+          name: a.name,
+          contentType: a.contentType,
+          size: a.size
+        }));
+      } catch {
+      }
+    }
+    const summary = mapSummary(m);
+    const body = m.body;
+    return {
+      ...summary,
+      cc: (m.ccRecipients ?? []).map(mapRecipient),
+      bcc: (m.bccRecipients ?? []).map(mapRecipient),
+      bodyText: body?.contentType === "text" ? body.content : void 0,
+      bodyHtml: body?.contentType === "html" ? body.content : void 0,
+      attachments
+    };
+  }
+  async readAttachment(account, messageId, attachmentId) {
+    const client = this.clients.get(account);
+    const att = await client.api(`/me/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`).select("name,contentType").get();
+    const data = await client.api(`/me/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}/$value`).responseType(ResponseType.ARRAYBUFFER).get();
+    const outPath = pathJoin(tmpdir(), att.name);
+    writeFileSync(outPath, Buffer.from(data));
+    return {
+      name: att.name,
+      contentType: att.contentType,
+      path: outPath
+    };
+  }
+  async sendEmail(account, msg) {
+    const client = this.clients.get(account);
+    const payload = {
+      message: {
+        subject: msg.subject,
+        body: {
+          contentType: msg.isHtml ? "HTML" : "Text",
+          content: msg.body
+        },
+        toRecipients: msg.to.map(toRecipient),
+        ccRecipients: (msg.cc ?? []).map(toRecipient),
+        bccRecipients: (msg.bcc ?? []).map(toRecipient)
+      },
+      saveToSentItems: true
+    };
+    await client.api("/me/sendMail").post(payload);
+    return { id: "" };
+  }
+};
+function mapRecipient(r) {
+  return {
+    name: r.emailAddress?.name,
+    address: r.emailAddress?.address ?? ""
+  };
+}
+function mapSummary(m, folder) {
+  return {
+    id: m.id,
+    subject: m.subject ?? "",
+    from: m.from ? mapRecipient(m.from) : void 0,
+    to: (m.toRecipients ?? []).map(mapRecipient),
+    receivedAt: m.receivedDateTime,
+    preview: m.bodyPreview,
+    isRead: m.isRead,
+    hasAttachments: m.hasAttachments,
+    folder
+  };
+}
+function toRecipient(a) {
+  return { emailAddress: { name: a.name, address: a.address } };
+}
+function clampLimit(v, dflt, max) {
+  if (!v || v <= 0) return dflt;
+  return Math.min(v, max);
+}
+
+// src/providers/imap/index.ts
+var NOT_IMPLEMENTED = "IMAP provider is not yet implemented in v1. Tracked at src/providers/imap/index.ts \u2014 see src/providers/types.ts for the contract.";
+var ImapProvider = class {
+  id = "imap";
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async addAccount(_input) {
+    throw new Error(NOT_IMPLEMENTED);
+  }
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async completeAddAccount(_handle) {
+    return { status: "error", error: NOT_IMPLEMENTED };
+  }
+  async listEmails(_account, _opts) {
+    throw new Error(NOT_IMPLEMENTED);
+  }
+  async searchEmails(_account, _query, _opts) {
+    throw new Error(NOT_IMPLEMENTED);
+  }
+  async readEmail(_account, _id) {
+    throw new Error(NOT_IMPLEMENTED);
+  }
+  async readAttachment(_account, _messageId, _attachmentId) {
+    throw new Error(NOT_IMPLEMENTED);
+  }
+  async sendEmail(_account, _msg) {
+    throw new Error(NOT_IMPLEMENTED);
+  }
+};
+
+// src/providers/registry.ts
+function buildRegistry(opts) {
+  const providers = /* @__PURE__ */ new Map();
+  providers.set("outlook", new OutlookProvider({ store: opts.store }));
+  providers.set("imap", new ImapProvider());
+  function get(id) {
+    const p = providers.get(id);
+    if (!p) throw new Error(`unknown provider: ${id}`);
+    return p;
+  }
+  function resolveByEmail(email) {
+    const account = opts.store.getAccount(email);
+    if (!account) {
+      throw new Error(
+        `no account registered for "${email}". Call add_account first.`
+      );
+    }
+    return { provider: get(account.provider), account };
+  }
+  return {
+    get,
+    resolveByEmail,
+    list: () => Array.from(providers.values())
+  };
+}
+
+// src/tools/index.ts
+import { z } from "zod";
+
+// src/html-to-markdown.ts
+import TurndownService from "turndown";
+var turndown = new TurndownService();
+function htmlToMarkdown(html) {
+  return turndown.turndown(html);
+}
+function selectBody(msg, format) {
+  switch (format) {
+    case "markdown": {
+      if (msg.bodyHtml) return htmlToMarkdown(msg.bodyHtml);
+      if (msg.bodyText) return msg.bodyText;
+      return "";
+    }
+    case "html": {
+      if (msg.bodyHtml) return msg.bodyHtml;
+      if (msg.bodyText) return msg.bodyText;
+      return "";
+    }
+    case "text": {
+      if (msg.bodyText) return msg.bodyText;
+      if (msg.bodyHtml) return msg.bodyHtml.replace(/<[^>]*>/g, "");
+      return "";
+    }
+  }
+}
+
+// src/tools/index.ts
+function ok(data) {
+  return {
+    content: [
+      { type: "text", text: JSON.stringify(data, null, 2) }
+    ]
+  };
+}
+function fail(message) {
+  return {
+    isError: true,
+    content: [{ type: "text", text: message }]
+  };
+}
+var emailAddrSchema = z.object({
+  address: z.string().email(),
+  name: z.string().optional()
+});
+function registerTools(server, opts) {
+  const { store, registry, readOnly = false } = opts;
+  server.registerTool(
+    "list_accounts",
+    {
+      description: "List all email accounts known to this server (no secrets). Use the returned `email` value as the `account` argument to other tools.",
+      inputSchema: {}
+    },
+    async () => {
+      const rows = store.listAccounts().map((a) => ({
+        email: a.email,
+        provider: a.provider,
+        displayName: a.displayName,
+        addedAt: a.addedAt,
+        hasSignature: !!a.signature,
+        hasStyle: !!(a.style && (a.style.fontFamily || a.style.fontSize || a.style.fontColor))
+      }));
+      return ok({ accounts: rows });
+    }
+  );
+  server.registerTool(
+    "add_account",
+    {
+      description: "Start adding an email account. For Outlook this returns a device code the user must enter at the verification URL; then call `complete_add_account` with the returned `handle` to finalize. Disabled in --read-only mode.",
+      inputSchema: {
+        provider: z.enum(["outlook", "imap", "gmail"]).describe("Email backend. v1 only fully implements 'outlook'."),
+        email: z.string().email().optional().describe("Optional hint \u2014 the provider will verify it against the auth result."),
+        config: z.record(z.unknown()).optional().describe("Provider-specific config (e.g. IMAP host/port). Unused for Outlook.")
+      }
+    },
+    async (args) => {
+      if (readOnly) return fail("server is in --read-only mode; add_account is disabled");
+      const provider = registry.get(args.provider);
+      try {
+        const res = await provider.addAccount({ email: args.email, config: args.config });
+        return ok(res);
+      } catch (err) {
+        return fail(errMsg(err));
+      }
+    }
+  );
+  server.registerTool(
+    "complete_add_account",
+    {
+      description: "Poll/finalize a pending add_account flow. Returns `pending` until the user completes the device-code step, then `ready` with the persisted account.",
+      inputSchema: {
+        provider: z.enum(["outlook", "imap", "gmail"]),
+        handle: z.string().min(1)
+      }
+    },
+    async (args) => {
+      const provider = registry.get(args.provider);
+      if (!provider.completeAddAccount) {
+        return fail(`provider ${args.provider} has no async add-account flow`);
+      }
+      try {
+        const res = await provider.completeAddAccount(args.handle);
+        return ok(res);
+      } catch (err) {
+        return fail(errMsg(err));
+      }
+    }
+  );
+  server.registerTool(
+    "get_account_settings",
+    {
+      description: "Get signature (HTML) and style preferences for an account.",
+      inputSchema: { account: z.string().email() }
+    },
+    async (args) => {
+      try {
+        const acct = store.getAccount(args.account);
+        if (!acct) return fail(`no account registered for "${args.account}"`);
+        return ok({ signature: acct.signature ?? null, style: acct.style ?? null });
+      } catch (err) {
+        return fail(errMsg(err));
+      }
+    }
+  );
+  server.registerTool(
+    "set_account_settings",
+    {
+      description: "Set signature (HTML snippet) and/or style preferences for an account. Disabled in --read-only mode.",
+      inputSchema: {
+        account: z.string().email(),
+        signature: z.string().optional().describe("HTML snippet \u2014 may contain formatting, images, links. Pass null to clear."),
+        style: z.object({
+          fontFamily: z.string().optional(),
+          fontSize: z.string().optional(),
+          fontColor: z.string().optional()
+        }).optional().describe("Font preferences applied to outgoing HTML emails. Pass null to clear.")
+      }
+    },
+    async (args) => {
+      if (readOnly) return fail("server is in --read-only mode; set_account_settings is disabled");
+      try {
+        const acct = store.getAccount(args.account);
+        if (!acct) return fail(`no account registered for "${args.account}"`);
+        const updated = await store.upsertAccount({
+          ...acct,
+          signature: args.signature ?? acct.signature,
+          style: args.style ?? acct.style
+        });
+        return ok({ signature: updated.signature ?? null, style: updated.style ?? null });
+      } catch (err) {
+        return fail(errMsg(err));
+      }
+    }
+  );
+  server.registerTool(
+    "remove_account",
+    {
+      description: "Forget an account and delete its stored tokens. Disabled in --read-only mode.",
+      inputSchema: { email: z.string().email() }
+    },
+    async (args) => {
+      if (readOnly) return fail("server is in --read-only mode; remove_account is disabled");
+      const removed = await store.removeAccount(args.email);
+      return ok({ removed, email: args.email });
+    }
+  );
+  server.registerTool(
+    "list_emails",
+    {
+      description: "List recent emails in a folder of the given account. Pass the user's email address as `account`; the server routes to the correct backend automatically.",
+      inputSchema: {
+        account: z.string().email(),
+        folder: z.string().default("inbox").optional(),
+        limit: z.number().int().positive().max(100).optional(),
+        unreadOnly: z.boolean().optional()
+      }
+    },
+    async (args) => {
+      try {
+        const { provider, account } = registry.resolveByEmail(args.account);
+        const items = await provider.listEmails(account, {
+          folder: args.folder,
+          limit: args.limit,
+          unreadOnly: args.unreadOnly
+        });
+        return ok({ account: account.email, count: items.length, items });
+      } catch (err) {
+        return fail(errMsg(err));
+      }
+    }
+  );
+  server.registerTool(
+    "search_emails",
+    {
+      description: "Search emails by free-text query (KQL on Outlook). Returns lightweight summaries.",
+      inputSchema: {
+        account: z.string().email(),
+        query: z.string().min(1),
+        limit: z.number().int().positive().max(100).optional()
+      }
+    },
+    async (args) => {
+      try {
+        const { provider, account } = registry.resolveByEmail(args.account);
+        const items = await provider.searchEmails(account, args.query, {
+          limit: args.limit
+        });
+        return ok({ account: account.email, count: items.length, items });
+      } catch (err) {
+        return fail(errMsg(err));
+      }
+    }
+  );
+  server.registerTool(
+    "read_email",
+    {
+      description: "Fetch a single email with full body and recipients by id. Body is returned as `body` with `bodyFormat` indicating the format. Default format is 'markdown' \u2014 HTML is automatically converted to save context tokens.",
+      inputSchema: {
+        account: z.string().email(),
+        id: z.string().min(1),
+        format: z.enum(["markdown", "html", "text"]).default("markdown").optional().describe(
+          "Output body format. 'markdown' converts HTML to Markdown (default), 'html' returns the raw HTML, 'text' returns plain text."
+        )
+      }
+    },
+    async (args) => {
+      try {
+        const { provider, account } = registry.resolveByEmail(args.account);
+        const msg = await provider.readEmail(account, args.id);
+        const format = args.format ?? "markdown";
+        const body = selectBody(msg, format);
+        return ok({
+          id: msg.id,
+          subject: msg.subject,
+          from: msg.from,
+          to: msg.to,
+          cc: msg.cc,
+          bcc: msg.bcc,
+          receivedAt: msg.receivedAt,
+          preview: msg.preview,
+          isRead: msg.isRead,
+          hasAttachments: msg.hasAttachments,
+          folder: msg.folder,
+          attachments: msg.attachments,
+          body,
+          bodyFormat: format
+        });
+      } catch (err) {
+        return fail(errMsg(err));
+      }
+    }
+  );
+  server.registerTool(
+    "read_attachment",
+    {
+      description: "Download an email attachment to a temporary file and return its path. Use messageId and attachmentId from a prior read_email call.",
+      inputSchema: {
+        account: z.string().email(),
+        messageId: z.string().min(1),
+        attachmentId: z.string().min(1)
+      }
+    },
+    async (args) => {
+      try {
+        const { provider, account } = registry.resolveByEmail(args.account);
+        const res = await provider.readAttachment(account, args.messageId, args.attachmentId);
+        return ok(res);
+      } catch (err) {
+        return fail(errMsg(err));
+      }
+    }
+  );
+  server.registerTool(
+    "send_email",
+    {
+      description: "Send an email from the given account. Automatically appends the account's signature (HTML) and applies style preferences unless `remove_signature` is true. Disabled in --read-only mode.",
+      inputSchema: {
+        account: z.string().email(),
+        to: z.array(emailAddrSchema).min(1),
+        cc: z.array(emailAddrSchema).optional(),
+        bcc: z.array(emailAddrSchema).optional(),
+        subject: z.string(),
+        body: z.string(),
+        isHtml: z.boolean().optional(),
+        remove_signature: z.boolean().default(false).optional().describe("Skip appending the account signature. Style is still applied.")
+      }
+    },
+    async (args) => {
+      if (readOnly) return fail("server is in --read-only mode; send_email is disabled");
+      try {
+        const { provider, account } = registry.resolveByEmail(args.account);
+        const composed = composeBody({
+          body: args.body,
+          isHtml: args.isHtml,
+          signature: account.signature,
+          style: account.style,
+          removeSignature: args.remove_signature
+        });
+        const res = await provider.sendEmail(account, {
+          to: args.to,
+          cc: args.cc,
+          bcc: args.bcc,
+          subject: args.subject,
+          body: composed.body,
+          isHtml: composed.isHtml
+        });
+        return ok({ sent: true, ...res });
+      } catch (err) {
+        return fail(errMsg(err));
+      }
+    }
+  );
+}
+function composeBody(input) {
+  const { body, isHtml = false, signature, style, removeSignature = false } = input;
+  const hasSignature = !removeSignature && !!signature;
+  const hasStyle = !!(style && (style.fontFamily || style.fontSize || style.fontColor));
+  if (!hasSignature && !hasStyle) {
+    return { body, isHtml };
+  }
+  const styleAttr = hasStyle ? buildStyleAttr(style) : "";
+  if (isHtml) {
+    let result2 = hasStyle ? `<div style="${styleAttr}">${body}</div>` : body;
+    if (hasSignature) result2 += `
+<div class="signature">${signature}</div>`;
+    return { body: result2, isHtml: true };
+  }
+  const escaped = escapeHtml(body);
+  let result = `<div style="${styleAttr}">${escaped}</div>`;
+  if (hasSignature) result += `
+<div class="signature">${signature}</div>`;
+  return { body: result, isHtml: true };
+}
+function buildStyleAttr(style) {
+  const parts = [];
+  if (style.fontFamily) parts.push(`font-family: ${style.fontFamily}`);
+  if (style.fontSize) parts.push(`font-size: ${style.fontSize}`);
+  if (style.fontColor) parts.push(`color: ${style.fontColor}`);
+  return parts.join("; ");
+}
+function escapeHtml(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/\n/g, "<br>");
+}
+function errMsg(err) {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+
+// src/version.ts
+var VERSION = "0.1.0";
+
+// src/server.ts
+async function startServer(opts = {}) {
+  const store = await AccountStore.open({ dataDir: opts.dataDir });
+  const registry = buildRegistry({ store });
+  const server = new McpServer(
+    { name: "hypermail-mcp", version: VERSION },
+    { capabilities: { tools: {}, logging: {} } }
+  );
+  registerTools(server, { store, registry, readOnly: !!opts.readOnly });
+  if (opts.http) {
+    await startHttp(server, opts.host ?? "127.0.0.1", opts.port ?? 3e3);
+  } else {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+  }
+}
+async function startHttp(server, host, port) {
+  const sessions = /* @__PURE__ */ new Map();
+  const http = createHttpServer(async (req, res) => {
+    try {
+      if (!req.url || !req.url.startsWith("/mcp")) {
+        res.statusCode = 404;
+        res.end("not found");
+        return;
+      }
+      const sessionId = req.headers["mcp-session-id"] ?? void 0;
+      let transport = sessionId ? sessions.get(sessionId) : void 0;
+      if (!transport) {
+        transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: () => randomUUID2(),
+          onsessioninitialized: (sid) => {
+            sessions.set(sid, transport);
+          }
+        });
+        transport.onclose = () => {
+          if (transport.sessionId) sessions.delete(transport.sessionId);
+        };
+        await server.connect(transport);
+      }
+      let body = void 0;
+      if (req.method === "POST" || req.method === "DELETE") {
+        const chunks = [];
+        for await (const chunk of req) chunks.push(chunk);
+        const raw = Buffer.concat(chunks).toString("utf8");
+        body = raw ? JSON.parse(raw) : void 0;
+      }
+      await transport.handleRequest(req, res, body);
+    } catch (err) {
+      console.error("[hypermail-mcp] http error:", err);
+      if (!res.headersSent) {
+        res.statusCode = 500;
+        res.end("internal error");
+      }
+    }
+  });
+  await new Promise((resolve) => http.listen(port, host, resolve));
+  console.error(`[hypermail-mcp] listening on http://${host}:${port}/mcp`);
+}
+
+// src/cli.ts
+function parseArgs(argv) {
+  const out = {
+    http: false,
+    port: 3e3,
+    host: "127.0.0.1",
+    readOnly: false,
+    help: false
+  };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    switch (a) {
+      case "--http":
+        out.http = true;
+        break;
+      case "--port":
+        out.port = Number(argv[++i] ?? "3000");
+        break;
+      case "--host":
+        out.host = String(argv[++i] ?? "127.0.0.1");
+        break;
+      case "--data-dir":
+        out.dataDir = String(argv[++i] ?? "");
+        break;
+      case "--read-only":
+        out.readOnly = true;
+        break;
+      case "-h":
+      case "--help":
+        out.help = true;
+        break;
+      default:
+        if (a && a.startsWith("--")) {
+        }
+    }
+  }
+  return out;
+}
+function printHelp() {
+  const msg = `hypermail-mcp \u2014 unified email MCP server
+
+Usage:
+  hypermail-mcp [options]
+
+Options:
+  --http              Run as Streamable HTTP server (default: stdio)
+  --port <n>          HTTP port (default: 3000)
+  --host <addr>       HTTP bind address (default: 127.0.0.1)
+  --data-dir <path>   Where to store the encrypted accounts file
+                      (default: $HYPERMAIL_MCP_DATA_DIR or ~/.hypermail-mcp)
+  --read-only         Disable tools that modify state (send_email, remove_account, add_account)
+  -h, --help          Show this help
+
+Environment:
+  HYPERMAIL_MCP_DATA_DIR   Same as --data-dir
+  HYPERMAIL_MCP_KEY        32-byte key (base64 or hex) for at-rest encryption
+  MS_CLIENT_ID               Azure AD public client (application) ID
+  MS_TENANT_ID               Tenant (default: "common")
+`;
+  process.stdout.write(msg);
+}
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    printHelp();
+    return;
+  }
+  await startServer({
+    http: opts.http,
+    port: opts.port,
+    host: opts.host,
+    dataDir: opts.dataDir,
+    readOnly: opts.readOnly
+  });
+}
+main().catch((err) => {
+  console.error("[hypermail-mcp] fatal:", err);
+  process.exit(1);
+});
+//# sourceMappingURL=cli.js.map