Skip to content

README.md

Latest commit

 

History

History
820 lines (611 loc) · 21.6 KB

README.md

File metadata and controls

820 lines (611 loc) · 21.6 KB

CSS First

An advanced MCP (Model Context Protocol) server that provides intelligent, context-aware CSS-first solutions for UI implementation tasks. Features semantic analysis, framework detection, and intelligent ranking with direct MDN integration.

Setup

Choose between Remote MCP (Server-Sent Events) or Local MCP (stdio) installation:

🌐 Remote MCP via SSE (Recommended)

Connect to our hosted Cloudflare Worker instance - no local installation required:

URL: https://mcp-css-first.chylik-lukas.workers.dev/sse

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "css-first-remote": {
      "url": "https://mcp-css-first.chylik-lukas.workers.dev/sse",
      "transport": "sse"
    }
  }
}

Cursor / Windsurf / Cline

Add to your MCP settings:

{
  "mcpServers": {
    "css-first-remote": {
      "serverUrl": "https://mcp-css-first.chylik-lukas.workers.dev/mcp"
    }
  }
}

Claude Code CLI

Edit ~/.config/claude/config.json and add:

{
  "mcpServers": {
    "css-first-remote": {
      "url": "https://mcp-css-first.chylik-lukas.workers.dev/sse",
      "transport": "sse"
    }
  }
}

💻 Local MCP via stdio

Install and run locally using npm package:

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "css-first": {
      "command": "npx",
      "args": ["-y", "@depthark/css-first"]
    }
  }
}

Cursor

Add to MCP settings (.cursor/mcp_settings.json or via Settings UI):

{
  "mcpServers": {
    "css-first": {
      "command": "npx",
      "args": ["-y", "@depthark/css-first"]
    }
  }
}

Windsurf

Add to MCP configuration:

{
  "mcpServers": {
    "css-first": {
      "command": "npx",
      "args": ["-y", "@depthark/css-first"]
    }
  }
}

Cline (VS Code Extension)

Add to Cline MCP settings:

{
  "mcpServers": {
    "css-first": {
      "command": "npx",
      "args": ["-y", "@depthark/css-first"]
    }
  }
}

Claude Code CLI

claude mcp add css-first npx -y @depthark/css-first

Codex

Add to mcp_servers.toml:

[mcp_servers.css-first]
command = "npx"
args = ["-y", "@depthark/css-first"]

Zed Editor

Add to Zed settings:

{
  "context_servers": {
    "css-first": {
      "command": {
        "path": "npx",
        "args": ["-y", "@depthark/css-first"]
      }
    }
  }
}

🚀 Deploy Your Own Remote Instance

Deploy your own Cloudflare Worker:

git clone https://github.com/luko248/css-first
cd css-first
bun install
bun run build:core
bun run deploy:worker

Then use your custom URL:

https://mcp-css-first.<your-subdomain>.workers.dev/sse

Usage

After adding the configuration:

  1. Restart your MCP client
  2. Ask CSS questions like:
    • "Create a responsive card layout"
    • "Center a div vertically and horizontally"
    • "Add dark mode support"
    • "Make a sticky header"
    • "Create organic rounded corners with corner-shape"
    • "Design modern buttons with superellipse curves"

🚀 Key Features

Intelligent Analysis

  • Semantic Intent Recognition: Understands user intent through advanced pattern matching (layout, animation, spacing, etc.)
  • Confidence Scoring: Provides transparency with confidence levels for suggestions
  • Context-Aware Keywords: Enhanced keyword extraction with semantic understanding

Project Context Awareness

  • Framework Detection: Automatically detects React, Vue, Angular, Svelte projects
  • CSS Framework Recognition: Supports Tailwind, Bootstrap, Material-UI, Chakra UI
  • Build Tool Integration: Recognizes Webpack, Vite, Parcel, Rollup environments
  • Constraint Analysis: Understands project constraints (performance, accessibility, responsive)

Enhanced MDN Integration

  • Direct MDN Parsing: Pulls property data straight from MDN pages
  • Performance Caching: 1-hour intelligent caching for improved response times
  • Real-time Browser Support: Compatibility data derived from MDN content

