AmICompat MCP - Be compatible regardless of the browser

❌ Without AmICompat

Building modern web applications often means encountering browser compatibility issues:

• ❌ Unclear feature support - Not knowing which browsers support your CSS and HTML
• ❌ Runtime surprises - Features breaking in production on older browsers
• ❌ Manual research - Constantly checking MDN and Can I Use for compatibility
• ❌ Guesswork polyfills - Adding unnecessary or missing polyfills
• ❌ Inconsistent baselines - No standardized way to assess browser support

✅ With AmICompat

AmICompat MCP automatically analyzes your CSS and HTML code and provides instant Web Baseline compatibility insights using ESLint-based feature detection.

Audit my web project for CSS and HTML compatibility issues using widely available baseline

Check this CSS file for modern features that might need polyfills

Analyze my HTML code and tell me what browsers support these elements

AmICompat provides:

• 🔍 ESLint-based detection - Robust feature detection using web-features data
• 🌐 compute-baseline enrichment - Detailed browser support with versions and dates
• 📊 Comprehensive compatibility reports - Full Baseline status with browser versions
• 🎯 Targeted recommendations - Specific baseline violation identification
• 🚀 Local processing - Fast analysis using native ESLint rules
• 📈 Rich JSON exports - Detailed compatibility data for integration

🛠️ Installation

Requirements

• Node.js >= v18.0.0
• Cursor, Claude Code, Windsurf, VS Code, or another MCP Client

Quick Start (No Installation Required)

AmICompat works out of the box with npx - no installation needed! Just configure your MCP client with the configurations below.

Optional: Local Installation

For faster startup times, you can optionally install AmICompat globally:

npm install -g amicompat-mcp

Then use "command": "amicompat-mcp" in your configurations instead of the npx commands.

MCP Client Configuration

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

claude mcp add amicompat-mcp -- npx -y amicompat-mcp

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

"mcp": {
  "servers": {
    "amicompat-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "amicompat-mcp"]
    }
  }
}

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

{
  "context_servers": {
    "AmICompat": {
      "command": {
        "path": "npx",
        "args": ["-y", "amicompat-mcp"]
      }
    }
  }
}

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

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

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

[mcp_servers.amicompat-mcp]
args = ["-y", "amicompat-mcp"]
command = "npx"

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

{
  "mcpServers": {
    "amicompat-mcp": {
      "command": "npx",
      "args": ["-y", "amicompat-mcp"],
      "tools": ["audit_project", "audit_file"]
    }
  }
}

{
  "mcpServers": {
    "AmICompat": {
      "command": "npx",
      "args": ["-y", "amicompat-mcp"]
    }
  }
}

{
  "args": ["-y", "amicompat-mcp"],
  "command": "npx",
  "env": {}
}

🔨 Available Tools

AmICompat MCP provides the following tools that LLMs can use:

• audit_project: Comprehensive project-wide compatibility analysis

  • project_path (required): Path to the project directory
  • target (optional): Baseline target (widely, newly)
  • max_files (optional): Maximum number of files to scan (default: 10000)
  • export_path (optional): Path to export JSON report

• audit_file: Single file compatibility analysis

  • file_path (required): Path to the CSS or HTML file to analyze

🎯 Supported Technologies

AmICompat uses advanced ESLint-based feature detection to analyze:

CSS

• ✅ Container queries (@container)
• ✅ :has() selector
• ✅ CSS Grid subgrid
• ✅ Cascade layers (@layer)
• ✅ Custom properties (@property)
• ✅ color-mix() function
• ✅ CSS nesting
• ✅ View transitions (view-transition-name)
• ✅ Anchor positioning (anchor-name)
• ✅ And more modern CSS features

HTML

• ✅ Dialog element (<dialog>)
• ✅ Search element (<search>)
• ✅ Popover API (<popover>)
• ✅ Lazy loading attributes
• ✅ Modern input types
• ✅ Web components
• ✅ ARIA attributes
• ✅ And more semantic HTML5+ features

📊 Baseline Targets

Choose your compatibility target:

• widely: High baseline - features widely supported across browsers
• newly: Features available in newest browser versions

🛟 Usage Examples

Project-wide Analysis

Run a baseline compatibility audit on my web project for widely available features and export the results to compatibility-report.json

Single File Check

Analyze this CSS file for container query usage and browser support

Custom Rules Integration

