MCP media_upload tool: design for #620 / #1825

[swissky]

Issue #620 (assigned) and #1825 both ask for the same missing piece: the MCP server has no way to get file bytes into storage. media_create only registers metadata for a file that's already at a storageKey, so fully-automated content workflows (e.g. Claude Code generating a post with a cover image) still have to drop to the CLI or the raw multipart API with CSRF headers.

Proposed design (implementation ready)

A new media_upload tool that accepts:

• base64 — base64-encoded file contents, or
• url — a public http(s) URL to fetch the file from (exactly one of the two)
• filename (required), contentType (required with base64, defaults to the response Content-Type with url), alt (optional)

It runs the exact same pipeline as the REST POST /_emdash/api/media route:

• global MIME allowlist (image/, video/, audio/, application/pdf)
• maxUploadSize limit (with a cheap precheck on the encoded string / Content-Length before buffering)
• content-hash deduplication — identical bytes return the existing item with deduplicated: true
• storage upload with cleanup if record creation fails
• image enrichment (dimensions, blurhash, dominant color)

Returns the media item with id, storageKey, and url, ready for content_create / content_update.

Security: URL fetches go through the existing ssrfSafeFetch (DNS resolution checked against private ranges, redirects re-validated, credential headers stripped cross-origin). Auth mirrors the REST route: media:write scope + Contributor minimum role (the media:upload permission's floor in rbac.ts).

Non-goals: no signed-URL round-trip over MCP (that flow stays as-is via media_create), no chunking — base64 over JSON-RPC is fine within the upload size limit.

PR incoming, linked here.

[swissky]

PR is up: #1954

[marcusbellamyshaw-cell]

Thanks for picking this up, @swissky! Glad to see a PR up already — will take it for a spin.