The MCP tool reference
The tools that Clate's MCP server offers to AI tools. Use this page when you connect your own tool or want to know exactly what the assistant can do.
Clate's MCP server is called Clate MCP Server. It talks JSON-RPC over HTTP and offers the nine tools below. Every tool needs an open project and fails with the message No project is open. Ask the user to open a project first. otherwise.
Overview
| Tool | Title | Kind | Purpose |
|---|---|---|---|
get_pages | List pages | Read | The pages of the project with their top-level nodes. Call it first. |
get_node | Read node subtree | Read | A node and everything below it, with the settings that are set. |
create_page | Create page | Adds | Creates a new page. |
get_active_page | Read active page | Read | The page that new objects are added to. |
get_selection | Read canvas selection | Read | The nodes selected on the canvas. |
apply_changes | Apply model changes | Changes | Applies a list of changes in one step. |
get_instance_image | Read rendered image | Read | A picture of what an object looks like. |
list_assets | List assets | Read | The image assets of the project. |
get_asset_image | Read asset image | Read | A picture of an image asset. |
get_pages
Returns the pages and the top-level nodes of each page. No parameters.
The result has a list pages. Each page has an id, a name, and rootNodeIds, the top-level nodes of the
page. Use the page id as the parent when you create objects.
get_node
Returns a node and its subtree with the settings that are set.
| Parameter | Description |
|---|---|
nodeId | The node to read. Use a root node from get_pages, or a node id from an earlier result. |
maxDepth | Optional. How many levels to return: 1 is the node alone, 2 adds its children, and 0 returns everything. The default is 4. |
Each node has an id, a displayName, a typeName such as QtQuick.Text, a kind (object, frame or
page), its properties and its children. Nodes whose children were cut off by maxDepth are marked with
truncated: true.
Values are plain: booleans, numbers, and strings. Colors are strings in the form #aarrggbb. A setting that
refers to an asset has the form { "asset": id }, and a setting that holds a gradient has the form
{ "nodeId": id }. Read the gradient with another get_node call.
create_page
Creates a page. The parameter displayName is the name of the page. The result is the new pageId. Creating a
page whose name already exists fails.
get_active_page
Returns the pageId and displayName of the active page. The pageId is missing when no page is active.
get_selection
Returns nodeIds, the nodes that are selected on the canvas. Use it to find out what the user means by "this".
apply_changes
Applies a list of changes as one step. If any change fails, Clate applies none of them. The parameter changes
is a list. Each change has an op that names the operation.
| Operation | What it does |
|---|---|
create_object | Creates an object, with its settings and children, under a page or a frame. |
create_object_before | Creates an object directly before an existing sibling. |
create_property_object | Creates an object that fills a setting of another object, such as a gradient. |
remove_node | Removes a node with everything below it. |
set_property | Sets a setting of an object. |
remove_property | Resets a setting to its default. |
reparent_node | Moves a node into another frame or page. |
move_node_before | Moves a node directly before a sibling. |
set_display_name | Renames a node. |
change_to_frame | Turns an object into a frame. |
add_asset | Adds an image asset, from base64 data or a file path. |
update_asset | Replaces the content of an asset. |
remove_asset | Removes an asset that is not in use. |
set_asset_display_name | Renames an asset. |
The result has created, the new node ids of the objects created at the top level, and assets, the new asset
ids.
Types an AI can create
QtQuick.Shapes.DesignHelpers.RectangleShape (also used for frames), EllipseShape, RegularPolygonShape and
StarShape, QtQuick.Text, QtQuick.Image, and for fills the gradients QtQuick.Shapes.LinearGradient,
RadialGradient and ConicalGradient with QtQuick.GradientStop children. A type name always has the module
in front of it. Clate rejects other types.
A plain object cannot contain other objects. To create an object with children, set kind to frame.
Settings an AI can change
See What an AI can do for the list of settings.
Errors
When a change fails, the tool returns an error that names the change, for example Change 2 of 3 ('set_property') failed: .... Clate applies nothing in that case.
get_instance_image
Returns a picture of what an object looks like, with everything inside it, cropped to the bounds of the object.
The parameter nodeId is the object. The picture is attached as a PNG that is at most 1024 pixels on its longest
edge. The result also has hasImage, width, and height.
The picture is a way to check a result, not a way to measure. Read positions and sizes with get_node. After a
change, the picture can still show the old state for a moment.
list_assets
Lists the assets of the project.
| Parameter | Description |
|---|---|
mimeType | The kind of asset, for example image. |
mimeSubtype | Optional. For example png. |
nameFilter | Optional. Text to look for in the name, ignoring upper and lower case. |
Each asset in the result has an assetId, a displayName, a mimeType, and a mimeSubtype.
get_asset_image
Returns a picture of an image asset. The parameter assetId is the asset. The picture is attached as a PNG that
is at most 1024 pixels on its longest edge.