Tapal

Tapal (തപാൽ — post / mail in Malayalam) — your mail, in any AI.

Your local AI-native mail layer. Plug Tapal into your existing client (Apple Mail · Thunderbird · ProtonMail Bridge · self-hosted IMAP) so any LLM agent can read and act on your inbox — or use Tapal as your email client and skip the dual-app lifestyle. Either way, your mail and your AI live on your machine.

Two modes, one architecture:

Stdio + Streamable HTTP MCP, drafts-by-default. Local-first by design (ADR 0007) — no Tapal-operated servers, ever.

Translator mode today: Apple Mail on macOS. Translator mode coming: Localhost IMAP loopback (Proton Bridge / self-hosters) — v0.2 · Mozilla Thunderbird — v0.3 · notmuch / Maildir (mutt + aerc + mu4e) — v0.4. Native-client mode coming: Gmail — v0.5 · Microsoft 365 / Exchange / Outlook.com — v0.6 · Yahoo + iCloud — v0.7 · Generic IMAP/POP — v0.8 · Calendar + Contacts — v0.9 · AI hub with local LLMs — v0.10.

Outlook desktop adapters are out of scope (ADR 0010). Microsoft email accounts (M365 / Exchange / Outlook.com) are supported via native-client mode (v0.6) directly through Microsoft Graph.

Table of contents

• Quickstart
• Why Tapal?
• Capabilities
• Tools at a glance
• Sending — opt-in
• Architecture
• Requirements
• For users
• For maintainers
• Roadmap
• Contributing
• Security
• License

Quickstart

# 1. Pick your orchestrator's config file (see table below)
# 2. Drop in:

{
  "mcpServers": {
    "tapal": {
      "command": "npx",
      "args": ["-y", "@cyberion/tapal"]
    }
  }
}

# 3. Restart the orchestrator. Done.

Detailed setup for every orchestrator:

Status: pre-release v0.1. Stable shape, but expect bugs and a few sharp edges. The Apple Mail backend has been used in anger across 12+ accounts; the multi-orchestrator packaging is fresh.

Why Tapal?

LLM agents are useful when they can act on your data. Mail is the densest source of that data for most people — meetings, projects, contracts, reviews, family threads. Letting an agent read, summarise, triage, and (with your permission) reply against your real inbox unlocks a lot.

But:

• Every orchestrator has its own tool format. Slack-MCP, Gmail-API-OAuth, GitHub-MCP, browser-extension-bots — they don't compose.
• Mail clients are fragmented. Apple Mail, Outlook, Thunderbird, Fastmail, ProtonMail, generic IMAP. Each ships its own scripting surface (or none).
• Sending mail from an LLM is dangerous if you're not careful.

Tapal solves all three:

1. One MCP server, every orchestrator. Stdio MCP is the lowest common denominator. Claude, Codex, Gemini, Cursor, Windsurf, Zed, LangChain — all speak it. Tapal speaks it once and works everywhere.
2. One tool surface, every mail client. A MailAdapter interface in core; concrete adapters per backend. Apple Mail today; Outlook + Thunderbird + JMAP + IMAP next. The MCP tool surface stays stable as backends are added.
3. Drafts-by-default. mode: "send" is opt-in via an env var. Default behaviour opens a compose window in your mail client for review. The agent never pushes Send unless you let it.

Capabilities

Apple Mail today (other adapters in Roadmap):

• Multi-account — Apple, Google, Microsoft 365, iCloud, Titan, custom IMAP, etc.
• Read & search — list, read, search, count, triage, paginated. Compound OR queries, structured filters, exclusions, date ranges.
• Compose — new mail, reply, reply-all, forward. HTML body, multi-recipient, attachments. Three modes: open, send (opt-in), draft.
• Manage — flag/unflag, mark read/unread, move (cross-account), batch operate, trash empty / delete / restore, bulk delete by category.
• Calendar — detect invites in mail (file-attachment and inline MIME), parse .ics, create / search / delete events in Calendar.app. Accept / decline via iMIP REPLY (RFC 6047), works against any sane organiser.
• Bulk categorise — rule-driven categorisation for inbox cleanup. Returns counts + samples; pair with mail_bulk_delete for safe sweeping.
• Fast — batch JXA property access (~87× speedup on big mailboxes; reproducible benchmarks), 30 s account/count caches, request deduplication.

Full reference: docs/tools.md.

Tools at a glance

