Design Scraper MCP Server

An MCP (Model Context Protocol) server that analyzes websites and automatically generates comprehensive design systems and style guides. Simply provide a URL and get detailed design analysis including colors, typography, borders, themes, and visual elements.

Features

🎨 Comprehensive Design Analysis

Color Extraction: Automatically detects background and foreground colors
Typography Analysis: Identifies heading and body font families
Border Properties: Extracts border radius, width, and styling
Theme Detection: Determines light/dark mode and overall theme
Visual Elements: Analyzes buttons, headers, and interactive components

📸 Visual Documentation

Full-page screenshot capture
Visual reference for design system validation
Responsive viewport analysis

🛠️ Developer-Friendly Output

CSS custom properties generation
Accessibility compliance checking (WCAG 2.1 AA)
Interactive HTML style guide artifacts
Copy-friendly code snippets

Prerequisites

Node.js v18.x or higher
npm

Installation

Clone the repository
Install dependencies:

npm install

MCP Server Configuration

Claude Desktop Configuration

To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file:

Location of config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "design-scraper-mcp": {
      "command": "node",
      "args": ["/path/to/design-scraper-mcp/src/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

If installed globally via npm:

{
  "mcpServers": {
    "design-scraper-mcp": {
      "command": "npx",
      "args": ["design-scraper-mcp"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Other MCP Clients

For other MCP-compatible clients, use these connection details:

Stdio Transport:

node /path/to/design-scraper-mcp/src/index.js

Environment Variables:

NODE_ENV: Set to production for production use
DEBUG: Set to design-scraper-mcp:* for debug logging

Verification

After adding the configuration:

Restart Claude Desktop completely
Look for the connection indicator - you should see "design-scraper-mcp" in the MCP servers list

Test the connection by asking Claude to analyze a website:

Can you analyze the design of https://example.com using the design scraper?

Troubleshooting

Server not connecting:

Verify the path to the script is correct
Ensure Node.js is installed and accessible
Check that all dependencies are installed (npm install)
Restart Claude Desktop after configuration changes

Permission issues:

Ensure the script has execute permissions
On macOS/Linux: chmod +x /path/to/design-scraper-mcp/src/index.js

Debug mode: Add debug environment variable to see detailed logs:

{
  "mcpServers": {
    "design-scraper-mcp": {
      "command": "node",
      "args": ["/path/to/design-scraper-mcp/src/index.js"],
      "env": {
        "NODE_ENV": "production",
        "DEBUG": "design-scraper-mcp:*"
      }
    }
  }
}

Usage

As an MCP Server

Start the server:

npm start

The server provides two main tools:

1. Design System Generator (`generate`)

Analyzes a website and creates a comprehensive style guide:

// Example usage through MCP client
const result = await client.callTool({
  name: "generate",
  arguments: {
    url: "https://example.com",
  },
});

Input Schema:

url (string, required): Valid URL to analyze

Output includes:

Complete design system analysis with visual screenshot
Color palette with background/foreground color extraction
Typography hierarchy with heading and body font detection
Visual design tokens (border radius, width, styling)
Theme mode detection (light/dark/auto)
Element-specific styling (buttons, headers, footers)
Implementation guide with CSS custom properties
Accessibility compliance checking

Example Response Structure:

{
  "content": [
    {
      "type": "text",
      "text": "🎨 DESIGN SYSTEM GENERATOR\n\n📸 VISUAL REFERENCE\n- Full Page Screenshot Captured\n- Dimensions: 1920px x 1080px\n\nCreate a comprehensive website style guide HTML artifact...\n\n=== COMPLETE DESIGN DATA ===\n{\n  \"theme\": \"light\",\n  \"colors\": {\n    \"backgrounds\": [\"#ffffff\", \"#f8f9fa\"],\n    \"foregrounds\": [\"#212529\", \"#6c757d\"],\n    \"elements\": {\n      \"button\": [{\n        \"background\": \"#007bff\",\n        \"foreground\": \"#ffffff\",\n        \"score\": 5\n      }],\n      \"header\": {\n        \"background\": \"#ffffff\",\n        \"foreground\": \"#212529\"\n      }\n    }\n  },\n  \"fonts\": {\n    \"headings\": \"Inter\",\n    \"body\": \"system-ui\"\n  },\n  \"borders\": {\n    \"borderRadius\": \"8px\",\n    \"borderWidth\": \"1px\",\n    \"borderColor\": \"#dee2e6\"\n  }\n}"
    },
    {
      "type": "image",
      "data": "base64-encoded-screenshot",
      "mimeType": "image/png"
    }
  ]
}

2. Website Screenshot (`screenshot`)

Captures full-page screenshots for visual reference:

// Example usage through MCP client
const result = await client.callTool({
  name: "screenshot",
  arguments: {
    url: "https://example.com",
    viewportWidth: 1920, // optional, default: 1920
    viewportHeight: 1080, // optional, default: 1080
  },
});

Input Schema:

url (string, required): Valid URL to capture
viewportWidth (number, optional): Browser viewport width in pixels
viewportHeight (number, optional): Browser viewport height in pixels

Example Response:

{
  "content": [
    {
      "type": "image",
      "data": "base64-encoded-screenshot",
      "mimeType": "image/png"
    },
    {
      "type": "text",
      "text": "Screenshot details:\nURL: https://example.com\nWidth: 1920\nHeight: 1080\nSize: 245760 bytes"
    }
  ]
}

Individual Extractor APIs

Color Extraction:

const colorData = await colors('https://example.com');
// Returns:
{
  backgrounds: ['#ffffff', '#f8f9fa'],
  foregrounds: ['#212529', '#6c757d'],
  elements: {
    button: [{ background: '#007bff', foreground: '#ffffff', score: 5 }],
    header: { background: '#ffffff', foreground: '#212529' },
    body: { background: '#ffffff', foreground: '#212529' },
    footer: { background: '#f8f9fa', foreground: '#6c757d' }
  }
}

Font Analysis:

const fontData = await getFontUsage('https://example.com');
// Returns:
{
  headings: 'Inter',
  body: 'system-ui'
}

Border Properties:

const borderData = await getBorderProperties('https://example.com');
// Returns:
{
  borderRadius: '8px',
  borderWidth: '1px',
  borderColor: '#dee2e6'
}

Theme Detection:

const themeData = await theme("https://example.com");
// Returns: 'light' | 'dark'

Screenshot Capture:

const screenshotData = await screenshots('https://example.com', {
  viewportWidth: 1920,
  viewportHeight: 1080
});
// Returns:
{
  screenshot: 'base64-encoded-image-data',
  dimensions: { width: 1920, height: 1080 },
  size: 245760
}

Architecture

The project uses a modular extractor pipeline system with the following components:

Core Components

src/extractor.js - Core pipeline system for modular data extraction
- Manages browser lifecycle and page navigation
- Orchestrates sequential execution of extractors
- Provides error handling and graceful degradation
- Supports extractor chaining with .add() method
src/browserManager.js - Singleton browser manager using Puppeteer
- Handles browser initialization and cleanup
- Manages page creation and navigation
- Optimizes resource usage with singleton pattern
src/generate.js - Main pipeline runner that orchestrates all extractors
- Combines theme, colors, fonts, and borders extractors
- Returns unified design system data structure
- Entry point for complete design analysis

Individual Extractors

src/colors.js - Advanced color extraction and analysis
- Extracts background and foreground colors from all elements
- Analyzes button color combinations with scoring system
- Identifies header, body, and footer color schemes
- Converts all colors to consistent hex format
- Filters out invalid/transparent color combinations
src/fonts.js - Comprehensive typography detection and analysis
- Analyzes font usage across heading and body elements
- Categorizes fonts by type (serif, sans-serif, monospace, etc.)
- Identifies web fonts vs system fonts
- Provides usage statistics and font hierarchy
- Extracts font weights, styles, and sizes
src/borders.js - Border and visual element extraction
- Analyzes border radius, width, and color properties
- Tracks usage frequency across all elements
- Identifies most common border patterns
- Supports complex border-radius values
- Converts colors to hex format for consistency
src/theme.js - Intelligent theme mode detection
- Analyzes background and text color brightness
- Checks for dark theme CSS classes
- Evaluates CSS color-scheme property
- Considers user's prefers-color-scheme preference
- Returns 'light' or 'dark' theme classification
src/screenshots.js - Full-page screenshot capture
- Captures complete page screenshots with custom viewport sizes
- Returns base64-encoded image data
- Provides image dimensions and file size metadata
- Supports responsive viewport configuration

Extractor Pipeline Usage

import Extractor from "./src/extractor.js";

const extractor = new Extractor();
extractor
  .add("theme", themeExtractor)
  .add("colors", colorsExtractor)
  .add("fonts", fontsExtractor)
  .add("borders", bordersExtractor);

const results = await extractor.extract("https://example.com");

Code Style Guidelines

ES6 Modules: Uses type: "module" with .js extensions for imports
Async/Await: Modern asynchronous patterns throughout
Error Handling: Graceful degradation with proper try/catch blocks
Modular Design: Each extractor is independent and reusable
JSDoc Comments: Comprehensive documentation for methods and parameters
Consistent Naming: PascalCase for classes, camelCase for functions
Color Normalization: All colors converted to lowercase hex format

Output Format Specification

The design system generator produces structured data:

Complete Design System Structure

{
  theme: 'light' | 'dark',
  colors: {
    backgrounds: ['#ffffff', '#f8f9fa'],
    foregrounds: ['#212529', '#6c757d'],
    elements: {
      button: [{ background: '#007bff', foreground: '#ffffff', score: 5 }],
      header: { background: '#ffffff', foreground: '#212529' },
      body: { background: '#ffffff', foreground: '#212529' },
      footer: { background: '#f8f9fa', foreground: '#6c757d' }
    }
  },
  fonts: {
    headings: 'Inter',
    body: 'system-ui'
  },
  borders: {
    borderRadius: '8px',
    borderWidth: '1px',
    borderColor: '#dee2e6'
  }
}

Generated Style Guide Sections

Color Palette - Organized backgrounds, foregrounds, and element-specific colors with usage guidelines
Typography System - Font hierarchy with heading and body font specifications and examples
Visual Design Tokens - Border radius, spacing, and styling specifications with CSS custom properties
Theme Specifications - Light and dark mode color schemes with accessibility considerations
Element Guidelines - Button, header, body, footer color combinations with hover states
Implementation Guide - Ready-to-use CSS custom properties and code snippets
Accessibility Report - WCAG 2.1 AA compliance analysis with contrast ratios

Performance Considerations

Browser Reuse: Singleton browser manager reduces initialization overhead
Sequential Processing: Extractors run sequentially to avoid resource conflicts
Memory Management: Pages are properly closed after extraction
Error Isolation: Failed extractors don't affect other pipeline components
Viewport Optimization: Screenshots use efficient viewport sizing

Testing

This project uses Vitest for unit testing with comprehensive test coverage.

Running Tests

# Run tests in watch mode (development)
npm test

# Run tests once (CI/production)
npm run test:run

# Run tests with coverage report
npm run test:coverage

Test Structure

Tests are located in the test/ directory and follow the naming convention *.test.js. The test suite includes:

Unit Tests: Individual extractor functions (color parsing, theme detection, etc.)
Integration Tests: Full pipeline extraction workflows
Mock Tests: Browser automation without actual network requests

Coverage Reports

Coverage reports are generated in multiple formats:

Terminal: Text summary displayed after test runs
HTML: Interactive coverage report in coverage/index.html
LCOV: Machine-readable format for CI integration

GitHub Actions

Automated testing runs on every push and pull request:

Tests against Node.js versions 18.x, 20.x, and 22.x
Includes linting checks with Prettier
Generates coverage reports
Uploads coverage data to Codecov (optional)

Dependencies

@modelcontextprotocol/sdk (^1.17.2) - MCP server framework for tool registration
puppeteer (^24.16.1) - Headless browser automation for web scraping and screenshots
chalk (^5.5.0) - Terminal styling for colored console output
zod (^3.25.76) - Schema validation for input parameters and type safety

Development Dependencies

vitest (^3.2.4) - Fast unit testing framework with native ES modules support
prettier (^3.6.2) - Code formatting and style consistency

Troubleshooting

Common Issues

Browser Launch Failures:

Ensure system has required dependencies for Puppeteer
Check for sufficient memory and disk space
Verify network connectivity for target URLs

Color Extraction Issues:

Some websites may use CSS-in-JS or dynamic styling
Transparent/inherited colors are filtered out automatically
Complex CSS selectors may not capture all elements

Font Detection Limitations:

Web fonts may not be detected if not fully loaded
System font fallbacks are identified when possible
Font variations (weights/styles) are captured separately

Theme Detection Edge Cases:

Websites with mixed light/dark sections may be ambiguous
CSS custom properties for theming may not be detected
User preference detection requires browser support

License

MIT - See LICENSE file for details.

Name		Name	Last commit message	Last commit date
Latest commit History 5 Commits
.github/workflows		.github/workflows
src		src
test		test
.gitignore		.gitignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
AGENT.md		AGENT.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
vitest.config.js		vitest.config.js

License

daveconstell/design-scraper-mcp

Folders and files

Latest commit

History

Repository files navigation

Design Scraper MCP Server

Features

Prerequisites

Installation

MCP Server Configuration

Claude Desktop Configuration

Other MCP Clients

Verification

Troubleshooting

Usage

As an MCP Server

1. Design System Generator (generate)

2. Website Screenshot (screenshot)

Individual Extractor APIs

Architecture

Core Components

Individual Extractors

Extractor Pipeline Usage

Code Style Guidelines

Output Format Specification

Complete Design System Structure

Generated Style Guide Sections

Performance Considerations

Testing

Running Tests

Test Structure

Coverage Reports

GitHub Actions

Dependencies

Development Dependencies

Troubleshooting

Common Issues

License

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

1. Design System Generator (`generate`)

2. Website Screenshot (`screenshot`)

Packages