jsdesign-mcp

让 Claude 等 AI 助手通过 MCP (Model Context Protocol) 直接操作即时设计（js.design）画板：读取、创建、编辑设计稿。

用户快速上手（三步）

1. 配置 Claude Code

终端运行一条命令，自动写入配置：

npx -y jsdesign-mcp setup

2. 重启 Claude Code

3. 打开插件

在即时设计中打开「MCP Bridge — AI 设计助手」插件，面板显示「已连接」即可开始使用。

连接是全自动的：插件会自动发现本地服务并获取认证 token，无需复制粘贴任何东西。

然后在 Claude Code 里直接说：

• 「创建一个 1440×900 的画板，里面放一个蓝色圆角按钮」
• 「读取当前选中的组件结构」
• 「把选中的画板导出成 PNG」

架构

Claude Code
    ↓ stdio (MCP)
jsdesign-mcp（本地服务，npx 运行）
    ↓ WebSocket + HTTP (127.0.0.1:3055，仅本机)
插件 UI（即时设计 iframe，自动获取 token）
    ↓ postMessage
插件 code.js（沙箱）
    ↓ jsDesign API
设计稿画板

隐私：所有数据仅在本机流转，设计稿不经过任何远程服务器。token 仅通过 localhost HTTP 下发（无 CORS 头，外部网页无法窃取）。

全部工具（49 个）

读取

| 工具 | 说明 | | --- | --- | | jsdesign_get_document_info | 获取文档信息 | | jsdesign_get_current_page | 获取当前页面 | | jsdesign_get_selection | 获取选中节点 | | jsdesign_get_node_by_id | 按 ID 获取节点 | | jsdesign_get_node_tree | 递归获取节点树 | | jsdesign_list_nodes | 列出页面/容器子节点 |

创建

| 工具 | 说明 | | --- | --- | | jsdesign_create_frame | 创建画板（支持 cornerRadius） | | jsdesign_create_rectangle | 创建矩形（支持 cornerRadius） | | jsdesign_create_ellipse | 创建圆形 | | jsdesign_create_line | 创建直线（长度/角度/描边） | | jsdesign_create_polygon | 创建多边形（边数 ≥3） | | jsdesign_create_star | 创建星形（角数 + 内径比） | | jsdesign_create_text | 创建文本（支持 fontFamily / fontStyle，如 PingFang SC Semibold；字体不可用时自动回退并返回警告） | | jsdesign_create_from_svg | 将 SVG 字符串导入为原生矢量图层 | | jsdesign_upload_image_from_url | 从 URL 上传图片 |

结构

| 工具 | 说明 | | --- | --- | | jsdesign_move_node | 移动节点：换父级（reparent，保持画布绝对位置）/ 调整层级（z-order） | | jsdesign_group_nodes / jsdesign_ungroup | 编组 / 取消编组（位置保持） | | jsdesign_update_node | 更新节点属性（位置、尺寸、显隐、锁定、透明度、clipsContent、isMask 等） | | jsdesign_delete_node | 删除节点（也可删除整个页面） |

矢量

| 工具 | 说明 | | --- | --- | | jsdesign_boolean_operate | 布尔运算：union / subtract / intersect / exclude | | jsdesign_flatten | 将多个节点拼合为单个矢量（需在画板/编组内） |

样式

| 工具 | 说明 | | --- | --- | | jsdesign_set_fill | 设置纯色填充（hex 支持 alpha；append 叠加多层填充） | | jsdesign_set_gradient_fill | 设置渐变填充：linear（angle 0=左→右、90=上→下，或 from/to）/ radial / angular，2-8 个色标支持 alpha | | jsdesign_set_corner_radius | 设置圆角：统一值或四角独立，cornerSmoothing 为 iOS 平滑圆角 | | jsdesign_set_stroke | 设置描边：颜色、粗细（0 清除）、对齐、虚线、透明度 | | jsdesign_set_effects | 设置效果：投影/内阴影/图层模糊/背景模糊（整体替换，传 [] 清除） | | jsdesign_set_text_style | 设置文字样式：字体字重、字号、对齐、字距、行高、大小写、下划线 |

自动布局与约束

