# MCP and assistant tools

> The 24 tools agents use to read and edit a comp.

Oink runs an MCP server inside the app, so AI agents (Claude Code, Codex, Cursor...) and the built-in Assistant panel can read and edit the open comp. **read** tools never change the comp; **edit** tools ask for your approval in the app and each call is one undo step.

Connection details (port, config file) are in [MCP and the assistant](/docs/developers/mcp).

| Tool | Kind | What it does |
|---|---|---|
| [`get_graph`](#get_graph) | read | The node graph: every node (name, type, disabled, inputs and what feeds them, knobs changed from their defaults), the pipes, frame range and current frame. |
| [`inspect_node`](#inspect_node) | read | Everything about one node: all knob values, inputs / outputs and connections, animation curves and expressions (with their errors), recent evaluation errors. |
| [`list_node_types`](#list_node_types) | read | Creatable node types. |
| [`render_frame`](#render_frame) | read | Render a node's image at a frame and return a small preview PNG (display-referred, sRGB view) plus its format, bbox, layers and per-channel stats of the full-resolution float pixels. |
| [`pixel_stats`](#pixel_stats) | read | Per-channel min / max / mean and NaN / inf counts of a node's float pixels at a frame, optionally inside region [x, y, r, t] (Nuke pixels, y up), plus the pixel value at `point` [x, y]. |
| [`recent_errors`](#recent_errors) | read | Recent evaluation errors and warnings (node failures, missing files, expression errors). |
| [`export_nk`](#export_nk) | read | Nuke script (.nk) text of the whole comp, or of the named nodes (clipboard form). |
| [`search_docs`](#search_docs) | read | Search the user documentation (node reference, knobs, shortcuts, guides) of the installed version. |
| [`get_doc`](#get_doc) | read | One documentation page as Markdown. |
| [`shot_report`](#shot_report) | read | Prep Show report (render.sh --prep-show ... |
| [`undo_history`](#undo_history) | read | Undo / redo history (names of the steps, newest last). |
| [`set_frame`](#set_frame) | read | Move the current frame (the viewer and timeline follow). |
| [`create_node`](#create_node) | edit | Create a node. |
| [`delete_node`](#delete_node) | edit | Delete a node (its pipes go with it). |
| [`connect`](#connect) | edit | Connect `from_node`'s output to `to_node`'s input (`input` = name or index; default the first free input). |
| [`disconnect`](#disconnect) | edit | Disconnect an input of a node (`input` name or index, default all inputs). |
| [`set_knobs`](#set_knobs) | edit | Set knob values on a node: {knob: value}. |
| [`set_key`](#set_key) | edit | Set an animation key on a knob at a frame (value: number, or list for all channels; `index` = one channel). |
| [`set_expression`](#set_expression) | edit | Set (or remove with '') a Nuke-style expression on a knob, e.g. |
| [`render_write`](#render_write) | edit | Render Write node(s) to disk over frames [first, last] (default: every enabled Write, the comp's frame range). |
| [`import_nk`](#import_nk) | edit | Import a Nuke script (.nk file path or script text). |
| [`undo`](#undo) | edit | Undo the last change (Edit > Undo). |
| [`redo`](#redo) | edit | Redo (Edit > Redo). |
| [`apply_changes`](#apply_changes) | edit | Apply several edits as ONE step (one approval, one undo): ops = [{tool, args}] with tool one of create_node, delete_node, connect, disconnect, set_knobs, set_key, set_expression. |

## get_graph

The node graph: every node (name, type, disabled, inputs and what feeds them, knobs changed from their defaults), the pipes, frame range and current frame. A very large comp comes back in pages: if `next_offset` is present call again with offset=next_offset (`total` = node count).

| Argument | Type | Required | Description |
|---|---|---|---|
| `offset` | integer |  | first node to return (default 0) |
| `limit` | integer |  | max nodes to return (default: as many as fit in ~40k characters) |

## inspect_node

Everything about one node: all knob values, inputs / outputs and connections, animation curves and expressions (with their errors), recent evaluation errors.

| Argument | Type | Required | Description |
|---|---|---|---|
| `node` | string | yes |  |

## list_node_types

Creatable node types. With `type`: that type's knobs (name, type, default, range, enum items).

| Argument | Type | Required | Description |
|---|---|---|---|
| `query` | string |  | filter by name/category |
| `type` | string |  | node type (e.g. Blur or OC_N_blur) to list knobs of |

## render_frame

Render a node's image at a frame and return a small preview PNG (display-referred, sRGB view) plus its format, bbox, layers and per-channel stats of the full-resolution float pixels.

| Argument | Type | Required | Description |
|---|---|---|---|
| `node` | string | yes |  |
| `frame` | number |  |  |
| `max_size` | integer |  |  |
| `layer` | string |  |  |

## pixel_stats

Per-channel min / max / mean and NaN / inf counts of a node's float pixels at a frame, optionally inside region [x, y, r, t] (Nuke pixels, y up), plus the pixel value at `point` [x, y].

| Argument | Type | Required | Description |
|---|---|---|---|
| `node` | string | yes |  |
| `frame` | number |  |  |
| `layer` | string |  |  |
| `region` | array |  |  |
| `point` | array |  |  |

## recent_errors

Recent evaluation errors and warnings (node failures, missing files, expression errors).

| Argument | Type | Required | Description |
|---|---|---|---|
| `node` | string |  | only messages mentioning this node |

## export_nk

Nuke script (.nk) text of the whole comp, or of the named nodes (clipboard form).

| Argument | Type | Required | Description |
|---|---|---|---|
| `nodes` | array |  |  |

## search_docs

Search the user documentation (node reference, knobs, shortcuts, guides) of the installed version. Returns matching pages [{path, title, snippet}]; read one with get_doc.

| Argument | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | words to look for, e.g. 'grade gain' or 'roto feather' |
| `limit` | integer |  | max results (default 8) |

## get_doc

One documentation page as Markdown. `path` as returned by search_docs ('nodes/grade', '/docs/nodes/grade' or just a node name like 'grade').

| Argument | Type | Required | Description |
|---|---|---|---|
| `path` | string | yes |  |

## shot_report

Prep Show report (render.sh --prep-show ... --out DIR): without `shot`, the show summary (shots with one-line findings, clusters with their key shots, hardest shots, people across the show); with `shot`, that shot's report: hidden cuts, bad frames, grain, camera move, people, faces, markers, lens estimate, exposure, motion blur, focus, and the proposed prep nodes (proposals, never applied).

| Argument | Type | Required | Description |
|---|---|---|---|
| `folder` | string | yes | the Prep Show output folder (holds prep_show.json) |
| `shot` | string |  |  |

## undo_history

Undo / redo history (names of the steps, newest last).

No arguments.

## set_frame

Move the current frame (the viewer and timeline follow). Does not change the comp.

| Argument | Type | Required | Description |
|---|---|---|---|
| `frame` | integer | yes |  |

## create_node

Create a node. `type`: node type or class name (Blur, Grade, Merge, Read, Viewer, OC_N_blur...). `inputs`: node names in input order (or {input name: node}). `knobs`: {knob: value} (names from list_node_types(type=...)). Placed under its first input unless x/y given. Returns the node's name.

| Argument | Type | Required | Description |
|---|---|---|---|
| `type` | string | yes |  |
| `name` | string |  |  |
| `inputs` | array or object |  |  |
| `knobs` | object |  |  |
| `x` | number |  |  |
| `y` | number |  |  |

## delete_node

Delete a node (its pipes go with it).

| Argument | Type | Required | Description |
|---|---|---|---|
| `node` | string | yes |  |

## connect

Connect `from_node`'s output to `to_node`'s input (`input` = name or index; default the first free input). Replaces what was connected there.

| Argument | Type | Required | Description |
|---|---|---|---|
| `from_node` | string | yes |  |
| `to_node` | string | yes |  |
| `input` | string,integer |  |  |
| `output` | string,integer |  |  |

## disconnect

Disconnect an input of a node (`input` name or index, default all inputs).

| Argument | Type | Required | Description |
|---|---|---|---|
| `node` | string | yes |  |
| `input` | string,integer |  |  |

## set_knobs

Set knob values on a node: {knob: value}. Colours / vectors take a list or one number (broadcast); enums take the item name; 'disable' via knob 'mute'; 'name' renames.

| Argument | Type | Required | Description |
|---|---|---|---|
| `node` | string | yes |  |
| `knobs` | object | yes |  |

## set_key

Set an animation key on a knob at a frame (value: number, or list for all channels; `index` = one channel).

| Argument | Type | Required | Description |
|---|---|---|---|
| `node` | string | yes |  |
| `knob` | string | yes |  |
| `frame` | number | yes |  |
| `value` |  | yes |  |
| `index` | integer |  |  |
| `interp` | string |  |  |

## set_expression

Set (or remove with '') a Nuke-style expression on a knob, e.g. 'frame/10', 'Blur1.size * 2', 'sin(frame)'; `index` = one channel.

| Argument | Type | Required | Description |
|---|---|---|---|
| `node` | string | yes |  |
| `knob` | string | yes |  |
| `expr` | string | yes |  |
| `index` | integer |  |  |

## render_write

Render Write node(s) to disk over frames [first, last] (default: every enabled Write, the comp's frame range). Returns the files written.

| Argument | Type | Required | Description |
|---|---|---|---|
| `write_node` | string |  |  |
| `frames` | array |  |  |

## import_nk

Import a Nuke script (.nk file path or script text). Adds the nodes to the comp (replace=true replaces the whole comp).

| Argument | Type | Required | Description |
|---|---|---|---|
| `path` | string |  |  |
| `text` | string |  |  |
| `replace` | boolean |  |  |

## undo

Undo the last change (Edit > Undo).

No arguments.

## redo

Redo (Edit > Redo).

No arguments.

## apply_changes

Apply several edits as ONE step (one approval, one undo): ops = [{tool, args}] with tool one of create_node, delete_node, connect, disconnect, set_knobs, set_key, set_expression. All or nothing: a failing op takes the earlier ones back.

| Argument | Type | Required | Description |
|---|---|---|---|
| `ops` | array | yes |  |
| `summary` | string |  |  |


---
Sources: opencomp_server/mcp_tools.py, opencomp_server/mcp_server.py