Spectrum Design Data MCP Server

⚠️ Deprecated — This package is no longer actively maintained. New projects should use @adobe/design-data-mcp instead, which runs in-process via wasm and is the actively maintained successor. Note that @adobe/design-data-mcp is not a drop-in replacement — it has different tool names and does not include query-tokens-by-value, validate-component-props, or the component-schema tools. This package remains available for backward compatibility but will receive no new features.

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+

For compatibility, token tools project the canonical embedded dataset through @adobe/design-data-wasm instead of reading generated legacy token files. Tool names and response shapes are unchanged. This package remains deprecated. Workspace development requires moon run sdk-wasm:build before running its tests.

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-design-data/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 Spectrum tokens by name, type, or category
• query-tokens-by-value: Find tokens by direct or resolved value (follows aliases)
• get-token-details: Get detailed information about a specific token
• get-component-tokens: Get all tokens for a component name

Schema Tools

• list-components: List available components (no schema payload)
• get-component-schema: Full schema for one component
• validate-component-props: Validate props against schema
• search-components-by-feature: Find components by property name

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": ["-y", "@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-design-data/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

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 button-related tokens across categories:
- Color tokens: floating-action-button colors
- Layout tokens: button sizing, padding, spacing
- Examples: radio-button-control-size-small, action-button-edge-to-hold-icon...

Finding Tokens by Value

Human: Which tokens resolve to 1px?

AI: I'll search for tokens whose value is 1px (direct or alias).

[Uses query-tokens-by-value with value="1px"]

Tokens with value 1px:
- border-width-100 (direct)
- picker-border-width (alias to border-width-100)

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-design-data
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 -y 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