@preply/ds-mcp

@preply/ds-mcp — Design System MCP Server

A Model Context Protocol (MCP) server that exposes Preply Design System knowledge to MCP-compatible clients (e.g., Claude Code, Cursor, etc.). It provides tools to discover components, read component docs, search design tokens by name/value, and find media icons.

Installing in the client

Cursor

Claude Code

claude mcp add ds-mcp -- npx -y @preply/ds-mcp@latest start

Other

Add an MCP server entry to your IDE config. Example:

{
  "mcpServers": {
    "ds-mcp": {
      "command": "npx",
      "args": ["-y", "@preply/ds-mcp@latest", "start"],
    },
  },
}

Any MCP client that supports stdio transports should work.

Using in DS repo

• Build DS packages
• Add MCP using absolute path to the binary (example):

{
  "mcpServers": {
    "ds-mcp": {
      "command": "node",
      "args": ["/Users/user/path/to/preply/design-system/packages/mcp/dist/index.js", "start"],
    },
  },
}

Available tools

The server registers the following tools. Tool names are the exact identifiers you’ll see in your MCP client.

list-components

• Description: Lists all available components from @preply/ds-web-lib and @preply/ds-web-root.
• Input: none
• Output: Text list with fields per item: name, import, description, deprecated.
• Notes: Use get-component-docs for full docs of a specific component.

get-component-docs

• Description: Returns markdown documentation for a specific component.
• Input:
  • name (string): Component name (e.g., Button).
• Output: Markdown content with import, description, tags, and props.

search_token_by_name

• Description: Search tokens by name in any of these formats.
• Input:
  • name (string): Raw (e.g., dropShadow.1.shorthand), SCSS (e.g., $dropShadow-1-shorthand), Less (e.g., @dropShadow-1-shorthand), or TypeScript (e.g., dropShadow[1].shorthand). Partial queries allowed.
  • format (enum: scss | less | typescript): Output formatting.
  • includeExample (boolean, default true): Include a usage example snippet.
• Output: Either a single exact match or a list of similar tokens, formatted as requested.

search_token_by_value

• Description: Find tokens by their value.
• Input:
  • value (string): e.g., numeric (500), color (#000000, rgba(...)), size (16px), font (Inter), etc.
  • format (enum: scss | less | typescript): Output formatting.
  • includeExample (boolean, default true): Include a usage example snippet.
• Output: List of matching tokens formatted as requested.

search_icon

• Description: Search media icons from @preply/ds-media-icons by name.
• Input:
  • name (string): With or without the TokyoUI prefix (e.g., Close or TokyoUIClose).
  • includeExample (boolean, default true): Include a usage example snippet.
• Output: Exact match (with full icon name) or a list of similar icons. Includes an example of usage with Icon from @preply/ds-web-lib when requested.

Development

yarn dev:inspector # starts the MCP inspector
yarn dev:logs # shows the debug logs