/p4-dam-workflows

name: p4-dam-workflows
description: P4 DAM (Digital Asset Management) workflows — search, browse, tag, review, and manage digital assets via P4 MCP tools. Use when discovering, searching, filtering, reviewing, or managing assets stored in P4 DAM.

P4 DAM Workflows

Prerequisites

• The P4 server must have the `P4.HTH.URL` property set (points at the P4 DAM instance).
• The server must be started with a P4 DAM API key via the `P4DAM_API_KEY` environment variable. Without a key, P4 DAM tools are not registered at all — a warning is logged at startup.
• Write tools (create, update, delete, sync) require the server to be started without `--readonly`.

Tool Reference

Discovery & Navigation

| Tool | Purpose | |------|---------| | `query_p4dam_projects` | List projects. Accepts `search_term` (matches name, short name, or description). | | `query_p4dam_repositories` | List repositories in a project. Accepts `search_term` (matches short name). | | `query_p4dam_helix_classic_branches` | List Helix Classic branches in a helix_classic repository. |

Asset Search

| Tool | Purpose | |------|---------| | `query_p4dam_assets` | Search assets by keyword/filters — use when you don't have a depot path yet. | | `query_p4dam_asset` | Fetch full metadata for a single known asset by depot path. | | `fetch_p4dam_media` | Fetch and render a thumbnail, preview, or file image. | | `regenerate_p4dam_preview` | Trigger async regeneration of thumbnail and preview for an asset revision. |

**`query_p4dam_assets` filters:** `search_term`, `project_ids` (UUIDs), `repository_ids` (UUIDs), `path` (wildcard depot path patterns, e.g. `//depot/art/*.png`), `name` (filename wildcard), `tag`, `file_extension`, `exclude_file_extension`, `user`, `from_size` / `to_size` (bytes), `from_date` / `to_date` (ISO 8601), `all_revisions`, `max_results`, `offset`.

**`query_p4dam_asset` params:** `depot_path` (required), `identifier` (changeset), `project_id` (short name or UUID), `repository_id` (UUID, or short name if `project_id` is also provided), `include`.

**`query_p4dam_asset` include values:**

• Default set: `commit`, `latest_commit`, `custom_attributes`, `weblinks`, `asset_bundle`, `asset_bundle_origin`, `parent_asset_bundles`, `helix_classic_branch_matches`, `stream_view_matches`, `sprite`
• Require project/repository/stream or branch context: `file_review`, `comments`, `all_comments`
• Extras: `file_count`, `scene_refs`

**`fetch_p4dam_media`:** Pass `thumbnail_url`, `preview_url`, `sprite_url`, or `file_url` from search/asset results. `thumbnail_url`, `preview_url`, and `sprite_url` are only present for image files (nil for non-image assets). Returns the image directly for visual display.

**`regenerate_p4dam_preview`:** Trigger P4Search to regenerate the thumbnail and preview for a specific asset revision. Params: `depot_path` (required), `commit_id` (changeset number, required). Returns `accepted` immediately — regeneration is async. Requires `P4.P4Search.URL` and `P4.P4Search.AUTH_TOKEN` on the P4 server.

Asset Bundles

| Tool | Purpose | |------|---------| | `create_p4dam_asset_bundle` | Create a named collection of depot files scoped for review. | | `update_p4dam_asset_bundle` | Update description, view_paths, or hero_file_path. | | `delete_p4dam_asset_bundle` | Delete an asset bundle (prompts for confirmation). | | `sync_p4dam_asset_bundle` | Sync bundle's depot files to local P4CLIENT workspace. |

**Create flow:** `query_p4dam_projects` → `query_p4dam_repositories` → (if helix_classic: `query_p4dam_helix_classic_branches`) → `create_p4dam_asset_bundle`.

File Reviews

| Tool | Purpose | |------|---------| | `query_p4dam_file_reviews` | List file reviews in a project. Filter by `depot_path`. | | `query_p4dam_file_review` | Fetch single review with full detail including `download_url`. | | `create_p4dam_file_review` | Create a file review (single-file or asset bundle). | | `update_p4dam_file_review` | Update state, name, view_paths, description, position. | | `delete_p4dam_file_review` | Delete a review (prompts for confirmation). |

**`query_p4dam_file_reviews` include:** `weblinks`.

Workflows

| Tool | Purpose | |------|---------| | `query_p4dam_workflows` | List workflows. `include` accepts `states`, `transition_rules`, `projects`. | | `query_p4dam_workflow` | Fetch a single workflow by short name or UUID. | | `query_p4dam_workflow_states` | List states for a workflow (name, short_name, kind, color, position). |

State kinds: `open` (initial), `review` (under review), `done` (terminal).

Comments

| Tool | Purpose | |------|---------| | `create_p4dam_comment` | Post a comment on a file review, a file within a review, a committed file, or as a reply. |

**`create_p4dam_comment` types and required fields:**

| `type` | Required | Use case | |--------|----------|----------| | `file_review` | `project`, `repository`, `file_review` | Comment on an asset bundle file review | | `file_review_file` | `project`, `repository`, `file_review`, `path` | Comment on a specific file inside a file review | | `commit_file` | `project`, `repository`, `commit`, `path` | Comment on a committed file or asset bundle without a review | | `comment` | `comment` | Reply to an existing comment |

`path` is a relative path within the repository (e.g. `renders/hero.png`), not a full depot path. For `commit_file` on helix_stream repos: also pass `stream_path`. For helix_classic: also pass `helix_classic_branch`.

Custom Attributes

| Tool | Purpose | |------|---------| | `query_p4dam_custom_attribute_templates` | List available custom attribute templates for a project (name, type, allowed values). | | `update_p4dam_asset_custom_attributes` | Set or remove custom attribute values on one or more assets. |

**Flow:** `query_p4dam_custom_attribute_templates(project_id=...)` → pick template UUID → `update_p4dam_asset_custom_attributes(paths=[...], create=[{uuid, value}])`.

**Attribute types:** `text` (an