@buildinternet/uploads 0.48.1 → 0.49.0

package/README.md

@@ -27,6 +27,8 @@ uploads put ./ui.png --frame browser --frame-url "https://app.example"
 uploads put ./after.png --pr 123
 uploads put ./capture-2026-…Z.png --pr 123 --name hero.png   # clean leaf, stable path
 uploads put ./shot.png --pr 123 --name hero.png --dry-run --format url  # preview URL, no upload
+uploads put --url https://cdn.example/shot.png --pr 123
+uploads put --url http://localhost:4321/shot.png
 uploads gallery create --title "Release screenshots"
 uploads put ./after.png --gallery gal_example
 # custom metadata (queryable): page URL, in-app path, which surface
@@ -196,7 +198,7 @@ Config layers (first match wins): CLI flags → env vars → `--env-file` → `~
 
 ## MCP server
 
-`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools include file operations plus public gallery workflows: `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`. Gallery tools return API-provided canonical URLs and never need GitHub credentials. The remaining stdio tools are `put`, `attach`, `list`, `delete`, `get_metadata`, `set_metadata`, `find_files`, `usage`, `reconcile`, `purge_expired`, `comment`, `health`, and `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. `put` and `attach` accept a `metadata` param (same `gh.*` auto-injection as the CLI's `attach`); `get_metadata`, `set_metadata`, and `find_files` mirror `uploads meta get` / `meta set` / `find`. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`health` needs no auth).
+`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools include file operations plus public gallery workflows: `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`. Gallery tools return API-provided canonical URLs and never need GitHub credentials. The remaining stdio tools are `put`, `attach`, `list`, `delete`, `get_metadata`, `set_metadata`, `find_files`, `usage`, `reconcile`, `purge_expired`, `comment`, `whoami`, and `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. `put` and `attach` accept a `metadata` param (same `gh.*` auto-injection as the CLI's `attach`); `get_metadata`, `set_metadata`, and `find_files` mirror `uploads meta get` / `meta set` / `find`. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`whoami` needs no auth).
 
 ```json
 { "command": "uploads", "args": ["--env-file", "/path/to/.env", "mcp"] }

package/dist/cli-help.js

@@ -106,6 +106,7 @@ ${section(style, "Examples:")}
   ${style.command("uploads whoami")}
   ${style.command("uploads put")} ./shot.png --pr 123 --name hero.png
   ${style.command("uploads put")} ./after.png --pr 123
+  ${style.command("uploads put")} --url https://cdn.example/shot.png --pr 123
   ${style.command("uploads put")} ./bug.png --issue 45
   ${style.command("uploads put")} ./shot.png --meta path=/settings --state after
   ${style.command("uploads attach")} ./before.png ./after.png
@@ -155,6 +156,7 @@ ${section(style, "Examples:")}
   ${style.command("uploads whoami")}
   ${style.command("uploads put")} ./shot.png --pr 123 --name hero.png
   ${style.command("uploads put")} ./after.png --pr 123
+  ${style.command("uploads put")} --url https://cdn.example/shot.png --pr 123
   ${style.command("uploads put")} ./bug.png --issue 45 --repo myorg/myapp
   ${style.command("uploads put")} ./shot.png --dry-run --format url
   ${style.command("uploads put")} ./shot.png --meta path=/settings --state after

package/dist/commands/completion.js

@@ -124,7 +124,10 @@ ${subMaps.join("\n")}
 
   if [[ "$cur" == -* ]]; then
     case "$cmd" in
-      put|attach)
+      put)
+        COMPREPLY=( $(compgen -W "\${put_flags[*]} --url" -- "$cur") )
+        ;;
+      attach)
         COMPREPLY=( $(compgen -W "\${put_flags[*]}" -- "$cur") )
         ;;
       screenshot)
@@ -284,6 +287,7 @@ function fishScript() {
             continue;
         lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put attach' -l ${flag.slice(2)}`);
     }
+    lines.push(`complete -c uploads -n '__fish_seen_subcommand_from put' -l url -r`);
     for (const flag of SCREENSHOT_FLAGS) {
         if (!flag.startsWith("--"))
             continue;

package/dist/commands/mcp.js

@@ -10,7 +10,7 @@ const MCP_HELP = `uploads [globals] mcp
 
 Serve the Model Context Protocol (MCP) over stdio for agent clients. Tools
 mirror the CLI commands: put, attach, list, delete, usage, reconcile,
-purge_expired, comment, health, doctor.
+purge_expired, comment, whoami, doctor.
 Global flags before "mcp" (--api-url, --token, --workspace, --env-file)
 configure every tool call; a per-call "workspace" argument overrides
 --workspace, like the CLI's per-command flag.

package/dist/commands.d.ts

@@ -350,7 +350,16 @@ export type PutUploadItem = PutResult & {
  */
 export declare function uploadPuts(opts: {
     client: UploadsClient;
-    files: readonly string[];
+    files?: readonly string[];
+    /**
+     * In-memory bodies (CLI `--url`, MCP `contentUrl`). Mutually exclusive
+     * with `files`. `source` is the failure/progress label (the URL).
+     */
+    byteSources?: readonly {
+        bytes: Uint8Array;
+        filename: string;
+        source: string;
+    }[];
     /** Single-file --name leaf override. */
     nameOverride?: string;
     /** Single-file --key. */

package/dist/commands.js

@@ -8,6 +8,7 @@ import { buildUploadMarkdown } from "./embed.js";
 import { readLocalRepoCommentConfig, resolveCommentOptions } from "./comment-config.js";
 import { urlForGithubEmbed } from "./public-urls.js";
 import { UploadsError } from "./errors.js";
+import { fetchUploadSource, resolveUploadFilename } from "./fetch-upload-source.js";
 import { writeJson, writeStdout } from "./io.js";
 import { imageFactsFromBytes } from "./image-facts.js";
 import { parseMetaFlags, validateMetaMap } from "./metadata.js";
@@ -94,8 +95,12 @@ export function readFileArg(fileArg) {
 }
 // --- put ---
 const PUT_HELP = `uploads put <file...> [options]
+uploads put --url <url> [options]
 
 Upload one or more images for GitHub embeds. Use "-" for stdin (single file only).
+Pass --url (repeatable) to fetch a file instead of a local path. Public HTTPS,
+or http://localhost / 127.0.0.1 / *.localhost on this machine. Other private
+hosts are rejected. The filename comes from the URL path, or --name.
 
 Multiple files upload in parallel (bounded concurrency). One bad file does not
 block the rest; multi-file JSON is { uploads, failures } (exit 1 when any failed).
@@ -135,6 +140,7 @@ MARKDOWN prefers embedUrl for GitHub. Override: UPLOADS_EMBED_PUBLIC_BASE_URL.
 Options:
   --key <key>           Object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>). Single file only
   --name <leaf>         Clean key leaf + default alt (no '/'); keeps --pr/default path. Single file only. Not with --key
+  --url <url>           Fetch this URL and upload its body (repeatable). Public HTTPS, or http://localhost on the CLI. Not with file arguments
   --destination <id>    Typed root: screenshots | gh | f (sets --prefix)
   --prefix <path>       Key prefix (default: screenshots, or UPLOADS_DEFAULT_PREFIX)
   --repo <owner/repo>   Repo segment (default: git remote, or UPLOADS_DEFAULT_REPO)
@@ -201,6 +207,8 @@ Examples:
   uploads put ./shot.png --pr 128 --name hero.webp --dry-run --format url
   uploads put ./after.png --gallery gal_example
   uploads put ./shot.png --meta path=/settings --state after --app web
