hypermail-mcp 0.4.2 → 0.5.0

package/README.md

@@ -3,6 +3,15 @@
 A **Model Context Protocol** server that lets an agent operate any of the user's
 inboxes through a single, unified tool surface.
 
+> **v0.5.0** — Replaced optional `isHtml` boolean with required `format`
+> parameter (`"html"` | `"markdown"`) on `send_email`, `draft_email`, and
+> `edit_draft`. Markdown bodies are converted to HTML via `marked` so
+> recipients always see clean HTML.
+>
+> **v0.4.3** — Upgraded Zod to v4.4.3. Fixed MCP SDK v1.29.0 compatibility
+> by wrapping all tool schemas in `z.object()` and replacing discriminated
+> union output schemas that caused `validateToolOutput` crashes.
+
 The agent doesn't care whether an address is a work Outlook account, a personal
 Microsoft account, or (soon) a personal IMAP mailbox — it just calls
 `list_emails`, `search_emails`, `read_email`, `send_email` and passes the email
@@ -117,9 +126,9 @@ account store.
 | `archive_email` | `account`, `id` | Move a message to the Archive folder. Disabled under `--read-only`. |
 | `trash_email` | `account`, `id` | Move a message to Deleted Items (trash). Disabled under `--read-only`. |
 | `move_email` | `account`, `id`, `destination` | Move to any folder by well-known name (`inbox`, `drafts`, etc.) or custom folder ID. Disabled under `--read-only`. |
