Skip to content

cache

cache

MCP tool wrappers for Houdini cache management operations.

Each tool delegates to the corresponding handler running inside Houdini via the HTTP bridge.

Functions:

Name Description
clear_cache

Delete cached files on disk for a cache node.
get_cache_status

Frames on disk for a cache node, against the range it is set to write.
list_caches

List all cache-type nodes under a root path.
write_cache

Execute a cache node, and report whether a cache actually appeared.

Functions:

clear_cache async 

clear_cache(
    ctx: Context, node_path: str, frame_range: list[int] | None = None
) -> dict

Delete cached files on disk for a cache node.

Parameters:

Name Type Description Default
ctx
Context

MCP context.

 required
node_path
str

Path to the cache node.

 required
frame_range
list[int] | None

[start, end] frame range to limit deletion.

 None

get_cache_status async 

get_cache_status(ctx: Context, node_path: str) -> dict

Frames on disk for a cache node, against the range it is set to write.

This is what to poll after a background write_cache: complete is true when every frame of expected_range is on disk, missing_frames lists the rest, writing is true while files are still arriving, and hint tells you when the finished cache is not yet loaded from disk. Never wait for a cache with a shell loop; call this between other work.

Parameters:

Name Type Description Default
ctx
Context

MCP context.

 required
node_path
str

Path to the cache node.

 required

list_caches async 

list_caches(ctx: Context, root_path: str = '/') -> dict

List all cache-type nodes under a root path.

Parameters:

Name Type Description Default
ctx
Context

MCP context.

 required
root_path
str

Root path to search from.

 '/'

write_cache async 

write_cache(
    ctx: Context,
    node_path: str,
    frame_range: list[int] | None = None,
    background: bool = False,
) -> dict

Execute a cache node, and report whether a cache actually appeared.

Foreground by default: Houdini shows its own progress dialog and the user can cancel. The call holds until the write finishes, however long that is; a client that hands a long call to a background task notifies you with the verdict when it lands. Do nothing else in Houdini meanwhile (every other call queues behind the write) and never poll the disk.

success and wrote_files reflect the files on disk and the errors of the node that did the writing -- a filecache delegates to an internal ROP and stays silent itself, so a failed write used to be reported as success. Errors are named with the node they came from.

Parameters:

Name Type Description Default
ctx
Context

MCP context.

 required
node_path
str

Path to the cache node.

 required
frame_range
list[int] | None

[start, end] frame range to render. Overrides the node's $FSTART/$FEND expressions for this and later writes.

 None
background
bool

Save from a separate Houdini process (File Cache's own "Save to Disk in Background") so Houdini stays usable, at the cost of the user seeing no progress there. Saves the hip first, returns at once with status "launched"; follow it with get_cache_status. Use it only when asked to keep working while a cache writes. A verified foreground write turns the node's Load from Disk on.

 False