collectui-mcp

コーディングエージェントにスクリーンショットではなく、デザインを見せてください。

CollectUI で素晴らしいUIアニメーションを見つけたとします。Claude Code（や Codex、Cursor）にそれに似たものを作ってほしい。そこでスクリーンショットを撮って貼り付けると……エージェントは凍り付いた1フレームを見るだけです。ドロップダウンが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 トークンです。画像は不要です。

なぜ単にフレームを送るだけではダメなのか？

5秒のGIFはおよそ150フレームです。その一部を送信するだけでも数万トークンを消費し、それでもトランジションが231msであることをエージェントに伝えることはできません。なぜなら、静止画の集まりから時間を測定することは不可能だからです。

そこで、このサーバーは動画を直接測定し、その答えを言葉で書き出します。テキストはより小さく、より正確で、より有用です。

画像も必要なときには利用できます。ただしオプトイン方式であり、取得される画像は、ブラインドサンプリングではなく、意味のある瞬間(トランジションの開始、ピーク、収束点)に選ばれます。

セットアップ

1. 前提条件

Node.js 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 を実際にクローンした場所 — 絶対的なパス(相対パスではありません)に置き換えてください。

1つのコマンド：

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"]
    }
  }
}

パスにスペースがある場合？ シェルコマンドで引用符で囲んでください (node "/Users/me/my folder/collectui-mcp/dist/index.js")。JSON では、普通の文字列以外の引用符は不要です。

4. 使用する

エージェントを再起動すると、あとはふつうに話しかけるだけです：

https://collectui.com/designs/ui-interaction-ui-design-inspiration を見て、2つ目を作ってください

これを解析して、タイミングを完全に合わせてください： <any CollectUI link>

CollectUI でドロップダウンアニメーションをいくつか見つけて、一番良いものがどう動くか見せてください

エージェントはツールを自分で呼び出します。名前を指定する必要はありません。

受け入れられる入力

次のようなものを渡すことができます：

• CollectUI のカテゴリページ — https://collectui.com/designs/ui-interaction-ui-design-inspiration

• デザイナーのページ — https://collectui.com/designers/someone

• トレンドページ、またはホームページ

• CollectUI の投稿 ID — ce63a499-08b0-4782-866c-f99d0b7adc5b

• 元の X/Twitter の投稿 URL

• 任意のダイレクト画像、GIF、またはビデオ URL — これは CollectUI とはまったく関係なく動作します

リストページを指定すると、選択用のインデックスが返ります。1つのデザインを指定すると、完全な分析結果が返ります。

ツール

get_design_context は、コストを制御する detail 設定を受け付けます：

多くの場合、brief で十分です。タイムラインは、既に持続時間、イージング、方向をエージェントに伝えます。

仕組み

1. デザインを見つける。 CollectUI のカタログは、公開されている読み取り専用エンドポイントの背後にあります。ウェブサイト自身の JavaScript が呼び出すものと同じです。データソースに関する注記を参照してください。

2. プレゼンテーションを切り取る。 デザイナーは自分の作品を大きな平らな背景の上に配置して見せます。まず、その背景を検出して削除します。重要さは、聞こえに触れる以上です。あるテスト投稿では、このステップを省略すると、カラーパレットが94%ベージュになり、UI ではなく 画用紙 を表現してしまいました。

3. 一度だけデコードする。 ffmpeg からは64px幅の生のピクセルとしてフレームが出力され、その1パスからすべてが計算されます。画像ライブラリも、一時ファイルも、2回目のデコードもありません。

4. モーションを測定する。 フレーム間の差分によって、タイムラインが静止状態とトランジションに分割されます。各トランジションは、次のものを取得します。

   • 変化が集中している 場所 を示す 8×5 のグリッド

   • 動きの方向と距離を特定するブロックマッチング

   • スプリングとイーズを区別のためのオーバーシュート検出

   • 14 の標準イージングカーブに当てはめ、R² でをスコアリングした進行カーブ

5. 見る価値のあるフレームを選ぶ。 セグメント境界、モーションのピーク、静止状態の中盤で選択します。 — 一律のサンプリングではありません。

実測と推定

あなたのエージェントがこれに基づいて 動作するのだから、明確にしておきます。

ファイルから実測】 — タイミング、寸法、色、コントラスト比、切り抜きボックス、変位、ループ検出。これらはピクセルから読み取られます。

推測されるもの — イージングの * 名前 *、スプリング定数、および要素の動き。これらは曲線当てはめとヒューリスティックによるものです。これらは信頼できる出発点ではありますが、絶対的な真実ではありません。

実質的な制限が1つあります。比較ではフレーム全体のブロックマッチングを使用するため、主要な 動きが報告されます。3つの要素が同時に異なる方向に動くと、それらは平均されてしまいます。すべてのブリーフにはその旨が明記され、エージェントが過信しないようにしています。

データソースに関する注記

CollectUI には公開APIはありません。フロントエンドは、サイトにアクセスするすべてのブラウザに配信される読み取り専用キーを使って Supabase エンドポイントから読み取ります。

このプロジェクトもその公開エンドポイントを使用しますが、そのキーのコピーは意図的に含まれません。キーはブラウザと同じく、実行時にライブサイトのバンドルから取得してローカルにキャッシュします。これにより、このリポジトリは他人の認証情報のような投稿を一切『』しません。また、キーがローテーションても壊れません。

さらに、すべてのダウンロードをキャッシュするため、同じデザインを再分析しても再取得は発生しません。

もし CollectUI が本物の API を公開したなら、src/api.ts だけを変更する必要があります — 分析パイプラインはメディアの取得元を気にしません。

どうか良識のある使い方をしてください。誰かのサイトのなのです。

開発

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

直接触って試すための 2 つのスクリプトがあります。

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 と PR を歓迎します。特に次のよのな関心があります：

• イージングのフィット向上(スプリングパラメータ推定は現在かなり大まかです)

• 領域ごとのモーション追跡, 複数の要素が同時に動く平均化されないように

• テキスト検出, ブリーフが UI の実際の内容に言及できるように

その他。ライセンス

MIT — LICENSE を参照してください。