Spectrum Design Data MCP Server

A Model Context Protocol (MCP) server that provides AI tools with structured access to Adobe Spectrum design system data, including design tokens and component API schemas.

Overview

This MCP server enables AI assistants to query and interact with Spectrum design data through a standardized protocol. It provides access to:

• Design Tokens: Color palettes, typography, layout tokens, and semantic tokens
• Component Schemas: API definitions and validation schemas for Spectrum components
• Future: Component anatomy, design patterns, and guidelines

Prerequisites

• Node.js 20+

Installation

npm install -g @adobe/spectrum-design-data-mcp

Verifying Package Integrity

This package is published with npm provenance for enhanced supply-chain security. You can verify the package's attestations:

npm audit signatures

Or clone and run locally:

git clone https://github.com/adobe/spectrum-design-data.git
cd spectrum-tokens/tools/spectrum-design-data-mcp
pnpm install

Usage

Starting the MCP Server

# Start the server (default command)
spectrum-design-data-mcp

# Or explicitly start
spectrum-design-data-mcp start

The server runs locally and communicates via stdio with MCP-compatible AI clients.

Available Tools

Token Tools

• query-tokens: Search and retrieve design tokens by name, type, or category
• find-tokens-by-use-case ⭐: Find appropriate tokens for specific component use cases (e.g., "button background", "text color", "error state")
• get-component-tokens ⭐: Get all tokens related to a specific component type
• get-design-recommendations ⭐: Get token recommendations for design decisions and component states
• get-token-categories: List all available token categories
• get-token-details: Get detailed information about a specific token

Schema Tools

• query-component-schemas: Search component API schemas
• get-component-schema: Get the complete schema for a specific component
• list-components: List all available components with schemas
• validate-component-props: Validate component properties against schemas
• get-type-schemas: Get type definitions used in schemas

Configuration

MCP Setup

Add to your MCP configuration (e.g., .cursor/mcp.json for Cursor IDE):

Option 1: Using npx (Recommended)

{
  "mcpServers": {
    "spectrum-design-data": {
      "command": "npx",
      "args": ["@adobe/spectrum-design-data-mcp"]
    }
  }
}

Option 2: Using global installation

{
  "mcpServers": {
    "spectrum-design-data": {
      "command": "@adobe/spectrum-design-data-mcp"
    }
  }
}

Option 3: Local development

{
  "mcpServers": {
    "spectrum-design-data": {
      "command": "node",
      "args": [
        "./path/to/spectrum-tokens/tools/spectrum-design-data-mcp/src/index.js"
      ]
    }
  }
}

Note: Using npx (Option 1) is recommended as it avoids PATH issues and ensures you always use the latest version. This approach mirrors other MCP servers like Browser MCP and resolves common NPX availability problems.

Claude Desktop (Legacy Configuration)

For older Claude Desktop configurations:

{
  "mcpServers": {
    "spectrum-design-data": {
      "command": "spectrum-design-data-mcp",
      "args": []
    }
  }
}

Other MCP Clients

The server uses stdio transport and follows the MCP specification. Refer to your client's documentation for configuration details.

Examples

Component Building Workflow ⭐

Finding Tokens for Component Use Cases

Human: I'm building a primary action button. What design tokens should I use for the background color?

AI: I'll help you find the appropriate tokens for a primary button background.

[Uses find-tokens-by-use-case with useCase="button background" and componentType="button"]

For a primary action button background, I recommend these Spectrum tokens:
- accent-color-100: Primary accent color for default state
- accent-color-200: For hover states
- accent-color-300: For pressed/active states
- floating-action-button-drop-shadow-color: For drop shadows

Design Intent Recommendations

Human: What tokens should I use for error messaging in my form validation?

AI: I'll find tokens for error state messaging.

[Uses get-design-recommendations with intent="negative" and context="text"]

For error messaging, use these Spectrum tokens:
- negative-color-100: Primary error text color
- negative-background-color-default: Error background areas
- negative-border-color: Error state borders

Component-Specific Token Discovery

Human: Show me all available button-related design tokens.

AI: I'll gather all button-related tokens from the Spectrum system.

[Uses get-component-tokens with componentName="button"]

Found 57 button-related tokens across categories:
- Color tokens (2): floating-action-button colors
- Layout tokens (55): button sizing, padding, spacing
- Examples: radio-button-control-size-small, action-button-edge-to-hold-icon...

Traditional Token Queries

Querying Color Tokens

Human: What blue color tokens are available in Spectrum?

AI: I'll search for blue color tokens in the Spectrum design system.

[Uses query-tokens tool with query="blue" and category="color"]

The Spectrum design system includes several blue color tokens:
- spectrum-blue-100: #e6f3ff
- spectrum-blue-200: #b3d9ff
- spectrum-blue-300: #80bfff
...

Validating Component Props

Human: Is this button configuration valid according to Spectrum?

AI: I'll validate those button properties against the Spectrum schema.

[Uses validate-component-props tool with component="action-button"]

The configuration is valid! All required properties are present and the types match the expected schema.

Troubleshooting

Installation Issues

# Check Node.js version
node --version  # Should be 20+

# Clear npm cache if needed
npm cache clean --force

# Verify package installation
npm list -g @adobe/spectrum-design-data-mcp

MCP Connection Issues

1. Verify the MCP configuration file path
2. Check that Node.js path is correct
3. Ensure the package is installed globally or use npx
4. Restart your AI client after configuration changes

Package Verification

# Verify package integrity
npm audit signatures

# Check for security vulnerabilities
npm audit

Development

Building from Source

git clone https://github.com/adobe/spectrum-design-data.git
cd spectrum-tokens
pnpm install
cd tools/spectrum-design-data-mcp

Testing

pnpm test

Project Structure

src/
├── index.js              # Main MCP server
├── cli.js               # CLI interface
├── tools/               # MCP tool implementations
│   ├── tokens.js        # Token-related tools
│   └── schemas.js       # Schema-related tools
└── data/                # Data access layer
    ├── tokens.js        # Token data access
    └── schemas.js       # Schema data access

Security

Supply Chain Security

• 🔐 NPM Provenance: Published with npm provenance attestations for verifiable builds
• 🛡️ Security Audits: Regular dependency security audits
• 📦 Verified Packages: All dependencies are audited and verified

Best Practices

• Always verify package integrity using npm audit signatures
• Keep the package updated to the latest version
• Use npx for the most secure and up-to-date execution
• Report security issues through the GitHub security advisory

License

Apache-2.0 © Adobe

Contributing

This project is part of the Spectrum Design System. Please see the main contribution guidelines for details on how to contribute.

Support

• Create an issue for bug reports or feature requests
• Check the documentation for detailed guides
• Review existing issues for solutions