@preply/ds-ai-mcp

MCP server for the Preply Design System.

Exposes Preply Design System reference docs — component docs, design tokens, and icons — over the Model Context Protocol (stdio transport), so MCP-compatible clients (Cursor, Claude Desktop, etc.) can query them.

The skills/design-system agent skill is the preferred integration for coding agents: it needs no server process and works with any agent that supports skills. Use this MCP server only for tools that don't support skills.

Data

The server's data is a bundled snapshot of the same skills/design-system/references/ files the skill ships — inlined into the build at compile time. There's no extraction pipeline and no network or filesystem access at runtime; the docs snapshot's version is recorded inline in the bundled rules, and the skill-docs-check CI job keeps it in sync with the design system's components, tokens, and icons.

Usage

As a standalone server

ds-mcp start

Programmatic

import { createServer } from '@preply/ds-ai-mcp';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createServer();
await server.connect(new StdioServerTransport());

MCP client configuration

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

Tools

• list_docs — returns the docs index for a platform (a table of components and guides), the entry point for finding a doc to read.

  list_docs({ platform: "web" })

• read_doc — reads a reference document verbatim by path, relative to references/<platform>/.

  read_doc({ platform: "web", path: "docs/Components/Button.md" })

• search_token_by_name — looks up a design token by name, accepting raw, scss, less, or typescript spellings.

  search_token_by_name({ platform: "web", name: "dropShadow.1.shorthand" })

• search_token_by_value — looks up a design token by its value (color, size, font, etc.), to check whether a hardcoded value already has a token.

  search_token_by_value({ platform: "web", value: "8px" })

• search_icon — searches icons available in @preply/ds-media-icons by name or keyword.

  search_icon({ platform: "web", name: "Close" })

All registered tools are annotated as read-only, idempotent, non-destructive, and closed-world — clients can safely call them in planning/preview modes.

Limitations

• Instructions are advisory. Not all MCP clients surface server instructions to the agent — don't assume the bundled rules were read.
• Docs navigation is agent-driven. There's no single lookup tool for docs content; the agent is expected to loop list_docs → read_doc to find what it needs. Tokens and icons are direct lookups via search_token_by_name, search_token_by_value, and search_icon.
• Content is a snapshot. The bundled docs reflect the design system as of the last package release and may lag behind the latest published components, tokens, or icons.

Telemetry

The server reports anonymous tool-usage events (tool name, arguments, invocation method) to help prioritize which tools and docs to improve. No source code or file contents are ever sent. Set DS_AI_DISABLE_TELEMETRY=1 to opt out.

Development

pnpm build           # Build the package
pnpm dev             # Build in watch mode
pnpm dev:inspector   # Launch with MCP Inspector for debugging
pnpm check:types     # Type-check
pnpm lint            # Lint
pnpm test            # Run tests