react-render-profile-mcp

Decodifica exportações do Profiler do React DevTools e detecta renderizações espúrias

Documentação

react-render-profile-mcp

Um Mecanismo Autônomo de SRE de Performance e Auto-Remedicação para React, exposto como um servidor Model Context Protocol (MCP). Construído especificamente para preencher a lacuna de percepção de performance para agentes de codificação de IA (Claude, Cursor, Copilot).

👁️ O Ponto Cego: Por Que Agentes de IA Quebram a Produção React

Quando um agente de IA refatora um Context Provider, altera a arquitetura de estado ou conecta um store global, ele está completamente cego para o impacto de performance em tempo de execução.

Um agente pode passar em testes unitários e compilar código com sucesso enquanto introduz regressões catastróficas de performance:

Uma única atualização de estado em cascata causando 80 re-renderizações desnecessárias de componentes filhos.
Loops infinitos de renderização disparados por referências instáveis de seletores Zustand/Redux.
Incompatibilidades de hidratação forçando o React a descartar o HTML renderizado no servidor e montar do zero.
Props key instáveis causando desmontagem e remontagem de componentes a cada ciclo de renderização (anomalias de ciclo de vida).

react-render-profile-mcp dá aos agentes de IA um "terceiro olho" para medir dinamicamente, visualizar e auto-remediar esses gargalos de performance.

⚡ Os Quatro Pilares do AI-SRE

Em vez de despejos brutos de JSON, este servidor organiza dados de performance em insights estruturados e acionáveis em quatro pilares centrais de engenharia:

🧠 1. Mecanismo de Auto-Remedicação AST (`ts-morph`)

Quando um gargalo é encontrado, o agente não precisa reescrever o código manualmente. O servidor pode modificar o código-fonte do componente no disco:

Hoisting: Elevação estática de literais de objetos e arrays para fora dos corpos de renderização.
Memoização Dinâmica: Encapsulamento de funções e variáveis instáveis em useCallback e useMemo com arrays de dependências calculados.
Encapsulamento ROI: Encapsulamento de componentes em React.memo somente se o tempo próprio perfilado e a contagem de renderizações espúrias justificarem a sobrecarga de comparação (ROI > 1.5).
Auditoria de Regras: Varredura de código para prevenir bailouts do compilador (detecção de mutações em Date.now(), Math.random() ou useRef durante a fase de renderização).

📊 2. Visualizador Interativo de Cascata SVG (Recurso MCP)

Gera gráficos de renderização pai-filho diretamente na janela de chat do agente usando o esquema de URI de recurso personalizado react-profile://commits/{commitId}/cascade?profile_path={profile_path}.

Os gatilhos são estilizados com paletas HSL distintas para isolar canais de propagação:
- 🔵 Gatilho de Contexto: Azul (onda oceânica)
- 🟠 Store Zustand/Redux: Laranja (ondulação de assinantes)
- 🔴 Invalidação de Props: Vermelho (incompatibilidade de referência)
- 🟢 Mudança de Estado: Verde (fonte de gatilho esmeralda)

🛡️ 3. Perfilador de Fluxo RSC e Segurança

Analisa fluxos Flight de React Server Components (RSC) para otimizar a entrega:

Identifica chunks inchados (> 50KB) e cascatas sequenciais.
Examina payloads em busca de vulnerabilidades de travessia de protótipo, como explorações CVE-2025-55182 (React2Shell).

⚛️ 4. Correlacionador de Rastreamento Multi-Camada

Alinha commits do React com eventos da linha do tempo do Chrome Performance usando marcadores blink.user_timing.

Mede tarefas de layout pós-commit, pintura e cálculo de estilo para calcular impactos reais nos Core Web Vitals (estimativas de CLS / INP).

🛠️ Referência de Ferramentas MCP

Abaixo está um resumo compacto das ferramentas expostas por este servidor. Todas as ferramentas aceitam um profile_path obrigatório apontando para uma exportação do React DevTools .json.

