ECL MCP Server

A Model Context Protocol (MCP) server that provides comprehensive knowledge about the Europa Component Library (ECL) - the design system for the European Commission and websites managed by the Commission.

Overview

This MCP server gives you instant access to:

169 crawled ECL pages with full documentation
50+ ECL components with semantic search and metadata
520+ usage guidance items (do's, don'ts, best practices)
756 code examples with complexity ratings and language filtering
783 accessibility requirements (WCAG, ARIA, keyboard support)
30+ API documentation entries (attributes, props, methods, events)
1,366 component tags for advanced filtering
Complete setup guides for NPM and CDN installation
Design guidelines (typography, colors, spacing, iconography)
JavaScript initialization patterns with auto-init support

What Makes This Server Special

Unlike basic documentation servers, this MCP server provides:

Semantic Search - Multi-filter search across components, API, examples, and guidance
Structured Data - Rich metadata including complexity, JavaScript requirements, variants
Cross-References - Discover component relationships and dependencies
Usage Guidance - Know when to use (and when NOT to use) each component
Code Examples - Filter by language, complexity, completeness
Accessibility First - WCAG compliance data and implementation notes
Design Tokens - Access to design system tokens (colors, spacing, typography)
Code Generation - Generate customized components and interactive playgrounds
Validation Tools - Check WCAG compliance, code quality, and component conflicts
Intelligent Responses - Helpful suggestions when results are empty
Component Validation - Validate HTML/JS against ECL requirements with quality scoring
Accessibility Checking - Verify WCAG 2.1 compliance (Level A, AA, AAA)
Code Analysis - Detect components, find anti-patterns, check design token usage
Conflict Detection - Identify incompatible component combinations

Installation

npm install

Usage

Running the Server

npm start

For development with auto-restart:

npm run dev

Adding to MCP Client Configuration

Add this server to your MCP client configuration (e.g., Claude Desktop, Cline):

{ "mcpServers": { "ecl": { "command": "node", "args": ["/home/simon/git/CNECT/ecl_mcp/index.js"] } } }

Available Tools

This server provides 28 tools organized in multiple categories:

3 Code Generation Tools (Phase 5) - Generate customized components and interactive playgrounds
4 Validation Tools (Phase 4) - Validate components, check accessibility, analyze code quality
14 Enhanced Search Tools (Phase 3) - Semantic search with rich metadata (prefix: ecl_*)
7 Legacy Tools (Phase 1) - Basic functionality for backward compatibility

For complete tool reference, see TOOLS.md

Quick Reference

Code Generation:

ecl_get_complete_example - Get runnable examples with all dependencies included
ecl_generate_component - Generate customized components with variants, sizes, content
ecl_create_playground - Create interactive multi-component testing environments

Validation & Diagnostics:

ecl_validate_component_usage - Validate HTML/JS against ECL requirements with quality scoring
ecl_check_accessibility - Verify WCAG 2.1 compliance (Level A, AA, AAA)
ecl_analyze_ecl_code - Detect components, find anti-patterns, check design token usage
ecl_check_conflicts - Identify incompatible component combinations

Component Discovery:

ecl_search_components - Advanced multi-filter component search
ecl_get_component_details - Complete component information

API Documentation:

ecl_search_api - Search attributes, props, methods, events
ecl_get_component_api - Get all API for a component

Code Examples:

ecl_search_code_examples - Search by language, complexity, completeness
ecl_get_example - Get complete code by ID
ecl_get_component_examples - Get all examples for a component

Usage Guidance:

ecl_get_component_guidance - Get do's, don'ts, best practices
ecl_search_guidance - Search guidance across all components

Component Relationships:

ecl_find_related_components - Find dependencies and conflicts
ecl_get_dependency_graph - Build recursive dependency graph

Design Tokens:

ecl_search_design_tokens - Search by name or category
ecl_get_tokens_by_category - Get all tokens for category
ecl_get_token - Get specific token details

Legacy Tools (Phase 1)

1. `get_component`

Get detailed information about a specific ECL component.

Parameters:

component_name (string): Name of the component (e.g., "button", "card", "accordion")

Example:

{ "component_name": "button" }

2. `search_components`

Search for components by category, name, or keyword.

Parameters:

query (string): Search query (category, keyword, or name)

Example:

{ "query": "forms" }

3. `generate_component_code`

Generate ready-to-use HTML code for a component.

Parameters:

component_name (string): Name of the component
variant (string, optional): Component variant (e.g., "primary", "secondary")

Example:

{ "component_name": "button", "variant": "primary" }

4. `get_setup_guide`

Get complete setup guide for integrating ECL.

Parameters:

method (string): "npm", "cdn", or "complete"

Example:

{ "method": "complete" }

5. `list_components_by_category`

List all components in a specific category.

Parameters:

category (string): One of: "forms", "navigation", "content", "media", "banners", "site-wide"

Example:

{ "category": "forms" }

6. `get_guidelines`

Get ECL design guidelines.

Parameters:

guideline_type (string): One of: "typography", "colours", "colors", "images", "iconography", "spacing", "all"

Example:

{ "guideline_type": "typography" }

7. `get_javascript_init`

Get JavaScript initialization code for components.

Parameters:

component_name (string, optional): Specific component name

Example:

{ "component_name": "accordion" }

Available Resources

The server provides several resources that can be accessed directly:

ecl://overview - Complete overview of ECL
ecl://installation - Installation and setup guide
ecl://components - List of all components
ecl://guidelines - Design guidelines
ecl://setup-template - Ready-to-use HTML template

