design-system repo
  -> .design-system-mcp/ local runtime and index
  -> .cursor/.codex MCP client entries
  -> Cursor / Codex / other MCP clients

npx github:lodado/design-system-mcp install

npx design-system-mcp install

.design-system-mcp/
  bin/server.js       # bundled stdio MCP server
  bin/generate.js     # bundled index generator
  cache/index.json    # generated component/icon/token index
  config.json         # scanner/input paths
  manifest.json       # install metadata

.cursor/mcp.json      # Cursor project MCP entry
.codex/config.toml    # Codex project MCP entry
.gitignore            # gets `.design-system-mcp/` if missing

npx github:lodado/design-system-mcp doctor

npx github:lodado/design-system-mcp doctor --json

node .design-system-mcp/bin/server.js

node .design-system-mcp/bin/generate.js

## Design-system MCP

Run this once after cloning to create local MCP runtime files:

```bash
npx github:lodado/design-system-mcp install
```

Before implementing UI, use the connected design-system MCP.

Workflow:
1. Call inspect_system to verify the MCP server and generated index are available.
2. Call discover_components with a narrow query and limit to find existing design-system components before creating custom UI.
3. Pick one componentId from discover_components, then call explain_component with that id and detailLevel="summary".
4. Request explain_component detailLevel="props" or "full" only for the selected component when summary is not enough.
5. Before choosing colors, typography, spacing, radius, shadow, or theme values, call discover_tokens with kind/query/limit.
6. Before using icons, call discover_icons with query/category/limit.
7. Prefer existing design-system components, props, and tokens over custom components or custom styles.
8. If a needed component, prop, token, or icon is missing, state that explicitly instead of inventing an API.

Token-budget rules:
- Do not call discover_components with many broad keyword variants. Start with 1-3 intent queries.
- Do not call explain_component for every candidate. Explain only the selected componentId.
- Keep explain_component at detailLevel="summary" unless implementation requires prop details.
- Treat totalMatches > returned as a signal to refine the query instead of dumping more results.

When reporting your implementation plan, include:
- MCP tools called
- selected componentIds and why
- selected tokens/icons and why
- any missing design-system APIs

UI 구현 전에는 연결된 design-system MCP를 반드시 사용한다.

작업 순서:
1. inspect_system으로 MCP 서버와 generated index 상태를 확인한다.
2. 커스텀 UI를 만들기 전에 좁은 query와 limit으로 discover_components를 호출해 기존 디자인시스템 컴포넌트를 찾는다.
3. discover_components가 반환한 componentId 하나를 선택한 뒤 explain_component에 id와 detailLevel="summary"를 넘긴다.
4. summary만으로 부족할 때만 선택한 컴포넌트에 대해 detailLevel="props" 또는 "full"을 요청한다.
5. 색상, 타이포그래피, spacing, radius, shadow, theme 값을 고르기 전에는 kind/query/limit과 함께 discover_tokens를 호출한다.
6. 아이콘을 쓰기 전에는 query/category/limit과 함께 discover_icons를 호출한다.
7. 커스텀 컴포넌트/커스텀 스타일보다 기존 디자인시스템 컴포넌트, props, token을 우선한다.
8. 필요한 컴포넌트, prop, token, icon이 없으면 추측하지 말고 누락 사실을 명시한다.

토큰 예산 규칙:
- discover_components를 많은 broad keyword 조합으로 반복 호출하지 말고, 먼저 1~3개의 intent query로 좁힌다.
- 모든 후보에 explain_component를 호출하지 말고, 선택한 componentId 하나에만 호출한다.
- 구현에 prop 상세가 필요하기 전까지 explain_component는 detailLevel="summary"로 유지한다.
- totalMatches가 returned보다 크면 더 많은 결과를 덤프하지 말고 query를 좁힌다.

구현 계획을 보고할 때는 다음을 포함한다:
- 호출한 MCP tool
- 선택한 componentId와 이유
- 선택한 token/icon과 이유
- 누락된 디자인시스템 API

inspect_system
  -> discover_components({ query, limit })
  -> explain_component({ id: componentId, detailLevel: "summary" })
  -> explain_component({ id: componentId, detailLevel: "props" }) only if needed
  -> discover_tokens({ kind, query, limit })
  -> discover_icons({ query, category, limit })

{
  "mcpServers": {
    "design-system": {
      "command": "node",
      "args": [".design-system-mcp/bin/server.js"],
      "cwd": "."
    }
  }
}

.design-system-mcp/cache/index.json

node .design-system-mcp/bin/generate.js

{
  "indexPath": ".design-system-mcp/cache/index.json",
  "components": ["src/**/*.{ts,tsx}"],
  "icons": ["src/**/*Icon.{ts,tsx}"],
  "tokens": ["src/**/*tokens*.{ts,tsx,json,css}"],
  "docs": ["docs/**/*.{md,mdx}"]
}

type DesignSystemIndex = {
  version: string;
  generatedAt: string;
  components: ComponentMetadata[];
  icons: IconMetadata[];
  tokens: TokenMetadata[];
};

ComponentMetadata
- name
- group
- description
- props[]
- inheritedProps
- subcomponents
- docsRef
- sourceRef
- packageName

PropMetadata
- name
- required
- typeSummary
- typeKind
- description
- defaultValue
- literals

IconMetadata
- name
- description
- keywords
- category

TokenMetadata
- name
- kind
- value
- description
- resolvedValueByTheme

npm install
npm run build
npm run test
npm run check