CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Model Context Protocol (MCP) server that provides JMAP (JSON Meta Application Protocol) email management tools. It's built with Deno and integrates with JMAP-compliant email servers like FastMail, Cyrus IMAP, and Stalwart Mail Server.

Development Commands

• deno task start - Run the MCP server
• deno task watch - Run with file watching
• deno check - Type-check the project
• deno fmt - Format code (excludes CHANGELOG.md)
• deno lint - Lint the project
• deno test --allow-env --allow-net - Run all tests
• deno test --allow-env --allow-net src/tools/email_test.ts - Run a single test file
• deno publish --dry-run --allow-dirty - Validate JSR publish

Pre-commit Hooks

Run deno task hooks:install to set up git hooks. Pre-commit runs deno check && deno fmt --check && deno lint. Pre-push runs deno publish --dry-run --allow-dirty.

Required Environment Variables

JMAP_SESSION_URL="https://your-jmap-server.com/.well-known/jmap"
JMAP_BEARER_TOKEN="your-bearer-token"
JMAP_ACCOUNT_ID="account-id"  # Optional, auto-detected if not provided

Architecture

Core Structure

• Entry point: src/mod.ts - MCP server setup, JMAP client initialization, and tool registration
• Tool modules: src/tools/ - Modular tool implementations
  • email.ts - Email search, retrieval, mailbox management, and basic operations
  • submission.ts - Email composition and sending (when JMAP submission capability is available)
• Utilities: src/utils.ts - Common utilities like error formatting

Key Design Patterns

• Functional programming style - Functions are pure where possible, side effects are contained
• Runtime validation - All inputs validated with Zod schemas before processing
• Capability-based registration - Tools are registered based on JMAP server capabilities (checked in mod.ts via session.capabilities)
• Graceful degradation - Server adapts to read-only accounts and limited JMAP capabilities

JMAP Integration

• Uses jmap-jam client library for JMAP RFC 8620/8621 compliance
• Automatically detects account capabilities and registers appropriate tools
• Supports both read-only and full-access JMAP accounts
• Handles JMAP mail (urn:ietf:params:jmap:mail) and submission (urn:ietf:params:jmap:submission) capabilities

Testing Pattern

Tests use MCP SDK's InMemoryTransport to create a connected client/server pair, with a mock JamClient that stubs jam.api.* methods. See src/tools/email_test.ts for the pattern. New tool tests should follow this approach: create mock, register tools on server, call tools via client, assert results.

Tool Categories

1. Email Search & Retrieval: search_emails, get_emails, get_threads
2. Mailbox Management: get_mailboxes
3. Email Actions (non-read-only): mark_emails, move_emails, delete_emails
4. Email Composition (submission capability): send_email, reply_to_email

Development Guidelines

Adding New Tools

1. Create Zod validation schemas for input parameters
2. Implement tool logic with proper error handling using formatError()
3. Register tools in appropriate module (email.ts vs submission.ts)
4. Tools should be registered conditionally based on JMAP capabilities

Code Style

• Follow functional programming patterns throughout the codebase
• Use TypeScript types imported from jmap-jam for JMAP objects
• All external inputs must be validated with Zod schemas
• Error handling should use the formatError() utility
• Console output uses console.warn() for server status messages
• Published to JSR as @wyattjoh/jmap-mcp; run deno publish --dry-run to validate before pushing

JMAP Considerations

• Email IDs and thread IDs are server-specific strings, not UUIDs
• Mailbox hierarchies use parent-child relationships via parentId
• Keywords like $seen, $flagged, $draft control email state
• Date filters must use ISO 8601 format
• Pagination is handled via position and limit parameters

Security Notes

• Bearer tokens are provided via environment variables, never hardcoded
• No secrets are logged or exposed in MCP responses
• Input validation prevents injection attacks
• JMAP protocol provides built-in security through proper authentication

JMAP MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with JMAP (JSON Meta Application Protocol) email servers. Built with Deno and using the @htunnicliff/jmap-jam client library.

