Servidor MCP de Mozaic

npm version npm downloads License: MIT Documentation

Skills de Claude Code autónomas y servidor MCP para el Sistema de Diseño Mozaic de ADEO.

📚 Documentación • 🎮 MCP Playground

Descripción general

Este paquete proporciona dos herramientas complementarias para trabajar con el Sistema de Diseño Mozaic en asistentes de IA:

🤖 Skills de Claude Code - 7 skills interactivas para la creación guiada de componentes y el uso de tokens de diseño
🔌 Servidor MCP - Servidor del Protocolo de Contexto de Modelo (MCP) con 17 herramientas para el acceso programático a los recursos de Mozaic

Qué incluye

Tipo de recurso	Cantidad	Descripción
Tokens de diseño	586	Colores, tipografía, espaciado, sombras, bordes, puntos de interrupción
Componentes	131+	Vue 3, React, Web Components y macros de Freemarker con documentación completa
Iconos	1.473	Iconos SVG en 15 categorías
Utilidades CSS	6	Flexy grid, Container, Margin, Padding, Ratio, Scroll
Documentación	281	Guías de uso y mejores prácticas con capacidad de búsqueda
Herramientas MCP	17	Acceso programático a todos los recursos
Skills de Claude	7	Flujos de trabajo interactivos para Vue, React, Web Components, Freemarker y uso agnóstico

Inicio rápido

Instalación interactiva (Recomendado)

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

Usa las teclas de flecha y la barra espaciadora para seleccionar componentes, luego presiona Enter para instalar.

Instalación con un solo comando

# 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

Comprobar el estado de la instalación

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

Pruébalo antes de instalar

Prueba las herramientas MCP directamente en tu navegador sin necesidad de instalación:

🎮 Abrir MCP Playground

El playground te permite:

Probar las 11 herramientas MCP de forma interactiva
Explorar componentes, tokens e iconos
Generar fragmentos de código
Buscar en la documentación

Skills de Claude Code

6 skills autónomas que proporcionan flujos de trabajo interactivos para construir con Mozaic.

Skills disponibles

Skill	Descripción	Caso de uso
mozaic-vue-builder	Generador interactivo de componentes Vue 3	Construir aplicaciones Vue con Mozaic
mozaic-react-builder	Generador interactivo de componentes React/TSX	Construir aplicaciones React con Mozaic
mozaic-webcomponents-builder	Generador interactivo de Web Components	Construir aplicaciones agnósticas al framework con web components nativos
mozaic-freemarker-builder	Generador interactivo de macros Freemarker	Construir plantillas del lado del servidor con Freemarker
mozaic-design-tokens	Experto en tokens de diseño y estilos	Acceder a colores, tipografía, espaciado
mozaic-css-utilities	Clases de utilidad CSS y layouts	Construir layouts responsivos
mozaic-icons	Búsqueda e integración de iconos	Encontrar y usar iconos de Mozaic

Cómo funcionan las Skills

Las skills se activan automáticamente en Claude Code según el contexto, o puedes invocarlas manualmente:

User: "I need a login form with Mozaic"

Claude Code activará automáticamente la skill adecuada (generador de Vue o React) y te guiará a través de:

Selección de componentes
Configuración de props
Generación de código
Instrucciones de instalación

Consulta SKILLS.md para obtener documentación detallada.

Herramientas del servidor MCP

14 herramientas programáticas para acceder a los recursos de Mozaic a través del Protocolo de Contexto de Modelo.

Herramientas disponibles

