fix(mail): address PR #935 round-2 review

- server/mail.py: guard nc_mail_get_message against an empty OCS payload so
  MailMessage(**{}) can't raise an uncaught ValidationError (returns a clean
  'not found' instead).
- server/mail.py: cap inlined attachment content at MAX_ATTACHMENT_CONTENT_BYTES
  (5 MiB), replacing oversized bodies with a sentinel so a large attachment
  can't blow up the MCP response.
- client/mail.py: harden the OCS meta statuscode parse against a non-numeric
  value (treat as success) instead of letting int() raise an uncaught
  ValueError.
- scanner.py: log the newest-N cap hit once per (user, mailbox) at info level
  (discoverable without flooding multi-tenant logs on every scan tick).
- tests: add incremental-sync scanner cases (new message queued, reappeared
  message clears grace, deletion after grace expiry).

Deferred (tracked, card #376): include doc_type in the _potentially_deleted
grace-period key — a pre-existing cross-cutting collision the reviewer flagged
as a follow-up, not a blocker.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

nextcloud_mcp_server/client/mail.py

@@ -71,7 +71,13 @@ class MailClient(BaseNextcloudClient):
         # instead of silently unwrapping data=null.
         ocs = body.get("ocs", {}) if isinstance(body, dict) else {}
         meta = ocs.get("meta", {})
-        status_code = int(meta.get("statuscode", 200) or 200)
+        # statuscode is spec'd as an int, but harden against a non-numeric value
+        # in a non-spec response rather than letting int() raise ValueError
+        # (which neither MCP-tool handler catches) — treat it as success.
+        try:
+            status_code = int(meta.get("statuscode", 200) or 200)
+        except (TypeError, ValueError):
+            status_code = 200
         if status_code >= 400:
             synthetic = Response(status_code=status_code, request=response.request)
             raise HTTPStatusError(

nextcloud_mcp_server/server/mail.py

@@ -24,6 +24,13 @@ from nextcloud_mcp_server.observability.metrics import instrument_tool
 
 logger = logging.getLogger(__name__)
 
+# Hard cap on inlined attachment content. The Mail OCS API returns the full
+# attachment body in the JSON response, which then has to fit in the host LLM's
+# context window; replace anything larger with a sentinel so a 20 MB design file
+# can't blow up the MCP response. Callers can still see the real size via the
+# message's attachment list.
+MAX_ATTACHMENT_CONTENT_BYTES = 5 * 1024 * 1024
+
 
 def configure_mail_tools(mcp: FastMCP):
     """Configure Mail app MCP tools (read-only)."""
@@ -161,6 +168,13 @@ def configure_mail_tools(mcp: FastMCP):
         client = await get_client(ctx)
         try:
             message_data = await client.mail.get_message(message_id)
+            # An empty payload (OCS data=null with a 200 meta) would make
+            # MailMessage(**{}) raise an uncaught ValidationError; treat it as
+            # not-found instead.
+            if not message_data:
+                raise McpError(
+                    ErrorData(code=-1, message=f"Message {message_id} not found")
+                )
             message = MailMessage(**message_data)
             return GetMessageResponse(message=message)
         except RequestError as e:
@@ -207,11 +221,17 @@ def configure_mail_tools(mcp: FastMCP):
         client = await get_client(ctx)
         try:
             data = await client.mail.get_attachment(message_id, attachment_id)
+            content = data.get("content")
+            if isinstance(content, str) and len(content) > MAX_ATTACHMENT_CONTENT_BYTES:
+                content = (
+                    f"[attachment too large to inline: {len(content)} bytes "
+                    f"(> {MAX_ATTACHMENT_CONTENT_BYTES})]"
+                )
             return GetAttachmentResponse(
                 name=data.get("name"),
                 mime=data.get("mime"),
                 size=data.get("size"),
-                content=data.get("content"),
+                content=content,
             )
         except RequestError as e:
             raise McpError(

nextcloud_mcp_server/vector/scanner.py

@@ -1362,6 +1362,12 @@ async def scan_news_items(
 # wanted, at the cost of more embedding work.
 MAIL_SCAN_MAX_PER_MAILBOX = 100
 
+# Per-process record of (user_id, mailbox_id) for which the newest-N cap has
+# already been logged, so the "older mail not indexed" notice is emitted once at
+# info level (discoverable) rather than on every scan tick (which would flood
+# multi-tenant logs).
+_mail_cap_logged: set[tuple[str, int]] = set()
+
 
 async def scan_mail_messages(
     user_id: str,
@@ -1460,10 +1466,15 @@ async def scan_mail_messages(
                 )
                 continue
 
-            if len(messages) >= MAIL_SCAN_MAX_PER_MAILBOX:
-                logger.debug(
+            cap_key = (user_id, mailbox_id)
+            if len(messages) >= MAIL_SCAN_MAX_PER_MAILBOX and cap_key not in (
+                _mail_cap_logged
+            ):
+                _mail_cap_logged.add(cap_key)
+                logger.info(
                     "[SCAN-%s] Mailbox %s hit the newest-%s cap; older messages "
-                    "are not indexed",
+                    "are not indexed (set MAIL_SCAN_MAX_PER_MAILBOX higher for "
+                    "deeper history)",
                     scan_id,
                     mailbox_id,
                     MAIL_SCAN_MAX_PER_MAILBOX,