@uappi/mcp-vue2-to-vue3

MCP server para migração de projetos Vue 2 (Vue CLI + Options API) para Vue 3 (Vite + Options API), com validação visual pixel a pixel via Playwright.

Pré-requisitos

• Node.js 18+ e 16.20.1
• Claude Code instalado (npm install -g @anthropic-ai/claude-code)

Configuração inicial (uma vez por máquina)

1. Instalar os MCPs globalmente

npm install -g @playwright/mcp@latest
npm install -g @uappi/mcp-vue2-to-vue3

2. Instalar o browser do Playwright

npx playwright install chromium

3. Registrar os MCPs no Claude Code

claude mcp add playwright @playwright/mcp@latest
claude mcp add vue-migration mcp-vue2-to-vue3

Verifique se foram adicionados:

claude mcp list

Protocolo de migração

Passo 1 — Clonar e preparar o ambiente da loja

Clone o repositório da loja na sua máquina:

git clone <url-do-repositorio-da-loja>
cd <nome-do-repositorio>

O projeto Vue 2 (Vue CLI) requer Node 16. Mude para a versão correta, instale as dependências e suba o servidor:

nvm use 16.20.1
npm install
npm run serve
# app em http://localhost:8080

Mantenha este terminal aberto com o servidor rodando.

Passo 2 — Iniciar o Claude Code

Abra um novo terminal, mude para Node 18+ e inicie o Claude Code no projeto:

nvm use 18
cd caminho/do/projeto
claude

A partir daqui, o Claude executa as ferramentas do MCP automaticamente conforme necessário.

Passo 3 — Ignorar artefatos de teste no git

Antes de qualquer commit, adicione ao .gitignore:

test-snapshots/
migration-test-plan.md

Passo 4 — Capturar baselines pré-migração

Faça isso antes de criar a branch de migração.

Peça ao Claude:

"Gere o plano de testes e capture os screenshots pré-migração. O servidor está em http://localhost:8080. As rotas dinâmicas do cliente são: [liste exemplos reais, ex: /marcas/bermar, /busca?q=fritadeira, /freezer-fricon.html]"

O Claude irá executar automaticamente:

1. generate_test_plan — lê o router e cria migration-test-plan.md
2. capture_screenshots — captura as rotas estáticas (auto-detectadas do router)
3. capture_screenshots — captura as rotas dinâmicas com os exemplos fornecidos

Passo 5 — Criar a branch de migração

git checkout -b migration

Passo 6 — Migrar os componentes

Peça ao Claude:

"Verifique o progresso da migração e comece a migrar os componentes pendentes."

O Claude irá usar get_migration_progress e analyze_component para guiar a migração, consultando as regras em migration://rules/general, migration://rules/api-consumption e migration://rules/vite-setup.

Passo 7 — Subir o servidor Vite

Com todos os componentes migrados:

npm run dev
# app em http://localhost:5173

Passo 8 — Validar a migração

Peça ao Claude:

"Capture os screenshots pós-migração e compare com os baselines. O servidor está em http://localhost:5173."

O Claude irá executar automaticamente:

1. capture_screenshots — captura pós-migração (estáticas + dinâmicas)
2. compare_all_routes — compara pixel a pixel com os baselines

Resultado esperado: ✅ APROVADO — N rotas sem nenhuma diferença visual.

A migração só está concluída quando compare_all_routes retorna 100% ✅. Qualquer pixel de diferença bloqueia o merge — peça ao Claude para investigar e corrigir.

Passo 9 — Merge

git checkout main
git merge migration

Ferramentas disponíveis

| Ferramenta | Descrição | |---|---| | generate_test_plan | Lê o router e gera migration-test-plan.md + diretórios de snapshots | | capture_screenshots | Captura screenshots full-page via Playwright (pré ou pós-migração) | | compare_visual_regression | Comparação pixel a pixel de uma rota (tolerância 0%) | | compare_all_routes | Compara todas as rotas com os baselines pré-migração | | analyze_component | Lista todos os padrões Vue 2 que precisam ser migrados em um .vue | | get_migration_progress | Mostra quantos componentes já estão prontos vs pendentes |

Recursos de regras

| URI | Conteúdo | |---|---| | migration://rules/pre-migration | Protocolo completo de captura e validação visual | | migration://rules/general | Breaking changes do Vue 3 (filters, lifecycle, event bus, router, vuex) | | migration://rules/api-consumption | Como atualizar plugins e manter $requestSend funcionando | | migration://rules/vite-setup | Passo a passo da troca de Vue CLI por Vite |

Atualizar os MCPs

npm install -g @playwright/mcp@latest
npm install -g @uappi/mcp-vue2-to-vue3

claude mcp remove playwright
claude mcp remove vue-migration
claude mcp add playwright @playwright/mcp@latest
claude mcp add vue-migration mcp-vue2-to-vue3