@emailens/mcp 0.12.1 → 0.13.0

package/dist/index.js

@@ -123,7 +123,7 @@ import {
   toPlainText,
   checkDesignRetention,
   EMAIL_CLIENTS as EMAIL_CLIENTS2,
-  MAX_HTML_SIZE
+  MAX_HTML_SIZE as MAX_HTML_SIZE2
 } from "@emailens/engine";
 
 // src/config.ts
@@ -167,6 +167,46 @@ function firstDraft(html) {
   return html;
 }
 
+// src/source.ts
+import { readFile, realpath, stat } from "fs/promises";
+import { extname } from "path";
+import { MAX_HTML_SIZE } from "@emailens/engine";
+var EXTENSIONS = {
+  ".html": void 0,
+  ".htm": void 0,
+  ".mjml": "mjml",
+  ".jsx": "jsx",
+  ".tsx": "jsx",
+  ".vue": "maizzle"
+};
+async function readSource(html, path, format, names = { html: "html", path: "path" }) {
+  if (html === void 0 === (path === void 0)) {
+    return { ok: false, message: `Pass exactly one of \`${names.html}\` (the source) or \`${names.path}\` (a file holding it).` };
+  }
+  if (html !== void 0) return { ok: true, html, format };
+  let real;
+  try {
+    real = await realpath(path);
+  } catch {
+    return { ok: false, message: `No file at ${path}. Pass an absolute path, or the source itself as \`${names.html}\`.` };
+  }
+  const ext = extname(real).toLowerCase();
+  if (!(ext in EXTENSIONS)) {
+    return { ok: false, message: `${path} is not an email source. Accepted: ${Object.keys(EXTENSIONS).join(", ")}.` };
+  }
+  const info = await stat(real);
+  if (!info.isFile()) return { ok: false, message: `${path} is not a file.` };
+  if (info.size > MAX_HTML_SIZE) {
+    return { ok: false, message: `${path} exceeds the ${Math.round(MAX_HTML_SIZE / 1024)}KB limit.` };
+  }
+  return { ok: true, html: await readFile(real, "utf8"), format: format ?? EXTENSIONS[ext], path: real };
+}
+function withoutSource(prompt, html, format, path) {
+  return prompt.replace(`\`\`\`${format}
+${html}
+\`\`\``, () => `The source is in \`${path}\`. Read and edit it there.`);
+}
+
 // src/hosted.ts
 async function apiRequest(path, options) {
   const { apiKey, apiUrl, method = "GET", body, timeoutMs = 3e4 } = options;
@@ -255,8 +295,10 @@ function worstScore(scores) {
 }
 var formatEnum = z.enum(["html", "jsx", "mjml", "maizzle"]).optional();
 var detailEnum = z.enum(["summary", "full"]).optional().describe(
-  "'summary' (default) returns one entry per problem, listing the clients it affects (roughly 10x smaller). 'full' returns one entry per client with fix snippets."
+  "'summary' (default) returns one entry per error or warning, listing the clients it affects, and only counts info findings (safe fallbacks). 'full' returns one entry per client with fix snippets, info included."
 );
+var htmlParam = z.string().optional().describe("The email source: HTML, or an MJML / Maizzle / React Email template when `format` says so. Pass this or `path`.");
+var pathParam = z.string().optional().describe("Absolute path to the email source file (.html, .htm, .mjml, .jsx, .tsx, .vue), instead of `html`. Prefer it when the email is on disk: the source stays out of your context. The extension sets `format` unless you pass one.");
 var targetingPolicyEnum = z.enum(["progressive", "strict", "lenient"]).optional().describe(
   "'progressive' (default) suppresses compatibility false-positives inside client-targeted scopes and only flags deprecated or dangerous hacks. 'strict' treats targeting as non-standard and reports every hack. 'lenient' suppresses false positives and ignores non-fatal targeting warnings."
 );
@@ -307,11 +349,14 @@ function compatibilityPayload(warnings, detail, clients) {
       }))
     };
   }
