hypermail-mcp 0.7.18 → 0.7.19

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.19** — Hardened Outlook ID handling when Microsoft Graph `$search`
+> returns IDs that `/me/messages/{id}` rejects as malformed: `search_emails`
+> now returns a translated readable immutable ID when available, and
+> `read_email` retries malformed/stale IDs through `translateExchangeIds`
+> before failing. `list_emails` also falls back from localized folder display
+> names such as `Éléments envoyés` to the matching Graph folder ID.
+>
 > **v0.7.18** — `search_emails` can now omit `account` to search all
 > registered accounts in parallel, returning account-annotated results plus
 > per-account errors without discarding successful matches. All-account
@@ -295,10 +302,10 @@ account store.
 | `get_account_settings` | `account` | Get signature (HTML) and style preferences for an account. |
 | `set_account_settings` | `account`, `signature?`, `signaturePath?`, `style?` | Set signature HTML (inline or via file path) and font preferences. |
 | `remove_account` | `email` | Deletes tokens for the account. |
-| `list_emails` | `account`, `folder?`, `limit?`, `unreadOnly?`, `skip?` | Defaults: folder=`inbox`, limit=25. Supports pagination via `skip` — response includes `hasMore`. |
+| `list_emails` | `account`, `folder?`, `limit?`, `unreadOnly?`, `skip?` | Defaults: folder=`inbox`, limit=25. Supports pagination via `skip` — response includes `hasMore`. Outlook accepts well-known folder names, folder IDs, and falls back from localized display names to matching folder IDs. |
 | `get_new_emails` | `account?`, `limit?` | Pull new inbox emails not previously returned by this tool. `limit` defaults to 10 and is global when `account` is omitted. Returns full markdown bodies with attachment metadata; bodies may be truncated. |
-| `search_emails` | `account?`, `query`, `limit?` | Search one account when `account` is provided, or omit it to search all registered accounts in parallel. Returns account-annotated summaries and partial per-account errors. Uses KQL on Outlook. |
-| `read_email` | `account`, `id`, `format?` | Returns full body + recipients + attachment metadata. `format`: `markdown` (default), `html`, or `text`. |
+| `search_emails` | `account?`, `query`, `limit?` | Search one account when `account` is provided, or omit it to search all registered accounts in parallel. Returns account-annotated summaries and partial per-account errors. Uses KQL on Outlook, and normalizes malformed Outlook search-result IDs to readable immutable IDs when possible. |
+| `read_email` | `account`, `id`, `format?` | Returns full body + recipients + attachment metadata. `format`: `markdown` (default), `html`, or `text`. Outlook retries malformed/stale IDs through Graph ID translation before failing. |
 | `read_attachment` | `account`, `messageId`, `attachmentId` | Download an attachment to a temporary file and return its path. |
 | `archive_email` | `account`, `id` | Move a message to the Archive folder. |
 | `trash_email` | `account`, `id` | Move a message to Deleted Items (trash). |

package/dist/cli.js

@@ -14870,6 +14870,10 @@ var FULL_MESSAGE_SELECT = [
   "hasAttachments",
   "body"
 ].join(",");
