Design System MCP Kit

Generic scaffold for teams building an MCP server that exposes their design system to AI agents.

Inspired by GitHub Primer's @primer/mcp, but split into:

• @ds-mcp/core — reusable framework (tools, registry, adapter contracts)

• examples/acme-ds-mcp — minimal working implementation teams can copy

Why this exists

Primer solved a specific problem well: give AI agents authoritative design-system context instead of hallucinating components, tokens, or accessibility rules.

Most design teams need the same capability, but their sources differ:

• Storybook metadata vs generated JSON vs TypeScript manifests

• Figma tokens vs Style Dictionary vs CSS variables

• Local MDX docs vs remote documentation sites

• Custom lint rules vs Stylelint presets

This kit standardizes the MCP tool surface and lets each team plug in adapters for their own data sources.

Related MCP server: Design System MCP Server

Architecture

flowchart TB
  Agent[AI Agent / Cursor / Copilot]
  Client[MCP Client]
  Server[Your DS MCP Server]
  Core["@ds-mcp/core"]
  Adapters[Team Adapters]
  Sources[(Components / Tokens / Docs / Icons)]

  Agent --> Client --> Server --> Core
  Server --> Adapters --> Sources

Layers

Standard tools (Primer-compatible surface)

Tools auto-register only when the required adapter is present.

Quick start

npm install
npm run build
npm run example:acme

Cursor / VS Code MCP config

{
  "servers": {
    "Acme Design System": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/design-system-mcp-kit/examples/acme-ds-mcp/dist/index.js"]
    }
  }
}

How teams adopt this

Phase 1 — Snapshot bootstrap (1–2 days)

1. Copy examples/acme-ds-mcp to packages/your-ds-mcp

2. Replace data/catalog.snapshot.json with your component/token/icon inventory

3. Update src/config.ts with your system name, package name, and agent instructions

4. Ship stdio MCP to designers and engineers

Good when you need value fast and docs are still maturing.

Phase 2 — Live adapters (1–2 weeks)

Replace snapshot adapters with real integrations:

Phase 3 — Governance (ongoing)

• CI job publishes refreshed snapshots on design-system releases

• Add custom tools via extraTools (e.g. review_jsx, suggest_token, migrate_component)

• Version MCP package alongside design-system semver

Adapter contract (minimal example)

import { createDesignSystemMcpServer } from '@ds-mcp/core';

export function createMyServer() {
  return createDesignSystemMcpServer({
    config: {
      name: 'My Design System',
      version: '1.0.0',
      packageName: '@my-org/design-system',
      instructions: 'Always use My DS components and tokens before custom UI.',
    },
    adapters: {
      components: {
        listComponents: () => [...],
        getComponent: (name) => ({ id: 'button', name: 'Button' }),
      },
      tokens: {
        findTokens: (query) => [...],
        getGroupBundle: (group) => ({ id: group, name: group, tokens: [] }),
      },
    },
  });
}

Comparison with Primer MCP

Primer Brand also ships a separate @primer/brand-mcp with review/setup tools — your framework can add similar custom tools through extraTools.

Recommended repo layout for a team

your-design-system/
├── packages/
│   ├── tokens/
│   ├── react/
│   └── ds-mcp/              # MCP server package
│       ├── data/
│       │   └── catalog.snapshot.json
│       └── src/
│           ├── index.ts
│           ├── config.ts
│           ├── server.ts
│           └── adapters/
│               ├── components.storybook.ts
│               ├── tokens.style-dictionary.ts
│               └── docs.mdx.ts
└── .cursor/mcp.json

Roadmap

• CLI: npm run create:ds-mcp generator

• Storybook adapter template

• Style Dictionary adapter template

• Remote docs fetch adapter (cheerio + turndown, like Primer)

• review_jsx tool for design-system compliance

• GitHub Action to refresh snapshots on release

Contributing

See CONTRIBUTING.md. Bug reports and pull requests are welcome.

License

MIT — see LICENSE.

References

• Primer MCP docs

• Primer MCP source

• Primer Brand MCP source

• Model Context Protocol