MarcusViniciusBarcelos/uiux-tools-react-mui

🎨 UX/UI Tools for React + Material-UI (MCP Server)

Model Context Protocol (MCP) Server that provides AI-powered tools to apply UX/UI best practices to React components with Material-UI.

Perfect for use with GitHub Copilot, Claude Desktop, and other AI assistants that support MCP.

✨ Features

• �� Responsive Design - Mobile-first patterns with MUI breakpoints
• 🎨 Material-UI Best Practices - Theme spacing, alpha transparency, sx prop
• 🍎 Apple Design Patterns - Custom scrollbars, smooth animations, minimalist design
• 🎯 Nielsen's 10 Heuristics - Complete usability guidelines
• 🧠 Cognitive Biases - Fitts's Law, Grouping Effect, Proximity Principle, and more
• ✅ UX Checklist - Ready-to-use validation checklist

📦 Installation

Option 1: Via npx (Recommended)

No installation needed! Use directly with npx:

npx @marcusbarcelos/uiux-tools-react-mui

Option 2: Global Installation

npm install -g @marcusbarcelos/uiux-tools-react-mui

Option 3: Docker

docker run -i marcusbarcelos/uiux-tools-react-mui

⚙️ Configuration

GitHub Copilot (VS Code)

Add to your ~/.config/Code/User/mcp.json (Linux/Mac) or %APPDATA%\Code\User\mcp.json (Windows):

{
  "servers": {
    "uiux-tools": {
      "command": "npx",
      "args": ["-y", "@marcusbarcelos/uiux-tools-react-mui"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "uiux-tools": {
      "command": "npx",
      "args": ["-y", "@marcusbarcelos/uiux-tools-react-mui"]
    }
  }
}

Docker Configuration

{
  "servers": {
    "uiux-tools": {
      "command": "docker",
      "args": ["run", "-i", "marcusbarcelos/uiux-tools-react-mui"]
    }
  }
}

🚀 Available Tools

1. apply_responsiveness

Apply mobile-first responsive design patterns.

Input:

• component: Component code or filename

Example:

Use tool apply_responsiveness on src/components/MyComponent.tsx

2. apply_material_ui_best_practices

Apply Material-UI best practices (theme.spacing, alpha, sx prop).

3. apply_apple_design

Apply Apple design patterns (custom scrollbar, animations, minimalism).

4. apply_nielsen_heuristic

Apply specific Nielsen heuristic (1-10).

Input:

• component: Component code
• heuristic: Heuristic number (1-10)

Example:

Use tool apply_nielsen_heuristic with heuristic=1 on current component

5. apply_cognitive_bias

Apply cognitive bias for better UX.

Input:

• component: Component code
• bias: One of fitts, grouping, proximity, zeigarnik, serial-position, hicks

6. apply_complete_ux

Apply ALL UX/UI guidelines at once.

7. get_ux_checklist

Get validation checklist for UX/UI review.

💡 Usage Examples

With GitHub Copilot

Use tool apply_complete_ux on src/components/Notification.tsx

Use tool get_ux_checklist

Use tool apply_responsiveness on current file

With Claude Desktop

Simply ask:

"Apply complete UX guidelines to this component"

"Show me the UX checklist"

📚 What's Included

Nielsen's 10 Usability Heuristics

1. Visibility of System Status - Loading states, progress indicators
2. Match Between System and Real World - User-friendly language
3. User Control and Freedom - Cancel buttons, undo actions
4. Consistency and Standards - Uniform colors, icons, patterns
5. Error Prevention - Real-time validation, input limits
6. Recognition Rather Than Recall - Visible options, tooltips
7. Flexibility and Efficiency - Keyboard shortcuts, quick actions
8. Aesthetic and Minimalist Design - Remove visual noise
9. Help Users Recognize Errors - Clear error messages, suggestions
10. Help and Documentation - Tooltips, helper text, placeholders

Cognitive Biases

• Fitts's Law - Larger touch targets (≥44px), closer actions
• Grouping Effect - Related items together, visual separation
• Proximity Principle - Related elements close together
• Zeigarnik Effect - Incomplete task indicators (badges, progress)
• Serial Position Effect - Important actions at top/bottom
• Hick's Law - Limit choices, progressive disclosure

Material-UI Patterns

• theme.spacing() for consistent spacing
• alpha() for transparency
• sx prop instead of styled components
• Smooth transitions with theme.transitions
• Custom scrollbars
• Touch-friendly targets

🐳 Docker

Build Image

docker build -t MarcusViniciusBarcelos/uiux-tools-react-mui .

Run Server

docker run -i MarcusViniciusBarcelos/uiux-tools-react-mui

Docker Hub

docker pull MarcusViniciusBarcelos/uiux-tools-react-mui

🛠️ Development

Clone Repository

git clone https://github.com/MarcusViniciusBarcelos/uiux-tools-react-mui.git
cd uiux-tools-react-mui
npm install

Run Locally

npm start

Test with Inspector

npx @modelcontextprotocol/inspector node index.js

📄 License

MIT © Datacred Team

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

🔗 Links

• Model Context Protocol Documentation
• Material-UI Documentation
• Nielsen Norman Group - 10 Usability Heuristics
• Laws of UX

📧 Support

• 🐛 Report Issues
• 💬 Discussions

Made with ❤️ for better UX/UI in React applications