mail_accounts            mail_count               mail_compose
mail_list                mail_count_all           mail_reply
mail_read                mail_stats_all           mail_forward
mail_search              mail_account_stats       mail_flag
mail_triage              mail_calendar_invites    mail_mark_read
mail_categorize          mail_calendar_respond    mail_move
mail_bulk_delete         mail_calendar_respond_ui mail_batch
                         calendar_list            mail_trash
                         calendar_events
                         calendar_search
                         calendar_create_event
                         calendar_delete_event

All 27 tools ship with the four standard MCP annotation hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so clients can colour buttons, gate destructive ops, and decide what an autonomous loop may call without asking.

Full schema reference in docs/tools.md.

Sending — opt-in

{
  "mcpServers": {
    "tapal": {
      "command": "npx",
      "args": ["-y", "@cyberion/tapal"],
      "env": { "ALLOW_SEND": "true" }
    }
  }
}

Without ALLOW_SEND=true, mode: "send" returns a structured error and doesn't touch the network. The mode: "open" default opens a compose window in Mail.app for your review — the LLM drafts, you click Send.

Architecture

Three packages in a monorepo:

@cyberion/tapal                       (the MCP server users install)
            ↓ depends on
@cyberion/tapal-adapters-apple-mail   (the first adapter)
            ↓ depends on
@cyberion/tapal-core                  (provider-agnostic)

• core ships the MailAdapter interface, domain types, and pure utilities (ICS parser, TTL cache, dedup, structured logger). Zero runtime dependencies.
• adapters-apple-mail implements MailAdapter against Mail.app via JXA (JavaScript for Automation). 25 JXA scripts, one per operation.
• server registers 27 MCP tools with the modern registerTool API, validates inputs with Zod, and wires the stdio transport.

Full breakdown: docs/architecture.md. Why this shape: docs/decisions/0002-monorepo-three-packages.md. Writing a new adapter (Outlook, Thunderbird, etc.): docs/adapter-guide.md.

Requirements

• macOS 13+ (Apple Mail adapter)
• Node.js ≥ 22
• Mail.app configured with at least one account
• Automation permission for your orchestrator (granted on first call)

For users

• Pick your orchestrator in the Quickstart table and follow the linked guide.
• Hit a snag? Common gotchas are in docs/operations/troubleshooting.md. Mail-app permission prompts and runtime quirks live in the per-orchestrator integration guide.
• Send something dangerous? It only does so with ALLOW_SEND=true. See Sending — opt-in.

For maintainers

If you've inherited this repo or you're returning after a break — start at docs/handoff.md. It captures where things stand, what's pending, and the operational facts that aren't obvious from the code.

Local development

git clone https://github.com/CyberionHelix/Tapal.git
cd Tapal
nvm use            # Node 22
npm ci --force     # workspaces + dev deps (--force is required; see docs/operations/ci-cd.md)
npm run build      # all 3 packages
npm test           # 332 tests (unit + edge, no Mail.app needed)

Need to run integration tests (require Mail.app)? npm run test:integration and npm run test:smoke — local only, excluded from CI.

Roadmap

Translator era — script local mail clients & bridges

No Outlook desktop adapter — see ADR 0010. EWS retires Oct 2026 (kills Outlook-Mac sync); New Outlook for Win drops COM with no shim. Microsoft email accounts arrive via native-client mode at v0.6.

Native-client era — Tapal is the email client

Tauri-based UI (ADR 0009). Local SQLite + FTS5 store. Direct provider APIs, no Tapal-operated servers (ADR 0007). MCP tool surface stays exposed.

AI-native — the differentiator

Live roadmap board: github.com/orgs/CyberionHelix/projects/1 — Now / Next / Later / Shipped, grouped by Area, updated on every issue. Per-issue tracking: open issues.

Pre-1.0 versioning: breaking changes bump minor (per SemVer's pre-1.0 guidance). See docs/decisions/0004-semantic-release.md § Pre-1.0 versioning policy.

Registry listings tracked in docs/registry-submissions.md.

Contributing

PRs welcome. Read CONTRIBUTING.md for the dev setup, Conventional Commits, PR checklist, and adapter-authoring walkthrough.

By contributing you agree to the Code of Conduct (Contributor Covenant 2.1).

Security

Tapal mediates an LLM agent's access to your real mail accounts. We take security reports seriously. Private-disclosure flow, supported-version policy, and triage SLOs in SECURITY.md.

Don't open public issues for security reports.

License

Apache 2.0 — patent grant included. Why Apache 2.0: docs/decisions/0003-license-apache-2.md. Copyright © 2026 CyberionHelix.

Acknowledgements

• The Model Context Protocol team at Anthropic.
• The macOS automation community for keeping JXA documented and alive.
• Everyone running pre-1.0 software for us — your bug reports shape v1.0.