📋 Next.js 16 MCP 툴 완전 가이드

🔧 내장 MCP 서버 툴 (5가지)

Next.js 16 개발 서버에 기본 탑재되어 있으며, /_next/mcp 엔드포인트를 통해 접근합니다.

1️⃣ get_errors

기능: 현재 발생한 모든 에러 조회

반환 정보:

• 빌드 에러 (Build Errors)
• 런타임 에러 (Runtime Errors)
• 타입 에러 (Type Errors)
• 브라우저 세션별 에러

실전 예제:

# AI 에이전트 사용
"내 앱에 현재 어떤 에러가 있어?"

# MCP 응답 예시
{
  "success": true,
  "port": 3000,
  "toolName": "get_errors",
  "result": {
    "content": [{
      "type": "text",
      "text": "# Found errors in 1 browser session(s)\n\n
      ## Session: /about\n\n
      **1 error(s) found**\n\n
      ### Runtime Errors\n\n
      #### Error 1 (Type: recoverable)\n\n
      **Error**: Hydration failed\n
      Server: 'server', Client: 'client'"
    }]
  }
}

2️⃣ get_logs

기능: 개발 서버의 콘솔 로그와 출력 조회

반환 정보:

• console.log 출력
• 경고 메시지
• 에러 메시지
• 서버 시작 로그

실전 예제:

# AI 에이전트 사용
"최근 서버 로그 보여줘"

# 반환되는 로그
✓ Compiled /_app successfully in 1.2s
✓ Ready on http://localhost:3000
⚠ Warning: Component is missing display name
✓ GET /api/users 200 in 45ms

3️⃣ get_page_metadata

기능: 특정 페이지의 라우트, 컴포넌트, 렌더링 정보 조회

반환 정보:

• 페이지 경로 (route)
• 렌더링된 컴포넌트 목록
• 레이아웃 정보
• 메타데이터 (title, description)
• 렌더링 타입 (SSR, SSG, CSR)

실전 예제:

# AI 에이전트 사용
"홈페이지에서 어떤 컴포넌트가 렌더링되고 있어?"

# 입력
get_page_metadata('/')

# 반환 예시
{
  "route": "/",
  "components": [
    "RootLayout",
    "HomePage",
    "Header",
    "Hero",
    "Footer"
  ],
  "layout": "app/layout.tsx",
  "metadata": {
    "title": "My Next.js App",
    "description": "Welcome page"
  },
  "renderType": "SSR"
}

4️⃣ get_project_metadata

기능: 프로젝트 전체 구조, 설정, 메타데이터 조회

반환 정보:

• 프로젝트 구조
• next.config.js 설정
• 사용 중인 라우트 목록
• 빌드 상태
• Dev 서버 URL

실전 예제:

# AI 에이전트 사용
"내 프로젝트 구조를 알려줘"

# 반환 예시
{
  "projectRoot": "/Users/dev/my-app",
  "devServerUrl": "http://localhost:3000",
  "routes": [
    "/",
    "/about",
    "/blog",
    "/api/users"
  ],
  "config": {
    "reactStrictMode": true,
    "images": {
      "domains": ["example.com"]
    }
  },
  "buildStatus": "ready"
}

5️⃣ get_server_action_by_id

기능: Server Action ID로 소스 파일과 함수명 조회

반환 정보:

• Server Action의 소스 파일 경로
• 함수명
• 함수 시그니처

실전 예제:

# Server Action ID로 조회
get_server_action_by_id('abc123')

# 반환 예시
{
  "id": "abc123",
  "sourceFile": "app/actions/user.ts",
  "functionName": "createUser",
  "signature": "async (formData: FormData) => Promise<User>"
}

---

🛠️ Next DevTools MCP 툴 (4가지)

외부 npm 패키지로 제공되며, 상위 레벨 개발 도구입니다.

1️⃣ nextjs_runtime

