List the digital-signage players (screens) in the calling tenant.

When to use:

• You need to discover which players exist before reading or changing them.

• The user asks "how many screens are online?" or wants an overview.

When NOT to use:

• You already know a specific player_id — call get_player instead, it's cheaper.

What to know:

• Optional filters: status ("online" | "offline"), group_id (UUID).

• Returns up to 25 players per call; pagination is not yet exposed in MVP.

• "online" means a heartbeat arrived within the last 90 seconds.

Fetch a single player by id.

When to use:

• You have a player_id and need its current state, assigned content, or last-seen timestamp.

When NOT to use:

• You only have the player's name — list_players first to resolve the id.

What to know:

• Returns the same shape as list_players' data items.

• 404 if the id does not exist in the calling tenant — never cross-tenant.

Patch mutable fields on a single player.

When to use:

• The user wants to rename a player, change its orientation, or reassign content.

When NOT to use:

• For content authoring — playlists, sequences, and planning have their own dedicated tools (coming in v0.2.0).

What to know:

• Mutable fields: name, orientation ("landscape" | "portrait" | "portrait-reverse"), playlist_id, sequence_id, planning_id, group_id.

• Assigning a *_id schedules a publish — the response includes publish_required: true. Call publish_players to make the player actually pick up the change.

• Pass null to clear an assignment (e.g. playlist_id: null).

• Exactly one of playlist_id / sequence_id / planning_id may be non-null at a time.

Build a fresh content snapshot so one or every player picks up its current content assignment.

When to use:

• update_player returned publish_required: true.

• The user changed a playlist's items elsewhere and asks to make screens reflect it.

When NOT to use:

• For a single field-only rename — that takes effect immediately without publish.

What to know:

• Omit player_id to publish every player in the tenant. Per-player failures are returned in "failed" without aborting the batch.

• Players with no playlist/sequence/planning assigned are listed under "skipped" with reason "no_content_assigned".

• Snapshots are durable; the player pulls them on its next heartbeat (typically within 10 seconds).

List the playlists in the calling tenant.

When to use:

• You need to surface playlist names and ids before assigning one to a player via update_player.

When NOT to use:

• For inspecting the items inside a playlist — get_playlist (v0.2.0) returns the playlist with its items inline.

What to know:

• Returns id, name, and timestamps. Item-level CRUD lands in v0.2.0 of this MCP server.

Fetch a single playlist by id, optionally with its content items inline.

When to use:

• The user wants to inspect what's actually queued on a playlist.

• You need the item ids before reordering or patching items.

When NOT to use:

• For just the name/id — list_playlists is one round-trip.

What to know:

• include_items=true returns the playlist with its items array; otherwise only the playlist row.

• Item shape depends on type (image/video/image_slideshow/youtube). Inspect type before assuming asset_id vs external_url vs config.

Create a new empty playlist in the calling tenant.

When to use:

• Bootstrapping content for a player, or splitting an existing playlist.

When NOT to use:

• A playlist with that name might already exist — list_playlists first if reuse is acceptable.

What to know:

• Only name is required. default_interval (seconds) and image_uri (cover-art URL) are optional and can be added later via update_playlist.

• The playlist starts empty; use add_playlist_item to fill it.

Patch a playlist's metadata.

When to use:

• Renaming a playlist, changing its default item duration, or swapping the cover image.

When NOT to use:

• For changing items — use add_playlist_item / update_playlist_item / delete_playlist_item.

What to know:

• Only name, default_interval, image_uri are mutable here. Pass image_uri: null to clear the cover.

• Updating a playlist does NOT trigger a publish on its own; a player assigned to this playlist still needs publish_players to pick up the new items list.

Permanently delete a playlist and all its items.

When to use:

• The playlist is no longer used by any player and you want to free up the name.

When NOT to use:

• A player still references this playlist — unassign it first via update_player (set playlist_id: null), otherwise the player will lose its content on next publish.

• You only want to clear items but keep the playlist — delete the items individually.

What to know:

• Irreversible. Cascade-deletes the playlist's content_items.

• Returns 204 on success.

Append a content item to a playlist.

When to use:

• Adding an image, video, YouTube embed, or image slideshow to an existing playlist.

When NOT to use:

• For images/videos: the asset must already exist (status='ready'). Use the asset upload flow first.

What to know:

• type drives the rest of the payload:

  • image / video → asset_id (UUID, already-uploaded asset)

  • youtube → external_url (a youtube.com or youtu.be link)

  • image_slideshow → config.asset_ids[] (1+ already-uploaded image UUIDs) plus optional image_duration / transition_speed / fit / bg_color / randomize

• duration_seconds overrides the playlist's default_interval for this item.

• schedule_start / schedule_end (HH:MM or HH:MM:SS) constrain the item to a time window.

• The item is appended at the end; use reorder_playlist_items to change order.

Patch an existing content item.

When to use:

• Renaming an item, adjusting duration_seconds, changing a schedule window, swapping the asset on an image/video item.

When NOT to use:

• For changing type — delete the item and add a new one (type drives a different validation surface).

• For reordering — use reorder_playlist_items.

What to know:

• Only the provided fields are touched. Pass null on nullable fields to clear them.

• Mutable: name, duration_seconds, is_selected, schedule_start, schedule_end, asset_id, external_url, config.

Remove an item from a playlist.

When to use:

• Pruning content that's no longer relevant.

When NOT to use:

• You want to keep the item but skip it for now — set is_selected: false via update_playlist_item instead.

What to know:

• Irreversible. The remaining items stay in order; gaps in sort_order are normalised on the server.

• The asset itself is NOT deleted (other playlists may reference it).

Set the playback order of a playlist's items in one call.

When to use:

• The user wants to promote/demote a few items, or apply a freshly-computed order.

When NOT to use:

• You only want to move one item by one position — same call still works, but reading + emitting the full list is the cost.

What to know:

• item_ids MUST contain every current item of the playlist, in the desired final order.

• A missing or extra id returns 422 with reorder_mismatch.

• Server uses a two-phase update (negative offset then final) to avoid UNIQUE(parent_id, sort_order) conflicts mid-flight.