+  uploads put --url https://cdn.example/shot.png --pr 128 --name hero.png
+  uploads put --url http://localhost:4321/shot.png
 `;
 /**
  * Turns a pr/issue pair (+ optional repo) into a GhTarget; undefined when
@@ -1027,13 +1035,21 @@ function errorDetail(err) {
  * Same partial-failure shape as uploadAttachments.
  */
 export async function uploadPuts(opts) {
-    if (opts.files.length > 1 && opts.files.some((f) => f === "-")) {
+    const files = opts.files ?? [];
+    const byteSources = opts.byteSources ?? [];
+    if (files.length > 0 && byteSources.length > 0) {
+        throw new UsageError("internal: uploadPuts files and byteSources are mutually exclusive");
+    }
+    const count = files.length + byteSources.length;
+    if (count === 0)
+        throw new UsageError("put requires at least one file");
+    if (count > 1 && files.some((f) => f === "-")) {
         throw new UsageError("stdin (-) cannot be combined with multiple file arguments");
     }
-    if (opts.files.length > 1 && opts.explicitKey) {
+    if (count > 1 && opts.explicitKey) {
         throw new UsageError("--key cannot be combined with multiple files");
     }
-    if (opts.files.length > 1 && opts.nameOverride) {
+    if (count > 1 && opts.nameOverride) {
         throw new UsageError("--name cannot be combined with multiple files");
     }
     // Resolved once for the whole batch (issue #631) — never per file.
@@ -1048,18 +1064,33 @@ export async function uploadPuts(opts) {
                 branch: opts.ghBranchTarget.branch,
             })
             : undefined;
-    const slots = await mapBounded(opts.files, opts.concurrency ?? UPLOAD_BATCH_CONCURRENCY, async (file) => {
+    const items = byteSources.length > 0
+        ? byteSources.map((s) => ({
+            source: s.source,
+            filename: opts.nameOverride ?? s.filename,
+            bytes: s.bytes,
+        }))
+        : files.map((file) => ({
+            source: file,
+            path: file,
+        }));
+    const slots = await mapBounded(items, opts.concurrency ?? UPLOAD_BATCH_CONCURRENCY, async (item) => {
+        const file = item.source;
         try {
-            const sourceName = opts.nameOverride ??
+            const bytes = item.bytes ?? readFileArg(item.path ?? file);
+            const sourceName = item.filename ??
+                opts.nameOverride ??
                 (file === "-"
                     ? opts.explicitKey
                         ? basename(opts.explicitKey)
                         : "stdin.bin"
                     : basename(file));
-            const bytes = readFileArg(file);
             // Sidecar manifest from a prior `screenshot --out` of this exact file
-            // (issue #469 lever 2) — see mergeSidecarMeta. Not applicable to stdin.
-            const metadata = file !== "-" ? mergeSidecarMeta(file, bytes, opts.metadata) : opts.metadata;
+            // (issue #469 lever 2) — see mergeSidecarMeta. Not applicable to stdin
+            // or URL fetches.
+            const metadata = item.path && item.path !== "-"
+                ? mergeSidecarMeta(item.path, bytes, opts.metadata)
+                : opts.metadata;
             const { result, prepared, markdown, sentMetadata } = await uploadPreparedImage(opts.client, bytes, sourceName, {
                 frame: opts.frame,
                 optimize: opts.optimize,
@@ -1883,12 +1914,23 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         return 0;
     }
     const files = parsed.positionals;
-    if (files.length === 0) {
-        throw new UsageError("put requires at least one file", {
+    if (parsed.flags.get("--url") === true) {
+        throw new UsageError("missing value for --url", {
+            example: "uploads put --url https://cdn.example/shot.png --pr 123",
+        });
+    }
+    const urlArgs = flagValues(parsed.flags, "--url");
+    if (files.length > 0 && urlArgs.length > 0) {
+        throw new UsageError("--url cannot be combined with file arguments", {
+            example: "uploads put --url https://cdn.example/shot.png --pr 123",
+        });
+    }
+    if (files.length === 0 && urlArgs.length === 0) {
+        throw new UsageError("put requires at least one file or --url", {
             example: "uploads put ./shot.png --pr 123",
         });
     }
-    const multi = files.length > 1;
+    const multi = files.length > 1 || urlArgs.length > 1;
     // Resolved early (issue #700): both the auto-PR opt-out default and the
     // `--no-git`-gated staging/auto-PR detection below need it before the rest
     // of put's flag parsing.
@@ -2135,36 +2177,77 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     const logHuman = !ctx.quiet && format === "human";
     if (logHuman) {
         if (multi) {
-            process.stderr.write(`>> ${dryRun ? "dry run for" : "uploading"} ${files.length} files\n`);
+            const n = files.length > 0 ? files.length : urlArgs.length;
+            process.stderr.write(`>> ${dryRun ? "dry run for" : "uploading"} ${n} files\n`);
         }
         else {
-            const fileArg = files[0];
+            const fileArg = files[0] ?? urlArgs[0];
             process.stderr.write(`>> ${dryRun ? "dry run" : "uploading"} ${fileArg === "-" ? "stdin" : fileArg}\n`);
         }
         if (attachedRef)
             process.stderr.write(`>> attached to ${attachedRef}\n`);
     }
-    const { uploads, failures, firstError, sentMetadata } = await uploadPuts({
-        client: ctx.client,
-        files,
-        nameOverride: nameFlag,
-        explicitKey: keyHint,
-        ghTarget: effectiveGhTarget,
-        ghBranchTarget: stagingTarget,
-        prefix: resolvedPrefix ?? defaults.prefix,
-        repo: flagString(parsed.flags, "--repo") ?? defaults.repo,
-        ref: flagString(parsed.flags, "--ref") ?? defaults.ref,
-        deriveRepoFromGit: !noGit,
-        contentType: contentTypeOverride,
-        dryRun,
-        replace: replaceFlag,
-        optimize: optimizeOpts,
-        frame: frameOpts,
-        metadata,
-        deriveImageFacts: derivedMetaEnabled(parsed.flags, defaults),
-        alt: altFlag,
-        width,
-    });
+    let byteSources;
+    const urlFetchFailures = [];
+    let urlFetchFirstError;
+    if (urlArgs.length > 0) {
+        byteSources = [];
+        for (const raw of urlArgs) {
+            try {
+                const filename = resolveUploadFilename(raw, !multi ? nameFlag : undefined, "--url", {
+                    allowLoopback: true,
+                });
+                const bytes = await fetchUploadSource(raw, {
+                    label: "--url",
+                    userAgent: "uploads.sh/cli",
+                    allowLoopback: true,
+                });
+                byteSources.push({ bytes, filename, source: raw });
+            }
+            catch (err) {
+                urlFetchFirstError ??= err;
+                urlFetchFailures.push({ file: raw, error: errorDetail(err) });
+            }
+        }
+    }
+    let uploads;
+    let failures;
+    let firstError;
+    let sentMetadata;
+    if (byteSources && byteSources.length === 0) {
+        uploads = [];
+        failures = urlFetchFailures;
+        firstError = urlFetchFirstError;
+        sentMetadata = [];
+    }
+    else {
+        const batch = await uploadPuts({
+            client: ctx.client,
+            files: byteSources ? undefined : files,
+            byteSources,
+            nameOverride: byteSources ? undefined : nameFlag,
+            explicitKey: keyHint,
+            ghTarget: effectiveGhTarget,
+            ghBranchTarget: stagingTarget,
+            prefix: resolvedPrefix ?? defaults.prefix,
+            repo: flagString(parsed.flags, "--repo") ?? defaults.repo,
+            ref: flagString(parsed.flags, "--ref") ?? defaults.ref,
+            deriveRepoFromGit: !noGit,
+            contentType: contentTypeOverride,
+            dryRun,
+            replace: replaceFlag,
+            optimize: optimizeOpts,
+            frame: frameOpts,
+            metadata,
+            deriveImageFacts: derivedMetaEnabled(parsed.flags, defaults),
+            alt: altFlag,
+            width,
+        });
+        uploads = batch.uploads;
+        failures = [...urlFetchFailures, ...batch.failures];
+        firstError = urlFetchFirstError ?? batch.firstError;
+        sentMetadata = batch.sentMetadata;
+    }
     // Single-file total failure: rethrow so CLI exit codes stay auth/network-aware.
     if (uploads.length === 0 && failures.length > 0 && !multi) {
         throw firstError instanceof Error ? firstError : new Error(String(firstError));

package/dist/fetch-upload-source.d.ts

@@ -0,0 +1,35 @@
+export declare const FETCH_UPLOAD_SOURCE_TIMEOUT_MS = 15000;
+export declare const FETCH_UPLOAD_SOURCE_MAX_REDIRECTS = 5;
+/** Client-side cap when the caller does not pass a workspace policy ceiling. */
+export declare const FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES: number;
+export interface FetchableUploadUrlOptions {
+    /**
+     * CLI / stdio MCP only. Permit loopback (`localhost`, `*.localhost`,
+     * `127.0.0.0/8`, `::1`) and `http` on those hosts. LAN, link-local, and
+     * `.internal` stay rejected. Hosted MCP must not set this.
+     */
+    allowLoopback?: boolean;
+}
+export interface FetchUploadSourceOptions extends FetchableUploadUrlOptions {
+    maxBytes?: number;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** Human label in errors (`--url`, `contentUrl`). */
+    label?: string;
+    userAgent?: string;
+}
+/** Parse and reject URLs we will not fetch. Used on the original URL and every redirect. */
+export declare function assertFetchableUploadUrl(raw: string, label?: string, opts?: FetchableUploadUrlOptions): URL;
+/** Filename leaf from a URL path (`https://cdn.example/a/shot.png?x=1` → `shot.png`). */
+export declare function filenameFromUploadUrl(url: URL): string | undefined;
+/** `filename` if given, else the URL path leaf. Throws USAGE when neither works. */
+export declare function resolveUploadFilename(rawUrl: string, filename: string | undefined, label?: string, opts?: FetchableUploadUrlOptions): string;
+/**
+ * GET `url` and return the body bytes, capped at `maxBytes`.
+ *
+ * Redirects are followed manually so each hop is re-validated (scheme, no
+ * credentials, host policy). A public origin cannot redirect onto loopback
+ * even when `allowLoopback` is set. Auth headers are never forwarded.
+ */
+export declare function fetchUploadSource(raw: string, opts?: FetchUploadSourceOptions): Promise<Uint8Array>;

