uisandbox-mcp

npx uisandbox-mcp open ./dist     # the sandbox opens in your browser with your build — no agent needed

或者把一个 zip 拖到 uisandbox.org 上。又或者，在 Claude Code 中：/plugin marketplace add AlexanderKaan/uisandbox → /plugin install uisandbox@uisandbox，然后说*“在 UISandbox 中打开这个应用”*。

它能做什么

1. 把构建带进来 — 三种方式：一个包含 dist/、build/、out/ 的 zip 包（或包含构建产物的整个仓库）；一个文件夹（能渲染的构建会被渲染，源码文件夹会被读作旋钮台）；一个公开的 GitHub 仓库 URL（通过同源路由以 zip 形式获取——这是唯一会离开标签页的内容，参见 notes/security.md）。处理过程中，入口界面会显示带编号的阶段。除此之外，没有任何数据离开标签页：文件在页面内被读取，并由本源的 service worker 提供给框架。

• 1:1 查看。 CSS 里的每个颜色、圆角、字体、字号、间距、行高、字间距、字重、边框宽度、时长、渐变角度和阴影字面量都会变成一个变量，值不变，因此页面渲染效果与原来完全一致——运行时样式也一样（JS 设置的 style=""、你框架追加的 <style>、来自 styled-components、Emotion、Lit、Ant 的 cssinjs 的 insertRule/replaceSync CDN 样式表通过同源代理加载；嵌套的同源框架，比如 Storybook 的）。

4. 转动旋钮。 Brand，以及 CSS 中实际包含的颜色家族（secondary、accent、状态色集合、为其他颜色准备的调色板行）；页面背景；灰色色调和边框色调；显示字体和正文字体（你的字体排在最前，再按字符特征推荐备选字体）；字号、行高、字间距、字重、间距、圆角、边框宽度、阴影深度、动效和渐变角度等旋钮——每个旋钮的中心**×1 = 按你的代码原值**；全局色相、饱和度和对比度，作用于所有颜色、图表调色板、CSS 绘制的图标也包括在内；你的深色模式，用自己的切换开关来控制。

5. 导出。：将你的值导出为 CSS / JSON / 补丁列表，就地修补你的文件，--k-* 令牌供 Web 使用（CSS、Tailwind、shadcn），iOS 的 Swift 常量 + 素材目录，Android 的 colors.xml + Kotlin。

Related MCP server: UI Preset MCP Server

设计上的诚实

• “1:1” 是测量出来的，不是凭感觉。 Check 1:1 会把未改动的构建和令牌化构建并排加载，逐一对比所有元素的计算样式（18 个属性，包括嵌套框架和 shadow root）。要么零差异，要么明确告诉你哪里不同。

• 覆盖率仪表 车站的角落会显示你所看到的内容中，有多少是旋钮能够触及的——已填充的颜色、字体家族、字号、圆角——以及哪些是它无法触及的（图片、canvas、视频）。

• 它能直接拒绝无法呈现的东西。 对于 iOS/Android 项目、WordPress 主题以及没有构建产物的源码，入口处会收到明确提示；页面请求的文件要是构建产物里没有，也会明确告诉你（“通常这意味着是源码，不是构建产物”）。

• 恶意构建包不能把工具拽走，不能注册自己的 service worker，也不能注销我们的，更无法导出时夹带 zip-slip 路径。它能做的——访问工具的 DOM，因为帧在设计上就是并源的——也不会触及任何有价值的东西：没有服务器、没有凭据、没有状态。阅读 notes/security.md；请部署在单独的 origin 上。

运行

pnpm install
pnpm dev        # http://localhost:5190
pnpm test       # vitest + node:test (audit engine)
pnpm build      # dist/ — static; public/_headers rides along
pnpm holdouts   # every fixture zip through the real app in headless Chromium (see below)

http://localhost:5190/?load=<zip-url> 通过 URL（同源或 CORS）加载一个 zip——这就是代理使用的入口。

用它来问责

pnpm holdouts 会把 fixtures/ 中的每个构建包（来自公开仓库的真实构建产物——已 gitignore，notes/decisions.md 记录了每个构建的来源）跑完整个流程：加载、1:1 校验、覆盖率检测，以及宿主校验（同源、仅一个 worker）。结果会与 scripts/holdouts.expect.json 保存的期望一致；一个实验用例一旦预期为 ok 而实际上是横幅验证，就会导致失败。支持 --only <name>、--record，以及针对生产构建或线上站点的 --base <url> --fixtures <url>。

运作原理

src/
  sandbox/
    rewrite.ts   their CSS/HTML → literals replaced by var(--us-vN); byte-preserving
    table.ts     the substitution sheet: one entry per (kind, value), with sites
    mapping.ts   knob → their values, RELATIVE to the baseline (identity at rest); families
    baseline.ts  the knobs on the stand of THEIR code (audit + the sheet + the rendered page)
    project.ts   root and deploy-base detection · screens · raw + rewritten files · guard + hook
    host.ts      owns the sandboxes, answers the service worker; live vars injected into HTML
    verify.ts    the 1:1 check: raw vs identity, computed styles per element
    coverage.ts  the reach meter
    live.ts      MutationObserver: runtime style="" and <style> get the same rewrite
    scheme.ts    their dark mode: hooks found in their CSS, switched
  public/sw.js   serves a sandbox document's URLs from the page; /__ext/ proxies CDN CSS
  tokens/ panel/ state/ export/ audit/   the knob engine, panel, undo/hash, exporters, source audit
notes/           decisions (numbered), traps, lessons, security, roadmap

MCP

npx -y uisandbox-mcp（npm）——或者从克隆的仓库运行 pnpm mcp ——把同一套引擎作为 MCP 服务器（stdio）运行：load 按 URL 或路径加载 zip 包，set 旋钮值，export 导出任意格式，verify 做 1:1 检查，screenshot 在 headless Chromium 里对真实应用截图。完整工具列表和 Claude/Cursor 配置见 mcp/README.md。Claude Code 插件（skill + server 合一）：/plugin marketplace add AlexanderKaan/uisandbox 然后 /plugin install uisandbox@uisandbox——这会带来 /uisandbox 命令（“在沙盒中打开这个应用”、“试试 brand #e11d48”）和 uisandbox MCP 服务器。只有 skill 的情况下，将 skills/uisandbox/SKILL.md 复制到 .claude/skills/ 即可。Codex / Cursor / 其他：添加 MCP 服务器（npx -y uisandbox-mcp）；服务器会发送自己的指令和 prompt。

部署

静态文件，单一 origin，service worker 位于根目录。Cloudflare Pages：构建命令 pnpm build，输出目录 dist/；public/_headers 确保 sw.js 不被缓存并设置安全头；public/_redirects 将深链重定向到应用。请勿在 origin 上部署除它之外的其他东西。

路线图

notes/roadmap.md：正式发布（uisandbox.org）· 把程序入口做成前台 · 让外界能发现它（SEO、llms.txt、统计分析）· MCP 服务器 · 发布后。

Made with ♥ by Alexander Kaan at Pageminds · MIT, free forever · the decisions that shaped it, numbered: notes/decisions.md