react-render-profile-mcp의 내부 작동 원리 - 그리고 실제 프로젝트에서 발견한 것들

저는 지난 몇 달 동안 react-render-profile-mcp를 구축해 왔습니다. 이는 AI 에이전트가 렌더링 성능을 진단하고 이제는 수정까지 할 수 있도록 React DevTools Profiler 내보내기(exports)를 디코딩하는 MCP (Model Context Protocol) 서버입니다. 이전 포스트에서는 v0.1과 v0.3.1을 다루었습니다. 이번에는 v1.0입니다. 저는 이 포스트에서 두 가지를 하고자 합니다. 실제 오픈 소스 프로젝트에서 무엇을 발견했는지 보여주는 것, 그리고 내부 엔진이 어떻게 작동하는지 설명하는 것입니다. 왜냐하면 "그저 MCP 래퍼(wrapper)일 뿐이다"라는 생각은 올바른 멘탈 모델이 아니기 때문입니다.

🐸 제1막 — slash-admin에서 발견한 것
저는 Zustand와 React Router를 사용하는 실제 React 관리자 대시보드인 slash-admin에서 전체 사이클을 실행했습니다.

대상: src/pages/management/user/profile/index.tsx 내의 UserProfile
진단 과정: get_render_summary → find_spurious_renders → analyze_compiler_efficacy → suggest_memoization
UserProfile에서 12개의 불필요한 렌더링(spurious renders) 발생
42ms 낭비
트리거: UNSTABLE_PARENT_REF Invalidation
인덱스: 22.5
ROI 점수: 2.5 (임계값은 1.5)

문제는 렌더링 본문 내부에 있는 두 개의 인라인 상수(inline constants)였습니다:

