compile route mcsp handler

Author: lukesandberg

docs/01-app/02-guides/mcp.mdx

@@ -86,6 +86,8 @@ Through `next-devtools-mcp`, agents can use the following tools:
 - **`get_project_metadata`**: Retrieve project structure, configuration, and dev server URL
 - **`get_routes`**: Get all routes that will become entry points by scanning the filesystem. Returns routes grouped by router type (appRouter, pagesRouter). Dynamic segments appear as `[param]` or `[...slug]` patterns
 - **`get_server_action_by_id`**: Look up Server Actions by their ID to find the source file and function name
+- **`get_compilation_issues`**: Retrieve compilation warnings and errors for the whole project from the bundler. Turbopack only.
+- **`compile_route`**: Trigger on-demand compilation of a specific route without making an HTTP request to it. Useful for warming the module graph, measuring compile time, or pre-compiling routes without needing live backends. Returns any compilation issues for the route. Turbopack only.
 
 ## Using with agents
 

packages/next/errors.json

@@ -1178,5 +1178,6 @@
   "1177": "The middleware \"%s\" accepts an async API directly with the form:\n  \n  export function middleware(request, event) {\n    return NextResponse.redirect('/new-location')\n  }\n  \n  Read more: https://nextjs.org/docs/messages/middleware-new-signature\n  ",
   "1178": "The request.page has been deprecated in favour of \\`URLPattern\\`.\n  Read more: https://nextjs.org/docs/messages/middleware-request-page\n  ",
   "1179": "Invariant: %s This is a bug in Next.js.",
-  "1180": "Cookies can only be modified in a Server Action or Route Handler. Read more: https://nextjs.org/docs/app/api-reference/functions/cookies#options"
+  "1180": "Cookies can only be modified in a Server Action or Route Handler. Read more: https://nextjs.org/docs/app/api-reference/functions/cookies#options",
+  "1181": "Compilation failed but no issues were recorded"
 }

packages/next/src/server/dev/hot-reloader-turbopack.ts

@@ -89,6 +89,7 @@ import {
   formatIssue,
   isFileSystemCacheEnabledForDev,
   isWellKnownError,
+  ModuleBuildError,
   processIssues,
   renderStyledStringToErrorAnsi,
   type EntryIssuesMap,
@@ -120,6 +121,7 @@ import {
   matchNextPageBundleRequest,
 } from './hot-reloader-shared-utils'
 import { getMcpMiddleware } from '../mcp/get-mcp-middleware'
+import { formatCompilationIssues } from '../mcp/tools/utils/format-compilation-issues'
 import { handleErrorStateResponse } from '../mcp/tools/get-errors'
 import { handlePageMetadataResponse } from '../mcp/tools/get-page-metadata'
 import { setStackFrameResolver } from '../mcp/tools/utils/format-errors'
@@ -1039,6 +1041,82 @@ export async function createHotReloaderTurbopack(
               clientsWithoutHtmlRequestId.size + clientsByHtmlRequestId.size,
             getDevServerUrl: () => process.env.__NEXT_PRIVATE_ORIGIN,
             getTurbopackProject: () => project,
+            compileRoute: async (pageOpts) => {
+              // ensurePage uses findPagePathData when no definition is provided,
+              // which calls normalizePagePath("/") → "/index" then findPageFile
+              // looking for "index.tsx" — neither of which matches "page.tsx" in
+              // the app dir. Pass a synthetic definition instead.
+              //
+              // currentEntrypoints.app is keyed by originalName which includes the
+              // trailing /page or /route segment (e.g. "/page" for the root route,
+              // "/blog/[slug]/page" for a dynamic page). Use normalizeAppPath to
+              // strip that suffix and find the entry matching the user-facing route.
+              let appOriginalName: string | undefined
+              for (const [name] of currentEntrypoints.app) {
+                if (normalizeAppPath(name) === pageOpts.page) {
+                  appOriginalName = name
+                  break
+                }
+              }
+              const ensureOpts = {
+                ...pageOpts,
+                // Skip wiring HMR subscriptions: there is no client to receive
+                // updates for routes compiled this way, and these subscriptions
+                // are never unsubscribed (see TODOs in handleRouteType).
+                subscribeToChanges: false,
+                ...(appOriginalName
+                  ? {
+                      // Synthesize a definition so ensurePage bypasses findPagePathData.
+                      // Only page and bundlePath are used from the definition:
+                      // - page: the originalName used as the route key for currentEntrypoints lookup
+                      // - bundlePath: must start with "app/" to set isInsideAppDir=true
+                      definition: {
+                        page: appOriginalName,
+                        bundlePath: `app${appOriginalName}`,
+                        filename: '',
+                      } as any,
+                    }
+                  : {}),
+              }
+
+              // Snapshot the current issue maps before compilation so we can
+              // identify which entry keys were added or updated by this call.
+              // processIssues always creates a new Map() reference, so identity
+              // comparison detects changes even for re-compilations.
+              const snapshotBefore = new Map(currentEntryIssues)
+
+              // For app-page routes, processIssues is called with throwIssue=true,
+              // meaning it throws ModuleBuildError when there are compile errors—but
+              // it still writes the issues into currentEntryIssues before throwing.
+              // Catch ModuleBuildError so we can read those issues and return them
+              // as structured output rather than propagating the throw.
+              let moduleBuildError: ModuleBuildError | undefined
+              try {
+                await hotReloader.ensurePage(ensureOpts)
+              } catch (err) {
+                if (err instanceof ModuleBuildError) {
+                  moduleBuildError = err
+                } else {
+                  throw err
+                }
+              }
+
+              const rawIssues = []
+              for (const [key, issueMap] of currentEntryIssues) {
+                if (snapshotBefore.get(key) !== issueMap) {
+                  rawIssues.push(...issueMap.values())
+                }
+              }
+
+              // If ensurePage threw ModuleBuildError but we found no new issues in
+              // the map (shouldn't happen, but be safe), re-surface the original
+              // error so its message and stack are preserved.
+              if (moduleBuildError && rawIssues.length === 0) {
+                throw moduleBuildError
+              }
+
+              return formatCompilationIssues(rawIssues)
+            },
           }),
         ]
       : []),
