hypermail-mcp 0.7.15 → 0.7.17

package/README.md

@@ -3,6 +3,20 @@
 A **Model Context Protocol** server that lets an agent operate any of the user's
 inboxes through a single, unified tool surface.
 
+> **v0.7.17** — Hardened Outlook message IDs returned by `list_emails` and
+> `search_emails`: Outlook reads now request Microsoft Graph immutable IDs,
+> `search_emails` probes results and marks stale/not-found messages with
+> `stale: true`, and `read_email` / `read_attachment` keep a legacy mutable-ID
+> fallback for older IDs. Graph errors now include structured diagnostic details
+> when available.
+>
+> **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 +219,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 +298,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

@@ -14846,21 +14846,122 @@ import { ResponseType } from "@microsoft/microsoft-graph-client";
 import { writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join as pathJoin } from "path";
+var OUTLOOK_IMMUTABLE_ID_PREFER = 'IdType="ImmutableId"';
+var MESSAGE_SELECT = [
+  "id",
+  "subject",
+  "from",
+  "toRecipients",
+  "receivedDateTime",
+  "bodyPreview",
+  "isRead",
+  "hasAttachments"
+].join(",");
+var FULL_MESSAGE_SELECT = [
+  "id",
+  "subject",
+  "from",
+  "toRecipients",
+  "ccRecipients",
+  "bccRecipients",
+  "receivedDateTime",
+  "bodyPreview",
+  "isRead",
+  "hasAttachments",
+  "body"
+].join(",");
+function graphErrorFields(err) {
+  if (typeof err !== "object" || err === null) {
+    return [String(err)];
+  }
+  const record2 = err;
+  const fields = [];
+  for (const key of ["code", "statusCode", "message"]) {
+    const value = record2[key];
+    if (typeof value === "string" || typeof value === "number") fields.push(value);
+  }
+  if (typeof record2.body === "string") {
+    try {
+      const parsed = JSON.parse(record2.body);
+      if (typeof parsed === "object" && parsed !== null) {
+        const graphError = parsed.error;
+        if (typeof graphError === "object" && graphError !== null) {
+          const graphRecord = graphError;
+          for (const key of ["code", "message"]) {
+            const value = graphRecord[key];
+            if (typeof value === "string" || typeof value === "number") {
+              fields.push(value);
+            }
+          }
+        }
+      }
+    } catch {
+      fields.push(record2.body);
+    }
+  }
+  return fields;
+}
+function isStaleMessageIdError(err) {
+  const fields = graphErrorFields(err);
+  if (fields.some((value) => value === 404)) return true;
+  return fields.some((value) => {
+    if (typeof value !== "string") return false;
+    const normalized = value.toLowerCase();
+    return normalized.includes("erroritemnotfound") || normalized.includes("invalidid") || normalized.includes("object was not found in the store") || normalized.includes("not found in the store");
+  });
+}
+async function probeMessage(client, id, useImmutableIds) {
+  let req = client.api(`/me/messages/${encodeURIComponent(id)}`).select("id");
+  if (useImmutableIds) req = req.header("Prefer", OUTLOOK_IMMUTABLE_ID_PREFER);
+  await req.get();
+}
+async function probeSearchResult(client, id) {
+  try {
+    await probeMessage(client, id, true);
+    return true;
+  } catch (err) {
+    if (!isStaleMessageIdError(err)) throw err;
+  }
+  try {
+    await probeMessage(client, id, false);
+    return true;
+  } catch (err) {
+    if (isStaleMessageIdError(err)) return false;
+    throw err;
+  }
+}
+async function getMessage(client, id) {
+  try {
+    const message2 = await client.api(`/me/messages/${encodeURIComponent(id)}`).header("Prefer", OUTLOOK_IMMUTABLE_ID_PREFER).select(FULL_MESSAGE_SELECT).get();
+    return { message: message2, useImmutableIds: true };
+  } catch (err) {
+    if (!isStaleMessageIdError(err)) throw err;
+  }
+  const message = await client.api(`/me/messages/${encodeURIComponent(id)}`).select(FULL_MESSAGE_SELECT).get();
+  return { message, useImmutableIds: false };
+}
+async function listAttachments(client, messageId, useImmutableIds) {
+  let req = client.api(`/me/messages/${encodeURIComponent(messageId)}/attachments`).select("id,name,contentType,size");
+  if (useImmutableIds) req = req.header("Prefer", OUTLOOK_IMMUTABLE_ID_PREFER);
+  const attRes = await req.get();
+  return attRes.value;
+}
+async function getAttachmentMetadata(client, messageId, attachmentId, useImmutableIds) {
+  let req = client.api(`/me/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}`).select("name,contentType");
+  if (useImmutableIds) req = req.header("Prefer", OUTLOOK_IMMUTABLE_ID_PREFER);
+  return await req.get();
+}
+async function getAttachmentValue(client, messageId, attachmentId, useImmutableIds) {
+  let req = client.api(`/me/messages/${encodeURIComponent(messageId)}/attachments/${encodeURIComponent(attachmentId)}/$value`).responseType(ResponseType.ARRAYBUFFER);
+  if (useImmutableIds) req = req.header("Prefer", OUTLOOK_IMMUTABLE_ID_PREFER);
+  return await req.get();
+}
 async function listEmails(client, account, opts) {
   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).skip(opts.skip ?? 0).select([
-    "id",
-    "subject",
-    "from",
-    "toRecipients",
-    "receivedDateTime",
-    "bodyPreview",
-    "isRead",
-    "hasAttachments"
-  ].join(",")).orderby("receivedDateTime DESC");
+  let req = client.api(`/me/mailFolders/${encodeURIComponent(folder)}/messages`).header("Prefer", OUTLOOK_IMMUTABLE_ID_PREFER).top(limit).skip(opts.skip ?? 0).select(MESSAGE_SELECT).orderby("receivedDateTime DESC");
   if (filterParts.length > 0) req = req.filter(filterParts.join(" and "));
   const res = await req.get();
   return {
@@ -14870,41 +14971,22 @@ async function listEmails(client, account, opts) {
 }
 async function searchEmails(client, account, query, opts) {
   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));
