hypermail-mcp 0.7.17 → 0.7.19

package/README.md

@@ -3,6 +3,19 @@
 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
+> `get_new_emails` polling also collects and hydrates per-account batches in
+> parallel while preserving the global oldest-first limit.
+>
 > **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
@@ -289,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?` | 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). |
@@ -319,6 +332,8 @@ tool on their own schedule, for example every 30–60 seconds.
 - `account` is optional. When omitted, the tool checks all registered accounts.
 - `limit` defaults to `10`. In all-account mode, the limit is a global total
   across accounts, selected by oldest `receivedAt` first.
+- All-account polling performs per-account candidate collection and hydration in
+  parallel, then returns the combined batch in oldest-first order.
 - First use for an account initializes its checkpoint to the newest inbox email
   and returns no emails for that account.
 - Later calls return emails not previously returned by this tool, oldest first.

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)) return false;
-    throw 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)) 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 };
     })
   );
 }
@@ -17839,20 +17913,36 @@ function registerNewEmailTool(server, ctx) {
       const collected = [];
       const providersByEmail = /* @__PURE__ */ new Map();
       const accountsByEmail = /* @__PURE__ */ new Map();
-      for (const stored of accounts) {
-        try {
-          const { provider, account } = registry.resolveByEmail(stored.email);
-          const result = await collectCandidatesForAccount(store, provider, account, logger);
-          providersByEmail.set(result.account.email, provider);
-          accountsByEmail.set(result.account.email, result.account);
-          collected.push(...result.candidates);
-        } catch (err) {
-          logger.debug("get-new-emails", "accountError", {
-            account: stored.email,
-            message: errMsg(err)
-          });
-          errors.push({ account: stored.email, message: errMsg(err) });
+      const collectedByAccount = await Promise.all(
+        accounts.map(async (stored) => {
+          try {
+            const { provider, account } = registry.resolveByEmail(stored.email);
+            const result = await collectCandidatesForAccount(store, provider, account, logger);
+            return {
+              status: "ok",
+              account: result.account,
+              provider,
+              candidates: result.candidates
+            };
+          } catch (err) {
+            const message = errMsg(err);
+            logger.debug("get-new-emails", "accountError", { account: stored.email, message });
+            return {
+              status: "error",
+              account: stored.email,
+              message
+            };
+          }
+        })
+      );
+      for (const result of collectedByAccount) {
+        if (result.status === "error") {
+          errors.push({ account: result.account, message: result.message });
+          continue;
         }
+        providersByEmail.set(result.account.email, result.provider);
+        accountsByEmail.set(result.account.email, result.account);
+        collected.push(...result.candidates);
       }
       const selected = oldestCandidatesFirst(collected).slice(0, limit);
       logger.debug("get-new-emails", "selected", {
@@ -17871,27 +17961,33 @@ function registerNewEmailTool(server, ctx) {
           items.push(candidate);
           byAccount.set(candidate.account.email, items);
         }
-        for (const [email, accountCandidates] of byAccount) {
-          const provider = providersByEmail.get(email);
-          const account = accountsByEmail.get(email);
-          if (!provider || !account) continue;
-          try {
-            emails.push(
-              ...await hydrateAndAdvance(
-                store,
-                provider,
-                account,
-                accountCandidates,
-                logger
-              )
-            );
-          } catch (err) {
-            logger.debug("get-new-emails", "accountError", {
-              account: email,
-              message: errMsg(err)
-            });
-            errors.push({ account: email, message: errMsg(err) });
+        const hydratedByAccount = await Promise.all(
+          [...byAccount].map(async ([email, accountCandidates]) => {
+            const provider = providersByEmail.get(email);
+            const account = accountsByEmail.get(email);
+            if (!provider || !account) return { status: "ok", emails: [] };
+            try {
+              return {
+                status: "ok",
+                emails: await hydrateAndAdvance(store, provider, account, accountCandidates, logger)
+              };
+            } catch (err) {
+              const message = errMsg(err);
+              logger.debug("get-new-emails", "accountError", { account: email, message });
+              return {
+                status: "error",
+                account: email,
+                message
+              };
+            }
+          })
+        );
+        for (const result of hydratedByAccount) {
+          if (result.status === "error") {
+            errors.push({ account: result.account, message: result.message });
+            continue;
           }
+          emails.push(...result.emails);
         }
       }
       const orderedEmails = emails.sort(compareNewEmailOutputOldestFirst);
@@ -18082,10 +18178,15 @@ function registerBrowseTools(server, ctx) {
     skip: z5.number(),
     hasMore: z5.boolean()
   });
+  const searchEmailSummaryOutputSchema = emailSummaryOutputSchema.extend({
+    account: z5.string()
+  });
   const searchEmailsOutputSchema = z5.object({
     account: z5.string(),
     count: z5.number(),
-    items: z5.array(emailSummaryOutputSchema)
+    items: z5.array(searchEmailSummaryOutputSchema),
+    accounts: z5.array(z5.string()).optional(),
+    errors: z5.array(z5.object({ account: z5.string(), message: z5.string() })).optional()
   });
   if (shouldRegister("list_emails", tools)) {
     server.registerTool(
@@ -18129,29 +18230,67 @@ function registerBrowseTools(server, ctx) {
     server.registerTool(
       "search_emails",
       {
-        description: "Search emails by free-text query (KQL on Outlook). Returns lightweight summaries.",
+        description: "Search emails by free-text query (KQL on Outlook). Returns lightweight summaries. Pass `account` to search one account, or omit it to search all registered accounts in parallel.",
         inputSchema: z5.object({
-          account: z5.string().email(),
+          account: z5.string().email().optional(),
           query: z5.string().min(1),
           limit: z5.number().int().positive().max(100).optional()
         }),
         outputSchema: searchEmailsOutputSchema
       },
       async (args) => {
-        try {
-          const { provider, account } = registry.resolveByEmail(args.account);
-          const items = await provider.searchEmails(account, args.query, {
-            limit: args.limit
-          });
-          const data = {
-            account: account.email,
-            count: items.length,
-            items
-          };
-          return ok(data, data);
-        } catch (err) {
-          return fail(errMsg(err));
+        if (args.account) {
+          try {
+            const { provider, account } = registry.resolveByEmail(args.account);
+            const items2 = await provider.searchEmails(account, args.query, {
+              limit: args.limit
+            });
+            const data2 = {
+              account: account.email,
+              count: items2.length,
+              items: items2.map((item) => ({ ...item, account: account.email })),
+              errors: []
+            };
+            return ok(data2, data2);
+          } catch (err) {
+            return fail(errMsg(err));
+          }
+        }
+        const accounts = store.listAccounts();
+        if (accounts.length === 0) {
+          return fail("no accounts registered. Call add_account first.");
         }
+        const results = await Promise.all(
+          accounts.map(async (stored) => {
+            try {
+              const { provider, account } = registry.resolveByEmail(stored.email);
+              const items2 = await provider.searchEmails(account, args.query, {
+                limit: args.limit
+              });
+              return {
+                account: account.email,
+                items: items2.map((item) => ({ ...item, account: account.email }))
+              };
+            } catch (err) {
+              return {
+                account: stored.email,
+                error: errMsg(err)
+              };
+            }
+          })
+        );
+        const items = results.flatMap((result) => result.items ?? []);
+        const errors = results.filter(
+          (result) => "error" in result
+        ).map((result) => ({ account: result.account, message: result.error }));
+        const data = {
+          account: "all",
+          accounts: accounts.map((account) => account.email),
+          count: items.length,
+          items,
+          errors
+        };
+        return ok(data, data);
       }
     );
   }
@@ -18999,7 +19138,7 @@ function registerTools(server, opts) {
 // package.json
 var package_default = {
   name: "hypermail-mcp",
-  version: "0.7.17",
+  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: {