Intelligent Ranking

  • Relevance Scoring: Suggestions ranked by intent match, browser support, and framework compatibility
  • Category-Prioritized Search: Focuses on most relevant CSS feature categories
  • Framework-Specific Recommendations: Tailored advice for your tech stack

User Experience

  • Consent-Driven Workflow: User approval required before property recommendations
  • Detailed Analysis: Optional semantic analysis breakdown for transparency
  • Implementation Guidance: Framework-specific best practices and code examples

Development Installation

For contributors and advanced users who want to modify the source:

git clone https://github.com/luko248/css-first
cd css-first
bun install
bun run build

Development Usage

For development/testing with local builds:

{
  "mcpServers": {
    "@depthark/css-first": {
      "command": "node",
      "args": ["/absolute/path/to/css-first/packages/cli/dist/cli.js"]
    }
  }
}

Available Tools

1. suggest_css_solution ⭐

Enhanced CSS-first solution suggester with semantic analysis, context awareness, and intelligent ranking.

Parameters:

  • task_description (string): Description of the UI task or problem to solve
  • preferred_approach (optional): 'modern', 'compatible', or 'progressive'
  • target_browsers (optional): Array of target browsers/versions
  • project_context (optional): Project context (framework, existing CSS patterns, constraints) NEW
  • include_analysis (optional): Include semantic analysis details in response NEW
  • baseline (optional): CSS Baseline availability filter: "Widely Available", "Newly Available", "Limited Availability", "Experimental" (fetched from MDN; falls back to support-level heuristics if unavailable)
  • max_suggestions (optional): Limit number of suggestions (default 3)
  • response_detail (optional): "compact" (default) or "full" response fields
    • compact returns minimal fields (property, description, support_level, baseline, overall_support, mdn_url)

Examples:

Basic Usage:

{
  "task_description": "I need to center a div horizontally and vertically",
  "preferred_approach": "modern"
}

With Project Context:

{
  "task_description": "Create a responsive card layout with hover animations",
  "preferred_approach": "modern",
  "project_context": "React project using Tailwind CSS, targeting Chrome 90+, performance-critical",
  "include_analysis": true
}

With Baseline Filter:

{
  "task_description": "Create a tooltip",
  "baseline": "Experimental"
}

Full Response Fields:

{
  "task_description": "Create a tooltip",
  "response_detail": "full",
  "max_suggestions": 5
}

Response includes:

  • Intelligently ranked CSS suggestions
  • Framework-specific recommendations
  • Semantic analysis breakdown (optional)
  • Confidence scoring and intent detection
  • Baseline availability labels with emoji color tags
  • Support level derived from MDN browser data
  • Compact responses by default to reduce token usage

2. check_css_browser_support

Checks browser support for specific CSS properties using MDN data.

Parameters:

  • css_property (string): CSS property name to check
  • include_experimental (optional boolean): Include experimental features

Example:

{
  "css_property": "flexbox",
  "include_experimental": false
}

3. get_css_property_details

Retrieves comprehensive information about a CSS property from MDN documentation.

Parameters:

  • css_property (string): CSS property name to get details for
  • include_examples (optional boolean): Include code examples

Example:

{
  "css_property": "grid",
  "include_examples": true
}

4. confirm_css_property_usage

Confirms user consent for using a specific CSS property and provides implementation guidance.

Parameters:

  • css_property (string): CSS property name user wants to use
  • user_consent (boolean): User consent to use this CSS property
  • fallback_needed (optional boolean): Whether fallback solutions are needed

Example:

{
  "css_property": "container-queries",
  "user_consent": true,
  "fallback_needed": true
}

🧠 How It Works

Intelligent Analysis Pipeline

  1. Semantic Intent Recognition: Advanced regex patterns analyze task descriptions to understand user intent (layout, animation, spacing, responsive, visual, interaction)

  2. Project Context Analysis: Detects frameworks, CSS libraries, build tools, and constraints from project context string

  3. MDN Integration:

    • Direct MDN parsing for property details and support data
    • Caching: 1-hour intelligent cache for performance

  4. Intelligent Ranking: Scores suggestions based on:

    • Intent match relevance
    • Browser support level
    • Framework compatibility
    • User confidence multiplier

  5. Context-Aware Recommendations: Provides framework-specific guidance and best practices

  6. User Consent & Implementation: Consent-driven workflow with detailed implementation guidance

