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

MCP Servers