collectui-mcp

让编码代理看到设计，而不是一张截图。

你在 CollectUI 上看到一段漂亮的 UI 动画。你想让 Claude Code（或 Codex、Cursor）实现类似的效果。于是你截图、粘贴进去，然后……代理只看到一帧静态画面。它不知道下拉框是在 240ms 内弹开的，不知道它会过冲 7% 再回稳，也不知道如何结束。它全靠猜，最后给你一坨普通的 ease-in-out。

这个 MCP 服务器解决了问题。粘贴一个 CollectUI 链接，你的代理就能得到真实数据。

你的代理实际会收到什么

真实输出，来自真实案例：

0.69s → 0.92s · TRANSITION · 231ms · translation — content travels right 75px
  - Change focused on the upper-centre-right (81% of the change energy)
  - Displacement: dx +75px, dy +0px (within the 644×350 content box)
  - Best-fit easing: expo-out (snappy) → cubic-bezier(0.16, 1, 0.3, 1) (R²=0.98)
  - Overshoot of 7% — a spring, not a plain ease

  Where the movement happens:
  |    ░▓▓░|
  |   ░░██░|
  |       ░|
  |       ▒|
  |     ▒▓ |

最后那一块是该帧的热图。你的代理能看出运动集中在右上方，而不只是“有东西动了”。

简报里还包含调色板（含对比度）、布局结构、动画是否无缝循环，最后还给出可直接复制的 CSS 和 framer-motion 代码作为起点。

这一切大约只需 2,500 个 token，完全不需要图片。

为什么不直接发帧？

一个 5 秒的 GIF 约有 150 帧。哪怕只发一小部分，也要消耗几万个 token，而且它依然无法告诉你的代理某个过渡是 231ms——因为你无法从一堆静态帧中测出时间。

所以这个项目会直接测量视频，并用文字把结果写下来。文字更小、更精确、更实用。

需要时仍然可以取图片——只是默认不返回。你拿到的帧是在有意义的节点上选取的（过渡开始、峰值、定格点），而不是盲抽。

准备工作

1. 环境要求

你需要 Node 18+ 和 ffmpeg。

brew install ffmpeg

（在 Linux 上：sudo apt install ffmpeg。在 Windows 上：从 ffmpeg.org 下载，并确保它已加入 PATH。）

2. 获取代码

git clone https://github.com/rayhankhilji/collectui-mcp.git

然后安装并构建：

cd collectui-mcp && npm install && npm run build

3. 把它连接到你的代理

选择你正在使用的那个。无论哪种方式，都要把 /path/to/collectui-mcp 替换成你实际克隆的路径——必须是绝对路径，而不是相对路径。

一条命令即可：

claude mcp add collectui --scope user -- node /path/to/collectui-mcp/dist/index.js

--scope user 让它在所有项目中可用。如果只想在当前仓库中使用，则改用 --scope project。

验证连接是否成功：

claude mcp list

在 ~/.codex/config.toml 中添加：

[mcp_servers.collectui]
command = "node"
args = ["/path/to/collectui-mcp/dist/index.js"]

把它添加到 ~/.cursor/mcp.json（或项目内的 .cursor/mcp.json）：

{
  "mcpServers": {
    "collectui": {
      "command": "node",
      "args": ["/path/to/collectui-mcp/dist/index.js"]
    }
  }
}

其实格式和 Cursor 一样——这就是一个标准的 stdio MCP 服务器：

{
  "mcpServers": {
    "collectui": {
      "command": "node",
      "args": ["/path/to/collectui-mcp/dist/index.js"]
    }
  }
}

路径里有空格？ 在 shell 命令中用引号包裹路径（node "/Users/me/my folder/collectui-mcp/dist/index.js"）。在 JSON 中只需正常写字符串，不用额外处理。

4. 使用

重启你的代理，然后像平时一样直接和它说话：

看看 https://collectui.com/designs/ui-interaction-ui-design-inspiration，帮我做第二个

分析这个并精确还原它的时间节奏：<any collectui link>

在 collectui 上帮我找几个下拉菜单动画，并展示最好的那个是怎么动的

你的代理会自己调用工具，你不需要显式指定工具名。

接受什么输入

它接受以下任意一种：