Add this rule to your MCP client for automatic compatibility checking:

Always run compatibility analysis with AmICompat when I'm working with modern CSS features,
container queries, CSS Grid, HTML elements, or when I mention browser support concerns.
Use 'widely' as the default target unless specified otherwise.

📊 Example Output

Console Report

🎯 Baseline Compatibility Report

📊 Summary:
   Target: widely
   Features Detected: 3
   Baseline Violations: 3
   Files Scanned: 2

🔍 Detected Features:
   • CSS backdrop-filter property (2 locations)
   • CSS outline property (1 location)

JSON Export (Rich Data)

{
  "project_path": "/path/to/project",
  "target": "widely",
  "features_detected": [
    {
      "feature": "CSS backdrop-filter property",
      "locations": [...],
      "detailed_support": {
        "baseline_status": "low",
        "baseline_low_date": "2024-09-16",
        "browser_support": {
          "chrome": "76",
          "firefox": "103",
          "safari": "18",
          "edge": "79"
        },
        "discouraged": false
      }
    }
  ]
}

💻 CLI Usage

AmICompat also provides a command-line interface:

# Show server information
npx amicompat-mcp info

# Test parser on a file
npx amicompat-mcp test-parse ./src/styles.css

# Audit a project
npx amicompat-mcp audit ./my-project --target widely

# Start MCP server (default)
npx amicompat-mcp

🧪 Testing

AmICompat includes a comprehensive test suite:

npm test                    # Run all tests
npm run test:coverage       # Run with coverage report
npm run test:integration    # Integration tests only
npm run test:cli           # Test CLI functionality

Test Coverage

• Unit Tests: ESLint wrapper, file walker, type validation
• Integration Tests: CLI interface, MCP tools end-to-end functionality
• Feature Detection: CSS and HTML feature detection tests
• Error Handling: Edge cases, malformed code, missing files

🏗️ Architecture

• TypeScript Native: Built with modern TypeScript and strict type checking
• Hybrid Detection: ESLint detection + compute-baseline enrichment for maximum accuracy
• Native Baseline Rules: Uses @eslint/css and @html-eslint built-in use-baseline rules
• web-features Powered: ESLint plugins natively integrate web-features for Baseline validation
• Browser Compatibility Data: Real-time enrichment with BCD via compute-baseline
• Zod Validation: Type-safe MCP tool inputs and outputs
• Rich Data Export: Comprehensive JSON reports with browser versions and dates

Why Hybrid ESLint + compute-baseline?

• 🔍 Robust Detection: ESLint handles syntax parsing with web-features validation
• 🌐 Rich Data: compute-baseline provides detailed browser support information
• ⚡ Performance: Local processing with native ESLint + BCD data
• 🎯 Accuracy: Double-validation via ESLint detection + compute-baseline analysis
• 📊 Comprehensive: Both detection and detailed compatibility in one tool

ESLint Baseline Integration

AmICompat leverages the native Baseline support in ESLint plugins:

• @eslint/css - CSS plugin with built-in use-baseline rule powered by web-features data
• @html-eslint - HTML plugin with built-in use-baseline rule powered by web-features data
• web-features integration - ESLint plugins automatically validate against curated Baseline features
• Seamless detection - No custom parsing needed, ESLint handles all syntax variations with Baseline awareness

Project Structure

src/
├── types/index.ts         # Zod schemas, TypeScript types + DetailedSupport
├── lib/
│   ├── eslint-wrapper.ts  # ESLint detection + compute-baseline enrichment
│   └── walker.ts          # File system walker with filtering
├── tools/index.ts         # MCP tools implementation
├── server.ts              # Main MCP server
└── cli.ts                 # CLI interface with test commands

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Install dependencies: npm install
4. Run tests: npm test
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open Pull Request

📄 License

MIT License. See LICENSE for details.

🙏 Acknowledgments

• MCP TypeScript SDK - Native MCP implementation
• ESLint - Robust CSS and HTML feature detection
• @eslint/css - CSS feature detection with use-baseline rule
• @html-eslint - HTML feature detection with use-baseline rule
• compute-baseline - Browser compatibility data enrichment
• @mdn/browser-compat-data - Comprehensive browser compatibility database
• web-features - Curated web platform features dataset
• Zod - Runtime type validation

AmICompat MCP - Be compatible regardless of the browser 🌐✨