package/dist/fetch-upload-source.js

@@ -0,0 +1,185 @@
+/**
+ * Fetch bytes from a caller-supplied URL for `put --url` / MCP `contentUrl`.
+ *
+ * Guardrails: HTTPS only (http allowed on loopback when `allowLoopback` is
+ * set), no URL credentials, private/internal hosts rejected unless they are
+ * loopback and `allowLoopback` is set. Redirects re-checked each hop; a
+ * public origin cannot redirect onto loopback. No auth headers forwarded.
+ * The server still sniffs and size-caps after this.
+ */
+import { UploadsError } from "./errors.js";
+import { isLoopbackHost, isPrivateOrLocalHost } from "./private-host.js";
+export const FETCH_UPLOAD_SOURCE_TIMEOUT_MS = 15_000;
+export const FETCH_UPLOAD_SOURCE_MAX_REDIRECTS = 5;
+/** Client-side cap when the caller does not pass a workspace policy ceiling. */
+export const FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+function fail(label, message, code = "USAGE") {
+    throw new UploadsError(`${label} ${message}`, code);
+}
+/** Parse and reject URLs we will not fetch. Used on the original URL and every redirect. */
+export function assertFetchableUploadUrl(raw, label = "url", opts = {}) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        fail(label, "must be a valid absolute URL");
+    }
+    const loopback = isLoopbackHost(url.hostname);
+    const allowThisLoopback = Boolean(opts.allowLoopback && loopback);
+    if (url.protocol === "http:") {
+        if (!allowThisLoopback)
+            fail(label, "must be https");
+    }
+    else if (url.protocol !== "https:") {
+        fail(label, "must be https");
+    }
+    if (url.username !== "" || url.password !== "") {
+        fail(label, "must not include credentials");
+    }
+    if (isPrivateOrLocalHost(url.hostname) && !allowThisLoopback) {
+        fail(label, "targets a private or internal network");
+    }
+    return url;
+}
+/** Filename leaf from a URL path (`https://cdn.example/a/shot.png?x=1` → `shot.png`). */
+export function filenameFromUploadUrl(url) {
+    const last = url.pathname.replace(/\/+$/, "").split("/").pop();
+    if (!last)
+        return undefined;
+    let decoded = last;
+    try {
+        decoded = decodeURIComponent(last);
+    }
+    catch {
+        // Keep the raw segment.
+    }
+    const cleaned = decoded.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+    return cleaned || undefined;
+}
+/** `filename` if given, else the URL path leaf. Throws USAGE when neither works. */
+export function resolveUploadFilename(rawUrl, filename, label = "url", opts = {}) {
+    if (filename)
+        return filename;
+    const derived = filenameFromUploadUrl(assertFetchableUploadUrl(rawUrl, label, opts));
+    if (!derived) {
+        throw new UploadsError(`${label} has no filename in the path; pass a filename`, "USAGE");
+    }
+    return derived;
+}
+function timeoutError(label) {
+    fail(label, "fetch timed out", "NETWORK");
+}
+function isAbortError(err) {
+    return ((err instanceof DOMException && err.name === "AbortError") ||
+        (err instanceof Error && err.name === "AbortError"));
+}
+async function readCappedBody(res, maxBytes, label) {
+    const declared = Number(res.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        fail(label, `exceeds the upload limit (${maxBytes} bytes)`);
+    }
+    const body = res.body;
+    if (!body)
+        fail(label, "returned an empty body");
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value || value.byteLength === 0)
+                continue;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => undefined);
+                fail(label, `exceeds the upload limit (${maxBytes} bytes)`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch {
+            // Already locked/cancelled after a size abort.
+        }
+    }
+    if (total === 0)
+        fail(label, "returned an empty body");
+    if (chunks.length === 1)
+        return chunks[0];
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+/**
+ * GET `url` and return the body bytes, capped at `maxBytes`.
+ *
+ * Redirects are followed manually so each hop is re-validated (scheme, no
+ * credentials, host policy). A public origin cannot redirect onto loopback
+ * even when `allowLoopback` is set. Auth headers are never forwarded.
+ */
+export async function fetchUploadSource(raw, opts = {}) {
+    const label = opts.label ?? "url";
+    const timeoutMs = opts.timeoutMs ?? FETCH_UPLOAD_SOURCE_TIMEOUT_MS;
+    const maxBytes = opts.maxBytes ?? FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES;
+    const doFetch = opts.fetch ?? fetch;
+    const timeout = AbortSignal.timeout(timeoutMs);
+    const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
+    const urlOpts = { allowLoopback: opts.allowLoopback };
+    let url = assertFetchableUploadUrl(raw, label, urlOpts);
+    for (let hop = 0; hop <= FETCH_UPLOAD_SOURCE_MAX_REDIRECTS; hop++) {
+        let res;
+        try {
+            res = await doFetch(url, {
+                method: "GET",
+                redirect: "manual",
+                signal,
+                headers: {
+                    accept: "*/*",
+                    "user-agent": opts.userAgent ?? "uploads.sh",
+                },
+            });
+        }
+        catch (err) {
+            if (isAbortError(err) || timeout.aborted)
+                timeoutError(label);
+            throw new UploadsError(`could not fetch ${label}`, "NETWORK");
+        }
+        if (REDIRECT_STATUSES.has(res.status)) {
+            const location = res.headers.get("location");
+            if (!location)
+                fail(label, "redirect is missing a Location header");
+            if (hop === FETCH_UPLOAD_SOURCE_MAX_REDIRECTS) {
+                fail(label, "redirected too many times");
+            }
+            // Loopback is only sticky while we are already on loopback. A public
+            // CDN cannot bounce the CLI onto http://127.0.0.1.
+            url = assertFetchableUploadUrl(new URL(location, url).toString(), label, {
+                allowLoopback: urlOpts.allowLoopback && isLoopbackHost(url.hostname),
+            });
+            continue;
+        }
+        if (res.status !== 200) {
+            throw new UploadsError(`could not fetch ${label} (HTTP ${res.status})`, "NETWORK");
+        }
+        try {
+            return await readCappedBody(res, maxBytes, label);
+        }
+        catch (err) {
+            if (isAbortError(err) || timeout.aborted)
+                timeoutError(label);
+            throw err;
+        }
+    }
+    fail(label, "redirected too many times");
+}

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey
 export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, resolveDestinationRoot, resolvePutPrefix, type BuiltinDestinationId, } from "./destinations.js";
 export { DEFAULT_API_URL, DEFAULT_WORKSPACE, UPLOADS_CONFIG_KEYS, defaultConfigPath, resolveConfigPath, loadConfigFile, loadEnvFile, resolveApiUrl, resolveConfig, describeConfigSources, redactToken, writeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, workspaceFromToken, workspaceMismatch, type UploadsClientConfig, type ResolvedConfig, type WorkspaceSource, type ConfigValueSource, type ConfigSources, type UploadsConfigKey, type UploadsConfigValues, type PutDefaults, } from "./config.js";
 export { UploadsError, type UploadsErrorCode } from "./errors.js";
