@smile-design/mcp-server

Model Context Protocol server that exposes smile-design's design intelligence — design-system presets, Tailwind v4 token round-trip, aesthetic checks, DOM Inspector, preview lifecycle, and headless screenshots — as MCP tools and resources for Claude Code and any other MCP-aware agent.

This is the developer track entry point for smile-design: install it once, register it as an MCP server in your existing Claude Code workflow, and ask the agent "switch this project to the corporate design system" or "tighten contrast on the hero section" — the agent will reach for smile_apply_design_system / smile_aesthetic_checks / smile_replace_properties and edit your codebase in place. No Web UI required.

Install

pnpm add -D @smile-design/mcp-server
# or run on demand without installing:
npx @smile-design/mcp-server

Register with Claude Code

Add an entry to mcpServers in either ~/.claude.json (user scope, available everywhere) or <your-project>/.claude/settings.json (project scope, checked into git):

{
  "mcpServers": {
    "smile-design": {
      "command": "npx",
      "args": ["-y", "@smile-design/mcp-server"],
      "env": {
        "SMILE_PROJECT_DIR": "/absolute/path/to/your/project",
      },
    },
  },
}

Restart Claude Code. The 13 smile_* tools and 3 smile-design://... resources should now appear in /mcp listing.

A guided npx smile-mcp install / uninstall CLI is planned for the next release and will write this configuration interactively (smile-design Sprint 4.1 task T-4.1.6).

Tools

The server registers 13 tools. All tool names are prefixed smile_ so they never collide with other MCP servers in the same Claude Code session.

| Tool | Purpose | | --------------------------- | ----------------------------------------------------------------------------------- | | smile_start_preview | Spawn a Vite dev-server in the user's project, return live URL | | smile_stop_preview | Stop the managed preview process | | smile_screenshot | Capture a base64 PNG of the running preview via headless Chromium | | smile_read_design_tokens | Parse globals.css @theme block and return current DesignTokenSet | | smile_apply_design_system | Switch the project to a built-in preset (corporate / default-minimalist) | | smile_compile_design_md | Compile DESIGN.md AST to Tailwind v4 @theme token map | | smile_aesthetic_checks | Run static + dynamic aesthetic checks (contrast / typography / spacing / alignment) | | smile_get_guidelines | Return the active aesthetic guide as Markdown for agent prompt injection | | smile_inspect_element | Toggle the DOM Inspector overlay inside the preview iframe | | smile_get_element_context | Resolve a clicked DOM node back to its source location and JSX context | | smile_search_properties | AST-search JSX prop values across .tsx / .jsx files | | smile_replace_properties | AST-rewrite JSX prop values with byte-accurate source-map preservation | | smile_refine_element | Apply a focused style/refactor to a single inspected element |

Resources

Read-only resources the agent can ReadResource before deciding which tool to call:

| URI | MIME | Returns | | ------------------------------- | ------------------ | --------------------------------------------------------------------------------------- | | smile-design://guide/active | text/markdown | Currently active aesthetic guide (the same prompt fragment injected into PromptBuilder) | | smile-design://tokens/current | application/json | Parsed globals.css @theme tokens grouped by colors / typography / spacing | | smile-design://preview/state | application/json | Current preview status (status / projectDir / url / template / recentErrors) |

Resources are fail-open: if the project has no DESIGN.md or the preview is not running, the resource returns an error payload rather than throwing — the agent can still reason about the situation.

Project resolution

Every tool that touches the user's filesystem resolves the target directory in this order:

1. The SMILE_PROJECT_DIR env var (set in your mcpServers entry — recommended)
2. The MCP request's optional projectDir argument
3. Fall back to an explicit error so the agent never silently edits the wrong project

This mirrors memory/conventions/mcp-project-dir-resolution.md from the smile-design monorepo.

Requirements

• Node.js ≥ 22 (LTS)
• A user project that runs on Vite (the preview manager spawns npx vite in SMILE_PROJECT_DIR). Next.js / Vue / Nuxt support arrives in Phase 5.
• For aesthetic-check sampling and screenshots: a Chromium download via npx playwright install chromium
• Claude Code 2.x or any MCP-aware agent that understands stdio transport

Related packages

• @smile-design/design-engine — design tokens, presets, aesthetic checks (used internally; expose as standalone library if you want to script DESIGN.md round-trip without going through MCP)
• @smile-design/preview-server — Vite dev-server lifecycle + headless screenshots (transitive dep)
• @smile-design/inspector — DOM Inspector AST engines + iframe runtime (transitive dep)
• @smile-design/inspector-plugin — drop-in Vite plugin to make any project BYOP-compatible without installing the full inspector

License

MIT