Macmillan Design System MCP Server

A Model Context Protocol (MCP) server that provides access to the Macmillan Design System tokens and component guidelines. This server follows the ITCSS (Inverted Triangle CSS) architecture and exposes design tokens, component guidelines, and code generation capabilities.

🚀 Quick Start

Prerequisites

• Node.js (v16 or higher)
• TypeScript (for development)

Installation & Setup

1. Clone and build the server:

   git clone <repository-url>
   cd mcp-design-system
   npm install
   npm run build

2. Test the server:

   echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node build/index.js

3. Configure your MCP client (see Client Configuration)

✨ Self-Discovery Feature

The server exposes its own documentation! Any MCP client can immediately discover how to use it:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_usage_instructions",
    "arguments": {"format": "markdown"}
  }
}

This means AI assistants can automatically learn how to use your design system without external documentation!

📡 Available Endpoints

🛠️ Tools (Interactive Functions)

1. get_design_tokens

Retrieve design tokens from the Macmillan design system following ITCSS architecture.

Parameters:

• layer (optional, default: "all"):
  • "settings" - Primitive tokens from SCSS variables
  • "tokens" - Semantic tokens mapped to CSS custom properties
  • "all" - Both layers
• category (optional, default: "all"):
  • "colors" - Color palette and semantic colors
  • "spacing" - Spacing scale and semantic spacing
  • "typography" - Font families, sizes, weights, line heights
  • "radius" - Border radius values
  • "shadows" - Box shadow definitions
  • "borders" - Border width definitions
  • "all" - All categories

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_design_tokens",
    "arguments": {
      "layer": "tokens",
      "category": "colors"
    }
  }
}

Example Response:

{
  "result": {
    "content": [{
      "type": "text",
      "text": "{\n  \"foreground\": {\n    \"hero\": \"var(--mac-color-fg-hero)\",\n    \"primary\": \"var(--mac-color-fg-primary)\",\n    ...\n  }\n}"
    }]
  }
}

2. get_component_guidelines

Get comprehensive usage guidelines, variants, and examples for a specific component.

Parameters:

• componentName (required): Component name
  • Available: "button", "card", "input", "heading", "link"

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_component_guidelines",
    "arguments": {
      "componentName": "button"
    }
  }
}

3. list_available_components

List all available components in the design system with their variants and descriptions.

Parameters: None

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_available_components",
    "arguments": {}
  }
}

4. generate_component

Generate a React component with TypeScript interfaces and SCSS implementation using design system tokens.

Parameters:

• componentType (required): Type of component (e.g., "button", "card", "input")
• variant (optional): Component variant (e.g., "primary", "secondary")
• props (optional): Additional props object
• includeAccessibility (optional, default: true): Include ARIA attributes

5. get_usage_instructions

Get comprehensive documentation and usage instructions for this MCP server.

Parameters:

• format (optional, default: "json"): Output format ("json" or "markdown")

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_usage_instructions",
    "arguments": {
      "format": "markdown"
    }
  }
}

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_component",
    "arguments": {
      "componentType": "button",
      "variant": "primary",
      "includeAccessibility": true
    }
  }
}

📚 Resources (Static Data)

1. design-system://tokens

Complete design system tokens in JSON format.

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": {
    "uri": "design-system://tokens"
  }
}

2. design-system://guidelines

Complete component guidelines in JSON format.

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": {
    "uri": "design-system://guidelines"
  }
}

3. design-system://documentation

Complete server documentation and usage instructions in JSON format.

Example Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/read",
  "params": {
    "uri": "design-system://documentation"
  }
}

🔧 Client Configuration

Claude Desktop Configuration

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "macmillan-design-system": {
      "command": "node",
      "args": ["D:/CODE/AI/mcp-servers/mcp-design-system/build/index.js"],
      "env": {}
    }
  }
}

Configuration file locations:

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

Programmatic Usage

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
import { spawn } from "child_process";

const client = new Client(
  { name: "design-system-client", version: "1.0.0" },
  { capabilities: {} }
);

const serverProcess = spawn("node", ["./build/index.js"]);
const transport = new StdioClientTransport({
  reader: serverProcess.stdout,
  writer: serverProcess.stdin,
});

await client.connect(transport);

// Example: Get color tokens
const result = await client.request(
  { method: "tools/call" },
  {
    name: "get_design_tokens",
    arguments: { layer: "tokens", category: "colors" }
  }
);

🎨 Design System Structure

ITCSS Layers

The design system follows ITCSS (Inverted Triangle CSS) architecture:

Settings Layer (Primitives)

Raw, unprocessed design tokens:

• Brand colors (brand5, brand20, brand40, etc.)
• Spacing primitives (xs1-4, s1-4, m1-4, l1-4)
• Typography primitives (font families, weights, sizes)
• Border and radius primitives

Tokens Layer (Semantic)

Semantic tokens mapped to CSS custom properties:

• Foreground colors (var(--mac-color-fg-*))
• Background colors (var(--mac-color-bg-*))
• Spacing tokens (var(--mac-spacing-*))
• Typography tokens (var(--mac-fontsize-*))

Available Components

Component	Variants	Sizes	Description
Button	primary, secondary, outline, ghost, hero	small, medium, large	Interactive buttons with semantic tokens
Card	elevated, outlined, filled, hero	-	Content containers with elevation
Input	text, email, password, number, textarea, select	-	Form inputs with validation states
Heading	h1, h2, h3, h4, h5, h6, h7	-	Hierarchical headings following typography scale
Link	default, hero, button-style	large, medium, small, xsmall	Styled links with hover/focus states

💡 Usage Examples

Example 1: Get Spacing Tokens from Settings Layer

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_design_tokens","arguments":{"layer":"settings","category":"spacing"}}}' | node build/index.js

Example 2: Get Button Component Guidelines

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_component_guidelines","arguments":{"componentName":"button"}}}' | node build/index.js

Example 3: Generate a Hero Button Component

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"generate_component","arguments":{"componentType":"button","variant":"hero","includeAccessibility":true}}}' | node build/index.js

Example 4: Get All Typography Tokens

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_design_tokens","arguments":{"category":"typography"}}}' | node build/index.js

🧪 Testing the Server

Basic Connectivity Test

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node build/index.js

Full Functionality Test

# Test tools listing
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node build/index.js

# Test resources listing  
echo '{"jsonrpc":"2.0","id":1,"method":"resources/list","params":{}}' | node build/index.js

# Test token retrieval
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_design_tokens","arguments":{"layer":"tokens","category":"colors"}}}' | node build/index.js

# Test component generation
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","parameters":{"name":"generate_component","arguments":{"componentType":"button","variant":"primary"}}}' | node build/index.js

🏗️ Development

Building

npm run build

Watching for Changes

npm run watch

Project Structure

src/
├── index.ts              # Main MCP server implementation
├── tokens/
│   ├── tokens.scss       # CSS custom properties
│   ├── settings/         # ITCSS Settings layer (primitives)
│   │   ├── colors.scss
│   │   ├── spacing.scss
│   │   ├── typography.scss
│   │   └── ...
│   └── ...
build/
└── index.js              # Compiled server

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Build and test: npm run build && npm test
5. Submit a pull request

📄 License

[Add your license information here]

🆘 Troubleshooting

Common Issues

Server won't start:

• Ensure Node.js version is 16 or higher
• Run npm install and npm run build
• Check that all dependencies are installed

Claude Desktop can't find the server:

• Verify the path in claude_desktop_config.json is correct
• Ensure the server builds without errors
• Restart Claude Desktop after configuration changes

Token queries return empty results:

• Check that the layer and category parameters are valid
• Use "all" for both parameters to see all available tokens

For more help, please create an issue in the repository.