io.github.MerzoukeMansouri/mozaic

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)

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

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

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:

1. Component selection
2. Props configuration
3. Code generation
4. 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

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

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:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes using Conventional Commits
4. Push to the branch (git push origin feature/amazing-feature)
5. 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