+export { assertFetchableUploadUrl, fetchUploadSource, filenameFromUploadUrl, resolveUploadFilename, FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES, FETCH_UPLOAD_SOURCE_MAX_REDIRECTS, FETCH_UPLOAD_SOURCE_TIMEOUT_MS, } from "./fetch-upload-source.js";
 export { createUploadsClient, type UploadsClient, type PutOptions, type ProvenanceInput, type ListOptions, type PutResult, type ListItem, type ListResult, type HeadResult, type DeleteResult, type GalleryItem, type Gallery, type GallerySummary, type GalleryListOptions, type GalleryListResult, type CreateGalleryOptions, type AddGalleryItemOptions, type DeleteGalleryOptions, type HealthResult, type UsageResult, type ReconcileResult, type PurgeExpiredResult, type PurgeExpiredResponse, type FindFilesOptions, type FindFilesItem, type FindFilesResult, type MetadataKeysResult, type MetadataValuesResult, type GetMetadataResult, type PatchMetadataOptions, type ResolveGhPrefixOptions, type ResolveGhPrefixResult, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";

package/dist/index.js

@@ -4,6 +4,7 @@ export { sanitizeKeySegment, sha256Short, deriveRepoFromGit, buildScreenshotKey
 export { BUILTIN_DESTINATIONS, isBuiltinDestination, keyMatchesDestination, resolveDestinationRoot, resolvePutPrefix, } from "./destinations.js";
 export { DEFAULT_API_URL, DEFAULT_WORKSPACE, UPLOADS_CONFIG_KEYS, defaultConfigPath, resolveConfigPath, loadConfigFile, loadEnvFile, resolveApiUrl, resolveConfig, describeConfigSources, redactToken, writeConfigKeys, configValuesFromClient, putDefaultsToConfigValues, resolvePutDefaults, mergePutDefaults, workspaceFromToken, workspaceMismatch, } from "./config.js";
 export { UploadsError } from "./errors.js";
+export { assertFetchableUploadUrl, fetchUploadSource, filenameFromUploadUrl, resolveUploadFilename, FETCH_UPLOAD_SOURCE_DEFAULT_MAX_BYTES, FETCH_UPLOAD_SOURCE_MAX_REDIRECTS, FETCH_UPLOAD_SOURCE_TIMEOUT_MS, } from "./fetch-upload-source.js";
 export { createUploadsClient, } from "./client.js";
 export { buildCliProvenance } from "./provenance.js";
 export { META_KEY_RE, META_VALUE_MAX, META_MAX_KEYS, META_MAX_TOTAL_BYTES, validateMetaEntry, parseMetaPair, parseMetaFlags, } from "./metadata.js";

package/dist/mcp/args.d.ts

@@ -10,12 +10,10 @@ export declare function optPosInt(args: ToolArgs, name: string, options?: {
 export declare function optStringRecord(args: ToolArgs, name: string): Record<string, string> | undefined;
 /** A JSON-array argument of strings (e.g. a `delete` or `files` param). */
 export declare function optStringArray(args: ToolArgs, name: string): string[] | undefined;
-/**
- * Shared tool-description text for the metadata-shaped `metadata`/`set`/
- * `filters` params across the CLI/local MCP (put/attach/set_metadata/
- * find_files) and the remote MCP worker (set_metadata/find_files).
- */
-export declare const METADATA_DESCRIPTION = "Queryable custom metadata (key\u2192value), separate from provenance. Omit to leave any metadata already stored for this key untouched; pass an object (even {}) to fully replace it. Keys: lowercase, ^[a-z][a-z0-9._-]{0,63}$. Values: 1-512 printable ASCII characters. Caps: at most 24 keys, at most 8192 total key+value bytes. Canonical keys, which uploads.sh derives automatically where it can: url, path, env, theme, viewport, device, software, captured. Use `path` for the route (e.g. /settings) \u2014 that is the key `find_files` searches by, so spell it `path` and not route/page/screen. `gh.*` is reserved by convention for GitHub PR/issue attachment context (repo/kind/number/ref).";
+/** Shared cue: `path` is the route `find_files` searches by. */
+export declare const METADATA_PATH_CUE = "Use `path` for the route (e.g. /settings), not route/page/screen.";
+/** put/screenshot/attach `metadata`. Key regex and caps stay in usage errors. */
+export declare const METADATA_DESCRIPTION: string;
 export declare const metadataProp: {
     type: string;
     additionalProperties: {
@@ -23,6 +21,8 @@ export declare const metadataProp: {
     };
     description: string;
 };
+/** 1×1 PNG, used only in MCP `inputSchema.examples` so copy-paste from Inspector works. */
+export declare const MCP_EXAMPLE_PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
 export declare const stateProp: {
     type: string;
     enum: ("after" | "before" | "empty" | "error" | "loading")[];

package/dist/mcp/args.js

@@ -66,17 +66,19 @@ export function optStringArray(args, name) {
     }
     return v;
 }
-/**
- * Shared tool-description text for the metadata-shaped `metadata`/`set`/
- * `filters` params across the CLI/local MCP (put/attach/set_metadata/
- * find_files) and the remote MCP worker (set_metadata/find_files).
- */
-export const METADATA_DESCRIPTION = "Queryable custom metadata (key→value), separate from provenance. Omit to leave any metadata already stored for this key untouched; pass an object (even {}) to fully replace it. Keys: lowercase, ^[a-z][a-z0-9._-]{0,63}$. Values: 1-512 printable ASCII characters. Caps: at most 24 keys, at most 8192 total key+value bytes. Canonical keys, which uploads.sh derives automatically where it can: url, path, env, theme, viewport, device, software, captured. Use `path` for the route (e.g. /settings) — that is the key `find_files` searches by, so spell it `path` and not route/page/screen. `gh.*` is reserved by convention for GitHub PR/issue attachment context (repo/kind/number/ref).";
+/** Shared cue: `path` is the route `find_files` searches by. */
+export const METADATA_PATH_CUE = "Use `path` for the route (e.g. /settings), not route/page/screen.";
+/** put/screenshot/attach `metadata`. Key regex and caps stay in usage errors. */
+export const METADATA_DESCRIPTION = "Queryable tags for later search (key→value). " +
+    METADATA_PATH_CUE +
+    " Omit to leave existing tags; pass an object (even {}) to replace them. `state` and `app` have their own fields.";
 export const metadataProp = {
     type: "object",
     additionalProperties: { type: "string" },
     description: METADATA_DESCRIPTION,
 };
+/** 1×1 PNG, used only in MCP `inputSchema.examples` so copy-paste from Inspector works. */
+export const MCP_EXAMPLE_PNG_BASE64 = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==";
 export const stateProp = {
     type: "string",
     enum: [...META_STATE_VALUES],

package/dist/mcp/output-schemas.d.ts

@@ -20,7 +20,7 @@ export declare const repoLinkStatusResultSchema: JsonSchema;
 export declare const usageResultSchema: JsonSchema;
 export declare const reconcileResultSchema: JsonSchema;
 export declare const purgeExpiredResultSchema: JsonSchema;
-export declare const healthResultSchema: JsonSchema;
+export declare const whoamiResultSchema: JsonSchema;
 export declare const promoteToolResultSchema: JsonSchema;
 export declare const galleryResultSchema: JsonSchema;
 export declare const galleryFindResultSchema: JsonSchema;

package/dist/mcp/output-schemas.js

@@ -223,10 +223,14 @@ export const purgeExpiredResultSchema = objectSchema({
     keysTruncated: { type: "boolean" },
     reconcile: reconcileResultSchema,
 });
-export const healthResultSchema = objectSchema({
+export const whoamiResultSchema = objectSchema({
     ok: { type: "boolean" },
+    workspace: { type: "string" },
+    scopes: { type: "array", items: { type: "string" } },
+    userId: nullableString,
+    signedIn: { type: "boolean" },
     apiUrl: { type: "string" },
-});
+}, ["ok", "workspace"]);
 export const promoteToolResultSchema = objectSchema({
     // `promotion` is optional (issue #702): a `keys`-only call (no `branch`)
     // never runs the branch sweep, so there's nothing to report under it.
@@ -307,7 +311,7 @@ export const hostedOutputSchemas = {
     usage: usageResultSchema,
     reconcile: reconcileResultSchema,
     purge_expired: purgeExpiredResultSchema,
-    health: healthResultSchema,
+    whoami: whoamiResultSchema,
 };
 /** Shared-shape stdio tools. Hosted-only tools (`promote`, `repo_link_status`) omitted. */
 export const stdioOutputSchemas = {
@@ -340,7 +344,7 @@ export const stdioOutputSchemas = {
     usage: usageResultSchema,
     reconcile: reconcileResultSchema,
     purge_expired: purgeExpiredResultSchema,
-    health: healthResultSchema,
+    whoami: whoamiResultSchema,
     report: objectSchema({
         ok: { type: "boolean" },
         id: { type: "string" },

package/dist/mcp/server.d.ts

@@ -18,18 +18,18 @@
  * must never go to stdout.
  */
 import { McpServer, type Implementation, type jsonSchemaValidator } from "@modelcontextprotocol/server";
-export { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, metadataArgWithCanonical, metadataProp, stateProp, optBool, optPosInt, optString, optStringArray, optStringRecord, usage, type ToolArgs, } from "./args.js";
+export { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, METADATA_PATH_CUE, MCP_EXAMPLE_PNG_BASE64, metadataArgWithCanonical, metadataProp, stateProp, optBool, optPosInt, optString, optStringArray, optStringRecord, usage, type ToolArgs, } from "./args.js";
 export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
 export { mapBounded } from "../async.js";
 export { McpServer, type jsonSchemaValidator };
-export { commentResultSchema, deleteResultSchema, findFilesResultSchema, galleryFindResultSchema, galleryResultSchema, healthResultSchema, hostedOutputSchemas, listResultSchema, metadataFacetsResultSchema, metadataResultSchema, promoteToolResultSchema, purgeExpiredResultSchema, putResultSchema, reconcileResultSchema, repoLinkStatusResultSchema, stdioOutputSchemas, usageResultSchema, withOutputSchemas, } from "./output-schemas.js";
+export { commentResultSchema, deleteResultSchema, findFilesResultSchema, galleryFindResultSchema, galleryResultSchema, hostedOutputSchemas, listResultSchema, metadataFacetsResultSchema, metadataResultSchema, promoteToolResultSchema, purgeExpiredResultSchema, putResultSchema, reconcileResultSchema, repoLinkStatusResultSchema, stdioOutputSchemas, usageResultSchema, withOutputSchemas, } from "./output-schemas.js";
 /** MCP tool safety hints. Required so tools/list advertises them for review. */
 export interface McpToolAnnotations {
     readOnlyHint: boolean;
     destructiveHint: boolean;
     openWorldHint: boolean;
 }
-/** Lookup / list / health. Does not change workspace or public state. */
+/** Lookup / list / whoami. Does not change workspace or public state. */
 export declare const mcpRead: McpToolAnnotations;
 /** Creates or updates a public object, gallery, or comment without deleting. */
 export declare const mcpWritePublic: McpToolAnnotations;
@@ -50,9 +50,9 @@ export type McpSecurityScheme = {
 export declare const mcpOAuthRead: McpSecurityScheme[];
 export declare const mcpOAuthWrite: McpSecurityScheme[];
 export declare const mcpOAuthDelete: McpSecurityScheme[];
-/** Authenticated, no particular file scope (hosted `health`). */
+/** Authenticated, no particular file scope (hosted `whoami`). */
 export declare const mcpOAuthAny: McpSecurityScheme[];
-/** Callable without a token (stdio `health`). */
+/** Callable without a token (stdio `whoami` when unsigned-in). */
 export declare const mcpNoAuth: McpSecurityScheme[];
 /**
  * Thrown when a presented token is missing a required scope. wrapHandler

package/dist/mcp/server.js

@@ -21,12 +21,12 @@ import { fromJsonSchema, McpServer, } from "@modelcontextprotocol/server";
 import { UploadsError } from "../errors.js";
 import { errorCodeFromUnknown, recordEvent } from "../telemetry.js";
 import { ToolBatchError } from "./batch-error.js";
-export { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, metadataArgWithCanonical, metadataProp, stateProp, optBool, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
+export { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, METADATA_PATH_CUE, MCP_EXAMPLE_PNG_BASE64, metadataArgWithCanonical, metadataProp, stateProp, optBool, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
 export { ToolBatchError, batchFailureMessage } from "./batch-error.js";
 export { mapBounded } from "../async.js";
 export { McpServer };
-export { commentResultSchema, deleteResultSchema, findFilesResultSchema, galleryFindResultSchema, galleryResultSchema, healthResultSchema, hostedOutputSchemas, listResultSchema, metadataFacetsResultSchema, metadataResultSchema, promoteToolResultSchema, purgeExpiredResultSchema, putResultSchema, reconcileResultSchema, repoLinkStatusResultSchema, stdioOutputSchemas, usageResultSchema, withOutputSchemas, } from "./output-schemas.js";
-/** Lookup / list / health. Does not change workspace or public state. */
+export { commentResultSchema, deleteResultSchema, findFilesResultSchema, galleryFindResultSchema, galleryResultSchema, hostedOutputSchemas, listResultSchema, metadataFacetsResultSchema, metadataResultSchema, promoteToolResultSchema, purgeExpiredResultSchema, putResultSchema, reconcileResultSchema, repoLinkStatusResultSchema, stdioOutputSchemas, usageResultSchema, withOutputSchemas, } from "./output-schemas.js";
+/** Lookup / list / whoami. Does not change workspace or public state. */
 export const mcpRead = {
     readOnlyHint: true,
     destructiveHint: false,
@@ -56,9 +56,9 @@ function oauth(scopes) {
 export const mcpOAuthRead = oauth(["files:read"]);
 export const mcpOAuthWrite = oauth(["files:write"]);
 export const mcpOAuthDelete = oauth(["files:delete"]);
-/** Authenticated, no particular file scope (hosted `health`). */
+/** Authenticated, no particular file scope (hosted `whoami`). */
 export const mcpOAuthAny = oauth([]);
-/** Callable without a token (stdio `health`). */
+/** Callable without a token (stdio `whoami` when unsigned-in). */
 export const mcpNoAuth = [{ type: "noauth" }];
 /**
  * Thrown when a presented token is missing a required scope. wrapHandler

package/dist/mcp/tools.d.ts

@@ -1,6 +1,6 @@
 /**
  * MCP tool set mirroring the CLI commands (put, attach, list, delete,
- * usage, reconcile, purge_expired, comment, health, doctor). Config is
+ * usage, reconcile, purge_expired, comment, whoami, doctor). Config is
  * resolved fresh per tool call so a
  * per-call `workspace` argument behaves like the CLI's --workspace flag, and
  * a missing token surfaces as a tool error rather than a startup failure.

package/dist/mcp/tools.js

@@ -3,13 +3,14 @@ import { buildDoctorReport, ghListPrefixes, ghMergedList, makeGhTarget, mergeSta
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { resolvePutPrefix } from "../destinations.js";
+import { fetchUploadSource, resolveUploadFilename } from "../fetch-upload-source.js";
 import { ghKeyPrefix, ghPrivateKeyPrefix } from "../github.js";
 import { safeCaptureFacts } from "../capture-facts.js";
 import { deriveRepoSlugFromGit } from "../keys.js";
 import { validateMetaMap } from "../metadata.js";
 import { mergeDerivedMeta } from "../metadata-vocab.js";
 import { execRunner, ghMetadataFromTargetWithTitle, resolveCurrentBranch, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
-import { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, metadataArgWithCanonical, metadataProp, optBool, optPosInt, optString, optStringArray, optStringRecord, stateProp, usage, } from "./args.js";
+import { appProp, canonicalMetaFromArgs, METADATA_PATH_CUE, metadataArgWithCanonical, metadataProp, optBool, optPosInt, optString, optStringArray, optStringRecord, stateProp, usage, } from "./args.js";
 import { batchFailureMessage, mcpDestroyPublic, mcpNoAuth, mcpOAuthAny, mcpOAuthDelete, mcpOAuthRead, mcpOAuthWrite, mcpRead, mcpWriteInternal, mcpWritePublic, stdioOutputSchemas, withOutputSchemas, ToolBatchError, } from "./server.js";
 import { attachmentFromText, buildReportPayload, parseReportType, REPORT_TYPES, submitReport, validateReportMessage, } from "../report.js";
 import { resolveApiUrl } from "../config.js";
@@ -272,30 +273,34 @@ export function createUploadsMcpTools(opts) {
             title: "Upload file",
             annotations: mcpDestroyPublic,
             securitySchemes: mcpOAuthWrite,
-            description: "Upload one or more files to uploads.sh and get public URL(s) plus GitHub-ready embed markdown. Single-file: pass `file` or `contentBase64`+`filename` (flat result with `url`/`embedUrl`/`markdown`). Multi-file: pass `files` (paths; parallel; returns `uploads`+`failures`). Prefer `embedUrl` in PR/issue markdown. With `pr`/`issue` keys are stable and `comment` syncs the managed attachments comment. All uploads are public; pr/issue keys are predictable — upload only non-sensitive media.",
+            description: "Upload one or more files and get a public URL plus GitHub-ready markdown. Prefer `embedUrl` in GitHub markdown. Pass `contentUrl` for a public HTTPS file, or http://localhost on this machine, instead of a local path. With `pr`/`issue`, keys are stable and the managed comment is synced. All uploads are public.",
             inputSchema: {
                 type: "object",
                 properties: {
                     file: {
                         type: "string",
-                        description: "Path of a single file to upload. Exactly one of file, files, or contentBase64 is required.",
+                        description: "Path of a single file to upload. Exactly one of file, files, contentBase64, or contentUrl is required.",
                     },
                     files: {
                         type: "array",
                         items: { type: "string" },
-                        description: "Paths of multiple files to upload in parallel. Returns { uploads, failures }. Cannot combine with file, contentBase64, key, or filename.",
+                        description: "Paths of multiple files to upload in parallel. Returns { uploads, failures }. Cannot combine with file, contentBase64, contentUrl, key, or filename.",
                     },
                     contentBase64: {
                         type: "string",
                         description: "Base64-encoded file content for in-memory uploads; requires filename.",
                     },
+                    contentUrl: {
+                        type: "string",
+                        description: "URL to fetch and upload. Public HTTPS, or http://localhost / 127.0.0.1 / *.localhost on this machine. Filename is optional when the URL path has a leaf. Other private/internal hosts are rejected. Exactly one of file, files, contentBase64, or contentUrl.",
+                    },
                     filename: {
                         type: "string",
-                        description: "Filename for contentBase64 content (drives the key and content type). With single `file`, overrides the key's leaf (clean name) while keeping the pr/default path.",
+                        description: "Filename for contentBase64/contentUrl (drives the key and content type). With single `file`, overrides the key's leaf (clean name) while keeping the pr/default path.",
                     },
                     key: {
                         type: "string",
-                        description: "Explicit object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>). Single file only; cannot be combined with pr/issue.",
+                        description: "Override the object key. Single file only; cannot combine with `pr`/`issue`.",
                     },
                     destination: {
                         type: "string",
@@ -351,7 +356,7 @@ export function createUploadsMcpTools(opts) {
                     },
                     comment: {
                         type: "boolean",
-                        description: "With pr/issue (or auto-detected PR context): create or update the managed attachments comment. Posts as uploads-sh[bot] when the GitHub App is installed on the repo; otherwise via local gh auth (best-effort).",
+                        description: "With `pr`/`issue` (or an auto-detected PR): create or update the managed attachments comment. Best-effort.",
                     },
                     dryRun: {
                         type: "boolean",
@@ -359,7 +364,7 @@ export function createUploadsMcpTools(opts) {
                     },
                     replace: {
                         type: "boolean",
-                        description: "Allow overwriting an existing object on a strict (non-gh/) key: explicit key, or the default put path. Default false — an existing object there is refused (key_exists) unless this is true or UPLOADS_OVERWRITE=1 is set in the server's environment. No effect on pr/issue keys, which always overwrite.",
+                        description: "Overwrite an existing object on a non-`gh/` key. Default false (or true if UPLOADS_OVERWRITE=1). No effect on `pr`/`issue` keys, which always overwrite.",
                     },
                     metadata: metadataProp,
                     state: stateProp,
@@ -367,18 +372,34 @@ export function createUploadsMcpTools(opts) {
                     workspace: workspaceProp,
                 },
                 additionalProperties: false,
+                examples: [
+                    { file: "./after.png", pr: 12, state: "after" },
+                    { file: "./after.png", branch: "feat/settings", state: "after" },
+                    { files: ["./before.png", "./after.png"], pr: 12 },
+                    {
+                        contentUrl: "https://cdn.example/settings-after.png",
+                        pr: 12,
+                        state: "after",
+                    },
+                ],
             },
             async handler(args) {
                 const file = optString(args, "file");
                 const filesArg = optStringArray(args, "files");
                 const contentBase64 = optString(args, "contentBase64");
+                const contentUrl = optString(args, "contentUrl");
                 if (filesArg !== undefined && filesArg.length === 0) {
                     usage("files must be a non-empty array of paths");
                 }
                 const multi = filesArg !== undefined;
-                const sources = [file !== undefined, multi, contentBase64 !== undefined];
+                const sources = [
+                    file !== undefined,
+                    multi,
+                    contentBase64 !== undefined,
+                    contentUrl !== undefined,
+                ];
                 if (sources.filter(Boolean).length !== 1) {
-                    usage("exactly one of file, files, or contentBase64 is required");
+                    usage("exactly one of file, files, contentBase64, or contentUrl is required");
                 }
                 const filenameArg = optString(args, "filename");
                 if (contentBase64 !== undefined && !filenameArg) {
@@ -548,10 +569,29 @@ export function createUploadsMcpTools(opts) {
                     }
                     return { uploads, failures, ...(hint ? { hint } : {}) };
                 }
-                // Single-file: contentBase64 still supported; paths go through uploadPuts.
-                if (contentBase64 !== undefined) {
-                    const sourceName = filenameArg;
-                    const bytes = new Uint8Array(Buffer.from(contentBase64, "base64"));
+                // Single-file: contentBase64 / contentUrl; paths go through uploadPuts.
+                if (contentBase64 !== undefined || contentUrl !== undefined) {
+                    let bytes;
+                    let sourceName;
+                    if (contentUrl !== undefined) {
+                        try {
+                            sourceName = resolveUploadFilename(contentUrl, filenameArg, "contentUrl", {
+                                allowLoopback: true,
+                            });
+                        }
+                        catch (err) {
+                            usage(err instanceof Error ? err.message : String(err));
+                        }
+                        bytes = await fetchUploadSource(contentUrl, {
+                            label: "contentUrl",
+                            userAgent: "uploads.sh/mcp",
+                            allowLoopback: true,
+                        });
+                    }
+                    else {
+                        sourceName = filenameArg;
+                        bytes = new Uint8Array(Buffer.from(contentBase64, "base64"));
+                    }
                     const { result, prepared, markdown } = await uploadPreparedImage(client, bytes, sourceName, {
                         frame: frameOpts,
                         optimize: optimizeOpts,
@@ -639,7 +679,7 @@ export function createUploadsMcpTools(opts) {
             title: "Capture screenshot",
             annotations: mcpDestroyPublic,
             securitySchemes: mcpOAuthWrite,
-            description: "Capture a URL or a local .html file and host it — a hosted, PR-embeddable image in one call. Backend `local` drives an already-installed Chrome/Chromium (dynamically loaded; unavailable in some runtimes); `remote` renders server-side via the workspace's render endpoint and counts against the monthly upload budget. Default via=auto prefers local when found, else remote. localhost/private-network URLs and .html files are local-only — via=remote (or auto falling back to remote) fails fast instead of a doomed request. Shares the put upload pipeline: optional frame, optimize-by-default, pr/issue attachment + comment, gallery, metadata. Uploads are public.",
+            description: "Capture a URL or local HTML file and host it. Shares put's attach, comment, and metadata options. `via=local` needs Chrome; `via=remote` renders server-side. localhost URLs are local-only.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -756,6 +796,10 @@ export function createUploadsMcpTools(opts) {
                 },
                 required: ["target"],
                 additionalProperties: false,
+                examples: [
+                    { target: "http://localhost:4321/settings", pr: 12, state: "after" },
+                    { target: "http://localhost:4321/settings", fullPage: true, state: "empty" },
+                ],
             },
             async handler(args) {
                 const targetArg = optString(args, "target");
@@ -1055,17 +1099,17 @@ export function createUploadsMcpTools(opts) {
                         description: "Keep EXIF/XMP/ICC when optimizing (default: strip for privacy on public embeds).",
                     },
                     ...frameProps,
-                    metadata: {
-                        ...metadataProp,
-                        description: "Extra queryable metadata (key→value), merged with the automatic gh.repo/gh.kind/gh.number/gh.ref pairs — a gh.* pair here loses to the resolved target's own gh.* value. " +
-                            METADATA_DESCRIPTION,
-                    },
+                    metadata: metadataProp,
                     state: stateProp,
                     app: appProp,
                     workspace: workspaceProp,
                 },
                 required: ["files"],
                 additionalProperties: false,
+                examples: [
+                    { files: ["./after.png"], pr: 12, state: "after" },
+                    { files: ["./before.png", "./after.png"], pr: 12 },
+                ],
             },
             async handler(args) {
                 const files = optStringArray(args, "files");
@@ -1181,7 +1225,7 @@ export function createUploadsMcpTools(opts) {
             title: "List staged files",
             annotations: mcpRead,
             securitySchemes: mcpOAuthRead,
-            description: "Read-only view of what's staged for a git branch (attach --branch / bare put on a non-default branch) and whether it will auto-attach once a PR opens. One list call against the branch staging prefix plus a repo-binding check (files:read only). Returns { repo, branch, files, binding }; binding.state is self/other/none/unknown and binding.autoAttach is true only for self.",
+            description: "List files staged for a git branch and whether they will auto-attach when a PR opens. Returns `{ repo, branch, files, binding }`.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1238,7 +1282,7 @@ export function createUploadsMcpTools(opts) {
             title: "Get metadata",
             annotations: mcpRead,
             securitySchemes: mcpOAuthRead,
-            description: "Read an object's queryable custom metadata (D1 key-value pairs, not R2 provenance). Returns `{ metadata }` (empty when none). Object must exist. Same as `uploads meta get`.",
+            description: "Read the queryable tags on one file. Returns `{ metadata }` (empty when none). Same as `uploads meta get`.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1260,14 +1304,15 @@ export function createUploadsMcpTools(opts) {
             title: "Set metadata",
             annotations: mcpWritePublic,
             securitySchemes: mcpOAuthWrite,
-            description: "Merge-set and/or delete an object's queryable custom metadata (D1 key-value pairs, not R2 provenance). `set` wins over `delete` for the same key. " +
-                METADATA_DESCRIPTION +
-                " Requires at least one of `set` or `delete`. Same as `uploads meta set`.",
+            description: "Set or delete queryable tags on an existing file. `set` wins over `delete` for the same key. Requires `set` and/or `delete`. Same as `uploads meta set`.",
             inputSchema: {
                 type: "object",
                 properties: {
                     key: { type: "string", description: "Object key to update." },
-                    set: { ...metadataProp, description: "Keys to set/overwrite. " + METADATA_DESCRIPTION },
+                    set: {
+                        ...metadataProp,
+                        description: "Keys to set or overwrite. " + METADATA_PATH_CUE,
+                    },
                     delete: {
                         type: "array",
                         items: { type: "string" },
@@ -1277,6 +1322,7 @@ export function createUploadsMcpTools(opts) {
                 },
                 required: ["key"],
                 additionalProperties: false,
+                examples: [{ key: "screenshots/settings.png", set: { path: "/settings", state: "after" } }],
             },
             async handler(args) {
                 const key = optString(args, "key");
@@ -1298,13 +1344,15 @@ export function createUploadsMcpTools(opts) {
             title: "Find files",
             annotations: mcpRead,
             securitySchemes: mcpOAuthRead,
-            description: "Find objects whose queryable custom metadata matches ALL of `filters` (ANDed equality) and/or whose key contains `name` (case-insensitive substring). At least one of `filters` or `name` is required. Returns each match's key, public URL, full metadata map, optional `truncated`, and a `cursor` to pass back for the next page (null when there are none; set `all` to follow it for you). Same as `uploads find k=v...` / `uploads find --name <term>`.",
+            description: "Search files by metadata (`filters`) and/or filename substring (`name`). At least one is required. Same as `uploads find`.",
             inputSchema: {
                 type: "object",
                 properties: {
                     filters: {
                         ...metadataProp,
-                        description: "Metadata equality filters (optional when `name` is set). " + METADATA_DESCRIPTION,
+                        description: "Equality filters; all must match. " +
+                            METADATA_PATH_CUE +
+                            " Optional when `name` is set.",
                     },
                     name: {
                         type: "string",
@@ -1326,6 +1374,7 @@ export function createUploadsMcpTools(opts) {
                     workspace: workspaceProp,
                 },
                 additionalProperties: false,
+                examples: [{ filters: { path: "/settings", state: "after" } }, { name: "hero.png" }],
             },
             async handler(args) {
                 const filters = optStringRecord(args, "filters") ?? {};
@@ -1355,7 +1404,7 @@ export function createUploadsMcpTools(opts) {
             title: "List metadata keys",
             annotations: mcpRead,
             securitySchemes: mcpOAuthRead,
-            description: "List the distinct queryable metadata keys present in the workspace, with file counts and distinct-value counts. Use this to discover what is filterable before calling find_files — keys are user/agent-defined, not a fixed schema. Same as `uploads meta keys`. Pass optional `key` to list that key's values instead (`uploads meta values <key>`).",
+            description: "List metadata keys in the workspace (with counts). Pass `key` to list that key's values instead. Use before `find_files`. Same as `uploads meta keys`.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1434,6 +1483,7 @@ export function createUploadsMcpTools(opts) {
                     workspace: workspaceProp,
                 },
                 additionalProperties: false,
+                examples: [{ pr: 12 }],
             },
             async handler(args) {
                 const target = ghTargetFromArgs(args, run);
@@ -1448,16 +1498,32 @@ export function createUploadsMcpTools(opts) {
             },
         },
         {
-            name: "health",
-            title: "Check health",
+            name: "whoami",
+            title: "Who am I",
             annotations: mcpRead,
             securitySchemes: mcpNoAuth,
-            description: "Check uploads.sh API liveness. No auth or arguments required.",
+            description: "Show the active uploads.sh identity: workspace, API URL, and token scopes. Use this to learn which workspace you're talking to. A successful result also means the API is up. For a full setup diagnosis, use `doctor`.",
             inputSchema: { type: "object", properties: {}, additionalProperties: false },
             async handler(args) {
                 const { config, client } = await clientFor(args, false);
-                const result = await client.health();
-                return { ...result, apiUrl: config.apiUrl };
+                const health = await client.health();
+                const signedIn = Boolean(config.token);
+                let scopes;
+                if (signedIn) {
+                    try {
+                        scopes = (await client.usage()).scopes;
+                    }
+                    catch {
+                        // Workspace and API URL are still useful if usage is unavailable.
+                    }
+                }
+                return {
+                    ok: health.ok,
+                    signedIn,
+                    workspace: config.workspace,
+                    apiUrl: config.apiUrl,
+                    ...(scopes ? { scopes } : {}),
+                };
             },
         },
         {

package/dist/private-host.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Literal-form private/loopback/link-local host checks. Mirrors the API's
+ * `isPrivateRenderTarget` so CLI `--via remote` and `put --url` reject the
+ * same targets the render/fetch endpoints would.
+ *
+ * Accepts a bare hostname or an IPv6 literal with its brackets still attached
+ * (as returned by `new URL(...).hostname`, e.g. `"[::1]"`).
+ */
+/**
+ * Loopback only: `localhost`, `*.localhost`, `127.0.0.0/8`, `::1`.
+ * Not RFC1918, not link-local, not `.internal` — those stay blocked even on the CLI.
+ */
+export declare function isLoopbackHost(hostname: string): boolean;
+export declare function isPrivateOrLocalHost(hostname: string): boolean;

package/dist/private-host.js

@@ -0,0 +1,92 @@
+/**
+ * Literal-form private/loopback/link-local host checks. Mirrors the API's
+ * `isPrivateRenderTarget` so CLI `--via remote` and `put --url` reject the
+ * same targets the render/fetch endpoints would.
+ *
+ * Accepts a bare hostname or an IPv6 literal with its brackets still attached
+ * (as returned by `new URL(...).hostname`, e.g. `"[::1]"`).
+ */
+/** IPv4 loopback/private/link-local ranges. */
+const PRIVATE_IPV4_RE = /^(127\.\d+\.\d+\.\d+|0\.0\.0\.0|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|169\.254\.\d+\.\d+)$/;
+/** Hostname forms treated as local/private regardless of DNS resolution. */
+const PRIVATE_HOSTNAME_RE = /^((.+\.)?localhost|.+\.local|.+\.internal)$/i;
+/** IPv6 unique local addresses, fc00::/7 (RFC 4193). */
+const IPV6_ULA_RE = /^f[cd][0-9a-f]{2}:/i;
+/** IPv6 link-local addresses, fe80::/10. */
+const IPV6_LINK_LOCAL_RE = /^fe[89ab][0-9a-f]:/i;
+function isPrivateIPv4(host) {
+    return PRIVATE_IPV4_RE.test(host);
+}
+function stripBrackets(hostname) {
+    return /^\[.+\]$/.test(hostname) ? hostname.slice(1, -1) : hostname;
+}
+/** IPv4-mapped IPv6 tail (`::ffff:127.0.0.1` or `::ffff:7f00:1`) as a dotted quad. */
+function mappedIpv4(host) {
+    const mapped = /^::ffff:(.+)$/i.exec(host);
+    if (!mapped)
+        return undefined;
+    const rest = mapped[1];
+    if (/^\d{1,3}(\.\d{1,3}){3}$/.test(rest))
+        return rest;
+    const hex = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(rest);
+    if (!hex)
+        return undefined;
+    const hi = Number.parseInt(hex[1], 16);
+    const lo = Number.parseInt(hex[2], 16);
+    const a = (hi >> 8) & 0xff;
+    const b = hi & 0xff;
+    const c = (lo >> 8) & 0xff;
+    const d = lo & 0xff;
+    return `${a}.${b}.${c}.${d}`;
+}
+function isLoopbackIpv4(host) {
+    return /^127\.\d+\.\d+\.\d+$/.test(host);
+}
+/**
+ * Loopback only: `localhost`, `*.localhost`, `127.0.0.0/8`, `::1`.
+ * Not RFC1918, not link-local, not `.internal` — those stay blocked even on the CLI.
+ */
+export function isLoopbackHost(hostname) {
+    const host = stripBrackets(hostname);
+    if (host === "localhost" || host.toLowerCase().endsWith(".localhost"))
+        return true;
+    if (host === "::1")
+        return true;
+    if (isLoopbackIpv4(host))
+        return true;
+    const mapped = mappedIpv4(host);
+    return mapped !== undefined && isLoopbackIpv4(mapped);
+}
+export function isPrivateOrLocalHost(hostname) {
+    const host = stripBrackets(hostname);
+    if (isPrivateIPv4(host))
+        return true;
+    if (PRIVATE_HOSTNAME_RE.test(host))
+        return true;
+    if (host === "::1" || host === "::")
+        return true;
+    if (IPV6_ULA_RE.test(host))
+        return true;
+    if (IPV6_LINK_LOCAL_RE.test(host))
+        return true;
+    // IPv4-mapped IPv6, e.g. "::ffff:10.0.0.1" or "::ffff:a00:1" — private iff
+    // the mapped IPv4 quad is private.
+    const mapped = /^::ffff:(.+)$/i.exec(host);
+    if (mapped) {
+        const rest = mapped[1];
+        if (isPrivateIPv4(rest))
+            return true;
+        const hex = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(rest);
+        if (hex) {
+            const hi = Number.parseInt(hex[1], 16);
+            const lo = Number.parseInt(hex[2], 16);
+            const a = (hi >> 8) & 0xff;
+            const b = hi & 0xff;
+            const c = (lo >> 8) & 0xff;
+            const d = lo & 0xff;
+            if (isPrivateIPv4(`${a}.${b}.${c}.${d}`))
+                return true;
+        }
+    }
+    return false;
+}

package/dist/screenshot.d.ts

@@ -1,5 +1,7 @@
+import { isPrivateOrLocalHost } from "./private-host.js";
 import { captureRemote } from "./screenshot-remote.js";
 import type { DetectRoots } from "./screenshot-local.js";
+export { isPrivateOrLocalHost };
 export type ScreenshotBackend = "auto" | "local" | "remote";
 export type WaitUntil = "load" | "domcontentloaded" | "networkidle" | number;
 /**
@@ -48,14 +50,6 @@ export type ScreenshotTarget = {
     path: string;
     html: string;
 };
-/**
- * True for localhost / private-network / link-local hosts — only reachable
- * by the local backend. Accepts a bare hostname or an IPv6 literal with its
- * brackets still attached (as returned by `new URL(...).hostname`, e.g.
- * `"[::1]"`). Mirrors the server's `isPrivateRenderTarget` so `--via remote`
- * fails fast for the same targets the render endpoint itself would reject.
- */
-export declare function isPrivateOrLocalHost(hostname: string): boolean;
 /** Classifies a CLI target: http(s) URL, or a path to a local .html file. */
 export declare function classifyTarget(target: string): ScreenshotTarget;
 /** A measured element box in device (raster) pixels — CSS pixels × deviceScaleFactor. */

package/dist/screenshot.js

@@ -13,7 +13,9 @@ import { basename, resolve as resolvePath } from "node:path";
 import { pathToFileURL } from "node:url";
 import { UploadsError } from "./errors.js";
 import { isMetaStateValue } from "./metadata-vocab.js";
+import { isPrivateOrLocalHost } from "./private-host.js";
 import { captureRemote, MAX_REMOTE_HTML_BYTES } from "./screenshot-remote.js";
+export { isPrivateOrLocalHost };
 /**
  * Host selectors for framework dev toolbars/overlays that otherwise pollute a
  * screenshot of a running dev server. Hidden (display:none) automatically when
@@ -84,57 +86,6 @@ export function parseWaitUntil(raw) {
         return Number.parseInt(raw, 10);
     throw new UploadsError(`invalid wait strategy: ${raw} (use load, domcontentloaded, networkidle, or a millisecond count)`, "USAGE");
 }
-/** IPv4 loopback/private/link-local ranges. Mirrors the server's isPrivateRenderTarget. */
-const PRIVATE_IPV4_RE = /^(127\.\d+\.\d+\.\d+|0\.0\.0\.0|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|169\.254\.\d+\.\d+)$/;
-/** Hostname forms treated as local/private regardless of DNS resolution. */
-const PRIVATE_HOSTNAME_RE = /^((.+\.)?localhost|.+\.local|.+\.internal)$/i;
-/** IPv6 unique local addresses, fc00::/7 (RFC 4193). */
-const IPV6_ULA_RE = /^f[cd][0-9a-f]{2}:/i;
-/** IPv6 link-local addresses, fe80::/10. */
-const IPV6_LINK_LOCAL_RE = /^fe[89ab][0-9a-f]:/i;
-function isPrivateIPv4(host) {
-    return PRIVATE_IPV4_RE.test(host);
-}
-/**
- * True for localhost / private-network / link-local hosts — only reachable
- * by the local backend. Accepts a bare hostname or an IPv6 literal with its
- * brackets still attached (as returned by `new URL(...).hostname`, e.g.
- * `"[::1]"`). Mirrors the server's `isPrivateRenderTarget` so `--via remote`
- * fails fast for the same targets the render endpoint itself would reject.
- */
-export function isPrivateOrLocalHost(hostname) {
-    const host = /^\[.+\]$/.test(hostname) ? hostname.slice(1, -1) : hostname;
-    if (isPrivateIPv4(host))
-        return true;
-    if (PRIVATE_HOSTNAME_RE.test(host))
-        return true;
-    if (host === "::1" || host === "::")
-        return true;
-    if (IPV6_ULA_RE.test(host))
-        return true;
-    if (IPV6_LINK_LOCAL_RE.test(host))
-        return true;
-    // IPv4-mapped IPv6, e.g. "::ffff:10.0.0.1" or "::ffff:a00:1" — private iff
-    // the mapped IPv4 quad is private.
-    const mapped = /^::ffff:(.+)$/i.exec(host);
-    if (mapped) {
-        const rest = mapped[1];
-        if (isPrivateIPv4(rest))
-            return true;
-        const hex = /^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/i.exec(rest);
-        if (hex) {
-            const hi = Number.parseInt(hex[1], 16);
-            const lo = Number.parseInt(hex[2], 16);
-            const a = (hi >> 8) & 0xff;
-            const b = hi & 0xff;
-            const c = (lo >> 8) & 0xff;
-            const d = lo & 0xff;
-            if (isPrivateIPv4(`${a}.${b}.${c}.${d}`))
-                return true;
-        }
-    }
-    return false;
-}
 /** Classifies a CLI target: http(s) URL, or a path to a local .html file. */
 export function classifyTarget(target) {
     if (/^https?:\/\//i.test(target)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.48.1",
+  "version": "0.49.0",
   "mcpName": "sh.uploads/mcp",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",