-| `send_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `isHtml?`, `include_signature?`, `inReplyTo?`, `replyAll?`, `forwardMessageId?` | Send an email. Appends signature when `include_signature` is true. `inReplyTo` sends as threaded reply; `forwardMessageId` sends as forward. Disabled under `--read-only`. |
-| `draft_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `isHtml?`, `include_signature?`, `inReplyTo?`, `replyAll?`, `forwardMessageId?` | Save as draft instead of sending. Returns the draft message ID and HTML body (`draftHtml`). Disabled under `--read-only`. |
-| `edit_draft` | `account`, `id`, `to?`, `cc?`, `bcc?`, `subject?`, `body?`, `isHtml?`, `include_signature?` | Edit an existing draft by ID. Only provided fields are updated. Returns the updated draft ID and HTML body (`draftHtml`). Disabled under `--read-only`. |
+| `send_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `format`, `include_signature?`, `inReplyTo?`, `replyAll?`, `forwardMessageId?` | Send an email. `format` (`"html"` or `"markdown"`) controls body format — Markdown is converted to HTML via `marked`. Appends signature when `include_signature` is true. `inReplyTo` sends as threaded reply; `forwardMessageId` sends as forward. Disabled under `--read-only`. |
+| `draft_email` | `account`, `to[]`, `cc?`, `bcc?`, `subject`, `body`, `format`, `include_signature?`, `inReplyTo?`, `replyAll?`, `forwardMessageId?` | Save as draft instead of sending. `format` (`"html"` or `"markdown"`) controls body format — Markdown is converted to HTML via `marked`. Returns the draft message ID and HTML body (`draftHtml`). Disabled under `--read-only`. |
+| `edit_draft` | `account`, `id`, `to?`, `cc?`, `bcc?`, `subject?`, `body?`, `format?`, `include_signature?` | Edit an existing draft by ID. Only provided fields are updated. `format` only meaningful when `body` is provided. Returns the updated draft ID and HTML body (`draftHtml`). Disabled under `--read-only`. |
 | `send_draft` | `account`, `id` | Send an existing draft email by ID. Use with draft IDs returned by `draft_email` or `edit_draft`. Disabled under `--read-only`. |
 | `add_attachment_to_draft` | `account`, `id`, `path` | Attach a local file to an existing draft email. Disabled under `--read-only`. |
 | `list_folders` | `account`, `parentFolderId?` | List available mail folders. Returns top-level folders by default, or children of `parentFolderId`. |

package/dist/cli.js

@@ -2459,6 +2459,14 @@ function buildRegistry(opts) {
 
 // src/tools/shared.ts
 import { z } from "zod";
+
+// src/markdown-to-html.ts
+import { marked } from "marked";
+function markdownToHtml(md) {
+  return marked.parse(md, { async: false });
+}
+
+// src/tools/shared.ts
 function ok(data, structuredContent) {
   const result = {
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
@@ -2504,7 +2512,7 @@ var accountFullOutputSchema = z.object({
   email: z.string(),
   provider: providerIdEnum,
   displayName: z.string().optional(),
-  tokens: z.record(z.unknown()),
+  tokens: z.record(z.string(), z.unknown()),
   addedAt: z.string(),
   signature: z.string().optional(),
   style: styleOutputSchema.optional()
@@ -2535,21 +2543,15 @@ var folderInfoOutputSchema = z.object({
   unreadItemCount: z.number()
 });
 function composeBody(input) {
-  const { body, isHtml = false, signature, style, includeSignature } = input;
+  const { body, format, signature, style, includeSignature } = input;
+  const htmlBody = format === "markdown" ? markdownToHtml(body) : body;
   const hasSignature = includeSignature && !!signature;
   const hasStyle = !!(style && (style.fontFamily || style.fontSize || style.fontColor));
   if (!hasSignature && !hasStyle) {
-    return { body, isHtml };
+    return { body: htmlBody, isHtml: true };
   }
   const styleAttr = hasStyle ? buildStyleAttr(style) : "";
-  if (isHtml) {
-    let result2 = hasStyle ? `<div style="${styleAttr}">${body}</div>` : body;
-    if (hasSignature) result2 += `
-<div class="signature">${signature}</div>`;
-    return { body: result2, isHtml: true };
-  }
-  const escaped = escapeHtml(body);
-  let result = `<div style="${styleAttr}">${escaped}</div>`;
+  let result = hasStyle ? `<div style="${styleAttr}">${htmlBody}</div>` : htmlBody;
   if (hasSignature) result += `
 <div class="signature">${signature}</div>`;
   return { body: result, isHtml: true };
@@ -2561,9 +2563,6 @@ function buildStyleAttr(style) {
   if (style.fontColor) parts.push(`color: ${style.fontColor}`);
   return parts.join("; ");
 }
-function escapeHtml(text) {
-  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/\n/g, "<br>");
-}
 function shouldRegister(name, tools) {
   if (tools.enabledTools) {
     return tools.enabledTools.has(name);
@@ -2578,15 +2577,15 @@ function shouldRegister(name, tools) {
 import { z as z2 } from "zod";
 function registerAccountTools(server, ctx) {
   const { store, registry, tools } = ctx;
-  const listAccountsOutputSchema = {
+  const listAccountsOutputSchema = z2.object({
     accounts: z2.array(accountSummaryOutputSchema)
-  };
+  });
   if (shouldRegister("list_accounts", tools)) {
     server.registerTool(
       "list_accounts",
       {
         description: "List all email accounts known to this server (no secrets). Use the returned `email` value as the `account` argument to other tools.",
-        inputSchema: {},
+        inputSchema: z2.object({}),
         outputSchema: listAccountsOutputSchema
       },
       async () => {
@@ -2603,36 +2602,31 @@ function registerAccountTools(server, ctx) {
       }
     );
   }
-  const addAccountOutputSchema = z2.discriminatedUnion("status", [
-    z2.object({
-      status: z2.literal("pending"),
-      handle: z2.string(),
-      verification: z2.object({
-        userCode: z2.string(),
-        verificationUri: z2.string(),
-        expiresAt: z2.string(),
-        message: z2.string()
-      })
-    }),
-    z2.object({
-      status: z2.literal("ready"),
-      account: accountFullOutputSchema
-    })
-  ]);
+  const addAccountOutputSchema = z2.object({
+    status: z2.enum(["pending", "ready"]),
+    handle: z2.string().optional(),
+    verification: z2.object({
+      userCode: z2.string(),
+      verificationUri: z2.string(),
+      expiresAt: z2.string(),
+      message: z2.string()
+    }).optional(),
+    account: accountFullOutputSchema.optional()
+  });
   if (shouldRegister("add_account", tools)) {
     server.registerTool(
       "add_account",
       {
         description: "Start adding an email account. For Outlook this returns a device code the user must enter at the verification URL; then call `complete_add_account` with the returned `handle` to finalize. Disabled in --read-only mode.",
-        inputSchema: {
+        inputSchema: z2.object({
           provider: providerIdEnum.describe("Email backend. 'outlook' (Microsoft Graph) and 'imap' are fully implemented."),
           email: z2.string().email().optional().describe(
             "Optional hint \u2014 the provider will verify it against the auth result."
           ),
-          config: z2.record(z2.unknown()).optional().describe(
+          config: z2.record(z2.string(), z2.unknown()).optional().describe(
             "Provider-specific config (e.g. IMAP host/port). Unused for Outlook."
           )
-        },
+        }),
         outputSchema: addAccountOutputSchema
       },
       async (args) => {
@@ -2659,10 +2653,10 @@ function registerAccountTools(server, ctx) {
       "complete_add_account",
       {
         description: "Poll/finalize a pending add_account flow. Returns `pending` until the user completes the device-code step, then `ready` with the persisted account.",
-        inputSchema: {
+        inputSchema: z2.object({
           provider: providerIdEnum,
           handle: z2.string().min(1)
-        },
+        }),
         outputSchema: completeAddAccountOutputSchema
       },
       async (args) => {
@@ -2681,16 +2675,16 @@ function registerAccountTools(server, ctx) {
       }
     );
   }
-  const accountSettingsOutputSchema = {
+  const accountSettingsOutputSchema = z2.object({
     signature: z2.string().nullable(),
     style: styleOutputSchema.nullable()
-  };
+  });
   if (shouldRegister("get_account_settings", tools)) {
     server.registerTool(
       "get_account_settings",
       {
         description: "Get signature (HTML) and style preferences for an account.",
-        inputSchema: { account: z2.string().email() },
+        inputSchema: z2.object({ account: z2.string().email() }),
         outputSchema: accountSettingsOutputSchema
       },
       async (args) => {
@@ -2714,7 +2708,7 @@ function registerAccountTools(server, ctx) {
       "set_account_settings",
       {
         description: "Set signature (HTML snippet) and/or style preferences for an account. Disabled in --read-only mode.",
-        inputSchema: {
+        inputSchema: z2.object({
           account: z2.string().email(),
           signature: z2.string().optional().describe(
             "HTML snippet \u2014 may contain formatting, images, links. Pass null to clear."
@@ -2726,7 +2720,7 @@ function registerAccountTools(server, ctx) {
           }).optional().describe(
             "Font preferences applied to outgoing HTML emails. Pass null to clear."
           )
-        },
+        }),
         outputSchema: accountSettingsOutputSchema
       },
       async (args) => {
@@ -2750,16 +2744,16 @@ function registerAccountTools(server, ctx) {
       }
     );
   }
-  const removeAccountOutputSchema = {
+  const removeAccountOutputSchema = z2.object({
     removed: z2.boolean(),
     email: z2.string()
-  };
+  });
   if (shouldRegister("remove_account", tools)) {
     server.registerTool(
       "remove_account",
       {
         description: "Forget an account and delete its stored tokens. Disabled in --read-only mode.",
-        inputSchema: { email: z2.string().email() },
+        inputSchema: z2.object({ email: z2.string().email() }),
         outputSchema: removeAccountOutputSchema
       },
       async (args) => {
@@ -2803,30 +2797,30 @@ function selectBody(msg, format) {
 // src/tools/browse.ts
 function registerBrowseTools(server, ctx) {
   const { registry, tools } = ctx;
-  const emailListOutputSchema = {
+  const emailListOutputSchema = z3.object({
     account: z3.string(),
     count: z3.number(),
     items: z3.array(emailSummaryOutputSchema),
     skip: z3.number(),
     hasMore: z3.boolean()
-  };
-  const searchEmailsOutputSchema = {
+  });
+  const searchEmailsOutputSchema = z3.object({
     account: z3.string(),
     count: z3.number(),
     items: z3.array(emailSummaryOutputSchema)
-  };
+  });
   if (shouldRegister("list_emails", tools)) {
     server.registerTool(
       "list_emails",
       {
         description: "List recent emails in a folder of the given account. Pass the user's email address as `account`; the server routes to the correct backend automatically.",
-        inputSchema: {
+        inputSchema: z3.object({
           account: z3.string().email(),
           folder: z3.string().default("inbox").optional(),
           limit: z3.number().int().positive().max(100).optional(),
           unreadOnly: z3.boolean().optional(),
           skip: z3.number().int().min(0).optional()
-        },
+        }),
         outputSchema: emailListOutputSchema
       },
       async (args) => {
@@ -2857,11 +2851,11 @@ function registerBrowseTools(server, ctx) {
       "search_emails",
       {
         description: "Search emails by free-text query (KQL on Outlook). Returns lightweight summaries.",
-        inputSchema: {
+        inputSchema: z3.object({
           account: z3.string().email(),
           query: z3.string().min(1),
           limit: z3.number().int().positive().max(100).optional()
-        },
+        }),
         outputSchema: searchEmailsOutputSchema
       },
       async (args) => {
@@ -2882,7 +2876,7 @@ function registerBrowseTools(server, ctx) {
       }
     );
   }
-  const readEmailOutputSchema = {
+  const readEmailOutputSchema = z3.object({
     id: z3.string(),
     subject: z3.string(),
     from: emailAddrOutputSchema.optional(),
@@ -2897,19 +2891,19 @@ function registerBrowseTools(server, ctx) {
     attachments: z3.array(attachmentMetaOutputSchema).optional(),
     body: z3.string(),
     bodyFormat: z3.enum(["markdown", "html", "text"])
-  };
+  });
   if (shouldRegister("read_email", tools)) {
     server.registerTool(
       "read_email",
       {
         description: "Fetch a single email with full body and recipients by id. Body is returned as `body` with `bodyFormat` indicating the format. Default format is 'markdown' \u2014 HTML is automatically converted to save context tokens.",
-        inputSchema: {
+        inputSchema: z3.object({
           account: z3.string().email(),
           id: z3.string().min(1),
           format: z3.enum(["markdown", "html", "text"]).default("markdown").optional().describe(
             "Output body format. 'markdown' converts HTML to Markdown (default), 'html' returns the raw HTML, 'text' returns plain text."
           )
-        },
+        }),
         outputSchema: readEmailOutputSchema
       },
       async (args) => {
@@ -2941,21 +2935,21 @@ function registerBrowseTools(server, ctx) {
       }
     );
   }
-  const readAttachmentOutputSchema = {
+  const readAttachmentOutputSchema = z3.object({
     name: z3.string(),
     contentType: z3.string().optional(),
     path: z3.string()
-  };
+  });
   if (shouldRegister("read_attachment", tools)) {
     server.registerTool(
       "read_attachment",
       {
         description: "Download an email attachment to a temporary file and return its path. Use messageId and attachmentId from a prior read_email call.",
-        inputSchema: {
+        inputSchema: z3.object({
           account: z3.string().email(),
           messageId: z3.string().min(1),
           attachmentId: z3.string().min(1)
-        },
+        }),
         outputSchema: readAttachmentOutputSchema
       },
       async (args) => {
@@ -2979,22 +2973,22 @@ function registerBrowseTools(server, ctx) {
 import { z as z4 } from "zod";
 function registerFolderTools(server, ctx) {
   const { registry, tools } = ctx;
-  const listFoldersOutputSchema = {
+  const listFoldersOutputSchema = z4.object({
     account: z4.string(),
     count: z4.number(),
     items: z4.array(folderInfoOutputSchema)
-  };
+  });
   if (shouldRegister("list_folders", tools)) {
     server.registerTool(
       "list_folders",
       {
         description: "List available mail folders. Returns top-level folders by default, or child folders of the given parent when `parentFolderId` is provided.",
-        inputSchema: {
+        inputSchema: z4.object({
           account: z4.string().email(),
           parentFolderId: z4.string().optional().describe(
             "When provided, lists child folders of this folder. When omitted, lists top-level folders (children of the root)."
           )
-        },
+        }),
         outputSchema: listFoldersOutputSchema
       },
       async (args) => {
@@ -3015,22 +3009,22 @@ function registerFolderTools(server, ctx) {
       }
     );
   }
-  const createFolderOutputSchema = {
+  const createFolderOutputSchema = z4.object({
     created: z4.literal(true),
     folder: folderInfoOutputSchema
-  };
+  });
   if (shouldRegister("create_folder", tools)) {
     server.registerTool(
       "create_folder",
       {
         description: "Create a new mail folder. Creates under the root folder by default, or under the specified parent when `parentFolderId` is provided. Disabled in --read-only mode.",
-        inputSchema: {
+        inputSchema: z4.object({
           account: z4.string().email(),
           displayName: z4.string().min(1).describe("Name of the new folder"),
           parentFolderId: z4.string().optional().describe(
             "When provided, creates the folder as a child of this folder. When omitted, creates under the root folder."
           )
-        },
+        }),
         outputSchema: createFolderOutputSchema
       },
       async (args) => {
@@ -3048,19 +3042,19 @@ function registerFolderTools(server, ctx) {
       }
     );
   }
-  const deleteFolderOutputSchema = {
+  const deleteFolderOutputSchema = z4.object({
     deleted: z4.literal(true),
     id: z4.string()
-  };
+  });
   if (shouldRegister("delete_folder", tools)) {
     server.registerTool(
       "delete_folder",
       {
         description: "Delete a mail folder by ID. Disabled in --read-only mode.",
-        inputSchema: {
+        inputSchema: z4.object({
           account: z4.string().email(),
           folderId: z4.string().min(1).describe("ID of the folder to delete")
-        },
+        }),
         outputSchema: deleteFolderOutputSchema
       },
       async (args) => {
@@ -3075,20 +3069,20 @@ function registerFolderTools(server, ctx) {
       }
     );
   }
-  const renameFolderOutputSchema = {
+  const renameFolderOutputSchema = z4.object({
     renamed: z4.literal(true),
     folder: folderInfoOutputSchema
-  };
+  });
   if (shouldRegister("rename_folder", tools)) {
     server.registerTool(
       "rename_folder",
       {
         description: "Rename an existing mail folder. Disabled in --read-only mode.",
-        inputSchema: {
+        inputSchema: z4.object({
           account: z4.string().email(),
           folderId: z4.string().min(1).describe("ID of the folder to rename"),
           newName: z4.string().min(1).describe("New display name for the folder")
-        },
+        }),
         outputSchema: renameFolderOutputSchema
       },
       async (args) => {
@@ -3126,14 +3120,14 @@ function registerOrganizeTools(server, ctx) {
     const data = { marked: true, id: args.id, isRead };
     return ok(data, data);
   }
-  const archiveMoveSchema = {
+  const archiveMoveSchema = z5.object({
     account: z5.string().email(),
     id: z5.string().min(1).describe("Message ID to move")
-  };
-  const archiveOutputSchema = {
+  });
+  const archiveOutputSchema = z5.object({
     archived: z5.literal(true),
     id: z5.string()
-  };
+  });
   if (shouldRegister("archive_email", tools)) {
     server.registerTool(
       "archive_email",
@@ -3151,10 +3145,10 @@ function registerOrganizeTools(server, ctx) {
       }
     );
   }
-  const trashOutputSchema = {
+  const trashOutputSchema = z5.object({
     trashed: z5.literal(true),
     id: z5.string()
-  };
+  });
   if (shouldRegister("trash_email", tools)) {
     server.registerTool(
       "trash_email",
@@ -3172,23 +3166,23 @@ function registerOrganizeTools(server, ctx) {
       }
     );
   }
-  const moveEmailOutputSchema = {
+  const moveEmailOutputSchema = z5.object({
     moved: z5.literal(true),
     id: z5.string(),
     destination: z5.string()
-  };
+  });
   if (shouldRegister("move_email", tools)) {
     server.registerTool(
       "move_email",
       {
         description: "Move a message to any folder by well-known name (e.g. 'inbox', 'drafts', 'junkemail', 'sentitems', 'outbox') or custom folder ID. Disabled in --read-only mode.",
-        inputSchema: {
+        inputSchema: z5.object({
           account: z5.string().email(),
           id: z5.string().min(1).describe("Message ID to move"),
           destination: z5.string().min(1).describe(
             "Destination folder \u2014 a well-known folder name ('archive', 'deleteditems', 'inbox', 'drafts', 'junkemail', 'sentitems', 'outbox') or a raw folder ID."
           )
-        },
+        }),
         outputSchema: moveEmailOutputSchema
       },
       async (args) => {
@@ -3207,15 +3201,15 @@ function registerOrganizeTools(server, ctx) {
       }
     );
   }
-  const markReadInputSchema = {
+  const markReadInputSchema = z5.object({
     account: z5.string().email(),
     id: z5.string().min(1).describe("Message ID to mark as read")
-  };
-  const markReadOutputSchema = {
+  });
+  const markReadOutputSchema = z5.object({
     marked: z5.literal(true),
     id: z5.string(),
     isRead: z5.boolean()
-  };
+  });
   if (shouldRegister("mark_read", tools)) {
     server.registerTool(
       "mark_read",
@@ -3263,7 +3257,9 @@ function registerComposeTools(server, ctx) {
     bcc: z6.array(emailAddrSchema).optional(),
     subject: z6.string(),
     body: z6.string(),
-    isHtml: z6.boolean().optional(),
+    format: z6.enum(["html", "markdown"]).describe(
+      "Body format. 'html' sends the body as-is (must be valid HTML). 'markdown' converts the body from Markdown to HTML for clean rendering on the recipient side."
+    ),
     include_signature: z6.boolean().describe(
       "Whether to append the account's saved HTML signature to the email. If true, don't include a signature in the body param to avoid double signature. Returns an error if true but no signature is configured for this account."
     ),
@@ -3287,7 +3283,7 @@ function registerComposeTools(server, ctx) {
       }
       const composed = composeBody({
         body: args.body,
-        isHtml: args.isHtml,
+        format: args.format,
         signature: account.signature,
         style: account.style,
         includeSignature: args.include_signature
@@ -3367,7 +3363,9 @@ function registerComposeTools(server, ctx) {
     bcc: z6.array(emailAddrSchema).optional(),
     subject: z6.string().optional(),
     body: z6.string().optional(),
-    isHtml: z6.boolean().optional(),
+    format: z6.enum(["html", "markdown"]).optional().describe(
+      "Body format. Only meaningful when `body` is also provided. 'html' sends the body as-is (must be valid HTML). 'markdown' converts the body from Markdown to HTML for clean rendering on the recipient side."
+    ),
     include_signature: z6.boolean().optional().describe(
       "Whether to re-apply the account's saved HTML signature to the body. If true, don't include a signature in the body param. Only meaningful when `body` is also provided. Returns an error if true but no signature is configured for this account."
     )
@@ -3399,7 +3397,7 @@ function registerComposeTools(server, ctx) {
           if (a.body !== void 0) {
             const composed = composeBody({
               body: a.body,
-              isHtml: a.isHtml,
+              format: a.format ?? "html",
               signature: account.signature,
               style: account.style,
               includeSignature: !!a.include_signature