@@ -1532,6 +1610,7 @@ export async function createHotReloaderTurbopack(
       definition,
       isApp,
       url: requestUrl,
+      subscribeToChanges = true,
     }) {
       // When there is no route definition this is an internal file not a route the user added.
       // Middleware and instrumentation are handled in turbpack-utils.ts handleEntrypoints instead.
@@ -1682,7 +1761,11 @@ export async function createHotReloaderTurbopack(
               logErrors: true,
 
               hooks: {
-                subscribeToChanges: subscribeToClientChanges,
+                // Omit subscribeToChanges to skip wiring HMR subscriptions for
+                // one-shot compilations (e.g. compile_route MCP tool).
+                ...(subscribeToChanges
+                  ? { subscribeToChanges: subscribeToClientChanges }
+                  : null),
                 handleWrittenEndpoint: (id, result, forceDeleteCache) => {
                   currentWrittenEntrypoints.set(id, result)
                   assetMapper.setPathsForKey(id, result.clientPaths)

packages/next/src/server/dev/hot-reloader-types.ts

@@ -267,13 +267,23 @@ export interface NextJsHotReloaderInterface {
     definition,
     isApp,
     url,
+    subscribeToChanges,
   }: {
     page: string
     clientOnly: boolean
     appPaths?: ReadonlyArray<string> | null
     isApp?: boolean
-    definition: RouteDefinition | undefined
+    definition?: RouteDefinition
     url?: string
+    /**
+     * Whether to wire HMR change subscriptions for the compiled entry.
+     * Defaults to true (the dev server uses these to push updates to
+     * connected browsers). Pass false for one-shot compilations (e.g.
+     * the `compile_route` MCP tool) where there is no client to receive
+     * HMR updates — without this, repeated calls leak subscriptions that
+     * keep firing on every file change for the life of the dev server.
+     */
+    subscribeToChanges?: boolean
   }): Promise<void>
   close(): void
 }

packages/next/src/server/dev/hot-reloader-webpack.ts

@@ -1690,6 +1690,7 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
               getActiveConnectionCount: () =>
                 this.webpackHotMiddleware?.getClientCount() ?? 0,
               getDevServerUrl: () => process.env.__NEXT_PRIVATE_ORIGIN,
+              // compile_route is Turbopack-only; intentionally omitted here.
             }),
           ]
         : [])
