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/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(