• 一个 CollectUI 分类页 — https://collectui.com/designs/ui-interaction-ui-design-inspiration

• 一个设计师个人页 — https://collectui.com/designers/someone

• The trending 页面，或者首页

• 一个 CollectUI 帖子 ID — ce63a499-08b0-4782-866c-f99d0adbd5ad

• 原始的 X/Twitter 帖子链接

• 任何直接的图片、GIF 或视频 URL，这部分甚至完全不需要现在用任何 UI

指向列表页，它给你一份可选择的索引；指向单一设计，它给完整的分解说明。

工具

get_design_context 接受一个 detail 参数来控制成本：

大多数时候 brief 完全够用——时间线已经告诉 agent 时长、缓动和方向。

工作原理

1. 找到设计。 CollectUI 的内容目录放在一个公开只读端点后面，它和网站自己的 JavaScript 调用的是同一个。详见下面的数据源说明。

2. 裁掉装饰区域。 设计师会把作品放在一大块纯色背景板上。先检测并移除这块背景。这一步的重要性超乎想象：在一个测试帖里，跳过这一步会让调色板变成 94% 米色，形容的是“背景板”而不是“UI”。

3. 只解码一次。 ffmpeg 解码的帧会先缩为 64px 宽的小图，后面所有计算都基于这一次解码结果。没有图像库，没有临时文件，没有二次解码。

4. 测量运动。 逐帧差分把时间线拆分为静帧与转场。每个转场阶段都会得到：

   • 一个 8×5 的格子，显示变化集中在哪里

   • 块匹配，判断移动方向与距离

   • 冲量检测——这是区分弹性 spring 与简单 ease 的关键

   • 用 R² 把进度曲线拟合到 14 条标准缓动函数上

5. 挑值得看的帧。 会在片段边界、运动峰值以及静止中途的落点取帧，而不会均匀抽样。

测得的 vs. 推断的

需要坦白说明，因为你的 agent 会按照这些信息采取行动。

从画面直接测得：时间、尺寸、颜色、对比度、裁剪框、位移、循环检测。这些都是从像素里读出来的。

推断出来的：缓动函数 名称、spring 弹性常数、元素角色。这些靠曲线拟合与启发式规则得到。它们是可靠的起点，但不是绝对事实。

一个真实存在的局限性：位移量计算会对整帧做块匹配，因此它上报的是 主导那个方向的位移。如果三个元素同时朝不同方向移动，它们就会被平均掉。每份简报都会注明这一点，这样你的 agent 就不会对它产生过多依赖。

关于数据源

CollectUI 没有公共 API。它的前端读取 Supabase 上的一个端点，使用的是一只体验认证后的 key 随每次加载下发到浏览器。本项目运行的也是同一个公开端点，不会内置那个 key 的副本。它像浏览器一样在运行时从线上包里读出 key，并缓存到本地。这样这个 repo 永远不会转发别人的凭证，也不担心他们轮换 key 后损坏。

每次下载都会缓存，所以重新分析同一个设计不会重新拉取任何内容。

如果 CollectUI 将来推出真实 API，只有 src/api.ts 一个文件需要改。分析流水线并不关心介质来自哪里。

请合理使用，不要过度。这是别人的网站。

开发

npm run build          # compile
npm run dev            # compile on change

两个脚本可以快速调试其中部分逻辑：

node scripts/smoke.mjs <url-or-id>   # run the full analysis, print the brief
node scripts/test-mcp.mjs            # drive the server over stdio, like an agent would

代码结构：

src/
  index.ts          MCP server + the four tools
  api.ts            resolving CollectUI links to posts
  media.ts          downloading and caching
  ffmpeg.ts         every ffmpeg/ffprobe call
  pack.ts           assembles the brief you actually read
  analysis/
    motion.ts       segmentation, easing fitting, displacement
    color.ts        palette extraction, contrast
    layout.ts       bands, matte detection, content box

贡献

欢迎提交 Issue 和 Pull Request。尤其关注：

• 更好的缓动参数拟合（当前弹簧参数相当粗糙）

• 分区运动追踪，让多个元素同时移动时不会被平均掉

• 文本检测，让简报能描述界面里真正显示的内容

许可证

MIT — 见 LICENSE.