@pinepaper.studio/mcp-server 1.6.14 → 1.6.16

package/dist/tools/definitions.js

@@ -1755,6 +1755,91 @@ EXAMPLE: { checks: ["contrast", "flash"], duration: 6, fps: 20 }`,
             },
         },
     },
+    {
+        name: 'pinepaper_generate',
+        annotations: { title: 'Generate Image (cloud)', readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        description: `Generate images with an AI model in the PinePaper cloud, and optionally place the first one on the canvas. CHARGED per output — price it first with pinepaper_generate_estimate (free).
+
+Needs a service-account key in PINEPAPER_API_KEY (pp_sa_…, render:create scope). It is an internal beta enabled per organisation: without it the result says "not enabled for your organisation", and nothing is charged. Every refusal says whether anything was charged.
+
+- model or useCase: a model id from pinepaper_generate_estimate {listModels: true}, or a use case and the cloud picks its default (hero stills, plates, text in the image, character-consistent edits).
+- input: { prompt, aspect ('16:9' | '9:16' | '1:1' | '4:5'), n (1-4), seed?, negativePrompt?, imageUrls? (https references for edit models) }.
+- brief / designRef: always passed on; the cloud records each generation against the design.
+- place: 'cover' (fill the canvas, centred; default when true) or 'contain' — places the first asset: an image as an image item, a video as a video layer (with its durationSeconds). The fit uses the asset's delivered size, not the requested aspect.
+- timeoutSec: how long to wait (default 180). A job that outlives it keeps running and is only charged if it delivers; collect it with pinepaper_generate_status.
+
+WORDS ARE VECTOR: give words as input.text [{content, role?: headline|subhead|caption|cta|label, font?}]. The model makes a text-free plate; the words come back as textLayers (plus a hint), and with place they are added as real, editable text over it: headline top-left (Anton by default), subhead below, caption / cta bottom-left, label top-right, inside title-safe, each contrast-checked against the plate (a dark scrim is added only where it falls short of WCAG 4.5:1, or 3:1 for large text). Their item ids are in placement.text.
+
+The result: assets [{assetId, ref, width, height}] — the sizes the files HAVE (a model may pick its own size for an aspect), chargedUsd, and any model notes (e.g. a SynthID watermark) to pass on.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                model: { type: 'string' },
+                useCase: { type: 'string' },
+                input: {
+                    type: 'object',
+                    properties: {
+                        prompt: { type: 'string' },
+                        aspect: { type: 'string', enum: ['16:9', '9:16', '1:1', '4:5'] },
+                        n: { type: 'integer', minimum: 1, maximum: 4 },
+                        seed: { type: 'integer' },
+                        negativePrompt: { type: 'string' },
+                        imageUrls: { type: 'array', items: { type: 'string' }, maxItems: 14, description: 'Reference / start-frame images: https URLs, or your own generated images as their ref "/scene-assets/<id>" (chain a still into a video or a character edit).' },
+                        seconds: { type: 'number', exclusiveMinimum: 0, maximum: 60, description: 'Video models: clip length; each model allows its own lengths (listModels).' },
+                        text: { type: 'array', maxItems: 12, items: { type: 'object', properties: { content: { type: 'string' }, role: { type: 'string', enum: ['headline', 'subhead', 'caption', 'cta', 'label'] }, font: { type: 'string' } }, required: ['content'] }, description: 'Words for the design. The model never draws them: the plate comes back text-free and these return as textLayers — with place, laid out as real PinePaper text.' },
+                        allowText: { type: 'boolean', description: 'Let the MODEL draw text — eval-tier models only (e.g. ideogram-v3); refused (422) elsewhere. Prefer text.' },
+                    },
+                    required: ['prompt'],
+                },
+                brief: { type: 'string' },
+                designRef: { type: 'object', properties: { kind: { type: 'string' }, id: { type: 'string' } }, required: ['kind', 'id'] },
+                place: { anyOf: [{ type: 'boolean' }, { type: 'string', enum: ['cover', 'contain'] }] },
+                timeoutSec: { type: 'integer', minimum: 10, maximum: 1800 },
+            },
+            required: ['input'],
+        },
+    },
+    {
+        name: 'pinepaper_generate_estimate',
+        annotations: { title: 'Estimate Generation (free)', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        description: `Free: price a pinepaper_generate call before making it, or list the models. { listModels: true } returns every model you may use with its price per output, use cases, licence notes and the defaults per use case; { model | useCase, input } returns the estimate for that request. Needs PINEPAPER_API_KEY, like pinepaper_generate.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                model: { type: 'string' },
+                useCase: { type: 'string' },
+                input: {
+                    type: 'object',
+                    properties: {
+                        prompt: { type: 'string' },
+                        aspect: { type: 'string', enum: ['16:9', '9:16', '1:1', '4:5'] },
+                        n: { type: 'integer', minimum: 1, maximum: 4 },
+                        seed: { type: 'integer' },
+                        negativePrompt: { type: 'string' },
+                        imageUrls: { type: 'array', items: { type: 'string' }, maxItems: 14, description: 'Reference / start-frame images: https URLs, or your own generated images as their ref "/scene-assets/<id>" (chain a still into a video or a character edit).' },
+                        seconds: { type: 'number', exclusiveMinimum: 0, maximum: 60, description: 'Video models: clip length; each model allows its own lengths (listModels).' },
+                        text: { type: 'array', maxItems: 12, items: { type: 'object', properties: { content: { type: 'string' }, role: { type: 'string', enum: ['headline', 'subhead', 'caption', 'cta', 'label'] }, font: { type: 'string' } }, required: ['content'] }, description: 'Words for the design. The model never draws them: the plate comes back text-free and these return as textLayers — with place, laid out as real PinePaper text.' },
+                        allowText: { type: 'boolean', description: 'Let the MODEL draw text — eval-tier models only (e.g. ideogram-v3); refused (422) elsewhere. Prefer text.' },
+                    },
+                    required: ['prompt'],
+                },
+                listModels: { type: 'boolean' },
+            },
+        },
+    },
+    {
+        name: 'pinepaper_generate_status',
+        annotations: { title: 'Generation Status', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        description: `Collect a pinepaper_generate job that outlived its timeoutSec: its status, and when done its assets and chargedUsd. place: 'cover' | 'contain' places the first image, as pinepaper_generate does.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                jobId: { type: 'string' },
+                place: { anyOf: [{ type: 'boolean' }, { type: 'string', enum: ['cover', 'contain'] }] },
+            },
+            required: ['jobId'],
+        },
+    },
     {
         name: 'pinepaper_render_batch',
         annotations: {
@@ -2043,15 +2128,18 @@ EXAMPLE: { times: [0, 0.5, 1, 1.5, 2], seed: 42 }`,
         description: `Bring VIDEO and AUDIO onto the canvas from a URL, and control playback. Uploaded video is a first-class canvas item (drag, scale, animate, export like any shape); audio rides the timeline.
 
 ACTIONS:
-- upload_video: { url (required), position?, scale?, timeOffset? (timeline start, s), clipInPoint?, clipOutPoint? (trim, s) } → { id, duration, width, height, name }
-- upload_audio: { url (required), volume? (0–1, default 1), loop?, muted?, timeOffset? } → { id, registryId, duration, name }. Pass loop EXPLICITLY — loop:true for a music bed, loop:false for a voice-over or sting; when omitted, the studio's own default applies and differs between builds.
+- upload_video: { url (required), position?, scale?, timeOffset? (timeline start, s) or atPlayhead?: true (start at the current playback time), clipInPoint?, clipOutPoint? (trim, s) } → { id, duration, width, height, name }
+- upload_audio: { url (required), volume? (0–1, default 1), loop?, muted?, timeOffset? or atPlayhead? } → { id, registryId, duration, name }. Pass loop EXPLICITLY — loop:true for a music bed, loop:false for a voice-over or sting; when omitted, the studio's own default applies and differs between builds.
 - list: → all media [{ id, kind, duration, … }]
 - remove: { id } → removed boolean
 - set_playback_rate: { id, rate (0.25–4) } → applies to video or audio
-- set_clip: { id, inPoint, outPoint (media-time s, outPoint > inPoint) } → re-trim an ALREADY-uploaded clip (video or audio)
+- set_clip: { id, inPoint, outPoint (media-time s, outPoint > inPoint), timeOffset? (canvas s: also MOVE the clip to start there) } → re-trim an ALREADY-uploaded clip (video or audio). A studio that cannot move clips refuses timeOffset rather than ignoring it.
+- split: { id, at (canvas s) } → cut a clip in two: { leftId, rightId, leftMediaId, rightMediaId, at }. The first half keeps its id. Refused (not claimed) where the studio cannot split or the time is outside the clip.
+- add_transition: { fromItemId (ends at the cut), toItemId (starts at it), transition?: { type: 'crossfade'|'dip', seconds, color } } → the same in preview and export. Split a clip, then transition between its halves, or join two clips that meet.
+- For an IMAGE on the timeline, use pinepaper_import_image with bornAt / ttl (seconds on screen).
 
 NOTES:
-- URL-based: the URL is fetched in the browser, so it must be reachable + CORS-permitted.
+- The server fetches the URL (or reads a local path / data: URL) and hands the page the bytes, so it does not need to be CORS-permitted.
 - Use the returned id with set_playback_rate / set_clip / remove, and (for video) modify/animate it like any item.
 
 VIDEO EDITING:
@@ -2065,14 +2153,16 @@ EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, time
         inputSchema: {
             type: 'object',
             properties: {
-                action: { type: 'string', enum: ['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip', 'set_time_remap', 'speed_ramp', 'match_cut', 'apply_track_matte', 'stop_live_matte'], description: "Media action" },
+                action: { type: 'string', enum: ['upload_video', 'upload_audio', 'list', 'remove', 'set_playback_rate', 'set_clip', 'split', 'add_transition', 'set_time_remap', 'speed_ramp', 'match_cut', 'apply_track_matte', 'stop_live_matte'], description: "Media action" },
+                transition: { type: 'object', properties: { type: { type: 'string', enum: ['crossfade', 'dip'] }, seconds: { type: 'number', exclusiveMinimum: 0, maximum: 10 }, color: { type: 'string' } }, description: "add_transition: { type ('crossfade' default | 'dip'), seconds, color (dip) }." },
+                atPlayhead: { type: 'boolean', description: 'upload_video / upload_audio: start at the current playback time (instead of timeOffset).' },
                 remapTrack: { type: 'array', items: { type: 'object', properties: { time: { type: 'number' }, value: { type: 'number' }, easing: { type: 'string' } }, required: ['time', 'value'] }, description: 'set_time_remap: canvas-seconds → source-seconds curve (≥2 points). null clears the remap.' },
                 segments: { type: 'array', items: { type: 'object', properties: { duration: { type: 'number' }, speed: { type: 'number' } }, required: ['duration', 'speed'] }, description: 'speed_ramp: consecutive {duration, speed} segments. speed 0 = freeze frame, negative = reverse.' },
                 fromItemId: { type: 'string', description: 'match_cut: outgoing shot item id.' },
                 toItemId: { type: 'string', description: 'match_cut: incoming shot item id.' },
                 subject: { type: 'string', enum: ['detect', 'bounds'], description: "match_cut: subject source — 'detect' (on-device DETR, needs consent on first use) or 'bounds'." },
                 label: { type: 'string', description: 'match_cut: narrow detection to one class ("person") when the biggest object is not the subject.' },
-                at: { type: 'number', description: 'match_cut: cut time in seconds (default 0).' },
+                at: { type: 'number', description: 'match_cut: cut time in seconds (default 0). split: the canvas time to cut at (required).' },
                 settle: { type: 'number', description: 'match_cut: seconds to relax to natural framing (default 0.8).' },
                 fade: { type: 'number', description: 'match_cut: crossfade seconds; 0 = hard cut (default 0.12).' },
                 consent: { type: 'boolean', description: 'match_cut: allow the detection model download (a first run without it returns needsConsent instead of downloading silently).' },
@@ -2089,7 +2179,7 @@ EXAMPLE: { action: 'upload_video', url: 'https://…/clip.mp4', scale: 0.5, time
                 outPoint: { type: 'number', description: 'Clip out-point (media-time s, > inPoint) — set_clip.' },
                 position: { type: 'object', properties: { x: { type: 'number' }, y: { type: 'number' } }, description: 'Canvas position — upload_video.' },
                 scale: { type: 'number', description: 'Scale factor — upload_video.' },
-                timeOffset: { type: 'number', description: 'Timeline start offset (s) — upload_video / upload_audio.' },
+                timeOffset: { type: 'number', description: 'Timeline start offset (s) — upload_video / upload_audio; set_clip: move the clip to start here.' },
                 clipInPoint: { type: 'number', description: 'Trim in-point (s) — upload_video.' },
                 clipOutPoint: { type: 'number', description: 'Trim out-point (s) — upload_video.' },
                 volume: { type: 'number', description: 'Volume 0–1 (default 1) — upload_audio.' },
@@ -3571,6 +3661,10 @@ EXAMPLE — Reveal at 2s, skip first second of keyframe data, end at 4s of keyfr
                     type: 'number',
                     description: 'Stop at N seconds into the keyframe data (tail trim). Default: lastKeyframeTime.',
                 },
+                append: {
+                    type: 'boolean',
+                    description: 'Add these keys to the item\'s existing track (same-time keys merge, new values win) instead of replacing it — e.g. a button press after an entrance. Without it, a second call replaces the track. result.track says whether the track was appended to or replaced; studios without merge replace, and say so.',
+                },
             },
             required: ['itemId', 'keyframes'],
         },
@@ -4901,7 +4995,9 @@ ACTIONS:
 - update_from_instance: Promote an instance's edits back into the master. Params: instanceId
 - detach: Make an instance an ordinary independent item. Params: instanceId
 
-Overrides are the point: an instance can differ from its master and still receive master updates.`,
+Overrides are the point: an instance can differ from its master and still receive master updates.
+
+Instances carry the master's LOOK (geometry, style, text), not its animation: instantiate and sync copy what the master is, not its keyframes or animations. To animate instances, animate each one (keyframe_animate on its instanceId, or stagger across them).`,
         inputSchema: {
             type: 'object',
             properties: {
@@ -8046,9 +8142,11 @@ VERIFY MOTION BEFORE YOU RENDER. An export takes seconds to minutes and shows yo
                         maxBytes: { type: 'integer', minimum: 1, description: 'Upload size budget (zip for html5-ad, HTML for playable). html5-ad default 150000 (Google Ads display); set your network figure.' },
                     },
                 },
-                transparent: { type: 'boolean', description: 'apng only: keep the alpha channel (the default); false fills the background colour.' },
+                transparent: { type: 'boolean', description: 'apng: keep the alpha channel (the default; false fills the background colour). webm: true writes a VP9 alpha channel where the studio supports it; result.video.alpha confirms it, and fidelity says when it did not. Not for mp4 / gif.' },
+                alphaQuantizer: { type: 'integer', minimum: 0, maximum: 63, description: 'webm with transparent: alpha-stream quality, 0 = lossless … 63.' },
                 loop: { anyOf: [{ type: 'boolean' }, { type: 'integer', minimum: 0, maximum: 1000 }], description: 'gif / apng: true = loop forever, false / 0 / 1 = play once, n = play n times (email clients often want a few plays, not forever). Refused on video formats — see SEAMLESS LOOPS.' },
                 broadcast: { type: 'boolean', description: 'mp4 only: broadcast-safe — BT.709, limited range (16-235), tagged bt709, constant bitrate with an 8 Mbps floor at 720p+ (4 below). result.video reports what the encoder did.' },
+                deterministic: { type: 'boolean', description: 'mp4 / webm: byte-identical files for the same scene (pins the container timestamps), so exports can be checksummed or cached by hash.' },
                 broadcastHeadroom: { type: 'integer', minimum: 0, maximum: 40, description: 'mp4 with broadcast only, default 12: luma codes kept clear at both ends, so encoder ringing stays legal (12 measured clean on hard edges; 4 = ~100x fewer out-of-range samples, 12 = ~1000x; never zero). Fidelity raises luma_out_of_range with the legaliser command when any remain.' },
                 bitrate: { type: 'integer', minimum: 100000, maximum: 200000000, description: 'mp4 / webm: target bits/s, replacing the quality-derived one. The browser encoder treats it as a CEILING; result.video.achievedBitrate is what it produced.' },
                 minBitrate: { type: 'integer', minimum: 100000, maximum: 200000000, description: 'mp4 / webm: a floor; a miss is a fidelity warning naming the re-encode a delivery spec needs.' },