expand to support url shaped strings not just specifiers

Author: lukesandberg

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

@@ -87,7 +87,7 @@ Through `next-devtools-mcp`, agents can use the following tools:
 - **`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.
+- **`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
 

packages/next/errors.json

@@ -1179,5 +1179,7 @@
   "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",
-  "1181": "Compilation failed but no issues were recorded"
+  "1181": "Compilation failed but no issues were recorded",
+  "1182": "no route matched for path \"%s\"",
+  "1183": "compileRoute: either routeSpecifier or path is required"
 }

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

@@ -122,6 +122,7 @@ import {
 } 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'
@@ -1041,7 +1042,36 @@ export async function createHotReloaderTurbopack(
               clientsWithoutHtmlRequestId.size + clientsByHtmlRequestId.size,
             getDevServerUrl: () => process.env.__NEXT_PRIVATE_ORIGIN,
             getTurbopackProject: () => project,
-            compileRoute: async (pageOpts) => {
+            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
@@ -1053,13 +1083,17 @@ export async function createHotReloaderTurbopack(
               // 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) {
+                if (normalizeAppPath(name) === page) {
                   appOriginalName = name
                   break
                 }
               }
               const ensureOpts = {
-                ...pageOpts,
+                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).
@@ -1115,7 +1149,10 @@ export async function createHotReloaderTurbopack(
                 throw moduleBuildError
               }
 
-              return formatCompilationIssues(rawIssues)
+              return {
+                routeSpecifier: page,
+                issues: formatCompilationIssues(rawIssues),
+              }
             },
           }),
         ]

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

@@ -23,9 +23,9 @@ export interface McpServerOptions {
   getDevServerUrl: () => string | undefined
   getTurbopackProject?: () => Project | undefined
   compileRoute?: (opts: {
-    page: string
-    clientOnly: boolean
-  }) => Promise<FormattedIssue[]>
+    routeSpecifier?: string
+    path?: string
+  }) => Promise<{ routeSpecifier: string; issues: FormattedIssue[] }>
 }
 
 let mcpServer: McpServer | undefined

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

@@ -15,9 +15,9 @@ import z from 'next/dist/compiled/zod'
 export function registerCompileRouteTool(
   server: McpServer,
   compileRoute: (opts: {
-    page: string
-    clientOnly: boolean
-  }) => Promise<FormattedIssue[]>
+    routeSpecifier?: string
+    path?: string
+  }) => Promise<{ routeSpecifier: string; issues: FormattedIssue[] }>
 ) {
   server.registerTool(
     'compile_route',
@@ -26,24 +26,57 @@ export function registerCompileRouteTool(
         '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.',
+        '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: {
-        page: z
+        routeSpecifier: z
           .string()
           .describe(
-            'The route specifier, e.g. "/", "/about", "/api/hello", "/blog/[slug]"'
-          ),
+            '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 ({ page }) => {
+    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 {
-        // 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 })
+        const { routeSpecifier: resolvedRouteSpecifier, issues } =
+          await compileRoute({ routeSpecifier, path })
         return {
-          content: [{ type: 'text', text: JSON.stringify({ page, issues }) }],
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({
+                routeSpecifier: resolvedRouteSpecifier,
+                issues,
+              }),
+            },
+          ],
         }
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error)
@@ -56,7 +89,9 @@ export function registerCompileRouteTool(
             {
               type: 'text',
               text: JSON.stringify(
-                notFound ? { page, notFound: true } : { page, error: message }
+                notFound
+                  ? { notFound: true, input: path ?? routeSpecifier }
+                  : { input: path ?? routeSpecifier, error: message }
               ),
             },
           ],

packages/next/src/server/mcp/tools/utils/resolve-path-to-route.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 }
+}