Refero MCP

styles.refero.design을 평이한 영어로 검색하고 모든 프로젝트에 DESIGN.md를 추가하세요.

빠른 탐색

이것은 무엇인가

Refero Styles는 색상, 타이포그래피, 간격, 스타일별 권장/금지 사항을 추출하는 고된 작업을 대신 수행해 주는 약 200개의 큐레이션된 사이트 카탈로그입니다. 각 항목은 DESIGN.md가 될 준비가 된 designSystem 블록과 함께 제공됩니다.

이 MCP는 해당 카탈로그를 래핑하여 Claude Code가 자연어로 검색하고, 스캐폴딩 중인 모든 프로젝트에 생성된 DESIGN.md를 바로 드롭할 수 있도록 합니다. 브라우저 탭에서 JSON을 복사/붙여넣기하거나 수동으로 토큰 테이블을 만들 필요가 없습니다.

첫 번째 컴포넌트가 렌더링되기 전에 디자인 언어를 고정하고 싶어 하는 새로운 앱, 데크 또는 클라이언트 프로젝트를 시작하는 Claude Code 사용자들을 위한 도구입니다.

빠른 설치

한 줄 명령어:

claude mcp add refero -- npx -y fidgetcoding-refero-mcp

Claude Code를 재시작하고 원하는 디자인을 설명하기 시작하세요.

바이브 검색(각 스타일의 시적인 northStar 요약에 대한 의미론적 순위 지정)을 원하시면 OpenAI 키를 전달하세요:

claude mcp add refero --env OPENAI_API_KEY=sk-... -- npx -y fidgetcoding-refero-mcp

키가 없으면 검색은 키워드 점수 방식으로 대체됩니다. 잘 작동하지만 마법 같은 느낌은 덜합니다.

claude_desktop_config.json 사용자의 경우:

{
  "mcpServers": {
    "refero": {
      "command": "npx",
      "args": ["-y", "fidgetcoding-refero-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "REFERO_MCP_VAULT_DIR": "/absolute/path/to/your/vault"
      }
    }
  }
}

사용법

깔끔하게 라우팅되는 몇 가지 프롬프트 예시:

"Find me a dark editorial style with a serif and a warm accent."

"Pull the full breakdown for Linear."

"What's similar to Vercel in the Refero catalog?"

"Render Cursor's DESIGN.md — don't save it yet, just show me."

"Save Cursor's DESIGN.md into my PARZVL project."

"Show me only dark-mode brutalist styles, top five."

"Refresh the Refero catalog before we start the design pass."

더 많은 레시피는 docs/USAGE.md에서 확인하세요.

도구

구성

모든 설정은 선택 사항입니다. 기본값은 MCP가 바로 실행되도록 설정되어 있습니다.

복사/붙여넣기 가능한 .env.example이 저장소 루트에 포함되어 있습니다.

REFERO_MCP_VAULT_DIR에 대한 기본값은 없습니다. 이전 초안에는 제 노트북 경로가 하드코딩되어 있었는데, 이는 지구상에서 딱 한 대의 기계에서만 잘 작동했습니다. 검토자가 이를 발견했습니다. 이제 설정하지 않으면 도구가 쓰기를 거부합니다. 다소 무례하게 들릴 수 있지만, 컴퓨터에 존재하지 않는 폴더에 파일을 떨어뜨리는 것보다는 낫습니다.

작동 원리

작성 시점 기준으로 공개된 Refero API 문서는 없으며, 형태는 라이브 사이트를 기반으로 경험적으로 매핑되었습니다. 전체 분석은 docs/api-surface.md에 있으므로 나중에 다시 발견할 필요가 없습니다.

• 로컬 카탈로그 미러. Refero는 ?page=N 페이지네이션을 노출하지만 ?search=, ?q=, ?colorScheme=은 무시합니다. 따라서 이 MCP는 페이지를 한 번 순회하고 REFERO_CACHE_DIR 아래에 로컬로 미러링한 다음, 모든 필터링과 순위 지정을 클라이언트 측에서 실행합니다.

• northStar를 통한 바이브 검색. 모든 Refero 스타일은 northStar라는 한 줄짜리 시적 요약과 함께 제공됩니다. OPENAI_API_KEY가 설정되면 MCP는 text-embedding-3-small을 사용하여 해당 요약을 임베딩하고 쿼리와의 코사인 유사도에 따라 순위를 매깁니다. 키가 없으면 northStar + 태그 + 사이트 이름을 기반으로 키워드 점수 방식으로 대체됩니다.

• 로컬에서 생성된 DESIGN.md. Refero는 /design.md 엔드포인트를 노출하지 않습니다. MCP는 style.fullResult.designSystem(권장 사항, 금지 사항, 태그, 테마, 역할별 색상)에서 하나를 합성합니다. 출력은 /stitch-design-taste 및 /design-taste-frontend 스킬과 호환됩니다.

문제 해결

"No styles found" / 카탈로그가 비어 있는 경우. 첫 실행 시에는 캐시가 비어 있습니다. Claude에게 한 번 *"refresh the Refero catalog"*라고 요청하세요. 250ms의 간격을 두고 약 10페이지를 순회하여 REFERO_CACHE_DIR에 기록합니다. 그 후에는 검색이 즉시 이루어집니다.

검색 결과가 의미론적이지 않고 키워드 위주인 경우. 아마도 OPENAI_API_KEY가 설정되지 않았을 것입니다. MCP 구성에 추가하고 재시작하거나, 카탈로그의 어휘(산업군 및 editorial, brutalist, glass와 같은 태그)를 더 적극적으로 활용하세요.

refero_design_md가 마크다운을 반환하지만 디스크에 기록하지 않는 경우. REFERO_MCP_VAULT_DIR이 설정되지 않았습니다. 볼트 루트(절대 경로)로 설정하면 도구가 <vault>/05-Projects/<NAME>/DESIGN.md에 기록합니다. 설정하지 않으면 대화창에서 마크다운을 받아 원하는 곳에 붙여넣을 수 있습니다.

라이선스

MIT — 자세한 내용은 LICENSE를 참조하세요.

저자

Nate Davidovich / Lorecraft LLC 제작.

• GitHub: lorecraft-io

• npm: lorecraft

• 자매 프로젝트: morgen-mcp, motion-mcp

⤴ 맨 위로 돌아가기

보안: gitleaks 스캔

이 저장소에는 .gitleaks.toml 구성과 작업 트리에서 비밀(GitHub 토큰, API 키, JWT, 개인 키, Anthropic 키 등)을 스캔하는 scripts/security-scan.sh 도우미가 포함되어 있습니다.

bash scripts/security-scan.sh

.husky/pre-commit 훅은 모든 커밋 시 gitleaks protect --staged를 실행하며, gitleaks가 로컬에 설치되어 있지 않으면 경고를 표시합니다.

아직 설치하지 않았다면:

• macOS: brew install gitleaks

• Linux: https://github.com/gitleaks/gitleaks/releases