기능: 실행 중인 Next.js 개발 서버 발견 및 MCP 도구 호출

액션:

• discover_servers: 실행 중인 Next.js 서버 자동 발견
• list_tools: 사용 가능한 MCP 도구 목록 조회
• call_tool: 특정 도구 실행

실전 예제:

// 1. 서버 발견
{
  "action": "discover_servers",
  "includeUnverified": false
}

// 반환
{
  "servers": [
    {
      "port": 3000,
      "url": "http://localhost:3000",
      "mcpEndpoint": "http://localhost:3000/_next/mcp"
    }
  ]
}

// 2. 도구 목록 조회
{
  "action": "list_tools",
  "port": 3000
}

// 반환
{
  "tools": [
    "get_errors",
    "get_logs",
    "get_page_metadata",
    "get_project_metadata",
    "get_server_action_by_id"
  ]
}

// 3. 도구 실행
{
  "action": "call_tool",
  "port": 3000,
  "toolName": "get_errors",
  "args": {}
}

2️⃣ nextjs_docs

기능: Next.js 공식 문서 및 지식 베이스 검색

파라미터:

• query (필수): 검색 쿼리
• category (선택): 카테고리 필터
  • all, getting-started, guides, api-reference, architecture, community

실전 예제:

// AI 에이전트 사용
"'use client'는 언제 써야 해?"

// MCP 실행
{
  "query": "use client directive",
  "category": "guides"
}

// 반환
{
  "results": [
    {
      "title": "Client Components",
      "url": "https://nextjs.org/docs/app/building/rendering/client-components",
      "content": "Client Components allow you to write interactive UI...",
      "source": "nextjs16://knowledge/core-mechanics"
    }
  ]
}

3️⃣ upgrade_nextjs_16

기능: Next.js 16으로 자동 업그레이드 가이드 및 codemod 실행

파라미터:

• project_path (선택): 프로젝트 경로 (기본값: 현재 디렉토리)

자동 처리 항목:

• Async API 변경 (params, searchParams, cookies, headers)
• 설정 파일 마이그레이션
• 이미지 최적화 기본값 변경
• Deprecated API 제거
• React 19 호환성 처리

실전 예제:

# AI 에이전트 사용
"Next.js 16으로 업그레이드 도와줘"

# MCP 실행
{
  "project_path": "/Users/dev/my-app"
}

# 반환
{
  "steps": [
    {
      "phase": "Pre-flight Checks",
      "status": "completed",
      "checks": [
        "✓ Clean git state",
        "✓ Next.js 15.x detected",
        "✓ Node.js 20.x compatible"
      ]
    },
    {
      "phase": "Running Codemods",
      "status": "in_progress",
      "codemods": [
        "✓ async-request-api",
        "⏳ next-dynamic-migration",
        "⏺ image-imports"
      ]
    },
    {
      "phase": "Manual Changes Required",
      "items": [
        "Update middleware.ts to proxy.ts",
        "Review next/image changes"
      ]
    }
  ]
}

4️⃣ enable_cache_components

기능: Next.js 16 Cache Components 설정 및 자동 오류 수정

파라미터:

• project_path (선택): 프로젝트 경로

자동 처리:

• Cache Components 설정 활성화
• Dev 서버 MCP 모드로 시작
• 라우트 검증 및 에러 감지
• Suspense 경계 자동 추가
• 캐싱 지시문 설정
• 정적 params 처리

실전 예제:

# AI 에이전트 사용
"Cache Components를 내 앱에 설정해줘"

# MCP 실행
{
  "project_path": "/Users/dev/my-app"
}

