css-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

For a shorter, tool-neutral bootstrap document, start with AGENTS.md.

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

# 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, async create_app + sync wrapper
├── tools/         # Tool implementations
│   ├── __init__.py # Pydantic input models + register_tools (all 9 tools) + register_health_tool (health probe)
│   └── profiles.py # Tool profile dispatch (W4.1, mcp-common>=0.18.0)
├── analyzer.py    # Core CSS analysis engine (~150 derived metrics over 78 CSSMetrics fields)
├── mdn_fetcher.py # MDN Web Docs documentation fetcher
├── compat.py      # Browser compatibility checker
├── config.py      # Configuration with environment variable support
├── cli.py         # Console-script entry (css-mcp) wired to mcp-common factory
├── __main__.py    # `python -m css_mcp` entry point
└── __init__.py    # Package metadata (CSSAnalyzer, CSSMetrics, CSSMCPSettings exports)

Key Components

CSSAnalyzer (analyzer.py): The core analysis engine that parses CSS using tinycss2 and computes ~150 derived metrics (78 CSSMetrics fields plus selector/property counters) 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)