/mediaserver-operation

name: mediaserver-operation
version: 3
description: >-
  Use this skill when the user asks to inspect, diagnose, or directly operate a
  configured Emby, Jellyfin, Plex, ZSpace, UGREEN, TrimeMedia, or Navidrome
  server. It discovers provider capabilities on demand and supports libraries,
  native movie/music search, episode coverage, recent media, resume state,
  playback sessions, statistics, scans, metadata refreshes, and provider play
  URLs without adding permanent tools.
allowed-tools: execute_command

Media Server Operation

Use `scripts/mp-mediaserver.py`. The helper reads MoviePilot's local server configuration and credentials itself. Never request, print, or pass a host, username, password, API key, token, Cookie, or arbitrary URL.

Run the bundled copy from the MoviePilot program directory with its project runtime, for example:

cd <MOVIEPILOT_ROOT>
python skills/mediaserver-operation/scripts/mp-mediaserver.py instances

The Agent command environment routes `python` to the project-specific `moviepilot-python` entry when available and falls back to the project or Docker `VENV_PATH` Python otherwise. Media-server connections may depend on macOS local-network permissions, so use the provided `python` command for every operation.

The runtime sets `MOVIEPILOT_ROOT` for copied skills. If you run a copied script directly from `<CONFIG_PATH>/agent/skills/`, set that variable to the program directory first; otherwise the helper returns a clear relocation error. Do not use a system `python3` when it does not meet MoviePilot's required Python version.

Boundary

• Keep `library.exists` in `moviepilot-api` for canonical duplicate checks. It

aggregates configured servers and applies MoviePilot media identity and music matching rules.

• Use this Skill for server-native exploration, diagnostics, playback state,

library browsing, scans, and metadata refreshes.

• A provider result is not automatically a MoviePilot transfer, subscription,

or history fact. Use the appropriate MoviePilot API for those workflows.

Instance And Provider Discovery

Fast path: call directly

Do not routinely call `instances` or `capabilities` before an operation. This Skill already contains the full action contract, and the helper performs instance resolution, provider support checks, complete argument validation, and the action in one `call` invocation.

• If the user or prior context provides the exact server name, pass it with

`--server` and call the action immediately.

• If no server name is known, omit `--server`. The helper automatically uses the

only enabled media server.

• If multiple servers remain ambiguous, the failed call lists every valid

server name. Reuse that list for the next direct call; do not add a separate `instances` call unless the user explicitly asks to inspect instances.

• Do not probe an action with empty or guessed arguments. Compose the complete

JSON object from the contract below before calling.

The helper rejects unknown fields and reports all detectable argument errors in one response before connecting to the provider, so correct every reported field together instead of retrying one field at a time.

Optional discovery

python skills/mediaserver-operation/scripts/mp-mediaserver.py instances
python skills/mediaserver-operation/scripts/mp-mediaserver.py capabilities
python skills/mediaserver-operation/scripts/mp-mediaserver.py capabilities --server "living-room"

The complete action and argument contract is documented below. Use `capabilities` only to confirm which documented actions a configured provider supports. For a compact machine-readable copy of one action's same contract:

python skills/mediaserver-operation/scripts/mp-mediaserver.py capabilities \
  --server "living-room" \
  --action items.season_episodes

Do not inspect the helper source to discover arguments and do not guess a provider-specific action. `capabilities` is optional and should be used only when the configured provider itself is unknown or support must be diagnosed.

Call Shape

python skills/mediaserver-operation/scripts/mp-mediaserver.py call \
  --server "living-room" \
  --action activity.latest \
  --arguments '{"limit":20}'

The `--arguments` value must be one JSON object. List reads default to 50 items and cap at 200.

External MCP Contract

External MCP clients do not receive this `SKILL.md` and cannot use the hidden `execute_command` tool. MoviePilot therefore exposes a separate admin-only MCP tool named `mediaserver_operation`. Its `tools/list` `inputSchema` contains one `oneOf` branch for every action below, including the function description, supported providers, effect, field types, required/default values, enums, nested `metadata.refresh` item fields, and cross-field rules. The external client should select the matching branch and make one `tools/call`; it does not need to call a discovery tool first.

The default schema mode is `full`. Clients explicitly sending `X-MCP-Schema-Mode: compact` receive a best-effort projection for oversized schemas, without action-specific branches. Use this contract or the full `GET /api/v1/mcp/tools/{tool_name}/schema` response for exact arguments; call-time validation and authorization are unchanged.

MCP call arguments use the same contract without shell quoting:

{
  "server": "living-room",
  "action": "items.season_episodes",
  "arguments": {
    "item_id": "exact-series-id",
    "season": 2
  }
}

`server` may be omitted when only one media server is enabled. If multiple instances remain ambiguous, the result lists the valid server names.

Complete Action Contract

This is the complete Media Server Operation action contract. It comes directly from the script `ACTIONS` registry and matches the external MCP `tools/list` oneOf branches. A field name ending in `*` is required. Put every action parameter in the `arguments` object.

| action | Purpose and