aurum-mcp

LLM 클라이언트에서 Aurum 디자인 시스템과 대화하세요. 컴포넌트 · 토큰 · 아이콘 · Figma 노드 ID · 변경 로그 — 이 모든 것을 Claude Code, Cursor, Copilot CLI, Gemini 및 Claude Desktop에서 쿼리할 수 있습니다.

aurum-mcp는 Aurum 디자인 시스템 카탈로그를 LLM에 제공하는 Model Context Protocol 서버입니다. 이 서버는 번들된 JSON 매니페스트(changejarapp.github.io/aurum-android에서 자동 동기화됨)를 읽고, LLM이 다음과 같은 질문에 답할 수 있도록 9가지 도구를 노출합니다:

• "AurumChip 사용 방법을 알려줘."

• "부정적 피드백 텍스트에 사용하는 색상 토큰은 무엇인가요?"

• "AurumTopAppBar의 Figma 노드는 무엇인가요?"

• "뒤로 가기 화살표 아이콘을 알려줘."

• "최근 릴리스에서 변경된 사항은 무엇인가요?"

설치 (한 번 붙여넣기로 모든 클라이언트 적용)

아래에서 클라이언트를 선택하고, 해당 설정 파일에 스니펫을 붙여넣은 뒤 클라이언트를 재시작하세요.

Claude Code (프로젝트 루트의 .mcp.json 또는 ~/.claude.json)

{
  "mcpServers": {
    "aurum": {
      "command": "npx",
      "args": ["-y", "github:atri-jar/aurum-mcp#latest-stable"]
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "aurum": {
      "command": "npx",
      "args": ["-y", "github:atri-jar/aurum-mcp#latest-stable"]
    }
  }
}

Copilot CLI (~/.copilot/mcp.json)

{
  "mcpServers": {
    "aurum": {
      "command": "npx",
      "args": ["-y", "github:atri-jar/aurum-mcp#latest-stable"]
    }
  }
}

Gemini CLI (~/.gemini/settings.json의 mcpServers 항목)

{
  "mcpServers": {
    "aurum": {
      "command": "npx",
      "args": ["-y", "github:atri-jar/aurum-mcp#latest-stable"]
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)

동일한 형식입니다. 위 스니펫을 mcpServers에 추가하세요. 앱을 재시작합니다.

끝입니다. npm 레지스트리, ~/.npmrc, PAT, 환경 변수가 필요 없습니다. 공개 Git, 공개 npx만 있으면 됩니다.

버전 관리

기본 스니펫은 항상 최신 안정 릴리스를 가리키는 CI 관리 Git 태그인 #latest-stable을 사용합니다. npm의 @latest dist-tag와 유사하게 작동하며, npx 캐시가 누락될 때마다(클라이언트 캐시에 따라 약 10분에서 몇 시간 소요) 자동 업데이트를 받습니다.

재현 가능성(자동화된 스크립트, 감사된 설정 등)을 위해서는 명시적 태그를 고정하세요:

"args": ["-y", "github:atri-jar/aurum-mcp#v0.1.0"]

aurum-mcp의 모든 버전은 일치하는 Aurum 라이브러리 버전의 매니페스트를 제공합니다 (@aurum-mcp:0.1.6 ⇄ aurum:0.1.6). LLM 클라이언트에서 get_aurum_version을 호출하여 현재 사용 중인 버전을 정확히 확인하세요.

도구

전체 입력 스키마와 응답 예시는 docs/tools.md를 참조하세요.

왜 npm이 아닌 npx-from-Git인가요?

세 가지 배포 채널(공개 npm, GitHub Packages, npx-from-Git)을 고려했으며, 단순성, 완전한 소유권, 새로운 인프라 제로를 최적화하기 위해 세 번째 방식을 선택했습니다:

• 관리할 새로운 계정 제로. npm 조직, NPM_TOKEN 교체, 2FA 복구, 72시간 게시 영구 유지에 대한 불안이 없습니다. 저장소 자체가 처음부터 끝까지 아티팩트입니다.

• 브랜치 기반 테스트 무료 제공. 기능 브랜치를 테스트하고 싶으신가요? 스니펫을 #feat/branch-name으로 변경하기만 하면 됩니다. npm을 사용하면 레지스트리에 영원히 남는 프리릴리스 태그를 게시해야 합니다.

• 이미 사용 중인 인증 방식. 이 저장소는 공개되어 있으며, 팀원들은 GitHub 접근 권한을 가지고 있으므로 새로 설정할 것이 없습니다.

• 미미한 설치 지연. 첫 실행 시 클론 + 빌드에 약 510초가 소요되며, npm의 25초와 비교됩니다. 캐시된 실행은 동일합니다.

우리가 감수하는 트레이드오프: 다소 투박한 버전 고정 UX(Git 태그 vs semver 범위)와 공개 npm 검색 기능 부재. 전체적인 이유는 docs/architecture.md에 있습니다.

로컬 개발

git clone https://github.com/atri-jar/aurum-mcp.git
cd aurum-mcp
pnpm install
pnpm dev          # run the server via tsx + stdio
pnpm inspect      # spawn the official MCP Inspector UI
pnpm build        # tsc → dist/
pnpm smoke        # end-to-end tools/list + tools/call test

서버는 (커밋된) data/manifest.json을 읽습니다. 라이브 Aurum 갤러리에서 최신 매니페스트를 가져와 번들된 복사본을 업데이트하려면 다음을 수행하세요:

make manifest-fetch

CI가 이를 자동으로 수행합니다(.github/workflows/sync-manifest.yml 참조).

아키텍처 요약

Aurum 디자인 시스템은 Changejarapp/aurum-android(비공개)에 존재하며 changejarapp.github.io/aurum-android에서 공개 갤러리를 제공합니다. tooling/gallery/generate.py 스크립트는 단일 파서 세트에서 컴포넌트, 토큰, 아이콘, Code Connect 매핑 및 변경 로그를 집계합니다. 우리는 동일한 데이터의 구조화된 JSON 프로젝션을 생성하는 --emit-manifest 플래그를 추가했습니다. 계약은 aurum-android의 tooling/manifest/schema.json입니다. 이 MCP 서버는 해당 JSON의 읽기 전용 인터페이스로, 부팅 시 매니페스트를 로드하고 인덱싱하여 위의 9가지 도구를 제공합니다. 단일 진실 공급원(Single Source of Truth)과 두 개의 렌더링 대상(사람을 위한 HTML, 에이전트를 위한 JSON)을 가집니다. aurum-ios가 출시되면 해당 매니페스트가 형제 소스로 연결되며, MCP 코드는 플랫폼에 구애받지 않습니다.

전체 파이프라인 다이어그램: docs/architecture.md.

기여

이슈와 PR을 환영합니다. 워크플로우(매니페스트 동기화, 드리프트 체크, 릴리스 프로세스)는 docs/contributing.md를 참조하세요. 코드 스타일: TypeScript strict, Prettier 기본값; 마크다운 포맷터에는 비즈니스 로직을 포함하지 않습니다.

라이선스

MIT — LICENSE를 참조하세요.