| 工具 | 说明 | | --- | --- | | jsdesign_set_auto_layout | 自动布局：方向、hug contents、对齐、padding、间距 | | jsdesign_set_layout_child | 子节点行为：layoutAlign（STRETCH 交叉轴撑满）、layoutGrow（主轴填充） | | jsdesign_set_constraints | 约束：MIN/MAX/CENTER/STRETCH/SCALE，父级缩放时生效 |

组件与实例

| 工具 | 说明 | | --- | --- | | jsdesign_create_component | 创建组件，可直接包装现有节点（保持位置） | | jsdesign_create_instance | 创建组件实例（组件集自动取默认变体） | | jsdesign_combine_as_variants | 合并组件为变体集 ⚠️ 当前 js.design 运行时对此 API 支持异常（会错误转换节点），检测到失败会自动回滚并报错；请在编辑器中手动创建变体集 | | jsdesign_instance_set_properties | 设置实例的变体属性（如 { "State": "Hover" }） | | jsdesign_instance_swap_component | 更换实例的主组件 | | jsdesign_detach_instance | 分离实例为普通画板 |

样式库

| 工具 | 说明 | | --- | --- | | jsdesign_create_style | 创建本地样式：PAINT / TEXT / EFFECT（名称支持 / 分组，如 Brand/Primary） | | jsdesign_list_styles | 列出文件内的本地样式（id、名称、类型、key） | | jsdesign_apply_style | 把样式库中的样式应用到节点（fill / text / effect，带类型校验） |

富文本

| 工具 | 说明 | | --- | --- | | jsdesign_set_text_range | 设置文本区间内样式：字号、字体字重、颜色、下划线、大小写、字距、行高 | | jsdesign_edit_text_characters | 插入/删除文本字符（删除通过重写实现，会塌缩区间样式） |

页面管理

| 工具 | 说明 | | --- | --- | | jsdesign_create_page | 新建页面 | | jsdesign_list_pages | 列出所有页面 | | jsdesign_set_current_page | 切换当前页面（重命名页面用 update_node） |

原型与排列

| 工具 | 说明 | | --- | --- | | jsdesign_set_reactions | 设置原型交互：触发（点击/悬停/超时…）+ 动作（打开链接/返回/关闭；⚠️ 跳转型交互在当前 js.design 运行时会触发平台异常，请在编辑器中设置） | | jsdesign_align_nodes | 对齐：左/水平居中/右/顶/垂直居中/底（支持跨父级） | | jsdesign_distribute_nodes | 分布：水平/垂直等距（首尾固定）或固定间距 |

导出

| 工具 | 说明 | | --- | --- | | jsdesign_export_node | 导出节点为 PNG/JPG/SVG/PDF（outputPath 直接写本地文件） |

读取工具（get_node_by_id / get_node_tree 等）会一并返回圆角、描边、渐变 transform、字体、自动布局、约束、样式引用、原型交互等属性，便于核对写入结果。

修改源码后如何生效（两步缺一不可）

1. 重启 MCP server：npm run build 后在 Claude Code 里 /mcp 重连，或重启 Claude Code 会话（MCP 进程在会话启动时拉起，不热加载）。
2. 重开插件：在即时设计客户端关闭并重新打开「MCP Bridge」插件（code.js 在插件启动时加载；端口 3055 不变，WebSocket 自动重连）。

开发者

构建

npm install
npm run build

本地调试

npm run start:server   # 启动 bridge + MCP server
npm run inspector      # MCP Inspector 调试工具

在 js.design 中加载开发版插件

• 打开 js.design 桌面客户端
• 菜单：插件 → 开发者 → 导入插件
• 选择 plugin/package/manifest.json（plugin/package/ 是构建生成的平铺发布目录：manifest 与 code.js / ui.html 同级），在「开发插件」列表中点击运行

发布到 npm

npm publish

prepublishOnly 会自动 clean + build，发布内容仅含 dist / README.md / LICENSE。

上架即时设计插件市场

上架物料见 store/（图标、简介文案、截图清单）。上架后在开发者后台重新上传 plugin/dist 构建产物，并将 plugin/manifest.json 的 id 替换为官方分配的插件 ID。

参考

• js.design 插件开发文档
• jsdesigndev/plugin-typings
• Model Context Protocol