> ## Documentation Index
> Fetch the complete documentation index at: https://opencanvas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# DesignJS MCP Tools Overview

> Reference for the 20+ DesignJS MCP tools across inspect, component mutation, artboards, variables, and selection — that let AI agents inspect and edit your live HTML/CSS canvas over stdio.

DesignJS exposes a bidirectional Model Context Protocol (MCP) server that AI coding agents — Claude Code, Cursor, Codex, and any MCP-compatible client — connect to over stdio using JSON-RPC 2.0. Each tool call travels from your agent through the MCP server, across a local WebSocket bridge on `127.0.0.1:29170`, and into the live GrapesJS canvas running in your browser. Responses follow the same path in reverse, arriving as JSON wrapped in MCP text content blocks.

## How agents call tools

Every tool call is a standard MCP `tools/call` request. The `arguments` object maps directly to the tool's input schema. Results are returned as a single `text` content block containing a JSON string — parse it to get the typed response object.

```json tool call example theme={null}
{
  "method": "tools/call",
  "params": {
    "name": "get_html",
    "arguments": {
      "componentId": "comp-abc123"
    }
  }
}
```

```json tool result theme={null}
{
  "content": [
    {
      "type": "text",
      "text": "{\"html\": \"<div class=\\\"p-4 text-gray-900\\\">Hello</div>\"}"
    }
  ]
}
```

<Note>
  All tool results are JSON-encoded strings inside the `text` content block. Your agent must parse the `text` field to access the structured response.
</Note>

## Transport

DesignJS uses the **stdio transport** defined by the MCP specification. The MCP server process (`@designjs/mcp-server`) is launched by your IDE or agent runner as a child process. Communication happens over the process's stdin and stdout streams — no HTTP port is exposed by the MCP server itself (the WebSocket bridge on port 29170 is internal).

## All 20+ tools

| Tool                                      | Category | Description                                                                                |
| ----------------------------------------- | -------- | ------------------------------------------------------------------------------------------ |
| [`ping`](/mcp/ping)                       | Read     | Health check — confirms the canvas is connected and returns a server timestamp             |
| [`get_tree`](/mcp/get-tree)               | Read     | Returns the full component tree as recursive JSON, optionally limited by depth or artboard |
| [`get_html`](/mcp/get-html)               | Read     | Exports clean HTML for the entire canvas or a specific component subtree                   |
| [`get_css`](/mcp/get-css)                 | Read     | Exports the CSS stylesheet for the entire canvas or a scoped component                     |
| [`get_screenshot`](/mcp/get-screenshot)   | Read     | Captures the canvas as a base64-encoded PNG or JPEG data URL                               |
| [`get_selection`](/mcp/get-selection)     | Read     | Returns the component IDs of whatever is currently selected in the editor                  |
| [`get_jsx`](/mcp/get-jsx)                 | Read     | Converts canvas HTML to a JSX string using Tailwind class names or inline styles           |
| [`get_variables`](/mcp/get-variables)     | Read     | Reads all CSS custom properties (`--var: value`) from the canvas `:root`                   |
| [`add_components`](/mcp/add-components)   | Write    | Inserts raw HTML onto the canvas and returns the new component IDs                         |
| [`update_styles`](/mcp/update-styles)     | Write    | Sets CSS properties on an existing component by ID                                         |
| [`delete_nodes`](/mcp/delete-nodes)       | Write    | Removes one or more components and their children from the canvas                          |
| [`set_variables`](/mcp/set-variables)     | Write    | Writes CSS custom properties to the canvas `:root`, persisted to `.designjs.json`          |
| [`create_artboard`](/mcp/create-artboard) | Write    | Creates a new named artboard (frame) at a given position and size                          |
| [`list_artboards`](/mcp/list-artboards)   | Read     | Returns all artboards with their IDs, names, positions, and dimensions                     |
| [`find_placement`](/mcp/find-placement)   | Read     | Suggests a non-overlapping canvas position for a new artboard of the given size            |

## Tool categories

**Read tools** only observe the canvas state — they are safe to call at any time and produce no side effects. Use them to gather context before deciding what to change.

**Write tools** mutate the canvas. Changes are reflected in the editor immediately and are persisted to `.designjs.json` (Cmd+S or 30-second autosave). All write operations are reversible through the editor's undo history.

## Data types

Two shared types appear across multiple tools.

**`ComponentNode`** — the recursive node returned by `get_tree`:

| Field         | Type                     | Description                              |
| ------------- | ------------------------ | ---------------------------------------- |
| `id`          | `string`                 | Unique component identifier              |
| `type`        | `string`                 | GrapesJS component type                  |
| `tagName`     | `string?`                | HTML tag name (e.g. `"div"`, `"button"`) |
| `classes`     | `string[]`               | Applied CSS class names                  |
| `attributes`  | `Record<string, string>` | HTML attributes                          |
| `textContent` | `string?`                | Text content of the node                 |
| `children`    | `ComponentNode[]`        | Nested child nodes                       |

**`ArtboardData`** — returned by `create_artboard` and `list_artboards`:

| Field    | Type     | Description                       |
| -------- | -------- | --------------------------------- |
| `id`     | `string` | Unique artboard identifier        |
| `name`   | `string` | Display name                      |
| `x`      | `number` | Canvas X coordinate (world space) |
| `y`      | `number` | Canvas Y coordinate (world space) |
| `width`  | `number` | Width in pixels                   |
| `height` | `number` | Height in pixels                  |