Mozaic MCP 서버

npm version npm downloads License: MIT Documentation

ADEO의 Mozaic 디자인 시스템을 위한 독립형 Claude Code 스킬 및 MCP 서버입니다.

📚 문서 • 🎮 MCP 플레이그라운드

개요

이 패키지는 AI 어시스턴트에서 Mozaic 디자인 시스템을 작업하기 위한 두 가지 상호 보완적인 도구를 제공합니다:

🤖 Claude Code 스킬 - 컴포넌트 빌드 및 디자인 토큰 사용을 안내하는 7가지 대화형 스킬
🔌 MCP 서버 - Mozaic 리소스에 프로그래밍 방식으로 접근할 수 있는 17가지 도구를 포함한 모델 컨텍스트 프로토콜 서버

포함된 내용

리소스 유형	개수	설명
디자인 토큰	586	색상, 타이포그래피, 간격, 그림자, 테두리, 중단점
컴포넌트	131+	Vue 3, React, 웹 컴포넌트 및 전체 문서가 포함된 Freemarker 매크로
아이콘	1,473	15개 카테고리의 SVG 아이콘
CSS 유틸리티	6	Flexy 그리드, 컨테이너, 마진, 패딩, 비율, 스크롤
문서	281	검색 가능한 사용 가이드 및 모범 사례
MCP 도구	17	모든 리소스에 대한 프로그래밍 방식 접근
Claude 스킬	7	Vue, React, 웹 컴포넌트, Freemarker 및 범용 사용을 위한 대화형 워크플로우

빠른 시작

대화형 설치 (권장)

npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools

화살표 키와 스페이스바를 사용하여 컴포넌트를 선택한 후 Enter 키를 눌러 설치하세요.

한 줄 명령어로 설치

# Install everything (skills + MCP server)
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools all

# Install only skills (for Claude Code)
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools skills

# Install only MCP server (for Claude Desktop)
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools mcp

설치 상태 확인

npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools list

설치 전 체험하기

설치 없이 브라우저에서 직접 MCP 도구를 테스트해보세요:

🎮 MCP 플레이그라운드 열기

플레이그라운드에서 다음을 수행할 수 있습니다:

11가지 MCP 도구를 대화형으로 테스트
컴포넌트, 토큰 및 아이콘 탐색
코드 스니펫 생성
문서 검색

Claude Code 스킬

Mozaic으로 빌드하기 위한 대화형 워크플로우를 제공하는 6가지 독립형 스킬입니다.

사용 가능한 스킬

스킬	설명	사용 사례
mozaic-vue-builder	대화형 Vue 3 컴포넌트 생성기	Mozaic으로 Vue 앱 빌드
mozaic-react-builder	대화형 React/TSX 컴포넌트 생성기	Mozaic으로 React 앱 빌드
mozaic-webcomponents-builder	대화형 웹 컴포넌트 생성기	네이티브 웹 컴포넌트로 프레임워크 독립적 앱 빌드
mozaic-freemarker-builder	대화형 Freemarker 매크로 생성기	Freemarker로 서버 사이드 템플릿 빌드
mozaic-design-tokens	디자인 토큰 및 스타일링 전문가	색상, 타이포그래피, 간격 접근
mozaic-css-utilities	CSS 유틸리티 클래스 및 레이아웃	반응형 레이아웃 빌드
mozaic-icons	아이콘 검색 및 통합	Mozaic 아이콘 찾기 및 사용

스킬 작동 방식

스킬은 컨텍스트에 따라 Claude Code에서 자동으로 활성화되거나 수동으로 호출할 수 있습니다:

User: "I need a login form with Mozaic"

Claude Code는 적절한 스킬(Vue 또는 React 빌더)을 자동으로 활성화하고 다음 과정을 안내합니다:

컴포넌트 선택
Props 구성
코드 생성
설치 지침

자세한 문서는 SKILLS.md를 참조하세요.

MCP 서버 도구

모델 컨텍스트 프로토콜을 통해 Mozaic 리소스에 접근하기 위한 14가지 프로그래밍 도구입니다.

사용 가능한 도구

