fastmail-mcp: Instructions file for Codex

AGENTS.md

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

Commands

npm run build          # Compile TypeScript to dist/
npm run dev            # Run directly with tsx (no build needed)
npm start              # Run compiled output (requires build first)
npm test               # Run all tests
tsx --test src/jmap-client.test.ts  # Run a single test file

Architecture

This is a Model Context Protocol (MCP) server that exposes 28 tools for interacting with Fastmail email via the JMAP protocol.

Source Files

• src/auth.ts — FastmailAuth class: holds API token, builds auth headers and endpoint URLs. Simple, rarely changes.
• src/jmap-client.ts — Core JMAP client (JmapClient class). All email/mailbox/attachment/search operations live here. Makes JMAP method calls via makeRequest(), handles session bootstrapping, identity resolution, and JMAP result references (#ids with resultOf for chained calls).
• src/mcp-server.ts — MCP server factory and tool handlers. Registers all 28 tools, handles request dispatch, coerces JSON-encoded string args from web clients, normalizes address arrays, and resolves Fastmail config into per-session runtime contexts.
• src/http-server.ts — HTTP transport/session manager. Creates isolated MCP server instances per HTTP session, enforces body/session limits, expires idle sessions, and returns structured JSON-RPC errors for malformed HTTP requests.
• src/index.ts — Startup entry point. Chooses stdio vs HTTP mode and delegates to the appropriate server bootstrap code.

Key Patterns

JMAP chaining: Many operations use JMAP result references — e.g., a query call returns an ID, and a subsequent get call references it with "#ids": {"resultOf": "...", "name": "...", "path": "/ids"}. This avoids two round trips.

Arg coercion in mcp-server.ts: The coerceArgs function handles the case where web UIs send tool arguments as JSON strings instead of parsed objects. Any new tools that accept arrays or objects need to be supported there.