Design OS Migration MCP Server

An MCP server that bridges Design OS exported component packages into target projects with different CSS approaches, component libraries, icon libraries, and file conventions.

Prerequisites

• Node.js 18+
• npm
• Claude Code CLI

Setup

# 1. Clone or download this repo
git clone <repo-url>
cd design-os-migration-mcp

# 2. Install dependencies
npm install

# 3. Build
npm run build

Register with Claude Code

Run from inside the project directory — $PWD resolves automatically.

Production (built server)

npm run mcp:add

Equivalent to:

claude mcp add design-os-migration -- node $PWD/dist/index.js

Development (no build step)

npm run mcp:add:dev

Equivalent to:

claude mcp add design-os-migration-dev -- npx tsx $PWD/src/index.ts

Restart Claude Code after source changes to reload the server.

Remove

npm run mcp:remove      # production
npm run mcp:remove:dev  # dev

Scopes

By default, the server is registered locally (current project only). Pass --scope to share it:

# Share with your team via .mcp.json
claude mcp add --scope project design-os-migration -- node $PWD/dist/index.js

# Available across all your projects
claude mcp add --scope user design-os-migration -- node $PWD/dist/index.js

Manual config (alternative)

Edit ~/.claude/mcp.json directly if you prefer not to use the CLI:

{
  "mcpServers": {
    "design-os-migration": {
      "command": "node",
      "args": ["/absolute/path/to/design-os-migration-mcp/dist/index.js"]
    }
  }
}

Restart Claude Code after editing manually.

Development scripts

Script	Description
npm run build	Compile TypeScript to dist/
npm run dev	Run directly with tsx (no build)
npm start	Run the compiled server
npm run mcp:add	Register production server with Claude Code
npm run mcp:add:dev	Register dev server with Claude Code
npm run mcp:remove	Remove production registration
npm run mcp:remove:dev	Remove dev registration
npm run mcp:inspect	Open MCP Inspector UI against the built server
npm run mcp:inspect:dev	Open MCP Inspector UI against the tsx dev server

Testing with the MCP Inspector

The MCP Inspector gives you an interactive UI at http://localhost:6274 to call tools, fill in parameters, and inspect responses — no Claude Code needed.

# Test the built server
npm run mcp:inspect

# Test without building (uses tsx)
npm run mcp:inspect:dev

Once open, you can:

• Browse all registered tools, prompts, and resources
• Call any tool with a generated form and see the JSON response
• Iterate quickly without restarting Claude Code

Tools

Tool	Parameters	Description
list_sections	exportPath	List all sections with component counts and available files
read_export_package	exportPath	Summarize the full export structure (sections, design system, shell, data model, instructions)
read_component	exportPath, section, component	Read a component's source and parsed metadata (imports, Tailwind classes, icons, props, callbacks)
read_export_file	exportPath, path	Read any file from the export by relative path
analyze_target_project	targetPath	Detect framework, CSS approach, component library, icon library, TypeScript usage, and file conventions
read_target_docs	targetPath, path?	List all doc files, or read a specific one
get_migration_context	exportPath, targetPath, section?	Build a full source→target mapping (colors, icons, CSS, components, imports, file structure, naming)

Prompts

Prompt	Parameters	Description
migrate-component	exportPath, targetPath, section, component	Ready-to-execute migration instructions for a single component
migrate-section	exportPath, targetPath, section	Migration instructions for an entire section (types → components → barrel → tests)
migrate-design-system	exportPath, targetPath	Token and theme translation from Design OS to the target styling system
full-migration	exportPath, targetPath	Complete multi-phase migration plan covering design system, data model, shell, and all sections

Resources

URI	Description
designos://export/overview?exportPath=…	Product overview markdown
designos://export/design-system?exportPath=…	Design tokens, color reference, and typography
designos://export/data-model?exportPath=…	Data model README and TypeScript types
designos://export/section/{sectionId}?exportPath=…	Section overview, types, and component list
designos://export/instructions/one-shot?exportPath=…	One-shot implementation guide
designos://export/instructions/{milestone}?exportPath=…	Incremental milestone instructions
designos://export/component-patterns	Design OS component pattern reference (import patterns, Tailwind conventions, callbacks)

Usage example

# 1. See what's in the export
list_sections exportPath=~/ravn/my-product/product-plan

# 2. Understand the target project
analyze_target_project targetPath=~/ravn/my-target-app

# 3. Get the full migration mapping
get_migration_context exportPath=~/ravn/my-product/product-plan targetPath=~/ravn/my-target-app

# 4. Generate migration instructions for a section
migrate-section exportPath=~/ravn/my-product/product-plan targetPath=~/ravn/my-target-app section=sessions

# 5. Or target a single component
migrate-component exportPath=~/ravn/my-product/product-plan targetPath=~/ravn/my-target-app section=sessions component=SessionList.tsx