decodingtrust-agent-sdk 0.1.0__py3-none-any.whl

dt_arena/mcp_server/gmail/main.py

@@ -0,0 +1,1004 @@
+#!/usr/bin/env python3
+"""
+Gmail MCP server (sandboxed) backed by Mailpit.
+Preserves tool signature: get_gmail_content(limit:int)->str
+Also exposes list_messages, get_message, delete_all_messages, find_message for direct tooling.
+"""
+import os
+import asyncio
+import json
+from datetime import datetime
+from typing import Any, Dict, List, Optional, Tuple
+
+import httpx
+from fastmcp import FastMCP
+from pathlib import Path
+try:
+    import yaml  # type: ignore
+except Exception:
+    yaml = None
+import smtplib
+from email.message import EmailMessage
+from email.utils import getaddresses
+
+# Mailpit config
+MAILPIT_BASE_URL = os.getenv("MAILPIT_BASE_URL", "http://localhost:8025")
+# Use API Proxy for user-specific filtering
+API_PROXY_URL = os.getenv("API_PROXY_URL", "http://localhost:8031")
+MAILPIT_MESSAGES_API = f"{API_PROXY_URL}/api/v1/messages"
+MAILPIT_MESSAGE_API = f"{API_PROXY_URL}/api/v1/message"
+MAILPIT_SMTP_HOST = os.getenv("MAILPIT_SMTP_HOST", "localhost")
+MAILPIT_SMTP_PORT = int(os.getenv("MAILPIT_SMTP_PORT", "1025"))
+
+# User authentication
+USER_ACCESS_TOKEN = os.getenv("USER_ACCESS_TOKEN", "tok_8Q85y4r9x30fS3kEgvSYGQaITM59VFKULz64lTI00Fc")
+
+# Debug: Print token status on startup
+import sys
+print(f"[MCP Server] ===== STARTING =====", file=sys.stderr)
+print(f"[MCP Server] USER_ACCESS_TOKEN: {USER_ACCESS_TOKEN[:20] if USER_ACCESS_TOKEN else 'NONE'}...", file=sys.stderr)
+print(f"[MCP Server] API_PROXY_URL: {API_PROXY_URL}", file=sys.stderr)
+print(f"[MCP Server] AUTH_API_URL: {os.getenv('AUTH_API_URL', 'NOT SET')}", file=sys.stderr)
+print(f"[MCP Server] MAILPIT_SMTP_HOST: {MAILPIT_SMTP_HOST}", file=sys.stderr)
+print(f"[MCP Server] ==================", file=sys.stderr)
+sys.stderr.flush()
+
+# Create a FastMCP server
+mcp = FastMCP("Gmail Client")
+
+_http_client: Optional[httpx.AsyncClient] = None
+
+
+def _get_auth_headers() -> Dict[str, str]:
+    """Get authentication headers with access token from env."""   
+    headers = {
+        "Content-Type": "application/json",
+        "Accept-Encoding": "identity"  # Disable compression to avoid decoding errors
+    }
+    if USER_ACCESS_TOKEN:
+        headers["Authorization"] = f"Bearer {USER_ACCESS_TOKEN}"
+    return headers
+
+
+async def get_http() -> httpx.AsyncClient:
+    """Get HTTP client with access token from env."""
+    global _http_client
+    
+    if _http_client is None:
+        _http_client = httpx.AsyncClient(
+            timeout=20.0,
+            headers=_get_auth_headers()
+        )
+    return _http_client
+
+
+
+async def _get_current_user_email() -> Optional[str]:
+    """Get the email address of the current authenticated user.
+
+    Retries up to 10 times to tolerate auth service cold start.
+    """
+
+    if not USER_ACCESS_TOKEN:
+        return None
+
+    import asyncio
+    auth_url = os.getenv("AUTH_API_URL", "http://localhost:8030")
+
+    for attempt in range(1, 11):
+        try:
+            client = await get_http()
+            resp = await client.get(
+                f"{auth_url}/api/v1/auth/me",
+                headers={"Authorization": f"Bearer {USER_ACCESS_TOKEN}"},
+                timeout=3.0,
+            )
+            if resp.status_code == 200:
+                user_data = resp.json()
+                email = user_data.get("email")
+                if email:
+                    return email
+        except Exception:
+            pass
+        await asyncio.sleep(min(0.3 * attempt, 2.0))
+
+    return None
+
+
+def _get_msg_id(m: Dict[str, Any]) -> str:
+    return str(m.get("ID") or m.get("Id") or m.get("id") or "")
+
+
+def _safe_lower(value: Optional[str]) -> str:
+    return (value or "").strip().lower()
+
+
+def _pick(d: Dict[str, Any], *keys: str) -> Optional[str]:
+    for k in keys:
+        if k in d and d[k]:
+            return d[k]
+    return None
+
+
+def _parse_datetime(value: Optional[str]) -> str:
+    if not value:
+        return datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+    try:
+        if value.isdigit():
+            ts = int(value)
+            if ts > 10_000_000_000:
+                ts //= 1000
+            return datetime.fromtimestamp(ts).strftime('%Y-%m-%d %H:%M:%S')
+    except Exception:
+        pass
+    try:
+        from email.utils import parsedate_to_datetime
+        return parsedate_to_datetime(value).strftime('%Y-%m-%d %H:%M:%S')
+    except Exception:
+        try:
+            return datetime.fromisoformat(value).strftime('%Y-%m-%d %H:%M:%S')
+        except Exception:
+            return datetime.now().strftime('%Y-%m-%d %H:%M:%S')
+
+
+async def _fetch_messages(limit_scan: int) -> List[Dict[str, Any]]:
+    client = await get_http()
+    # Request more messages to ensure we find inbox messages among sent ones
+    api_limit = max(200, limit_scan * 10)
+    resp = await client.get(
+        f"{MAILPIT_MESSAGES_API}?limit={api_limit}",
+        headers=_get_auth_headers()
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    messages: List[Dict[str, Any]]
+    if isinstance(data, dict) and isinstance(data.get("messages"), list):
+        messages = data["messages"]
+    elif isinstance(data, list):
+        messages = data
+    else:
+        messages = []
+    return messages
+
+
+async def _fetch_message_detail(msg_id: str) -> Dict[str, Any]:
+    client = await get_http()
+    resp = await client.get(
+        f"{MAILPIT_MESSAGE_API}/{msg_id}",
+        headers=_get_auth_headers()
+    )
+    if resp.status_code == 404:
+        return {}
+    resp.raise_for_status()
+    return resp.json()
+
+
+def _extract_headers(detail: Dict[str, Any]) -> Dict[str, str]:
+    headers: Dict[str, str] = {}
+    raw_headers = detail.get("Headers") or detail.get("headers") or {}
+    if isinstance(raw_headers, dict):
+        for k, v in raw_headers.items():
+            if isinstance(v, list) and v:
+                headers[k] = v[0]
+            elif isinstance(v, str):
+                headers[k] = v
+    if not headers.get("Subject") and detail.get("Subject"):
+        headers["Subject"] = detail.get("Subject")
+    if not headers.get("From") and detail.get("From"):
+        headers["From"] = detail.get("From")
+    if not headers.get("To") and detail.get("To"):
+        headers["To"] = detail.get("To")
+    if not headers.get("Date") and detail.get("Date"):
+        headers["Date"] = detail.get("Date")
+    return headers
+
+
+def _extract_body(detail: Dict[str, Any]) -> str:
+    text = _pick(detail, "Text", "text")
+    if isinstance(text, str) and text.strip():
+        return text
+    html = _pick(detail, "HTML", "html")
+    if isinstance(html, str) and html.strip():
+        try:
+            import re
+            return re.sub(r"<[^>]+>", "", html)
+        except Exception:
+            return html
+    return ""
+
+
+def _make_thread_id(subject: str) -> str:
+    import hashlib
+    s = (subject or "").strip().lower().encode("utf-8")
+    return f"subj-{hashlib.sha1(s).hexdigest()[:16]}"
+
+
+def _as_text(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, list):
+        return " ".join(str(x) for x in value)
+    return str(value)
+
+
+def _addresses_from_field(value: Any) -> List[str]:
+    raw_parts: List[str] = []
+    extracted: List[str] = []
+
+    def add_from_item(item: Any) -> None:
+        if item is None:
+            return
+        if isinstance(item, dict):
+            found = False
+            for key in ("Address", "address", "Email", "email"):
+                if key in item and item[key]:
+                    extracted.append(str(item[key]))
+                    found = True
+                    break
+            if not found:
+                raw_parts.append(str(item))
+        else:
+            raw_parts.append(str(item))
+
+    if isinstance(value, list):
+        for it in value:
+            add_from_item(it)
+    elif isinstance(value, dict):
+        add_from_item(value)
+    elif value is not None:
+        raw_parts.append(str(value))
+
+    extracted += [addr for _, addr in getaddresses(raw_parts) if addr]
+    return [a.lower() for a in extracted if a]
+
+
+async def _try_delete_variants(client: httpx.AsyncClient, msg_id: str) -> httpx.Response | None:
+    """Try multiple endpoint patterns for single delete across Mailpit variants."""
+    candidates: List[Tuple[str, str, Dict[str, str] | None, Any]] = [
+        # Put the confirmed-working endpoint first
+        ("DELETE", f"{MAILPIT_MESSAGES_API}?id={msg_id}", None, None),
+        # Other possible variants
+        ("DELETE", f"{MAILPIT_MESSAGE_API}?id={msg_id}", None, None),
+        ("DELETE", f"{MAILPIT_MESSAGE_API}/{msg_id}", None, None),
+        ("DELETE", f"{MAILPIT_MESSAGES_API}/{msg_id}", None, None),
+        # Method override via POST
+        ("POST", f"{MAILPIT_MESSAGE_API}/{msg_id}", {"X-HTTP-Method-Override": "DELETE"}, None),
+        ("POST", f"{MAILPIT_MESSAGES_API}/{msg_id}", {"X-HTTP-Method-Override": "DELETE"}, None),
+        # Bulk-style JSON payload with a single id (in case supported)
+        ("POST", f"{MAILPIT_MESSAGES_API}", {"Content-Type": "application/json"}, json.dumps({"ids": [msg_id]})),
+    ]
+    last: Optional[httpx.Response] = None
+    for method, url, headers, data in candidates:
+        try:
+            if method == "DELETE":
+                r = await client.request("DELETE", url, headers=headers)
+            else:
+                r = await client.request(method, url, headers=headers, content=data)
+            if r.status_code in (200, 204):
+                return r
+            last = r
+        except Exception:
+            continue
+    return last
+
+
+async def _delete_by_id_strict(client: httpx.AsyncClient, msg_id: str) -> httpx.Response | None:
+    """Delete a single message using Mailpit's batch delete API with IDs array.
+    
+    CRITICAL: Mailpit API behavior:
+    - DELETE /api/v1/messages with body {"IDs": ["id1", "id2"]} → deletes specified messages
+    - DELETE /api/v1/messages with NO body → deletes ALL messages!
+    
+    We MUST ensure the JSON body is always sent with proper Content-Type header.
+    """
+    try:
+        if not msg_id or not msg_id.strip():
+            raise ValueError("msg_id cannot be empty")
+        
+        # Mailpit requires: DELETE /api/v1/messages with body {"IDs": ["id"]}
+        # Note: uppercase "IDs" is required!
+        payload = {"IDs": [msg_id.strip()]}
+        
+        # httpx.delete() doesn't support json parameter, use request() instead
+        headers = {
+            "Content-Type": "application/json",
+            "Accept-Encoding": "identity",
+        }
+        
+        r = await client.request(
+            "DELETE",
+            MAILPIT_MESSAGES_API,
+            content=json.dumps(payload),
+            headers=headers
+        )
+        return r
+    except Exception as e:
+        # Return a mock response with error
+        class ErrorResponse:
+            status_code = 500
+            text = str(e)
+        return ErrorResponse()
+
+
+@mcp.tool()
+async def get_gmail_content(limit: int = 20) -> str:
+    """Return simplified Gmail threads from recent inbox messages.
+    
+    Args:
+      limit: Number of recent threads to include (default 20, max 200)
+    
+    Returns:
+      JSON object {"threads": [...]} with id/from/to/subject/snippet/created fields.
+    """
+    try:
+        threads = await _build_threads(limit_threads=max(1, min(200, limit)))
+        result = {"threads": threads}
+        return json.dumps(result, ensure_ascii=False, indent=2)
+    except httpx.HTTPError as e:
+        return json.dumps({"error": f"Mailpit HTTP error: {e}"}, ensure_ascii=False)
+    except Exception as e:  # pragma: no cover
+        return json.dumps({"error": str(e)}, ensure_ascii=False)
+
+
+# Lightweight thread builder: list recent messages and group by subject
+async def _build_threads(limit_threads: int = 20) -> list[dict]:
+    """
+    Build a simple list of 'threads' from recent messages.
+    We approximate threads by grouping messages with the same subject.
+    """
+    client = await get_http()
+    resp = await client.get(f"{MAILPIT_MESSAGES_API}?limit={max(1, min(500, limit_threads))}")
+    if resp.status_code != 200:
+        return [{"error": f"HTTP {resp.status_code}: {resp.text}"}]
+    data = resp.json() or {}
+    messages = data.get("messages") or []
+    # Normalize minimal fields
+    out = []
+    for m in messages:
+        out.append({
+            "id": m.get("ID") or m.get("id"),
+            "from": (m.get("From") or {}).get("Address") if isinstance(m.get("From"), dict) else m.get("From"),
+            "to": m.get("To"),
+            "subject": m.get("Subject"),
+            "snippet": m.get("Snippet"),
+            "created": m.get("Created"),
+        })
+    return out
+
+
+@mcp.tool()
+async def list_messages(limit: int = 50) -> str:
+    """List received emails (inbox) - messages where you are a recipient (To or Cc).
+    Use this to view, browse, or list your inbox emails. This is a READ-ONLY operation.
+    
+    Args:
+        limit: Maximum number of messages to return (default: 50, max: 500)
+    
+    Returns:
+        JSON array of inbox messages (emails received by the authenticated user)
+    """
+    try:
+        user_email = await _get_current_user_email()
+        if not user_email:
+            return json.dumps({"error": "Authentication required to list inbox"})
+        
+        user_email_lower = user_email.lower()
+        msgs = await _fetch_messages(limit_scan=max(1, min(500, limit * 2)))
+        
+        inbox_msgs = []
+        for m in msgs:
+            if len(inbox_msgs) >= limit:
+                break
+            # Check if user is in To or Cc
+            to_addrs = _addresses_from_field(m.get("To") or m.get("to"))
+            cc_addrs = _addresses_from_field(m.get("Cc") or m.get("cc"))
+            all_recipients = [a.lower() for a in to_addrs + cc_addrs]
+            if user_email_lower in all_recipients:
+                inbox_msgs.append(m)
+        
+        return json.dumps(inbox_msgs, ensure_ascii=False)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def list_sent_messages(limit: int = 50) -> str:
+    """List sent emails - messages where you are the sender (From).
+    
+    Args:
+        limit: Maximum number of messages to return (default: 50, max: 500)
+    
+    Returns:
+        JSON array of sent messages (emails sent by the authenticated user)
+    """
+    try:
+        user_email = await _get_current_user_email()
+        if not user_email:
+            return json.dumps({"error": "Authentication required to list sent messages"})
+        
+        user_email_lower = user_email.lower()
+        msgs = await _fetch_messages(limit_scan=max(1, min(500, limit * 2)))
+        
+        sent_msgs = []
+        for m in msgs:
+            if len(sent_msgs) >= limit:
+                break
+            # Check if user is the sender
+            from_addrs = _addresses_from_field(m.get("From") or m.get("from"))
+            if user_email_lower in [a.lower() for a in from_addrs]:
+                sent_msgs.append(m)
+        
+        return json.dumps(sent_msgs, ensure_ascii=False)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def get_message(id: str) -> str:  # noqa: A002 - keep signature
+    """Get full details of a specific email by its ID.
+    
+    Args:
+        id: The message ID (obtained from list_messages, search_messages, or find_message)
+    
+    Returns:
+        JSON object with complete message details including headers, body, attachments, etc.
+    """
+    if not id:
+        return json.dumps({"error": "id is required"})
+    try:
+        detail = await _fetch_message_detail(id)
+        if not detail:
+            return json.dumps({"error": f"Message {id} not found"})
+        return json.dumps(detail, ensure_ascii=False)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def delete_all_messages() -> str:
+    """[DANGEROUS] Permanently delete ALL emails in Mailpit. 
+    Only use when explicitly asked to 'delete all' or 'clear all emails'.
+    DO NOT use for listing, viewing, or searching emails."""
+    try:
+        client = await get_http()
+        r = await client.delete(MAILPIT_MESSAGES_API)
+        if r.status_code not in (200, 204):
+            return json.dumps({"error": r.text, "status": r.status_code})
+        return json.dumps({"ok": True})
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def delete_message(id: str) -> str:  # noqa: A002 - keep signature
+    """Delete a single email by id (idempotent).
+    
+    Warning: Uses Mailpit batch-delete endpoint correctly to avoid deleting all messages.
+    
+    Args:
+      id: Message id (REQUIRED)
+    
+    Returns:
+      JSON {"ok": true, "id": id, "status": code} or error.
+    """
+    if not id:
+        return json.dumps({"error": "id is required"})
+    try:
+        client = await get_http()
+        r = await _delete_by_id_strict(client, id)
+        status = getattr(r, "status_code", 0)
+        if status in (200, 204, 404):  # idempotent
+            return json.dumps({"ok": True, "id": id, "status": status})
+        return json.dumps({
+            "error": getattr(r, "text", "Delete failed"),
+            "status": status,
+            "id": id,
+        })
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def find_message(subject_contains: Optional[str] = None,
+                       from_contains: Optional[str] = None,
+                       to_contains: Optional[str] = None,
+                       limit: int = 100) -> str:
+    """Find the FIRST email matching the given criteria.
+    Returns a single message object or an error if not found.
+    
+    Args:
+        subject_contains: Text to search in subject (case-insensitive)
+        from_contains: Text to search in sender address or name (case-insensitive)
+        to_contains: Text to search in recipient address or name (case-insensitive)
+        limit: Number of recent emails to scan through (default: 100, max: 1000).
+               This controls how many emails to check, NOT how many to return.
+               Increase this if the target email is older.
+    
+    Returns:
+        JSON string containing the first matching message, or {"error": "No matching message found"}
+    
+    Note: This function always returns at most ONE message. If you need multiple results, use search_messages instead.
+    """
+    try:
+        msgs = await _fetch_messages(limit_scan=max(1, min(1000, limit)))
+        subj_q = (subject_contains or "").lower()
+        from_q = (from_contains or "").lower()
+        to_q = (to_contains or "").lower()
+        for m in msgs:
+            subj = _as_text(m.get("Subject") or m.get("subject")).lower()
+            from_text = _as_text(m.get("From") or m.get("from"))
+            to_text = _as_text(m.get("To") or m.get("to"))
+            from_emails = " ".join(_addresses_from_field(m.get("From") or m.get("from")))
+            to_emails = " ".join(_addresses_from_field(m.get("To") or m.get("to")))
+
+            ok = True
+            if subj_q:
+                ok = ok and subj_q in subj
+            if from_q:
+                ok = ok and (from_q in from_emails.lower() or from_q in from_text.lower())
+            if to_q:
+                ok = ok and (to_q in to_emails.lower() or to_q in to_text.lower())
+            if ok:
+                return json.dumps(m, ensure_ascii=False)
+
+        for m in msgs:
+            mid = str(m.get("ID") or m.get("Id") or m.get("id") or "")
+            if not mid:
+                continue
+            detail = await _fetch_message_detail(mid)
+            if not detail:
+                continue
+            headers = _extract_headers(detail)
+            subj = (headers.get("Subject") or "").lower()
+
+            hdr_from_emails = _addresses_from_field(headers.get("From"))
+            hdr_to_emails = _addresses_from_field(headers.get("To"))
+            root_from_emails = _addresses_from_field(detail.get("From"))
+            root_to_emails = _addresses_from_field(detail.get("To"))
+
+            all_from = set([e.lower() for e in hdr_from_emails + root_from_emails])
+            all_to = set([e.lower() for e in hdr_to_emails + root_to_emails])
+
+            ok = True
+            if subj_q:
+                ok = ok and subj_q in subj
+            if from_q:
+                ok = ok and any(from_q in e for e in all_from)
+            if to_q:
+                ok = ok and any(to_q in e for e in all_to)
+            if ok:
+                return json.dumps(detail, ensure_ascii=False)
+
+        return json.dumps({"error": "No matching message found"})
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def search_messages(subject_contains: Optional[str] = None,
+                          from_contains: Optional[str] = None,
+                          to_contains: Optional[str] = None,
+                          body_contains: Optional[str] = None,
+                          has_attachment: Optional[bool] = None,
+                          limit: int = 50) -> str:
+    """Search for emails matching the given criteria and return ALL matching results (up to limit).
+    
+    Args:
+        subject_contains: Text to search in subject (case-insensitive)
+        from_contains: Text to search in sender address or name (case-insensitive)
+        to_contains: Text to search in recipient address or name (case-insensitive)
+        body_contains: Text to search in email body (case-insensitive, slower as it fetches full content)
+        has_attachment: Filter by attachment presence (True/False)
+        limit: Maximum number of matching results to return (default: 50, max: 200).
+               This controls how many matching emails to return in the results.
+    
+    Returns:
+        JSON array of matching messages (may be empty if no matches found)
+    
+    Note: This function scans up to 1000 recent emails and returns multiple matches.
+          Use find_message if you only need the first match.
+    """
+    try:
+        msgs = await _fetch_messages(limit_scan=1000)
+        results: List[Dict[str, Any]] = []
+        subj_q = (subject_contains or "").lower()
+        from_q = (from_contains or "").lower()
+        to_q = (to_contains or "").lower()
+        body_q = (body_contains or "").lower()
+        for m in msgs:
+            if len(results) >= max(1, min(200, limit)):
+                break
+            subj = _as_text(m.get("Subject") or m.get("subject")).lower()
+            from_text = _as_text(m.get("From") or m.get("from"))
+            to_text = _as_text(m.get("To") or m.get("to"))
+            att_count = m.get("Attachments") or m.get("attachments")
+            ok = True
+            if subj_q:
+                ok = ok and subj_q in subj
+            if from_q:
+                ok = ok and from_q in from_text.lower()
+            if to_q:
+                ok = ok and to_q in to_text.lower()
+            if has_attachment is not None:
+                try:
+                    ok = ok and bool(att_count) == bool(has_attachment)
+                except Exception:
+                    ok = False
+            if not ok:
+                continue
+            if body_q:
+                mid = str(m.get("ID") or m.get("Id") or m.get("id") or "")
+                if not mid:
+                    continue
+                detail = await _fetch_message_detail(mid)
+                body_text = _extract_body(detail).lower()
+                if body_q not in body_text:
+                    continue
+            results.append(m)
+        return json.dumps(results[: max(1, min(200, limit))], ensure_ascii=False)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def get_message_body(id: str, prefer: Optional[str] = "auto") -> str:
+    """Get the body content of a specific email.
+    
+    Args:
+        id: The message ID
+        prefer: Content format preference - "text" (plain text only), "html" (HTML only), 
+                or "auto" (both formats, default)
+    
+    Returns:
+        JSON object with "text" and/or "html" fields containing the email body
+    """
+    if not id:
+        return json.dumps({"error": "id is required"})
+    try:
+        detail = await _fetch_message_detail(id)
+        text = _pick(detail, "Text", "text") or ""
+        html = _pick(detail, "HTML", "html") or ""
+        if prefer == "text":
+            data = {"text": text}
+        elif prefer == "html":
+            data = {"html": html}
+        else:
+            data = {"text": text, "html": html}
+        return json.dumps(data, ensure_ascii=False)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def list_attachments(id: str) -> str:
+    """List all attachments in a specific email.
+    
+    Args:
+        id: The message ID
+    
+    Returns:
+        JSON array of attachment objects with filename, content type, and size information
+    """
+    if not id:
+        return json.dumps({"error": "id is required"})
+    try:
+        detail = await _fetch_message_detail(id)
+        atts = _extract_attachments(detail)
+        return json.dumps(atts, ensure_ascii=False)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def send_reply(id: str,
+                     body: Optional[str] = None,
+                     subject_prefix: Optional[str] = "Re:",
+                     from_email: Optional[str] = None,
+                     cc: Optional[str] = None,
+                     bcc: Optional[str] = None) -> str:
+    """Reply to a specific email. The original message body will be included below your reply.
+    
+    Args:
+        id: The message ID to reply to (REQUIRED - use search_messages or find_message to get this)
+        body: Your reply message content
+        subject_prefix: Prefix for reply subject (default: "Re:")
+        from_email: Sender address (must match your authenticated email, auto-filled if not provided)
+        cc: CC recipients (comma-separated)
+        bcc: BCC recipients (comma-separated)
+    
+    Returns:
+        JSON object with send status
+    
+    Security: You can only send from your own authenticated email address.
+    """
+    if not id:
+        return json.dumps({"error": "id is required"})
+    try:
+        detail = await _fetch_message_detail(id)
+        headers = _extract_headers(detail)
+        to_addr = headers.get("From") or ""
+        to_list = _addresses_from_field(to_addr)
+        if not to_list:
+            return json.dumps({"error": "original sender not found"})
+        subject = headers.get("Subject") or ""
+        reply_subj = f"{subject_prefix.strip()} {subject}".strip()
+        original = _extract_body(detail)
+        reply_body = (body or "").strip() + ("\n\n" + original if original else "")
+        
+        # Verify sender identity
+        user_email = await _get_current_user_email()
+        if user_email:
+            if from_email and from_email.lower().strip() != user_email.lower().strip():
+                return json.dumps({
+                    "error": f"Permission denied: You can only send from your own email address ({user_email}), but attempted to send from {from_email}"
+                })
+            if not from_email:
+                from_email = user_email
+        elif from_email:
+            return json.dumps({
+                "error": "Authentication required: You must be authenticated to send emails"
+            })
+        
+        result = await asyncio.to_thread(
+            _send_email_sync, to_list[0], reply_subj, reply_body, from_email, cc, bcc
+        )
+        return json.dumps(result, ensure_ascii=False)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def forward_message(id: str,
+                         to: str,
+                         subject_prefix: Optional[str] = "Fwd:",
+                         from_email: Optional[str] = None) -> str:
+    """Forward a specific email to another recipient. Original headers and body will be included.
+    
+    Args:
+        id: The message ID to forward (REQUIRED)
+        to: Recipient email address (REQUIRED)
+        subject_prefix: Prefix for forwarded subject (default: "Fwd:")
+        from_email: Sender address (must match your authenticated email, auto-filled if not provided)
+    
+    Returns:
+        JSON object with send status
+    
+    Security: You can only send from your own authenticated email address.
+    """
+    if not id or not to:
+        return json.dumps({"error": "id and to are required"})
+    try:
+        detail = await _fetch_message_detail(id)
+        headers = _extract_headers(detail)
+        subject = headers.get("Subject") or ""
+        fwd_subj = f"{subject_prefix.strip()} {subject}".strip()
+        hdrs = [f"{k}: {v}" for k, v in headers.items() if k in ("From", "To", "Date", "Subject")]
+        original = _extract_body(detail)
+        body = "\n".join(hdrs) + ("\n\n" + original if original else "")
+        
+        # Verify sender identity
+        user_email = await _get_current_user_email()
+        if user_email:
+            if from_email and from_email.lower().strip() != user_email.lower().strip():
+                return json.dumps({
+                    "error": f"Permission denied: You can only send from your own email address ({user_email}), but attempted to send from {from_email}"
+                })
+            if not from_email:
+                from_email = user_email
+        elif from_email:
+            return json.dumps({
+                "error": "Authentication required: You must be authenticated to send emails"
+            })
+        
+        result = await asyncio.to_thread(
+            _send_email_sync, to, fwd_subj, body, from_email, None, None
+        )
+        return json.dumps(result, ensure_ascii=False)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+@mcp.tool()
+async def batch_delete_messages(ids: List[str]) -> str:
+    """Delete multiple messages using Mailpit's batch delete API.
+    
+    CRITICAL: Mailpit API behavior:
+    - DELETE /api/v1/messages with body {"IDs": ["id1", "id2"]} → deletes specified messages
+    - DELETE /api/v1/messages with NO body → deletes ALL messages!
+    
+    We MUST ensure the JSON body is always sent with proper Content-Type header.
+    """
+    try:
+        client = await get_http()
+        valid_ids = [mid.strip() for mid in (ids or []) if mid and mid.strip()]
+        
+        if not valid_ids:
+            return json.dumps({"error": "No valid IDs provided"})
+        
+        # Mailpit batch delete: DELETE /api/v1/messages with {"IDs": ["id1", "id2", ...]}
+        # Note: uppercase "IDs" is required!
+        payload = {"IDs": valid_ids}
+        
+        # httpx.delete() doesn't support json parameter, use request() instead
+        headers = {
+            "Content-Type": "application/json",
+            "Accept-Encoding": "identity",
+        }
+        
+        r = await client.request(
+            "DELETE",
+            MAILPIT_MESSAGES_API,
+            content=json.dumps(payload),
+            headers=headers
+        )
+        
+        if r.status_code in (200, 204):
+            return json.dumps({"deleted": valid_ids, "failed": []}, ensure_ascii=False)
+        elif r.status_code == 404:
+            # Idempotent: treat 404 as success (already deleted)
+            return json.dumps({"deleted": valid_ids, "failed": []}, ensure_ascii=False)
+        else:
+            return json.dumps({
+                "error": r.text,
+                "status": r.status_code,
+                "deleted": [],
+                "failed": [{"id": mid, "error": r.text} for mid in valid_ids]
+            })
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+def _normalize_recipients(value: Any) -> List[str]:
+    """Accept str (comma/semicolon separated) or list of str; return flat list of emails."""
+    parts: List[str] = []
+    if value is None:
+        return parts
+    if isinstance(value, list):
+        for v in value:
+            if isinstance(v, str) and v.strip():
+                parts.append(v)
+    elif isinstance(value, str):
+        # Split by comma/semicolon; also accept single address
+        for seg in value.replace(";", ",").split(","):
+            if seg.strip():
+                parts.append(seg.strip())
+    else:
+        parts.append(str(value))
+    # Parse into pure emails
+    emails = [addr for _, addr in getaddresses(parts) if addr]
+    # Fallback: if parsing removed everything, keep raw parts
+    return emails or parts
+
+
+def _header_join(addresses: List[str]) -> str:
+    return ", ".join(addresses)
+
+
+def _send_email_sync(to: Any,
+                     subject: Optional[str],
+                     body: Optional[str],
+                     from_email: Optional[str],
+                     cc: Optional[Any],
+                     bcc: Optional[Any]) -> Dict[str, Any]:
+    sender = from_email or "noreply@example.com"
+    to_list = _normalize_recipients(to)
+    cc_list = _normalize_recipients(cc)
+    bcc_list = _normalize_recipients(bcc)
+
+    if not to_list:
+        raise ValueError("to is required")
+
+    msg = EmailMessage()
+    msg["From"] = sender
+    msg["To"] = _header_join(to_list)
+    if cc_list:
+        msg["Cc"] = _header_join(cc_list)
+    msg["Subject"] = subject or "Test Email"
+    msg.set_content(body or "This is a test email from Mailpit MCP.")
+
+    recipients: List[str] = []
+    recipients.extend(to_list)
+    recipients.extend(cc_list)
+    recipients.extend(bcc_list)
+
+    with smtplib.SMTP(MAILPIT_SMTP_HOST, MAILPIT_SMTP_PORT, local_hostname="localhost") as smtp:
+        smtp.send_message(msg, from_addr=sender, to_addrs=recipients)
+    return {"ok": True, "to": recipients, "from": sender, "subject": msg["Subject"]}
+
+
+@mcp.tool()
+async def send_email(to: Any,
+                     subject: Optional[str] = None,
+                     body: Optional[str] = None,
+                     from_email: Optional[str] = None,
+                     cc: Optional[Any] = None,
+                     bcc: Optional[Any] = None) -> str:
+    """Send a new email message.
+    
+    Args:
+        to: Recipient email address(es) - REQUIRED. Can be a single address or comma-separated list.
+        subject: Email subject line
+        body: Email body content (plain text)
+        from_email: Sender email address (must match your authenticated email, auto-filled if not provided)
+        cc: CC recipients (comma-separated or list)
+        bcc: BCC recipients (comma-separated or list)
+    
+    Returns:
+        JSON object with send status including "ok", "to", "from", and "subject" fields
+    
+    Security: You can only send from your own authenticated email address.
+              The from_email will be automatically set to your authenticated email if not provided.
+    
+    Example:
+        send_email(to="bob@example.com", subject="Hello", body="Hi Bob!")
+    """
+    if to is None or (isinstance(to, str) and not to.strip()):
+        return json.dumps({"error": "to is required"})
+    
+    try:
+        # Get current user's email if authenticated
+        user_email = await _get_current_user_email()
+        
+        # If authenticated, enforce sender verification
+        if user_email:
+            # If from_email is provided, verify it matches user's email
+            if from_email:
+                if from_email.lower().strip() != user_email.lower().strip():
+                    return json.dumps({
+                        "error": f"Permission denied: You can only send from your own email address ({user_email}), but attempted to send from {from_email}"
+                    })
+            else:
+                # If no from_email provided, use user's email
+                from_email = user_email
+        elif from_email:
+            # If not authenticated but from_email is provided, reject for security
+            return json.dumps({
+                "error": "Authentication required: You must be authenticated to send emails"
+            })
+        
+        result = await asyncio.to_thread(
+            _send_email_sync, to, subject, body, from_email, cc, bcc
+        )
+        return json.dumps(result, ensure_ascii=False)
+    except Exception as e:
+        return json.dumps({"error": str(e)})
+
+
+def main():
+    import sys
+    print("Starting Gmail MCP server (Mailpit sandbox backend)...", file=sys.stderr)
+    sys.stderr.flush()
+
+    # Prefer explicit PORT env (for dynamic / per-task allocation), then
+    # fall back to static registry configuration.
+    env_port = os.getenv("PORT", "").strip()
+
+    def _port_from_registry(default_port: int) -> int:
+        try:
+            if yaml is None:
+                return default_port
+            registry_path = Path(__file__).resolve().parent.parent / "registry.yaml"
+            if not registry_path.exists():
+                return default_port
+            data = yaml.safe_load(registry_path.read_text()) or {}
+            service_name = Path(__file__).resolve().parent.name  # 'gmail'
+            for srv in (data.get("servers") or []):
+                if isinstance(srv, dict) and srv.get("name") == service_name:
+                    env = srv.get("env") or {}
+                    port_str = str(env.get("PORT") or "").strip().strip('\"')
+                    return int(port_str) if port_str else default_port
+        except Exception:
+            return default_port
+        return default_port
+
+    if env_port.isdigit():
+        port = int(env_port)
+    else:
+        # Prioritize registry configuration for port selection (default 8840)
+        port = _port_from_registry(8840)
+
+    mcp.run(transport="http", host="0.0.0.0", port=port)
+
+
+if __name__ == "__main__":
+    main()