Migration Assistant MCP Server

A powerful Model Context Protocol (MCP) server that automates the migration of legacy JSP/Spring applications to modern React architecture. This tool analyzes legacy codebases, converts HTML APIs to JSON, generates React components, and tracks migration progress.

Features

• 🔍 Legacy Code Analysis: Automatically identify all files, routes, and APIs related to a specific feature
• 🔄 API Conversion: Transform HTML-returning endpoints to modern JSON APIs with auto-generated code
• ⚛️ React Generation: Create complete React components with hooks, TypeScript types, and tests
• 📋 Migration Planning: Generate comprehensive step-by-step migration plans with time estimates
• 📊 Progress Tracking: Monitor migration progress across all features
• 🎨 Project Customization (v1.0.1): Configure output paths, naming conventions, and tech stack
• 🔍 Structure Analysis (v1.0.1): Analyze existing React projects to detect conventions automatically
• 💾 Auto File Writing (v1.0.1): Optionally write generated files directly to disk

Installation

Prerequisites

• Node.js 18+
• npm or yarn
• A legacy JSP/Spring project to migrate
• A target React project

Setup

1. Clone or create the project:

git clone <repository-url>
cd migration-assistant-mcp

2. Install dependencies:

npm install

3. Configure environment variables:

cp .env.example .env

Edit .env with your project paths:

LEGACY_REPO=/absolute/path/to/legacy/project
MODERN_REPO=/absolute/path/to/react/project
BACKEND_FRAMEWORK=spring
LEGACY_URL_BASE=http://localhost:8080

4. Build the project:

npm run build

Configuration

Environment Variables

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | LEGACY_REPO | ✅ Yes | Absolute path to legacy project | /home/user/projects/legacy-app | | MODERN_REPO | ✅ Yes | Absolute path to React project | /home/user/projects/react-app | | BACKEND_FRAMEWORK | ✅ Yes | Backend framework (spring or express) | spring | | LEGACY_URL_BASE | ⚠️ Optional | URL of running legacy app (for HTML fetching) | http://localhost:8080 |

Claude Desktop Integration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "migration-assistant": {
      "command": "node",
      "args": ["/absolute/path/to/migration-assistant-mcp/dist/index.js"],
      "env": {
        "LEGACY_REPO": "/path/to/legacy/project",
        "MODERN_REPO": "/path/to/react/project",
        "BACKEND_FRAMEWORK": "spring",
        "LEGACY_URL_BASE": "http://localhost:8080"
      }
    }
  }
}

Restart Claude Desktop after configuration.

Project Configuration (v1.0.1)

Create a .migration-config.json file in your MODERN_REPO to customize code generation:

cp .migration-config.example.json path/to/react-project/.migration-config.json

Example configuration:

{
  "project": {
    "structure": "feature-based",
    "baseDir": "src"
  },
  "paths": {
    "components": "features/{feature}/components",
    "hooks": "features/{feature}/hooks",
    "types": "features/{feature}/types"
  },
  "techStack": {
    "stateManagement": "zustand",
    "styling": "tailwind"
  },
  "codeGen": {
    "writeFiles": false
  }
}

See .migration-config.example.json for all options.

Available Tools

1. analyze_legacy_feature

Analyzes your legacy codebase to identify all files, routes, and APIs related to a specific feature.

Parameters:

• featureName (required): Feature name to analyze (e.g., "cart", "product")
• searchKeywords (optional): Additional search keywords

Example:

{
  "featureName": "cart",
  "searchKeywords": ["shopping", "basket"]
}

Output:

{
  "feature": "cart",
  "files": [
    {
      "path": "src/main/webapp/cart/list.jsp",
      "type": "jsp",
      "size": 15234,
      "lastModified": "2024-01-15T10:30:00Z"
    }
  ],
  "routes": [
    {
      "url": "/cart/list.do",
      "method": "GET",
      "file": "CartController.java"
    }
  ],
  "apiCalls": [
    {
      "endpoint": "/cart/add.do",
      "method": "POST",
      "location": "cart.js:45",
      "responseType": "html"
    }
  ],
  "dependencies": {
    "libraries": ["org.springframework"],
    "services": ["CartService", "ProductService"]
  },
  "dataFlow": {
    "description": "...",
    "steps": ["..."]
  }
}

