email-mcp: Instructions file for Codex

AGENTS.md -- Session Context

Repo: email-mcp

Full-featured email server for MCP clients. Web dashboard at 10812, backend at 10813. 188 tests, 42 MCP tools. Microsoft Graph support for personal Outlook/Hotmail (basic SMTP auth is disabled on those accounts — 535 5.7.139).

---

Key Architecture

Layer	Tech	Notes
MCP Framework	FastMCP 3.2+	fastmcp>=3.2.0,<4
Web Framework	FastAPI	REST endpoints in web.py
Frontend	React 19 + Vite + Tailwind	Port 10812
Tests	pytest (69) + Playwright (17)	86 total
SMTP Testing	aiosmtpd 1.4+	Throwaway servers for testing
DB	JSON file storage	Contacts, drafts, rules, pending

Critical Gotcha

mcp_app.call_tool() returns CallToolResult objects in FastMCP 3.2, not raw dicts. Always use _extract_tool_result() when calling tools from web.py REST endpoints. See web.py for the helper.

---

Current State (2026-08-03)

Features

• 45+ MCP tools: send, receive, search, delete, move, copy, forward, mark-read/unread, folders CRUD, list/configure/remove services, mailing lists, email_help, suggest_subject, agentic_assist, watcher, contacts, workflows, auto-respond, email_connector, email_rag, sync_email_rag, email_rag_stats
• Neural Email RAG & Vector Store: Local LanceDB vector repository (data/email_lancedb) with FastEmbed 384-dim semantic embeddings (BAAI/bge-small-en-v1.5), GPU accelerator auto-discovery (RAG_GPU=1 / CUDAExecutionProvider), paragraph-aware chunking with email header context injection, and incremental sync skips
• Standardized RAG Operations REST: Non-blocking asynchronous background sweep worker (POST /api/rag/sweep, GET /api/rag/status/{job_id}, GET /api/rag/stats, GET /api/rag/search, with /api/reindex backward compatibility)
• Microsoft Graph: personal Outlook/Hotmail via Graph REST (send/receive/search/folders); OAuth device flow with public client ID (no Azure registration); service="default" auto-backs onto Graph when a token exists for an Outlook account
• Folder treeview: Inbox sidebar tree (expandable, unread badges, icons) + inline folder CRUD (new/rename/delete); custom folder names resolve to Graph folder ids
• Fleet connectors: email_connector tool + REST — aiwatcher fleet ingest and robofang email hook (opt-in env, fail-soft)
• Auto-Respond: rule engine + AI drafting + pending queue + spam spoof mode (irate/mock-stupid/absurd/polite-but-confused)
• Bulk Send: paste email lists, max 50, anti-spam warnings
• Mail Watcher: background IMAP polling with webhook POST
• Mail Lab: throwaway aiosmtpd SMTP server with AI message generator
• Contacts: full CRUD + CSV/vCard/Google People/Microsoft Graph import + curated public official lists (US Congress, Austrian Parliament, EU Commission)
• Creative Workflows: 7 AI presets (love letter, complaint, etc.) with text/ascii/svg output
• Expander: short-note-to-full-email with 6 fictional contexts
• Quick Setup: 8 providers (Gmail/Outlook/Yahoo/iCloud/ProtonMail/Zoho/GMX/Fastmail)
• Prompt injection defense: 37 Unicode chars stripped + safety boundary wrapping
• Folder CRUD: list/create/delete/rename IMAP folders
• justfile: SOTA standard (inline dashboard, build=uv sync, check=fmt+lint, ci pipeline)