design-os-migration-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@design-os-migration-mcp Migrate the Button component from the export to my React project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: @manansiingh/figma-react-mcp-server
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 buildRegister with Claude Code
Run from inside the project directory — $PWD resolves automatically.
Production (built server)
npm run mcp:addEquivalent to:
claude mcp add design-os-migration -- node $PWD/dist/index.jsDevelopment (no build step)
npm run mcp:add:devEquivalent to:
claude mcp add design-os-migration-dev -- npx tsx $PWD/src/index.tsRestart Claude Code after source changes to reload the server.
Remove
npm run mcp:remove # production
npm run mcp:remove:dev # devScopes
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.jsManual 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 |
| Compile TypeScript to |
| Run directly with |
| Run the compiled server |
| Register production server with Claude Code |
| Register dev server with Claude Code |
| Remove production registration |
| Remove dev registration |
| Open MCP Inspector UI against the built server |
| Open MCP Inspector UI against the |
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:devOnce 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 all sections with component counts and available files |
|
| Summarize the full export structure (sections, design system, shell, data model, instructions) |
|
| Read a component's source and parsed metadata (imports, Tailwind classes, icons, props, callbacks) |
|
| Read any file from the export by relative path |
|
| Detect framework, CSS approach, component library, icon library, TypeScript usage, and file conventions |
|
| List all doc files, or read a specific one |
|
| Build a full source→target mapping (colors, icons, CSS, components, imports, file structure, naming) |
Prompts
Prompt | Parameters | Description |
|
| Ready-to-execute migration instructions for a single component |
|
| Migration instructions for an entire section (types → components → barrel → tests) |
|
| Token and theme translation from Design OS to the target styling system |
|
| Complete multi-phase migration plan covering design system, data model, shell, and all sections |
Resources
URI | Description |
| Product overview markdown |
| Design tokens, color reference, and typography |
| Data model README and TypeScript types |
| Section overview, types, and component list |
| One-shot implementation guide |
| Incremental milestone instructions |
| 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.tsxAvailable Tools
7 toolsanalyze_target_projectA
Analyze a target project to detect its framework, CSS approach, component library, icon library, TypeScript usage, and file conventions
Inputs: targetPath (required).
get_migration_contextB
Build a migration mapping between the Design OS export package and the target project, showing what needs to change for colors, icons, CSS, components, imports, file structure, and naming
Inputs: exportPath (required), targetPath (required), section.
list_sectionsB
List all sections available in a Design OS export package with their component counts and available files
Inputs: exportPath (required).
read_componentA
Read a specific React component from the export package and return its source code with parsed metadata (imports, Tailwind classes, icon imports, props interface, callbacks)
Inputs: section (required), component (required), exportPath (required).
read_export_fileB
Read any file from the Design OS export package by relative path
Inputs: path (required), exportPath (required).
read_export_packageA
Read and summarize the entire Design OS export package structure (sections, design system, shell, data model, instructions)
Inputs: exportPath (required).
read_target_docsA
Read documentation files from the target project. Without a path, lists all available doc files. With a path, returns that file's content.
Inputs: targetPath (required), path.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: analyzing target project, building migration context, listing export sections, reading components/files from export, reading entire package, and reading target docs. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern with underscores (e.g., analyze_target_project, read_component, get_migration_context). The naming is predictable and clear.
7 tools is well-scoped for a migration analysis server. It covers the necessary operations without being excessive or insufficient.
The tool set covers analysis of both source and target, reading various granularities of the export package, and generating migration context. A minor gap is the lack of a tool to apply changes or generate migration scripts, but the set is complete for analysis purposes.
Maintenance
Related MCP Connectors
Accessible React components, tokens, usage guidance, and install commands for product interfaces.
Design systems your AI agent builds with and you reshape, plus standalone React components.
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
Build and manage your design system with AI: tokens, themes, components, icons, Figma and code.
Related MCP Servers
- AlicenseAqualityDmaintenanceBridge Figma designs to any platform with structured specs for Unity, React, Flutter, SwiftUI, and more, including layout audit, design tokens, and accessibility checks.199 npm8MIT
- AlicenseAqualityDmaintenanceConverts Figma designs into production-ready React components with design token extraction, widget registry integration, and micro-frontend module generation.351 npm1MIT
- AlicenseNot gradedqualityBmaintenanceBridges AI assistants with Figma for design system extraction, bidirectional token sync, visual debugging, and design creation.154 npm1MIT
- AlicenseAqualityDmaintenanceMaps design components, tokens, and patterns to their code implementations, providing AI coding agents with exact-match resolution across any design tool and framework. Enables agents to reliably discover and reuse existing components across React, Vue, Flutter, SwiftUI, and more.20MIT