-  const findings = collapseWarnings(scoped);
+  const collapsed = collapseWarnings(scoped);
+  const findings = collapsed.filter((f) => f.severity !== "info");
+  const info = collapsed.length - findings.length;
   return {
     warningCount: scoped.length,
     findingCount: findings.length,
-    findings
+    findings,
+    ...info ? { infoFindings: info, infoNote: "Safe fallbacks, not problems. Pass detail:'full' to list them." } : {}
   };
 }
 function positionsApply(format) {
@@ -328,14 +373,14 @@ function withPositions(w) {
   };
 }
 function validateHtmlSize(html) {
-  if (html.length > MAX_HTML_SIZE) {
-    return mcpError(`HTML input exceeds ${Math.round(MAX_HTML_SIZE / 1024)}KB limit. Reduce the email size and try again.`);
+  if (html.length > MAX_HTML_SIZE2) {
+    return mcpError(`HTML input exceeds ${Math.round(MAX_HTML_SIZE2 / 1024)}KB limit. Reduce the email size and try again.`);
   }
   return null;
 }
 var server = new McpServer({
   name: "emailens",
-  version: "0.12.1"
+  version: "0.13.0"
 });
 server.registerTool(
   "preview_email",
@@ -343,7 +388,8 @@ server.registerTool(
     title: "Preview Email",
     description: `Full email compatibility preview, transforms HTML for ${EMAIL_CLIENTS2.length} email clients (Gmail, Outlook, Apple Mail, Yahoo, Samsung, Thunderbird, HEY, Proton Mail, AOL, Fastmail, Superhuman), analyzes CSS, generates scores, simulates dark mode, checks inbox preview and email size.`,
     inputSchema: {
-      html: z.string().describe("The email source: HTML, or an MJML / Maizzle / React Email template when `format` says so"),
+      html: htmlParam,
+      path: pathParam,
       clients: z.array(z.string()).optional().describe("Optional client ID filter (e.g. ['gmail-web', 'outlook-windows'])"),
       format: formatEnum.describe("Source format: 'html' (default), 'jsx' (React Email), 'mjml', or 'maizzle' (HTML template or Vue single-file component). Anything but 'html' is compiled before analysis and sets the syntax of the fix snippets. A pasted Vue file with no format is compiled as maizzle."),
       targetingPolicy: targetingPolicyEnum
@@ -356,7 +402,10 @@ server.registerTool(
       openWorldHint: false
     }
   },
-  async ({ html, clients, format, targetingPolicy }) => {
+  async ({ html: inline, path, clients, format: given, targetingPolicy }) => {
+    const input = await readSource(inline, path, given);
+    if (!input.ok) return mcpError(input.message);
+    const { html, format } = input;
     const sizeError = validateHtmlSize(html);
     if (sizeError) return sizeError;
     const source = await toHtml(html, format);
@@ -369,7 +418,7 @@ server.registerTool(
       const filter = clients.filter((c) => validClientIds.has(c));
       if (filter.length === 0) {
         return mcpError(
-          JSON.stringify({ error: "No valid client IDs provided", validClientIds: Array.from(validClientIds) }, null, 2)
+          JSON.stringify({ error: "No valid client IDs provided", validClientIds: Array.from(validClientIds) })
         );
       }
       transforms = filter.map((c) => transformForClient(source.html, c, framework));
@@ -413,7 +462,7 @@ server.registerTool(
     if (!config.isHosted) {
       result.tip = overallScore < 90 ? "Capture real screenshots to verify these issues across clients. Add EMAILENS_API_KEY to your MCP config \u2192 app.emailens.dev/dashboard/api?utm_source=mcp" : "Checked by Emailens against 21 email clients. Confirm on real Outlook, Gmail and Apple Mail \u2192 emailens.dev/real-devices?utm_source=mcp";
     }
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
   }
 );
 server.registerTool(
@@ -422,7 +471,8 @@ server.registerTool(
     title: "Analyze Email",
     description: "Fix error and warning findings. Info findings are not problems (the email falls back safely there): never remove responsive (@media) or dark-mode CSS to clear them. Quick CSS compatibility analysis, returns per-client scores and one finding per problem, listing the clients it affects. For HTML input each finding carries loc (line, column, offset) and alsoAtLines, so you can edit the exact source. Narrow with clients, or pass detail:'full' for the per-client breakdown with fix snippets. Use audit_email for a full quality report (spam, links, a11y, images, etc.).",
     inputSchema: {
-      html: z.string().describe("The email source: HTML, or an MJML / Maizzle / React Email template when `format` says so"),
+      html: htmlParam,
+      path: pathParam,
       format: formatEnum.describe("Source format: 'html' (default), 'jsx' (React Email), 'mjml', or 'maizzle' (HTML template or Vue single-file component). Anything but 'html' is compiled before analysis and sets the syntax of the fix snippets. A pasted Vue file with no format is compiled as maizzle."),
       detail: detailEnum,
       clients: clientsParam,
@@ -436,7 +486,10 @@ server.registerTool(
       openWorldHint: false
     }
   },
-  async ({ html, format, detail, clients, targetingPolicy }) => {
+  async ({ html: inline, path, format: given, detail, clients, targetingPolicy }) => {
+    const input = await readSource(inline, path, given);
+    if (!input.ok) return mcpError(input.message);
+    const { html, format } = input;
     const sizeError = validateHtmlSize(html);
     if (sizeError) return sizeError;
     const clientError = validateClients(clients);
@@ -458,9 +511,7 @@ server.registerTool(
               overallScore,
               scores,
               ...compatibilityPayload(warnings, detail, clients)
-            },
-            null,
-            2
+            }
           )
         }
       ]
@@ -473,7 +524,8 @@ server.registerTool(
     title: "Audit Email",
     description: "Fix error and warning findings, and restore anything listed in designRemovals. Info findings are not problems (the email falls back safely there): never remove responsive (@media), dark-mode CSS or rounded corners to clear them. designRemovals compares this version with the first one audited for the same email (or with previousHtml): design the edits deleted, such as @media rules, dark mode, corners, gradients, VML fallbacks or images. Comprehensive email quality audit: CSS compatibility, spam scoring, link validation, accessibility, images, inbox preview, size (Gmail clipping), template variables, content overflow, visual fallbacks, dark-mode and mobile text contrast, design consistency, structural faults in Outlook-only VML (which lives inside conditional comments and is invisible to every other check), style survival: CSS a client parses correctly and then discards, such as a stylesheet past Gmail's 16 KB ceiling or every rule after a `}}`, which no support matrix can express, and client targeting: HowToTarget hacks such as Gmail u+.body or MSO conditionals, which do not score as css-hack. For HTML input, findings tied to a specific element carry loc (line, column, offset) so you can edit the exact source. Compatibility is collapsed to one finding per problem listing the clients it affects; pass detail:'full' for the per-client breakdown with fix snippets. Use skip to omit checks, targetingPolicy to change how targeted scopes affect scores, and clients to narrow which clients are reported.",
     inputSchema: {
-      html: z.string().describe("The email source: HTML, or an MJML / Maizzle / React Email template when `format` says so"),
+      html: htmlParam,
+      path: pathParam,
       format: formatEnum.describe("Source format: 'html' (default), 'jsx' (React Email), 'mjml', or 'maizzle' (HTML template or Vue single-file component). Anything but 'html' is compiled before analysis and sets the syntax of the fix snippets. A pasted Vue file with no format is compiled as maizzle."),
       skip: z.array(skipEnum).optional().describe("Checks to skip (e.g. ['spam', 'images'])"),
       detail: detailEnum,
@@ -490,7 +542,10 @@ server.registerTool(
       openWorldHint: false
     }
   },
-  async ({ html, format, skip, detail, clients, targetingPolicy, emailType, previousHtml }) => {
+  async ({ html: inline, path, format: given, skip, detail, clients, targetingPolicy, emailType, previousHtml }) => {
+    const input = await readSource(inline, path, given);
+    if (!input.ok) return mcpError(input.message);
+    const { html, format } = input;
     const sizeError = validateHtmlSize(html);
     if (sizeError) return sizeError;
     const clientError = validateClients(clients);
@@ -533,9 +588,7 @@ server.registerTool(
               design: report.design,
               styleSurvival: report.styleSurvival,
               targeting: report.targeting
-            },
-            null,
-            2
+            }
           )
         }
       ]
@@ -548,7 +601,8 @@ server.registerTool(
     title: "Fix Email",
     description: "Generate a structured fix prompt for email compatibility issues. Returns markdown with the original code, detected issues (CSS or structural), fix snippets, and format-specific instructions. Use after preview_email or analyze_email.",
     inputSchema: {
-      html: z.string().describe("The email source: HTML, or an MJML / Maizzle / React Email template when `format` says so: the source to fix"),
+      html: htmlParam,
+      path: pathParam,
       format: formatEnum.describe("Source format: 'html' (default), 'jsx' (React Email), 'mjml', or 'maizzle' (HTML template or Vue single-file component). Anything but 'html' is compiled before analysis and sets the syntax of the fix snippets. A pasted Vue file with no format is compiled as maizzle."),
       scope: z.enum(["all", "current"]).optional().describe("'all' (default) or 'current' (requires selectedClientId)"),
       selectedClientId: z.string().optional().describe("Client ID to scope fixes to (e.g. 'outlook-windows')")
@@ -561,7 +615,10 @@ server.registerTool(
       openWorldHint: false
     }
   },
-  async ({ html, format, scope, selectedClientId }) => {
+  async ({ html: inline, path, format: given, scope, selectedClientId }) => {
+    const input = await readSource(inline, path, given);
+    if (!input.ok) return mcpError(input.message);
+    const { html, format } = input;
     const sizeError = validateHtmlSize(html);
     if (sizeError) return sizeError;
     const source = await toHtml(html, format);
@@ -577,7 +634,7 @@ server.registerTool(
         content: [
           {
             type: "text",
-            text: JSON.stringify({ message: "No compatibility issues found \u2014 nothing to fix.", overallScore: 100 }, null, 2)
+            text: JSON.stringify({ message: "No compatibility issues found \u2014 nothing to fix.", overallScore: 100 })
           }
         ]
       };
@@ -614,12 +671,10 @@ server.registerTool(
                 truncated: estimate.truncated
               },
               note: "Apply the fixes in the prompt below. Structural issues require HTML restructuring (tables, VML conditionals), not just CSS changes."
-            },
-            null,
-            2
+            }
           )
         },
-        { type: "text", text: prompt }
+        { type: "text", text: input.path ? withoutSource(prompt, html, inputFormat, input.path) : prompt }
       ]
     };
   }