2. convert_api_to_json

Converts an HTML-returning API to a modern JSON API with auto-generated backend code.

Parameters:

• endpoint (required): Legacy endpoint to convert (e.g., "/cart/list.do")
• htmlSample (optional): HTML response sample
• framework (optional): 'spring' or 'express' (defaults to config)
• newEndpoint (optional): New endpoint path (auto-generated if not provided)

Example:

{
  "endpoint": "/cart/list.do",
  "framework": "spring"
}

Output:

• Analyzed data structure from HTML
• Recommended JSON API structure
• Generated Spring/Express code:
  • Controller
  • DTO/Types
  • Service
  • Tests

3. generate_react_component

Generates a complete React component with hooks, types, and tests.

Parameters:

• componentName (required): Component name in PascalCase (e.g., "CartPage")
• apiEndpoint (required): API endpoint to consume
• apiSpec (optional): API specification object
• styling (optional): 'tailwind', 'styled-components', or 'css-modules' (default: 'tailwind')

Example:

{
  "componentName": "CartPage",
  "apiEndpoint": "/api/v2/cart",
  "styling": "tailwind"
}

Output:

• Component file (CartPage.tsx)
• Custom hook file (useCart.ts)
• TypeScript types (CartPage.types.ts)
• Test file (CartPage.test.tsx)
• Usage example

4. create_migration_plan

Creates a comprehensive migration plan with steps, time estimates, risks, and checklists.

Parameters:

• featureName (required): Feature to create plan for
• priority (optional): 'high', 'medium', or 'low' (default: 'medium')

Example:

{
  "featureName": "cart",
  "priority": "high"
}

Output:

{
  "feature": "cart",
  "estimatedTime": "3-5 days",
  "complexity": "medium",
  "steps": [
    {
      "step": 1,
      "title": "Analyze Legacy Code",
      "description": "...",
      "tasks": ["..."],
      "estimatedTime": "2-4 hours",
      "dependencies": []
    }
  ],
  "risks": [
    {
      "description": "...",
      "mitigation": "..."
    }
  ],
  "checklist": [
    {
      "category": "Backend Migration",
      "items": [
        { "task": "Convert HTML APIs to JSON", "completed": false }
      ]
    }
  ]
}

5. track_progress

Tracks overall migration progress across all features.

Parameters:

• detailed (optional): Include detailed information (default: false)

Example:

{
  "detailed": true
}

Output:

{
  "summary": {
    "totalFeatures": 5,
    "completed": 2,
    "inProgress": 2,
    "notStarted": 1,
    "percentComplete": 40
  },
  "features": [
    {
      "name": "cart",
      "status": "in-progress",
      "lastUpdated": "2024-01-15T10:30:00Z",
      "completedSteps": 3,
      "totalSteps": 6
    }
  ],
  "recentActivity": [...],
  "blockers": [...]
}

6. analyze_project_structure (v1.0.1)

Analyzes existing React project structure to detect conventions and patterns.

Parameters:

• referencePath (optional): Path to analyze (defaults to MODERN_REPO)

Example:

{
  "referencePath": "src/features/mypage"
}

Output:

{
  "detectedStructure": "feature-based",
  "folderPatterns": {
    "components": ["features/cart/components", "features/product/components"],
    "hooks": ["features/cart/hooks"]
  },
  "conventions": {
    "namingPattern": "kebab-case",
    "importStyle": "alias",
    "stateManagement": ["zustand", "react-query"],
    "styling": ["tailwind"]
  },
  "examples": {
    "componentPath": "features/mypage/components/MyPage.tsx",
    "hookPath": "features/mypage/hooks/useMyPage.ts"
  },
  "recommendations": [
    "Use feature-based folder structure: features/{feature}/components",
    "Use alias imports with @ prefix"
  ]
}

