MaterialExpressiveMcp by keyurgolani - MCP Server

Material 3 Expressive MCP Server

A comprehensive Material 3 Expressive design system implementation with MCP (Model Context Protocol) server capabilities. This server provides AI agents with powerful tools to generate design tokens, components, themes, and complete design systems following Google's Material 3 Expressive design language.

✨ Features

🎨 Dynamic Color System

HCT Color Space: Perceptually uniform color manipulation using Material Color Utilities
Nine Color Schemes: Complete support for all Material 3 schemes (Expressive, Tonal Spot, Content, Fidelity, Vibrant, Neutral, Monochrome, Fruit Salad, Rainbow)
Dynamic Theming: Algorithmic color generation from single source colors
Brand Integration: Custom color harmonization while maintaining semantic relationships

🧩 Component Library

Framework Agnostic: Support for React, Vue, Angular, Svelte, and vanilla HTML/CSS
Material 3 Expressive: Enhanced emotional expression with playful interactions
Accessibility First: WCAG 2.1 AA compliance with comprehensive screen reader support
Spring Physics: Natural, fluid animations with haptic feedback

🤖 AI-Powered Design Guidance

Research-Backed: Based on 46 studies with 18,000+ participants
Component Patterns: Step-by-step guidance for creating Material 3 Expressive components
Validation Rules: Automated compliance checking and improvement suggestions
Design Principles: Comprehensive education on Material 3 Expressive principles

🛠️ Developer Experience

MCP Integration: Seamless integration with AI development environments
Multiple Export Formats: CSS, SCSS, JavaScript, JSON, and Figma tokens
Interactive Showcase: Live component demonstrations with theme switching
CLI Tools: Command-line utilities for development and validation

🚀 Quick Start

Installation

npm install -g material-expressive-mcp-server

Basic Usage

As MCP Server

# Start the MCP server
material-expressive

# The server will be available for MCP clients to connect

Generate Design Tokens

# Generate CSS tokens with expressive scheme
material-expressive generate-tokens --base-color "#4C5C92" --scheme expressive --format css

# Generate complete theme with custom colors
material-expressive generate-theme --name "My Brand" --base-color "#1976D2" --custom-colors brand:#FF6B35,accent:#4ECDC4

Create Components

# Generate React button component
material-expressive generate-component button --framework react --variant filled

# Generate complete component library
material-expressive generate-library --framework vue --output ./components

MCP Tools

The server provides five main MCP tools for AI agents:

1. `get_design_tokens`

Generate complete Material 3 design token sets.

{
  "baseColor": "#4C5C92",
  "scheme": "expressive",
  "format": "css",
  "contrastLevel": 0,
  "customColors": [{ "name": "brand", "color": "#FF6B35", "harmonize": true }]
}

2. `generate_component`

Create framework-specific components with Material 3 Expressive styling.

{
  "componentType": "button",
  "variant": "filled",
  "framework": "react",
  "includeAnimations": true,
  "accessibilityLevel": "enhanced"
}

3. `create_theme`

Generate complete themes with accessibility validation.

{
  "name": "Brand Theme",
  "baseColor": "#1976D2",
  "scheme": "fidelity",
  "customColors": [
    { "name": "brand-primary", "color": "#1976D2", "harmonize": false }
  ],
  "expressiveness": {
    "emotionalIntensity": 0.8,
    "springPhysics": true,
    "contextualResponses": true
  }
}

4. `get_showcase_page`

Generate interactive showcase applications.

{
  "framework": "react",
  "includeAccessibilityTools": true,
  "includeThemeSwitcher": true,
  "responsive": true
}

5. `get_ai_guidance`

Get comprehensive design guidance and best practices.

{
  "topic": "component-creation",
  "componentType": "button",
  "framework": "react",
  "includeExamples": true
}

📚 Documentation

Material 3 Expressive Principles

This implementation follows Google's Material 3 Expressive design language, which emphasizes:

Elicit Emotion: Playful, energetic, creative, friendly, and positive
Communicate Function: Clear visual hierarchy and priority signaling
Enhance Usability: 4x cognitive load reduction for key actions
Personal for Every Style: Dynamic theming and user preferences
Accessible for Every Need: Inclusive design standards
Alive and Adaptive: Contextual responses and spring physics

Color Schemes