# 반환
{
  "phases": [
    {
      "name": "Pre-flight Checks",
      "status": "completed",
      "details": "✓ Next.js 16.0.0 detected"
    },
    {
      "name": "Enable Configuration",
      "status": "completed",
      "changes": [
        "Added experimental.cacheComponents: true"
      ]
    },
    {
      "name": "Route Verification",
      "status": "completed",
      "routes_checked": ["/", "/about", "/blog"]
    },
    {
      "name": "Error Detection",
      "errors_found": [
        {
          "route": "/blog",
          "error": "Missing Suspense boundary",
          "fix": "Added <Suspense> wrapper"
        }
      ]
    },
    {
      "name": "Final Verification",
      "status": "success",
      "build_status": "passed"
    }
  ]
}

5️⃣ browser_eval

기능: Playwright를 사용한 브라우저 자동화 및 테스팅

주요 액션:

• start: 브라우저 시작
• navigate: 페이지 이동
• click: 요소 클릭
• type: 텍스트 입력
• screenshot: 스크린샷 캡처
• console_messages: 콘솔 메시지 조회
• evaluate: JavaScript 실행

실전 예제:

// 1. 브라우저 시작 및 페이지 이동
{
  "action": "start",
  "browser": "chrome",
  "headless": true
}

{
  "action": "navigate",
  "url": "http://localhost:3000"
}

// 2. 스크린샷 캡처
{
  "action": "screenshot",
  "fullPage": true
}

// 반환
{
  "screenshot": "base64_encoded_image_data",
  "timestamp": "2025-10-28T10:30:00Z"
}

// 3. 콘솔 에러 확인
{
  "action": "console_messages"
}

// 반환
{
  "messages": [
    {
      "type": "error",
      "text": "Uncaught ReferenceError: foo is not defined",
      "location": "app/page.tsx:42"
    }
  ]
}

// 4. 사용자 인터랙션 테스트
{
  "action": "click",
  "selector": "button[data-testid='submit']"
}

{
  "action": "type",
  "selector": "input[name='email']",
  "text": "test@example.com"
}

---

🎯 실전 워크플로우 예제

예제 1: 에러 진단 및 수정

사용자: "페이지에 에러가 있어. 고쳐줘"

AI 실행 순서:
1. get_errors() → 하이드레이션 에러 발견
2. get_page_metadata('/about') → 문제 페이지 구조 파악
3. get_logs() → 상세 로그 확인
4. 수정 코드 제안
5. 다시 get_errors() → 수정 확인

예제 2: 새 기능 추가

사용자: "블로그 페이지에 댓글 기능 추가해줘"

AI 실행 순서:
1. get_project_metadata() → 프로젝트 구조 파악
2. get_page_metadata('/blog') → 블로그 페이지 컴포넌트 확인
3. nextjs_docs("server actions") → Server Actions 문서 검색
4. 코드 생성 및 추가
5. browser_eval → 브라우저에서 실제 테스트

예제 3: 업그레이드

사용자: "Next.js 16으로 업그레이드하고 Cache Components 활성화해줘"

AI 실행 순서:
1. upgrade_nextjs_16() → 자동 업그레이드 실행
2. enable_cache_components() → Cache Components 설정
3. get_errors() → 마이그레이션 후 에러 확인
4. browser_eval → 각 페이지 브라우저 검증

---

💡 핵심 요약

내장 MCP 툴 (앱 내부 상태):

1. ✅ get_errors - 에러 조회
2. 📋 get_logs - 로그 조회
3. 📄 get_page_metadata - 페이지 정보
4. 🗂️ get_project_metadata - 프로젝트 구조
5. ⚡ get_server_action_by_id - Server Action 디버깅

DevTools MCP 툴 (개발 가이드):

1. 🔌 nextjs_runtime - 서버 발견 및 도구 실행
2. 📚 nextjs_docs - 문서 검색
3. 🚀 upgrade_nextjs_16 - 자동 업그레이드
4. ⚙️ enable_cache_components - Cache Components 설정
5. 🌐 browser_eval - 브라우저 테스팅

이 툴들을 조합하면 AI 에이전트가 여러분의 Next.js 앱을 완벽하게 이해하고 도움을 줄 수 있습니다! 🎉