io.github.Patrizzos/stylesafe

StyleSafe - MCP and CLI

An MCP server and CLI that catches CSS cascade conflicts and Tailwind utility clashes before they ship — built for AI coding agents and CI workflows.

What it does

• Detects duplicate CSS declarations and dead rules from specificity conflicts
• Flags silent style overrides that may be accidental
• Finds conflicting Tailwind utilities (padding, margin, background, shadow, opacity, border, ring, etc.)
• Understands cn(), clsx(), and twMerge() call expressions, not just plain className strings
• Returns structured agent-friendly reports with confidence, riskScore, and nextStep

Quick start

As a CLI tool

npm install -g stylesafe
stylesafe src/components/Button.jsx
stylesafe --changed --fail-on-issues
stylesafe --projectRoot src
stylesafe --watch src

As an MCP server

{
  "mcpServers": {
    "stylesafe": {
      "command": "node",
      "args": ["/absolute/path/to/server.js"]
    }
  }
}

Example output

stylesafe examples/tailwind-conflict.jsx

Returns a structured report:

{
  "totalIssues": 5,
  "riskScore": 275,
  "averageRiskScore": 55,
  "riskLevel": "medium",
  "passed": true,
  "clean": false,
  "files": [
    {
      "filename": "examples/tailwind-conflict.jsx",
      "issues": [
        {
          "type": "tailwind-conflict",
          "category": "padding",
          "classes": ["p-4", "px-8"],
          "confidence": "medium",
          "riskScore": 55,
          "nextStep": "Choose one utility from the conflicting set or split the classes by scope.",
          "requiresUserConfirmation": true
        }
      ]
    }
  ]
}

passed: true means no hard errors. clean: true means zero issues of any kind.

Use cases

• AI code generation: Catch style bugs before the agent commits changes
• PR gate: Block merged changes that introduce cascade conflicts or utility clashes
• Agent workflows: Integrate as a confirmation step in multi-turn coding tasks
• Style audits: Run across a project to find existing issues

CLI options

• stylesafe <file> — analyze a single file
• stylesafe <dir> — analyze a directory recursively
• stylesafe --projectRoot <dir> — same as above
• stylesafe --changed — analyze git-changed files (for PR/CI)
• stylesafe --changed --fail-on-issues — exit with code 1 if any issues found
• stylesafe --watch src — re-run on every file change
• npm test — run regression tests

Config

Place a .styleintegrityrc file in your project root:

{
  "ignore": ["dist", "*.min.css"],
  "failOn": ["error", "warning"]
}

GitHub Actions

Add to .github/workflows/style-check.yml:

name: stylesafe

on:
  pull_request:
  push:
    branches: [main]

jobs:
  stylesafe:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install
      - run: node server.js --changed --fail-on-issues