@@ -650,9 +705,7 @@ server.registerTool(
               engine: c.engine,
               darkModeSupport: c.darkModeSupport,
               ...c.deprecated ? { deprecated: c.deprecated } : {}
-            })),
-            null,
-            2
+            }))
           )
         }
       ]
@@ -665,8 +718,10 @@ server.registerTool(
     title: "Diff Emails",
     description: "Compare two email HTML versions, shows score changes, fixed issues, and newly introduced issues per client. Use after making fixes to verify improvements.",
     inputSchema: {
-      before: z.string().describe("Original email source"),
-      after: z.string().describe("Modified email source, in the same format"),
+      before: z.string().optional().describe("Original email source. Pass this or `beforePath`."),
+      after: z.string().optional().describe("Modified email source, in the same format. Pass this or `afterPath`."),
+      beforePath: z.string().optional().describe("Absolute path to the original source file, instead of `before`"),
+      afterPath: z.string().optional().describe("Absolute path to the modified source file, instead of `after`"),
       format: formatEnum.describe("Source format: 'html' (default), 'jsx' (React Email), 'mjml', or 'maizzle' (HTML template or Vue single-file component). Anything but 'html' is compiled before analysis and sets the syntax of the fix snippets. A pasted Vue file with no format is compiled as maizzle.")
     },
     annotations: {
@@ -677,7 +732,14 @@ server.registerTool(
       openWorldHint: false
     }
   },
-  async ({ before, after, format }) => {
+  async ({ before: beforeInline, after: afterInline, beforePath, afterPath, format: given }) => {
+    const beforeInput = await readSource(beforeInline, beforePath, given, { html: "before", path: "beforePath" });
+    if (!beforeInput.ok) return mcpError(beforeInput.message);
+    const afterInput = await readSource(afterInline, afterPath, given, { html: "after", path: "afterPath" });
+    if (!afterInput.ok) return mcpError(afterInput.message);
+    const before = beforeInput.html;
+    const after = afterInput.html;
+    const format = afterInput.format ?? beforeInput.format;
     const beforeSizeError = validateHtmlSize(before);
     if (beforeSizeError) return beforeSizeError;
     const afterSizeError = validateHtmlSize(after);
@@ -729,9 +791,7 @@ server.registerTool(
                 clientsUnchanged,
                 avgScoreDelta: results.length > 0 ? Math.round(totalDelta / results.length * 10) / 10 : 0
               }
-            },
-            null,
-            2
+            }
           )
         }
       ]
