bulk_mark_read

Instructions

Implementation Reference

• src/tools/bulk_mark_read.ts:37-62 (handler)

  The register function that defines the 'bulk_mark_read' tool with its handler logic. It validates that at least one of mailbox/from is provided, then runs the AppleScript to mark matching messages as read.

  export function register(server: McpServer): void {
    server.tool(
      "bulk_mark_read",
      "Mark multiple messages as read in one call — by mailbox, sender substring, or both. Far faster than calling set_message_flags per message.",
      schema,
      { title: "Bulk Mark Read", readOnlyHint: false, destructiveHint: false },
      async ({ mailbox, from, account }) => {
        if (!mailbox && !from) {
          return {
            content: [{ type: "text", text: "At least one of mailbox or from is required." }],
            isError: true,
          };
        }
        const result = await runAppleScript({
          script: SCRIPT,
          args: {
            theMailbox: mailbox ?? "",
            theSender: from ?? "",
            theAcct: account ?? "",
          },
          timeoutMs: 120_000,
        });
        return { content: [{ type: "text", text: result }] };
      },
    );
  }

• src/tools/bulk_mark_read.ts:5-9 (schema)

  Zod schema for tool inputs: optional mailbox (exact name), from (substring match sender), and account (exact name).

  const schema = {
    mailbox: z.string().optional().describe("Restrict to this exact mailbox name. At least one of mailbox or from is required."),
    from: z.string().optional().describe("Substring to match against the sender field. At least one of mailbox or from is required."),
    account: z.string().optional().describe("Restrict to this account name."),
  };

• src/tools/bulk_mark_read.ts:13-35 (helper)

  The AppleScript template that iterates over accounts/mailboxes/messages and marks unread messages as read, given theMailbox, theSender, and theAcct variables.

  const SCRIPT = `
    tell application "Mail"
      set markedCount to 0
      repeat with acct in accounts
        if theAcct is "" or (name of acct) contains theAcct then
          repeat with mb in mailboxes of acct
            if theMailbox is "" or (name of mb) is theMailbox then
              set msgs to messages of mb
              repeat with m in msgs
                if (read status of m) is false then
                  if theSender is "" or (sender of m) contains theSender then
                    set read status of m to true
                    set markedCount to markedCount + 1
                  end if
                end if
              end repeat
            end if
          end repeat
        end if
      end repeat
      return (markedCount as string) & " messages marked read"
    end tell
  `;

• src/tools/bulk_mark_read.ts:37-46 (helper)

  The helper function runAppleScript imported from ../lib/applescript.ts, which writes the script to a temp file and executes it via osascript with safe argument passing.

  export function register(server: McpServer): void {
    server.tool(
      "bulk_mark_read",
      "Mark multiple messages as read in one call — by mailbox, sender substring, or both. Far faster than calling set_message_flags per message.",
      schema,
      { title: "Bulk Mark Read", readOnlyHint: false, destructiveHint: false },
      async ({ mailbox, from, account }) => {
        if (!mailbox && !from) {
          return {
            content: [{ type: "text", text: "At least one of mailbox or from is required." }],

• src/server.ts:15-35 (registration)

  Import of the register function from bulk_mark_read.ts, and its invocation at line 35 to register the tool with the MCP server.

  import { register as registerBulkMarkRead } from "./tools/bulk_mark_read.js";
  import { register as registerGetUnsubscribeLink } from "./tools/get_unsubscribe_link.js";
  import { register as registerListSenders } from "./tools/list_senders.js";
  import { register as registerEmptyMailbox } from "./tools/empty_mailbox.js";
  
  const server = new McpServer({
    name: "mail-app-mcp",
    version: "1.0.0",
  });
  
  registerSearch(server);
  registerRead(server);
  registerAccounts(server);
  registerListRecent(server);
  registerSend(server);
  registerReply(server);
  registerFlags(server);
  registerMove(server);
  registerTrash(server);
  registerCreateMailbox(server);
  registerBulkMarkRead(server);