css-mcp

# CSS MCP Server An MCP (Model Context Protocol) server that provides up-to-date CSS documentation from MDN and comprehensive CSS code analysis. ## Features **Documentation & Compatibility:** - Official MDN Docs - Fetches documentation directly from MDN's API - Browser Compatibility - Includes browser support data from MDN's BCD - Simple API - Just pass CSS property names like `"grid"`, `"flexbox"`, or `":has"` - Markdown Conversion - Converts HTML documentation to clean, readable markdown - Auto-normalization - Supports both simple slugs (`"grid"`) and full paths (`"Web/CSS/grid"`) - Smart Caching - SQLite-based cache with 7-day TTL for blazing-fast responses **CSS Analysis:** - 150+ Metrics - Comprehensive analysis of stylesheet quality and complexity - Design Patterns - Detect color palettes, font sizes, spacing patterns - Code Quality - Selector complexity, specificity analysis, property usage - Performance Insights - Identify overly complex selectors and redundant code ## Installation ### For Claude Code Install via the Claude Code CLI: ```bash claude mcp add css -- npx -y css-mcp ``` ### For VS Code One click install: [](https://vscode.dev/redirect/mcp/install?name=css&config=%7B%22name%22%3A%22css-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22css-mcp%22%5D%2C%22env%22%3A%7B%7D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=css&config=%7B%22name%22%3A%22css%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22css-mcp%22%5D%2C%22env%22%3A%7B%7D%7D&quality=insiders) Install via VS Code CLI: ```bash code --add-mcp '{\"name\":\"css\",\"command\":\"npx\",\"args\":[\"-y\",\"css-mcp\"],\"env\":{}}' ``` ### For MCP Clients (Claude Desktop, etc.) Add to your MCP settings configuration: ```json { "mcpServers": { "css": { "command": "npx", "args": ["-y", "css-mcp"] } } } ``` ### For Development ```bash npm install -g css-mcp ``` Or use with npx: ```bash npx css-mcp --self-test ``` ## Requirements - Node.js 20+ - Build tools for native modules (usually pre-installed on most systems) ## Usage ### Available Tools #### `get_docs` Fetch CSS documentation for any property, selector, function, or concept. **Parameters:** - `slug` (string) - CSS feature name or MDN path **Examples:** ```javascript // Simple slugs (auto-normalized) get_docs({ slug: "grid" }); get_docs({ slug: ":has" }); get_docs({ slug: "flexbox" }); get_docs({ slug: "@media" }); get_docs({ slug: "::before" }); // Full MDN paths also work get_docs({ slug: "Web/CSS/grid" }); get_docs({ slug: "en-US/docs/Web/CSS/border-radius" }); ``` **Returns:** ```json { "source": "mdn-doc", "slug": "/en-US/docs/Web/CSS/grid", "url": "https://developer.mozilla.org/en-US/docs/Web/CSS/grid/index.json", "title": "grid", "mdn_url": "/en-US/docs/Web/CSS/grid", "summary": "The grid CSS property is a shorthand...", "body": [ { "type": "prose", "title": "Syntax", "content": "The **`grid`** property is a shorthand..." } ] } ``` #### `get_browser_compatibility` Fetch browser compatibility data for CSS features. **Parameters:** - `bcd_id` (string) - Browser Compat Data ID (e.g., `"css.properties.grid"`) **Example:** ```javascript get_browser_compatibility({ bcd_id: "css.properties.grid" }); get_browser_compatibility({ bcd_id: "css.selectors.has" }); ``` #### `analyze_css` Analyze CSS code for quality, complexity, and design patterns. Returns **curated summary by default** (lightweight, ~1-2k tokens). Use `summaryOnly: false` for complete 150+ metrics (uses ~10k+ tokens). **Parameters:** - `css` (string, required) - CSS code to analyze - `summaryOnly` (boolean, optional) - Return summary instead of full analysis. Default: `true` **Examples:** ```javascript // Summary mode (default, lightweight) analyze_css({ css: ` .container { display: grid; color: #3b82f6; } ` }); // Full analysis with all 150+ metrics analyze_css({ css: "...", summaryOnly: false }); ``` **Returns (default summary):** ```json { "analysis": { "stylesheet": { "sourceLinesOfCode": 5, "size": 72 }, "rules": { "total": 1 }, "selectors": { "total": 1, "averageComplexity": 1.0, "maxComplexity": 1 }, "colors": { "unique": 1, "uniqueColors": ["#3b82f6"] } }, "note": "Summary metrics only. Use summaryOnly: false for complete 150+ metrics." } ``` #### `analyze_project_css` Analyze all CSS files in a project. Finds CSS files recursively, combines them, and provides project-wide analysis. **Framework-agnostic** - works with built CSS from any framework (SvelteKit, React, Vue, etc.). Returns **curated summary metrics by default** (lightweight, ~1-2k tokens). Use `includeFullAnalysis: true` for complete data (uses ~10k+ tokens). **Automatically excludes:** - `**/node_modules/**` - `**/*.min.css` **Parameters:** - `path` (string, required) - File path, directory, or glob pattern - `includeFullAnalysis` (boolean, optional) - Return full 150+ metrics instead of summary. Default: `false` - `exclude` (array of strings, optional) - Additional glob patterns to exclude **Examples:** ```javascript // Analyze all CSS in a directory (summary - default, lightweight) analyze_project_css({ path: "dist" }); // Full analysis with all 150+ metrics (uses more tokens) analyze_project_css({ path: "dist", includeFullAnalysis: true }); // Exclude additional patterns analyze_project_css({ path: "dist", exclude: ["**/vendor/**", "**/*.legacy.css"] }); // Analyze specific file analyze_project_css({ path: "public/styles.css" }); // Use glob patterns analyze_project_css({ path: "dist/**/*.css" }); ``` **Returns (default summary):** ```json { "files": { "total": 5, "analyzed": 5, "errors": 0, "list": [ { "path": "/path/to/style.css", "size": 2048 }, { "path": "/path/to/theme.css", "size": 1024 } ] }, "summary": { "stylesheet": { "sourceLinesOfCode": 450, "size": 12800 }, "rules": { "total": 85 }, "selectors": { "total": 120, "averageComplexity": 1.4, "maxComplexity": 5 }, "colors": { "unique": 12, "uniqueColors": ["#3b82f6", "#10b981", ...] }, "fontSizes": { "unique": 8, "uniqueSizes": ["1rem", "1.5rem", ...] } }, "note": "Summary metrics only. Use includeFullAnalysis: true for complete data." } ``` ## Cache Management The server automatically: - Creates cache at `~/.cache/css-mcp/cache.db` - Cleans up expired entries on startup - Tracks hit counts for each cached entry - Uses WAL mode for better concurrent performance To clear the cache: ```bash rm -rf ~/.cache/css-mcp/ ``` ## Self-Test Verify the server is working correctly: ```bash npm test # or css-mcp --self-test # or npx css-mcp --self-test ``` Expected output: ``` docs ok (simple slug): { input: 'grid', slug: '/en-US/docs/Web/CSS/grid', ... } docs ok (pseudo-selector + markdown): { input: ':has', ... } bcd ok: { bcd_id: 'css.properties.grid', has_compat: true, ... } ``` ## Example: Using with Claude Code Once configured, you can ask Claude Code: **Documentation & Compatibility:** > "Use the CSS MCP to get documentation for flexbox" > "What browser support does :has selector have?" > "Explain how CSS grid works" **CSS Analysis:** > "Analyze this CSS and tell me what could be improved" > "What colors are used in my stylesheet?" > "Check the complexity of my selectors" **Project Analysis:** > "Analyze all CSS in my dist folder" > "What's the total complexity of my project's CSS?" > "Show me all colors used across my entire project" Claude will automatically use the MCP to fetch the latest MDN documentation and analyze CSS code. ## Development ```bash # Clone the repository git clone https://github.com/stolinski/css-mcp.git cd css-mcp # Install dependencies npm install # Link for local development npm link # Run tests npm test ``` ## Performance & Limits **Caching:** - **First fetch**: ~400-500ms (network + cache write) - **Cached fetch**: ~100ms (**~5x faster**) - **Cache size**: ~390KB for typical usage **Input Limits:** - **Max file size**: 10MB per CSS file - **Max total size**: 50MB combined - **Max files**: 500 CSS files per analysis - **Network timeout**: 10 seconds for MDN API calls ## Troubleshooting ### "Module did not self-register" This usually means native modules need rebuilding: ```bash npm rebuild better-sqlite3 ``` ### Cache not working Check cache directory permissions: ```bash ls -la ~/.cache/css-mcp/ ``` Should show `cache.db`, `cache.db-shm`, and `cache.db-wal` files. ## Contributing This is an experimental MCP server for CSS documentation tooling, let's work on tools that make AI better at CSS