Skip to main content
Glama
design-os-migration-mcp

design-os-migration-mcp

by dchavezp

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 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

Available Tools

7 tools
analyze_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

    A3.8/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    7 tools is well-scoped for a migration analysis server. It covers the necessary operations without being excessive or insufficient.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Bridge Figma designs to any platform with structured specs for Unity, React, Flutter, SwiftUI, and more, including layout audit, design tokens, and accessibility checks.
      19
      9 npm
      8
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Maps 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.
      20
      MIT