How do I install Mozaic?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Mozaic need an API key?

No required environment variable is listed on this record.

What transport does Mozaic use?

Mozaic runs locally over stdio.

When was Mozaic last checked?

Last checked 2026-11-09. Mozaic Design System (ADEO): tokens, components, icons, docs and style guides for any agent.

Mozaic MCP server

Mozaic MCP Server

MCP server and agent skills for the Mozaic Design System by ADEO, for any coding agent: Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, ...

📚 Documentation • 🎮 MCP Playground • 🌐 Website

Overview

This package provides two complementary tools for working with the Mozaic Design System in coding agents:

🤖 Agent Skills - 8 interactive skills for guided component building and design token usage
🔌 MCP Server - Model Context Protocol server with 19 tools for programmatic access to Mozaic resources

HTTP API

Coding agents should use the local stdio server (npx -y mozaic-mcp-server@2, see Quick Start). The HTTP API is a separate, token-protected server for web tools (e.g. v0) that cannot spawn a local process.

Public server: https://mozaic-mcp.m14i.com (Swagger)

Method	Route	Description
GET	`/health`	Health check (public)
GET	`/api`	Swagger UI (public)
POST	`/mcp`	JSON-RPC 2.0 MCP endpoint, full 19 tools
GET	`/mcp/info`	Server info
POST	`/mcp/list-tools`	List the 19 tools
POST	`/mcp/call-tool`	Call a tool
POST	`/mcp/light`	JSON-RPC 2.0 "MCP Light" endpoint (`initialize`, `initialized`, `tools/list`, `tools/call`)
POST	`/mcp/light/list-tools`	List the 7 light tools
POST	`/mcp/light/call-tool`	Call a light tool

Full vs light: the full endpoints proxy to a spawned stdio MCP server and expose all 19 tools. The light endpoints read SQLite directly (no subprocess, faster) and expose 7 tools: get_design_tokens, list_css_utilities, get_css_utility, search_icons, get_icon, list_style_guides, get_style_guide (get_style_guide returns the screenshot as a PNG image block).

Authentication: Authorization: Bearer <token> on every route except /health and /api. Contact me on Slack for a token.

Call a tool: body is {"name": "<tool>", "arguments": {...}}.

curl -X POST https://mozaic-mcp.m14i.com/mcp/light/call-tool \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"search_icons","arguments":{"query":"arrow","limit":5}}'

Self-hosting env vars: PORT (3000), AUTH_TOKEN, DATABASE_PATH (/app/data/mozaic.db), MCP_SERVER_PATH (/app/dist/index.js), MCP_DEBUG. See DEPLOYMENT.md.

What's Included

Resource Type	Count	Description
Design Tokens	586	Colors, typography, spacing, shadows, borders, breakpoints
Components	191	Vue 3, React, Web Components, and Freemarker macros with full documentation
Icons	1,473	SVG icons across 15 categories
CSS Utilities	6	Flexy grid, Container, Margin, Padding, Ratio, Scroll
Documentation	309	Searchable usage guides and best practices
MCP Tools	19	Programmatic access to all resources
Agent Skills	8	Interactive workflows for Vue, React, Web Components, Freemarker, and agnostic use
Style Guides	16	Composed screen patterns with screenshots

Quick Start

Works with any coding agent that supports Agent Skills and/or MCP: Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf, VS Code, ...

Install

Two standard, agent-agnostic CLIs. Each detects your agents and writes to the current project by default:

npx skills add MerzoukeMansouri/adeo-mozaic-mcp        # 8 skills -> .agents/skills/, .claude/skills/, ...
npx add-mcp mozaic-mcp-server@2 --name mozaic           # MCP server -> .mcp.json, .cursor/mcp.json, .vscode/mcp.json, .codex/config.toml, ...

