# 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

```bash
# 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)

```bash
npm run mcp:add
```

Equivalent to:

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

### Development (no build step)

```bash
npm run mcp:add:dev
```

Equivalent to:

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

Restart Claude Code after source changes to reload the server.

### Remove

```bash
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:

```bash
# 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:

```json
{
  "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](https://github.com/modelcontextprotocol/inspector) gives you an interactive UI at `http://localhost:6274` to call tools, fill in parameters, and inspect responses — no Claude Code needed.

```bash
# 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
```