@@ -1844,6 +1845,10 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
     isApp?: boolean
     definition?: RouteDefinition
     url?: string
+    // subscribeToChanges is accepted for interface compatibility but is a
+    // no-op for webpack: webpack's on-demand entry handler does not wire HMR
+    // subscriptions per entry the way Turbopack does.
+    subscribeToChanges?: boolean
   }): Promise<void> {
     return this.hotReloaderSpan
       .traceChild('ensure-page', {

packages/next/src/server/dev/turbopack-utils.ts

@@ -134,9 +134,12 @@ export type ClientState = {
 export type ClientStateMap = WeakMap<ws, ClientState>
 
 // hooks only used by the dev server.
+// subscribeToChanges is optional: omit it to skip wiring HMR subscriptions
+// for one-shot compilations (e.g. the compile_route MCP tool) where there
+// is no client to receive updates and no unsubscribe path.
 type HandleRouteTypeHooks = {
   handleWrittenEndpoint: HandleWrittenEndpoint
-  subscribeToChanges: StartChangeSubscription
+  subscribeToChanges?: StartChangeSubscription
 }
 
 export async function handleRouteType({
@@ -167,6 +170,8 @@ export async function handleRouteType({
 
   readyIds?: ReadyIds // dev
 
+  // hooks.subscribeToChanges may be omitted to skip HMR subscriptions for
+  // one-shot compilations (e.g. the compile_route MCP tool).
   hooks?: HandleRouteTypeHooks // dev
 }) {
   switch (route.type) {
@@ -251,7 +256,7 @@ export async function handleRouteType({
         if (dev) {
           // TODO subscriptions should only be caused by the WebSocket connections
           // otherwise we don't known when to unsubscribe and this leaking
-          hooks?.subscribeToChanges(
+          hooks?.subscribeToChanges?.(
             serverKey,
             false,
             route.dataEndpoint,
@@ -270,7 +275,7 @@ export async function handleRouteType({
               }
             }
           )
-          hooks?.subscribeToChanges(
+          hooks?.subscribeToChanges?.(
             clientKey,
             false,
             route.htmlEndpoint,
@@ -287,7 +292,7 @@ export async function handleRouteType({
             }
           )
           if (entrypoints.global.document) {
-            hooks?.subscribeToChanges(
+            hooks?.subscribeToChanges?.(
               getEntryKey('pages', 'server', '_document'),
               false,
               entrypoints.global.document,
@@ -344,7 +349,7 @@ export async function handleRouteType({
       if (dev) {
         // TODO subscriptions should only be caused by the WebSocket connections
         // otherwise we don't known when to unsubscribe and this leaking
-        hooks?.subscribeToChanges(
+        hooks?.subscribeToChanges?.(
           key,
           true,
           route.rscEndpoint,
@@ -864,7 +869,7 @@ export async function handlePagesErrorRoute({
 
     const writtenEndpoint = await entrypoints.global.app.writeToDisk()
     hooks.handleWrittenEndpoint(key, writtenEndpoint, false)
-    hooks.subscribeToChanges(
+    hooks.subscribeToChanges?.(
       key,
       false,
       entrypoints.global.app,
@@ -893,7 +898,7 @@ export async function handlePagesErrorRoute({
 
     const writtenEndpoint = await entrypoints.global.document.writeToDisk()
     hooks.handleWrittenEndpoint(key, writtenEndpoint, false)
-    hooks.subscribeToChanges(
+    hooks.subscribeToChanges?.(
       key,
       false,
       entrypoints.global.document,
@@ -919,7 +924,7 @@ export async function handlePagesErrorRoute({
 
     const writtenEndpoint = await entrypoints.global.error.writeToDisk()
     hooks.handleWrittenEndpoint(key, writtenEndpoint, false)
-    hooks.subscribeToChanges(
+    hooks.subscribeToChanges?.(
       key,
       false,
       entrypoints.global.error,

packages/next/src/server/mcp/get-or-create-mcp-server.ts

@@ -6,9 +6,11 @@ import { registerGetLogsTool } from './tools/get-logs'
 import { registerGetActionByIdTool } from './tools/get-server-action-by-id'
 import { registerGetRoutesTool } from './tools/get-routes'
 import { registerGetCompilationIssuesTool } from './tools/get-compilation-issues'
+import { registerCompileRouteTool } from './tools/compile-route'
 import type { HmrMessageSentToBrowser } from '../dev/hot-reloader-types'
 import type { NextConfigComplete } from '../config-shared'
 import type { Project } from '../../build/swc/types'
+import type { FormattedIssue } from './tools/utils/format-compilation-issues'
 
 export interface McpServerOptions {
   projectPath: string
@@ -20,6 +22,10 @@ export interface McpServerOptions {
   getActiveConnectionCount: () => number
   getDevServerUrl: () => string | undefined
   getTurbopackProject?: () => Project | undefined
+  compileRoute?: (opts: {
+    page: string
+    clientOnly: boolean
+  }) => Promise<FormattedIssue[]>
 }
 
 let mcpServer: McpServer | undefined
@@ -62,5 +68,9 @@ export const getOrCreateMcpServer = (options: McpServerOptions) => {
     registerGetCompilationIssuesTool(mcpServer, options.getTurbopackProject)
   }
 
+  if (options.compileRoute) {
+    registerCompileRouteTool(mcpServer, options.compileRoute)
+  }
+
   return mcpServer
 }

packages/next/src/server/mcp/tools/compile-route.ts

@@ -0,0 +1,67 @@
+/**
+ * MCP tool for compiling a specific route via the on-demand entry handler.
+ *
+ * Triggers on-demand compilation so the route's assets are built without making an
+ * HTTP request to the route. This is the same call path the dev server uses
+ * when a route is first navigated to, making it useful for warming the module
+ * graph, measuring compile time, or pre-compiling routes for memory
+ * benchmarking without requiring live backends.
+ */
+import type { McpServer } from 'next/dist/compiled/@modelcontextprotocol/sdk/server/mcp'
+import { mcpTelemetryTracker } from '../mcp-telemetry-tracker'
+import type { FormattedIssue } from './utils/format-compilation-issues'
+import z from 'next/dist/compiled/zod'
+
+export function registerCompileRouteTool(
+  server: McpServer,
+  compileRoute: (opts: {
+    page: string
+    clientOnly: boolean
+  }) => Promise<FormattedIssue[]>
+) {
+  server.registerTool(
+    'compile_route',
+    {
+      description:
+        'Compile a specific route (page or API route) without making an HTTP request. ' +
+        'Triggers the same on-demand compilation the dev server uses when a route is first visited. ' +
+        'Useful for warming up the module graph, measuring compile time, or pre-compiling routes for memory benchmarking. ' +
+        'Returns { page, issues } on success where issues contains any compilation warnings or errors. ' +
+        'Returns an error if the route does not exist.',
+      inputSchema: {
+        page: z
+          .string()
+          .describe(
+            'The route specifier, e.g. "/", "/about", "/api/hello", "/blog/[slug]"'
+          ),
+      },
+    },
+    async ({ page }) => {
+      mcpTelemetryTracker.recordToolCall('mcp/compile_route')
+      try {
+        // clientOnly: false ensures both server and client bundles are compiled,
+        // matching what happens on a real page navigation.
+        const issues = await compileRoute({ page, clientOnly: false })
+        return {
+          content: [{ type: 'text', text: JSON.stringify({ page, issues }) }],
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        const notFound =
+          error instanceof Error &&
+          (error as NodeJS.ErrnoException).code === 'ENOENT'
+        return {
+          isError: true,
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify(
+                notFound ? { page, notFound: true } : { page, error: message }
+              ),
+            },
+          ],
+        }
+      }
+    }
+  )
+}

packages/next/src/telemetry/events/build.ts

@@ -260,6 +260,7 @@ export type McpToolName =
   | 'mcp/get_routes'
   | 'mcp/get_server_action_by_id'
   | 'mcp/get_compilation_issues'
+  | 'mcp/compile_route'
 
 export type EventMcpToolUsage = {
   toolName: McpToolName