Content
# Tool List
JsDesign MCP Bridge: **Read design draft node data → Cursor Agent writes page**.
No writing back to the canvas, only design draft → code.
Repository: https://github.com/nothing-sy/js.design
## What problems does it solve
In instant design, select a screen design, Agent gets the complete node tree (layout, color, text, level) through MCP, and then writes HTML / CSS / React and other pages accordingly, rather than relying on screenshots to guess styles.
## Requirements
- Node.js 18+
- [JsDesign](https://js.design/download) desktop client
- [Cursor](https://cursor.com) (or other MCP-enabled clients)
## I. Installation and Construction
```bash
git clone https://github.com/nothing-sy/js.design.git
cd js.design/mcp-server
npm install
npm run build
```
Build product: `mcp-server/dist/index.js` (Cursor will start this file).
## II. Enabling MCP (Cursor)
**No need to manually open the terminal for a long time.** Cursor will automatically start the service according to the configuration.
### Method A: Global configuration (recommended, available for any project)
Edit the MCP configuration in the user directory:
| System | Path |
|------|------|
| Windows | `%USERPROFILE%\.cursor\mcp.json` |
| macOS / Linux | `~/.cursor/mcp.json` |
Add ( **change the path to your local repository location** ):
```json
{
"mcpServers": {
"jsdesign": {
"command": "node",
"args": ["D:/projects/js.design/mcp-server/dist/index.js"]
}
}
}
```
### Method B: Only for the current project
Copy this repository's [`.cursor/mcp.json`](.cursor/mcp.json) and modify the absolute path.
If the name is the same as the global one, **project-level configuration takes priority**.
### Confirm it is enabled
1. Open Cursor **Settings → MCP**
2. Find **jsdesign**, turn on the switch, and wait for the **green light**
3. When the light is red, click **Refresh / Restart**
Successfully, the machine will listen to: `ws://127.0.0.1:3847`
Optional environment variable: `JSDESIGN_MCP_PORT` (default `3847`). Change the port and the address in the plugin panel.
## III. Import JsDesign Plugin
1. Open JsDesign → any design file
2. Menu: **Plugin → Developer → Import Plugin**
3. Select this repository's [`plugin/manifest.json`](plugin/manifest.json)
4. Run the plugin **JsDesign MCP Bridge**
5. The panel shows **"Connected"** (green light)
> You must let Cursor start MCP (the green light in the previous step) before the plugin can connect.
> Keep the plugin panel open during use; closing it will disconnect the bridge, and MCP will prompt not connected.
## IV. What does "selecting a canvas" mean
On the JsDesign canvas, **click the entire screen you want to restore to code** (usually a large Frame) and make it in the selected state.
| Operation | `export_selection` export content |
|------|---------------------------|
| Select the entire "Home" Frame | The complete structure of the screen (recommended) |
| Select only one button inside | Only that button |
| No selection | Error: No node selected |
You can also call `list_top_frames` to see which top-level canvases are currently on the page, and then use `nodeId` / `name` to export using `export_node`.
## V. Daily usage process (design draft → write page)
1. Cursor: MCP `jsdesign` green light
2. JsDesign: Open **JsDesign MCP Bridge**, display "Connected"
3. **Select the target canvas** on the canvas
4. In the Cursor conversation, say to the Agent, for example:
> First, use jsdesign's `get_connection_status` to check the connection, then `export_selection`, and write a React page according to the design data.
Typical Agent call sequence:
```text
get_connection_status → export_selection → (optional) get_design_tokens → write code
```
## VI. MCP Tool List
| Tool | Description |
|------|------|
| `get_connection_status` | Is the plugin online |
| `get_document_info` | File / current page information |
| `list_pages` | Page list |
| `list_top_frames` | Current page top-level canvases |
| `export_selection` | **Export the complete node tree of the current selection (most commonly used)** |
| `export_node` | Export a subtree according to `nodeId` or `name` |
| `export_page` | Export the entire page (large page慎用) |
| `export_assets` | Export cut images / picture resources to the local directory |
| `get_design_tokens` | Color / font size / spacing / rounded corners deduplication |
| `get_node_css` | Single node approximate CSS summary |
Export optional parameters:
- `maxDepth`: Maximum recursion depth
- `skipHidden`: Skip hidden nodes (default `true`)
- `skipInstanceChildren`: Skip component instance internals (default `true`)
- `includeAssets`: Export bitmaps together (if the tool supports)
- `outputDir`: Cut image output directory
When JSON exceeds about 400KB, it will be written to a temporary file (such as `%TEMP%/jsdesign-mcp/export-*.json`), and the tool returns `path`, and the Agent uses Read to read.
## VII. What does the exported data look like
Each node roughly contains:
- **Identity**: `id`, `name`, `type`, `visible`
- **Geometry**: `x`, `y`, `width`, `height`, `rotation`
- **Layout**: `layoutMode`, `padding*`, `itemSpacing`, …
- **Visual**: `fills`, `strokes`, `cornerRadius`, `effects`, `opacity`
- **Text**: `characters`, `fontName`, `fontSize`, `lineHeight`, …
- **Hierarchy**: `children[]`
Type definition see [`mcp-server/src/schema.ts`](mcp-server/src/schema.ts) `DesignNode`.
## VIII. Project Structure
```text
js.design/
plugin/ # JsDesign plugin (bridge)
manifest.json
code.js
ui.html
mcp-server/ # Node MCP Server
src/
index.ts
bridge.ts
tools.ts
schema.ts
dist/ # build product (Cursor startup entrance)
.cursor/mcp.json # Project-level MCP configuration example
package.json
README.md
```
Architecture diagram:
```text
Cursor Agent ──stdio──► MCP Server ──WebSocket──► Plugin UI ──postMessage──► code.js ──► Canvas
```
According to [JsDesign Plugin API](https://js.design/developer-doc/plugin/guide/start/Intro): The main thread has no network capability, and the bridge must be placed in the UI iframe.
## IX. Frequently Asked Questions
| Phenomenon | Solution |
|------|------|
| jsdesign red light in Cursor | `npm run build` and Refresh; check if `mcp.json` path points to this machine's `dist/index.js` |
| Port occupied | End the process occupying `3847`, or set `JSDESIGN_MCP_PORT` and synchronize the plugin address |
| Plugin displays "Not connected" | Ensure Cursor MCP green light, then click the plugin "Reconnect" |
| `export_selection` reports no selection | Select the target Frame on the canvas and then call |
| Export is slow / large | Prioritize exporting a single canvas; use `maxDepth` to limit depth |
## Limitations
- The plugin must be opened and kept running by the user and cannot be resident in the background
- Cannot listen to editing in real-time; each tool call pulls the latest snapshot
- Only one JsDesign plugin can be run at the same time
- **No writing back to the canvas**
## License
MIT