Features

Email Management Tools

• Search Emails: Search emails with text queries, sender/recipient filters, date ranges, and keywords. All filters are AND'd together.
• Get Emails: Retrieve specific emails by ID with configurable property selection
• Get Threads: Retrieve email threads (conversation chains)
• Mark Emails: Mark emails as read/unread, flagged/unflagged
• Move Emails: Move emails between mailboxes
• Delete Emails: Delete emails permanently

Mailbox Management

• Get Mailboxes: List all mailboxes/folders with hierarchy support. Use this to find mailbox IDs needed by other tools.

Incremental Sync

• Get Email Changes: Get IDs of emails created, updated, or destroyed since a previous state (state-based delta tracking)
• Get Search Updates: Get additions/removals within a previous search query since its last queryState

Email Composition

• Send Email: Compose and send new emails with support for plain text and HTML
• Reply to Email: Reply to existing emails with automatic header handling and reply-all support

Key Capabilities

• Full JMAP RFC 8620/8621 compliance via jmap-jam
• Comprehensive input validation with Zod schemas
• Pagination support for all list operations
• State-based incremental sync for efficient polling
• Rich error handling and connection management
• Capability-based tool registration (read-only, submission)
• TypeScript support with strong typing

Installation

Claude Code Plugin (Recommended)

Install via the plugin marketplace:

/plugin marketplace add wyattjoh/claude-code-marketplace
/plugin install jmap-mcp@wyattjoh-marketplace

Then configure the required environment variables in your MCP server settings.

Prerequisites

• Deno v1.40 or later
• A JMAP-compliant email server (e.g., Cyrus IMAP, Stalwart Mail Server, FastMail)
• Valid JMAP authentication credentials

Setup

Add the following to your agent of choice:

{
  "mcpServers": {
    "jmap": {
      "type": "stdio",
      "command": "deno",
      "args": [
        "run",
        "--allow-net=api.fastmail.com",
        "--allow-env=JMAP_SESSION_URL,JMAP_BEARER_TOKEN,JMAP_ACCOUNT_ID",
        "jsr:@wyattjoh/jmap-mcp@0.6.2"
      ],
      "env": {
        "JMAP_SESSION_URL": "https://api.fastmail.com/jmap/session",
        "JMAP_BEARER_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Replace api.fastmail.com in --allow-net with your JMAP server's hostname if not using FastMail.

Usage

Environment Variables

Available Tools

get_mailboxes

List mailboxes/folders with their IDs, names, and metadata. Call this first to get mailbox IDs needed by search_emails (inMailbox) and move_emails (mailboxId). Common names: Inbox, Drafts, Sent, Trash, Archive, Spam/Junk.

Parameters:

• parentId (optional): Filter by parent mailbox ID
• limit (optional): Max results (1-200, default: 100)
• position (optional): Starting position for pagination

search_emails

Search emails with filters. All filters are AND'd together. Returns only email IDs — use get_emails to fetch content. Results include queryState for incremental sync via get_search_updates.

Parameters:

• query (optional): Text search across all fields
• body (optional): Search in message body only
• from (optional): Filter by sender email address
• to (optional): Filter by recipient email address
• subject (optional): Filter by subject text
• inMailbox (optional): Mailbox ID to search within (get from get_mailboxes)
• hasKeyword (optional): Filter by keyword (e.g., $seen, $flagged)
• notKeyword (optional): Exclude by keyword (e.g., $seen, $draft)
• allInThreadHaveKeyword (optional): All emails in thread must have keyword
• someInThreadHaveKeyword (optional): At least one email in thread must have keyword
• before (optional): Only emails before date (ISO 8601 datetime)
• after (optional): Only emails after date (ISO 8601 datetime)
• limit (optional): Max results (1-100, default: 50)
• position (optional): Starting position for pagination (default: 0)

get_emails

Retrieve specific emails by their IDs. Use properties to request only what you need — fetching all properties returns large payloads.

Parameters:

• ids: Array of email IDs (1-50 IDs)
• properties (optional): Specific properties to return. Recommended sets:
  • Summary: ["id", "subject", "from", "to", "receivedAt", "preview"]
  • Full read: ["id", "subject", "from", "to", "cc", "receivedAt", "bodyValues", "textBody", "htmlBody"]
  • Note: To get body content, include bodyValues AND textBody/htmlBody

get_threads

Get email threads by their IDs. Thread IDs come from get_emails responses (threadId property). Returns email IDs per thread — use get_emails on those IDs to fetch content.

Parameters:

• ids: Array of thread IDs (1-20 IDs)

get_email_changes

Get IDs of emails created, updated, or destroyed since a previous state. Use the state string from a get_emails response.

Parameters:

• sinceState: State string from a previous get_emails response
• maxChanges (optional): Max changes to return (1-500)
• fetchEmails (optional): Auto-fetch full email details for changed IDs (default: false)
• properties (optional): Properties to fetch when fetchEmails is true

get_search_updates

Get changes within a previous search query since its queryState. Must use the same filter parameters as the original search_emails call.

Parameters:

• sinceQueryState: queryState from a previous search_emails response
• All filter parameters from search_emails (must match original query)
• maxChanges (optional): Max changes to return (1-500)

mark_emails

Mark emails as read/unread or flagged/unflagged.

Parameters:

• ids: Array of email IDs (1-100 IDs)
• seen (optional): Mark as read (true) or unread (false)
• flagged (optional): Mark as flagged (true) or unflagged (false)

move_emails

Move emails to a different mailbox. Use get_mailboxes to find the target mailbox ID.

Parameters:

• ids: Array of email IDs (1-100 IDs)
• mailboxId: Target mailbox ID (get from get_mailboxes)

delete_emails

Delete emails permanently (cannot be undone). Prefer moving to Trash via move_emails for recoverable deletion.

Parameters:

• ids: Array of email IDs (1-100 IDs)

send_email

Send a new email. Requires either textBody or htmlBody (or both).

Parameters:

• to: Array of recipients (name optional, email required)
• cc (optional): Array of CC recipients
• bcc (optional): Array of BCC recipients
• subject: Email subject
• textBody (optional): Plain text body
• htmlBody (optional): HTML body
• identityId (optional): JMAP identity ID to send from (uses server default if omitted)

reply_to_email

Reply to an existing email. Automatically sets To/CC, Re: subject prefix, and threading headers (In-Reply-To, References).

Parameters:

• emailId: ID of email to reply to
• replyAll (optional): Include all original recipients (default: false)
• subject (optional): Custom reply subject (defaults to Re: <original>)
• textBody (optional): Plain text body
• htmlBody (optional): HTML body
• identityId (optional): JMAP identity ID to send from (uses server default if omitted)

JMAP Server Compatibility

This server should work with any JMAP-compliant email server, including:

• Cyrus IMAP 3.0+
• Stalwart Mail Server
• FastMail (commercial)
• Apache James (with JMAP support)

Development

Running in Development

just watch          # Run with file watching
just start          # Run without watching

Testing

just test           # Run all tests
just check          # Format check + lint + type check
just fmt            # Auto-format code

Architecture

The server is built using:

• Deno: Modern JavaScript/TypeScript runtime
• @modelcontextprotocol/sdk: MCP server framework
• jmap-jam: Lightweight, typed JMAP client
• Zod: Runtime type validation

Security

• All input is validated using Zod schemas
• Environment variables are used for sensitive configuration
• No secrets are logged or exposed in responses
• Follows JMAP security best practices

Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes following the functional programming style
4. Test your changes thoroughly
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Related Projects

• jmap-jam - JMAP client library
• Model Context Protocol - MCP specification
• JMAP RFC 8620 - JMAP core protocol
• JMAP RFC 8621 - JMAP for Mail