@buildinternet/uploads 0.48.0 → 0.49.0

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

@@ -17,19 +17,19 @@
  * The stdio transport comes from `@modelcontextprotocol/server/stdio`; logs
  * must never go to stdout.
  */
-import { McpServer, type jsonSchemaValidator } from "@modelcontextprotocol/server";
-export { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, metadataArgWithCanonical, metadataProp, stateProp, optBool, optPosInt, optString, optStringArray, optStringRecord, usage, type ToolArgs, } from "./args.js";
+import { McpServer, type Implementation, type jsonSchemaValidator } from "@modelcontextprotocol/server";
+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
@@ -81,11 +81,14 @@ export interface McpTool {
     outputSchema?: Record<string, unknown>;
     handler: (args: Record<string, unknown>) => Promise<unknown>;
 }
+/**
+ * Brand mark on `serverInfo.icons` (MCP `Icon`, spec 2026-07-28). PNG is the
+ * type clients that render icons MUST support. The file is the site's
+ * apple-touch-icon (180×180 pixel chevron), already public on uploads.sh.
+ */
+export declare const MCP_SERVER_ICONS: NonNullable<Implementation["icons"]>;
 export declare function createMcpServer(opts: {
-    serverInfo: {
-        name: string;
-        version: string;
-    };
+    serverInfo: Implementation;
     tools: McpTool[];
     /** API base for telemetry (honors uploads --api-url). */
     apiUrl?: string;

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
@@ -138,6 +138,18 @@ function wrapHandler(tool, apiUrl) {
         }
     };
 }
+/**
+ * Brand mark on `serverInfo.icons` (MCP `Icon`, spec 2026-07-28). PNG is the
+ * type clients that render icons MUST support. The file is the site's
+ * apple-touch-icon (180×180 pixel chevron), already public on uploads.sh.
+ */
+export const MCP_SERVER_ICONS = [
+    {
+        src: "https://uploads.sh/apple-touch-icon.png",
+        mimeType: "image/png",
+        sizes: ["180x180"],
+    },
+];
 export function createMcpServer(opts) {
     const { serverInfo, tools, apiUrl, validator } = opts;
     const server = new McpServer(serverInfo, {

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. */