empty_mailbox

Instructions

Implementation Reference

• src/tools/empty_mailbox.ts:33-51 (handler)

  The handler function that registers and executes the 'empty_mailbox' tool. It accepts mailbox_name and optional account, runs an AppleScript to delete every message in the target mailbox, and returns the count of deleted messages.

  export function register(server: McpServer): void {
    server.tool(
      "empty_mailbox",
      "Delete every message in a mailbox at once — moves to Deleted Messages, or permanently removes if the mailbox is already Deleted Messages/Trash. Use for Junk, Trash, or bulk-cleanup folders.",
      schema,
      { title: "Empty Mailbox", readOnlyHint: false, destructiveHint: true },
      async ({ mailbox_name, account }) => {
        const result = await runAppleScript({
          script: SCRIPT,
          args: {
            theMailbox: mailbox_name,
            theAcct: account ?? "",
          },
          timeoutMs: 120_000,
        });
        return { content: [{ type: "text", text: result }] };
      },
    );
  }

• src/tools/empty_mailbox.ts:5-8 (schema)

  Zod schema defining the tool's input parameters: mailbox_name (required string) and account (optional string for disambiguation).

  const schema = {
    mailbox_name: z.string().describe("Exact mailbox name to empty (e.g. 'Junk', 'Deleted Messages'). Use list_accounts_and_mailboxes for exact names."),
    account: z.string().optional().describe("Account name to disambiguate when the same mailbox name exists in multiple accounts"),
  };

• src/server.ts:18-18 (registration)

  Import of the register function from the empty_mailbox tool module.

  import { register as registerEmptyMailbox } from "./tools/empty_mailbox.js";

• src/server.ts:38-38 (registration)

  Registration call that wires the 'empty_mailbox' tool into the MCP server.

  registerEmptyMailbox(server);

• src/lib/applescript.ts:22-46 (helper)

  The runAppleScript helper that writes the AppleScript to a temp file and executes it via osascript, safely passing arguments through argv.

  export async function runAppleScript(opts: RunAppleScriptOptions): Promise<string> {
    const { script, args = {}, timeoutMs = 30_000 } = opts;
  
    const argNames = Object.keys(args);
    const argValues = argNames.map((n) => args[n]!);
  
    const bindings = argNames
      .map((name, i) => `  set ${name} to item ${i + 1} of argv`)
      .join("\n");
  
    const wrapped = `on run argv\n${bindings}\n${script}\nend run\n`;
  
    const dir = await mkdtemp(path.join(tmpdir(), "mail-mcp-"));
    const scriptPath = path.join(dir, "script.applescript");
    try {
      await writeFile(scriptPath, wrapped, "utf8");
      const { stdout } = await execFileP("osascript", [scriptPath, ...argValues], {
        timeout: timeoutMs,
        maxBuffer: 10 * 1024 * 1024,
      });
      return stdout.trimEnd();
    } finally {
      await rm(dir, { recursive: true, force: true }).catch(() => {});
    }
  }