email-mcp: Instructions file for Claude Code

email-mcp -- Claude Code Guide

Overview

Multi-service email platform supporting SMTP/IMAP, SendGrid, Mailgun, Resend, local testing, and webhook integrations (FastMCP 3.2, Prefab UI)

Entry Points

• uv run email-mcp → email_mcp.server:main

Standards

• FastMCP 3.2+ portmanteau tool pattern -- tools use operation enum param
• Responses: structured dicts with success, message, domain-specific fields
• Dual transport: stdio (Claude Desktop) + HTTP (MCP_TRANSPORT=http)
• See mcp-central-docs for fleet-wide coding standards

Session Context

• Before starting work: call email_status() to check connectivity, then check_inbox(service="default", unread_only=True, limit=10) for recent activity
• At end of work: send drafted emails, mark read, subscribe to mailing lists via mailing_list_latest()

Key Files

• README.md -- full documentation
• pyproject.toml -- build config and entry points
• AGENTS.md -- Agent context

Fleet context — required reading

Before any task in this fleet, read mcp-central-docs/standards/AGENT_READING_ORDER.md. It carries the AGENTS.md chain, the 13-file Primary Read List, the domain read list, the pitfalls docs and the bug depot. There are 124 files under standards/; that file is the index that makes them usable.

Search mcp-central-docs/troubleshooting/BUGS_DEPOT.md by symptom before debugging anything — a bug the fleet has already paid for is a lookup, not an investigation.

These few are repeated here rather than linked, because a rule whose violation produces no error cannot depend on anyone following a link:

• Never author multi-line file content with a Bash heredoc (cat > file <<'EOF') — it intermittently writes nothing on this Windows/Git-Bash setup. Use the Write tool. (BUG-031)
• Never patch files with inline Python (python - <<'PY', python -c) — Python's string parser silently converts backslash escapes, so "D:\Dev\repos\x" becomes D: + \D + ev + CR + epos + CR + x. One observed case deleted dict entries while staying valid Python with a clean lint. Use Edit and Write. (BUG-039)
• Never hardcode a port. Claim one with mcp-central-docs/fleet-gate/claim_ports.py, which checks operations/WEBAPP_PORTS.md and every fleet-start.config.ps1.
• Max 5 files per commit and per script invocation; 3+ file edits need a timestamped .bak per file written first.
• Never restart an NSSM service by killing its child — sc.exe stop/start, then verify a NEW PID owns the port.
• Never invent a date or location; read the clock or write UNKNOWN-DATE.
• Prove changes by running them. A gate that reports success having examined nothing is this fleet's most common failure mode.