Metadata-Version: 2.4
Name: css-mcp
Version: 0.1.1
Summary: CSS analysis and documentation MCP server for FastBlocks ecosystem
Project-URL: Homepage, https://github.com/lesleslie/css-mcp
Project-URL: Repository, https://github.com/lesleslie/css-mcp
Author-email: Les Leslie <les@lesleslie.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.13
Requires-Dist: cssselect>=1.2.0
Requires-Dist: fastmcp>=0.6.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp-common>=0.1.0
Requires-Dist: oneiric>=0.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: tinycss2>=1.3.0
Provides-Extra: dev
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Description-Content-Type: text/markdown

# CSS MCP Server

CSS Analysis and Documentation MCP Server for the FastBlocks ecosystem.

## Features

- **CSS Analysis**: 150+ metrics 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 | Enable debug mode |

## Available Tools

| Tool | Description |
|------|-------------|
| `analyze_css` | Full CSS analysis with 150+ 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 |

## Integration with FastBlocks

This server is designed for analyzing programmatically generated CSS from FastBlocks style adapters:

- **Kelp UI**: Custom lightweight CSS framework
- **WebAwesome**: Font Awesome's component library
- **Vanilla**: Minimal semantic styling

### Example: Analyze Generated CSS

```python
from css_mcp.analyzer import CSSAnalyzer

# Analyze CSS generated by FastBlocks style adapter
analyzer = CSSAnalyzer()
metrics = analyzer.analyze(kelp_css)

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

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

## Metrics

The analyzer provides 150+ metrics 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
```

## License

MIT
