hypermail-mcp 0.7.15 → 0.7.16

package/README.md

@@ -3,6 +3,13 @@
 A **Model Context Protocol** server that lets an agent operate any of the user's
 inboxes through a single, unified tool surface.
 
+> **v0.7.16** — Hardened `draft_email` after successful draft creation:
+> if post-save readback fails, the tool now returns the created draft ID with
+> `warning` and `draftReadbackError` instead of losing the draft behind an
+> error. Compose operations also emit sanitized `HYPERMAIL_DEBUG` stage logs,
+> IMAP drafts now use the server-advertised `\\Drafts` mailbox when present,
+> and the CLI supports `--version`.
+>
 > **v0.7.15** — Hardened IMAP draft creation: drafts now append directly to
 > the Drafts mailbox, retry without the `\\Draft` flag when an IMAP server
 > rejects flagged APPEND, and preserve IMAP reply/forward context in drafts the
@@ -205,7 +212,7 @@ Hypermail uses flat `HYPERMAIL_*` environment variables as the source of truth.
 There is no runtime config file. CLI flags only override transport, host, port,
 and data directory for a single invocation.
 
-CLI flags: `--http`, `--port`, `--host`, `--data-dir`, `--help`.
+CLI flags: `--http`, `--port`, `--host`, `--data-dir`, `--version`, `--help`.
 
 Subcommands: `hypermail-mcp generate-key` — generate a base64 32-byte key for
 `HYPERMAIL_KEY`.
