@aprila/design-system-mcp

An MCP server that teaches AI agents the Aprila design system. It reads the component manifests and the compiled stylesheet from the deployed Storybook, so it needs no local checkout of this repo — anyone can run it with npx and point their agent at the live design system.

What it serves

| Tool | What you get | | ----------------- | ----------------------------------------------------------------------------- | | list_components | Every component, grouped by section | | get_component | Props (types, defaults, allowed values), story snippets, import statement | | list_docs | The design-token guideline docs (colors, spacing, typography, radius, …) | | get_doc | One guideline doc in full | | get_stylesheet | The complete compiled @aprila/ui-core CSS, ready to inline into a prototype |

Two consumption modes, both explained to the agent by the tools themselves:

• In a codebase with @aprila/ui-react installed: use the imports and React examples.
• Standalone prototypes (plain HTML, claude.ai artifacts, Blazor, …): inline the stylesheet and write markup with each component's root class and data-* attributes — no build, no install.

Setup

The server reads the deployed Storybook origin from APRILA_STORYBOOK_URL.

Claude Desktop — Settings → Developer → Edit Config, add:

{
  "mcpServers": {
    "aprila-design-system": {
      "command": "npx",
      "args": ["-y", "@aprila/design-system-mcp"],
      "env": { "APRILA_STORYBOOK_URL": "https://<storybook-host>" }
    }
  }
}

Claude Code:

claude mcp add aprila-design-system -e APRILA_STORYBOOK_URL=https://<storybook-host> -- npx -y @aprila/design-system-mcp

Any other MCP client with stdio support works the same way.

Development

npm -w @aprila/design-system-mcp run build   # tsc → dist/
npx http-server apps/storybook/storybook-static -p 8787   # serve a local build
APRILA_STORYBOOK_URL=http://127.0.0.1:8787 node packages/design-system-mcp/dist/index.js

The manifests come from @storybook/addon-mcp during npm run build-storybook; the flat stylesheet from apps/storybook/scripts/bundle-css.mjs in the same build.

Publishing

Not yet published. npm publish from this directory once the org scope is set up (prepack builds automatically). Devs working in this repo don't need it — the Storybook dev server exposes the richer official MCP at http://localhost:6006/mcp (docs + dev + test toolsets).