DS MCP — Servidor de Design System para Agentes de IA
aestheticfunction/ds-mcp
Dê aos agentes de IA a verdade sobre seu design system
Ver no GitHubUm servidor MCP que lê arquivos dspack e expõe tokens, componentes e padrões de design system como ferramentas consultáveis para agentes de IA. Elimina adivinhações sobre nomenclatura de componentes e props ao fornecer um contrato consultável com a especificação real do design system da equipe.
Instalação
npx convez-ai aestheticfunction/ds-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Evitar que agentes de IA gerem componentes incorretos fora do design system
- Consultar tokens, cores, variantes e padrões durante codificação com IA
- Manter consistência visual em projetos React/Tailwind gerenciados por agentes
Veredito

Solução pragmática que resolve um problema real: agentes de IA inventando componentes e props fora da especificação do design system. Bem arquitetado, agnóstico a ferramentas e focado em consulta (não geração), tornando-o um complemento seguro para pipelines de código assistido.
README
A tradução para o português deste README ainda está na fila.
ds-mcp
Stop asking AI agents to guess your design system. Give them a contract they can query.
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 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.
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 and v0.2).
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
- Create a dspack file describing your design system's tokens, components, patterns, and anti-patterns. (Use the included shadcn/ui v0.2 example to try it now, or the v0.1 example for the minimal format. Have a React + Tailwind/shadcn codebase? You can generate a starting file from it — see Don't have a dspack file yet? below.)
- Start ds-mcp with the dspack file. It loads the file once and holds it in memory.
- 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.2 example dspack
curl -L https://raw.githubusercontent.com/aestheticfunction/ds-mcp/main/examples/shadcn-ui-v02.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 codebase, the experimental dspack-export tool can generate a starting dspack file from it — components, props (with cva variant enums and defaults), color/radius tokens from your CSS custom properties, 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.
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 nine read-only tools:
| 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 |
Requirements
- Node.js 20.0.0 or later
- A dspack v0.1 or v0.2 file (see the dspack spec)
Configuration
ds-mcp accepts the dspack file path via:
--dspack <path>CLI flag (first priority)DSPACK_PATHenvironment variable (fallback)
Set DSMCP_DEBUG=true for verbose stderr logging.
Documentation
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. 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.