Mozaic MCP Server

An MCP (Model Context Protocol) server that exposes the Mozaic Design System by ADEO to Claude and other AI assistants.

View Documentation | Try the Playground

Note: This project is under active development. Contributions and feedback are welcome!

What It Does

This server indexes the entire Mozaic Design System and makes it queryable through MCP tools. AI assistants can:

Look up design tokens (colors, spacing, typography, etc.)
Get component documentation with props, slots, events, and examples
Search and retrieve icons with SVG/React/Vue code
Search documentation pages
Generate component code snippets

Quick Start

pnpm install
pnpm build   # Compiles TypeScript & builds the database
pnpm start   # Starts the MCP server

What's Indexed

| Type | Count | Description | | -------------------- | ----- | --------------------------------------------------------------- | | Design Tokens | 586 | Colors, typography, spacing, shadows, borders, screens, grid | | Vue Components | 52 | Props, slots, events, examples | | React Components | 39 | Props, callbacks, examples | | Icons | 1,473 | SVG icons in 15 categories (354 unique, 5 sizes each) | | CSS Utilities | 6 | Flexy, Container, Margin, Padding, Ratio, Scroll (500+ classes) | | Documentation | 281 | MDX pages with full-text search |

Documentation sources:

Design System docs (220 pages)
Vue Storybook docs (58 pages) - Getting Started, Usage guides
React Storybook docs (3 pages) - Getting Started, Usage guides

MCP Tools

Component Tools

| Tool | Description | | -------------------------- | ---------------------------------------------------------------- | | get_component_info | Get Vue/React component details (props, slots, events, examples) | | list_components | List framework components by category | | generate_vue_component | Generate Vue component code | | generate_react_component | Generate React component code |

CSS Utility Tools

| Tool | Description | | -------------------- | ---------------------------------------------------------- | | get_css_utility | Get CSS utility classes and examples (Flexy, Margin, etc.) | | list_css_utilities | List available CSS utilities by category (layout, utility) |

Icon Tools

| Tool | Description | | -------------- | --------------------------------------------------------------------------- | | search_icons | Search icons by name, type (navigation, media, social), or size (16-64px) | | get_icon | Get icon details with SVG markup and ready-to-use React/Vue code |

Installation Tools

| Tool | Description | | ------------------ | ----------------------------------------------------------------------------------- | | get_install_info | Get installation commands, imports, and quick start code for a component (beta) |

Other Tools

| Tool | Description | | ---------------------- | ----------------------------------------------------------------------------------- | | get_design_tokens | Query tokens by category (color, spacing, typography, shadow, border, screen, grid) | | search_documentation | Full-text search across all docs |

Token Categories

| Category | Count | Examples | | ---------- | ----- | -------------------------------------------------- | | color | 482 | --color-primary-01-100, --color-button-solid-* | | typography | 60 | --font-size-*, --line-height-* | | spacing | 19 | $mu025 to $mu1000 (Magic Unit system) | | screen | 12 | Breakpoints: s, m, l, xl, xxl | | shadow | 3 | Box shadows with x, y, blur, spread, opacity | | border | 3 | Border widths | | radius | 3 | Border radius values | | grid | 4 | Gutters, magic-unit, rem values |

CSS Utilities

CSS-only layout and utility classes (no Vue/React wrapper). Use get_css_utility tool to get full class lists and examples.

| Utility | Category | Description | | ------------- | -------- | ---------------------------------------------- | | Flexy | layout | Flexbox 12-column grid with responsive classes | | Container | layout | Responsive container with max-width | | Margin | utility | Margin utilities using Magic Unit scale | | Padding | utility | Padding utilities using Magic Unit scale | | Ratio | utility | Aspect ratio utilities (16:9, 4:3, 1:1, etc.) | | Scroll | utility | Scroll prevention utility |

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Claude Desktop                          │
└─────────────────────────┬───────────────────────────────────┘
                          │ stdio
┌─────────────────────────▼───────────────────────────────────┐
│                    MCP Server                               │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Tools: get_component_info, get_css_utility, ...     │   │
│  └─────────────────────────┬───────────────────────────┘   │
│                            │                                │
│  ┌─────────────────────────▼───────────────────────────┐   │
│  │                 SQLite Database                     │   │
│  │  tokens | components | icons | css_utilities | docs │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                          ▲
                          │ build
┌─────────────────────────┴───────────────────────────────────┐
│                    Source Repositories                      │
│  mozaic-design-system  │  mozaic-vue  │  mozaic-react      │
└─────────────────────────────────────────────────────────────┘

Scripts

| Script | Description | | ----------------- | ------------------------------------- | | pnpm build | Compile TypeScript and build database | | pnpm build:docs | Generate documentation diagrams | | pnpm start | Start the MCP server | | pnpm dev | Development mode with watch | | pnpm clean | Remove dist and database | | pnpm test | Run unit tests | | pnpm database:sanity | Validate database integrity |

Documentation

docs/ARCHITECTURE.md - Architecture diagrams and statistics
docs/TEST.md - Testing guide

Next Steps

Benchmarking: MCP vs Claude Skills

Compare performance and effectiveness of MCP server approach vs native Claude skills:

[ ] Define benchmark scenarios (component lookup, code generation, documentation search)
[ ] Measure response accuracy and completeness
[ ] Compare token usage and latency
[ ] Evaluate context window efficiency
[ ] Document trade-offs and recommendations

Release Process

Steps to publish the MCP server:

[ ] npm registry: Publish to npm (npm publish)
[ ] Smithery: Submit to smithery.ai MCP marketplace
[ ] GitHub release: Create tagged release with changelog
[ ] Claude Desktop config: Document installation in claude_desktop_config.json
[ ] Version strategy: Define semver policy for database schema changes

Future Improvements

[ ] Incremental database updates (avoid full rebuild)
[ ] Watch mode for local development
[ ] Caching layer for frequently accessed data
[ ] Support for custom/extended tokens
[ ] Multi-language documentation support

Version History

Compatibility with Mozaic Design System versions:

| MCP Server | Mozaic Version | Date | Changes | | ---------- | -------------- | ---------- | -------------------------------------------- | | 1.0.0 | 2.x | 2024-12 | Initial release with Vue 3, React, CSS utils |

Mozaic Repositories Indexed

| Repository | Branch | Description | | ----------------------- | ------ | ------------------------ | | mozaic-design-system | main | Tokens, docs, styles | | mozaic-vue | main | Vue 3 components | | mozaic-react | main | React components |

Updating for New Mozaic Versions

When a new Mozaic version is released:

Pull latest changes: pnpm build (clones/updates repos automatically)
Run sanity check: pnpm database:sanity
Run tests: pnpm test
Update version table above
Tag release: git tag vX.Y.Z

License

MIT

MCP Servers