@buildinternet/uploads 0.41.1 → 0.42.1

package/dist/cli-args.d.ts

@@ -79,4 +79,6 @@ export declare function flagBool(flags: CommandFlags["flags"], name: string): bo
 export declare function flagValues(flags: CommandFlags["flags"], name: string): string[];
 /** Command-level workspace override (`--workspace` / `-w`). */
 export declare function commandWorkspace(flags: CommandFlags["flags"]): string | undefined;
-export declare function flagInt(flags: CommandFlags["flags"], name: string, label: string): number | undefined;
+export declare function flagInt(flags: CommandFlags["flags"], name: string, label: string, options?: {
+    allowZero?: boolean;
+}): number | undefined;

package/dist/cli-args.js

@@ -198,16 +198,18 @@ export function flagValues(flags, name) {
 export function commandWorkspace(flags) {
     return flagString(flags, "--workspace") ?? flagString(flags, "-w");
 }
-export function flagInt(flags, name, label) {
+export function flagInt(flags, name, label, options) {
+    const allowZero = options?.allowZero ?? false;
+    const kind = allowZero ? "non-negative" : "positive";
     const raw = flagString(flags, name);
     if (raw === undefined)
         return undefined;
     if (!/^\d+$/.test(raw)) {
-        throw new UsageError(`invalid ${label}: must be a positive integer (got ${raw})`);
+        throw new UsageError(`invalid ${label}: must be a ${kind} integer (got ${raw})`);
     }
     const n = Number.parseInt(raw, 10);
-    if (!Number.isFinite(n) || n <= 0) {
-        throw new UsageError(`invalid ${label}: must be a positive integer (got ${raw})`);
+    if (!Number.isFinite(n) || (allowZero ? n < 0 : n <= 0)) {
+        throw new UsageError(`invalid ${label}: must be a ${kind} integer (got ${raw})`);
     }
     return n;
 }

package/dist/cli-catalog.js

@@ -56,6 +56,7 @@ export const SCREENSHOT_FLAGS = [
     "--viewport",
     "--selector",
     "--full-page",
+    "--max-height",
     "--dark",
     "--light",
     "--wait",

package/dist/commands/screenshot.js

@@ -13,7 +13,7 @@ import { parseMetaFlags, validateMetaMap } from "../metadata.js";
 import { mergeDerivedMeta } from "../metadata-vocab.js";
 import { writeSidecarMeta } from "../sidecar.js";
 import { readStdin, writeJson, writeStdout } from "../io.js";
-import { assertHideSelector, captureScreenshot, parseViewport, parseWaitUntil, } from "../screenshot.js";
+import { assertHideSelector, captureScreenshot, clipHintText, DEFAULT_FULL_PAGE_MAX_HEIGHT, parseViewport, parseWaitUntil, } from "../screenshot.js";
 const SCREENSHOT_HELP = `uploads screenshot <target> [options]
 
 Capture a URL or a local .html file and host it — a hosted, PR-embeddable
@@ -59,6 +59,10 @@ Options:
   --viewport <WxH[@Sx]>     Size + device scale factor (default: 1280x800@2)
   --selector <css>          Capture one element instead of the viewport
   --full-page               Capture the full scrollable page
+  --max-height <px>         Cap on full-page capture height in CSS px (default: ${DEFAULT_FULL_PAGE_MAX_HEIGHT},
+                            or 0 for uncapped). A page over the cap is clipped, with a note printed
+                            to stderr and a --format json \`hint\`. Requires --full-page. Applied on
+                            both --via local and --via remote so behavior matches.
   --dark / --light          Emulate prefers-color-scheme (full media-query emulation on --via local
                             only; --via remote just sets the CSS color-scheme property, so a page's
                             own prefers-color-scheme queries won't flip)
@@ -182,6 +186,14 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     const viewport = parseViewport(flagString(parsed.flags, "--viewport"));
     const selector = flagString(parsed.flags, "--selector");
     const fullPage = flagBool(parsed.flags, "--full-page");
+    // Unlike every other --…-px flag, 0 is a valid (uncapped) value here, not
+    // an error — flagInt's allowZero option covers it.
+    const maxHeightFlag = flagInt(parsed.flags, "--max-height", "--max-height", {
+        allowZero: true,
+    });
+    if (maxHeightFlag !== undefined && !fullPage) {
+        throw new UsageError("--max-height requires --full-page");
+    }
     const colorScheme = colorSchemeFromFlags(parsed.flags);
     const waitUntil = parseWaitUntil(flagString(parsed.flags, "--wait"));
     const hide = flagValues(parsed.flags, "--hide");
@@ -387,6 +399,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
         viewport,
         selector,
         fullPage,
+        maxHeight: maxHeightFlag,
         colorScheme,
         waitUntil,
         hide,
@@ -403,6 +416,14 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     });
     if (logHuman)
         process.stderr.write(`>> captured via ${captured.backend} backend\n`);
+    // Full-page height cap note (issue #652): printed regardless of --format
+    // (only --quiet suppresses it) since it's directly actionable info about
+    // the image that was just captured, same as the upload-tail warnings below.
+    const clipHint = captured.capped?.clipped
+        ? clipHintText(captured.capped.maxHeightPx, "--max-height")
+        : undefined;
+    if (clipHint && !ctx.quiet)
+        process.stderr.write(`${clipHint}\n`);
     // Resolve selectors + render annotations before the frame/optimize/upload
     // pipeline runs — everything downstream (the --out write, the sidecar
     // hash, and the upload itself) should see the annotated bytes.
@@ -543,9 +564,11 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
             process.stderr.write(`${bindingWarning}\n`);
         process.stderr.write("\n");
     }
-    // One JSON `hint` slot (mirrors bare put): the binding warning is more
-    // actionable than the generic staging note, so it wins when both fire; a
-    // replaced-object note (issue #618) is the lowest priority of the three —
+    // One JSON `hint` slot (mirrors bare put): the clip note (issue #652) wins
+    // first — it's about the just-captured image itself, more immediately
+    // actionable than the other three, which are about upload/staging
+    // mechanics. Then the binding warning, more actionable than the generic
+    // staging note; a replaced-object note (issue #618) is lowest priority —
     // it only surfaces when nothing else already claimed the slot. Since state
     // folds into the derived key, replaced + state means a same-side re-capture,
     // which is the intended replace-in-place flow — word it as informational,
@@ -553,7 +576,7 @@ loadAnnotateModule = () => import("../annotate/index.js")) {
     const replacedHint = result.replaced && explicitMeta.state
         ? `re-capture replaced the previous state=${explicitMeta.state} object at ${result.key} — expected for repeat captures of the same URL + state`
         : undefined;
-    const jsonHint = bindingWarning ?? stagingNote ?? replacedHint;
+    const jsonHint = clipHint ?? bindingWarning ?? stagingNote ?? replacedHint;
     switch (format) {
         case "json":
             await writeJson({

package/dist/mcp/args.d.ts

@@ -3,7 +3,9 @@ export declare function usage(msg: string): never;
 export declare function optString(args: ToolArgs, name: string): string | undefined;
 /** A boolean flag argument; missing/null reads as `false`. */
 export declare function optBool(args: ToolArgs, name: string): boolean;
-export declare function optPosInt(args: ToolArgs, name: string): number | undefined;
+export declare function optPosInt(args: ToolArgs, name: string, options?: {
+    allowZero?: boolean;
+}): number | undefined;
 /** A JSON-object argument of string→string pairs (e.g. a `metadata` or `filters` param). */
 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). */

package/dist/mcp/args.js

@@ -25,12 +25,13 @@ export function optBool(args, name) {
         usage(`${name} must be a boolean`);
     return v;
 }
-export function optPosInt(args, name) {
+export function optPosInt(args, name, options) {
+    const allowZero = options?.allowZero ?? false;
     const v = args[name];
     if (v === undefined || v === null)
         return undefined;
-    if (typeof v !== "number" || !Number.isInteger(v) || v <= 0) {
-        usage(`${name} must be a positive integer`);
+    if (typeof v !== "number" || !Number.isInteger(v) || (allowZero ? v < 0 : v <= 0)) {
+        usage(`${name} must be a ${allowZero ? "non-negative" : "positive"} integer`);
     }
     return v;
 }

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

@@ -0,0 +1,37 @@
+/**
+ * JSON Schema for MCP tool `structuredContent`. The SDK validates successful
+ * results against the advertised `outputSchema`, so every property a handler
+ * actually returns must be listed. Roots are always `type: object` — a
+ * oneOf/anyOf root is treated as non-object by the 2025-era codec and wraps
+ * the result as `{ result: … }`.
+ */
+export type JsonSchema = Record<string, unknown>;
+/** Hosted + stdio `comment` / `put.comment` — all PostCommentResult variants. */
+export declare const commentResultSchema: JsonSchema;
+/** Single-file put (flat) or multi-file `{ uploads, failures }`, plus optional comment/promote extras. */
+export declare const putResultSchema: JsonSchema;
+export declare const listResultSchema: JsonSchema;
+export declare const deleteResultSchema: JsonSchema;
+export declare const metadataResultSchema: JsonSchema;
+export declare const findFilesResultSchema: JsonSchema;
+/** `meta keys` or `meta values <key>`. */
+export declare const metadataFacetsResultSchema: JsonSchema;
+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 promoteToolResultSchema: JsonSchema;
+export declare const galleryResultSchema: JsonSchema;
+export declare const galleryFindResultSchema: JsonSchema;
+/** Hosted catalog — every tool must have an entry. */
+export declare const hostedOutputSchemas: Record<string, JsonSchema>;
+/** Shared-shape stdio tools. Hosted-only tools (`promote`, `repo_link_status`) omitted. */
+export declare const stdioOutputSchemas: Record<string, JsonSchema>;
+export declare function withOutputSchemas<T extends {
+    name: string;
+}>(tools: T[], schemas: Record<string, JsonSchema>, opts: {
+    required: boolean;
+}): Array<T & {
+    outputSchema?: JsonSchema;
+}>;

package/dist/mcp/output-schemas.js

@@ -0,0 +1,338 @@
+function objectSchema(properties, required = []) {
+    return {
+        type: "object",
+        properties,
+        ...(required.length > 0 ? { required } : {}),
+        additionalProperties: false,
+    };
+}
+const stringMap = {
+    type: "object",
+    additionalProperties: { type: "string" },
+};
+const nullableString = { type: ["string", "null"] };
+const nullableNumber = { type: ["number", "null"] };
+/** Hosted + stdio `comment` / `put.comment` — all PostCommentResult variants. */
+export const commentResultSchema = objectSchema({
+    posted: { type: "boolean" },
+    reason: {
+        type: "string",
+        enum: [
+            "app_unconfigured",
+            "not_installed",
+            "not_authorized",
+            "actor_not_authorized",
+            "unavailable",
+            "forbidden",
+        ],
+    },
+    message: { type: "string" },
+    fixUrl: { type: "string" },
+    required: { type: "array", items: { type: "string" } },
+    action: { type: "string", enum: ["skipped", "created", "updated"] },
+    count: { type: "number" },
+    commentUrl: { type: "string" },
+}, ["posted"]);
+const promoteResultSchema = objectSchema({
+    promoted: { type: "array", items: { type: "string" } },
+    skipped: {
+        type: "array",
+        items: objectSchema({ key: { type: "string" }, reason: { type: "string" } }, [
+            "key",
+            "reason",
+        ]),
+    },
+}, ["promoted", "skipped"]);
+const putObjectFields = {
+    key: { type: "string" },
+    url: nullableString,
+    embedUrl: nullableString,
+    size: { type: "number" },
+    contentType: { type: "string" },
+    replaced: { type: "boolean" },
+    markdown: { type: "string" },
+    provenance: stringMap,
+    metadata: stringMap,
+    visibility: { type: "string" },
+};
+/** Hosted `PostCommentResult` or stdio `AttachmentsCommentResult` (`via`/`action`). */
+const putCommentSchema = objectSchema({
+    posted: { type: "boolean" },
+    reason: {
+        type: "string",
+        enum: [
+            "app_unconfigured",
+            "not_installed",
+            "not_authorized",
+            "actor_not_authorized",
+            "unavailable",
+            "forbidden",
+        ],
+    },
+    message: { type: "string" },
+    fixUrl: { type: "string" },
+    required: { type: "array", items: { type: "string" } },
+    action: { type: "string", enum: ["skipped", "created", "updated"] },
+    count: { type: "number" },
+    commentUrl: { type: "string" },
+    via: { type: "string", enum: ["bot", "gh"] },
+});
+const putExtras = {
+    comment: putCommentSchema,
+    commentError: { type: "string" },
+    promotion: promoteResultSchema,
+    promoteError: { type: "string" },
+};
+const putFailure = objectSchema({
+    file: { type: "string" },
+    error: objectSchema({
+        message: { type: "string" },
+        code: { type: "string" },
+        status: { type: "number" },
+    }, ["message"]),
+}, ["file", "error"]);
+/** Single-file put (flat) or multi-file `{ uploads, failures }`, plus optional comment/promote extras. */
+export const putResultSchema = objectSchema({
+    workspace: { type: "string" },
+    ...putObjectFields,
+    file: { type: "string" },
+    uploads: {
+        type: "array",
+        items: {
+            type: "object",
+            properties: { file: { type: "string" }, ...putObjectFields },
+            additionalProperties: true,
+        },
+    },
+    failures: { type: "array", items: putFailure },
+    ...putExtras,
+    // stdio put adds client-side optimize/frame provenance and dry-run flags.
+    optimize: { type: "object", additionalProperties: true },
+    frame: { type: "object", additionalProperties: true },
+    dryRun: { type: "boolean" },
+    hint: { type: "string" },
+});
+export const listResultSchema = objectSchema({
+    items: {
+        type: "array",
+        items: objectSchema({
+            key: { type: "string" },
+            url: nullableString,
+            embedUrl: nullableString,
+            size: { type: "number" },
+            contentType: { type: "string" },
+            uploaded: { type: "string" },
+            visibility: { type: "string" },
+            pageUrl: { type: "string" },
+        }),
+    },
+    cursor: nullableString,
+    prefixes: { type: "array", items: { type: "string" } },
+});
+export const deleteResultSchema = objectSchema({
+    key: { type: "string" },
+    deleted: { type: "boolean" },
+    dryRun: { type: "boolean" },
+}, ["key"]);
+export const metadataResultSchema = objectSchema({ metadata: stringMap }, ["metadata"]);
+export const findFilesResultSchema = objectSchema({
+    items: {
+        type: "array",
+        items: objectSchema({
+            key: { type: "string" },
+            url: nullableString,
+            metadata: stringMap,
+        }, ["key"]),
+    },
+    cursor: nullableString,
+    truncated: { type: "boolean" },
+}, ["items"]);
+/** `meta keys` or `meta values <key>`. */
+export const metadataFacetsResultSchema = objectSchema({
+    keys: {
+        type: "array",
+        items: objectSchema({
+            key: { type: "string" },
+            count: { type: "number" },
+            distinctValues: { type: "number" },
+        }, ["key", "count", "distinctValues"]),
+    },
+    truncated: { type: "boolean" },
+    key: { type: "string" },
+    values: {
+        type: "array",
+        items: objectSchema({ value: { type: "string" }, count: { type: "number" } }, [
+            "value",
+            "count",
+        ]),
+    },
+});
+export const repoLinkStatusResultSchema = objectSchema({ binding: { type: "string", enum: ["self", "other", "none"] } }, ["binding"]);
+export const usageResultSchema = objectSchema({
+    workspace: { type: "string" },
+    bytes: { type: "number" },
+    objects: { type: "number" },
+    uploadsInPeriod: { type: "number" },
+    periodStart: { type: "string" },
+    updatedAt: { type: "string" },
+    maxStorageBytes: { type: "number" },
+    storageRemainingBytes: { type: "number" },
+    maxUploadsPerPeriod: { type: "number" },
+    uploadsRemaining: { type: "number" },
+});
+export const reconcileResultSchema = objectSchema({
+    workspace: { type: "string" },
+    bytes: { type: "number" },
+    objects: { type: "number" },
+    previous: objectSchema({ bytes: { type: "number" }, objects: { type: "number" } }, [
+        "bytes",
+        "objects",
+    ]),
+    changed: { type: "boolean" },
+    usage: usageResultSchema,
+    unprefixedBucket: { type: "boolean" },
+});
+export const purgeExpiredResultSchema = objectSchema({
+    skipped: { type: "boolean" },
+    reason: { type: "string" },
+    workspace: { type: "string" },
+    retentionDays: { type: "number" },
+    cutoff: { type: "string" },
+    deleted: { type: "number" },
+    freedBytes: { type: "number" },
+    keys: { type: "array", items: { type: "string" } },
+    keysTruncated: { type: "boolean" },
+    reconcile: reconcileResultSchema,
+});
+export const healthResultSchema = objectSchema({
+    ok: { type: "boolean" },
+    apiUrl: { type: "string" },
+});
+export const promoteToolResultSchema = objectSchema({
+    promotion: promoteResultSchema,
+    comment: commentResultSchema,
+    commentError: { type: "string" },
+}, ["promotion"]);
+const galleryItemSchema = objectSchema({
+    id: { type: "string" },
+    objectKey: { type: "string" },
+    filename: { type: "string" },
+    position: { type: "number" },
+    caption: nullableString,
+    altText: nullableString,
+    createdAt: { type: "string" },
+    status: { type: "string", enum: ["available", "missing", "withheld"] },
+    url: nullableString,
+    embedUrl: nullableString,
+    pageUrl: { type: "string" },
+    contentType: nullableString,
+    size: nullableNumber,
+    uploaded: nullableString,
+    modified: nullableString,
+    posterUrl: { type: "string" },
+    videoDimensions: {
+        type: "object",
+        additionalProperties: true,
+    },
+});
+const galleryReferenceSchema = objectSchema({
+    id: { type: "string" },
+    provider: { type: "string" },
+    resourceType: { type: "string" },
+    coordinate: { type: "string" },
+    canonicalUrl: nullableString,
+    createdAt: { type: "string" },
+    title: { type: "string" },
+    kind: { type: "string", enum: ["pull", "issue"] },
+});
+export const galleryResultSchema = objectSchema({
+    id: { type: "string" },
+    url: { type: "string" },
+    workspace: { type: "string" },
+    title: { type: "string" },
+    description: nullableString,
+    visibility: { type: "string" },
+    coverItemId: nullableString,
+    version: { type: "number" },
+    createdAt: { type: "string" },
+    updatedAt: { type: "string" },
+    items: { type: "array", items: galleryItemSchema },
+    itemCount: { type: "number" },
+    references: { type: "array", items: galleryReferenceSchema },
+});
+export const galleryFindResultSchema = objectSchema({
+    galleries: { type: "array", items: galleryResultSchema },
+    nextCursor: nullableString,
+});
+/** Hosted catalog — every tool must have an entry. */
+export const hostedOutputSchemas = {
+    gallery_create: galleryResultSchema,
+    gallery_get: galleryResultSchema,
+    gallery_add: galleryItemSchema,
+    gallery_link: galleryReferenceSchema,
+    gallery_find_by_reference: galleryFindResultSchema,
+    put: putResultSchema,
+    list: listResultSchema,
+    delete: deleteResultSchema,
+    comment: commentResultSchema,
+    promote: promoteToolResultSchema,
+    get_metadata: metadataResultSchema,
+    set_metadata: metadataResultSchema,
+    find_files: findFilesResultSchema,
+    list_metadata_keys: metadataFacetsResultSchema,
+    repo_link_status: repoLinkStatusResultSchema,
+    usage: usageResultSchema,
+    reconcile: reconcileResultSchema,
+    purge_expired: purgeExpiredResultSchema,
+    health: healthResultSchema,
+};
+/** Shared-shape stdio tools. Hosted-only tools (`promote`, `repo_link_status`) omitted. */
+export const stdioOutputSchemas = {
+    gallery_create: galleryResultSchema,
+    gallery_get: galleryResultSchema,
+    gallery_add: galleryItemSchema,
+    gallery_link: galleryReferenceSchema,
+    gallery_find_by_reference: galleryFindResultSchema,
+    put: putResultSchema,
+    list: listResultSchema,
+    delete: deleteResultSchema,
+    comment: objectSchema({
+        posted: { type: "boolean" },
+        reason: { type: "string" },
+        message: { type: "string" },
+        fixUrl: { type: "string" },
+        required: { type: "array", items: { type: "string" } },
+        action: { type: "string", enum: ["skipped", "created", "updated"] },
+        count: { type: "number" },
+        commentUrl: { type: "string" },
+        repo: { type: "string" },
+        kind: { type: "string" },
+        num: { type: "number" },
+        via: { type: "string", enum: ["bot", "gh"] },
+    }),
+    get_metadata: metadataResultSchema,
+    set_metadata: metadataResultSchema,
+    find_files: findFilesResultSchema,
+    list_metadata_keys: metadataFacetsResultSchema,
+    usage: usageResultSchema,
+    reconcile: reconcileResultSchema,
+    purge_expired: purgeExpiredResultSchema,
+    health: healthResultSchema,
+    report: objectSchema({
+        ok: { type: "boolean" },
+        id: { type: "string" },
+        hasAttachment: { type: "boolean" },
+    }, ["ok"]),
+};
+export function withOutputSchemas(tools, schemas, opts) {
+    return tools.map((tool) => {
+        const outputSchema = schemas[tool.name];
+        if (!outputSchema) {
+            if (opts.required) {
+                throw new Error(`missing output schema for MCP tool ${tool.name}`);
+            }
+            return tool;
+        }
+        return { ...tool, outputSchema };
+    });
+}

package/dist/mcp/server.d.ts

@@ -22,11 +22,63 @@ export { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, metadataArgWithCa
 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";
+/** 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. */
+export declare const mcpRead: McpToolAnnotations;
+/** Creates or updates a public object, gallery, or comment without deleting. */
+export declare const mcpWritePublic: McpToolAnnotations;
+/** Deletes or overwrites a public object or a public GitHub comment. */
+export declare const mcpDestroyPublic: McpToolAnnotations;
+/** Mutates first-party / internal state only (ledger, reports). */
+export declare const mcpWriteInternal: McpToolAnnotations;
+/**
+ * Per-tool auth policy for ChatGPT / Codex plugin review. Advertised on
+ * tools/list as `_meta.securitySchemes` (the SDK has no first-class field).
+ */
+export type McpSecurityScheme = {
+    type: "noauth";
+} | {
+    type: "oauth2";
+    scopes: string[];
+};
+export declare const mcpOAuthRead: McpSecurityScheme[];
+export declare const mcpOAuthWrite: McpSecurityScheme[];
+export declare const mcpOAuthDelete: McpSecurityScheme[];
+/** Authenticated, no particular file scope (hosted `health`). */
+export declare const mcpOAuthAny: McpSecurityScheme[];
+/** Callable without a token (stdio `health`). */
+export declare const mcpNoAuth: McpSecurityScheme[];
+/**
+ * Thrown when a presented token is missing a required scope. wrapHandler
+ * turns this into a tool error that carries `_meta["mcp/www_authenticate"]`
+ * so ChatGPT can prompt a re-consent.
+ */
+export declare class McpAuthError extends Error {
+    readonly challenge: string;
+    constructor(message: string, challenge: string);
+}
+/** Build an insufficient_scope challenge pointing at this resource's metadata. */
+export declare function insufficientScopeError(resourceMetadataUrl: string, scope: string): McpAuthError;
 export interface McpTool {
     name: string;
     description: string;
+    /** Short label for tools/list. Falls back to `name` when omitted. */
+    title?: string;
+    annotations: McpToolAnnotations;
+    securitySchemes: McpSecurityScheme[];
     /** Hand-written JSON Schema for the tool's arguments. */
     inputSchema: Record<string, unknown>;
+    /**
+     * Hand-written JSON Schema for successful `structuredContent`. Required
+     * whenever the handler returns structured data (OpenAI Scan Tools).
+     */
+    outputSchema?: Record<string, unknown>;
     handler: (args: Record<string, unknown>) => Promise<unknown>;
 }
 export declare function createMcpServer(opts: {

package/dist/mcp/server.js

@@ -25,6 +25,58 @@ export { appProp, canonicalMetaFromArgs, METADATA_DESCRIPTION, metadataArgWithCa
 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 const mcpRead = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: false,
+};
+/** Creates or updates a public object, gallery, or comment without deleting. */
+export const mcpWritePublic = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+};
+/** Deletes or overwrites a public object or a public GitHub comment. */
+export const mcpDestroyPublic = {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+};
+/** Mutates first-party / internal state only (ledger, reports). */
+export const mcpWriteInternal = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: false,
+};
+function oauth(scopes) {
+    return [{ type: "oauth2", 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`). */
+export const mcpOAuthAny = oauth([]);
+/** Callable without a token (stdio `health`). */
+export const mcpNoAuth = [{ type: "noauth" }];
+/**
+ * Thrown when a presented token is missing a required scope. wrapHandler
+ * turns this into a tool error that carries `_meta["mcp/www_authenticate"]`
+ * so ChatGPT can prompt a re-consent.
+ */
+export class McpAuthError extends Error {
+    challenge;
+    constructor(message, challenge) {
+        super(message);
+        this.name = "McpAuthError";
+        this.challenge = challenge;
+    }
+}
+/** Build an insufficient_scope challenge pointing at this resource's metadata. */
+export function insufficientScopeError(resourceMetadataUrl, scope) {
+    return new McpAuthError(`forbidden: requires ${scope} scope`, `Bearer resource_metadata="${resourceMetadataUrl}", error="insufficient_scope", error_description="This tool requires the ${scope} scope"`);
+}
 /**
  * The tool catalog is fixed for the lifetime of a deploy, so a generous
  * freshness hint is honest. `private` rather than `public` because the list is
@@ -75,6 +127,13 @@ function wrapHandler(tool, apiUrl) {
                     isError: true,
                 };
             }
+            if (err instanceof McpAuthError) {
+                return {
+                    content: [{ type: "text", text: err.message }],
+                    isError: true,
+                    _meta: { "mcp/www_authenticate": [err.challenge] },
+                };
+            }
             return { content: [{ type: "text", text: toolErrorText(err) }], isError: true };
         }
     };
@@ -86,8 +145,14 @@ export function createMcpServer(opts) {
     });
     for (const tool of tools) {
         server.registerTool(tool.name, {
+            ...(tool.title ? { title: tool.title } : {}),
             description: tool.description,
             inputSchema: fromJsonSchema(tool.inputSchema, validator),
+            ...(tool.outputSchema
+                ? { outputSchema: fromJsonSchema(tool.outputSchema, validator) }
+                : {}),
+            annotations: tool.annotations,
+            _meta: { securitySchemes: tool.securitySchemes },
         }, wrapHandler(tool, apiUrl));
     }
     return server;

package/dist/mcp/tools.js

@@ -10,7 +10,7 @@ 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 { batchFailureMessage, ToolBatchError } from "./server.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";
 function mcpOptimizeOptions(args, defaults) {
@@ -130,9 +130,12 @@ export function createUploadsMcpTools(opts) {
         }
         return { comment, commentError };
     };
-    return [
+    const tools = [
         {
             name: "gallery_create",
+            title: "Create gallery",
+            annotations: mcpWritePublic,
+            securitySchemes: mcpOAuthWrite,
             description: "Create a public ordered media gallery in the workspace. The returned canonical URL is safe to give users, but anyone who knows it can view the gallery and its media.",
             inputSchema: {
                 type: "object",
@@ -154,6 +157,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "gallery_get",
+            title: "Get gallery",
+            annotations: mcpRead,
+            securitySchemes: mcpOAuthRead,
             description: "Get a workspace-owned gallery, including ordered media and its canonical public URL. Gallery media is public to anyone with the URL.",
             inputSchema: {
                 type: "object",
@@ -171,6 +177,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "gallery_add",
+            title: "Add gallery item",
+            annotations: mcpWritePublic,
+            securitySchemes: mcpOAuthWrite,
             description: "Add one existing, publicly served workspace object to a gallery. Reads the latest gallery version before writing, so the optimistic API version is handled safely. Does not upload or delete the object.",
             inputSchema: {
                 type: "object",
@@ -200,6 +209,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "gallery_link",
+            title: "Link gallery",
+            annotations: mcpWritePublic,
+            securitySchemes: mcpOAuthWrite,
             description: "Link a gallery to an external reference. References use provider-neutral fields; github currently accepts owner/repo#number or a strict GitHub issue/PR URL. No GitHub credentials or API calls are used.",
             inputSchema: {
                 type: "object",
@@ -227,6 +239,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "gallery_find_by_reference",
+            title: "Find galleries",
+            annotations: mcpRead,
+            securitySchemes: mcpOAuthRead,
             description: "Find workspace galleries linked to an external reference. Returns gallery summaries and canonical public URLs without contacting the provider.",
             inputSchema: {
                 type: "object",
@@ -254,6 +269,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "put",
+            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.",
             inputSchema: {
                 type: "object",
@@ -558,6 +576,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "screenshot",
+            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.",
             inputSchema: {
                 type: "object",
@@ -584,6 +605,12 @@ export function createUploadsMcpTools(opts) {
                     },
                     selector: { type: "string", description: "Capture one element instead of the viewport." },
                     fullPage: { type: "boolean", description: "Capture the full scrollable page." },
+                    maxHeight: {
+                        type: "number",
+                        description: "Cap on full-page capture height in CSS px (default: 5000, 0 = uncapped). A page over " +
+                            "the cap is clipped, with a `hint` in the result. Requires fullPage. Applied on both " +
+                            "via: local and via: remote so behavior matches.",
+                    },
                     colorScheme: {
                         type: "string",
                         description: "Emulate prefers-color-scheme: dark | light. Full media-query emulation requires via: \"local\" — the remote backend only sets the CSS color-scheme property and won't flip a page's own prefers-color-scheme queries.",
@@ -678,6 +705,12 @@ export function createUploadsMcpTools(opts) {
                 if (colorSchemeArg && colorSchemeArg !== "dark" && colorSchemeArg !== "light") {
                     usage("colorScheme must be dark or light");
                 }
+                const fullPageArg = optBool(args, "fullPage");
+                // Unlike other px args, 0 is valid here (uncapped) — optPosInt's
+                // allowZero option covers it.
+                const maxHeightArg = optPosInt(args, "maxHeight", { allowZero: true });
+                if (maxHeightArg !== undefined && !fullPageArg)
+                    usage("maxHeight requires fullPage");
                 const target = ghTargetFromArgs(args, run);
                 const wantComment = optBool(args, "comment");
                 const dryRun = optBool(args, "dryRun");
@@ -778,7 +811,8 @@ export function createUploadsMcpTools(opts) {
                         cdp: optString(args, "cdp"),
                         viewport,
                         selector: optString(args, "selector"),
-                        fullPage: optBool(args, "fullPage"),
+                        fullPage: fullPageArg,
+                        maxHeight: maxHeightArg,
                         colorScheme: colorSchemeArg,
                         waitUntil: screenshotModule.parseWaitUntil(optString(args, "wait")),
                         hide: optStringArray(args, "hide"),
@@ -863,6 +897,11 @@ export function createUploadsMcpTools(opts) {
                     frame: prepared.frame,
                     gallery,
                     ...(dryRun ? { dryRun: true } : {}),
+                    // Full-page height cap note (issue #652), mirrors the CLI's stderr
+                    // note + `hint` field.
+                    ...(captured.capped?.clipped
+                        ? { hint: screenshotModule.clipHintText(captured.capped.maxHeightPx, "maxHeight") }
+                        : {}),
                 };
                 if (wantComment && target) {
                     const { comment, commentError } = await syncComment(client, target, config.workspace);
@@ -873,6 +912,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "attach",
+            title: "Attach to GitHub",
+            annotations: mcpDestroyPublic,
+            securitySchemes: mcpOAuthWrite,
             description: "Upload one or more files as stable PR/issue attachments (in parallel) and maintain a managed GitHub comment. Returns `uploads` and `failures` (one bad file does not abort the batch). Each success has `url`, `embedUrl`, and `markdown` (prefer embedUrl for GitHub). With no pr/issue, targets the current branch PR. Attachments are public and keys are predictable; upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
@@ -971,6 +1013,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "list",
+            title: "List files",
+            annotations: mcpRead,
+            securitySchemes: mcpOAuthRead,
             description: "List uploaded objects in the workspace, filtered by key prefix or by a PR/issue's attachments. Paginate with cursor, or set all to fetch every page.",
             inputSchema: {
                 type: "object",
@@ -1028,6 +1073,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "staged",
+            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.",
             inputSchema: {
                 type: "object",
@@ -1053,6 +1101,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "delete",
+            title: "Delete file",
+            annotations: mcpDestroyPublic,
+            securitySchemes: mcpOAuthDelete,
             description: "Delete an uploaded object by key. Set dryRun to preview without deleting.",
             inputSchema: {
                 type: "object",
@@ -1079,6 +1130,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "get_metadata",
+            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`.",
             inputSchema: {
                 type: "object",
@@ -1098,6 +1152,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "set_metadata",
+            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`.",
@@ -1133,6 +1190,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "find_files",
+            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, and optional `truncated`. Same as `uploads find k=v...` / `uploads find --name <term>`.",
             inputSchema: {
                 type: "object",
@@ -1173,6 +1233,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "list_metadata_keys",
+            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>`).",
             inputSchema: {
                 type: "object",
@@ -1193,6 +1256,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "usage",
+            title: "Show usage",
+            annotations: mcpRead,
+            securitySchemes: mcpOAuthRead,
             description: "Workspace storage and monthly upload counters (and remaining headroom when budgets are configured). Same as `uploads usage`.",
             inputSchema: {
                 type: "object",
@@ -1206,6 +1272,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "reconcile",
+            title: "Reconcile usage",
+            annotations: mcpWriteInternal,
+            securitySchemes: mcpOAuthWrite,
             description: "Rebuild usage ledger bytes/objects from storage (source of truth). Preserves the monthly upload counter. Requires files:write. Same as `uploads reconcile`.",
             inputSchema: {
                 type: "object",
@@ -1219,6 +1288,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "purge_expired",
+            title: "Purge expired files",
+            annotations: mcpDestroyPublic,
+            securitySchemes: mcpOAuthDelete,
             description: "Delete objects older than the workspace retentionDays setting, then reconcile. Skips if retention is unset. Requires files:delete. Same as `uploads purge-expired`.",
             inputSchema: {
                 type: "object",
@@ -1232,6 +1304,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "comment",
+            title: "Sync attachments comment",
+            annotations: mcpDestroyPublic,
+            securitySchemes: mcpOAuthWrite,
             description: "Create or update the managed attachments comment on a GitHub PR or issue, listing everything uploaded for it. Posts as uploads-sh[bot] when the GitHub App is installed on the repo; otherwise via local gh auth. Edits its own prior comment in place and never touches other comments.",
             inputSchema: {
                 type: "object",
@@ -1255,6 +1330,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "health",
+            title: "Check health",
+            annotations: mcpRead,
+            securitySchemes: mcpNoAuth,
             description: "Check uploads.sh API liveness. No auth or arguments required.",
             inputSchema: { type: "object", properties: {}, additionalProperties: false },
             async handler(args) {
@@ -1265,6 +1343,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "doctor",
+            title: "Diagnose setup",
+            annotations: mcpRead,
+            securitySchemes: mcpOAuthAny,
             description: "Diagnose the configuration: API health, token auth, and workspace/token alignment. Returns the same report as `uploads doctor --json`, including hints.",
             inputSchema: {
                 type: "object",
@@ -1278,6 +1359,9 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "report",
+            title: "Send diagnostic report",
+            annotations: mcpWriteInternal,
+            securitySchemes: mcpOAuthWrite,
             description: "Send an explicit diagnostic report to the uploads team (message + optional text log). " +
                 "Only call this when the user asked to submit feedback, a bug report, or error logs — " +
                 "never automatically. Do not include tokens, secrets, or private file contents. " +
@@ -1359,4 +1443,5 @@ export function createUploadsMcpTools(opts) {
             },
         },
     ];
+    return withOutputSchemas(tools, stdioOutputSchemas, { required: false });
 }

package/dist/screenshot-local.d.ts

@@ -48,6 +48,13 @@ export interface LocalCaptureOptions {
     };
     selector?: string;
     fullPage?: boolean;
+    /**
+     * Cap (CSS px) on full-page capture height (issue #652). Only consulted
+     * when `fullPage` is true; 0 or undefined means uncapped. When the page's
+     * measured scroll height exceeds this, the capture is clipped to exactly
+     * this height instead of the full scroll height.
+     */
+    maxHeightPx?: number;
     colorScheme?: "dark" | "light";
     /** "load" | "domcontentloaded" | "networkidle", or a millisecond settle delay. */
     waitUntil: "load" | "domcontentloaded" | "networkidle" | number;
@@ -86,6 +93,16 @@ export interface MeasuredBox {
 interface EvaluatablePage {
     evaluate<T>(fn: (selectors: string[]) => T, arg: string[]): Promise<T>;
 }
+/**
+ * Measures the page's full scrollable height in CSS px — the same quantity
+ * a `fullPage: true` screenshot would otherwise capture in its entirety.
+ * `document.documentElement.scrollHeight` is the standard measure; `body`'s
+ * is included too since some pages (quirks-mode, non-standard layouts) only
+ * grow one or the other.
+ */
+export declare function measureFullPageHeight(page: {
+    evaluate<T>(fn: () => T): Promise<T>;
+}): Promise<number>;
 /**
  * Measures each selector's getBoundingClientRect on the page in a single
  * `page.evaluate` round-trip, scaling CSS pixels to device (raster) pixels so
@@ -99,5 +116,6 @@ export declare function measureSelectorBoxes(page: EvaluatablePage, selectors: r
 export declare function captureLocal(opts: LocalCaptureOptions): Promise<{
     png: Uint8Array;
     measures?: Record<string, MeasuredBox>;
+    clipped?: boolean;
 }>;
 export {};

package/dist/screenshot-local.js

@@ -203,6 +203,16 @@ export function detectLocalBrowser(roots = {}) {
     const winner = [...candidates].toSorted((a, b) => rank(a) - rank(b))[0];
     return { envOverride, candidates, winner };
 }
+/**
+ * Measures the page's full scrollable height in CSS px — the same quantity
+ * a `fullPage: true` screenshot would otherwise capture in its entirety.
+ * `document.documentElement.scrollHeight` is the standard measure; `body`'s
+ * is included too since some pages (quirks-mode, non-standard layouts) only
+ * grow one or the other.
+ */
+export async function measureFullPageHeight(page) {
+    return page.evaluate(() => Math.max(document.documentElement.scrollHeight, document.body?.scrollHeight ?? 0));
+}
 /**
  * Measures each selector's getBoundingClientRect on the page in a single
  * `page.evaluate` round-trip, scaling CSS pixels to device (raster) pixels so
@@ -349,11 +359,33 @@ export async function captureLocal(opts) {
         const measures = opts.measureSelectors && opts.measureSelectors.length > 0
             ? await measureSelectorBoxes(page, opts.measureSelectors, opts.viewport.deviceScaleFactor)
             : undefined;
-        const png = opts.selector
-            ? await page.locator(opts.selector).screenshot({ timeout: opts.timeoutMs ?? 30_000 })
-            : await page.screenshot({ fullPage: opts.fullPage === true });
+        // Full-page height cap (issue #652): measure the actual scroll height
+        // first so a page under the cap keeps its normal exact-content-height
+        // fullPage capture — only a page that genuinely exceeds the cap gets
+        // clipped to it. `clip` (CSS px, captures beyond the current viewport)
+        // is the mechanism; it can't be combined with `fullPage: true`.
+        let clipped = false;
+        let png;
+        if (opts.selector) {
+            png = await page.locator(opts.selector).screenshot({ timeout: opts.timeoutMs ?? 30_000 });
+        }
+        else if (opts.fullPage && opts.maxHeightPx && opts.maxHeightPx > 0) {
+            const fullHeight = await measureFullPageHeight(page);
+            if (fullHeight > opts.maxHeightPx) {
+                clipped = true;
+                png = await page.screenshot({
+                    clip: { x: 0, y: 0, width: opts.viewport.width, height: opts.maxHeightPx },
+                });
+            }
+            else {
+                png = await page.screenshot({ fullPage: true });
+            }
+        }
+        else {
+            png = await page.screenshot({ fullPage: opts.fullPage === true });
+        }
         // Buffer extends Uint8Array — return it as-is rather than copying.
-        return { png, measures };
+        return { png, measures, clipped };
     }
     finally {
         await browser.close();

package/dist/screenshot-remote.d.ts

@@ -10,6 +10,14 @@ export interface RemoteRenderRequest {
     };
     selector?: string;
     fullPage?: boolean;
+    /**
+     * Cap (CSS px) on full-page capture height (issue #652). Only sent when
+     * `fullPage` is true and the cap is active (nonzero); the server applies a
+     * best-effort clamp (see apps/api's render.ts) and reports whether it
+     * actually kicked in via the `X-Uploads-Full-Page-Clipped` response header,
+     * surfaced back on the result as `clipped`.
+     */
+    maxHeight?: number;
     colorScheme?: "dark" | "light";
     waitUntil?: "load" | "domcontentloaded" | "networkidle" | number;
     /** CSS selectors hidden (display:none) server-side before capture. */
@@ -27,5 +35,14 @@ export interface RemoteRenderOptions {
     fetchImpl?: typeof fetch;
     timeoutMs?: number;
 }
-/** POST the render request; resolves with raw PNG bytes on 200. */
-export declare function captureRemote(body: RemoteRenderRequest, opts: RemoteRenderOptions): Promise<Uint8Array>;
+export interface RemoteRenderResult {
+    png: Uint8Array;
+    /**
+     * True when the server's best-effort full-page height clamp actually
+     * kicked in (read from the `X-Uploads-Full-Page-Clipped` response header).
+     * Always false when `maxHeight` wasn't sent.
+     */
+    clipped: boolean;
+}
+/** POST the render request; resolves with raw PNG bytes (+ clip status) on 200. */
+export declare function captureRemote(body: RemoteRenderRequest, opts: RemoteRenderOptions): Promise<RemoteRenderResult>;

package/dist/screenshot-remote.js

@@ -32,7 +32,7 @@ function mapRenderError(status, message, code) {
         return new UploadsError(message, "RATE_LIMITED", status);
     return new UploadsError(message, "API_ERROR", status);
 }
-/** POST the render request; resolves with raw PNG bytes on 200. */
+/** POST the render request; resolves with raw PNG bytes (+ clip status) on 200. */
 export async function captureRemote(body, opts) {
     if (body.html !== undefined) {
         const htmlBytes = new TextEncoder().encode(body.html).byteLength;
@@ -65,7 +65,7 @@ export async function captureRemote(body, opts) {
         if (bytes.byteLength === 0) {
             throw new UploadsError("render endpoint returned an empty response", "RENDER_FAILED");
         }
-        return bytes;
+        return { png: bytes, clipped: res.headers.get("x-uploads-full-page-clipped") === "true" };
     }
     catch (err) {
         if (err instanceof UploadsError)

package/dist/screenshot.d.ts

@@ -25,6 +25,16 @@ export interface ScreenshotViewport {
     deviceScaleFactor: number;
 }
 export declare const DEFAULT_SCREENSHOT_VIEWPORT: ScreenshotViewport;
+/**
+ * Default cap (CSS px) on `--full-page` capture height (issue #652). Picked
+ * from the 4000-6000px range the issue proposed: generous enough to cover a
+ * long single-viewport marketing/docs page without clipping, but well short
+ * of the multi-thousand-entry-list case that motivated this (a 53-entry
+ * changelog page, PR #651) — those still clip, with a note pointing at
+ * `--max-height` to raise or remove the cap. `0` (via `--max-height 0`) means
+ * uncapped, for the rare case the full strip is genuinely wanted.
+ */
+export declare const DEFAULT_FULL_PAGE_MAX_HEIGHT = 5000;
 /** Parses `WIDTHxHEIGHT[@SCALEx]`, e.g. "1280x800", "1280x800@2x", "1280x800@2". */
 export declare function parseViewport(raw: string | undefined): ScreenshotViewport;
 /** Parses `--wait`: "load" | "domcontentloaded" | "networkidle" | a millisecond count. */
@@ -63,6 +73,13 @@ export interface CaptureScreenshotOptions {
     viewport?: ScreenshotViewport;
     selector?: string;
     fullPage?: boolean;
+    /**
+     * Cap (CSS px) on `--full-page` capture height. Only meaningful with
+     * `fullPage: true`; ignored otherwise. `undefined` applies
+     * `DEFAULT_FULL_PAGE_MAX_HEIGHT`; `0` means uncapped. Wired through both
+     * capture backends so behavior matches regardless of `via` (issue #652).
+     */
+    maxHeight?: number;
     colorScheme?: "dark" | "light";
     waitUntil?: WaitUntil;
     /**
@@ -104,6 +121,8 @@ export interface CaptureScreenshotOptions {
         viewport: ScreenshotViewport;
         selector?: string;
         fullPage?: boolean;
+        /** CSS px cap on full-page height; 0 or undefined = uncapped. */
+        maxHeightPx?: number;
         colorScheme?: "dark" | "light";
         waitUntil: WaitUntil;
         hide?: string[];
@@ -117,6 +136,8 @@ export interface CaptureScreenshotOptions {
     }) => Promise<{
         png: Uint8Array;
         measures?: Record<string, MeasuredBox>;
+        /** Present when `fullPage` + a positive `maxHeightPx` were given. */
+        clipped?: boolean;
     }>;
     /** Injectable for tests: replaces the remote capture implementation. */
     captureRemoteImpl?: typeof captureRemote;
@@ -127,7 +148,23 @@ export interface CaptureScreenshotResult {
     backend: "local" | "remote";
     /** Present when `measureSelectors` was given and the local backend ran. */
     measures?: Record<string, MeasuredBox>;
+    /**
+     * Present when `fullPage` was requested with a nonzero max-height cap
+     * (explicit or default) — regardless of backend. `clipped` tells the
+     * caller whether the cap actually kicked in, so it can print the
+     * "exceeds Npx; clipped" note and JSON `hint` (issue #652).
+     */
+    capped?: {
+        maxHeightPx: number;
+        clipped: boolean;
+    };
 }
+/**
+ * The "clipped by the max-height cap" note shared by the CLI's stderr
+ * message and the MCP tool's JSON `hint` field (issue #652) — identical
+ * except for how each surface names the flag to raise the cap.
+ */
+export declare function clipHintText(maxHeightPx: number, flagName: string): string;
 /**
  * Folds a `--state` value into an auto-derived filename's stem, e.g.
  * `localhost-docs-mcp.png` + "before" → `localhost-docs-mcp-before.png`. This

package/dist/screenshot.js

@@ -48,6 +48,16 @@ export const DEFAULT_SCREENSHOT_VIEWPORT = {
     height: 800,
     deviceScaleFactor: 2,
 };
+/**
+ * Default cap (CSS px) on `--full-page` capture height (issue #652). Picked
+ * from the 4000-6000px range the issue proposed: generous enough to cover a
+ * long single-viewport marketing/docs page without clipping, but well short
+ * of the multi-thousand-entry-list case that motivated this (a 53-entry
+ * changelog page, PR #651) — those still clip, with a note pointing at
+ * `--max-height` to raise or remove the cap. `0` (via `--max-height 0`) means
+ * uncapped, for the rare case the full strip is genuinely wanted.
+ */
+export const DEFAULT_FULL_PAGE_MAX_HEIGHT = 5000;
 /** Parses `WIDTHxHEIGHT[@SCALEx]`, e.g. "1280x800", "1280x800@2x", "1280x800@2". */
 export function parseViewport(raw) {
     if (!raw)
@@ -146,6 +156,14 @@ export function classifyTarget(target) {
     }
     return { kind: "html-file", path: abs, html: readFileSync(abs, "utf8") };
 }
+/**
+ * The "clipped by the max-height cap" note shared by the CLI's stderr
+ * message and the MCP tool's JSON `hint` field (issue #652) — identical
+ * except for how each surface names the flag to raise the cap.
+ */
+export function clipHintText(maxHeightPx, flagName) {
+    return `full page exceeds ${maxHeightPx}px; clipped — use ${flagName} to raise`;
+}
 /** Derives a filename from a URL (host+path) or the source .html filename. */
 function deriveFilename(target) {
     if (target.kind === "html-file") {
@@ -225,6 +243,14 @@ export async function captureScreenshot(opts) {
     for (const sel of opts.hide ?? [])
         assertHideSelector(sel);
     const hide = [...(opts.hide ?? []), ...(autoHideDevTools ? DEV_TOOLBAR_SELECTORS : [])];
+    // Full-page height cap (issue #652): only meaningful with fullPage. 0
+    // (explicit --max-height 0) means uncapped; undefined applies the default.
+    const effectiveMaxHeight = opts.fullPage ? (opts.maxHeight ?? DEFAULT_FULL_PAGE_MAX_HEIGHT) : 0;
+    // Shared by both backends below — only meaningful when fullPage capped at
+    // a positive height; `clipped` is the one thing that differs per backend.
+    const cappedFrom = (clipped) => opts.fullPage && effectiveMaxHeight > 0
+        ? { maxHeightPx: effectiveMaxHeight, clipped }
+        : undefined;
     // Populated only when auto-routing actually probes the filesystem, so it
     // can be threaded into captureLocalImpl below to avoid a second scan.
     let detected;
@@ -284,6 +310,7 @@ export async function captureScreenshot(opts) {
             viewport,
             selector: opts.selector,
             fullPage: opts.fullPage,
+            maxHeightPx: effectiveMaxHeight,
             colorScheme: opts.colorScheme,
             waitUntil,
             hide,
@@ -294,7 +321,8 @@ export async function captureScreenshot(opts) {
             detectRoots: opts.detectRoots,
             detectResult: detected,
         });
-        return { png: localResult.png, filename, backend, measures: localResult.measures };
+        const capped = cappedFrom(localResult.clipped === true);
+        return { png: localResult.png, filename, backend, measures: localResult.measures, capped };
     }
     if (target.kind === "html-file") {
         const bytes = new TextEncoder().encode(target.html).byteLength;
@@ -303,15 +331,17 @@ export async function captureScreenshot(opts) {
         }
     }
     const captureRemoteImpl = opts.captureRemoteImpl ?? captureRemote;
-    const png = await captureRemoteImpl({
+    const remoteResult = await captureRemoteImpl({
         ...(target.kind === "html-file" ? { html: target.html } : { url: target.url }),
         viewport,
         selector: opts.selector,
         fullPage: opts.fullPage,
+        ...(opts.fullPage && effectiveMaxHeight > 0 ? { maxHeight: effectiveMaxHeight } : {}),
         colorScheme: opts.colorScheme,
         waitUntil,
         ...(hide.length > 0 ? { hide } : {}),
         ...(opts.reducedMotion ? { reducedMotion: true } : {}),
     }, { apiUrl: opts.apiUrl, token: opts.token });
-    return { png, filename, backend };
+    const capped = cappedFrom(remoteResult.clipped === true);
+    return { png: remoteResult.png, filename, backend, capped };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.41.1",
+  "version": "0.42.1",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,
@@ -38,7 +38,7 @@
     "node": ">=22"
   },
   "peerDependencies": {
-    "files-sdk": "^2.2.3"
+    "files-sdk": "^2.2.4"
   },
   "peerDependenciesMeta": {
     "files-sdk": {
@@ -48,7 +48,7 @@
   "devDependencies": {
     "@types/node": "^26.1.0",
     "ai": "^6.0.0",
-    "files-sdk": "^2.2.3",
+    "files-sdk": "^2.2.4",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
   },