---
name: visily
description: Visily is an AI design canvas that turns text prompts, screenshots, URLs & more into UI designs that are as easy to edit as a Google Slide. Use Visily MCP to find boards/screens and return links, turn Visily designs into code, or extract theme tokens.
---

# Visily MCP

Use the Visily MCP server whenever the user mentions Visily, pastes a Visily URL
(`app.visily.ai/...`), or asks to find a board, generate code from a design, or pull a Visily
theme. Default code-generation stack unless told otherwise: **React + TypeScript + Tailwind v4 + shadcn/ui**.

## Access requirement (read first)

The Visily MCP only works on workspaces on a **Pro or Business** plan where the user is the
creator or has an **editor** license. Free workspaces and viewer/guest roles are denied with
a `FORBIDDEN` error at call time — this is by design, **not** a bug, so don't retry. If a call
is denied, tell the user which condition failed (plan vs. editor role) and, if they have other
workspaces, offer to `list_workspaces` and work from an accessible one. Details:
`visily://docs/access-and-permissions`.

## Pick the intent

- **Find / open a design** — "get me the board I was working on for 4.6", "link to that
  screen" → *Find a board or screen*.
- **Design → code** — "turn this Visily screen into code", a pasted element link →
  *Design to code*.
- **Extract a theme** — "use our Visily theme", "get the brand tokens" → *Extract a theme*.

## Find a board or screen

1. `list_workspaces` if no workspace is known (only accessible workspaces are returned).
2. `list_boards({workspaceId | projectId})` — or `list_projects` first for large workspaces.
   Match the user's description against names; for "what I was working on", sort by
   `updatedAt`. If several match, ask the user to pick rather than guessing.
3. `list_elements({boardId})` to resolve a specific screen.
4. Return a navigable URL (not just IDs), then stop — don't generate code unless asked:
   - Project: `https://app.visily.ai/projects/{projectId}`
   - Board: `https://app.visily.ai/projects/{projectId}/boards/{boardId}`
   - Screen: `https://app.visily.ai/projects/{projectId}/boards/{boardId}/elements/{elementId}`

## Design to code

Keep this path short: one call gets the code, and you pull the theme or a screenshot only when
they actually help.

1. **Identify the page element.** If the user pasted an element URL, use it directly — no
   discovery. Otherwise do the minimum discovery to reach a screen (PAGE) element:
   `list_elements({boardId})` and pick the screen (`exportable: true`).
2. **Get the code.** `get_design_context({visilyUrl})` returns the code export for that element
   (JSX by default; pass `codeFormat: "html"` for HTML) — code only, nothing else. Large
   screens come back paginated: follow `pagination.nextCursor` with
   `get_design_context({cursor})` and concatenate the chunks. For a very large screen, or to
   reconstruct from a single fetch, pass `delivery: "url"` and download the returned link.
3. **Match an existing theme (optional).** Only if the user wants the output to match their
   Visily board's design system, call `get_board_theme({visilyUrl | boardId, format: "Tailwind"})`
   and wire the tokens in (see *Extract a theme*). Skip this otherwise.
4. **Verify visually (recommended).** `get_screenshot({visilyUrl})` for a visual reference
   before building, and again to diff your generated UI against the design. When the code
   export and the screenshot disagree, trust the screenshot for layout and the export for exact
   content.

Rebuild **semantic, responsive** code — the export is absolute-positioned, so never ship it
as-is. Preserve every visible text, control, and asset — reference the CDN asset URLs directly or
download them to self-host (either is fine), but don't substitute icon-library lookalikes or
placeholders, and disclose anything you can't reproduce. For a whole board, repeat step 2 per
screen and extract shared components and one shared theme instead of cloning markup.

## Extract a theme

`get_board_theme({visilyUrl | boardId, format: "Tailwind" | "CSS" | "JSON"})`. Paste the
`:root`/`.dark` variables + `@theme inline` block into the target app's stylesheet and map its
components onto the tokens. Keep both light and dark working.

## Reference

Full rules (read on demand): `visily://docs/output-conventions`, `visily://docs/mcp-usage`,
`visily://docs/handling-elements`, `visily://docs/access-and-permissions`. Advanced/rarely
needed tools: `get_element` (raw model), `get_element_export` (raw artifact URLs) — prefer
`get_design_context`.