@@ -762,7 +822,7 @@ server.registerTool(
       }
       const report = await _checkDeliverability(domain);
       return {
-        content: [{ type: "text", text: JSON.stringify(report, null, 2) }]
+        content: [{ type: "text", text: JSON.stringify(report) }]
       };
     } catch (err) {
       const msg = err.message ?? String(err);
@@ -781,7 +841,8 @@ server.registerTool(
     title: "Capture Screenshots",
     description: "Capture real email screenshots across 21 clients (Gmail, Outlook, Apple Mail, etc.) with light and dark mode variants. Screenshots are rendered in real browsers and hosted on CDN. Requires EMAILENS_API_KEY env var \u2014 free plan at emailens.dev?utm_source=mcp.",
     inputSchema: {
-      html: z.string().describe("The email source: HTML, or an MJML / Maizzle / React Email template when `format` says so"),
+      html: htmlParam,
+      path: pathParam,
       format: formatEnum.describe("Input format"),
       clients: z.array(z.string()).optional().describe("Filter to specific client IDs"),
       modes: z.array(z.enum(["light", "dark"])).optional().describe("Screenshot modes (default: ['light'])"),
@@ -795,7 +856,10 @@ server.registerTool(
       openWorldHint: true
     }
   },
-  async ({ html, format, clients, modes, title: title2 }) => {
+  async ({ html: inline, path, format: given, clients, modes, title: title2 }) => {
+    const input = await readSource(inline, path, given);
+    if (!input.ok) return mcpError(input.message);
+    const { html, format } = input;
     if (!config.isHosted) {
       return noApiKeyError("capture_screenshots");
     }
@@ -836,9 +900,7 @@ server.registerTool(
                 captured: [],
                 failed: [],
                 note: `Preview created but screenshot capture failed: ${screenshotResult.error}. View the full preview at the URL above.`
-              },
-              null,
-              2
+              }
             )
           }
         ]
