# ds-mcp

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

> Part of the [dspack ecosystem](https://github.com/aestheticfunction) — 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](https://github.com/aestheticfunction/dspack) spec; vendors its generation core from [dspack-gen](https://github.com/aestheticfunction/dspack-gen); bootstrap a contract with [dspack-export](https://github.com/aestheticfunction/dspack-export); see the full chain running in [dspack-studio](https://github.com/aestheticfunction/dspack-studio) ([hosted replay](https://studio.aesthetic-function.com))

---

## 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.

## The solution

ds-mcp is a read-only [MCP](https://modelcontextprotocol.io/) server that
loads a [dspack](https://github.com/aestheticfunction/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](https://github.com/aestheticfunction/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](https://github.com/aestheticfunction/dspack) (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](examples/shadcn-ui-v04.dspack.json) to try
   it now — it carries the governance blocks the generation tools need.
   The [v0.2](examples/shadcn-ui-v02.dspack.json) and
   [v0.1](examples/shadcn-ui-v01.dspack.json) 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?](#dont-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

```bash
# 1. Install (or skip: `npx @aestheticfunction/ds-mcp` works without installing)
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-v04.dspack.json

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

The filename keeps its spec version deliberately: a bare `shadcn-ui.dspack.json`
means different content in different repositories.

Configure your MCP client to connect to ds-mcp. See
[docs/README.md](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](https://github.com/aestheticfunction/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:

```bash
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](https://github.com/aestheticfunction/dspack/blob/main/ADOPTING.md).

## What agents can ask

| Agent question | Tool call | Returns |
|---|---|---|
| What components are available? | `list-components` | Components with names, descriptions, deprecation and lifecycle status |
| Which components are stable? | `list-components { status: "stable" }` | Only components with stable lifecycle status |
| How do I use the Button component? | `get-component { id: "button" }` | Props, usage guidance, tokens, accessibility, composition, constraints |
| What's the right layout for a settings form? | `get-pattern { id: "settings-form" }` | Components to use, guidance on control selection and layout |
| What color token should I use for text? | `get-token { category: "color", name: "foreground" }` | Token value, description, type, tier, status, aliasOf |
| Which tokens relate to spacing? | `search-tokens { query: "spacing" }` | All tokens matching "spacing" across names, categories, descriptions, tier |
| What should I avoid doing? | `list-antipatterns` | Anti-patterns with reasoning, severity, and preferred alternatives |
| What are the must-not rules? | `list-antipatterns { severity: "must-not" }` | Only anti-patterns with must-not severity |
| How do I import Button in React? | `get-framework-mapping { framework: "react", componentId: "button" }` | Import path, install command, sub-component exports, guidance |
| What overrides does the dark theme apply? | `get-theme { id: "dark" }` | Theme description and token override map |
| What breakpoints should I use? | `get-layout` | Breakpoints, grid config, container sizes, spacing scale |

## Tools

ds-mcp exposes eleven read-only tools. Every tool returns its answer as
pretty-printed JSON inside a single MCP text block —
`{ content: [{ type: "text", text: "<JSON>" }] }` — and reports failures the
same way (an error string in that text channel) rather than as an MCP
protocol error, so clients should parse the text and check for the error
shape.

| Tool | Input | Description |
|------|-------|-------------|
| `get-token` | `{ category, name }` | Retrieve a single design token by category and name |
| `search-tokens` | `{ query }` | Search tokens by name, category, description, type, tier, status, or aliasOf |
| `get-component` | `{ id }` | Retrieve a full component definition including accessibility, composition, and constraints |
| `list-components` | `{ status? }` | List all components; optionally filter by lifecycle status |
| `get-pattern` | `{ id }` | Retrieve a documented usage pattern by ID |
| `list-antipatterns` | `{ severity? }` | List all anti-patterns; optionally filter by severity |
| `get-framework-mapping` | `{ framework, componentId? }` | Retrieve framework-specific information including sub-component export mappings |
| `get-theme` | `{ id }` | Retrieve a theme definition with token overrides |
| `get-layout` | none | Retrieve layout primitives: breakpoints, grid, containers, spacing scale |
| `get-generation-context` | `{ intent }` | Compile a dspack 0.3/0.4 contract into generation context: system prompt, generation JSON schema, few-shot examples |
| `validate-ui` | `{ surface, intent? }` | Lint a dspack surface against the contract's governance (gates S1/S2/S3) and return the findings |

### 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 posture is **tag-pinned**: the pin is always the commit of a
dspack-gen *release tag*, so the vendored core corresponds exactly to a
published dspack-gen version.

**Currently vendored: dspack-gen `v0.5.0`** (`5203569`), dspack-gen's
latest release. Moving here from v0.1.2 widened what `validate-ui` rejects,
in exactly two places. Gate S2 now enforces sub-component **containment**
(spec v0.4 §5.1): a declared sub-component is valid only inside its
declaring compound's subtree, so a `dialog-title` with no `dialog` ancestor
is a vocabulary error rather than an accepted node. Gate S3 now evaluates
**`requiredCategories`** on `required-composition` rules (§4.3), letting a
contract require that a matching node have a descendant drawn from a named
category. Surfaces that passed under the older core can fail under this one
— that is the point of the move, and it is why re-pinning is a deliberate
release step rather than an automatic follow. `forbiddenCategories` was
already evaluated at v0.1.2 and is unchanged, as are the lookup tools.

`get-generation-context` also serves a richer system prompt: from
dspack-gen 0.5.0 each component's vocabulary line carries that component's
`composition.notes` from the contract (capped at two sentences). Nothing
about the S-gates changes with it — it is prompt material, and prompt
steering is not enforcement.

CI watches the vendoring three 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). `scripts/check-sync.mjs` byte-compares every copied
artifact against its upstream, including the four dspack JSON Schemas the
loader validates against — a stale schema copy is not cosmetic, it makes
ds-mcp refuse contracts the spec considers valid. And the golden-context
test byte-compares `get-generation-context` output against dspack-gen's own
compiler golden, read against the contract dspack-gen compiled that golden
from. Re-pinning means moving the devDependency to the new release tag
commit, `npm install`, `npm run build`, `node scripts/check-sync.mjs
--write`, 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](https://github.com/aestheticfunction/dspack));
  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](docs/README.md)
- [Architecture](docs/architecture.md)
- [Demo walkthrough: shadcn/ui settings form](docs/demo-shadcn.md)

## Development

```bash
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](SECURITY.md) for reporting instructions.

## License

Copyright 2026 Aesthetic Function, LLC.

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for the full text.