도구	카테고리	설명
`get_design_tokens`	토큰	카테고리별 토큰 쿼리 (색상, 타이포그래피, 간격 등)
`get_component_info`	컴포넌트	컴포넌트 props, 슬롯, 이벤트 및 문서 가져오기
`list_components`	컴포넌트	카테고리 또는 프레임워크별 컴포넌트 나열
`generate_vue_component`	코드 생성	Props가 포함된 Vue 3 SFC 코드 생성
`generate_react_component`	코드 생성	TypeScript가 포함된 React/TSX 코드 생성
`generate_webcomponent`	코드 생성	임포트가 포함된 네이티브 웹 컴포넌트 HTML 생성
`get_webcomponent_info`	웹 컴포넌트	속성, 슬롯, 이벤트, CSS 속성 가져오기
`list_webcomponents`	웹 컴포넌트	카테고리별 웹 컴포넌트 나열
`generate_freemarker`	코드 생성	구성 정보가 포함된 Freemarker 매크로 코드 생성
`get_freemarker_info`	Freemarker	매크로 구성 옵션 및 사용법 가져오기
`list_freemarker`	Freemarker	카테고리별 Freemarker 매크로 나열
`search_documentation`	문서	281개 문서 페이지 전체 텍스트 검색
`get_css_utility`	CSS	CSS 유틸리티 클래스 및 예제 가져오기
`list_css_utilities`	CSS	사용 가능한 CSS 유틸리티 나열
`search_icons`	아이콘	이름, 유형 또는 카테고리별로 1,473개 아이콘 검색
`get_icon`	아이콘	아이콘 SVG 및 프레임워크 코드 가져오기
`get_install_info`	설치	npm/yarn/pnpm 설치 명령어 가져오기

구성

Claude Code 또는 Claude Desktop 설정에 추가하세요:

Claude Code의 경우 (.claude/settings.json):

{
  "mcpServers": {
    "mozaic": {
      "command": "npx",
      "args": ["-y", "mozaic-mcp-server"]
    }
  }
}

Claude Desktop의 경우 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mozaic": {
      "command": "npx",
      "args": ["-y", "mozaic-mcp-server"]
    }
  }
}

사용 예시

Claude Code에서 스킬 사용하기

스킬은 요청에 따라 자동으로 활성화됩니다:

You: "I need a responsive grid with 3 columns"
Claude: [activates mozaic-css-utilities skill]
        Here's the Flexy grid solution...

You: "Add a shopping cart icon"
Claude: [activates mozaic-icons skill]
        I found these cart icons...

프로그래밍 방식으로 MCP 도구 사용하기

구성되면 Claude는 MCP 도구를 직접 사용할 수 있습니다:

You: "What design tokens are available?"
Claude: [calls get_design_tokens tool]
        Found 586 tokens across 7 categories...

You: "Generate a React button component"
Claude: [calls get_component_info, then generate_react_component]
        Here's your Button component with TypeScript...

CLI 명령어

adeo-mozaic-install-tools CLI는 여러 명령어를 제공합니다:

# Interactive mode (default)
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools

# Install all components
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools all

# Install skills only
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools skills

# Install MCP server only
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools mcp

# Check status
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools list

# Remove components
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools remove skills
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools remove mcp
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools remove all

# Show help
npx -p mozaic-mcp-server@latest adeo-mozaic-install-tools --help

아키텍처

┌─────────────────────────────────────┐
│   Claude Code / Claude Desktop      │
│                                     │
│   ┌─────────────┐  ┌─────────────┐ │
│   │   Skills    │  │ MCP Server  │ │
│   │  (5 total)  │  │ (11 tools)  │ │
│   └─────────────┘  └─────────────┘ │
│          │                │         │
└──────────┼────────────────┼─────────┘
           │                │
           ▼                ▼
    ┌──────────────────────────┐
    │  Shell Scripts (14)      │
    │  ↓ sqlite3 queries       │
    └──────────────────────────┘
               ▼
    ┌──────────────────────────┐
    │  SQLite Database         │
    │  ~/.claude/mozaic.db     │
    │                          │
    │  • 586 tokens            │
    │  • 91 components         │
    │  • 1,473 icons           │
    │  • 281 docs              │
    └──────────────────────────┘

