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 tokens입니다. 이미지는 필요 없습니다.

프레임을 그냥 보내면 안 될까?

5초짜리 GIF는 ~150프레임입니다. 그중 일부만 보내도 수만 개의 토큰을 소비하고, 그래도 에이전트에게 전환이 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"]
    }
  }
}

경로에 공백이 있나요? 셸 명령줄에서는 따옴표로 감싸세요 (node "/Users/me/my folder/collectui-mcp/dist/index.js"). JSON에서는 보통 문자열 외에 추가 인용 처리가 필요하지 않습니다.

4. 사용하기

에이전트를 재시작한 뒤 평소처럼 말만 하면 됩니다:

Look at https://collectui.com/designs/UI-interaction-design-ui-inspiration and build me the second one

Analyse this and match the timing exactly: <any collectui link>

Find me some dropdown animations on collectui and show me how the best one moves

에이전트는 도구를 스스로 호출합니다. 일일이 이름을 알려줄 필요가 없어요.

어떤 것을 전달할 수 있는가

다음 중 하나를 주시면 됩니다:

• CollectUI 카테고리 페이지 — https://collectui.com/designs/ui-interaction-design-ui-inspiration

• 디자이너 페이지 — https://collectui.com/designers/someone

• 트렌딩 페이지 또는 홈페이지

• CollectUI 게시물 ID — ce63a499-08b0-4782-866c-f99d0b7adc5b

• X/Twitter의 원본 게시물 URL

• 모든 URL 이미지, GIF, 또는 비디오 직접 링크 — 이 경우 CollectUI 연관 없이 동작합니다.

목록 페이지를 주면 선택할 수 있는 인덱스가 나옵니다. 하나의 디자인을 주면 전체 분석 결과가 나옵니다.

도구

get_design_context는 비용을 조절하는 detail 옵션을 받습니다:

brief는 대부분의 경우 충분합니다 — 타임라인을 통해 에이전트가 해당 지속시간, 이징, 방향을 이미 알 수 있으니까요.

동작 원리

1. 디자인을 찾습니다. CollectUI의 카탈로그는 공공 읽기 전용 엔드포인트 뒤에 존재합니다. 해당 웹사이트의 자체 JavaScript가 사용하는 것과 같은 엔드포인트입니다. 아래 데이터소스에 관한 자세한 내용을 참조하세요.

2. 프레젠테이션을 잘라냅니다. 디자이너들은 작품을 크고 평평한 배경 위에 올립니다. 이 서버는 그 배경을 먼저 찾아 제거합니다. 그 중요성은 생각보다 큽니다. 어떤 테스트 글에서는 이 단계를 건너뛰자 팔레트가 94% 사용하지 않는 베이지색으로 나와 UI가 아니라 받침대를 설명하게 되었습니다.

3. 한 번만 디코딩합니다. ffmpeg에서 64픽셀의 최적 픽셀로 프레임이 나오며, 모든 계산은 이 한 번의 파이프라인에서 이루어집니다. 이미지 라이브러리, 임시 파일, 추가 디코딩이 전혀 없습니다.

4. 모션을 측정합니다. 프레임의 차이로 타임라인을 멈춤(stop)과 전환(end)으로 나눕니다. 각 전환에 대해 다음을 실행합니다:

   • 변화가 집중된 위치를 보여주는 8×5 그리드

   • 어느 방향으로 얼마나 움 x딕 찾는 블록 매칭

   • 스프링과 이징을 구분해주는 오버슈트 검출

   • 진행 곡선을 14가지 표준 이징 곡선에 맞추고 R²으로 점수화

5. 실제 보아야 할 프레임을 선택합니다. 전환 경계, 모션 최고점, 멈춘 상태의 중간부에서 선택합니다 — 균일하게 샘플링하지 않습니다.

측정된 정보 vs 유추된 정보

에이전트가 이 정보를 바탕을 하니까 분명히 말해두겠습니다.

파일에서 직접 측정된 것 — 타이밍, 크기, 색상, 대비 비율, 크롭 영역, 이동량, 루프 여부. 이 항목은 픽셀을 읽는 만큼 들어요.

유추된 것 — 이징 름(curve name), 스프링 상수, 화면 요소의 역할. 이 값은 커브 피팅와 융법 사용의 추림에 나온 것입니다. 강력한 시작점이지 사실은 아닐 수 있습니다.

실제 한계 한 가지: 이동량은 전체 프레임 기준의 블록 매칭을 사용하므로 지배적인 움직임을 보고합니다. 만약 세 요소가 서로 다른 방향으로 움직이면 평균으로 상쇄됩니다. 브리프에는 언제나 그렇게 명시되어 있기 때문에 에이전트가 이미지 간 너부 맹신하지 않도록 되어 있습니다.

데이터 소스에 관한 참고

CollectUI는 공개 API가 없습니다. 프런트엔드 데이터가 사이트에 방문하는 모든 브라우저에 제공하는 읽기 전용 키를 사용해 Supabase 엔드포인트에서 데이터를 읽습니다.

이 프로젝트는 동일한 공개 엔드포인트를 사용합니다. 하지만 일부러 그 키의 사본을 저장소에 넣지 않습니다. 브라우저와 동일하게 런타임에 실시간 사이트 번들에서 키를 가져와 로컬에 캐시합니다. 이렇게 하면 다른 사람 크레덴셜을 재배포하는 사태가 없고, 그들이 키를 교체할 경우에도 문제가 생기지 않습니다.

또한 모든 다운로드를 캐시하므로 같은 디자인을 다시 분석해도 다시 다운로드하지 않습니다.

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

기여

이슈와 PR 언제든 환영합니다. 특히 다음 주제에 관심이 많습니다:

• 이징 적합 높이기 (스프링 파라미터 추정은 지금 메약 추추합니다)

• 구역별 모션 추적 (여러 요소의 움직임이 함께 평균으로 합산되지 않도록)

• 자연어 인식 (브리프가 화면 UI에 실제로 무언가를 잘 설명해낼 수 있도록)

라이선스

MIT — LICENSE 참조.