Usage Examples

Typical Migration Workflow

1. Analyze a feature:

User: Analyze the shopping cart feature
Assistant: *calls analyze_legacy_feature*

2. Convert APIs to JSON:

User: Convert /cart/list.do to a JSON API
Assistant: *calls convert_api_to_json*

3. Generate React component:

User: Generate a CartPage component for /api/v2/cart
Assistant: *calls generate_react_component*

4. Create migration plan:

User: Create a migration plan for the cart feature
Assistant: *calls create_migration_plan*

5. Track progress:

User: Show me the overall migration progress
Assistant: *calls track_progress*

v1.0.1 Features: Project Customization

1. Analyze existing project structure:

User: Analyze my React project structure at src/features/mypage
Assistant: *calls analyze_project_structure*
Result: Detects feature-based structure, Zustand, Tailwind, alias imports

2. Generate with custom paths:

User: Generate CartPage component for cart feature
      Use feature-based structure
Assistant: *uses .migration-config.json if available*
          *generates files at features/cart/components/CartPage.tsx*

3. Auto-write files (optional):

// In .migration-config.json
{
  "codeGen": {
    "writeFiles": true
  }
}

Files are automatically written to disk instead of just returning code.

Development

Project Structure

migration-assistant-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── config.ts             # Configuration loader
│   ├── types.ts              # TypeScript type definitions
│   ├── tools/                # MCP tool implementations
│   │   ├── legacy-analyzer.ts
│   │   ├── api-converter.ts
│   │   ├── react-generator.ts
│   │   ├── migration-planner.ts
│   │   └── progress-tracker.ts
│   ├── parsers/              # Code parsers
│   │   ├── html-parser.ts
│   │   ├── java-parser.ts
│   │   └── route-extractor.ts
│   ├── generators/           # Code generators
│   │   ├── spring-code-gen.ts
│   │   ├── express-code-gen.ts
│   │   └── react-code-gen.ts
│   └── utils/                # Utilities
│       ├── file-search.ts
│       └── logger.ts
└── dist/                     # Compiled output

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run watch - Watch mode for development
• npm run dev - Build and run the server
• npm test - Run tests (not yet implemented)

Adding New Features

1. Create a new tool file in src/tools/
2. Implement the tool function
3. Add the tool definition in src/index.ts
4. Update types in src/types.ts if needed
5. Rebuild: npm run build

Troubleshooting

Server won't start

Error: LEGACY_REPO environment variable is required

Solution: Ensure all required environment variables are set in your Claude Desktop config or .env file.

Cannot fetch HTML from legacy endpoint

Error: Could not fetch HTML from http://localhost:8080/cart/list.do

Solutions:

• Ensure your legacy application is running
• Check that LEGACY_URL_BASE is correct
• Or provide htmlSample parameter directly

File search returns no results

Possible causes:

• Feature name doesn't match file names
• Files are in excluded directories (node_modules, .git, etc.)

Solution: Use searchKeywords parameter to add more search terms

Build errors

Error: Cannot find module ...

Solution:

rm -rf node_modules package-lock.json
npm install
npm run build

Limitations

• HTML parsing works best with semantic, well-structured HTML
• Java parsing is basic pattern matching (not full AST parsing)
• Auto-generated code requires manual review and completion of TODOs
• Progress tracking requires manual updates (not automatic)

Roadmap

• [ ] Support for more frameworks (NestJS, Django, Ruby on Rails)
• [ ] Advanced Java AST parsing with Babel
• [ ] Automatic test generation improvements
• [ ] Database schema migration support
• [ ] CI/CD integration
• [ ] Visual progress dashboard

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

MIT

Support

For issues and questions:

• GitHub Issues: [Create an issue]
• Documentation: This README

Built with ❤️ using the Model Context Protocol