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 code
• ❌ 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 web code and provides instant Web Baseline compatibility insights using ESLint-based feature detection and local Baseline data.

Audit my React project for browser compatibility issues using baseline-2025 target

Check this CSS file for modern features that might need polyfills

Analyze my JavaScript code and tell me what browsers support these features

AmICompat provides:

• 🔍 ESLint-based analysis - Robust feature detection for JavaScript, TypeScript, CSS, and HTML
• 📊 Baseline compatibility reports - Standards-based browser support analysis
• 🎯 Targeted recommendations - Specific polyfill and fallback suggestions
• 🚀 Local processing - Fast analysis using local Baseline data via web-features
• 📈 Coverage metrics - Browser coverage percentages and support levels

🛠️ 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", "get_feature_status", "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 (baseline-2025, baseline-2024,baseline-2023, widely, limited)
  • 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 file to analyze

• get_feature_status: Get Baseline status for specific web features

  • feature (required): Feature identifier (e.g., css-container-queries, js-optional-chaining)

• 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:

JavaScript & TypeScript

• ✅ Optional chaining (?.)
• ✅ Nullish coalescing (??)
• ✅ Private class fields (#field)
• ✅ Top-level await
• ✅ Dynamic imports
• ✅ Decorators
• ✅ And more ES2015+ features

CSS

• ✅ Container queries (@container)
• ✅ :has() selector
• ✅ CSS Grid subgrid
• ✅ Cascade layers (@layer)
• ✅ Custom properties (@property)
• ✅ color-mix() function
• ✅ CSS nesting
• ✅ And more modern CSS features

HTML

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

📊 Baseline Targets

Choose your compatibility target:

• baseline-2025: Features available in all major browsers since 2025
• baseline-2024: Features available in all major browsers since 2024
• baseline-2023: Features available in all major browsers since 2023
• widely: High baseline - widely supported across browsers
• limited: Limited baseline - some browser support

🛟 Usage Examples

Project-wide Analysis

Run a baseline compatibility audit on my React project for baseline-2025 target and export the results to compatibility-report.json

Single File Check

Analyze this CSS file for container query usage and browser support

Feature Status Lookup

What's the baseline status of CSS Grid subgrid feature?

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 web features,
CSS Grid, flexbox, JavaScript ES2015+ syntax, or when I mention browser support concerns.
Use baseline-2025 as the default target unless specified otherwise.

📊 Example Output

🎯 Baseline Compatibility Report

📊 Summary:
   Global Score: 85.2% (Target: baseline-2025)
   Features Detected: 15
   Files Scanned: 127

🌐 Browser Coverage:
   chrome: 95.2%
   firefox: 87.3%
   safari: 71.4%
   edge: 94.1%

📈 Feature Distribution:
   ● Widely Supported: 8
   ● Newly Available: 4
   ● Limited Support: 2
   ● No Support: 1

💡 Recommendations:
   • Consider polyfills for limited support features
   • Pay special attention to safari compatibility (71.4%)
   • Monitor newly available features for wider adoption

💻 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/app.js

# Start MCP server (default)
npx amicompat-mcp

🧪 Testing

AmICompat includes a comprehensive test suite with >90% coverage:

npm test                    # Run all tests (99 tests)
npm run test:coverage       # Run with coverage report
npm run test:integration    # Integration tests only
npm run test:cli           # Test CLI functionality
npm run test:parsers        # Test feature detection with real files

Test Coverage

• Unit Tests: ESLint wrapper, baseline computation, file walker, type validation
• Integration Tests: CLI interface, MCP tools end-to-end functionality
• Feature Detection: 26 comprehensive tests covering JS, CSS, HTML features
• Error Handling: Edge cases, malformed code, missing files
• Performance: Large codebase handling and memory management

🏗️ Architecture

• TypeScript Native: Built with modern TypeScript and strict type checking
• ESLint-based Detection: Uses ESLint for robust and reliable feature detection
• Local Baseline Data: Powered by web-features and compute-baseline for offline analysis
• Zod Validation: Type-safe MCP tool inputs and outputs
• Comprehensive Testing: Unit and integration tests with >90% coverage

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/
│   ├── baseline.ts        # Local Baseline computation via compute-baseline
│   ├── eslint-wrapper.ts  # ESLint-based feature detection
│   └── 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
• web-features - Local Baseline data source
• compute-baseline - Baseline status computation
• ESLint - Robust JavaScript/TypeScript feature detection
• @html-eslint - HTML feature detection
• Zod - Runtime type validation

AmICompat MCP - Be compatible regardless of the browser 🌐✨