@marlinjai/email-mcp 1.3.0 → 1.4.0

package/README.md

@@ -103,7 +103,7 @@ npx @marlinjai/email-mcp setup
 # Optionally enter SMTP host and port for sending
 ```
 
-## Available Tools (25)
+## Available Tools (30)
 
 ### Account Management (4)
 
@@ -157,6 +157,18 @@ npx @marlinjai/email-mcp setup
 
 All batch tools accept a `sourceFolder` parameter for IMAP/iCloud and include a sequential fallback for maximum compatibility.
 
+### Spam Moderation (5)
+
+| Tool | Description |
+|------|-------------|
+| `email_report_spam` | Report an email as spam/junk, training the provider's own filter — the same signal the "Report Junk" button sends in Gmail/Outlook. This is different from `email_delete`, which removes the message but teaches the filter nothing. **Not** an abuse report to the provider's security team; it only trains this account's filter |
+| `email_batch_report_spam` | Report multiple emails as spam/junk at once |
+| `email_create_block_rule` | Create a standing rule that intercepts future mail matching a pattern (sender domain/address, subject, or arbitrary header content) and either deletes it or files it straight to Junk. Use `headerContains` (e.g. a Reply-To domain) to block a spam template family whose visible "From" domain rotates — matching the rotating domain directly stops working within days. **Not supported on iCloud/generic IMAP** (no standard server-side rule mechanism exists across IMAP servers). On Outlook, requires the `MailboxSettings.ReadWrite` scope — accounts authenticated before this tool existed need to re-run the setup wizard once to re-consent |
+| `email_list_block_rules` | List the standing block rules on an account, for auditing or before deleting one |
+| `email_delete_block_rule` | Delete a standing block rule — use to undo a rule that turned out too broad |
+
+Gmail and Outlook only for the rule tools; `email_report_spam`/`email_batch_report_spam` work on every provider (iCloud/IMAP fall back to a best-effort move into the account's Junk-typed folder, with no vendor ML training signal since generic IMAP has none to train).
+
 ## Usage with Claude Code
 
 Add the following to your `.mcp.json` file (project-level or global `~/.claude/.mcp.json`):

package/dist/index.js

@@ -7463,6 +7463,74 @@ var init_adapter = __esm({
           messageCount: label.messagesTotal ?? 0
         }));
       }
+      /**
+       * Trains Gmail's own spam filter — the same signal the "Report spam" UI
+       * button sends (add SPAM, drop INBOX). Not an abuse report to Google.
+       */
+      async reportSpam(emailId, _sourceFolder) {
+        const gmail = this.ensureConnected();
+        await gmail.users.messages.modify({
+          userId: "me",
+          id: emailId,
+          requestBody: { addLabelIds: ["SPAM"], removeLabelIds: ["INBOX"] }
+        });
+      }
+      async createBlockRule(rule) {
+        const gmail = this.ensureConnected();
+        const criteria = {};
+        switch (rule.matchType) {
+          case "senderDomain":
+            criteria.from = `@${rule.value}`;
+            break;
+          case "senderAddress":
+            criteria.from = rule.value;
+            break;
+          case "subjectContains":
+            criteria.subject = rule.value;
+            break;
+          case "headerContains":
+            criteria.query = rule.value;
+            break;
+        }
+        const action = rule.action === "delete" ? { addLabelIds: ["TRASH"] } : { addLabelIds: ["SPAM"], removeLabelIds: ["INBOX"] };
+        const res = await gmail.users.settings.filters.create({
+          userId: "me",
+          requestBody: { criteria, action }
+        });
+        return { id: res.data.id || "" };
+      }
+      async listBlockRules() {
+        const gmail = this.ensureConnected();
+        const res = await gmail.users.settings.filters.list({ userId: "me" });
+        return (res.data.filter || []).map((f) => {
+          const criteria = f.criteria || {};
+          const addLabelIds = f.action?.addLabelIds || [];
+          let matchType = "headerContains";
+          let value = criteria.query || "";
+          if (typeof criteria.from === "string" && criteria.from.startsWith("@")) {
+            matchType = "senderDomain";
+            value = criteria.from.slice(1);
+          } else if (criteria.from) {
+            matchType = "senderAddress";
+            value = criteria.from;
+          } else if (criteria.subject) {
+            matchType = "subjectContains";
+            value = criteria.subject;
+          }
+          return {
+            id: f.id || "",
+            matchType,
+            value,
+            action: addLabelIds.includes("TRASH") ? "delete" : "moveToJunk",
+            createdAt: ""
+            // Gmail's filter API does not expose a creation timestamp
+          };
+        });
+      }
+      async deleteBlockRule(ruleId) {
+        const gmail = this.ensureConnected();
+        await gmail.users.settings.filters.delete({ userId: "me", id: ruleId });
+      }
       buildRfc2822(params) {
         const lines = [];
         lines.push(`From: ${this.email}`);
@@ -8059,6 +8127,86 @@ var init_adapter2 = __esm({
         }
         return result;
       }
+      /**
+       * Trains Outlook's own spam filter — the same signal "Report Junk" sends
+       * in the UI (move to the Junk Email well-known folder). Not an abuse
+       * report to Microsoft's security team.
+       */
+      async reportSpam(emailId, _sourceFolder) {
+        const client = this.ensureClient();
+        await client.api(`/me/messages/${encodeURIComponent(emailId)}/move`).post({
+          destinationId: "junkemail"
+        });
+      }
+      /**
+       * Requires the `MailboxSettings.ReadWrite` delegated scope, confirmed by
+       * Microsoft's own docs to be supported for personal Microsoft accounts
+       * (outlook.com/hotmail), not just work/school. Accounts authenticated
+       * before this scope was added need to re-run the setup wizard to
+       * re-consent — old tokens will 403 on this call until then.
+       */
+      async createBlockRule(rule) {
+        const client = this.ensureClient();
+        const conditions = {};
+        switch (rule.matchType) {
+          case "senderDomain":
+          case "senderAddress":
+            conditions.senderContains = [rule.value];
+            break;
+          case "subjectContains":
+            conditions.subjectContains = [rule.value];
+            break;
+          case "headerContains":
+            conditions.headerContains = [rule.value];
+            break;
+        }
+        const actions = { stopProcessingRules: true };
+        if (rule.action === "delete") {
+          actions.delete = true;
+        } else {
+          actions.moveToFolder = await this.resolveFolder("junkemail");
+        }
+        const existing = await this.listBlockRules();
+        const result = await client.api("/me/mailFolders/inbox/messageRules").post({
+          displayName: `email-mcp: ${rule.matchType} "${rule.value}"`.slice(0, 255),
+          sequence: existing.length + 1,
+          isEnabled: true,
+          conditions,
+          actions
+        });
+        return { id: result.id };
+      }
+      async listBlockRules() {
+        const client = this.ensureClient();
+        const response = await client.api("/me/mailFolders/inbox/messageRules").get();
+        return (response.value || []).map((r) => {
+          const conditions = r.conditions || {};
+          let matchType = "headerContains";
+          let value = "";
+          if (conditions.senderContains?.length) {
+            value = conditions.senderContains[0];
+            matchType = value.includes("@") ? "senderAddress" : "senderDomain";
+          } else if (conditions.subjectContains?.length) {
+            matchType = "subjectContains";
+            value = conditions.subjectContains[0];
+          } else if (conditions.headerContains?.length) {
+            matchType = "headerContains";
+            value = conditions.headerContains[0];
+          }
+          return {
+            id: r.id,
+            matchType,
+            value,
+            action: r.actions?.delete ? "delete" : "moveToJunk",
+            createdAt: ""
+            // Graph's messageRule resource has no creation timestamp field
+          };
+        });
+      }
+      async deleteBlockRule(ruleId) {
+        const client = this.ensureClient();
+        await client.api(`/me/mailFolders/inbox/messageRules/${encodeURIComponent(ruleId)}`).delete();
+      }
       async getCategories() {
         const client = this.ensureClient();
         const response = await client.api("/me/outlook/masterCategories").get();
@@ -8122,7 +8270,10 @@ var init_auth2 = __esm({
     DEFAULT_CACHE_FILE = path2.join(DEFAULT_CACHE_DIR, "msal-cache.json");
     OutlookAuth = class _OutlookAuth {
       static AUTHORITY = "https://login.microsoftonline.com/consumers";
-      static SCOPES = ["Mail.ReadWrite", "Mail.Send", "offline_access"];
+      // MailboxSettings.ReadWrite is required for the messageRules API (block
+      // rules) — confirmed by Microsoft's own docs to be supported for personal
+      // Microsoft accounts (not just work/school), not just Mail.ReadWrite/Send.
+      static SCOPES = ["Mail.ReadWrite", "Mail.Send", "MailboxSettings.ReadWrite", "offline_access"];
       pca;
       cryptoProvider;
       constructor(clientId, cacheFilePath) {
@@ -8745,6 +8896,30 @@ var init_adapter3 = __esm({
           lock.release();
         }
       }
+      /**
+       * Best-effort only: generic IMAP has no server-side ML classifier to
+       * train, so this just moves the message to the account's Junk-typed
+       * folder (via the same alias resolution `deleteEmail` uses for Trash).
+       * No standing block-rule mechanism exists across IMAP servers (Sieve
+       * exists on some but isn't universal), so `createBlockRule` is
+       * intentionally left unimplemented for this provider.
+       */
+      async reportSpam(emailId, sourceFolder) {
+        if (!this.client) throw new Error("Not connected");
+        const folder = sourceFolder || "INBOX";
+        const junkFolder = await this.resolveFolder("junk");
+        let lock;
+        try {
+          lock = await this.client.getMailboxLock(folder);
+        } catch (error48) {
+          throw formatImapError(error48, `Failed to open folder "${folder}"`);
+        }
+        try {
+          await this.client.messageMove(emailId, junkFolder, { uid: true });
+        } finally {
+          lock.release();
+        }
+      }
       async deleteEmail(emailId, permanent, sourceFolder) {
         if (!this.client) throw new Error("Not connected");
         const folder = sourceFolder ? await this.resolveFolder(sourceFolder) : "INBOX";
@@ -33492,6 +33667,144 @@ function registerOrganizingTools(server, accountManager) {
   );
 }
 
+// src/tools/moderation.ts
+function jsonResult5(data) {
+  return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+var BLOCK_RULE_MATCH_TYPES = ["senderDomain", "senderAddress", "subjectContains", "headerContains"];
+var BLOCK_RULE_ACTIONS = ["delete", "moveToJunk"];
+function registerModerationTools(server, accountManager) {
+  server.tool(
+    "email_report_spam",
+    `Report an email as spam/junk, training the provider's own spam filter (the same signal the "Report Junk" button sends in Gmail/Outlook). This is different from email_delete, which removes the message but teaches the filter nothing. Not an abuse report to the provider's security team \u2014 it only trains this account's filter.`,
+    {
+      accountId: external_exports3.string(),
+      emailId: external_exports3.string(),
+      sourceFolder: external_exports3.string().optional().describe("Source folder (required for IMAP/iCloud when email is not in INBOX)")
+    },
+    async (args) => {
+      try {
+        const provider = await accountManager.getProvider(args.accountId);
+        if (!provider.reportSpam) {
+          return jsonResult5({ success: false, error: "email_report_spam is not supported on this provider" });
+        }
+        await provider.reportSpam(args.emailId, args.sourceFolder);
+        return jsonResult5({ success: true });
+      } catch (error48) {
+        return jsonResult5({ success: false, error: error48.message });
+      }
+    }
+  );
+  server.tool(
+    "email_batch_report_spam",
+    "Report multiple emails as spam/junk at once. Much faster than individual calls.",
+    {
+      accountId: external_exports3.string(),
+      emailIds: external_exports3.array(external_exports3.string()).min(1).describe("Array of email IDs to report as spam"),
+      sourceFolder: external_exports3.string().optional().describe("Source folder (required for IMAP/iCloud when emails are not in INBOX)")
+    },
+    async (args) => {
+      try {
+        const provider = await accountManager.getProvider(args.accountId);
+        if (!provider.reportSpam) {
+          return jsonResult5({ success: false, error: "email_batch_report_spam is not supported on this provider" });
+        }
+        const result = { succeeded: [], failed: [] };
+        for (const id of args.emailIds) {
+          try {
+            await provider.reportSpam(id, args.sourceFolder);
+            result.succeeded.push(id);
+          } catch (e) {
+            result.failed.push({ id, error: e.message });
+          }
+        }
+        return jsonResult5({ success: true, ...result });
+      } catch (error48) {
+        return jsonResult5({ success: false, error: error48.message });
+      }
+    }
+  );
+  server.tool(
+    "email_create_block_rule",
+    'Create a standing rule that intercepts future mail matching a pattern, before it reaches the inbox. Use headerContains (e.g. matching a Reply-To domain) to block a spam template family whose visible "From" domain rotates \u2014 matching the rotating domain directly stops working within days. Not supported on iCloud/generic IMAP (no standard server-side rule mechanism exists across IMAP servers). Outlook requires the MailboxSettings.ReadWrite scope \u2014 accounts authenticated before this tool existed need to re-run the setup wizard once to re-consent.',
+    {
+      accountId: external_exports3.string(),
+      matchType: external_exports3.enum(BLOCK_RULE_MATCH_TYPES).describe(
+        "senderDomain/senderAddress: match the From address. subjectContains: match the subject. headerContains: match any header's raw content \u2014 the right choice for a stable element (e.g. a Reply-To domain) when the From domain rotates."
+      ),
+      value: external_exports3.string().describe("The domain, address, or text to match"),
+      action: external_exports3.enum(BLOCK_RULE_ACTIONS).describe("delete: discard on arrival. moveToJunk: file straight to Junk/Spam without notifying.")
+    },
+    async (args) => {
+      try {
+        const provider = await accountManager.getProvider(args.accountId);
+        if (!provider.createBlockRule) {
+          return jsonResult5({
+            success: false,
+            error: "email_create_block_rule is not supported on this provider",
+            supportedProviders: ["gmail", "outlook"]
+          });
+        }
+        const result = await provider.createBlockRule({
+          matchType: args.matchType,
+          value: args.value,
+          action: args.action
+        });
+        return jsonResult5({ success: true, data: result });
+      } catch (error48) {
+        return jsonResult5({ success: false, error: error48.message });
+      }
+    }
+  );
+  server.tool(
+    "email_list_block_rules",
+    "List the standing block rules on an account, for auditing or before deleting one.",
+    {
+      accountId: external_exports3.string()
+    },
+    async (args) => {
+      try {
+        const provider = await accountManager.getProvider(args.accountId);
+        if (!provider.listBlockRules) {
+          return jsonResult5({
+            success: false,
+            error: "email_list_block_rules is not supported on this provider",
+            supportedProviders: ["gmail", "outlook"]
+          });
+        }
+        const rules = await provider.listBlockRules();
+        return jsonResult5({ success: true, data: rules });
+      } catch (error48) {
+        return jsonResult5({ success: false, error: error48.message });
+      }
+    }
+  );
+  server.tool(
+    "email_delete_block_rule",
+    "Delete a standing block rule \u2014 use this to undo a rule that turned out to be too broad (e.g. it blocked a domain a real correspondent also uses).",
+    {
+      accountId: external_exports3.string(),
+      ruleId: external_exports3.string()
+    },
+    async (args) => {
+      try {
+        const provider = await accountManager.getProvider(args.accountId);
+        if (!provider.deleteBlockRule) {
+          return jsonResult5({
+            success: false,
+            error: "email_delete_block_rule is not supported on this provider",
+            supportedProviders: ["gmail", "outlook"]
+          });
+        }
+        await provider.deleteBlockRule(args.ruleId);
+        return jsonResult5({ success: true });
+      } catch (error48) {
+        return jsonResult5({ success: false, error: error48.message });
+      }
+    }
+  );
+}
+
 // src/server.ts
 async function createServer(accountManager) {
   const mgr = accountManager ?? new AccountManager();
@@ -33503,6 +33816,7 @@ async function createServer(accountManager) {
   registerReadingTools(server, mgr);
   registerSendingTools(server, mgr);
   registerOrganizingTools(server, mgr);
+  registerModerationTools(server, mgr);
   return { server, accountManager: mgr };
 }
 async function startServer() {