⚙️ FEATURE-#88: Add optional MCP server and Claude Code plugin

[FernandoCelmer]

Description

Adds an optional MCP server so any MCP client (Claude Code, Claude Desktop, Cursor) can read, search, organize and — when allowed — send email through the existing Email API, plus the manifests and skills that make the repository a Claude Code plugin.

Library

• pyproject.toml / poetry.lock — mcp extra (mcp>=2.0), email-profile-mcp console script, keywords. Core install gains no dependency.
• email_profile/mcp/server.py — build() assembles an MCPServer around one lazy Email; CLI with --allow-send, --allow-delete, --max-chars, --http/--host/--port.
• email_profile/mcp/config.py — Settings from EMAIL_MCP_* env (allow flags, max_chars, limit, default_mailbox, attachments_dir).
• email_profile/mcp/session.py — lazy, reconnecting Email handle; RLock serializes IMAP access across tool threads.
• email_profile/mcp/params.py — Uid (digits only, refuses IMAP sequence sets) and Mailbox argument types.
• email_profile/mcp/results.py — typed result models (MessageSummary, MessageDetail, SearchPage, Outcome); bodies truncated, attachment bytes never returned.
• email_profile/mcp/annotations.py — read-only / reversible / sends / destructive tool hints.
• email_profile/mcp/tools/ — mailbox.py (list, search with pagination), message.py (read, attachments, flags, move, delete; save_attachment confined to EMAIL_MCP_ATTACHMENTS_DIR), send.py (send, reply, forward — registered only with --allow-send).
• email_profile/mcp/prompts.py — triage_inbox, find_message, draft_reply, summarize_thread.
• email_profile/clients/imap/query.py — string clauses now escape " and \ per RFC 3501 (search terms can come from untrusted email content).

Plugin

• .mcp.json, .app.json, server.json, .claude-plugin/, .codex-plugin/, .agents/plugins/ — manifests.
• skills/ — six skills: triage-inbox, find-message, read-message, draft-reply, send-email, organize-mailbox.
• scripts/check_skills.py + .github/workflows/plugin.yml — fail when skills and tools drift; validate manifests.

CI / docs

• .github/actions/setup-poetry gains install-extras; test.yml installs mcp.
• README.md (cover, centered header, contents, MCP section with safety model), docs/nav/advanced/mcp-server.md, docs index and install page, examples/, CHANGELOG.md, .env-example.

Issue: 📌 ISSUE — Closes #88

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation updated (documentation was updated and published)

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream modules

[FernandoCelmer]

🔍 Code Review

Code issues found: 5

#	Severity	Comment
1	[Blocking]	EMAIL_MCP_LIMIT never applied
2	[Blocking]	Unsynchronized IMAP session across threads
3	[Blocking]	save_attachment writes anywhere
4	[Blocking]	IMAP search string injection
5	[Blocking]	uid accepts sequence sets