Skip to content

Stream authenticated binary attachments outside MCP results - #7

Merged
markmnl merged 3 commits into
mainfrom
feat/binary-attachment-downloads
Sep 22, 2026
Merged

markmnl merged 3 commits into
mainfrom
feat/binary-attachment-downloads

Conversation

@markmnl

@markmnl markmnl commented Sep 20, 2026

Copy link
Copy Markdown
Owner

Remote clients previously had to embed binary attachments as Base64 in MCP results. Add get_attachment_download_url, which checks attachment visibility and returns metadata plus a credential-free HTTP resource link. An authenticated GET to /mcp/attachments/{id}/{filename} streams the original bytes with download headers, backpressure, cancellation and explicit failure on interrupted transfers. Close unused connections on shutdown, including replacement connections opened after an aborted fetch. Inline downloads and local stdio saves remain available.

Downloads reuse the existing API-key/OAuth caller handling and require fmsg:read in OAuth mode. The Web API checks message access on every fetch; incoming OAuth tokens are exchanged rather than forwarded. Links use the configured public MCP URL, never request/forwarded headers. OAuth reuses its resource URL; API-key operators set FMSG_MCP_PUBLIC_URL. Update proxy routing, host guidance and deployment documentation accordingly.

Host compatibility: the AI host must fetch the URL using its existing MCP Authorization header. An ordinary unauthenticated browser click returns 401. No credentials are included in links or model output, and no new recipient ACL or messaging approval flow is introduced. Range/resume support is outside this change.

Validation:

  • Typecheck, build and all 145 unit/integration-fixture tests pass locally and in CI on Node 22 and Node 24.
  • New coverage checks exact bytes, Unicode filenames, public proxy prefixes, caller isolation, OAuth scopes/exchange/revocation, upstream errors, Host/Origin/CORS, backpressure, cancellation and truncated-transfer detection.
  • Package dry-run and documentation link checks pass.
  • Docker image build and the extended real two-host acceptance suite pass in CI, including authenticated binary attachment downloads.
  • All checks pass for commit 88a7fef: CI run.

One initial full-suite run hit the existing OAuth wait-expiry test's intermittent 500/401 failure. A subsequent full run and eight targeted runs passed; retain diagnostic response/log output in that assertion. No OAuth exchange logic is changed here.

Closes #6.

@markmnl markmnl mentioned this pull request Sep 20, 2026
@markmnl
markmnl merged commit 23de8ad into main Sep 22, 2026
4 checks passed
@markmnl
markmnl deleted the feat/binary-attachment-downloads branch September 22, 2026 06:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Why Base64 downloads?

1 participant