MCP Tools Reference

The Design Bridge adds 7 MCP tools to the Prototyper UI server. All tools are available when the MCP server is running. If the bridge server is reachable, tools use the Yjs-backed bridge for real-time sync. Otherwise, they fall back to file-based sessions.

design_create

Create a new live design session. Returns a session ID and preview URL.

Parameters

Parameter	Type	Required	Description
`name`	`string`	Yes	Session name, e.g. `"Login Page"`
`spec`	`string`	No	JSON Compose spec string (`root` + `elements`)
`description`	`string`	No	Human description of the design
`theme`	`object`	No	Theme overrides (merged with defaults)

The theme object accepts:

Property	Type	Range	Description
`hue`	`number`	0-360	Primary color hue
`chroma`	`number`	0-0.4	Color saturation
`grayChroma`	`number`	0-0.03	Gray tint saturation
`radius`	`number`	0+	Border radius in px
`font`	`string`	--	Font family name

Example

{
  "name": "Signup Form",
  "description": "A registration form with name, email, and password",
  "theme": {
    "hue": 220,
    "radius": 8
  }
}

Response

{
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "previewUrl": "http://localhost:4321/?session=a1b2c3d4",
  "revision": 0,
  "source": "bridge"
}

design_update

Update the spec of an active design session. Accepts either a full replacement spec or RFC 6902 JSON Patch operations.

Parameters

Parameter	Type	Required	Description
`sessionId`	`string`	No	Session ID (falls back to active session)
`spec`	`string`	No	Full replacement spec as JSON string
`patches`	`string`	No	JSON Patch array (RFC 6902) as JSON string
`description`	`string`	No	Change description, e.g. `"Added submit button"`

Provide exactly one of spec or patches, not both.

Patches Format

Patches follow RFC 6902. Common operations:

Add an element:

[
  {
    "op": "add",
    "path": "/elements/submitBtn",
    "value": {
      "type": "Button",
      "props": { "children": "Submit", "className": "w-full" },
      "children": []
    }
  }
]

Change a prop:

[
  {
    "op": "replace",
    "path": "/elements/submitBtn/props/children",
    "value": "Sign Up"
  }
]

Remove an element:

[
  {
    "op": "remove",
    "path": "/elements/submitBtn"
  }
]

Reorder children:

[
  {
    "op": "replace",
    "path": "/elements/form/children",
    "value": ["nameField", "emailField", "passwordField", "submitBtn"]
  }
]

Spec Operations

When connected to the bridge server, patches are converted to granular SpecOp operations for optimal CRDT merging:

Operation	Description
`add_element`	Add a new element with parent
`remove_element`	Remove an element by key
`update_props`	Merge props into an element
`set_prop`	Set a single prop value
`remove_prop`	Remove a single prop
`reorder_children`	Set the children array
`set_root`	Change the root element key
`replace_spec`	Replace the entire spec

Response

{
  "revision": 3,
  "applied": 2,
  "errors": [],
  "source": "bridge"
}

design_theme

Update the theme of a design session. Accepts natural language descriptions, preset names, or explicit numeric parameters.

Parameters

Parameter	Type	Required	Description
`sessionId`	`string`	No	Session ID (falls back to active session)
`description`	`string`	No	Natural language, e.g. `"warm sunset colors with large rounded corners"`
`hue`	`number`	No	Primary hue (0-360)
`chroma`	`number`	No	Color saturation (0-0.4)
`grayChroma`	`number`	No	Gray tint saturation (0-0.03)
`radius`	`number`	No	Border radius in px
`font`	`string`	No	Font family name

When both description and explicit parameters are provided, explicit parameters take precedence.

Natural Language Examples

"dark blue professional" — parsed to hue ~220, moderate chroma
"warm sunset with rounded corners" — parsed to warm hues, large radius
"forest" — resolved from the forest preset
"midnight" — resolved from the midnight preset

Example

{
  "description": "clean minimal with Inter font",
  "radius": 6
}

Response

{
  "theme": {
    "hue": 240,
    "chroma": 0.12,
    "grayChroma": 0.005,
    "radius": 6,
    "font": "Inter"
  },
  "description": "Theme with hue 240, chroma 0.12, radius 6px, font \"Inter\"",
  "source": "bridge"
}

design_get

Get details about a design session at varying levels of detail.

Parameters

Parameter	Type	Required	Default	Description
`sessionId`	`string`	No	active	Session ID
`include`	`enum`	No	`"summary"`	Level of detail to return

The include parameter accepts:

Value	Returns
`summary`	ID, name, description, revision, element names, theme
`full`	Everything including full spec, theme CSS, history
`spec-only`	Just the spec
`theme-only`	Just the theme parameters and generated CSS

Example

{
  "include": "summary"
}

Response (summary)

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Login Page",
  "description": "A login form with email and password",
  "revision": 5,
  "componentCount": 8,
  "elementNames": ["container", "heading", "emailField", "passwordField", "submitBtn"],
  "theme": {
    "hue": 264,
    "chroma": 0.24,
    "grayChroma": 0.01,
    "radius": 0.625
  },
  "source": "bridge"
}

{
  "sessions": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Login Page",
      "revision": 5
    },
    {
      "id": "f9e8d7c6-b5a4-3210-fedc-ba9876543210",
      "name": "Dashboard",
      "revision": 12
    }
  ],
  "source": "bridge"
}

design_close

Close a design session. Optionally export the design before closing.

Parameters

Parameter	Type	Required	Default	Description
`sessionId`	`string`	No	active	Session ID
`exportFirst`	`boolean`	No	`false`	Export as React code before closing

Example

{
  "exportFirst": true
}

Response

{
  "closed": true,
  "exported": {
    "code": "import { Card, CardHeader, ... } from \"@/components/proto\";\n\nexport function LoginPage() { ... }",
    "themeCSS": ":root { --primary: ... }"
  },
  "source": "bridge"
}

When exportFirst is false, the exported field is omitted.

design_export

Export a design session as a React component with optional theme CSS.

Parameters

Parameter	Type	Required	Default	Description
`sessionId`	`string`	No	active	Session ID
`componentName`	`string`	No	Derived from name	PascalCase component name
`importPrefix`	`string`	No	`@/components/proto`	Import path prefix for components
`includeTheme`	`boolean`	No	`true`	Include theme CSS in export

Example

{
  "componentName": "SignupForm",
  "importPrefix": "@/components/ui"
}

Response

{
  "code": "import { Card, CardHeader, CardContent, ... } from \"@/components/ui\";\n\nexport function SignupForm() {\n  return (\n    <Card className=\"p-6\">\n      ...\n    </Card>\n  );\n}",
  "themeCSS": ":root {\n  --primary: 39.11% 0.084 240.8;\n  ...\n}",
  "installDeps": [
    "@prototyperco/ui/card",
    "@prototyperco/ui/button",
    "@prototyperco/ui/text-field"
  ],
  "files": [
    {
      "path": "components/signup-form.tsx",
      "content": "..."
    },
    {
      "path": "styles/theme-tokens.css",
      "content": "..."
    }
  ],
  "source": "bridge"
}

design_create

Parameters

Example

Response

design_update

Parameters

Patches Format

Spec Operations

Response

design_theme

Parameters

Natural Language Examples

Example

Response

design_get

Parameters

Example

Response (summary)

design_list

Parameters

Response

design_close

Parameters

Example

Response

design_export

Parameters

Example

Response

On this page