@@ -284,7 +291,7 @@ account store.
 | `trash_email` | `account`, `id` | Move a message to Deleted Items (trash). |
 | `move_email` | `account`, `id`, `destination` | Move to any folder by well-known name (`inbox`, `drafts`, etc.) or custom folder ID. |
 | `send_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `format`, `include_signature`, `inReplyTo`, `replyAll?`, `forwardMessageId?`, `attachments?` | Send an email. `format` (`"html"` or `"markdown"`) controls body format — Markdown is converted to HTML via `marked`; multiline plain text with `format: "html"` is rejected, so use `"markdown"` for paragraphs or add tags like `<p>`/`<br>`. Appends signature when `include_signature` is true. `inReplyTo` sends as threaded reply; `forwardMessageId` sends as forward. `inReplyTo` is required — set to `false` for new emails. `attachments` is an optional array of `{filePath, name?}` — files are read from disk and encoded automatically. |
-| `draft_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `format`, `include_signature`, `inReplyTo`, `replyAll?`, `forwardMessageId?`, `attachments?` | Save as draft instead of sending. Same params as `send_email` including `attachments`. Returns the draft message ID and HTML body (`draftHtml`). `inReplyTo` is required — set to `false` for new emails. |
+| `draft_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `format`, `include_signature`, `inReplyTo`, `replyAll?`, `forwardMessageId?`, `attachments?` | Save as draft instead of sending. Same params as `send_email` including `attachments`. Returns the draft message ID and, when readback succeeds, HTML body (`draftHtml`). If the draft is created but readback fails, returns the draft ID with `warning` and `draftReadbackError` so callers can retry `read_email` or continue with `send_draft`. `inReplyTo` is required — set to `false` for new emails. |
 | `edit_draft` | `account`, `id`, `to?`, `cc?`, `bcc?`, `subject?`, `old_text?`, `new_text?`, `body?`, `format?`, `include_signature?`, `new_attachments?`, `remove_attachments?` | Edit an existing draft by ID. Body edits require exact selected-section replacement: copy `old_text` from the current draft HTML (`draftHtml` or `read_email` with `format: "html"`) and provide `new_text`; the match must occur exactly once, and unselected content such as reply/forward history is preserved. Deprecated `body` is only an alias for `new_text` when `old_text` is also provided; body-only full replacement is rejected. Multiline plain-text replacements with `format: "html"` are rejected; use `"markdown"` for paragraphs or add tags like `<p>`/`<br>`. Body edits are re-read after saving; if the updated body is not observable after retries, the tool returns an error instead of reporting success. `new_attachments` adds files (`{filePath, name?}[]`); `remove_attachments` removes by attachment ID (`string[]`). Returns the updated draft ID, HTML body (`draftHtml`), and attachment metadata. |
 | `send_draft` | `account`, `id` | Send an existing draft email by ID. Use with draft IDs returned by `draft_email` or `edit_draft`. |
 | `list_folders` | `account`, `parentFolderId?` | List available mail folders. Returns top-level folders by default, or children of `parentFolderId`. |

package/dist/cli.js

@@ -15264,6 +15264,17 @@ function resolveTrashMailbox(mailboxes) {
   }
   return "Trash";
 }
+function resolveDraftMailbox(mailboxes) {
+  for (const mailbox of mailboxes) {
+    const specialUse = mailbox.specialUse?.toLowerCase();
+    if (specialUse === "\\drafts") return mailbox.path;
+    const flags = mailbox.flags ? Array.from(mailbox.flags) : [];
+    if (flags.some((flag) => flag.toLowerCase() === "\\drafts")) {
+      return mailbox.path;
+    }
+  }
+  return "Drafts";
+}
 function clampLimit2(v, dflt, max) {
   if (!v || v <= 0) return dflt;
   return Math.min(v, max);
@@ -15643,10 +15654,13 @@ async function sendEmail(clients, account, msg) {
 }
 async function saveDraft(clients, account, msg) {
   const client = clients.get(account);
-  const folder = "Drafts";
   const rawMsg = await buildRawMessage(client, account, msg);
+  let folder = "Drafts";
   try {
-    const result = await client.run((imap) => appendDraft(imap, folder, rawMsg));
+    const result = await client.run(async (imap) => {
+      folder = resolveDraftMailbox(await imap.list());
+      return appendDraft(imap, folder, rawMsg);
+    });
     return { id: encodeId(folder, appendUid(result, folder)) };
   } catch (err) {
     throw imapOperationError(`failed to save IMAP draft to ${folder}`, err);
@@ -18522,10 +18536,21 @@ var editDraftSchema = z8.object({
 
 // src/tools/compose.ts
 function registerComposeTools(server, ctx) {
-  const { store, registry, tools } = ctx;
+  const { store, registry, tools, logger } = ctx;
   async function handleSendOrDraft(args, action, resultKey, toolName) {
     try {
       const { provider, account } = registry.resolveByEmail(args.account);
+      logger?.debug("compose", "start", {
+        tool: toolName,
+        account: account.email,
+        provider: provider.id,
+        toCount: args.to.length,
+        ccCount: args.cc?.length ?? 0,
+        bccCount: args.bcc?.length ?? 0,
+        hasReply: !!args.inReplyTo,
+        hasForward: !!args.forwardMessageId,
+        attachmentCount: args.attachments?.length ?? 0
+      });
       if (args.include_signature && !account.signature) {
         return fail(
           "include_signature is true but no signature is configured for this account. Set up a signature first with set_account_settings."
@@ -18538,6 +18563,14 @@ function registerComposeTools(server, ctx) {
         style: account.style,
         includeSignature: args.include_signature
       });
+      logger?.debug("compose", "composed", {
+        tool: toolName,
+        account: account.email,
+        provider: provider.id,
+        format: args.format,
+        isHtml: composed.isHtml,
+        includeSignature: args.include_signature
+      });
       if (args.inReplyTo && args.forwardMessageId) {
         return fail(
           "inReplyTo and forwardMessageId are mutually exclusive \u2014 use one or the other"
@@ -18555,6 +18588,12 @@ function registerComposeTools(server, ctx) {
           };
         });
       }
+      logger?.debug("compose", "attachmentsProcessed", {
+        tool: toolName,
+        account: account.email,
+        provider: provider.id,
+        attachmentCount: processedAttachments?.length ?? 0
+      });
       const res = await action(provider, account, {
         to: args.to,
         cc: args.cc,
@@ -18567,13 +18606,42 @@ function registerComposeTools(server, ctx) {
         forwardMessageId: args.forwardMessageId,
         attachments: processedAttachments
       });
+      logger?.debug("compose", "providerActionSuccess", {
+        tool: toolName,
+        account: account.email,
+        provider: provider.id,
+        hasId: !!res.id
+      });
       const result = { [resultKey]: true, ...res };
       if (toolName === "draft_email" && res.id) {
-        const draft = await provider.readEmail(account, res.id);
-        result.draftHtml = draft.bodyHtml;
+        try {
+          const draft = await provider.readEmail(account, res.id);
+          result.draftHtml = draft.bodyHtml;
+          logger?.debug("compose", "draftReadbackSuccess", {
+            tool: toolName,
+            account: account.email,
+            provider: provider.id,
+            hasDraftHtml: draft.bodyHtml !== void 0
+          });
+        } catch (readErr) {
+          const message = errMsg(readErr);
+          result.warning = "Draft was created, but reading it back for draftHtml failed. Use read_email with the returned id to inspect it, or continue with send_draft if appropriate.";
+          result.draftReadbackError = message;
+          logger?.debug("compose", "draftReadbackError", {
+            tool: toolName,
+            account: account.email,
+            provider: provider.id,
+            message
+          });
+        }
       }
       return ok(result, result);
     } catch (err) {
+      logger?.debug("compose", "error", {
+        tool: toolName,
+        account: args.account,
+        message: errMsg(err)
+      });
       return fail(errMsg(err));
     }
   }
@@ -18600,7 +18668,9 @@ function registerComposeTools(server, ctx) {
   const draftEmailOutputSchema = {
     draft: z9.literal(true),
     id: z9.string(),
-    draftHtml: z9.string().optional()
+    draftHtml: z9.string().optional(),
+    warning: z9.string().optional(),
+    draftReadbackError: z9.string().optional()
   };
   if (shouldRegister("draft_email", tools)) {
     server.registerTool(
@@ -18797,13 +18867,13 @@ function registerTools(server, opts) {
   registerBrowseTools(server, { store, registry, tools, logger });
   registerFolderTools(server, { registry, tools });
   registerOrganizeTools(server, { registry, tools });
-  registerComposeTools(server, { store, registry, tools });
+  registerComposeTools(server, { store, registry, tools, logger });
 }
 
 // package.json
 var package_default = {
   name: "hypermail-mcp",
-  version: "0.7.15",
+  version: "0.7.16",
   description: "Unified email MCP server \u2014 operate any inbox (Outlook now, IMAP/Gmail later) by passing an email address.",
   type: "module",
   bin: {
@@ -19210,10 +19280,16 @@ function parseArgs(argv) {
     if (argv.length > 1) {
       throw new Error(`Unknown argument for generate-key: ${argv[1]}`);
     }
-    return { command: "generate-key", help: false, overrides: {} };
+    return {
+      command: "generate-key",
+      help: false,
+      version: false,
+      overrides: {}
+    };
   }
   const out = {
     help: false,
+    version: false,
     overrides: {}
   };
   for (let i = 0; i < argv.length; i++) {
@@ -19244,6 +19320,9 @@ function parseArgs(argv) {
       case "--help":
         out.help = true;
         break;
+      case "--version":
+        out.version = true;
+        break;
       default:
         if (arg.startsWith("-")) {
           throw new Error(`Unknown option: ${arg}`);
@@ -19268,6 +19347,7 @@ Options:
   --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
+  --version           Show package version
   -h, --help          Show this help
 
 Configuration:
@@ -19311,6 +19391,11 @@ async function main() {
     process.stdout.write(helpText());
     return;
   }
+  if (opts.version) {
+    process.stdout.write(`${VERSION}
+`);
+    return;
+  }
   const { config, warnings } = loadConfig(opts.overrides);
   for (const warning of warnings) {
     process.stderr.write(`[hypermail-mcp] warning: ${warning}