+var EXCHANGE_ID_TRANSLATION_SOURCE_TYPES = [
+  "ewsId",
+  "restId"
+];
 function graphErrorFields(err) {
   if (typeof err !== "object" || err === null) {
     return [String(err)];
@@ -14910,6 +14914,23 @@ function isStaleMessageIdError(err) {
     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 translateMessageIdToImmutable(client, id) {
+  for (const sourceIdType of EXCHANGE_ID_TRANSLATION_SOURCE_TYPES) {
+    try {
+      const res = await client.api("/me/translateExchangeIds").post({
+        inputIds: [id],
+        sourceIdType,
+        targetIdType: "restImmutableEntryId"
+      });
+      const targetId = res.value?.find((item) => item.targetId)?.targetId;
+      if (typeof targetId === "string" && targetId !== "" && targetId !== id) {
+        return targetId;
+      }
+    } catch {
+    }
+  }
+  return void 0;
+}
 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);
@@ -14918,27 +14939,58 @@ async function probeMessage(client, id, useImmutableIds) {
 async function probeSearchResult(client, id) {
   try {
     await probeMessage(client, id, true);
-    return true;
+    return id;
   } catch (err) {
     if (!isStaleMessageIdError(err)) throw err;
   }
   try {
     await probeMessage(client, id, false);
-    return true;
+    return id;
+  } catch (err) {
+    if (!isStaleMessageIdError(err)) throw err;
+  }
+  const translatedId = await translateMessageIdToImmutable(client, id);
+  if (!translatedId) return void 0;
+  try {
+    await probeMessage(client, translatedId, true);
+    return translatedId;
   } catch (err) {
-    if (isStaleMessageIdError(err)) return false;
-    throw err;
+    if (!isStaleMessageIdError(err)) throw err;
+    return void 0;
   }
 }
+async function getMessageById(client, id, useImmutableIds) {
+  let req = client.api(`/me/messages/${encodeURIComponent(id)}`).select(FULL_MESSAGE_SELECT);
+  if (useImmutableIds) req = req.header("Prefer", OUTLOOK_IMMUTABLE_ID_PREFER);
+  return await req.get();
+}
 async function getMessage(client, id) {
+  let lastStaleError;
   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 };
+    return { message: await getMessageById(client, id, true), useImmutableIds: true };
   } catch (err) {
     if (!isStaleMessageIdError(err)) throw err;
+    lastStaleError = err;
   }
-  const message = await client.api(`/me/messages/${encodeURIComponent(id)}`).select(FULL_MESSAGE_SELECT).get();
-  return { message, useImmutableIds: false };
+  try {
+    return { message: await getMessageById(client, id, false), useImmutableIds: false };
+  } catch (err) {
+    if (!isStaleMessageIdError(err)) throw err;
+    lastStaleError = err;
+  }
+  const translatedId = await translateMessageIdToImmutable(client, id);
+  if (translatedId) {
+    try {
+      return {
+        message: await getMessageById(client, translatedId, true),
+        useImmutableIds: true
+      };
+    } catch (err) {
+      if (!isStaleMessageIdError(err)) throw err;
+      lastStaleError = err;
+    }
+  }
+  throw lastStaleError ?? new Error("Message not found");
 }
 async function listAttachments(client, messageId, useImmutableIds) {
   let req = client.api(`/me/messages/${encodeURIComponent(messageId)}/attachments`).select("id,name,contentType,size");
@@ -14956,14 +15008,36 @@ async function getAttachmentValue(client, messageId, attachmentId, useImmutableI
   if (useImmutableIds) req = req.header("Prefer", OUTLOOK_IMMUTABLE_ID_PREFER);
   return await req.get();
 }
+async function listMessagePage(client, folder, limit, skip, filterParts) {
+  let req = client.api(`/me/mailFolders/${encodeURIComponent(folder)}/messages`).header("Prefer", OUTLOOK_IMMUTABLE_ID_PREFER).top(limit).skip(skip).select(MESSAGE_SELECT).orderby("receivedDateTime DESC");
+  if (filterParts.length > 0) req = req.filter(filterParts.join(" and "));
+  return await req.get();
+}
+function normalizeFolderDisplayName(value) {
+  return value.trim().normalize("NFD").replace(new RegExp("\\p{Diacritic}", "gu"), "").toLowerCase();
+}
+async function resolveFolderIdByDisplayName(client, displayName) {
+  const wanted = normalizeFolderDisplayName(displayName);
+  if (!wanted) return void 0;
+  const res = await client.api("/me/mailFolders").top(100).select("id,displayName").get();
+  return (res.value ?? []).find(
+    (folder) => normalizeFolderDisplayName(folder.displayName) === wanted
+  )?.id;
+}
 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`).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();
+  let res;
+  try {
+    res = await listMessagePage(client, folder, limit, opts.skip ?? 0, filterParts);
+  } catch (err) {
+    if (!isStaleMessageIdError(err)) throw err;
+    const resolvedFolderId = await resolveFolderIdByDisplayName(client, folder);
+    if (!resolvedFolderId || resolvedFolderId === folder) throw err;
+    res = await listMessagePage(client, resolvedFolderId, limit, opts.skip ?? 0, filterParts);
+  }
   return {
     items: res.value.map((m) => mapSummary(m, folder)),
     hasMore: !!res["@odata.nextLink"]
@@ -14975,8 +15049,8 @@ async function searchEmails(client, account, query, opts) {
   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 };
+      const readableId = await probeSearchResult(client, summary.id);
+      return readableId ? { ...summary, id: readableId } : { ...summary, stale: true };
     })
   );
 }
@@ -19064,7 +19138,7 @@ function registerTools(server, opts) {
 // package.json
 var package_default = {
   name: "hypermail-mcp",
-  version: "0.7.18",
+  version: "0.7.19",
   description: "Unified email MCP server \u2014 operate any inbox (Outlook now, IMAP/Gmail later) by passing an email address.",
   type: "module",
   bin: {