Expressive (Default): Bold, creative expressions detached from source color
Tonal Spot: Balanced, harmonious (Android default)
Content: Source-focused, stable for content-heavy apps
Fidelity: True to source color for brand-accurate experiences
Vibrant: Maximum colorfulness for high-energy apps
Neutral: Near grayscale for professional/minimal interfaces
Monochrome: Pure grayscale for accessibility/focus
Fruit Salad: Playful, colorful for fun experiences
Rainbow: Vibrant, diverse for social/entertainment

Supported Components

Buttons: Filled, Outlined, Text, FAB (with pill shapes)
Cards: Elevated, Filled, Outlined (with 28px radius)
Navigation: App Bar, Bottom Navigation, Drawer, Rail, Tabs
Inputs: Text Fields, Switches, Sliders, Chips
Feedback: Snackbars, Dialogs, Bottom Sheets
Layout: Grids, Containers
Data Display: Lists, Tables

Framework Support

React: Modern hooks and TypeScript support
Vue: Composition API and reactive theming
Angular: Component architecture with dependency injection
Svelte: Reactive components with stores
Vanilla: Semantic HTML with progressive enhancement

📱 Live Examples

Check out the React Showcase Application in the examples/react-showcase directory to see a comprehensive demonstration of all MCP server capabilities:

cd examples/react-showcase
npm install
npm run dev

The showcase demonstrates:

Design token generation with all token types
Theme creation with accessibility validation
Component generation for multiple frameworks
All 9 Material 3 color schemes
Accessibility features and best practices

🎯 Usage Examples

Generate a Complete Design System

// Using the MCP tools programmatically
const theme = await mcpClient.callTool('create_theme', {
  name: 'Acme Corp Design System',
  baseColor: '#1976D2',
  scheme: 'fidelity',
  customColors: [
    { name: 'brand-primary', color: '#1976D2', harmonize: false },
    { name: 'brand-secondary', color: '#FFC107', harmonize: true },
    { name: 'brand-accent', color: '#FF5722', harmonize: true },
  ],
  accessibility: {
    highContrast: false,
    colorBlindnessSupport: true,
  },
  expressiveness: {
    emotionalIntensity: 0.6,
    contextualResponses: true,
    springPhysics: true,
  },
});

// Generate components using the theme
const button = await mcpClient.callTool('generate_component', {
  componentType: 'button',
  variant: 'filled',
  framework: 'react',
  includeAnimations: true,
  accessibilityLevel: 'enhanced',
});

Create Interactive Showcase

const showcase = await mcpClient.callTool('get_showcase_page', {
  framework: 'react',
  theme: theme,
  includeAccessibilityTools: true,
  includeThemeSwitcher: true,
  responsive: true,
});

🔧 Development

Prerequisites

Node.js 18+
TypeScript 5.3+
Material Color Utilities

Setup

# Clone the repository
git clone https://github.com/your-org/material-expressive-mcp-server.git
cd material-expressive-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Start development server
npm run dev

Project Structure

src/
├── ai-guidance/          # AI guidance system and design principles
├── cli/                  # Command-line interface
├── components/           # Component definitions and generators
├── mcp/                  # MCP server implementation
├── showcase/             # Interactive showcase generation
├── theme/                # Theme generation and color schemes
├── tokens/               # Design token system
└── utils/                # Shared utilities

Testing

# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run specific test suite
npm test -- src/theme/generator.test.ts

Linting and Formatting

# Check code quality
npm run lint

# Fix linting issues
npm run lint:fix

# Format code
npm run format

🤝 Contributing

We welcome contributions! Please see our for details.

Development Workflow

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Ensure all tests pass (npm test)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Code Style

Use TypeScript for all new code
Follow the existing code style (ESLint + Prettier)
Write comprehensive tests for new features
Document public APIs with JSDoc
Follow Material 3 Expressive design principles

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

Google Material Design Team for the Material 3 Expressive design language
Material Color Utilities for the HCT color space implementation
Model Context Protocol for the AI integration framework
Open Source Community for the amazing tools and libraries

📞 Support

Documentation:
Issues: GitHub Issues
Discussions: GitHub Discussions

🗺️ Roadmap

Additional framework support (Flutter, SwiftUI)
Advanced animation system with Lottie integration
Design tool plugins (Figma, Sketch, Adobe XD)
Real-time collaboration features
Advanced accessibility testing tools
Performance optimization and bundle analysis

Made with ❤️ by the Material Expressive MCP team