파일 위치

설치 후:

~/.claude/
├── mozaic.db                      # SQLite database (all Mozaic data)
├── skills/                        # Claude Code skills
│   ├── mozaic-vue-builder/
│   ├── mozaic-react-builder/
│   ├── mozaic-design-tokens/
│   ├── mozaic-css-utilities/
│   └── mozaic-icons/
└── (Claude Code settings.json)    # MCP server config

~/Library/Application Support/Claude/
└── claude_desktop_config.json     # Claude Desktop MCP config

개발

사전 요구 사항

Node.js ≥25.2.0
pnpm (권장)

설정

# Clone the repository
git clone https://github.com/MerzoukeMansouri/adeo-mozaic-mcp.git
cd mozaic-mcp-server

# Install dependencies
pnpm install

# Build the project (compiles TypeScript + builds database)
pnpm build

# Run tests
pnpm test

# Start MCP server in debug mode
pnpm start:debug

프로젝트 구조

mozaic-mcp-server/
├── src/                    # TypeScript source code
│   ├── index.ts           # MCP server entry point
│   ├── tools/             # MCP tool implementations
│   └── database/          # Database utilities
├── skills/                # Claude Code skills
│   ├── mozaic-vue-builder/
│   │   ├── skill.md       # Skill instructions
│   │   └── scripts/       # Shell scripts (4)
│   └── ...                # Other skills
├── scripts/               # Build and utility scripts
│   ├── build-index.ts     # Database builder
│   └── generate-docs.ts   # Documentation generator
├── data/                  # Generated database
│   └── mozaic.db
├── repos/                 # Mozaic Design System repositories (git submodules)
│   ├── mozaic-design-system/
│   ├── mozaic-vue/
│   └── mozaic-react/
├── bin/                   # CLI entry points
│   └── install.js         # Installation CLI
└── website/               # Documentation website

데이터베이스 빌드

SQLite 데이터베이스는 Mozaic 디자인 시스템 저장소에서 빌드됩니다:

# Update submodules
git submodule update --init --recursive

# Build database
pnpm build

다음 항목을 인덱싱합니다:

mozaic-design-system/packages/tokens의 디자인 토큰
mozaic-vue 및 mozaic-react의 컴포넌트
mozaic-design-system/packages/icons의 아이콘
모든 저장소의 문서

기여

기여를 환영합니다! 다음 가이드라인을 따라주세요:

저장소 포크
기능 브랜치 생성 (git checkout -b feature/amazing-feature)
Conventional Commits를 사용하여 변경 사항 커밋
브랜치로 푸시 (git push origin feature/amazing-feature)
Pull Request 열기

커밋 컨벤션

의미론적 버전 관리와 Conventional Commits를 사용합니다:

feat: - 새로운 기능 (마이너 버전 업데이트)
fix: - 버그 수정 (패치 버전 업데이트)
feat!: 또는 BREAKING CHANGE: - 주요 변경 사항 (메이저 버전 업데이트)
chore:, docs:, style:, refactor:, test: - 버전 업데이트 없음

리소스

문서 및 도구

📚 문서: https://merzoukemansouri.github.io/adeo-mozaic-mcp/
🎮 MCP 플레이그라운드: https://merzoukemansouri.github.io/adeo-mozaic-mcp/#/playground
GitHub: https://github.com/MerzoukeMansouri/adeo-mozaic-mcp
npm: https://www.npmjs.com/package/mozaic-mcp-server

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE 파일을 참조하세요.

지원

문제나 질문이 있는 경우:

📚 온라인 문서 읽기
🎮 MCP 플레이그라운드 체험하기
🐛 GitHub에 이슈 열기
📖 스킬 문서 확인하기
🎨 Mozaic 디자인 시스템 문서 검토하기

ADEO 커뮤니티를 위해 ❤️로 제작됨

Mozaic 디자인 시스템은 ADEO에서 유지 관리합니다

Mozaic MCP Server