fastmail-mcp-server copilot-instructions.md

Copilot Instructions for Fastmail MCP Server

Project Overview

This is a Model Context Protocol (MCP) server for Fastmail that enables AI assistants to interact with Fastmail accounts via the JMAP protocol. It provides tools for managing emails, calendars, contacts, and mailboxes, including AI-powered features via MCP sampling.

Published as @jordonh19/fastmail-mcp-server on npm.

Architecture

• Transport: Supports stdio (default) and HTTP transports (@modelcontextprotocol/sdk)
• Protocol: JMAP (JSON Meta Application Protocol) for communicating with Fastmail
• Language: TypeScript with ESM modules ("type": "module")
• Configuration: File-based (.fastmail-mcp.json) with CLI arg overrides

Directory Structure

src/
├── config.ts            # Configuration loader (file + CLI args)
├── config.test.ts       # Config tests
├── index.ts             # Entry point — stdio or HTTP transport
├── server.ts            # Server factory — creates McpServer, registers all tool groups
├── server.test.ts       # Server tests
├── jmap/
│   ├── client.ts        # JmapClient — session, auth, API requests, blob download
│   ├── client.test.ts   # Client tests
│   ├── methods.ts       # JMAP method call builders (pure functions)
│   ├── methods.test.ts  # Method builder tests
│   └── types.ts         # TypeScript interfaces and JMAP capability constants
└── tools/
    ├── email-helpers.ts    # Shared email utilities (formatting, HTML stripping, body extraction)
    ├── email-read.ts       # Email reading tools (search, get, thread, unread, latest, mailbox, download)
    ├── email-read.test.ts
    ├── email-write.ts      # Email composition tools (send, reply, forward, draft, send_draft)
    ├── email-write.test.ts
    ├── email-manage.ts     # Email management tools (move, flags, delete, bulk, archive, mark_read)
    ├── email-manage.test.ts
    ├── mailbox.ts          # Mailbox CRUD tools (list, create, rename, delete)
    ├── mailbox.test.ts
    ├── calendar.ts         # Calendar event tools (list, query, get, create, update, delete)
    ├── calendar.test.ts
    ├── contacts.ts         # Contact card tools (list, search, get, create, update, delete)
    ├── contacts.test.ts
    ├── identity.ts         # Sender identity tools (get_identities)
    ├── identity.test.ts
    ├── sampling.ts         # AI-powered tools via MCP sampling (summarize, suggest_reply)
    └── sampling.test.ts