secondsky/claude-skills / plugins/maz-ui/skills/maz-ui
maz-ui
VerifiedMaz-UI v4 - Modern Vue & Nuxt component library with 50+ standalone components, composables, directives, theming, i18n, and SSR support. Use when building Vue/Nuxt applications with forms, dialogs, tables, animations, or need responsive design system with dark mode.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.7 KB |
| references/accessibility.md | markdown | 16.2 KB |
| references/cli.md | markdown | 10.8 KB |
| references/components-feedback.md | markdown | 19.1 KB |
| references/components-forms.md | markdown | 8.4 KB |
| references/components-layout.md | markdown | 17.8 KB |
| references/components-navigation.md | markdown | 19.5 KB |
| references/composables.md | markdown | 28.3 KB |
| references/directives.md | markdown | 17.0 KB |
| references/form-validation.md | markdown | 22.7 KB |
| references/icons.md | markdown | 14.9 KB |
| references/mcp.md | markdown | 13.6 KB |
| references/migration-v4.md | markdown | 21.0 KB |
| references/performance.md | markdown | 17.0 KB |
| references/plugins.md | markdown | 25.1 KB |
| references/resolvers.md | markdown | 26.2 KB |
| references/setup-nuxt.md | markdown | 26.0 KB |
| references/setup-vue.md | markdown | 21.7 KB |
| references/ssr-ssg.md | markdown | 13.9 KB |
| references/theming.md | markdown | 7.2 KB |
| references/translations.md | markdown | 20.1 KB |
| references/troubleshooting.md | markdown | 9.0 KB |
references/mcp.md
View on GitHub# Maz-UI MCP Server Reference
Guide to integrating Maz-UI with AI assistants using Model Context Protocol (MCP).
## Overview
### What is Model Context Protocol (MCP)?
**Model Context Protocol (MCP)** is a standardized way to connect AI assistants with external knowledge sources. Think of it as a **smart bridge** between your AI assistant and Maz-UI's documentation.
**Package**: `@maz-ui/mcp`
**NPM**: [](https://www.npmjs.com/package/@maz-ui/mcp)
### Benefits
Instead of asking _"How do I use MazBtn?"_ and getting generic or outdated answers, your AI can now:
- π **Search** through all 50+ Maz-UI components
- π **Read** exact documentation for components, composables, directives, plugins
- π‘ **Suggest** best implementation approaches
- π οΈ **Help** with code examples and best practices
### What's Included
The MCP server provides **read-only access** to:
| Resource Type | Count | Description |
|--------------|-------|-------------|
| **Components** | 50+ | All Vue components with props, events, examples |
| **Guides** | 11 | Installation, theming, migration, best practices |
| **Composables** | 14+ | Reusable Vue composition functions |
| **Directives** | 5 | Vue directives for enhanced functionality |
| **Plugins** | 4 | Toast, dialog, AOS, wait overlay systems |
| **Helpers** | 20+ | Utility functions for common tasks |
::: tip Security Note
The MCP server provides **read-only access** to documentation. No sensitive data is transmitted or stored.
:::
---
## Supported AI Assistants
Maz-UI MCP server works with:
- **Claude Code** - Anthropic's CLI tool
- **Claude Desktop** - Desktop application
- **Cursor IDE** - AI-powered code editor
- **Windsurf** - Development environment
- **VS Code Copilot** - GitHub Copilot in VS Code
- **Cline** - VS Code extension
---
## Installation & Configuration
### Claude Code
**1. Add MCP Server**:
```bash
# Install at project scope (recommended)
claude mcp add maz-ui npx @maz-ui/mcp --scope project
# Or user scope (global)
claude mcp add maz-ui npx @maz-ui/mcp --scope user
# Or local scope (current directory only)
claude mcp add maz-ui npx @maz-ui/mcp --scope local
```
**2. Configuration File**:
The command creates/updates `~/.mcp.json` (or project-specific `.mcp.json`):
```json
{
"mcpServers": {
"maz-ui": {
"type": "stdio",
"command": "npx",
"args": ["@maz-ui/mcp"]
}
}
}
```
**3. Restart**:
```bash
# Restart Claude Code to apply configuration
```
**4. Verify**:
Ask Claude Code: _"What Maz-UI components are available for forms?"_
The AI will now search the MCP server and provide accurate, up-to-date information.
---
### Claude Desktop
**1. Open Settings**:
- Launch Claude Desktop
- Navigate to **Settings**
**2. Edit Config**:
- Under **Developer** tab
- Tap **Edit Config** to open configuration file
**3. Add Configuration**:
```json
{
"mcpServers": {
"maz-ui": {
"type": "stdio",
"command": "npx",
"args": ["@maz-ui/mcp"]
}
}
}
```
**4. Restart**:
- Save configuration file
- Restart Claude Desktop
**5. Verify**:
- Start a new chat
- Look for hammer (MCP) icon
- Maz-UI server should be listed as available
---
### Cursor IDE
**1. Create Config Directory**:
```bash
# In your project root
mkdir -p .cursor
```
**2. Create MCP Config**:
Create `.cursor/mcp.json`:
```json
{
"mcpServers": {
"maz-ui": {
"command": "npx",
"args": ["@maz-ui/mcp"]
}
}
}
```
**3. Verify Connection**:
- Open Cursor Settings
- Navigate to **Settings** β **MCP**
- Green active status = successfully connected
**4. Usage**:
Ask Cursor: _"Show me how to implement a multi-step form with MazStepper"_
---
### Windsurf
**1. Open MCP Settings**:
- Launch Windsurf
- Navigate to **Cascade assistant**
- Tap hammer (MCP) icon
- Tap **Configure**
**2. Add Configuration**:
```json
{
"mcpServers": {
"maz-ui": {
"command": "npx",
"args": ["@maz-ui/mcp"]
}
}
}
```
**3. Reload**:
- Save configuration file
- Tap **Refresh** in Cascade assistant
**4. Verify**:
- Green active status = successfully connected
---
### Visual Studio Code (Copilot)
**1. Create Config Directory**:
```bash
# In your project root
mkdir -p .vscode
```
**2. Create MCP Config**:
Create `.vscode/mcp.json`:
```json
{
"servers": {
"maz-ui": {
"command": "npx",
"args": ["@maz-ui/mcp"]
}
}
}
```
**3. Setup Copilot**:
- Open Copilot chat
- Switch to **Agent** mode
- Tap tool icon to confirm MCP tools are available
- Enter personal access token when prompted
**4. Usage**:
Ask Copilot: _"What's the best way to handle form validation with Maz-UI?"_
---
### Cline (VS Code Extension)
**1. Open MCP Settings**:
- Open Cline extension in VS Code
- Tap **MCP Servers** icon
- Tap **Configure MCP Servers**
**2. Add Configuration**:
```json
{
"mcpServers": {
"maz-ui": {
"command": "npx",
"args": ["@maz-ui/mcp"]
}
}
}
```
**3. Auto-Reload**:
- Save configuration file
- Cline automatically reloads configuration
**4. Verify**:
- Green active status = successfully connected
---
## Usage Examples
### Component Discovery
**Before MCP**:
```
User: "How do I create a button in Maz-UI?"
AI: *Generic answer or outdated information*
```
**With MCP**:
```
User: "How do I create a button in Maz-UI?"
AI: *Searches MCP server, returns current MazBtn documentation with props, events, and examples*
```
---
### Implementation Help
**Query**: _"I need a form with email validation, a loading state, and toast notifications on submit"_
**AI Response** (with MCP):
```vue
<script setup lang="ts">
import { ref } from 'vue'
import { useToast } from 'maz-ui'
import { string, email, pipe } from 'valibot'
const toast = useToast()
const isLoading = ref(false)
const emailValue = ref('')
const schema = {
email: pipe(
string('Email is required'),
email('Invalid email format')
)
}
const handleSubmit = async () => {
isLoading.value = true
try {
await submitToAPI({ email: emailValue.value })
toast.success('Email submitted successfully!')
} catch (error) {
toast.error('Submission failed. Please try again.')
} finally {
isLoading.value = false
}
}
</script>
<template>
<form @submit.prevent="handleSubmit">
<MazInput
v-model="emailValue"
type="email"
label="Email Address"
placeholder="Enter your email"
required
/>
<MazBtn type="submit" :loading="isLoading">
Submit
</MazBtn>
</form>
</template>
```
The AI knows:
- MazInput component with validation props
- MazBtn with loading state
- useToast composable for notifications
- Valibot integration for schema validation
---
### Best Practices Discovery
**Query**: _"What's the recommended way to handle theming in Maz-UI v4?"_
**AI Response** (with MCP):
- Fetches theming guide from MCP server
- Suggests @maz-ui/themes package (not legacy CLI)
- Provides runtime theme switching example
- Recommends built-in presets (maz-ui, ocean, pristine, obsidian)
---
## Available Resources Details
### 50+ Components
**Forms**:
- MazInput, MazSelect, MazTextarea, MazCheckbox, MazRadio
- MazPhoneNumberInput, MazInputPrice, MazInputCode, MazInputTags
- MazPicker (date/time), MazSlider, MazSwitch
**Navigation**:
- MazTabs, MazStepper, MazPagination, MazBreadcrumbs
**Feedback**:
- MazFullscreenLoader, MazLoadingBar, MazCircularProgressBar
- MazDialog, MazToast, MazAlert, MazBadge, MazAvatar
**Layout**:
- MazCard, MazAccordion, MazDrawer, MazBottomSheet
- MazCarousel, MazGallery, MazDropdown, MazPopover
**Display**:
- MazBtn, MazIcon, MazLazyImg, MazAnimatedText, MazAnimatedCounter
### 14+ Composables
- **Theme**: useTheme (runtime theme switching)
- **i18n**: useTranslations (8 languages)
- **UI**: useToast, useDialog, useWait
- **Layout**: useBreakpoints, useWindowSize
- **Forms**: useFormValidator (Valibot integration)
- **Interaction**: useSwipe, useIdleTimeout, useUserVisibility
- **Utilities**: useTimer, useReadingTime, useStringMatching, useDisplayNames, useFormField
### 5 Directives
- **v-tooltip**: Customizable tooltips with positioning
- **v-click-outside**: Detect clicks outside element
- **v-lazy-img**: Lazy load images with blur-up effect
- **v-zoom-img**: Image zoom on hover/click
- **v-fullscreen-img**: Open images in fullscreen viewer
### 4 Plugins
- **Toast**: Notification system with actions, persistence, stacking
- **Dialog**: Promise-based modals with custom buttons
- **AOS**: Animate On Scroll with 60+ animations
- **Wait**: Global loading state management
### 11 Guides
1. Getting Started
2. Installation (Vue, Nuxt)
3. Theming (v4 themes package)
4. Migration (v3 β v4)
5. Auto-Import Resolvers
6. CLI (legacy v3)
7. MCP Server
8. SSR/SSG Support
9. Accessibility
10. Performance Optimization
11. Best Practices
### 20+ Helpers
**String**: capitalize, kebabCase, camelCase, snakeCase, slugify
**Number**: formatNumber, formatCurrency, clamp, randomInt
**Date**: formatDate, formatRelative, isValidDate
**Array**: chunk, unique, shuffle, groupBy
**Object**: deepClone, mergeDeep, pick, omit
**Color**: hexToRgb, rgbToHex, lighten, darken, getContrast
**Validation**: isEmail, isURL, isPhoneNumber, isCreditCard
---
## Troubleshooting
### MCP Server Not Appearing
**Issue**: AI assistant doesn't show Maz-UI in available MCP servers
**Solutions**:
1. **Check configuration file syntax**:
```bash
# Validate JSON
cat ~/.mcp.json | jq .
```
2. **Verify npx is installed**:
```bash
npx --version
```
3. **Check network connectivity** (npx needs to download @maz-ui/mcp)
4. **Restart AI assistant** after configuration changes
---
### Connection Failed
**Issue**: MCP server shows as "inactive" or "connection failed"
**Solutions**:
1. **Test npx command directly**:
```bash
npx @maz-ui/mcp
```
2. **Check Node.js version**:
```bash
node --version # Should be 20+
```
3. **Clear npx cache**:
```bash
npx clear-npx-cache
npx @maz-ui/mcp
```
4. **Check firewall settings** (if using corporate network)
---
### Outdated Documentation Returned
**Issue**: AI returns old information despite MCP server
**Solutions**:
1. **Verify MCP server is active** (green status)
2. **Check @maz-ui/mcp version**:
```bash
npm view @maz-ui/mcp version
```
3. **Update package**:
```bash
npx @maz-ui/mcp@latest
```
4. **Restart AI assistant**
---
### AI Not Using MCP Server
**Issue**: AI gives generic answers instead of using MCP
**Solutions**:
1. **Explicitly request MCP usage**:
- "Search Maz-UI documentation for..."
- "Using the Maz-UI MCP server, show me..."
2. **Check MCP server is enabled** in AI settings
3. **Verify hammer (MCP) icon** appears in UI
---
## Advanced Configuration
### Custom Installation Path
**Problem**: Don't want to use npx (prefer global installation)
**Solution**:
1. **Install globally**:
```bash
npm install -g @maz-ui/mcp
```
2. **Update configuration**:
```json
{
"mcpServers": {
"maz-ui": {
"command": "maz-ui-mcp",
"args": []
}
}
}
```
---
### Multiple Projects
**Problem**: Different Maz-UI versions across projects
**Solution**: Use **project-scoped configuration**
**Claude Code**:
```bash
# In project directory
claude mcp add maz-ui npx @maz-ui/mcp --scope project
```
Creates `.mcp.json` in project root, not global `~/.mcp.json`.
**Cursor IDE**:
```bash
# Each project has .cursor/mcp.json
```
**VS Code**:
```bash
# Each project has .vscode/mcp.json
```
---
### Offline Usage
**Problem**: Need MCP server without internet
**Solution**:
1. **Cache @maz-ui/mcp**:
```bash
npx @maz-ui/mcp # Downloads and caches
```
2. **Verify cache**:
```bash
ls ~/.npm/_npx
```
3. **Offline mode**: npx uses cached version when offline
---
## Benefits Summary
### Before MCP
- β Generic answers from AI training data
- β Outdated documentation (AI cutoff date)
- β No context about current Maz-UI version
- β Manual documentation searching
### After MCP
- β
Accurate, up-to-date documentation
- β
Current Maz-UI v4 best practices
- β
Component-specific examples
- β
AI searches documentation for you
- β
Integration examples with your stack
### Example Impact
**Without MCP**:
```
User: "How do I validate a form in Maz-UI?"
AI: *Generic Vue form validation answer*
```
**With MCP**:
```
User: "How do I validate a form in Maz-UI?"
AI: *Returns useFormValidator documentation with Valibot schemas,
validation modes (lazy, aggressive, eager, blur, progressive),
error handling, TypeScript type inference, real-world examples*
```
---
## Related Documentation
- **[Setup Vue](./setup-vue.md)** - Vue 3 installation with auto-import resolvers
- **[Setup Nuxt](./setup-nuxt.md)** - Nuxt 3 module configuration
- **[Composables](./composables.md)** - All 14+ composables reference
- **[Components Forms](./components-forms.md)** - Form components catalog
- **[Theming](./theming.md)** - v4 theme customization
- **[Troubleshooting](./troubleshooting.md)** - Common issues and fixes
---
## External Resources
- **[@maz-ui/mcp on NPM](https://www.npmjs.com/package/@maz-ui/mcp)** - MCP server package
- **[Official MCP Docs](https://maz-ui.com/guide/mcp)** - Official guide
- **[Model Context Protocol](https://modelcontextprotocol.io/)** - MCP specification
- **[Claude Code MCP Guide](https://docs.anthropic.com/claude/docs/mcp)** - Anthropic's MCP documentation
---
**MCP Server Version**: @maz-ui/mcp (latest)
**Supported Maz-UI Version**: v4.9.3+
**Last Updated**: 2025-12-14
::: tip Recommendation
Enable MCP for all Maz-UI projects to get intelligent, context-aware AI assistance with components, composables, and best practices.
:::
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |