hypermail-mcp 0.7.16 → 0.7.17

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.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

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(),
@@ -18873,7 +18999,7 @@ function registerTools(server, opts) {
 // package.json
 var package_default = {
   name: "hypermail-mcp",
-  version: "0.7.16",
+  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: {