Herramienta	Categoría	Descripción
`get_design_tokens`	Tokens	Consultar tokens por categoría (colores, tipografía, espaciado, etc.)
`get_component_info`	Componentes	Obtener props, slots, eventos y documentación de componentes
`list_components`	Componentes	Listar componentes por categoría o framework
`generate_vue_component`	Gen. código	Generar código SFC de Vue 3 con props
`generate_react_component`	Gen. código	Generar código React/TSX con TypeScript
`generate_webcomponent`	Gen. código	Generar HTML de Web Component nativo con importaciones
`get_webcomponent_info`	Web Components	Obtener atributos, slots, eventos, propiedades CSS
`list_webcomponents`	Web Components	Listar web components por categoría
`generate_freemarker`	Gen. código	Generar código de macro Freemarker con configuración
`get_freemarker_info`	Freemarker	Obtener opciones de configuración de macros y uso
`list_freemarker`	Freemarker	Listar macros Freemarker por categoría
`search_documentation`	Docs	Búsqueda de texto completo en 281 páginas de documentación
`get_css_utility`	CSS	Obtener clases de utilidad CSS y ejemplos
`list_css_utilities`	CSS	Listar utilidades CSS disponibles
`search_icons`	Iconos	Buscar 1.473 iconos por nombre, tipo o categoría
`get_icon`	Iconos	Obtener SVG de icono y código de framework
`get_install_info`	Instalación	Obtener comandos de instalación npm/yarn/pnpm

Configuración

Añádelo a la configuración de Claude Code o Claude Desktop:

Para Claude Code (en .claude/settings.json):

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

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

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

Ejemplos de uso

Uso de Skills en Claude Code

Las skills se activan automáticamente según tu solicitud:

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...

Uso de herramientas MCP de forma programática

Una vez configurado, Claude puede usar las herramientas MCP directamente:

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...

Comandos CLI

La CLI adeo-mozaic-install-tools proporciona varios comandos:

# 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

Arquitectura

┌─────────────────────────────────────┐
│   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              │
    └──────────────────────────┘

Ubicaciones de archivos

Después de la instalación:

~/.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

Desarrollo

Requisitos previos

Node.js ≥25.2.0
pnpm (recomendado)

Configuración

# 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

Estructura del proyecto

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

Construcción de la base de datos

La base de datos SQLite se construye a partir de los repositorios del Sistema de Diseño Mozaic:

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

# Build database
pnpm build

Esto indexa:

Tokens de diseño de mozaic-design-system/packages/tokens
Componentes de mozaic-vue y mozaic-react
Iconos de mozaic-design-system/packages/icons
Documentación de todos los repositorios

Contribución

¡Las contribuciones son bienvenidas! Por favor, sigue estas pautas:

Haz un fork del repositorio
Crea una rama de funcionalidad (git checkout -b feature/amazing-feature)
Confirma tus cambios usando Conventional Commits
Envía los cambios a la rama (git push origin feature/amazing-feature)
Abre una Pull Request

Convención de commits

Usamos versionado semántico con commits convencionales:

feat: - Nueva funcionalidad (incremento de versión menor)
fix: - Corrección de errores (incremento de versión de parche)
feat!: o BREAKING CHANGE: - Cambio disruptivo (incremento de versión mayor)
chore:, docs:, style:, refactor:, test: - Sin incremento de versión

Recursos

Documentación y herramientas

📚 Documentación: https://merzoukemansouri.github.io/adeo-mozaic-mcp/
🎮 MCP Playground: 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

Recursos relacionados

Sistema de Diseño Mozaic: https://mozaic.adeo.cloud/
Protocolo MCP: https://modelcontextprotocol.io/
Claude Code: https://code.claude.com/

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

Soporte

Para problemas o preguntas:

📚 Lee la documentación en línea
🎮 Prueba el MCP playground
🐛 Abre un issue en GitHub
📖 Consulta la documentación de Skills
🎨 Revisa la documentación del Sistema de Diseño Mozaic

Creado con ❤️ para la comunidad ADEO

El Sistema de Diseño Mozaic es mantenido por ADEO

Mozaic MCP Server

Servidor MCP de Mozaic

Descripción general

Qué incluye

Inicio rápido

Instalación interactiva (Recomendado)

Instalación con un solo comando

Comprobar el estado de la instalación

Pruébalo antes de instalar

Skills de Claude Code

Skills disponibles

Cómo funcionan las Skills

Herramientas del servidor MCP

Herramientas disponibles

Configuración

Ejemplos de uso

Uso de Skills en Claude Code

Uso de herramientas MCP de forma programática

Comandos CLI

Arquitectura

Ubicaciones de archivos

Desarrollo

Requisitos previos

Configuración

Estructura del proyecto

Construcción de la base de datos

Contribución

Convención de commits

Recursos

Documentación y herramientas

Recursos relacionados

Licencia

Soporte

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API