Email attachments: send, upload, fetch, store

[rockfordlhotka]

End-to-end email attachment support across all real email providers (M365,
Outlook.com, Gmail, IMAP/SMTP). Started as outbound-only; grew through
several review iterations into a complete inbound + outbound + temp-store
solution that's been validated against rockbot in the live k8s deployment.

What ships

Outbound (the original PR):

• send_email accepts an attachments array per item with either
  base64Content (inline) or attachmentId (from upload).
• All four real providers attach via the right API: Graph
  FileAttachment (M365/Outlook.com), MimeKit BodyBuilder + base64url
  raw send (Gmail), MimeKit + SMTP (IMAP). ICS and JSON providers
  throw NotSupportedException.
• Per-message cap 25 MB; per-attachment 3 MB on Graph.

Upload endpoint:

• POST /attachments (multipart) returns
  { attachmentId, name, contentType, size, expiresAt }.
• GET /attachments/{id} non-consuming read (raw bytes,
  Content-Disposition).
• DELETE /attachments/{id} explicit cleanup.
• IAttachmentStore interface + InMemoryAttachmentStore: 22-char
  base64url IDs from RandomNumberGenerator, single-use consume on
  send_email, multi-read on GET, 60 s background eviction sweeper.
• Limits: 10 MB per upload, 100 MB global, 15 min TTL. In-process memory
  only — no PVC required for the single-pod deployment.

Inbound attachment visibility + fetch:

• get_email_details populates an attachments[] array with name, size,
  contentType, and a provider-side attachmentId. Implemented for
  M365, Outlook.com, Gmail, and IMAP. ICS/JSON return null.
• New get_email_attachment tool fetches by ID. Two modes:
  • stash (default): bytes go straight into IAttachmentStore,
    returns the store ID; agent passes that ID to send_email to
    forward without bytes ever transiting the LLM.
  • inline: returns base64Content directly; capped at 1 MB.
• Gmail uses positional part-N IDs (handles small inline-data
  attachments and large separate-fetch attachments uniformly). IMAP also
  positional. Graph uses native opaque IDs.

What changed during review

• Original design assumed agents could either base64-encode files or
  share a filesystem with the server. Neither is true for hosted agents
  (M365 Copilot) or k8s-deployed servers without PVCs. The HTTP upload
  endpoint addresses this.
• Initial agent self-test (rockbot) tripped over the missing
  GET /attachments/{id} and burned tool calls guessing URL shapes.
  Added GET/DELETE for symmetry.
• Tool descriptions tightened: emailId parameter explicitly says "NOT
  messageId" after agents fumbled it; get_email_attachment description
  mentions the HTTP GET endpoint as the escape hatch when the file is
  too large for the 1 MB inline cap.
• Gmail attachment fetch initially used Gmail's body.attachmentId,
  which doesn't behave for small inline-data attachments. Switched to
  positional part-N.

Testing

• 243/243 unit tests pass. New coverage:
  • InMemoryAttachmentStoreTests (8): put/consume, oversized rejection,
    global cap, expiry on consume, expiry on read, eviction frees quota,
    peek-twice, delete frees quota.
  • SendEmailToolTests + SendEmailToolMcpInvocationTests (9): direct
    invocation and full AIFunctionFactory round-trip with attachment
    JSON.
  • SendEmailToolAttachmentIdTests (5): ID resolution, name/contentType
    overrides, unknown ID, both-shapes rejection, neither-shape
    rejection.
  • GetEmailAttachmentToolTests (5): stash mode round-trips bytes
    through the store; inline under cap returns base64; inline over cap
    rejects with guidance to use stash; provider-null bubbles as error;
    invalid mode rejects.
• End-to-end manual validation in the live k8s deployment:
  • Outbound: rockbot sent attachments via base64 path (succeeded) and
    via POST /attachments upload + attachmentId flow.
  • Inbound: rockbot fetched a 58-byte text attachment from a Gmail
    message via both inline and stash modes (after the Gmail
    inline-data fix in 1.2.5).
  • HTTP store lifecycle: rockbot's Python script verified
    POST → GET → DELETE → GET-404 round trip.

Deployment

Image rockylhotka/calendar-mcp-http:1.2.6 already deployed and tested
in the cluster.

Known limitations

• Single-replica only. The in-memory store is per-pod; if HttpServer is
  ever scaled out, swap InMemoryAttachmentStore for a Redis-backed
  implementation. Interface stays the same.
• Pod restart drops in-flight uploads. Acceptable given 15 min TTL and
  re-upload-on-retry. PVC would survive restart but adds operational
  surface for marginal benefit at this scale.
• Graph ItemAttachment (forwarded-message attachments) and
  ReferenceAttachment (links) are intentionally excluded from inbound
  visibility — only FileAttachment is surfaced.
• IMAP/Gmail attachment IDs are positional (part-N); fine in practice
  since agents fetch right after listing details.
• No agent-facing streaming. MCP protocol delivers tool results as a
  single JSON-RPC message even over SSE. Server-internal forward
  streaming is a future option (would skip the store entirely for
  forward workflows; requires Graph upload sessions for outbound > 3 MB).

Discoverability follow-up

Filed #53 for the unrelated M365/Outlook \$search quote-handling bug
noticed in the rockbot logs.

🤖 Generated with Claude Code

[rockfordlhotka]

@copilot add a ci build to the repo to build and run tests

[Copilot]

@copilot add a ci build to the repo to build and run tests

Added a dotnet test step to the existing CI workflow in commit 2a80027. The CI now restores, builds, and runs all tests on every PR and push to main.