A1: Add Builtin-backed MCP shortcuts for approved outcomes

Kevin approved rows 1–9 on 2026-10-15. Parent: transloadit/api2#9857. Spec: posted merged list, with full research in ~/.local/state/gh-board-dispatcher/research/9857/ (merged.md, three r2 files, sign-offs). Posted sign-off corrections supersede stale details in merged.md.

Why

Expose the approved outcomes as thin adapters of one Builtin-owned workflow and field contract.

Dependencies and scope

Depends on https://github.com/transloadit/api2/issues/9920 plus the matching Builtins below being merged/deployed. Scaffold after F0 and ship per outcome after its owner completes real-output review. Adapters do not depend on one another.

Implement in packages/mcp-server. Reuse tool-metadata.ts, upload/create/wait helpers, transloadit_list_templates and Builtin template_id support. Pass schema metadata through the current list mapper and derive shortcut input schemas from the catalog. M1 rows 1/2/3/4/5/7/8; M2 rows 6/9. Keep generic tools compatible. Use the approved OCR fallback until node-sdk#559 release where SDK lint is needed; plain captions do not wait for social. Correct the speechTranscribe intent’s target_language translation claim.

F0 discovery contract

Reuse GET /templates with include_builtin=exclusively-latest (or exclusively-all). Existing name, builtin_version, description and id identify the Builtin; new fields_schema contains standalone draft-07 JSON Schema. Defaults remain in content.fields: merge those with caller fields before validation. Null means an older Builtin has no declared schema; Workspace Templates omit the property. x-transloadit-input-fidelity: conservative marks deliberately approximate constraints; runtime validation remains authoritative. MCP must pass this metadata through its existing mapper.

Approved steps, fieldsSchema and channel contract

B1: prepare-image (rows 4)

Owner: https://github.com/transloadit/api2/issues/9921

Steps: /upload/handle → /image/resize: fit, format, quality, strip and rotation auto.

Field owners: w/h ← dimensionFieldSchema; q ← qualityFieldSchema; bg ← backgroundColorFieldSchema; f/r ← imageFormatFieldSchema/resizeStrategyFieldSchema lifted from storage-preview; strip ← robotImageResizeInstructionsSchema.shape.strip.

Channels: Builtin, MCP M1, skill, Zapier.

B2: video-covers (rows 2)

Owner: https://github.com/transloadit/api2/issues/9922

Steps: /upload/handle → /video/thumbs: smart selection/count or exact offsets.

Field owners: robotVideoThumbsInstructionsSchema.pick({ count: true, offsets: true, smart: true, smart_max_candidates: true, width: true, height: true, format: true }). Keep Robot limits: 1920×1080, not the 8000px image fragment.

Channels: Builtin, MCP M1, skill, Zapier.

B3: transcribe + caption-video (rows 1, 6)

Owner: https://github.com/transloadit/api2/issues/9923

Steps: /upload/handle → /speech/transcribe (text, JSON timestamps, SRT or WebVTT). Plain captions: SRT transcription plus original video → /video/subtitle, use aliases video/subtitles, subtitles_type burned. Social later uses JSON word timings.

Field owners: provider/source_language/format ← robotSpeechTranscribeInstructionsSchema.pick(...), including its own provider enum. Captions use robotVideoSubtitleInstructionsSchema.shape.font_size/.position/.font_color/.border_color, later .style/.highlight_color/.max_words_per_caption. Reuse subtitle colors via these exported shapes; image background colors are incompatible.

Channels: Transcribe: Builtin, MCP M1, existing skill update, Zapier. Captions: Builtin, MCP M2, new skill, Zapier.

B4: extract-text (rows 3)

Owner: https://github.com/transloadit/api2/issues/9924

Steps: /upload/handle → /file/filter image/document branches → /image/ocr and /document/extract (extract text, text_method auto). Office files first use /document/convert to PDF. MCP uses /document/ocr + /image/ocr compatibility variant until the release fixing transloadit/node-sdk#559.

Field owners: ocr_provider ← robotDocumentExtractInstructionsSchema.shape.ocr_provider with explicit aws/gcp default, also mapped to image OCR provider. Never forward awsGcpAiProviderSchema’s auto default. text_method/text_format/page_range/password come from the extract Robot. auto/OCR require provider and forbid password/page_range/page granularity; validate cross-field runtime rules separately from lint.

Channels: Builtin, MCP M1, skill, Zapier.

B5: encode-video (rows 8)

Owner: https://github.com/transloadit/api2/issues/9925

Steps: /upload/handle → /video/encode with web MP4 preset and turbo. Existing Optimize Video and Convert Video to WebM become compatible presets.

Field owners: preset ← webVideoPresetFieldSchema derived from robotFFmpegVideo.shape.preset, including web/mp4/* AND web/webm/* (gif may be in the shared subset). w/h ← robotVideoEncodeInstructionsSchema.shape.width/.height; turbo and other exposed parameters from that Robot. F0 exports video-split segmentSchema for later clip reuse.

Channels: Builtin, MCP M1, skill, existing Zapier video action updates.

B6: capture-webpage + convert-to-pdf (rows 7, 9)

Owner: https://github.com/transloadit/api2/issues/9926

Steps: /html/convert (public url, png/jpeg/pdf, fullpage), or /upload/handle → /html/convert for uploaded HTML. PDF: /upload/handle → /document/convert, format pdf; Office/HTML/Markdown/text inputs.

Field owners: Capture: robotHtmlConvertInstructionsSchema.pick({ url: true, format: true, fullpage: true, width: true, height: true, delay: true, wait_until: true }), URL composed with httpUrlSchema. PDF: documentConvertPdfFormatSchema plus robotDocumentConvertInstructionsSchema.shape.markdown_format/.pdf_margin/.markdown_theme where exposed. Document thumbnail review uses its own Robot width/height (5000px cap).

Channels: Capture: Builtin, MCP M1, skill, Zapier. PDF: Builtin, MCP M2, existing Markdown-to-PDF skill update, Zapier.

B7: remove-background (rows 5)

Owner: https://github.com/transloadit/api2/issues/9927

Steps: /upload/handle → /image/bgremove, transparent PNG output.

Field owners: Use robotImageBgremoveInstructionsSchema.pick({ format: true, select: true, provider: true }); retain its PNG/foreground behavior and provider defaults. Expose model only if the simple outcome needs the existing provider-specific override. No parallel provider or format schema.

Channels: Builtin, MCP M1, existing skill update, Zapier.

Done when

• Implement as a versioned Builtin owning steps and BuiltinTemplateDefinition.fieldsSchema, built from the existing fragments/Robot shapes named here. Adapters consume the catalog and execute its template_id; no copied pipelines or constraints.
• Meaningful red → green tests cover defaults, limits, cross-field rules and output contracts. Follow the board runbook for review and green CI.
• Dogfood on non-customer fixtures; retain actual Assembly/result artifacts. Visually review the real output (readable transcript/OCR text and rendered PDF pages count where applicable), not just lint.
• Announce the shipped outcome using the reviewed real output and a working invocation.

Also invoke through this channel and inspect actual artifacts against the Builtin output contract before announcement. Rows 10–30 are outside this wave.