npx skills and npx add-mcp both accept -g (your user instead of the project), -a <agent> (target specific agents) and -y (no prompts).
The skills' scripts install their database (~/.mozaic/mozaic.db) on first use. Refresh it any time with npx -y -p mozaic-mcp-server@2 mozaic-db.
Remove: npx skills remove <skill> and npx add-mcp remove mozaic.

Project or global?

Project (default, recommended): commit the generated files so the whole team gets the same setup, and skills are only loaded in Mozaic projects.
Global (-g): for your user across every project, nothing to commit.
Never npm i -g: agents run the server with npx -y mozaic-mcp-server@2, which stays on major version 2 and picks up fixes.

Try Before Installing

Test all 19 MCP tools directly in your browser, without installation:

🎮 Open MCP Playground

Agent Skills

8 skills that provide interactive workflows for building with Mozaic.

Available Skills

Skill	Description	Use Case
mozaic-vue-builder	Interactive Vue 3 component generator	Building Vue apps with Mozaic
mozaic-react-builder	Interactive React/TSX component generator	Building React apps with Mozaic
mozaic-webcomponents-builder	Interactive Web Components generator	Building framework-agnostic apps with native web components
mozaic-freemarker-builder	Interactive Freemarker macro generator	Building server-side templates with Freemarker
mozaic-design-tokens	Design tokens and styling expert	Accessing colors, typography, spacing
mozaic-css-utilities	CSS utility classes and layouts	Building responsive layouts
mozaic-icons	Icon search and integration	Finding and using Mozaic icons
mozaic-style-guide	Composed-pattern catalog (framework-agnostic)	Reference real Mozaic-compliant screens before building (modals, dashboards, tables, ...)

How Skills Work

Skills follow the Agent Skills format (skills/<name>/SKILL.md), so any compatible agent activates them automatically based on context:

User: "I need a login form with Mozaic"

The agent activates the appropriate skill (e.g. Vue or React builder) and guides you through:

Component selection
Props configuration
Code generation
Installation instructions

See SKILLS.md for detailed documentation.

MCP Server Tools

19 programmatic tools for accessing Mozaic resources via the Model Context Protocol.

Available Tools

Tool	Category	Description
`get_design_tokens`	Tokens	Query tokens by category (colors, typography, spacing, etc.)
`get_component_info`	Components	Get component props, slots, events, and documentation
`list_components`	Components	List components by category or framework
`generate_vue_component`	Code Gen	Generate Vue 3 SFC code with props
`generate_react_component`	Code Gen	Generate React/TSX code with TypeScript
`generate_webcomponent`	Code Gen	Generate native Web Component HTML with imports
`get_webcomponent_info`	Web Components	Get attributes, slots, events, CSS properties
`list_webcomponents`	Web Components	List web components by category
`generate_freemarker`	Code Gen	Generate Freemarker macro code with configuration
`get_freemarker_info`	Freemarker	Get macro configuration options and usage
`list_freemarker`	Freemarker	List Freemarker macros by category
`search_documentation`	Docs	Full-text search across 309 documentation pages
`get_css_utility`	CSS	Get CSS utility classes and examples
`list_css_utilities`	CSS	List available CSS utilities
`search_icons`

Configuration

npx add-mcp mozaic-mcp-server@2 --name mozaic writes the right file for each agent. The server name must be mozaic (the mozaic-style-guide skill expects it). Manual setup, for example .mcp.json (Claude Code) or .cursor/mcp.json (Cursor):

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

VS Code uses a servers key in .vscode/mcp.json; Codex uses [mcp_servers.mozaic] in .codex/config.toml.

The server is also published to the MCP Registry as io.github.MerzoukeMansouri/mozaic.

Usage Examples

Using Skills

Skills activate automatically based on your request:

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

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

Using MCP Tools Programmatically

When configured, the agent can use MCP tools directly:

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

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

Architecture

            Any coding agent
     ┌──────────────┴──────────────┐
     ▼                             ▼
 Skills (8)                  MCP server (19 tools, stdio)
 24 shell scripts + sqlite3  npx -y mozaic-mcp-server@2
     │                             │
     ▼                             ▼
 ~/.mozaic/mozaic.db         data/mozaic.db (packaged)

