hypermail-mcp 0.7.16 → 0.7.18

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.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
+> `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
@@ -284,7 +297,7 @@ account store.
 | `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`. |
 | `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. |
+| `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`. |
 | `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. |
@@ -312,6 +325,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

@@ -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 {
@@ -17229,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({
@@ -17294,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(),
@@ -17713,20 +17839,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", {
@@ -17745,27 +17887,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);
@@ -17956,10 +18104,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(
@@ -18003,29 +18156,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);
       }
     );
   }
@@ -18873,7 +19064,7 @@ function registerTools(server, opts) {
 // package.json
 var package_default = {
   name: "hypermail-mcp",
-  version: "0.7.16",
+  version: "0.7.18",
   description: "Unified email MCP server \u2014 operate any inbox (Outlook now, IMAP/Gmail later) by passing an email address.",
   type: "module",
   bin: {