Example Analysis Flow

Input: "Create a responsive navigation menu with smooth animations"
↓
Intent Detection: layout + responsive + animation (85% confidence)
↓
Context: React + Tailwind detected
↓
Ranked Suggestions:
1. Flexbox layout (95% support) + CSS transitions
2. CSS Grid (92% support) + transform animations
3. Container queries (75% support) with fallbacks
↓
Framework Recommendations: "Use Tailwind's responsive prefixes", "Consider React transition components"

Development

# Install dependencies
bun install

# Build all packages
bun run build

# Build specific packages
bun run build:core     # @css-first/core
bun run build:cli      # @depthark/css-first

# Type check
bun run typecheck

# Lint code
bun run lint

# Deploy to Cloudflare Workers
bun run deploy:worker

# Publish CLI to npm
bun run publish:cli

📁 Project Structure (Bun Monorepo)

packages/
├── core/                        # @css-first/core - shared CSS services
│   └── src/
│       ├── index.ts            # CSS services entry point
│       ├── types.ts            # TypeScript interfaces and enums
│       ├── mdnClient.ts        # MDN client and parser
│       ├── suggestions.ts      # Semantic analysis and intelligent ranking
│       ├── guidance.ts         # Implementation guidance
│       ├── contextAnalyzer.ts  # Project context detection
│       └── features/           # Modular CSS feature definitions
│           ├── animation/      # Animation and transition features
│           ├── layout/         # Flexbox, Grid features
│           ├── logical/        # Logical properties
│           ├── responsive/     # Responsive design
│           ├── visual/         # Visual effects
│           └── ...             # More feature modules
├── cli/                         # @depthark/css-first - npm package
│   └── src/
│       └── index.ts            # MCP server (stdio/HTTP transport)
└── worker/                      # @css-first/worker - Cloudflare Workers
    ├── src/
    │   └── index.ts            # McpAgent class for remote MCP (SSE)
    └── wrangler.toml           # Worker-specific config

Key Architecture Benefits

  • Monorepo Structure: Shared core, separate deployments (npm + Cloudflare)
  • Modular Design: Each CSS category has dedicated modules for maintainability
  • Semantic Analysis: Intent recognition and confidence scoring for accuracy
  • Context Awareness: Framework and project constraint detection
  • Performance Optimized: Intelligent caching and ranked results
  • Dual Deployment: Local CLI via npm, remote MCP via Cloudflare Workers

🎯 CSS Feature Coverage

Intelligent Categories

The enhanced system provides context-aware suggestions across:

  • Layout 🏗️: Flexbox, Grid, positioning, display modes
  • Animation ✨: CSS animations, transitions, transforms
  • Responsive 📱: Container queries, media queries, viewport units
  • Visual 🎨: Shadows, gradients, borders, effects
  • Interaction 🖱️: Hover states, focus, active, disabled
  • Logical Properties 📐: Writing-mode aware spacing and sizing
  • HTML APIs 🧩: Dialogs, popovers, invoker commands
  • Typography 📝: Font properties, text alignment, spacing
  • Positioning 📍: Static, relative, absolute, fixed, sticky

Supported Feature Catalog

Logical Spacing

  • Logical Spacing Properties
  • Modern CSS Units

Layout (Flexbox)

  • Flexbox

Layout (Grid)

  • CSS Grid
  • CSS Subgrid

Animation

  • CSS Transitions
  • CSS Animations
  • CSS @starting-style
  • CSS interpolate-size
  • CSS Scroll Timeline
  • CSS View Timeline
  • CSS Animation Timeline
  • CSS Animation Range
  • CSS View Timeline Inset
  • CSS Timeline Scope
  • CSS View Transitions

Visual

  • CSS Gradients
  • CSS Transforms
  • Logical Border Properties
  • CSS Overflow
  • CSS Overflow Clip
  • CSS Overscroll Behavior
  • CSS Corner Shape
  • CSS -webkit-box-reflect

Responsive

  • Media Queries

Interaction

  • CSS Scroll Snap
  • Modern CSS Carousel with Pseudo-Elements

