gibeon.io MCP tools

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.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "online",
        "offline"
      ],
      "description": "Filter by reachability"
    },
    "group_id": {
      "type": "string",
      "format": "uuid",
      "description": "Filter by player group UUID"
    }
  },
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "player_id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID of the player"
    }
  },
  "required": [
    "player_id"
  ],
  "additionalProperties": false
}

Patch mutable fields on a single player.

When to use:
- The user wants to rename a player, change its orientation, reassign content, or toggle the free-plan watermark on a single device.

When NOT to use:
- For content authoring: playlists, sequences, and planning have their own dedicated tools.

What to know:
- Mutable fields: name, orientation ("landscape" | "portrait"), playlist_id, sequence_id, planning_id, group_id, hide_watermark.
- Assigning a *_id schedules a publish. The response includes publish_required: true. Call publish_players to make the player actually pick up the change. Same for toggling hide_watermark.
- 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.
- hide_watermark=true on a free-plan tenant is capped to 1 device. A 2nd attempt returns 422 with code free_tier_hide_watermark_limit. Paid tenants have no limit.

{
  "type": "object",
  "properties": {
    "player_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "orientation": {
      "type": "string",
      "enum": [
        "landscape",
        "portrait"
      ]
    },
    "playlist_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "sequence_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "planning_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "group_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "hide_watermark": {
      "type": "boolean",
      "description": "Suppress the free-plan branding overlay on this device. Free-tier dev privilege."
    }
  },
  "required": [
    "player_id"
  ],
  "additionalProperties": false
}

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, which 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).

{
  "type": "object",
  "properties": {
    "player_id": {
      "type": "string",
      "format": "uuid",
      "description": "Specific player to publish; omit to publish every player"
    }
  },
  "additionalProperties": false
}

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.
- Reconcile what playlists exist before creating a duplicate-by-mistake.

When NOT to use:
- For inspecting the items inside a playlist: call get_playlist with include_items.

What to know:
- Returns id, name, default_interval, image_uri, timestamps.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "playlist_id": {
      "type": "string",
      "format": "uuid"
    },
    "include_items": {
      "type": "boolean",
      "description": "Inline the playlist items in the response"
    }
  },
  "required": [
    "playlist_id"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1
    },
    "default_interval": {
      "type": "integer",
      "minimum": 1,
      "description": "Default item duration in seconds"
    },
    "image_uri": {
      "type": [
        "string",
        "null"
      ],
      "description": "Cover image URL"
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "playlist_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "default_interval": {
      "type": "integer",
      "minimum": 1
    },
    "image_uri": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "playlist_id"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "playlist_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "playlist_id"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "playlist_id": {
      "type": "string",
      "format": "uuid"
    },
    "type": {
      "type": "string",
      "enum": [
        "image",
        "video",
        "image_slideshow",
        "youtube"
      ]
    },
    "name": {
      "type": [
        "string",
        "null"
      ]
    },
    "duration_seconds": {
      "type": "integer",
      "minimum": 0
    },
    "is_selected": {
      "type": "boolean"
    },
    "schedule_start": {
      "type": [
        "string",
        "null"
      ],
      "description": "HH:MM or HH:MM:SS"
    },
    "schedule_end": {
      "type": [
        "string",
        "null"
      ],
      "description": "HH:MM or HH:MM:SS"
    },
    "asset_id": {
      "type": "string",
      "format": "uuid",
      "description": "For image/video items"
    },
    "external_url": {
      "type": "string",
      "format": "uri",
      "description": "For youtube items"
    },
    "config": {
      "type": "object",
      "description": "For image_slideshow items",
      "properties": {
        "asset_ids": {
          "type": "array",
          "items": {
            "type": "string",
            "format": "uuid"
          },
          "minItems": 1
        },
        "image_duration": {
          "type": "integer",
          "minimum": 1
        },
        "transition_speed": {
          "type": "integer",
          "minimum": 0
        },
        "fit": {
          "type": "string",
          "enum": [
            "contain",
            "cover"
          ]
        },
        "bg_color": {
          "type": "string"
        },
        "randomize": {
          "type": "boolean"
        }
      }
    }
  },
  "required": [
    "playlist_id",
    "type"
  ],
  "additionalProperties": false
}

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.

{
  "type": "object",
  "properties": {
    "playlist_id": {
      "type": "string",
      "format": "uuid"
    },
    "item_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": [
        "string",
        "null"
      ]
    },
    "duration_seconds": {
      "type": "integer",
      "minimum": 0
    },
    "is_selected": {
      "type": "boolean"
    },
    "schedule_start": {
      "type": [
        "string",
        "null"
      ]
    },
    "schedule_end": {
      "type": [
        "string",
        "null"
      ]
    },
    "asset_id": {
      "type": "string",
      "format": "uuid"
    },
    "external_url": {
      "type": "string",
      "format": "uri"
    },
    "config": {
      "type": "object"
    }
  },
  "required": [
    "playlist_id",
    "item_id"
  ],
  "additionalProperties": false
}

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).

{
  "type": "object",
  "properties": {
    "playlist_id": {
      "type": "string",
      "format": "uuid"
    },
    "item_id": {
      "type": "string",
      "format": "uuid"
    }
  },
  "required": [
    "playlist_id",
    "item_id"
  ],
  "additionalProperties": false
}

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. The 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.

{
  "type": "object",
  "properties": {
    "playlist_id": {
      "type": "string",
      "format": "uuid"
    },
    "item_ids": {
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid"
      },
      "minItems": 1,
      "description": "All current item ids of the playlist, in the desired final order"
    }
  },
  "required": [
    "playlist_id",
    "item_ids"
  ],
  "additionalProperties": false
}