ECL Components Included

Forms

Checkbox, Datepicker, File Upload, Radio, Range, Rating Field, Search Form, Select, Text Area, Text Field

Navigation

Breadcrumb, Inpage Navigation, Links, Mega Menu, Menu, Navigation List, Pagination, Tabs

Content

Accordion, Blockquote, Button, Card, Category Filter, Content Item, Date Block, Expandable, Fact & Figures, File, Icon, Label, List, List with Illustration, Loading Indicator, Message, Modal, News Ticker, Notification, Popover, Separator, Social Media Follow, Social Media Share, Splash Page, Table, Tag, Timeline

Media

Banners

Banner, Carousel

Site-wide

Site Header, Page Header, Site Footer

Features

Core Capabilities

✅ Comprehensive Database: 169 crawled pages, 50+ components, 3,495 structured records
✅ Semantic Search: Multi-filter search across components, API, examples, and guidance
✅ Rich Metadata: Component complexity, JavaScript requirements, variants, status
✅ Code Examples: 756 examples with language, complexity, and completeness filtering
✅ Usage Guidance: 520+ do's, don'ts, best practices, and caveats
✅ Accessibility Data: 783 requirements with WCAG criteria and implementation notes
✅ API Documentation: 30+ entries covering attributes, props, methods, events
✅ Component Tags: 1,366 tags for advanced categorization
✅ Design Tokens: Token search by category (colors, spacing, typography)
✅ Relationships: Discover component dependencies and conflicts
✅ Performance: Query execution 0-50ms typical
✅ Standardized Responses: Consistent JSON format with metadata and suggestions

Database Schema

8 New Tables (Phase 2): ├── component_metadata (169 records) - Component types and complexity ├── component_api (30 records) - Attributes, props, methods, events ├── design_tokens (0 records*) - Colors, spacing, typography tokens ├── usage_guidance (520 records) - Do's, don'ts, best practices ├── component_relationships (0 records*) - Requires/suggests/conflicts ├── component_tags (1,366 records) - Categorization tags ├── enhanced_code_examples (756 records) - Example metadata └── accessibility_requirements (783 records) - WCAG, ARIA, keyboard support *Needs refinement in future iterations

Example Use Cases

Finding and Understanding Components

// 1. Search for interactive components requiring JavaScript ecl_search_components({ tag: "interactive", requiresJs: true, limit: 10 }) // 2. Get complete details including tags, complexity, status ecl_get_component_details({ component: "accordion" }) // 3. Check usage guidance (when to use, do's, don'ts) ecl_get_component_guidance({ component: "accordion" }) // 4. Review accessibility requirements // Returns WCAG criteria, ARIA patterns, keyboard support

Building with Components

// 1. Find form components ecl_search_components({ category: "forms" }) // 2. Check component API ecl_get_component_api({ component: "text-field" }) // 3. Get code examples filtered by complexity ecl_search_code_examples({ component: "text-field", language: "html", complexity: "basic" }) // 4. Check for component dependencies ecl_get_dependency_graph({ component: "form", maxDepth: 2 })

Exploring Design Tokens

// 1. List all token categories ecl_get_token_categories() // 2. Get all color tokens ecl_get_tokens_by_category({ category: "color" }) // 3. Find specific token ecl_get_token({ tokenName: "primary-color" }) // 4. Search tokens by keyword ecl_search_design_tokens({ query: "spacing" })

Accessibility Compliance

// 1. Search for accessible components ecl_search_components({ tag: "accessible" }) // 2. Get component details with accessibility data ecl_get_component_details({ component: "button" }) // 3. Review WCAG requirements // Returns accessibility_requirements with WCAG criteria

ECL Version

This server is based on ECL v4.11.1 (EU variant)

Resources

Official ECL Site: https://ec.europa.eu/component-library/
GitHub: https://github.com/ec-europa/europa-component-library
NPM: https://www.npmjs.com/org/ecl
Playground: https://ec.europa.eu/component-library/playground/eu/

License

MIT

Important Notes

Always host SVG sprites on the same domain to avoid CORS issues
ECL uses Pikaday for datepicker - must be loaded separately
Include Cookie Consent Kit before going live
Recommended to host ECL resources locally rather than using CDN
Use data-ecl-auto-init attribute for automatic component initialization
Call ECL.autoInit() after page load for auto-initialization

Support

For ECL-specific questions, refer to the official documentation at https://ec.europa.eu/component-library/

For issues with this MCP server, please check the code or create an issue in your repository.

ECL MCP Server

Overview

What Makes This Server Special

Installation

Usage

Running the Server

Adding to MCP Client Configuration

Available Tools

Quick Reference

Legacy Tools (Phase 1)

1. get_component

2. search_components

3. generate_component_code

4. get_setup_guide

5. list_components_by_category

6. get_guidelines

7. get_javascript_init

Available Resources

ECL Components Included

Forms

Navigation

Content

Media

Banners

Site-wide

Features

Core Capabilities

Database Schema

Example Use Cases

Finding and Understanding Components

Building with Components

Exploring Design Tokens

Accessibility Compliance

ECL Version

Resources

License

Important Notes

Support

Related Resources

New MCP Servers

MCP directory API

1. `get_component`

2. `search_components`

3. `generate_component_code`

4. `get_setup_guide`

5. `list_components_by_category`

6. `get_guidelines`

7. `get_javascript_init`