Both are the same SQLite database: 586 tokens, 191 components, 1,473 icons, 309 docs, 16 style guides. Skills never need the MCP server: every skill, including mozaic-style-guide (screenshots are stored in the database), works from its scripts alone.

File Locations

What	Project (default)	Global (`-g`)
Skills	`.agents/skills/`, `.claude/skills/`, ... per agent	`~/.claude/skills/`, `~/.codex/skills/`, `~/.cursor/skills/`, ...
MCP config	`.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json`, `.codex/config.toml`, ...	`~/.claude.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`, ...
Skills database	`~/.mozaic/mozaic.db` (override with `MOZAIC_DB_PATH`)	same

Development

Prerequisites

Node.js ≥25.2.0
pnpm (recommended)

Setup

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

# 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

Project Structure

mozaic-mcp-server/
├── src/                    # TypeScript source code
│   ├── index.ts           # stdio MCP server entry point
│   ├── main.ts            # NestJS HTTP server entry point
│   ├── tools/             # MCP tool implementations
│   ├── mcp/               # HTTP controllers (full + light)
│   ├── parsers/           # Source repo parsers
│   └── db/                # Schema and queries
├── skills/                # Agent Skills (SKILL.md)
│   ├── mozaic-vue-builder/
│   │   ├── SKILL.md       # Skill instructions
│   │   └── scripts/       # Shell scripts
│   └── ...                # Other skills
├── scripts/               # Build and utility scripts
│   ├── build-index.ts     # Database builder
│   ├── sanity-check.ts    # Database sanity check
│   └── generate-docs.ts   # Documentation generator
├── data/                  # Generated database
│   └── mozaic.db
├── repos/                 # Source repos, cloned by `pnpm build` (gitignored)
├── style-guides/          # Hand-authored patterns (meta.json + screenshot.png)
├── bin/mozaic-db.js       # installs the skills database to ~/.mozaic/mozaic.db
└── website/               # Documentation website

Building the Database

pnpm build compiles TypeScript, then clones (or pulls) the source repos into repos/ and builds data/mozaic.db:

adeo/mozaic-design-system (public): tokens, icons, docs
adeo/mozaic-vue, mozaic-react, mozaic-web-components, mozaic-freemarker (private, need GitHub access)
style-guides/<slug>/ (in this repo)

Check it with pnpm database:sanity.

Contributing

Contributions are welcome! Please follow these guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes using Conventional Commits
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Commit Convention

We use semantic versioning with conventional commits:

feat: - New feature (minor version bump)
fix: - Bug fix (patch version bump)
feat!: or BREAKING CHANGE: - Breaking change (major version bump)
chore:, docs:, style:, refactor:, test: - No version bump

Resources

Documentation & Tools

🌐 Website: https://merzoukemansouri.github.io/adeo-mozaic-mcp/
📚 Documentation: https://merzoukemansouri.github.io/adeo-mozaic-mcp/#/docs
🎮 MCP Playground: https://merzoukemansouri.github.io/adeo-mozaic-mcp/#/playground
🎨 Skills Guide: https://merzoukemansouri.github.io/adeo-mozaic-mcp/#/skills
GitHub: https://github.com/MerzoukeMansouri/adeo-mozaic-mcp
npm: https://www.npmjs.com/package/mozaic-mcp-server

Related Resources

Mozaic Design System: https://mozaic.adeo.cloud/
MCP Protocol: https://modelcontextprotocol.io/
Agent Skills spec: https://agentskills.io/specification

License

MIT License - see LICENSE file for details.

Support

For issues or questions:

🌐 Visit the website
📚 Read the documentation
🎮 Try the MCP playground
🐛 Open an issue on GitHub
📖 Check the Skills guide
🎨 Review Mozaic Design System docs

Built with ❤️ for the ADEO community

Mozaic Design System is maintained by ADEO