@omnifyjp/mcp-design-system 0.2.0

package/README.md

@@ -0,0 +1,133 @@
+# @omnifyjp/mcp-design-system
+
+MCP (Model Context Protocol) server that exposes the @omnifyjp design system to AI tools — Claude Code, Cursor, Windsurf, etc.
+
+When consumers install `@omnifyjp/ui` via npm, they get components but **not** the design rules. This package bridges that gap: configure once, and AI tools automatically know how to use the design system correctly.
+
+## How It Works
+
+This is a **stdio MCP server** — no HTTP server, no ports, no daemon to run. AI tools launch it automatically as a subprocess, communicate via stdin/stdout, and terminate it when done.
+
+```
+AI Tool (Claude Code / Cursor)
+  ↓ spawns process
+  node @omnifyjp/mcp-design-system
+  ↓ JSON-RPC over stdin/stdout
+  AI gets design tokens, rules, component APIs
+  ↓ process exits when session ends
+```
+
+## Setup
+
+### For this monorepo (development)
+
+Already configured in `.mcp.json` at the repo root. Just build:
+
+```bash
+pnpm --filter @omnifyjp/mcp-design-system build
+```
+
+Claude Code will automatically pick up the MCP server on next session.
+
+### For consumers
+
+`.mcp.json` is auto-configured on install. Just install `@omnifyjp/shell` (which depends on this package):
+
+```bash
+npm install @omnifyjp/shell
+```
+
+The `postinstall` script automatically creates `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "omnify-design": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@omnifyjp/mcp-design-system"]
+    }
+  }
+}
+```
+
+If `.mcp.json` already exists, it merges the `omnify-design` entry without overwriting your other MCP servers.
+
+That's it. No server to run, no environment variables, no manual configuration.
+
+## What AI Tools Get
+
+### Resources
+
+| URI | Content |
+|-----|---------|
+| `design://tokens` | All design tokens — colors, density, layout, shadows, z-index, transitions, shared types (UIColor, UIVariant, UISize) |
+| `design://rules` | WRONG→RIGHT cheat sheet, DOs/DON'Ts, sidebar sizing rules, interaction patterns, code quality standards |
+| `design://components` | Component inventory — 53 primitives + 14 domain components with props and usage |
+| `design://layout` | Layout patterns — page, card, dialog, table, sidebar, header, drawer |
+
+### Tools
+
+| Tool | Description |
+|------|-------------|
+| `validate_component` | Validate React code against design rules. Catches hardcoded colors (`bg-white`, `text-gray-500`), wrong spacing (`p-6` instead of `p-page`), layout anti-patterns (`h-screen`), and more. |
+| `suggest_token` | Describe what you need ("page background", "subdued text") → get the correct design token |
+| `get_component_api` | Get props, variants, sizes, and usage example for any component |
+
+## Examples
+
+### AI validates code automatically
+
+When writing a component, the AI can call `validate_component` to check:
+
+```tsx
+// This code has violations:
+<div className="bg-white p-6 border-gray-200">
+  <h1 className="text-3xl font-bold">Title</h1>
+</div>
+
+// validate_component output:
+// - Line 1: Hardcoded `bg-white` → Use `bg-background` or `bg-card`
+// - Line 1: Hardcoded `p-6` → Use `p-page`
+// - Line 1: Hardcoded `border-gray-200` → Use `border-border`
+// - Line 2: `text-3xl font-bold` → Use `text-page-title font-semibold`
+```
+
+### AI suggests tokens
+
+```
+suggest_token("subdued text color")
+→ text-muted-foreground (CSS: --muted-foreground) — Subdued text (replaces text-gray-500/600)
+```
+
+### AI looks up component API
+
+```
+get_component_api("Button")
+→ variant: default | secondary | outline | soft | ghost | link
+→ color: primary | destructive | success | warning | info
+→ size: xs | sm | default | lg | xl
+→ Example: <Button variant="soft" color="success" size="sm">Approve</Button>
+```
+
+## Development
+
+```bash
+# Build
+pnpm --filter @omnifyjp/mcp-design-system build
+
+# Watch mode
+pnpm --filter @omnifyjp/mcp-design-system dev
+```
+
+### Keeping Content in Sync
+
+When design tokens, rules, or components change in `@omnifyjp/ui`, update the corresponding MCP resource:
+
+| Change | Update |
+|--------|--------|
+| `theme.css` tokens | `src/resources/tokens.ts` |
+| Design rules / CLAUDE.md | `src/resources/rules.ts` |
+| New/removed components | `src/resources/components.ts` |
+| Layout patterns | `src/resources/layout.ts` |
+| Cheat sheet WRONG→RIGHT | `src/resources/rules.ts` |