Target files, folders, and elements

The safest agent task points to a current Misaki Studio target instead of asking the agent to guess from a label. Use a copied MCP reference from the editor, or let the agent discover current UUIDs and node IDs with read tools.

The three target levels

• Target: Project · Example identity: project ID returned by list-projects · Best discovery route: list-projects, then select-project

• Target: File or folder · Example identity: project-relative path plus current UUID · Best discovery route: File Explorer Copy Path For MCP or get-project-details

• Target: Element · Example identity: file path plus node ID · Best discovery route: element Path → Copy For MCP or get-file-tree

File UUIDs and element node IDs are not interchangeable. A project-relative path such as components/atoms/Button is also different from the element hierarchy inside that Component.

Copy a target from the editor

File or folder

In the Files panel, right-click the file or folder and choose Copy Path For MCP.

A file reference looks like:

Project(Website)→File(components/molecules/FeatureCard)

A folder reference looks like:

Project(Website)→Folder(components/molecules)

The folder form is intentionally different: file fields resolve to a file UUID, while supported folder-path fields resolve to a project-relative path.

Element

Select one element, open its context menu, then choose Path → Copy For MCP.

The result includes all three levels:

Project(Website)→File(components/molecules/FeatureCard)→Element(<node-id>)

Paste the complete reference into the prompt. Do not remove the project or file parts; they let the server validate scope and resolve the file before it uses the node.

Tell the agent to pass the reference through

The server resolves copied references when they are supplied as top-level tool arguments. For an element reference, the same string can be passed as the tool's fileUuid argument to resolve the file half and as nodeId to resolve the element half.

The agent should not parse the string itself or search the whole project merely to translate a reference that already names the target.

Example:

In the selected Website project, inspect Project(Website)→File(components/molecules/FeatureCard)→Element(<node-id>). Pass this reference through as the file and node target. Read its metadata and current style, then stop without changing anything.

Discover targets through MCP

Use current reads when a copied reference is unavailable:

1. get-project-details returns the full project file/folder tree with UUIDs.

2. list-design-files returns Pages, Components, and Mockups with their UUIDs and paths.

3. get-file-tree takes one design file UUID and returns that file's element hierarchy as [nodeId] TYPE "name" rows.

4. search-nodes narrows a large element hierarchy by name or content.

5. get-selection can report the canvas selection for a referenced design file; if it reports no selection or the task spans windows, use an explicit copied reference instead.

The name get-file-tree is easy to misread: it returns a visual design file's element tree, not the Project File Explorer tree. Use get-project-details for folders and files.

Reference validation and useful failures

The resolver checks the selected project and target category before the operation runs.

• A reference for another project is refused; select that project explicitly, then retry.

• A file reference whose path no longer exists is stale; read the tree or copy it again.

• A file-only reference cannot supply a node field.

• A folder reference is refused when a file field is required.

• A file reference is refused when a supported folder-path field requires a folder.

• An element ID is valid only inside its owning file and until that node is deleted or replaced.

References are resolved only in top-level string arguments and top-level string arrays. A reference buried inside nested style, logic, or arbitrary JSON is not rewritten automatically.

Folder-reference limitation

Copied folder references currently resolve in the explicitly supported path fields parentPath, folderPath, and path. Other parameters, including some destination-path fields, may still require the plain project-relative path shown by get-project-details.

Read the connected tool's current parameter description before passing a folder reference. Do not assume every argument containing the word “path” accepts the structured reference form.

Paths can become stale

File and folder references store the current project-relative path. Renaming or moving the target changes that path, so an older copied reference can stop resolving. Copy the reference again or use the UUID returned by a current read.

Within an existing file, a node ID is a better target than a display name because names can repeat. Re-read the element tree after a large replacement, paste, conversion, or deletion before reusing old node IDs.

Targeting is not authorization

A precise reference answers “where,” not “what may happen.” Keep the operation and safety boundary in the prompt:

In the Website project, update only <element reference>. Preserve its children, logic, timelines, and responsive overrides. Change the base background color to <value>, read the resolved style back, and show a preview. Do not export, publish, move, rename, duplicate, or delete any file.

UI and MCP relationship

Coverage: UI + MCP. The UI identifies targets through selection and hierarchy; MCP uses explicit project/file/node arguments. Explorer expansion, active tabs, and visible selection are navigation state and do not need to match for the stored project change to be equivalent.