@@ -857,7 +919,7 @@ server.registerTool(
     if (ss.failed?.length > 0) {
       result.note = `${ss.failed.length} of ${(ss.captured?.length ?? 0) + ss.failed.length} screenshots failed: ${ss.failed.join(", ")}`;
     }
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    return { content: [{ type: "text", text: JSON.stringify(result) }] };
   }
 );
 server.registerTool(
@@ -866,7 +928,8 @@ server.registerTool(
     title: "Share Preview",
     description: "Create a shareable link for an email preview. Recipients see the full analysis without needing an account. Requires EMAILENS_API_KEY env var and Dev plan ($9/mo).",
     inputSchema: {
-      html: z.string().describe("The email source: HTML, or an MJML / Maizzle / React Email template when `format` says so"),
+      html: htmlParam,
+      path: pathParam,
       title: z.string().optional().describe("Display title for the share page"),
       format: formatEnum.describe("Input format")
     },
@@ -878,7 +941,10 @@ server.registerTool(
       openWorldHint: true
     }
   },
-  async ({ html, title: title2, format }) => {
+  async ({ html: inline, path, title: title2, format: given }) => {
+    const input = await readSource(inline, path, given);
+    if (!input.ok) return mcpError(input.message);
+    const { html, format } = input;
     if (!config.isHosted) {
       return noApiKeyError("share_preview", "Shareable links require the Dev plan ($9/mo).");
     }
@@ -898,9 +964,7 @@ server.registerTool(
             {
               shareUrl: `${config.apiUrl}/share/${result.data.id}`,
               expiresAt: result.data.expiresAt
-            },
-            null,
-            2
+            }
           )
         }
       ]
@@ -938,7 +1002,7 @@ server.registerTool(
       content: [
         {
           type: "text",
-          text: JSON.stringify(result.data, null, 2)
+          text: JSON.stringify(result.data)
         }
       ]
     };
@@ -984,7 +1048,7 @@ server.registerTool(
       content: [
         {
           type: "text",
-          text: JSON.stringify(result.data?.message ?? result.data, null, 2)
+          text: JSON.stringify(result.data?.message ?? result.data)
         }
       ]
     };
@@ -1022,7 +1086,7 @@ server.registerTool(
       content: [
         {
           type: "text",
-          text: JSON.stringify(result.data, null, 2)
+          text: JSON.stringify(result.data)
         }
       ]
     };
@@ -1059,7 +1123,7 @@ server.registerTool(
       content: [
         {
           type: "text",
-          text: JSON.stringify(result.data, null, 2)
+          text: JSON.stringify(result.data)
         }
       ]
     };