designer-mcp

适用于 Claude Code 的 Cursor 风格设计笔。在有头 Chromium 浏览器中对任意网页进行点击、框选或绘图，Claude 即可获得精确的源文件、行号、CSS 选择器和截图——随时准备进行编辑和验证。

功能说明

三种可视化转源码模式：

所有截图均保存为 /tmp 目录下的 PNG 文件并返回路径——你的 MCP 客户端永远不会触及 base64 的上下文限制。

React 源码解析在 Next.js 开发模式下通过 _debugSource fiber 属性（由 @babel/plugin-transform-react-jsx-source 附加）工作。生产环境构建会移除此属性；请参阅下方的 生产环境源码映射。

演示

You:     "Make this button rounder"
Claude:  [designer_open http://localhost:3000/dashboard]
Claude:  [designer_pick mode=element]
You:     *click the button*
Claude:  → source: Button.tsx:42
Claude:  [Edit Button.tsx add rounded-full]
Claude:  [designer_screenshot selector=#cta-btn]  ← after screenshot for verification

安装

先决条件：Node 18+，Claude Code，可用的 macOS/Linux 环境（Playwright Chromium）。

git clone https://github.com/YOUR_USER/designer-mcp.git
cd designer-mcp
npm install
npx playwright install chromium      # one-time browser download

将 MCP 注册到 Claude Code（用户范围 = 在每个会话中可用）：

claude mcp add --scope user designer-mcp node "$(pwd)/index.js"

安装 Claude 技能，以便未来的会话了解该工作流：

mkdir -p ~/.claude/skills/designer
cp SKILL.md ~/.claude/skills/designer/SKILL.md

重启 Claude Code。你应该能在会话中看到 designer_* 工具和一个 designer: 技能。

使用方法

启动你的 Next.js 开发服务器（用于源码映射）：

cd your-nextjs-app && npm run dev

然后在 Claude Code 中：

"在设计器中打开 http://localhost:3000/settings 并让我选择页眉。"

Claude 将调用 designer_open(...)，然后调用 designer_pick({ mode: "element" })。Chromium 窗口会弹出到前台，你的光标变成十字准线，点击页眉即可。Claude 将获得 source.fileName + lineNumber 并可以直接进行编辑。

模式速查表

• 单个元素 — 使用 element

• 同一区域内的多个相关元素 — 使用 area（拖拽一个框；返回中心点落在框内的所有元素）

• 可视化标注/解释 — 使用 draw（红笔，按 Enter 完成，按 Esc 取消）

生产环境源码映射

_debugSource 仅限开发环境使用。若要在生产构建中使用拾取器，请在 next.config.js 中启用源码映射：

module.exports = {
  productionBrowserSourceMaps: true,
  // ...
};

拾取器目前在生产环境中返回 source: null；未来版本将通过已部署的 sourcemap 解析选择器。欢迎提交 PR。

工具参考

所有工具均通过 MCP 公开；Claude Code 将它们视为 mcp__designer-mcp__*。

designer_open(url: string)

启动或重用有头 Chromium 实例并导航。通过 bringToFront() + AppleScript 提示在 macOS 上将窗口置于前台。

designer_pick({ mode?: "element" | "area" | "draw" })

激活拾取器覆盖层。当用户完成交互（或按 Esc 取消，或 180 秒超时）时返回。

designer_screenshot({ selector?: string })

获取页面或特定元素的 PNG。返回 { path, bytes }。

designer_close()

关闭浏览器并释放 Playwright 资源。

工作原理

1. 启动一个由 Playwright 控制的有头 Chromium 实例。每个进程单例。

2. designer_pick 将一个小型的原生 JS 覆盖层 (picker.js) 注入页面。该覆盖层：

   • 元素模式 — 追踪 mousemove/click，用蓝色勾勒悬停目标，解析一个相对唯一的 CSS 选择器，遍历 React fiber 链以获取 _debugSource，并返回给 MCP。

   • 区域模式 — 橡皮筋式框选；鼠标抬起时，收集所有中心点落在框内的元素（按选择器去重）。

   • 绘图模式 — 全视口画布覆盖层；将笔迹捕获为点数组；按 Enter 键完成。

3. 服务器每 200 毫秒轮询一次 window.__designerResult，最长持续 180 秒。

4. 完成后，将适当的截图（元素/区域裁剪/全视口）保存到 /tmp 并返回路径。

贡献

• 欢迎提交 PR，特别是在以下方面：

  • 生产环境 sourcemap 解析

  • Kestrel/React Native 拾取器（目前仅支持 Web）

  • 元素模式下的多元素累加（Cmd-点击以添加）

  • VS Code "在编辑器中显示" 集成

许可证

MIT