css-mcp 0.1.1__tar.gz

css_mcp-0.1.1/.envrc

@@ -0,0 +1 @@
+layout uv

css_mcp-0.1.1/.gitignore

@@ -0,0 +1,63 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Distribution
+*.manifest
+*.spec
+
+# Logs
+*.log
+
+# Cache
+.css_mcp_cache/
+.cache/
+
+# OS
+.DS_Store
+Thumbs.db

css_mcp-0.1.1/CLAUDE.md

@@ -0,0 +1,106 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+CSS MCP Server is an MCP (Model Context Protocol) server for CSS analysis and documentation, designed for the FastBlocks ecosystem. It provides 9 tools for analyzing programmatically generated CSS from style adapters like Kelp UI and WebAwesome.
+
+## Development Commands
+
+```bash
+# Install dependencies
+uv sync --group dev
+
+# Run tests
+pytest
+
+# Type check
+mypy css_mcp
+
+# Lint
+ruff check css_mcp
+
+# Run the server locally
+css-mcp
+# or
+python -m css_mcp.server
+```
+
+## Architecture
+
+The server is built on FastMCP and follows a modular architecture:
+
+```
+css_mcp/
+├── server.py      # MCP server entry point, tool registration
+├── tools.py       # Tool implementations with Pydantic input models
+├── analyzer.py    # Core CSS analysis engine (150+ metrics)
+├── mdn_fetcher.py # MDN Web Docs documentation fetcher
+├── compat.py      # Browser compatibility checker
+└── config.py      # Configuration with environment variable support
+```
+
+### Key Components
+
+**CSSAnalyzer** (`analyzer.py`): The core analysis engine that parses CSS using tinycss2 and computes 150+ metrics including:
+- Complexity scores (0-100)
+- Specificity analysis with distribution
+- Selector patterns (ID, class, element, universal)
+- Property categorization (layout, typography, flexbox, grid, etc.)
+- Quality metrics (duplicates, empty rules, !important usage)
+
+**MDNFetcher** (`mdn_fetcher.py`): Fetches CSS property documentation from MDN Web Docs with built-in fallback metadata for common properties.
+
+**BrowserCompatChecker** (`compat.py`): Built-in browser compatibility data for major CSS properties across Chrome, Firefox, Safari, and Edge.
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `analyze_css` | Full CSS analysis with 150+ metrics |
+| `analyze_css_summary` | Quick summary (faster) |
+| `get_docs` | MDN documentation for CSS properties |
+| `get_browser_compatibility` | Browser support checking |
+| `search_properties` | Search CSS properties |
+| `get_properties_by_category` | Properties by category |
+| `analyze_project_css` | Project-wide CSS analysis |
+| `list_capabilities` | List available tools |
+| `health_check` | Server health status |
+
+## Configuration
+
+Environment variables (prefix: `CSS_MCP_`):
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CSS_MCP_HTTP_PORT` | 3050 | Server port |
+| `CSS_MCP_HTTP_HOST` | localhost | Server host |
+| `CSS_MCP_DEBUG` | false | Enable debug mode |
+
+## Dependencies
+
+- **fastmcp**: MCP server framework
+- **tinycss2**: CSS parsing
+- **cssselect**: Selector parsing
+- **httpx**: Async HTTP for MDN fetching
+- **pydantic**: Data validation
+- **mcp-common**: Shared MCP utilities
+- **oneiric**: Configuration management
+
+## FastBlocks Integration
+
+This server is designed for analyzing CSS generated by FastBlocks style adapters:
+- Kelp UI (custom lightweight framework)
+- WebAwesome (Font Awesome components)
+- Vanilla (minimal semantic styling)
+
+When analyzing generated CSS, use `CSSAnalyzer` directly:
+
+```python
+from css_mcp.analyzer import CSSAnalyzer
+
+analyzer = CSSAnalyzer()
+metrics = analyzer.analyze(css_content)
+suggestions = analyzer.get_suggestions()
+```

css_mcp-0.1.1/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Robert Leslie and Wedgwood Web Works
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

css_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,170 @@
+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

css_mcp-0.1.1/README.md

@@ -0,0 +1,140 @@
+# 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

css_mcp-0.1.1/css_mcp/__init__.py

@@ -0,0 +1,14 @@
+"""CSS MCP Server - CSS analysis and documentation for FastBlocks ecosystem."""
+
+__version__ = "0.1.0"
+__author__ = "Les Leslie"
+
+from css_mcp.analyzer import CSSAnalyzer, CSSMetrics, CSSProperty
+from css_mcp.config import CSSMCPConfig
+
+__all__ = [
+    "CSSAnalyzer",
+    "CSSMetrics",
+    "CSSProperty",
+    "CSSMCPConfig",
+]

css_mcp-0.1.1/css_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for running CSS MCP as a module."""
+
+from css_mcp.server import main
+
+if __name__ == "__main__":
+    main()