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 analysis - Robust feature detection for CSS and HTML
• 📊 Baseline compatibility reports - Standards-based browser support analysis
• 🎯 Targeted recommendations - Specific baseline violation identification
• 🚀 Local processing - Fast analysis using native ESLint rules
• 📈 Coverage metrics - Clear baseline violation reporting

🛠️ 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", "export_last_report"]
    }
  }
}

{
  "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

• export_last_report: Export the most recent audit report

  • path (required): File path for the exported JSON report

🎯 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

🎯 Baseline Compatibility Report

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

🔍 Detected Features:
   • CSS view-transition-name property (1 location)
   • CSS anchor-name property (1 location)
   • HTML <search> element (1 location)

💻 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
• ESLint-based Detection: Uses ESLint for robust and reliable feature detection
• Native Baseline Rules: Powered by @eslint/css and @html-eslint use-baseline rules
• Zod Validation: Type-safe MCP tool inputs and outputs
• Simplified Design: Clean, maintainable codebase focused on CSS and HTML

Why ESLint-based Detection?

• 🛡️ Robustness: ESLint handles edge cases and syntax variations better than custom parsers
• 🔧 Maintainability: Leverages battle-tested, community-maintained parsing logic
• ⚡ Performance: Optimized parsing engine designed for large codebases
• 🚀 Extensibility: Easy to add new feature detection via ESLint rules
• 🎯 Accuracy: Industry-standard parsing with comprehensive syntax support

Project Structure

src/
├── types/index.ts         # Zod schemas and TypeScript types
├── lib/
│   ├── eslint-wrapper.ts  # ESLint-based feature detection for CSS/HTML
│   └── 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
• Zod - Runtime type validation

AmICompat MCP - Be compatible regardless of the browser 🌐✨