Nome da Ferramenta	Parâmetros	Propósito / Saída
`get_render_summary`	`profile_path`	Visão geral de commits, tempo total de renderização, contagem de renderizações espúrias e anomalias de ciclo de vida.
`find_spurious_renders`	`profile_path`, `min_render_count`?	Lista componentes que renderizaram com props/estado idênticos. Classifica o gatilho em `UNSTABLE_PARENT_REF` ou `CONTEXT_UPDATE`.
`analyze_compiler_efficacy`	`profile_path`, `invalid_threshold`?	Calcula o Índice de Invalidação para identificar onde o React Compiler ou `React.memo` está sendo ignorado.
`diagnose_hydration_and_suspense`	`profile_path`, `waterfall_threshold_ms`?	Detecta incompatibilidades de hidratação servidor-cliente e cascatas aninhadas de fetch com Suspense.
`evaluate_external_store_performance`	`profile_path`, `max_blocking_task_ms`?	Encontra seletores instáveis de useSyncExternalStore e tarefas síncronas bloqueantes de alta prioridade.
`trace_state_cascade_footprint`	`profile_path`, `commit_index`	Rastreia a árvore virtual de proprietários para medir a profundidade de propagação e a contagem de consumidores de atualizações.
`suggest_memoization`	`profile_path`, `min_wasted_ms`?	Fornece sugestões de `React.memo` de alto ROI com base no tempo próprio médio (limite > 2ms).
`remediate_component`	`file_path`, `component_name`, `unstable_props`, `roi_score`	Modifica o AST no disco para elevar variáveis, encapsular hooks e aplicar memoização.
`audit_compiler_rules`	`file_path`, `component_name`	Audita estaticamente o código-fonte do componente em busca de violações de regras do React Compiler.
`profile_rsc_stream`	`stream_payload`	Analisa logs de Flight RSC para auditar tamanhos de chunks, cascatas e explorações de `React2Shell`.
`correlate_chrome_trace`	`profile_path`, `trace_path`	Alinha commits do React com eventos de rastreamento do Chrome para calcular impactos nos web vitals CLS/INP.

🤖 Injeção de Prompt: Ensine Seu Agente a Perfilar

Para aproveitar ao máximo este servidor, adicione o seguinte prompt às instruções de sistema do seu agente (por exemplo, em .cursorrules, Prompt de Sistema do Cursor ou Instruções Personalizadas do Claude):

You are equipped with `react-render-profile-mcp`. Use it systematically whenever:

1. You make structural changes to React components, global state providers, or store selectors.
2. The user reports lag, slow input response, or UI stuttering.
3. You refactor context providers, Zustand selectors, or Redux dispatches.

Debugging Workflow:

- Ask the user to record and export a React DevTools profile (.json).
- Run `get_render_summary` to understand the scale of the problem and look for `lifecycle_anomaly: true` (unstable keys).
- Run `find_spurious_renders` and `analyze_compiler_efficacy` to pinpoint unstable prop references.
- Call the `react-profile://commits/{commitId}/cascade` resource to visualize cascades.
- Use `remediate_component` to automatically apply AST optimizations (hoisting static variables, wrapping hooks) instead of doing it manually.

📋 Como Exportar um Perfil

Abra o React DevTools no seu navegador.
Navegue até a aba Profiler.
Clique no botão Record (círculo), interaja com sua aplicação para disparar o problema de performance e clique em Stop.
Clique no ícone Save Profile (💾) para baixar o arquivo .json.
Forneça o caminho absoluto para este arquivo ao servidor MCP.

⚙️ Configuração e Instalação

Claude Desktop

Adicione isto ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "react-render-profile": {
      "command": "npx",
      "args": ["-y", "react-render-profile-mcp"]
    }
  }
}

Cursor / VS Code / Outros Clientes

Adicione um servidor MCP do tipo command:

Comando: npx -y react-render-profile-mcp

🔧 Por Dentro do Funcionamento

Nativo ESM: Construído com TypeScript ESM, otimizado para importações rápidas no Node.js.
Protocolo React DevTools v5: Decodifica nativamente arrays de operações serializadas, resolvendo snapshots de fibras e mapas de nomes.
Identificação de Lanes: Distingue entre atualizações de lanes de alta prioridade e commits de transição concorrentes (Baixa Prioridade/Idle) para prevenir sinalizações falsas de regressão.
Segurança na Modificação de AST: Implementa blocos de manipulação de declarações ts-morph, evitando corrupção comum do estado do parser durante reescritas de múltiplas passagens.

Parte do Cinto de Ferramentas MCP

Desenvolvido em conjunto com:

tailwind-context-resolver-mcp — Resolve tokens de design Tailwind e valida classes de utilitários.
v8-cpu-profile-decoder-mcp — Decodifica perfis de CPU V8 para ajuste de performance no backend Node.js.

Licença

MIT

react-render-profile-mcp

Documentação