Unverified Commit f49ed227 authored by Luke Sandberg's avatar Luke Sandberg Committed by GitHub

Add MCP `compile_route` tool (#93337)

### What?

Adds a `compile_route` MCP tool that triggers on-demand compilation of a
specific route (app or pages) without issuing an HTTP request, and
returns any compilation issues.

### Why?

Coding agents and benchmarking workflows need a way to warm the module
graph or measure compile time for a route without standing up a live
backend to satisfy the request. The existing path — hitting the URL —
requires the route's runtime dependencies to be available and couples
compile timing to request handling.

### How?

- New tool `mcp/compile_route` registered in
`get-or-create-mcp-server.ts`, backed by a `compileRoute({ page,
clientOnly })` callback plumbed from the Turbopack hot reloader
- Reuses the dev server's existing on-demand entry path (`ensurePage` /
`handleRouteType`), so the call path matches a first navigation.
- Adds a `subscribeToChanges` opt-out on `ensurePage` and threads it
through `handleRouteType` / `handlePagesErrorRoute`. One-shot MCP
compilations skip HMR subscription wiring — without this, each call
would leak a subscription that fires on every subsequent file change for
the life of the dev server.
- Telemetry: registers `mcp/compile_route` in the `McpToolName` union.
- e2e test in
`test/development/mcp-server/mcp-server-compile-route.test.ts`.

