next-devtools-guide

Next.js DevTools MCP

要件：Node.js v20.19+、npm または pnpm、ランタイム診断には Next.js 16+ が必要です。

合計機能数：7 個のツール + 2 個のプロンプト + 17 個のリソース = 利用可能な機能は 26 個です。

ツールの命名規則：すべてのツールは mcp__plugin_next-devtools_next-devtools__<tool-name> に従います。このファイルでは簡潔にするため、略称を使用しています。

完全なツール一覧と nextjs_call のツール名については、references/tools-reference.md を参照してください。

ツール（7 個）

ツール	目的
init	ドキュメントを優先する動作で MCP コンテキストを初期化します
nextjs_index	実行中の Next.js 開発サーバーと利用可能な MCP ツールを検出します
nextjs_call	実行中の Next.js 開発サーバー上で特定の MCP ツールを呼び出します
nextjs_docs	パスを指定して Next.js の公式ドキュメントを取得します
browser_eval	テスト用の Playwright ブラウザー自動化
enable_cache_components	Next.js 16 の Cache Components モードに移行します
upgrade_nextjs_16	Next.js 16 へのアップグレードをガイドします

プロンプト（2 個）

プロンプト	目的
upgrade-nextjs-16	codemod の実行と手動修正を含む、完全なアップグレードガイド
enable-cache-components	自動エラー修正を含む、Cache Components の完全なセットアップ

リソース（17 個）

Cache Components（13 個）：

• cache-components://overview - AI エージェントが起こしやすい重大なエラー、クイックリファレンス
• cache-components://core-mechanics - 基本となるパラダイムシフトと cacheComponents の動作
• cache-components://public-caches - 'use cache' を使用するパブリックキャッシュの仕組み
• cache-components://private-caches - 'use cache: private' を使用するプライベートキャッシュの仕組み
• cache-components://runtime-prefetching - プリフェッチの設定と stale time のルール
• cache-components://request-apis - 非同期 params、searchParams、cookies()、headers() のパターン
• cache-components://cache-invalidation - updateTag()、revalidateTag() のパターンと戦略
• cache-components://advanced-patterns - cacheLife()、cacheTag()、ドラフトモード
• cache-components://build-behavior - プリレンダリング、静的シェル、ビルド時の動作
• cache-components://error-patterns - よくあるエラーと解決策
• cache-components://test-patterns - 125 件以上のフィクスチャに基づく、実践的なテスト駆動パターン
• cache-components://reference - メンタルモデル、API リファレンス、チェックリスト
• cache-components://route-handlers - Route Handler（API Routes）での 'use cache' の使用

その他（4 個）：

• nextjs-fundamentals://use-client - Server Components で 'use client' を使うタイミングと理由を学びます
• nextjs16://migration/beta-to-stable - Next.js 16 beta から stable への移行に関する完全ガイド
• nextjs16://migration/examples - Next.js 16 への移行の実例
• nextjs-docs://llms-index - Next.js ドキュメントの完全なインデックス

セッションの初期化

ドキュメントを優先する動作とツールの使用方法に関するガイダンスを設定するため、すべてのセッションの開始時に init を呼び出してください。

クイックスタート

Next.js 16+（ランタイム診断）：

1. 開発サーバーを起動します：npm run dev（または pnpm dev）
2. init を呼び出して MCP コンテキストを初期化します
3. nextjs_index を呼び出して実行中のサーバーと利用可能なツールを検出します
4. nextjs_call を呼び出し、目的の toolName を指定して開発サーバー上のツールを実行します

すべての Next.js バージョン（自動化とドキュメント）：

init の後、必要に応じて upgrade_nextjs_16、enable_cache_components、nextjs_docs、または browser_eval を使用してください。

一般的なワークフロー

変更を実装する前：nextjs_index を呼び出して現在のアプリケーションの状態を把握し、その後、適切なツールを指定して nextjs_call を呼び出します。

エラーの検出：nextjs_index を呼び出し、その後 toolName="get_errors" を指定して nextjs_call を呼び出します。

ルートの確認：nextjs_index を呼び出し、その後 toolName="get_routes" を指定して nextjs_call を呼び出します。

Server Action の追跡：toolName="get_server_action_by_id" と適切な引数を指定して nextjs_call を呼び出します。

ドキュメントの検索：MCP リソース nextjs-docs://llms-index を読み、正しいパスを取得してから、そのパスを指定して nextjs_docs を呼び出します。

重要：nextjs_call の args パラメーターは、オブジェクトでなければなりません。ツールに引数が必要ない場合は、args 自体を省略してください。

トラブルシューティング

MCP サーバーに接続できない場合：

• Next.js v16 以降であることを確認します
• .mcp.json で next-devtools-mcp が設定されていることを確認します
• 開発サーバーを起動または再起動します（npm run dev）
• nextjs_index による自動検出に失敗した場合は、開発サーバーが実行されているポートをユーザーに確認し、port パラメーターに指定します

「No server info found」：開発サーバーが実行されている必要があります。Next.js 15 以前を使用している場合は、upgrade_nextjs_16 ツールを使用します。

モジュールが見つからない場合：npx キャッシュをクリアし、MCP クライアントを再起動します。

ベストプラクティス

• 他のツールを使う前に、セッション開始時に init を呼び出します
• nextjs_index または nextjs_call を使う前に、開発サーバーを起動します
• エラーの検出と診断には、browser_eval よりも nextjs_index／nextjs_call を優先します
• 実際のページ描画や JavaScript の実行が必要なタスクに限り、browser_eval を使用します
• nextjs_docs を呼び出す前に、まず nextjs-docs://llms-index リソースを読みます