Selectors

  • Basic Selectors
  • Attribute Selectors
  • State Pseudo-classes
  • Structural Pseudo-classes
  • Modern Selectors
  • Pseudo-elements
  • Form Validation Selectors

Logical

  • CSS if() Function

HTML

  • Invoker Commands
  • Dialog closedby Attribute

Positioning

  • CSS Anchor Positioning
  • Anchor Positioning with Container Queries
  • Anchor Name
  • Position Anchor
  • Position Area
  • Position Try Properties
  • Position Visibility
  • Position Try At-Rule
  • Anchor Functions

Display

  • CSS Display Property
  • Display Contents
  • Flexbox Display
  • Grid Display
  • Inline Display Values
  • Block Display Values
  • Table Display Values
  • Display None
  • List Item Display
  • Flow Root Display
  • Subgrid Display

Modern: Container & Queries

  • CSS Container Queries
  • CSS Container Style Queries
  • CSS Container Scroll State Queries
  • CSS Anchor Positioning
  • Anchor Positioning with Container Queries
  • Expanded Range Syntax

Modern: Layout & Sizing

  • CSS Subgrid
  • CSS Masonry Layout
  • CSS Grid Lanes (Masonry)
  • CSS Sizing Properties
  • Flexbox gap Property
  • Enhanced Logical Properties
  • Mobile Viewport Heights
  • Stretch Sizing Keyword
  • CSS aspect-ratio
  • CSS Nesting

Modern: Color & Visual

  • CSS color-mix() Function
  • CSS color-contrast() Function
  • CSS accent-color
  • CSS color-scheme
  • CSS light-dark() Function
  • Enhanced Light-Dark Theme System
  • CSS backdrop-filter
  • CSS conic-gradient
  • CSS image-set() Function
  • Enhanced Text Decoration
  • Enhanced font-variant Properties
  • Text Box Trim

Modern: Motion & Transitions

  • Scroll-driven Animations
  • Scroll-triggered Animations
  • CSS View Transitions
  • View Transition Group Property
  • Scoped View Transitions

Modern: Interaction & UI Patterns

  • CSS Carousel with Modern Pseudo-Elements
  • Scroll-Driven Carousel Animations
  • CSS-Only Form Validation
  • CSS-Only Modal/Dialog
  • CSS-Only Tabs/Accordion
  • CSS-Only Navigation Patterns
  • CSS-Only Loading/Skeleton
  • Popover API
  • Interest Invokers
  • Scroll Target Group

Modern: Media & Environment

  • Enhanced prefers-* Media Queries
  • CSS forced-colors Media Query
  • CSS env() Function
  • CSS scroll-behavior
  • CSS overscroll-behavior

Modern: Functions & Syntax

  • CSS Enhanced Math Functions
  • CSS if() Conditional Function
  • CSS Custom Functions (@function)
  • CSS shape() Function
  • Advanced attr() Function
  • Tree Counting Functions
  • Customizable Select Element

Framework-Specific Features

  • React: Component-scoped styling, CSS-in-JS patterns
  • Vue: Scoped styles, transition components
  • Angular: ViewEncapsulation, Material Design integration
  • Svelte: Built-in scoped styling, reactive CSS

CSS Framework Integration

  • Tailwind: Utility-first patterns, responsive prefixes
  • Bootstrap: Grid system, utility classes
  • Material-UI: Theme customization, sx props
  • Chakra UI: Design system tokens

📊 Enhanced Browser Support Levels

  • Excellent (95%+): ✅ Safe for production use
  • Good (85%+): ⚠️ Consider fallbacks for legacy browsers
  • Moderate (70%+): ⚡ Use with caution and provide fallbacks
  • Limited (<70%): 🔄 Consider alternative approaches
  • Experimental (varies): 🧪 Cutting-edge features with progressive enhancement

✅ CSS Baseline Availability

Baseline labels are fetched from MDN and kept current; if MDN doesn't expose a Baseline status for a property, the server falls back to the support-level heuristic.

When you pass the baseline parameter, responses include an emoji tag per suggestion:

  • 🟢 Widely Available: broadly supported and safe for most production usage
  • 🔵 Newly Available: recently supported, validate target browsers
  • 🟡 Limited Availability: spotty support; use progressive enhancement
  • 🟣 Experimental: likely behind flags or drafts; only for experiments