+  const res = await client.api("/me/messages").header("ConsistencyLevel", "eventual").header("Prefer", OUTLOOK_IMMUTABLE_ID_PREFER).top(limit).search(`"${query.replace(/"/g, '\\"')}"`).select(MESSAGE_SELECT).get();
+  const summaries = res.value.map((m) => mapSummary(m));
+  return Promise.all(
+    summaries.map(async (summary) => {
+      const readable = await probeSearchResult(client, summary.id);
+      return readable ? summary : { ...summary, stale: true };
+    })
+  );
 }
 async function readEmail(client, account, id) {
-  const m = await client.api(`/me/messages/${encodeURIComponent(id)}`).select(
-    [
-      "id",
-      "subject",
-      "from",
-      "toRecipients",
-      "ccRecipients",
-      "bccRecipients",
-      "receivedDateTime",
-      "bodyPreview",
-      "isRead",
-      "hasAttachments",
-      "body"
-    ].join(",")
-  ).get();
+  const { message: m, useImmutableIds } = await getMessage(client, id);
   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) => ({
+      const attRes = await listAttachments(client, m.id, useImmutableIds);
+      attachments = attRes.map((a) => ({
         id: a.id,
         name: a.name,
         contentType: a.contentType,
@@ -14925,8 +15007,22 @@ async function readEmail(client, account, id) {
   };
 }
 async function readAttachment(client, account, messageId, attachmentId) {
-  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();
+  let useImmutableIds = true;
+  let att;
+  try {
+    att = await getAttachmentMetadata(client, messageId, attachmentId, true);
+  } catch (err) {
+    if (!isStaleMessageIdError(err)) throw err;
+    useImmutableIds = false;
+    att = await getAttachmentMetadata(client, messageId, attachmentId, false);
+  }
+  let data;
+  try {
+    data = await getAttachmentValue(client, messageId, attachmentId, useImmutableIds);
+  } catch (err) {
+    if (!useImmutableIds || !isStaleMessageIdError(err)) throw err;
+    data = await getAttachmentValue(client, messageId, attachmentId, false);
+  }
   const outPath = pathJoin(tmpdir(), att.name);
   writeFileSync(outPath, Buffer.from(data));
   return {
@@ -15264,6 +15360,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 +15750,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);
@@ -17215,12 +17325,41 @@ function fail(message) {
     content: [{ type: "text", text: message }]
   };
 }
+function graphErrorDetails(err) {
+  if (typeof err !== "object" || err === null) return void 0;
+  const record2 = err;
+  const details = {};
+  for (const key of ["code", "statusCode", "requestId", "date", "innerError"]) {
+    if (record2[key] !== void 0) details[key] = record2[key];
+  }
+  if (typeof record2.body === "string") {
+    try {
+      const parsed = JSON.parse(record2.body);
+      if (typeof parsed === "object" && parsed !== null) {
+        const graphError = parsed.error;
+        if (typeof graphError === "object" && graphError !== null) {
+          const graphRecord = graphError;
+          for (const key of ["code", "message", "innerError"]) {
+            if (graphRecord[key] !== void 0 && details[key] === void 0) {
+              details[key] = graphRecord[key];
+            }
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return Object.keys(details).length > 0 ? details : void 0;
+}
 function errMsg(err) {
   const message = err instanceof Error ? err.message : String(err);
   if (message.includes("HYPERMAIL_GMAIL_CLIENT_ID")) {
     return "Missing Gmail OAuth configuration: set HYPERMAIL_GMAIL_CLIENT_ID before adding a Gmail account.";
   }
-  return message;
+  const details = graphErrorDetails(err);
+  if (!details) return message;
+  return `${message}
+${JSON.stringify({ error: details }, null, 2)}`;
 }
 var providerIdEnum = z2.enum(["outlook", "imap", "gmail"]);
 var emailAddrSchema = z2.object({
@@ -17280,7 +17419,8 @@ var emailSummaryOutputSchema = z2.object({
   preview: z2.string().optional(),
   isRead: z2.boolean().optional(),
   hasAttachments: z2.boolean().optional(),
-  folder: z2.string().optional()
+  folder: z2.string().optional(),
+  stale: z2.boolean().optional()
 });
 var attachmentMetaOutputSchema = z2.object({
   id: z2.string(),
@@ -18522,10 +18662,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 +18689,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 +18714,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 +18732,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 +18794,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 +18993,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.17",
   description: "Unified email MCP server \u2014 operate any inbox (Outlook now, IMAP/Gmail later) by passing an email address.",
   type: "module",
   bin: {
@@ -19210,10 +19406,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 +19446,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 +19473,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 +19517,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}