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.
An MCP server that bridges Design OS exported component packages into target projects with different CSS approaches, component libraries, icon libraries, and file conventions.
Node.js 18+
npm
Claude Code CLI
Related MCP server: figma-spec-mcp
# 1. Clone or download this repo
git clone <repo-url>
cd design-os-migration-mcp
# 2. Install dependencies
npm install
# 3. Build
npm run buildRun from inside the project directory — $PWD resolves automatically.
npm run mcp:addEquivalent to:
claude mcp add design-os-migration -- node $PWD/dist/index.jsnpm 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.
npm run mcp:remove # production
npm run mcp:remove:dev # devBy 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.jsEdit ~/.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.
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 |
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
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) |
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 |
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) |
# 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.tsxAnalyze a target project to detect its framework, CSS approach, component library, icon library, TypeScript usage, and file conventions
| Name | Required | Description | Default |
|---|---|---|---|
| targetPath | Yes | Path to the target project root directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose whether the tool modifies files, requires specific permissions, or has side effects. As it performs analysis, it is likely read-only, but this is not stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded with the action and resource, and efficiently lists all detection capabilities. No redundant words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main function but lacks details on output structure, error conditions, and behavioral traits. Given no output schema and no annotations, more information (e.g., what the analysis returns) would be beneficial for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter targetPath. The description adds context by listing what will be detected, but doesn't provide additional syntactic or semantic details (e.g., path format, validation rules). Baseline 3 with marginal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Analyze') and resource ('target project'), and enumerates specific aspects detected (framework, CSS approach, component library, icon library, TypeScript usage, file conventions). It distinguishes from sibling tools like read_component or read_export_file which are about reading content rather than analysis.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing project configuration detection, but does not explicitly state when to use this tool versus alternatives like get_migration_context or list_sections. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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
| Name | Required | Description | Default |
|---|---|---|---|
| section | No | Optional section ID to focus the migration context on a specific section | |
| exportPath | Yes | Path to the product-plan export directory | |
| targetPath | Yes | Path to the target project root directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden of behavioral disclosure. It only describes what the tool does, not side effects (e.g., whether it modifies files), error handling, or permissions needed. Mutation vs read-only status is unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The single sentence is efficient and front-loaded with purpose. However, it lacks structure (e.g., bullet points or sections) that could improve scannability without increasing word count significantly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 3 parameters and no output schema, the description omits what the mapping output looks like, how to interpret results, and error scenarios. For a migration tool, output details are critical for agent decision-making.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema: it doesn't explain path formats, the optional section ID's significance, or how parameters interact.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool builds a migration mapping between Design OS export and target project, listing specific aspects (colors, icons, CSS, etc.). It distinguishes from sibling tools like 'analyze_target_project' which likely focus on analysis rather than mapping creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for migration planning but lacks explicit guidance on when to use versus alternatives, prerequisites, or exclusions. It does not state when not to use or provide context about the migration workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all sections available in a Design OS export package with their component counts and available files
| Name | Required | Description | Default |
|---|---|---|---|
| exportPath | Yes | Path to the product-plan export directory (e.g. ~/ravn/my-product/product-plan) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is minimal and does not disclose behavioral traits such as side effects, required permissions, rate limits, or error conditions. Since no annotations are provided, the description carries full responsibility for transparency, but it only states the function without any contextual safety or behavior details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that directly conveys the tool's purpose without unnecessary words. It is front-loaded with the verb and resource, making it efficient for an AI to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with one parameter and no output schema, the description is adequate but lacks specifics about the output format (e.g., list of section names, counts file paths) or example usage. It could be more informative about what the agent can expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides a complete description of the single parameter 'exportPath'. The description reiterates the concept of an 'export package' but adds no new meaning beyond the schema. Baseline 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists sections from a Design OS export package, including component counts and available files. It uses a specific verb ('list') and resource ('sections'), and the provided sibling tools (e.g., 'read_component', 'read_export_file') indicate that this tool is distinct for obtaining an overview.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus its siblings (e.g., 'read_export_package', 'get_migration_context'). It does not mention prerequisites, when to avoid it, or how it complements other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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)
| Name | Required | Description | Default |
|---|---|---|---|
| section | Yes | Section ID (e.g. 'sessions', 'personas') or 'shell' for shell components | |
| component | Yes | Component filename (e.g. 'SessionList.tsx') | |
| exportPath | Yes | Path to the product-plan export directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states 'Read' implying no mutation, and describes the output format, but does not disclose error conditions, permission requirements, or side effects. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence (20 words) that efficiently conveys the tool's purpose and output. Every word adds value, with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description explicitly lists the returned data: source code and parsed metadata (imports, Tailwind classes, icon imports, props interface, callbacks). This covers the key information an agent needs, making it complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with all parameters described clearly. The description does not add additional parameter semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the verb 'Read', the resource 'specific React component', and the output format 'source code with parsed metadata'. It clearly distinguishes from siblings like read_export_file by focusing on React components with parsing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the usage context clear (reading a specific component with metadata), but does not explicitly mention when not to use it or provide direct comparisons to sibling tools like read_export_file or read_export_package.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read any file from the Design OS export package by relative path
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path within the export package (e.g. 'design-system/tokens.css', 'sections/sessions/types.ts') | |
| exportPath | Yes | Path to the product-plan export directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for behavioral disclosure. It indicates a read-only operation but lacks details on permissions, rate limits, or side effects. Important traits like whether the file is read into memory or streamed are not mentioned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no extraneous words. It efficiently conveys the core purpose. However, a slightly longer description could improve completeness without sacrificing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 params, no nested objects, no output schema), the description is insufficient. It does not explain the return format, error scenarios, or the relationship to the export package structure. The agent may not know how to handle the response or errors.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and both parameters have descriptions. The description adds the phrase 'by relative path', which aligns with the path parameter but does not add significant new meaning beyond the schema. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read' and the resource 'any file from the Design OS export package', specifying the mechanism 'by relative path'. This distinguishes it from siblings like read_component (reads a single component) and read_export_package (reads the entire package).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention when not to use it, nor does it reference sibling tools like read_export_package for reading the entire package or list_sections for listing sections. The agent is left to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read and summarize the entire Design OS export package structure (sections, design system, shell, data model, instructions)
| Name | Required | Description | Default |
|---|---|---|---|
| exportPath | Yes | Path to the product-plan export directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states it is a read operation (non-destructive) and summarizes, but does not mention potential size limits, permissions, or whether it reads the entire directory. The description is adequate but lacks detail for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the action and resource, with every word contributing to clarity. No unnecessary verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and one parameter, the description covers the main purpose and lists what the summary contains. It lacks details on return format but is sufficient for an agent to understand the tool's function. Could be enhanced with usage examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter (exportPath). The description does not add additional meaning beyond the schema, which already describes it as 'Path to the product-plan export directory'. Baseline 3 is appropriate as no extra semantic value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read and summarize' and the resource 'entire Design OS export package structure', listing specific components (sections, design system, shell, data model, instructions). It distinguishes from siblings like 'read_component' or 'list_sections' by emphasizing the whole package.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The purpose implies it's for a comprehensive overview, but there is no mention of when not to use it or references to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read documentation files from the target project. Without a path, lists all available doc files. With a path, returns that file's content.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Relative path to a specific doc file. If omitted, lists all available documentation files. | |
| targetPath | Yes | Path to the target project root directory |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It correctly states it reads files (a read-only operation), but does not describe potential errors, return format, or side effects. Basic transparency is present but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every sentence adds necessary information. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and the presence of similar sibling tools, the description could provide more detail on return format (e.g., list vs array, file content as string) and error handling. It covers the basic functionality but leaves room for ambiguity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description adds value for the 'path' parameter by explaining its behavior when omitted, but does not mention 'targetPath' at all. Overall, the description adds some but not substantial extra meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it reads documentation files from the target project, with two distinct modes: listing all files when path is omitted, and returning file content when path is provided. This makes the purpose specific and distinguishable from sibling tools like read_component or read_export_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear conditions for using the tool: without a path it lists files, with a path it returns content. This gives implicit guidance on when to use it, though it does not explicitly exclude alternatives or mention when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0analyze_target_projectget_migration_contextlist_sectionsread_componentread_export_fileread_export_packageread_target_docsScored 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.
Accessible React components, tokens, usage guidance, and install commands for product interfaces.
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.
Provides style context & tokens to design or restyle web UIs in any framework
