Add upload_image: re-host an external image on Substack

[marcomoauro]

Summary

Adds an upload_image MCP tool that takes an http(s) image URL, downloads it, re-encodes it as a base64 data URI, and uploads it to POST /api/v1/image, returning a Substack-hosted URL that goes straight into image2.src in set_post_body.

This overturns a documented limit. CLAUDE.md recorded the endpoint as unreachable — "hangs in all three tested encodings, do not implement." That record was wrong. Re-measured live on 2026-08-08 from the authenticated dashboard, the endpoint answers 200 in ~300ms. The three earlier attempts failed because they sent the wrong thing, not for a header detail or a Cloudflare wall: the body is JSON {image: "data:<mime>;base64,…"}, a data URI built in the editor from canvas.toDataURL().

Proven end to end on a real draft before any code was written: upload → captionedImage node → PUT → the editor renders it through Substack's CDN (substackcdn.com/image/fetch/…).

What changed

• SubstackApi.uploadImage({image, post_id}) — JSON data-URI POST to /api/v1/image, post_id mapped to postId and omitted when absent.
• src/tools/upload_image.js — schema (url + optional post_id) and handler: guard → fetch → validate → encode → upload → map the response.
• src/logger.js — elides a base64 data: URI's payload (keeps the mime prefix + omitted length). SubstackApi logs every request body at info, so without this a real upload would put hundreds of KB of base64 on one line. A post body, being prose, is still logged in full.
• Registered in the tools registry; README section added; CLAUDE.md corrected.

Why the tool downloads the image itself

Substack server-fetches only its own S3 bucket — an external URL passed as image answers 400 "Failed to fetch image". So the download happens here, and that fetch (the one place this server contacts a caller-chosen host) is guarded:

• http/https only.
• SSRF block on private/loopback/link-local addresses after DNS resolution, re-checked on every redirect hop (redirects are followed manually — fetch's default follow would contact a redirect target before we ever saw its host). IPv6 hosts are de-bracketed before lookup, and IPv4-mapped IPv6 is caught in both the dotted and the compressed-hex form the URL parser emits (::ffff:a9fe:a9fe = 169.254.169.254).
• image/* content-type, HEIC (and -sequence variants) refused early with a convert-first message.
• A 10 MB cap — ours, not Substack's (its MAX_FILE_SIZE could not be read from the minified bundle) — enforced against a declared Content-Length before the body is read, then against the buffered length; a per-request timeout bounds an unbounded chunked response.

Test plan

• 706 tests pass on Node 24 (.nvmrc) and Node 22 (engines floor).
• Every guard is mutation-tested (broken on purpose, confirmed the test fails, restored).
• Real entrypoint over stdio advertises upload_image in tools/list with additionalProperties: false, required: ['url'].
• Full upload→render loop verified live on a real draft (then reverted).

For the reviewer

One thing is unverified: every live measurement used the browser session cookie, not SUBSTACK_SESSION_TOKEN in a header as SubstackApi sends it. Equivalent in principle, unconfirmed through SubstackApi — the first thing to check if the tool misbehaves against the real API. Accepted residual risks, documented in-code: the DNS-rebinding TOCTOU (validated then fetched separately) and exotic IPv4-in-IPv6 encodings (6to4/Teredo/NAT64).

🤖 Generated with Claude Code