fruteroclub/para-wallet-migration-mcp

graph TB
    A[📊 Analyze Project] --> B[🎯 Detect Strategy]
    B --> C[📋 Create Replacement Plan]
    C --> D[🔍 Pre-flight Validation]
    D --> E[⚡ Execute Atomic Migration]
    E --> F[✅ Post-migration Validation] 
    F --> G[🎉 Complete Success]
    
    E --> H[❌ Failure Detected]
    H --> I[🔄 Automatic Rollback]
    I --> J[📝 Issue Report]

git clone https://github.com/fruteroclub/Para-wallet-migration-mcp.git
cd Para-wallet-migration-mcp
npm install
npm run build

# Add to global MCP configuration
python3 -c "
import json
with open('/home/$(whoami)/.claude.json', 'r') as f:
    data = json.load(f)
data['mcpServers']['para-migration'] = {
    'command': 'node',
    'args': ['$(pwd)/dist/index.js']
}
with open('/home/$(whoami)/.claude.json', 'w') as f:
    json.dump(data, f, indent=2)
print('✅ Para Migration MCP added to Claude Code')
"

{
  "mcpServers": {
    "para-migration": {
      "command": "node",
      "args": ["/absolute/path/to/Para-wallet-migration-mcp/dist/index.js"]
    }
  }
}

# Check MCP status in Claude Code
/mcp list

# Should show:
# ❯ 5. para-migration    ✔ connected · Enter to view details

# Test MCP functionality
"Analyze my project for wallet provider migration"

{
  "mcp.servers": {
    "para-migration": {
      "command": "node",
      "args": ["/absolute/path/to/Para-wallet-migration-mcp/dist/index.js"]
    }
  }
}

{
  "mcpServers": {
    "para-migration": {
      "command": "node",
      "args": ["/absolute/path/to/Para-wallet-migration-mcp/dist/index.js"],
      "env": {}
    }
  }
}

# Check all MCP servers
/mcp list

# Expected output:
│ Manage MCP servers                                                           │
│                                                                              │
│ ❯ 1. context7                       ✔ connected · Enter to view details     │
│   2. playwright                     ✔ connected · Enter to view details     │
│   3. sequential-thinking            ✔ connected · Enter to view details     │
│   4. serena                         ✘ failed · Enter to view details        │
│   5. para-migration                 ✔ connected · Enter to view details     │

# Test 1: Basic functionality
"Generate a Para configuration with API key test_key_123"

# Test 2: Project analysis  
"Analyze the current directory for wallet provider usage"

# Test 3: Migration validation
"Check this project for Para migration compatibility"

# Natural language command in Claude Code/Cursor:
"Analyze my project for wallet provider usage and suggest migration strategy"

# MCP automatically uses: analyze_project tool
# Result: "Detected privy-to-para migration strategy"

# Complete migration in one command:
"Execute atomic migration from Privy to Para with rollback capability"

# MCP uses: execute_atomic_migration tool
# Result: 0% Privy code, 100% Para code in <5 minutes

# Verify migration success:
"Validate migration state and check completion percentage"

# MCP uses: validate_migration_state tool  
# Result: 95% migration success, all critical issues resolved

"I have a React app using Privy for authentication. Migrate it to Para step by step:
1. Analyze my Privy setup
2. Generate Para replacement config
3. Execute atomic migration  
4. Validate all critical components"

"Migrate my ReOwn AppKit implementation to Para:
- Remove all @reown packages
- Replace useAppKit hooks with Para equivalents
- Ensure ParaModal component is included
- Validate CSS imports are correct"

# Para modal not appearing:
"Use validate_para_migration to check for the 3 critical issues that cause 90% of failures"

# Missing styles:
"Use generate_css_imports to find where to add Para SDK styles"

# Hook compatibility:
"Use generate_hooks_examples to show me before/after patterns for Privy to Para"

// ❌ v1.0: Modal functions called but no UI appears
<ParaProvider config={...}>
  {children}
</ParaProvider>

// ✅ v2.0: ParaModal automatically included
<ParaProvider config={...}>
  {children}
  {/* CRITICAL: Auto-included by atomic migration */}
  <ParaModal />
</ParaProvider>

// ❌ v1.0: Modal appears but styling broken
// No CSS imports

// ✅ v2.0: CSS automatically detected and imported
// layout.tsx, main.tsx, or _app.tsx
import '@para-wallet/react/styles.css' // Auto-added to correct entry point

// ❌ v1.0: Runtime errors from string usage
paraClientConfig: {
  env: "development" // Breaks at runtime
}

// ✅ v2.0: Environment enum automatically used
import { Environment } from "@para-wallet/react"
paraClientConfig: {
  env: Environment.DEVELOPMENT // Type-safe enum
}

// BEFORE: Privy Setup (100% removed)
"@privy-io/react-auth": "^2.21.3"     // ❌ Removed
"@privy-io/wagmi": "^1.0.6"           // ❌ Removed
usePrivy(), useWallets(), useLogin()   // ❌ Replaced

// AFTER: Para Setup (100% replaced)  
"@para-wallet/react": "^1.0.0"        // ✅ Added
useAccount(), useWallet(), useConnect() // ✅ Replaced
<ParaModal /> + CSS imports            // ✅ Auto-included

// BEFORE: ReOwn Setup (100% removed)
"@reown/appkit": "^1.0.0"              // ❌ Removed  
"@web3modal/wagmi": "^3.5.7"           // ❌ Removed
useAppKit(), useAppKitAccount()        // ❌ Replaced

// AFTER: Para Setup (100% replaced)
"@para-wallet/react": "^1.0.0"         // ✅ Added
useModal(), useAccount()               // ✅ Replaced  
<ParaModal /> + CSS imports            // ✅ Auto-included

# Test atomic architecture  
npm run test:atomic

# Test ReOwn migration support
npm run test:reown

# Test all migration strategies
npm run test:all

# Integration testing
npm run test:integration

# Clone and setup
git clone https://github.com/fruteroclub/Para-wallet-migration-mcp.git
cd Para-wallet-migration-mcp
npm install

# Development with hot reload
npm run dev

# Build for production  
npm run build

# Run test suite
npm test

# Verify installation:
ls -la ~/.claude.json | grep -A 5 para-migration

# If missing, re-run installation:
python3 -c "
import json
with open('/home/$(whoami)/.claude.json', 'r') as f:
    data = json.load(f)
data['mcpServers']['para-migration'] = {
    'command': 'node',
    'args': ['$(pwd)/dist/index.js']
}
with open('/home/$(whoami)/.claude.json', 'w') as f:
    json.dump(data, f, indent=2)
"

# Then restart Claude Code

# Check if build files exist:
ls -la dist/index.js

# If missing, rebuild:
npm run build

# Check Node.js version:
node --version  # Should be 18+

# Test MCP server directly:
node dist/index.js --test

# Verify MCP connection:
/mcp list

# Should show: para-migration ✔ connected

# Test with simple command:
"Generate Para config with API key test123"

# If no response, restart Claude Code

# Check rollback status:
"Use validate_migration_state to see what was rolled back"

# Common causes:
1. Missing write permissions
2. Conflicting dependencies  
3. Invalid project structure

# Instant fix:
"Use validate_para_migration to check for critical issues"

# Will detect and fix:
1. Missing <ParaModal /> component
2. Missing CSS imports
3. Wrong entry point configuration

# Detailed analysis:
"Use validate_migration_state to see completion breakdown"

# Shows exactly:
- Dependencies: X% complete
- Imports: X% complete  
- Providers: X% complete
- Hooks: X% complete