<!-- NEXT_JS_LLM_PR -->
parent 2af85b58
......@@ -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. Accepts either a `routeSpecifier` (e.g. `/blog/[slug]`, as returned by `get_routes`) or a `path` (e.g. `/blog/hello-world`) which is resolved to the matching route using the dev router's live route table. Returns any compilation issues for the route. Turbopack only.
## Using with agents
......
......@@ -1252,5 +1252,8 @@
"1251": "Route \"%s\": Next.js encountered runtime data during the initial render or a navigation.\\n\\n\\`cookies()\\`, \\`headers()\\`, \\`params\\`, or \\`searchParams\\` accessed outside of \\`<Suspense>\\` prevents the route from being prerendered or the navigation from being instant, leading to a slower user experience.\\n\\nWays to fix this:\\n - Provide a placeholder with \\`<Suspense fallback={...}>\\` around the data access\\n - Use \\`generateStaticParams\\` to make route params static\\n - Set \\`export const instant = false\\` to allow a blocking route\\n\\nLearn more: https://nextjs.org/docs/messages/blocking-route",
"1252": "\\`experimental.cssChunking: \"graph\"\\` is only supported with Turbopack. Please remove the option or run Next.js with Turbopack in %s.",
"1253": "\\`experimental.cssChunking: \"strict\"\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s.",
"1254": "\\`experimental.cssChunking: false\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s."
"1254": "\\`experimental.cssChunking: false\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s.",
"1255": "Compilation failed but no issues were recorded",
"1256": "no route matched for path \"%s\"",
"1257": "compileRoute: either routeSpecifier or path is required"
}
......@@ -59,6 +59,7 @@ import {
processTopLevelIssues,
printNonFatalIssue,
normalizedPageToTurbopackStructureRoute,
type StartChangeSubscription,
} from './turbopack-utils'
import {
propagateServerField,
......@@ -89,6 +90,7 @@ import {
formatIssue,
isFileSystemCacheEnabledForDev,
isWellKnownError,
ModuleBuildError,
processIssues,
renderStyledStringToErrorAnsi,
type EntryIssuesMap,
......@@ -120,6 +122,8 @@ import {
matchNextPageBundleRequest,
} from './hot-reloader-shared-utils'
import { getMcpMiddleware } from '../mcp/get-mcp-middleware'
import { formatCompilationIssues } from '../mcp/tools/utils/format-compilation-issues'
import { resolvePathToRoute } from '../mcp/tools/utils/resolve-path-to-route'
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 +1043,116 @@ export async function createHotReloaderTurbopack(
clientsWithoutHtmlRequestId.size + clientsByHtmlRequestId.size,
getDevServerUrl: () => process.env.__NEXT_PRIVATE_ORIGIN,
getTurbopackProject: () => project,
compileRoute: async ({ routeSpecifier, path }) => {
// Resolve the caller's input to a concrete route specifier. The
// path-mode branch reuses the dev router's own live route table
// (opts.fsChecker) — the same one resolve-routes.ts consults on
// every incoming HTTP request — so first-match ordering and live
// route updates are inherited for free.
let page: string
if (routeSpecifier != null) {
page = routeSpecifier
} else if (path != null) {
const resolved = resolvePathToRoute(path, {
appFiles: opts.fsChecker.appFiles,
pageFiles: opts.fsChecker.pageFiles,
dynamicRoutes: opts.fsChecker.getDynamicRoutes(),
})
if ('notFound' in resolved) {
const err: NodeJS.ErrnoException = new Error(
`no route matched for path "${resolved.pathname}"`
)
err.code = 'ENOENT'
throw err
}
page = resolved.routeSpecifier
} else {
// Tool handler rejects the empty case; defend the boundary.
throw new Error(
'compileRoute: either routeSpecifier or path is required'
)
}
// 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 extraOptions: object | undefined = undefined
for (const [name] of currentEntrypoints.app) {
if (normalizeAppPath(name) === page) {
extraOptions = {
// 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: name,
bundlePath: `app${name}`,
filename: '',
} as any,
}
break
}
}
const ensureOpts = {
page,
// Compile both server and client bundles, matching what happens
// on a real page navigation. Client-only compilation isn't a
// meaningful MCP use case so we don't expose it as a knob.
clientOnly: false,
// 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,
...extraOptions,
}
// 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 {
routeSpecifier: page,
issues: formatCompilationIssues(rawIssues),
}
},
}),
]
: []),
......@@ -1532,6 +1646,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 +1797,11 @@ export async function createHotReloaderTurbopack(
logErrors: true,
hooks: {
subscribeToChanges: subscribeToClientChanges,
// Pass a no-o subscribeToChanges to skip wiring HMR subscriptions for
// one-shot compilations (e.g. compile_route MCP tool).
subscribeToChanges: subscribeToChanges
? subscribeToClientChanges
: ((async () => {}) as StartChangeSubscription),
handleWrittenEndpoint: (id, result, forceDeleteCache) => {
currentWrittenEntrypoints.set(id, result)
assetMapper.setPathsForKey(id, result.clientPaths)
......
......@@ -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
}
......@@ -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', {
......
......@@ -135,6 +135,9 @@ 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
......@@ -168,6 +171,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) {
......
......@@ -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: {
routeSpecifier?: string
path?: string
}) => Promise<{ routeSpecifier: string; issues: 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
}
/**
* 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: {
routeSpecifier?: string
path?: string
}) => Promise<{ routeSpecifier: string; issues: 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 { routeSpecifier, issues } on success where routeSpecifier is the resolved route and issues contains any compilation warnings or errors. ' +
'Returns an error if no matching route exists.',
inputSchema: {
routeSpecifier: z
.string()
.describe(
'A route specifier as returned by the get_routes tool (e.g. "/", "/blog/[slug]", "/api/users/[id]"). ' +
'Mutually exclusive with `path`; provide exactly one.'
)
.optional(),
path: z
.string()
.describe(
'A URL path on this site (e.g. "/blog/hello-world", "/docs/a/b/c"). ' +
'Query strings are allowed and ignored. Do not include scheme/host/port. ' +
"The path is resolved to its matching route specifier using the dev router's live route table. " +
'Mutually exclusive with `routeSpecifier`; provide exactly one.'
)
.optional(),
},
},
async ({ routeSpecifier, path }) => {
mcpTelemetryTracker.recordToolCall('mcp/compile_route')
if ((routeSpecifier == null) === (path == null)) {
return {
isError: true,
content: [
{
type: 'text',
text: JSON.stringify({
error: 'Provide exactly one of `routeSpecifier` or `path`.',
}),
},
],
}
}
try {
const { routeSpecifier: resolvedRouteSpecifier, issues } =
await compileRoute({ routeSpecifier, path })
return {
content: [
{
type: 'text',
text: JSON.stringify({
routeSpecifier: resolvedRouteSpecifier,
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
? { notFound: true, input: path ?? routeSpecifier }
: { input: path ?? routeSpecifier, error: message }
),
},
],
}
}
}
)
}
/**
* Resolves a URL path (e.g. "/blog/hello-world") to its matching Next.js route
* specifier (e.g. "/blog/[slug]") using the dev router's own live route table.
*
* The `matchers` argument is a thin view of `fsChecker` from the router-server
* process — the same data structure `resolve-routes.ts` iterates on every
* incoming HTTP request — so first-match ordering and live route updates are
* inherited for free.
*/
export interface RouteMatcherView {
appFiles: ReadonlySet<string>
pageFiles: ReadonlySet<string>
dynamicRoutes: ReadonlyArray<{
page: string
match: (pathname: string) => false | object
}>
}
export function resolvePathToRoute(
path: string,
matchers: RouteMatcherView
): { routeSpecifier: string } | { notFound: true; pathname: string } {
let pathname = path
const q = pathname.indexOf('?')
if (q >= 0) pathname = pathname.slice(0, q)
const h = pathname.indexOf('#')
if (h >= 0) pathname = pathname.slice(0, h)
if (!pathname.startsWith('/')) pathname = '/' + pathname
if (pathname !== '/' && pathname.endsWith('/')) {
pathname = pathname.slice(0, -1)
}
if (matchers.appFiles.has(pathname) || matchers.pageFiles.has(pathname)) {
return { routeSpecifier: pathname }
}
for (const route of matchers.dynamicRoutes) {
// Skip SSG/SSP data-route variants prepended by setup-dev-bundler.
if (route.page.startsWith('/_next/data/')) continue
if (route.match(pathname)) {
return { routeSpecifier: route.page }
}
}
return { notFound: true, pathname }
}
......@@ -280,6 +280,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
......
import path from 'path'
import { nextTestSetup } from 'e2e-utils'
async function callMcpTool(
url: string,
toolName: string,
args: Record<string, unknown> = {}
): Promise<unknown> {
const response = await fetch(`${url}/_next/mcp`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'application/json, text/event-stream',
},
body: JSON.stringify({
jsonrpc: '2.0',
id: toolName + '-' + Date.now(),
method: 'tools/call',
params: { name: toolName, arguments: args },
}),
})
const text = await response.text()
const match = text.match(/data: ({.*})/s)
expect(match).toBeTruthy()
const envelope = JSON.parse(match![1])
return JSON.parse(envelope.result?.content?.[0]?.text)
}
// compile_route is Turbopack-only; it is not registered on webpack dev servers.
;(process.env.IS_TURBOPACK_TEST ? describe : describe.skip)(
'mcp-server compile_route tool',
() => {
const { next, skipped } = nextTestSetup({
files: path.join(__dirname, 'fixtures', 'dynamic-routes-app'),
})
if (skipped) {
return
}
describe('routeSpecifier input', () => {
it('should compile a valid app router root route', async () => {
const result = await callMcpTool(next.url, 'compile_route', {
routeSpecifier: '/',
})
expect(result).toMatchObject({ routeSpecifier: '/', issues: [] })
})
it('should compile a valid dynamic app router route', async () => {
const result = await callMcpTool(next.url, 'compile_route', {
routeSpecifier: '/blog/[slug]',
})
expect(result).toMatchObject({
routeSpecifier: '/blog/[slug]',
issues: [],
})
})
it('should compile a valid pages router route', async () => {
const result = await callMcpTool(next.url, 'compile_route', {
routeSpecifier: '/about',
})
expect(result).toMatchObject({ routeSpecifier: '/about', issues: [] })
})
it('should compile a valid app router API route', async () => {
const result = await callMcpTool(next.url, 'compile_route', {
routeSpecifier: '/api/users/[id]',
})
expect(result).toMatchObject({
routeSpecifier: '/api/users/[id]',
issues: [],
})
})
it('should compile a valid pages router API route', async () => {
const result = await callMcpTool(next.url, 'compile_route', {
routeSpecifier: '/api/legacy',
})
expect(result).toMatchObject({
routeSpecifier: '/api/legacy',
issues: [],
})
})
it('should return notFound for a non-existent specifier', async () => {
const result = (await callMcpTool(next.url, 'compile_route', {
routeSpecifier: '/does-not-exist',
})) as any
expect(result).toMatchObject({
notFound: true,
input: '/does-not-exist',
})
})
})
describe('path input', () => {
it('should resolve a static app route path', async () => {
const result = await callMcpTool(next.url, 'compile_route', {
path: '/',
})
expect(result).toMatchObject({ routeSpecifier: '/', issues: [] })
})
it('should resolve a dynamic app route path', async () => {
const result = await callMcpTool(next.url, 'compile_route', {
path: '/blog/hello-world',
})
expect(result).toMatchObject({
routeSpecifier: '/blog/[slug]',
issues: [],
})
})
it('should resolve a catchall app route path', async () => {
const result = await callMcpTool(next.url, 'compile_route', {
path: '/docs/a/b/c',
})
expect(result).toMatchObject({
routeSpecifier: '/docs/[...slug]',
issues: [],
})
})
it('should strip query string before matching', async () => {
const result = await callMcpTool(next.url, 'compile_route', {
path: '/products/42?ref=x',
})
expect(result).toMatchObject({
routeSpecifier: '/products/[id]',
issues: [],
})
})
it('should resolve a pages router dynamic path', async () => {
const result = await callMcpTool(next.url, 'compile_route', {
path: '/posts/7',
})
expect(result).toMatchObject({
routeSpecifier: '/posts/[id]',
issues: [],
})
})
it('should resolve an app router API path', async () => {
const result = await callMcpTool(next.url, 'compile_route', {
path: '/api/users/42',
})
expect(result).toMatchObject({
routeSpecifier: '/api/users/[id]',
issues: [],
})
})
it('should resolve a static pages router path', async () => {
const result = await callMcpTool(next.url, 'compile_route', {
path: '/about',
})
expect(result).toMatchObject({ routeSpecifier: '/about', issues: [] })
})
it('should strip a trailing slash before matching', async () => {
const result = await callMcpTool(next.url, 'compile_route', {
path: '/about/',
})
expect(result).toMatchObject({ routeSpecifier: '/about', issues: [] })
})
it('should return notFound when no route matches', async () => {
const result = (await callMcpTool(next.url, 'compile_route', {
path: '/nope/x',
})) as any
expect(result).toMatchObject({ notFound: true, input: '/nope/x' })
})
})
describe('input validation', () => {
it('should error when both routeSpecifier and path are provided', async () => {
const result = (await callMcpTool(next.url, 'compile_route', {
routeSpecifier: '/',
path: '/',
})) as any
expect(result).toMatchObject({
error: expect.stringContaining('exactly one'),
})
})
it('should error when neither routeSpecifier nor path is provided', async () => {
const result = (await callMcpTool(next.url, 'compile_route', {})) as any
expect(result).toMatchObject({
error: expect.stringContaining('exactly one'),
})
})
})
}
)
// Compilation errors don't throw from ensurePage — they are collected from
// Turbopack's per-entry issue map and returned directly in the compile_route
// response, so no second round-trip to get_compilation_issues is needed.
;(process.env.IS_TURBOPACK_TEST ? describe : describe.skip)(
'mcp-server compile_route with compilation errors',
() => {
const { next, skipped } = nextTestSetup({
files: path.join(__dirname, 'fixtures', 'compilation-errors-app'),
})
if (skipped) {
return
}
it('should return compilation issues inline in the response', async () => {
const result = (await callMcpTool(next.url, 'compile_route', {
routeSpecifier: '/missing-module',
})) as {
routeSpecifier: string
issues: Array<{ severity: string; filePath: string; title: string }>
}
expect(result.routeSpecifier).toBe('/missing-module')
expect(result.issues.length).toBeGreaterThan(0)
const moduleNotFound = result.issues.find(
(issue) =>
(issue.severity === 'error' || issue.severity === 'fatal') &&
(issue.filePath.includes('missing-module') ||
issue.title.includes('non-existent-module'))
)
expect(moduleNotFound).toBeDefined()
})
}
)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment