Report whether the DualStream desktop app's control server is reachable, including app version, port, auth mode, and this connection's consent state (consent: 'pending' means the streamer must approve this client inside DualStream before other tools work). Call this first when other DualStream tools fail, to distinguish 'app not running' from real errors.

Authoritative snapshot of DualStream's scene state: every scene (scene_id + scene_name) and the active scene id. Call this to (re)sync after connecting or after an event.resync_required / event.scenes_changed event.

List all scenes in DualStream's active collection as {scene_id, scene_name}. scene_id is stable across rename/reorder within a collection; a collection switch invalidates ids (an event.scenes_changed with reason 'collection_switched' is emitted).

Return the currently active scene ({scene_id, scene_name}) or null if none.

Switch DualStream's live output to another scene. Takes effect immediately on the user's live stream; call only when the user asked for a scene change. Identify the scene by scene_id (preferred, from get_scenes) or by exact scene_name (case-insensitive). Optional transition name overrides the scene's default transition.

Save the last N seconds of the stream as a clip pair (horizontal + vertical files are saved natively). duration_sec is optional; omitted uses the user's configured default. If the replay buffer is warming up the error is marked retryable; wait for the user's go-ahead and try again.

Poll buffered control events (scene_activated, scenes_changed, scene_renamed, clip_saved, stream_event, resync_required), oldest first. Pass since_seq from your last call to receive only new events; truncated=true means events were evicted and you should resync with get_state_snapshot. Timestamps are receipt times stamped by this MCP server. event.stream_event entries are platform events (follows/subs/raids/…) that matched an enabled automation; use this for catch-up ('what happened this stream?'); use wait_for_event to react live.

List DualStream's installed recipes: reusable scene templates (a background plus positioned sources for both the 16:9 and 9:16 canvases). Optionally filter by mode. Use before apply_recipe to discover recipe ids, or before authoring to avoid duplicate names.

Apply a recipe to the live stream. By default this CREATES a new scene from the recipe and switches to it, taking effect immediately on the user's stream, so call only when the user asked to build/switch a scene. Pass target_scene_id to instead add the recipe's sources into an existing scene. Both canvases (H+V) are populated from the recipe.

Author a new recipe from a manifest and save it to the user's recipe library (does NOT change the live stream; use apply_recipe for that). A manifest is a background plus a list of sources with per-canvas geometry. The simplest useful recipe uses a color/gradient background and Text sources; no media files needed. Full field reference: contract/set-design-v1.md in this package. Shapes:

• background (optional): SceneBackground, e.g. {"SolidColor":{"color":"#7C3AED"}} or {"Gradient":{"start_color":"#111","end_color":"#333","direction":"DiagonalDown"}}.

• sources[]: {kind, name, settings, and geometry}. kind is PascalCase ("Text","Image",...). Geometry: absolute pixels at 1920x1080 via position{x,y}+size{w,h} and verticalPosition+verticalSize for the 9:16 canvas, OR resolution-independent positionGrid (Center, TopLeft, …) + sizePct{w,h} (percent).

• A Text source's settings: {text, fontFamily, fontSize, color:"#RRGGBB", outlineEnabled, outlineColor, shadowEnabled, halignment:"center", valignment:"center", backgroundColor:"#AARRGGBB", scrollEnabled, scrollSpeed}. id/version/thumbnail are filled in automatically.

Read the current settings JSON for a widget in the active scene (alert box, chat box, goal tracker, or prediction tracker). Returns the exact shape update_widget_settings accepts: read it, change the fields you want, send it back. Errors with widget_not_found if the active scene has no widget of that type (alerts always exist).

Apply new settings to a widget in the active scene; takes effect immediately on the stream. Pass the full settings object from get_widget_settings with your changes applied (round-trip: get, modify, update). format omitted applies to both canvases. For alerts, changes also update the durable canonical template used by every scene.

Enumerate capture devices available to add as sources: cameras, capture cards, virtual cameras, displays, windows, audio inputs. Each entry gives a device_id and source_type ready to pass straight to add_source. Displays include is_primary and resolution. Call this first to find, e.g., the user's webcam or primary monitor.

Create a new empty scene. Pass activate:true to switch the live output to it immediately (call only when the user wants to build/switch to it now); otherwise it's created off-air and you can populate it, then activate_scene when ready. Returns the new scene_id to pass to add_source.

List the sources in a scene (defaults to the active scene) with their ids, types, visibility, per-canvas transform, and whether each has a crop/shape/effects applied. Use to find source_ids for set_source_* calls, or to see the current layout.

Add a source to a scene (defaults to the active scene); it appears live immediately if the scene is active. For cameras/displays/windows, pass the device_id and source_type from list_devices verbatim. The new source lands centered by default; use set_source_transform to position/size it, set_source_shape to mask it, etc. Returns the new source_id.

Remove a source from a scene (defaults to the active scene) by source_id.

Set a source's position and/or size on a canvas. Coordinates are absolute pixels: the horizontal (desktop) canvas is 1920×1080, the vertical (mobile) canvas is 1080×1920. Provide any of x, y, width, height (omitted keys unchanged). ALWAYS set the two canvases SEPARATELY (format:'horizontal' then format:'vertical'); a desktop layout never maps 1:1 to mobile. Desktop examples: fullscreen bg {x:0,y:0,width:1920,height:1080}; bottom-right cam {x:1400,y:790,width:480,height:270}. MOBILE (vertical 1080×1920) is a tall portrait frame; rethink the layout, don't shrink the desktop one. Good mobile patterns: (a) CAM + SCREEN: full-width square camera at the TOP {x:0,y:0,width:1080,height:1080}, and the 16:9 screen/game below it centred in the lower band {x:0,y:1196,width:1080,height:608}. (b) CAM-ONLY (just chatting): a large cam centred {x:0,y:420,width:1080,height:1080}. (c) GAME + FACECAM: game full-width at top {x:0,y:280,width:1080,height:608}, circle facecam lower {width:300,height:300}. Fill the tall frame; avoid large empty bands.

Crop pixels off a source's edges. left/right/top/bottom are absolute pixels of the SOURCE's native resolution (not the canvas). anchor controls where the retained region sits (Center, Top, …). format omitted applies to both canvases.

Mask a source to a shape. shape='Circle' inscribes a circle (great for round webcam cams); 'RoundedRectangle' uses radius (pixels); 'RoundedRectangle9x16' for portrait; 'None' clears the mask. format omitted applies to both canvases.

Apply visual effects to a source. Provide any of border, shadow, glow, blur (each an object). Colors are u32 RGBA integers (0xRRGGBBAA as decimal; e.g. white=4294967295). Examples. Soft shadow: {shadow:{enabled:true,offsetX:6,offsetY:8,blur:20,opacity:0.5,color:255,inner:false}}; white border: {border:{enabled:true,width:6,color:4294967295,style:0}}; blur: {blur:{enabled:true,sigma:8}}. format omitted applies to both canvases.

Change a source's layer order. 'back' sends it behind everything (use for a background/screen added after a camera so it doesn't cover the cam); 'front' brings it above other sources (alert overlays keep their reserved top layer); 'up'/'down' move one step. New sources are added on top, so a background added last usually needs 'back'.

Show, hide, or toggle a source in a scene. Omit 'visible' to toggle. Applies to both canvases unless format narrows it. A source_id from another scene resolves to this scene's matching instance (same device or name). Returns the new state.

Mute, unmute, or toggle an audio-carrying source. Applies to every scene containing the source (matched by device identity), so the mute survives scene switches. Omit 'muted' to toggle. The source's saved volume is preserved. Returns the new state.

Enable, disable, or toggle an effect already configured on a source (shader-style filters like a black-and-white look). Omit 'enabled' to toggle. Only effects the streamer already applied can be toggled; the error lists what is configured. Returns the new state.

Post a card onto the live stream via DualStream's alert system; it renders on both canvases with the styling, position, sound, and duration the streamer configured for the AI Card alert type. You supply only the text: a title and an optional message body. Use for short, timely, viewer-facing moments (welcoming a raid, celebrating a milestone), only when the user asked for it or set up an automation. The AI Card type is OFF by default; a card_disabled error means the streamer must enable it in the alerts inspector first (they were shown a notice pointing there).

Block until a control event arrives (or return immediately if matching events are already buffered past since_seq). WARNING: while this call waits, the user cannot interact with their assistant at all; the whole session is held. Only call it when the user has EXPLICITLY asked you to listen for events ("watch my stream", "wait for the next raid"). Never use it to wait for consent approval or as a convenience between steps; for those, tell the user what to do, end your turn, and retry when they respond. Live-reaction loop: pass the last_seq from your previous call, filter to ['event.stream_event'] to wake only on automation-matched platform events, act on the automation prompt in the payload, then call wait_for_event again. No timeout is applied by this server; the call resolves on the next event, or fails (retryable) if the DualStream connection drops while waiting.

List the streamer's stored automations; each pairs a stream-event trigger (event types, optional platform and min_amount) with a prompt: the streamer's standing instruction for what you should do when that event arrives. Disabled automations are included but never relay events.

Create or update an automation (matched by id; id is derived from name when omitted). Only create automations the streamer asked for. The doc follows automation-v1: trigger.event_types uses canonical names ("Follow", "Raid", "Cheer", "SuperChat", …); trigger.min_amount compares against the event's amount, whose meaning is per-type (raid=viewers, cheer=bits, gift=count, resub=months). Prefer rare, high-signal events; every match wakes the AI session. Matching events start relaying immediately.

Delete a stored automation by id. Its events stop relaying immediately.