ui-component-judgment-mcp

recommend_component 도구 하나를 노출하는 MCP 서버로, UI 컴포넌트 요구사항을 기존 shadcn/ui 또는 21st.dev 컴포넌트로 충족해야 하는지, 아니면 Mobbin의 실제 앱 레퍼런스를 참고한 커스텀 빌드가 필요한지 판정합니다. 검색 결과 목록이 아닌 구조화된 판정을 반환합니다 — 사람이 탐색하기 위한 것이 아니라 에이전트가 빌드 중간에 소비하도록 만들어졌습니다.

이 서버는 제품 브리프에서 검증된 판정 레이어를 구현합니다: 실제 컴포넌트 증거를 기준으로 필드/요구사항 커버리지를 점수화하고, use_existing / custom_build로 임계값을 나누며, no_candidates_found 버킷을 낮은 커버리지와 별도로 유지하고, 사소한 프리미티브를 위한 정적 스킵 리스트와, 커버리지는 영구적 사실이 아닌 스냅샷이므로 computed_at 타임스탬프를 포함합니다.

작동 방식

이 서버는 shadcn/21st.dev/Mobbin을 직접 스크래핑하지 않습니다. 각 도구 호출은 서버 측 web_search 도구가 활성화된 Anthropic Messages API(claude-sonnet-4-6)에 요청을 한 번 보내며, 전체 프로세스(스킵 리스트 확인, 요구사항 추출, 후보 검색, 실제 증거 커버리지 점수화, 임계값, 그리고 custom_build 시 Mobbin 레퍼런스 조회)를 인코딩한 시스템 프롬프트를 함께 전송합니다. 모델은 구조화된 JSON을 반환하고, 서버는 이를 변경 없이 호출한 에이전트에게 전달합니다.

사소한 프리미티브(button, input, checkbox, label, badge, spinner, tooltip, avatar, icon)는 API 호출 전에 로컬에서 걸러지므로 요청을 소모하지 않습니다.

Related MCP server: shadcn MCP Server

설정

npm install
npm run build

서버가 실행되는 환경에 ANTHROPIC_API_KEY가 설정되어 있어야 합니다.

실행

ANTHROPIC_API_KEY=sk-ant-... npm start

이렇게 하면 stdio를 통해 MCP 서버가 시작됩니다. MCP 클라이언트(Claude Code, Cursor, Claude Desktop 등)에서 이 서버를 가리키면 됩니다 — 정확한 구성은 클라이언트에 따라 다르지만, 일반적으로 다음과 같은 형태입니다:

{
  "mcpServers": {
    "ui-component-judgment": {
      "command": "node",
      "args": ["/path/to/ui-component-mcp/dist/index.js"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
    }
  }
}

도구: recommend_component

입력:

{
  "component_need": "price breakdown with fees and taxes",
  "domain": "Airbnb-style rental marketplace",
  "framework": "React + Tailwind",
  "existing_stack": "already using shadcn/ui"
}

component_need는 카테고리가 아닌 구체적인 내용이어야 합니다 — "pricing"이 아니라 "fees and taxes가 포함된 가격 내역". 모호한 카테고리 이름이 검증 중에 오탐 매칭을 만든 원인입니다(일반적인 SaaS 가격 티어 컴포넌트가 예약 체크아웃의 매칭으로 점수화됨).

출력: 다음에 해당하는 JSON:

{
  "verdict": "use_existing | custom_build",
  "confidence": "high | medium | low",
  "reason": "scored | no_candidates_found | skip_list",
  "computed_at": "2026-08-23",
  "requirements_checked": [ { "requirement": "...", "met": true, "evidence": "..." } ],
  "coverage": "5/7 (71%)",
  "recommendation": {
    "source": "21st.dev | shadcn | null",
    "install_command": "string | null",
    "reference": { "source": "Mobbin", "url": "...", "flow_name": "..." }
  }
}

비용

사소하지 않은 각 호출은 짧은 다중 턴 도구 루프(검색 → 점수화 → 응답)를 실행하며, 현재 가격($2/M 입력, $10/M 출력, web_search 호출당 $0.01) 기준 Sonnet 5로 약 $0.06–$0.10가 소요됩니다 — 스킵 리스트에 있는 프리미티브는 API에 도달하지 않으므로 $0입니다. 품질에 영향을 주지 않으면서 비용을 낮추는 세 가지 요소가 있습니다:

• 시스템 블록의 프롬프트 캐싱(cache_control: ephemeral) — 지침이 모든 호출에서 동일하므로, 반복된 턴과 반복된 호출은 전체 가격을 다시 청구하는 대신 캐시에서 읽습니다.

• 후보 발견을 위한 2회 검색 예산(custom_build가 Mobbin 조회를 트리거하면 1회 추가) — shadcn과 21st.dev를 순차적으로가 아닌 같은 턴에서 검색하므로, 커져가는 대화가 호출당 더 적은 횟수로 재전송됩니다.

• UI_JUDGMENT_MODEL 환경 변수(기본값 claude-sonnet-5) — 코드 변경 없이 더 저렴한 모델(예: Haiku 4.5)로 교체할 수 있습니다. 프로덕션에서 더 저렴한 모델을 신뢰하기 전에, 제품 브리프의 검증된 5개 테스트 케이스(가격 내역, 취소 정책, 수익 대시보드, 갤러리, 메시징)를 다시 실행하고 판정을 Sonnet의 결과와 비교하세요 — 이는 테스트된 것이 아니라 추론만 된 상태입니다.

알려진 제한 사항(검증에서 이어짐)

• 캐싱 없음, 의도된 설계. 모든 호출은 처음부터 다시 검색하고 다시 점수화합니다. custom_build 판정은 라이브러리가 새 컴포넌트를 출시함에 따라 낡을 수 있습니다(검증됨: shadcn의 2026년 6월 채팅 프리미티브가 커스텀 빌드로 보이던 메시징 컴포넌트를 거의 완벽한 매칭으로 바꿈). 호출 에이전트 계층에 캐싱을 추가한다면 세션 범위로만 유지하세요 — 판정을 세션이나 빌드 간에 영구 저장하지 마세요.

• 스킵 리스트는 시작점일 뿐, 아직 실제 사용으로 검증되지 않음. 모든 호출과 스킵 리스트 적중 여부를 로그로 남기세요. 스킵 리스트 항목에 대해 에이전트가 여전히 도구를 호출하는지(리스트가 너무 좁음) 또는 스킵되어야 할 항목에 일반 UI를 사용하는지(리스트에 항목 누락) 관찰하세요.

• 완전히 샌드박스된 환경에서 종단 간 테스트 불가. 이 서버는 api.anthropic.com에 대한 아웃바운드 네트워크 접근과 모델의 web_search 도구가 도달하는 모든 대상에 대한 접근이 필요합니다 — 일반 인터넷 접근을 차단하는 환경에서는 실행되지 않습니다.

• 요구사항 추출과 커버리지 점수화는 결정적 조회가 아닌 모델이 단일 패스로 내리는 판단입니다. 수동 검증 때와 마찬가지로, 파이프라인을 무인으로 신뢰하기 전에 초기 출력을 실제 컴포넌트와 대조해 샘플 점검하세요.