function UserProfile () {
const bgStyle : CSSProperties = {
position : " absolute ",
inset : 0,
background : url( ${ bannerImage } ),
backgroundSize : " cover ",
backgroundRepeat : " no-repeat ",
};
const tabs = [
{ icon : , title : " " Profile " },
{ icon : , title : " " Followers " },
// ...기타 3개
];
return ( ... );
}

매 렌더링마다 새로운 객체 참조(object reference)가 생성됩니다. 이로 인해 실제로 변경 사항이 있는지 여부와 관계없이, 하위의 모든 메모이제이션(memoized)된 자식 요소들이 매 패스마다 무효화(invalidated)됩니다.

자동 수정 및 에지 케이스(edge case)
remediate_component는 세 번의 AST (Abstract Syntax Tree) 패스를 실행합니다. 이 파일에서 즉시 실제 에지 케이스에 부딪혔습니다:

import type { CSSProperties } from " react " ;

타입 전용 임포트(Type-only import). 이를 수정하지 않고 기본 내보내기(default export)에 React.memo를 추가하면 런타임 ReferenceError가 발생하게 됩니다.

해결사(remediator)가 이를 감지하여 import 문을 다시 작성하고 작업을 계속했습니다: -import type { CSSProperties } from "react"; +import React, { CSSProperties } from "react"; 그 후 세 번의 패스(pass)가 실행되었습니다: -function UserProfile() { - const bgStyle: CSSProperties = { position: "absolute", inset: 0, ... }; - const tabs = [{ icon: , title: ""Profile"" }, ...];" +const bgStyle: CSSProperties = { position: "absolute", inset: 0, ... }; +const tabs = [{ icon: , title: ""Profile"" }, ...];" +function UserProfile() { const { avatar, username } = useUserInfo(); return ( ... ); } -export default UserProfile; +export default React.memo(UserProfile); 기존 구현의 이러한 결함은 실제 코드에서 실행함으로써 발견되었습니다. 이제 새로운 단위 테스트(unit test)가 import type 케이스를 커버합니다. 57개의 테스트 통과. 42ms의 불필요한 렌더링(spurious renders) 제거. 수동으로 작성된 코드는 0줄입니다.

제2막 — 내부에서 실제로 작동하는 방식
이 부분은 단순히 작동한다는 사실을 넘어, 실제로 어떤 일이 일어나고 있는지 이해하고 싶을 때 중요한 대목입니다.

계층 1: 프로파일러(profiler) 형식 디코딩
React DevTools 버전 5가 내보내는 형식은 대부분의 개발자가 수동으로 파싱할 필요가 없었던 형식입니다. 까다로운 부분들은 다음과 같습니다:

changeDescriptions는 JSON 객체가 아닌 Map.entries()로 직렬화(serialized)됩니다: "changeDescriptions" : [[ 3 , { "isFirstMount" : true }], [ 4 , { "props" : []}]]
파서(parser)는 로드 시 이를 Record로 정규화(normalize)하여 나머지 코드들이 일관되게 작동할 수 있도록 합니다.

operations는 트리 변이(tree mutations)를 인코딩하는 오피코드(opcode) 정수 배열입니다. 형식: [ rendererID , rootFiberID , stringTableSize , ...strings , ...opcodes ]

• 오피코드 1 (ADD): [ 1 , id , type , parentID , ownerID , nameStringIdx , keyIdx ]
• 오피코드 2 (REMOVE): [ 2 , count , id 1 , id 2 , ... ]
• 오피코드 3 (REORDER_CHILDREN): [ 3 , id , count , ...childIds ]

파서는 React 런타임 없이, 오직 정수 산술(integer arithmetic)과 문자열 테이블 조회(string table lookups)만으로 이 배열을 순회하며 fiber 이름 맵, 부모-자식 관계, 그리고 언마운트 횟수(unmount counts)를 재구성합니다.

두 가지 이름 해석 (name resolution) 전략과 폴백(fallback) 방식:

• 기본(Primary): 스냅샷 맵 (snapshots map, 사람이 읽을 수 있으며 항상 우선적으로 사용)
• 폴백(Fallback): 연산(operations)의 오코드(opcodes)로부터 문자열 테이블(string table)을 디코딩

이 이중 전략 덕분에 파서는 다양한 DevTools 내보내기(export) 설정에 대해 견고하게 작동합니다.

가짜 렌더링(Spurious render) 탐지는 한 가지 직관적이지 않은 React의 동작에 의존합니다: 컴포넌트가 불안정한 프롭 참조(unstable prop reference)로 인해 재렌더링되지만 실제 프롭 값은 변경되지 않은 경우, React는 changeDescriptions에 props: [] (빈 배열)를 기록합니다. props: null은 알 수 없음을 의미하며, props: ["value"]는 value 프롭이 실제로 변경되었음을 의미합니다. 파서는 정확히 이 신호를 사용합니다:

function isSpurious ( fiberID : number , commit : ProfileCommit ): boolean {
  const desc = commit . changeDescriptions ?.[ String ( fiberID )];
  if ( ! desc ) return false ;
  if ( desc . isFirstMount || desc . context || desc . didHooksChange ) return false ;
  if ( desc . state && desc . state . length > 0 ) return false ;
  return desc . props !== null && desc . props . length === 0 ;
}

React 18 동시성 모드(concurrent mode)의 오탐(false-positive) 방지: startTransition과 useDeferredValue는 React가 불완전한 트리(incomplete trees)를 추측하여 렌더링하고 폐기함에 따라 컴포넌트를 여러 번 렌더링하게 만들 수 있습니다. 이러한 경우 priorityLevel: "Low Priority" 또는 `

Layer 3: AST 수정 엔진 (AST remediation engine)

ASTPerformanceRemediator는 ts-morph (TypeScript compiler API wrapper)를 사용하여 소스 파일에 대해 세 번의 패스(pass)를 수행합니다:

Pass 1 — 정적 호이스팅 (static hoisting). 렌더링 본문(render body)을 탐색하여 초기화 식(initializer)이 ObjectLiteralExpression 또는 ArrayLiteralExpression인 VariableStatement 노드를 찾습니다. 각 노드에 대해, 내부의 Identifier가 컴포넌트 범위 바인딩(props, state, hooks)을 참조하는지 확인합니다. 참조하지 않는다면 — 이는 정적(static)인 것이므로 모듈 범위(module scope)로 호이스팅됩니다. 이 과정은 더 이상 호이스팅 가능한 문장이 발견되지 않을 때까지 루프를 돌며 실행되어, 컴포넌트당 여러 개의 선언을 처리합니다.

Pass 2 — useCallback 래핑 (useCallback wrapping). 렌더링 본문 내부의 ArrowFunction 노드를 탐색합니다. 불안정한 prop 이름과 일치하는 각 노드에 대해 resolveReactiveDependencies를 호출합니다. 이 함수는 화살표 함수의 모든 Identifier 후손(descendant)을 탐색하고 이를 컴포넌트의 로컬 범위 바인딩과 교차(intersect)시킵니다. 이를 통해 개발자가 수동으로 고민할 필요 없이 의존성 배열(dependency array)이 자동으로 생성됩니다.

Pass 3 — React.memo 래핑 (React.memo wrapping). ROI 점수가 1.5를 초과하는지 확인한 후, 기본 내보내기(default export) 할당을 찾아 이를 다시 작성(rewrite)합니다. (slash-admin에서 발견된 예외 케이스인) 임포트 확인 작업이 이제 가장 먼저 실행됩니다. 만약 파일이 import type ... from "react"만 가지고 있다면, 래퍼를 적용하기 전에 이를 값 임포트(value import)로 다시 작성합니다.

세 가지 패스 모두 라이브 AST 상에서 작동하며 마지막에 한 번 saveSync()를 호출합니다. 중간 파일 쓰기가 없으므로 부분적인 상태(partial state)가 발생할 위험이 없습니다.

왜 React 런타임 의존성이 없는가

위에서 설명한 모든 것 — opcode 디코딩, 이름 해석(name resolution), 불필요한 렌더링 탐지(spurious render detection), 캐스케이드 추적(cascade tracing) — 은 순수 JSON과 TypeScript 상에서 실행됩니다. React, DevTools, 브라우저가 필요하지 않습니다. 이는 의도된 설계입니다. 서버는 빠르게 시작되어야 하며(모든 MCP 클라이언트 연결 시 npx 명령으로 실행됨), 어떤 환경에서도 안전하게 실행되어야 하기 때문입니다.

설정 (Setup)

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

프로필 내보내기: React DevTools → Profiler 탭 → Record → 상호작용 → Stop → 저장 아이콘 (💾).

.json 경로를 profile_path 로 전달하세요. GitHub: vola-trebla/react-render-profile-mcp npm: npx react-render-profile-mcp opcode 디코더(opcode decoder)나 의존성 추론(dependency inference) 로직에 관한 질문은 언제든 환영합니다. 🐸