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

Install in Cursor

Go to: Settings -> Cursor Settings -> MCP -> Add new global MCP server

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

If you installed globally: use "command": "amicompat-mcp" and "args": []

Install in Claude Code

Run this command. See Claude Code MCP docs for more info.

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

Install in Windsurf

Add this to your Windsurf MCP config file. See Windsurf MCP docs for more info.

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

Install in VS Code

Add this to your VS Code MCP config file. See VS Code MCP docs for more info.

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

Install in Cline

Open Cline.
Click the hamburger menu icon (☰) to enter the MCP Servers section.
Choose Local Servers tab.
Click the Edit Configuration button.
Add amicompat-mcp to mcpServers:

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

Install in Zed

Add this to your Zed settings.json. See Zed Context Server docs for more info.

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

Install in Roo Code

Add this to your Roo Code MCP configuration file. See Roo Code MCP docs for more info.

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

Install in Gemini CLI

See Gemini CLI Configuration for details.

Add the following to the mcpServers object in your ~/.gemini/settings.json file:

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

Install in Claude Desktop

Open Claude Desktop developer settings and edit your claude_desktop_config.json file. See Claude Desktop MCP docs for more info.

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

Install in OpenAI Codex

Add the following configuration to your OpenAI Codex MCP server settings:

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

Install in JetBrains AI Assistant

See JetBrains AI Assistant Documentation for more details.

In JetBrains IDEs, go to Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP)
Click + Add.
Add this configuration and click OK

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

Install in Copilot Coding Agent

Add the following configuration to the mcp section of your Copilot Coding Agent configuration file:

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

Install in LM Studio

Navigate to Program (right side) > Install > Edit mcp.json.
Paste the configuration given below:

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

Install in Perplexity Desktop

Navigate Perplexity > Settings
Select Connectors.
Click Add Connector.
Select Advanced.
Enter Server Name: AmICompat
Paste the following JSON in the text area:

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

Fork the repository
Create feature branch: git checkout -b feature/amazing-feature
Install dependencies: npm install
Run tests: npm test
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
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 🌐✨

Name		Name	Last commit message	Last commit date
Latest commit History 53 Commits
.github/workflows		.github/workflows
scripts		scripts
src		src
test-project		test-project
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

AmICompat MCP - Be compatible regardless of the browser

❌ Without AmICompat

✅ With AmICompat

🛠️ Installation

Requirements

Quick Start (No Installation Required)

Optional: Local Installation

MCP Client Configuration

🔨 Available Tools

🎯 Supported Technologies

CSS

HTML

📊 Baseline Targets

🛟 Usage Examples

Project-wide Analysis

Single File Check

Custom Rules Integration

📊 Example Output

Console Report

JSON Export (Rich Data)

💻 CLI Usage

🧪 Testing

Test Coverage

🏗️ Architecture

Why Hybrid ESLint + compute-baseline?

ESLint Baseline Integration

Project Structure

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Uh oh!

Releases

Packages

Languages

License

jolehuit/amicompat

Folders and files

Latest commit

History

Repository files navigation

AmICompat MCP - Be compatible regardless of the browser

❌ Without AmICompat

✅ With AmICompat

🛠️ Installation

Requirements

Quick Start (No Installation Required)

Optional: Local Installation

MCP Client Configuration

🔨 Available Tools

🎯 Supported Technologies

CSS

HTML

📊 Baseline Targets

🛟 Usage Examples

Project-wide Analysis

Single File Check

Custom Rules Integration

📊 Example Output

Console Report

JSON Export (Rich Data)

💻 CLI Usage

🧪 Testing

Test Coverage

🏗️ Architecture

Why Hybrid ESLint + compute-baseline?

ESLint Baseline Integration

Project Structure

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages