ds-mcp

Stop asking AI agents to guess your design system. Give them a contract they can query.

Part of the dspack ecosystem — the organization profile has the full map of how the repositories fit together.

Kind: application (MCP server, npm @aestheticfunction/ds-mcp, bin ds-mcp) · Audience: people using AI coding agents against a design system, and MCP client authors · Neighbors: implements the dspack spec; vendors its generation core from dspack-gen; bootstrap a contract with dspack-export; see the full chain running in dspack-studio (hosted replay)

The problem

AI coding agents generate UI by guessing: they invent component names, fabricate props, hardcode color values, and ignore the patterns your team has documented. Every generated file needs manual correction to match your design system.

Related MCP server: BrixUI MCP Server

The solution

ds-mcp is a read-only MCP server that loads a dspack file — a portable JSON description of your design system — and exposes its contents as tools that agents can query before generating code. The agent asks questions; ds-mcp answers with your team's actual tokens, components, props, patterns, and anti-patterns.

See it in action

ds-mcp serves a dspack contract to an agent; the same contract is then compiled (dspack-emit) and rendered (A2UI). The query step starts here.

https://github.com/user-attachments/assets/510a781b-4214-49b3-b997-9cbecdc36961

What this is

• A read-only MCP server. It retrieves design system information. It does not generate code, write files, or make network calls.

• The reference implementation of the dspack specification (supports v0.1–v0.4).

What this is not

• A code generator. Code generation is the agent's job.

• A Figma sync tool. dspack files are authored and versioned by your team.

• A runtime dependency. ds-mcp runs alongside your MCP client during development, not in production.

How it works

1. Create a dspack file describing your design system's tokens, components, patterns, and anti-patterns. (Use the included shadcn/ui v0.4 example to try it now — it carries the governance blocks the generation tools need. The v0.2 and v0.1 examples remain for the minimal format. (The v0.1 example was previously named shadcn-ui.dspack.json; it was renamed so that no unversioned filename can be confused with the v0.4 contract of the same name in the dspack repository.) Have a React + Tailwind/shadcn codebase? You can generate a starting file from it — see Don't have a dspack file yet? below.)

2. Start ds-mcp with the dspack file. It loads the file once and holds it in memory.

3. Connect your MCP client (Claude Desktop, Claude Code, Cursor, GitHub Copilot). The agent can now query your design system at coding time.

Quick start

# 1. Install
npm install -g @aestheticfunction/ds-mcp

# 2. Download the shadcn/ui v0.4 example dspack
curl -L https://raw.githubusercontent.com/aestheticfunction/ds-mcp/main/examples/shadcn-ui-v04.dspack.json \
  -o shadcn-ui.dspack.json

# 3. Run with the downloaded file
ds-mcp --dspack ./shadcn-ui.dspack.json

Configure your MCP client to connect to ds-mcp. See docs/README.md for client-specific configuration examples.

Don't have a dspack file yet?

If your design system is a React + Tailwind/shadcn or Vue 3 + Vuetify 3 codebase, the experimental dspack-export tool can generate a starting dspack file from it — components, props (with cva variant enums and defaults, and Vue defineProps/emits/slots), color/radius tokens from your CSS custom properties or an imported DTCG design-token file, dark-theme overrides, and breakpoints:

git clone https://github.com/aestheticfunction/dspack-export
cd dspack-export && npm install && npm run build && npm link

cd /path/to/your/design-system
dspack-export init        # detects conventions, writes a config
dspack-export generate --config dspack-export.config.json
ds-mcp --dspack ./your-system.dspack.json

The generated file is a snapshot of extractable facts. The sections that make a dspack file most useful to agents — patterns, antiPatterns, whenToUse, accessibility, constraints — are deliberately left for your team to author. The complete journey from snapshot to a governed, validated contract (including what to author and in what order) is walked in the adoption guide.

What agents can ask

Tools

ds-mcp exposes eleven read-only tools:

The governed generation loop (dspack 0.3/0.4)

With a dspack 0.3/0.4 contract loaded, any MCP-connected agent becomes a governed UI generator without ds-mcp embedding a model:

1. get-generation-context { intent } → system prompt + generation schema + few-shot examples, compiled from the contract.

2. The agent generates a dspack surface itself (it is the LLM).

3. validate-ui { surface } → gates S1 (surface schema), S2 (contract vocabulary), S3 (governance rules with rationales), independently reported.

4. The agent repairs against the findings and validates again.

A generate_ui tool is deliberately absent: generation requires a model call, which would break the no-network invariant — and the MCP host already is a model. Both tools are pure computation over the loaded contract, backed by @aestheticfunction/dspack-gen/core (that package's zero-network, emitter-free subpath); a boundary test scans the whole tool path for network capability. Prompt steering is not enforcement: validate-ui's gate S3 is the guarantee.

dspack-gen is a build-time dependency: its core subpath is bundled into the published package (dist/vendor/dspack-gen-core.js) from a commit-pinned devDependency, so installing ds-mcp from npm pulls nothing from git. The default posture is tag-pinned: the pin is the commit of dspack-gen's latest release tag, so the vendored core corresponds exactly to a published dspack-gen version. CI watches this two ways: scripts/check-core-pin.mjs fails loudly when a newer dspack-gen release changes shipped src/core files (test files are excluded — the documented escape for intentional ahead-of-release pins), and the golden-context test byte-compares get-generation-context output against dspack-gen's own compiler golden. Updating governance semantics means re-pinning to the new release tag commit, npm install, npm run build, verifying the golden tests, and republishing ds-mcp.

Requirements

• Node.js 20.0.0 or later

• A dspack v0.1–v0.4 file (see the dspack spec); the generation tools require v0.3 or v0.4 (governance blocks; versions are hard-allowlisted)

Configuration

ds-mcp accepts the dspack file path via:

1. --dspack <path> CLI flag (first priority)

2. DSPACK_PATH environment variable (fallback)

Set DSMCP_DEBUG=true for verbose stderr logging.

Documentation

• Installation and MCP client setup

• Architecture

• Demo walkthrough: shadcn/ui settings form

Development

npm install
npm run build
npm test
bash scripts/smoke.sh

Security

ds-mcp is architecturally read-only. It does not write files, execute commands, or make network calls. Any behavior that violates these constraints is a defect. The generation tools preserve the invariants: they compile and lint in-process via @aestheticfunction/dspack-gen/core (a zero-network subpath), verified by a network-boundary test over the compiled tool path. See SECURITY.md for reporting instructions.

License

Copyright 2026 Aesthetic Function, LLC.

Licensed under the Apache License, Version 2.0. See LICENSE for the full text.