# CSS MCP Server

[![Code style: crackerjack](https://img.shields.io/badge/code%20style-crackerjack-000042)](https://github.com/lesleslie/crackerjack)
[![Runtime: oneiric](https://img.shields.io/badge/runtime-oneiric-6e5494)](https://github.com/lesleslie/oneiric)
[![Framework: FastMCP](https://img.shields.io/badge/framework-FastMCP-0ea5e9)](https://github.com/PrefectHQ/fastmcp)
[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
[![Python: 3.14+](https://img.shields.io/badge/python-3.14%2B-green)](https://www.python.org/downloads/)

Universal CSS Analysis and Documentation MCP Server. Analyze any CSS with ~150 derived metrics (built on ~78 `CSSMetrics` fields plus selector/property counters) for complexity, specificity, and quality.

## Features

- **CSS Analysis**: ~150 derived metrics (78 `CSSMetrics` fields plus selector/property counters) for CSS complexity, specificity, and quality
- **MDN Documentation**: Fetch CSS property docs from MDN Web Docs
- **Browser Compatibility**: Check cross-browser support for CSS properties
- **Project Analysis**: Analyze all CSS files in a project

## Installation

```bash
# Using uv
uv pip install css-mcp

# Using pip
pip install css-mcp
```

## Usage

### Start Server

```bash
# Via CLI
css-mcp

# Via Python module
python -m css_mcp.server
```

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CSS_MCP_HTTP_PORT` | 3050 | Server port |
| `CSS_MCP_HTTP_HOST` | localhost | Server host |
| `CSS_MCP_DEBUG` | false | Inherited Oneiric debug flag; sets the field on `CSSMCPSettings` but has no local behavioral effect (no code path in `css_mcp/` reads `settings.debug` yet). Wire-up is tracked as a follow-up. |

## Available Tools

| Tool | Description |
|------|-------------|
| `analyze_css` | Full CSS analysis with ~150 derived metrics |
| `analyze_css_summary` | Quick CSS summary (faster) |
| `get_docs` | MDN documentation for CSS properties |
| `get_browser_compatibility` | Check browser support for properties |
| `search_properties` | Search for CSS properties |
| `get_properties_by_category` | Get properties by category |
| `analyze_project_css` | Analyze all CSS in a project |
| `list_capabilities` | List available capabilities |
| `health_check` | Check server health |

## Programmatic Usage

Use the analyzer directly in Python for any CSS:

### Example: Analyze Any CSS

```python
from css_mcp.analyzer import CSSAnalyzer

# Analyze any CSS content
analyzer = CSSAnalyzer()
metrics = analyzer.analyze(css_content)

# Get complexity score
print(f"Complexity: {metrics.complexity_score}/100")

# Get optimization suggestions
suggestions = analyzer.get_suggestions()
```

## Metrics

The analyzer provides ~150 derived metrics (built from 78 `CSSMetrics` fields plus selector and property counters), including:

### Basic Metrics

- Total rules, selectors, properties
- File size (bytes, gzipped)
- Lines of code

### Selector Metrics

- ID, class, element, universal selectors
- Pseudo-classes and pseudo-elements
- Combinators (descendant, child, sibling)
- Selector depth

### Specificity Metrics

- Average, min, max specificity
- High specificity rules
- Specificity distribution

### Property Metrics

- Unique properties
- Category distribution (layout, typography, etc.)
- Vendor prefixes
- `!important` usage
- CSS custom properties

### Quality Metrics

- Duplicate selectors
- Duplicate properties
- Empty rules
- Complexity score
- Efficiency scores

## Browser Compatibility

Built-in compatibility data for common CSS properties across:

- Chrome
- Firefox
- Safari
- Edge

## Development

```bash
# Install dev dependencies
uv sync --group dev

# Run tests
pytest

# Type check
mypy css_mcp

# Lint
ruff check css_mcp
```

## Installation via Claude Code marketplace

The `css` plugin is published through the [www-mcp-servers marketplace](https://github.com/lesleslie/www-mcp-servers). Register the marketplace once, install the plugin, and the css-mcp HTTP server becomes available as `mcp__css__*` tools alongside three slash commands (`/css-audit-project`, `/css-analyze`, `/css-check-compat`). The plugin manifest lives at `.claude-plugin/plugin.json` and the server is registered in the colocated `.mcp.json` at `http://localhost:3050/mcp` — start the css-mcp server first, then run `claude plugin install css --marketplace www-mcp-servers` from a fresh session.

## License

BSD-3-Clause

Built on [Oneiric](https://github.com/lesleslie/oneiric) for runtime configuration
and [mcp-common](https://github.com/lesleslie/mcp-common) for the FastMCP
baseline. [Crackerjack](https://github.com/lesleslie/crackerjack) gates every commit.