🔧 Automated Feature Discovery

This MCP features automated CSS feature discovery using MDN documentation. The system continuously discovers and integrates recent CSS features (2021-2025) with intelligent categorization.

Automated Feature Discovery

  • 🤖 Auto-Discovery: Automatically finds and categorizes new CSS features from MDN
  • 📊 Intelligent Categorization: Uses semantic analysis to categorize features by type
  • 🔄 Continuous Updates: Built-in mechanisms for ongoing feature maintenance
  • 📈 Browser Support Analysis: Automatic extraction of compatibility information

Recently Integrated Features (2021-2025)

🆕 Major CSS Features Added

  • Container Queries (2022): Element-based responsive design with logical units (cqi, cqb) and style/scroll queries
  • CSS Nesting (2023): Native CSS nesting without preprocessors
  • :has() Pseudo-class (2022): Parent selection based on children
  • Dynamic Viewport Units (2022-2023): Complete logical viewport units (dvi, dvb, svi, svb, lvi, lvb) with physical fallbacks
  • color-mix() Function (2021-2024): Advanced color mixing in different color spaces
  • Scroll-driven Animations (2023-2024): Animations driven by scroll progress
  • CSS Cascade Layers (2022): Better style organization with @layer
  • Subgrid (2021-2023): Grid items participating in parent grid
  • aspect-ratio Property (2021): Native aspect ratio control
  • Enhanced Math Functions (2021-2023): clamp(), round(), trigonometric functions

📱 Responsive & Modern Layout

  • CSS Anchor Positioning (2024): Position elements relative to other elements
  • View Transitions (2023-2024): Smooth page/view transitions
  • Enhanced Logical Properties: Complete writing-mode aware spacing, sizing, and positioning
  • Container Style Queries: Query container's computed style values
  • Container Scroll State Queries: Query container's scroll state
  • Masonry Layout (Experimental): Pinterest-style layouts

🎨 Visual & Color Enhancements

  • accent-color: Customize form control colors
  • color-scheme: Light/dark mode indication
  • light-dark() Function: Theme-aware color values
  • backdrop-filter: Glass morphism effects
  • conic-gradient: Conical gradients for complex designs
  • corner-shape (Experimental): Superellipse curves for organic, Apple-like rounded corners

Automated Update Commands

# Discover and integrate new CSS features from MDN
npm run update-features

# Run feature discovery (development)
npm run discover-features

MDN Setup

  • Uses direct MDN parsing with caching and structured extraction
  • No external MCP dependencies required for documentation lookups

🌍 Logical Units & Internationalization

This MCP implements a logical-first approach to CSS suggestions, prioritizing writing-mode aware properties for better internationalization support.

Logical Units Priority System

Viewport Units (Logical Preferred)

  • dvi, dvb (dynamic viewport inline/block) → dvw, dvh (physical fallback)
  • svi, svb (small viewport inline/block) → svw, svh (physical fallback)
  • lvi, lvb (large viewport inline/block) → lvw, lvh (physical fallback)

Container Query Units (Logical Preferred)

  • cqi, cqb (container query inline/block) → cqw, cqh (physical fallback)

CSS Properties (Logical Preferred)

  • inline-size, block-size → width, height (physical fallback)
  • margin-inline, margin-block → margin-left/right, margin-top/bottom
  • padding-inline, padding-block → padding-left/right, padding-top/bottom
  • border-inline, border-block → border-left/right, border-top/bottom
  • inset-inline, inset-block → left/right, top/bottom

Advanced Container Queries

Size-based Container Queries (Enhanced)

@container (inline-size > 30cqi) {
  .component {
    gap: 2cqi;
  }
}

Style Queries (NEW)

@container style(--theme: dark) {
  .card {
    background: var(--dark-bg);
  }
}

Scroll State Queries (NEW)

@container scroll-state(stuck: top) {
  .header {
    backdrop-filter: blur(10px);
  }
}

Writing-Mode Awareness

  • RTL Language Support: Logical properties automatically adapt to right-to-left languages
  • Vertical Writing Modes: Properties work correctly with writing-mode: vertical-rl
  • International Compatibility: Suggestions prioritize globally compatible approaches

License

MIT