macos-mail-mcp: Instructions file for Claude Code

CLAUDE.md — macos-mail-mcp

Project Overview

MCP (Model Context Protocol) server that connects Claude to macOS Mail.app via AppleScript. Provides 20 tools across 4 domains for full email management: reading, searching, composing, flagging, moving, deleting, and attachment handling.

Works with any email account configured in Mail.app — iCloud, Gmail, Outlook/Exchange, Yahoo, Fastmail, custom IMAP/POP, etc. No code changes needed when adding new accounts; just configure them in Mail.app.

Operating layer

This repository governs itself: .portulan/ is a kind: repository Portulan workspace, which the boot skill finds automatically because it searches ${CLAUDE_PROJECT_DIR}/.portulan/. It is not part of the Sleepy Panda portfolio workspace.

• .portulan/identity.md — what this repository is, the stack, the three-layer shape, and the glossary. Start here.
• .portulan/gate-map.md — which actions are Auto, Propose, Gated, Prohibited. Merge, publishing a release, pushing a tag, and npm publish by hand are Gated: they need explicit approval, per action. No action is Prohibited.
• .portulan/dod.md — when a change is done here, including the 100% coverage bar and the rule that a verdict must post-date the head it judges.
• .portulan/principles.md — five principles, each naming the incident that produced it.
• .portulan/handoffs/ — the session record, dated YYYY-MM-DD-{slug}.md. Every session ends with one; read the most recent before starting.

It declares tree: "../", so doctor lints the gate map's claims against this repository — it checks that the required status check verify is one a workflow here actually reports. Nothing in .portulan/ ships to npm; files: ["build"] governs the tarball.

Tech Stack

• Runtime: Node.js 20+ (engines floor; CI builds and tests on 20, 22 and 24)
• Language: TypeScript (ES2022, Node16 module resolution)
• MCP SDK: @modelcontextprotocol/sdk v1.x (stdio transport)
• Mail integration: AppleScript via osascript (execFile, not exec — prevents shell injection)
• Validation: Zod schemas on all tool inputs
• Testing: Vitest, mocked bridge — no real Mail.app needed. Coverage of src/ is gated at 100% (statements, branches, functions, lines) in vitest.config.ts, and CI runs test:coverage. The gate is the invariant; the raw test count is not tracked here because it goes stale on every change and nothing checks it.
• The .applescript files are the exception, and it is a real one. That 100% covers src/**/*.ts only. Because the bridge is mocked, the AppleScript templates are text handed to a mock rather than code that runs — which is how a handler that threw on any emoji subject shipped unexercised, found by an outside contributor (#33) rather than by the suite. tests/bridge/escape-for-json.applescript.test.ts executes the escaping handler through osascript for real. It runs only on macOS and is skipped everywhere else, including CI, so those assertions run on a maintainer's machine and never in the merge gate. Run npm run test:coverage locally before touching anything under src/**/*.applescript; the runner cannot do it for you.