[MCP] Add manual compile mode to pause Turbopack scheduling during batched edits

Author: gaojude

crates/next-napi-bindings/src/next_api/project.rs

@@ -2134,6 +2134,31 @@ pub fn project_update_info_subscribe(
     Ok(())
 }
 
+/// Pause compilation. Task scheduling is deferred — file changes still mark
+/// tasks dirty, but no recomputation happens until `project_compile_and_resume`
+/// is called.
+#[napi]
+pub fn project_pause_compilation(
+    #[napi(ts_arg_type = "{ __napiType: \"Project\" }")] project: External<ProjectInstance>,
+) -> napi::Result<()> {
+    project.turbopack_ctx.turbo_tasks().pause_compilation();
+    Ok(())
+}
+
+/// Compile all deferred tasks in one batch, wait for the compilation cycle to
+/// finish, then resume normal scheduling.
+#[napi]
+pub async fn project_compile_and_resume(
+    #[napi(ts_arg_type = "{ __napiType: \"Project\" }")] project: External<ProjectInstance>,
+) -> napi::Result<()> {
+    project
+        .turbopack_ctx
+        .turbo_tasks()
+        .compile_and_resume()
+        .await;
+    Ok(())
+}
+
 /// Subscribes to all compilation events that are not cached like timing and progress information.
 #[napi]
 pub fn project_compilation_events_subscribe(

packages/next/src/build/swc/generated-native.d.ts

@@ -344,6 +344,21 @@ export declare function projectUpdate(
 export declare function projectInvalidateFileSystemCache(project: {
   __napiType: 'Project'
 }): Promise<void>
+/**
+ * Pause compilation. Task scheduling is deferred — file changes still mark
+ * tasks dirty, but no recomputation happens until `projectCompileAndResume`
+ * is called.
+ */
+export declare function projectPauseCompilation(project: {
+  __napiType: 'Project'
+}): void
+/**
+ * Compile all deferred tasks in one batch, wait for the compilation cycle to
+ * finish, then resume normal scheduling.
+ */
+export declare function projectCompileAndResume(project: {
+  __napiType: 'Project'
+}): Promise<void>
 /**
  * Runs exit handlers for the project registered using the [`ExitHandler`] API.
  *

packages/next/src/build/swc/index.ts

@@ -843,6 +843,14 @@ function bindingToApi(
       return binding.projectInvalidateFileSystemCache(this._nativeProject)
     }
 
+    pauseCompilation(): void {
+      binding.projectPauseCompilation(this._nativeProject)
+    }
+
+    compileAndResume(): Promise<void> {
+      return binding.projectCompileAndResume(this._nativeProject)
+    }
+
     shutdown(): Promise<void> {
       return binding.projectShutdown(this._nativeProject)
     }

packages/next/src/build/swc/types.ts

@@ -333,6 +333,10 @@ export interface Project {
 
   invalidateFileSystemCache(): Promise<void>
 
+  pauseCompilation(): void
+
+  compileAndResume(): Promise<void>
+
   shutdown(): Promise<void>
 
   onExit(): Promise<void>

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

@@ -1050,6 +1050,12 @@ export async function createHotReloaderTurbopack(
               clientsWithoutHtmlRequestId.size + clientsByHtmlRequestId.size,
             getDevServerUrl: () => process.env.__NEXT_PRIVATE_ORIGIN,
             getTurbopackProject: () => project,
+            pauseCompilation: () => {
+              project.pauseCompilation()
+            },
+            compileAndResume: async () => {
+              await project.compileAndResume()
+            },
           }),
         ]
       : []),

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

@@ -1699,6 +1699,8 @@ export default class HotReloaderWebpack implements NextJsHotReloaderInterface {
               getActiveConnectionCount: () =>
                 this.webpackHotMiddleware?.getClientCount() ?? 0,
               getDevServerUrl: () => process.env.__NEXT_PRIVATE_ORIGIN,
+              pauseCompilation: () => {},
+              compileAndResume: async () => {},
             }),
           ]
         : [])

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

@@ -6,6 +6,10 @@ 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 {
+  registerPauseCompilationTool,
+  registerCompileAndResumeTool,
+} from './tools/manual-compile'
 import type { HmrMessageSentToBrowser } from '../dev/hot-reloader-types'
 import type { NextConfigComplete } from '../config-shared'
 import type { Project } from '../../build/swc/types'
@@ -20,6 +24,8 @@ export interface McpServerOptions {
   getActiveConnectionCount: () => number
   getDevServerUrl: () => string | undefined
   getTurbopackProject?: () => Project | undefined
+  pauseCompilation: () => void
+  compileAndResume: () => Promise<void>
 }
 
 let mcpServer: McpServer | undefined
@@ -62,5 +68,8 @@ export const getOrCreateMcpServer = (options: McpServerOptions) => {
     registerGetCompilationIssuesTool(mcpServer, options.getTurbopackProject)
   }
 
+  registerPauseCompilationTool(mcpServer, options.pauseCompilation)
+  registerCompileAndResumeTool(mcpServer, options.compileAndResume)
+
   return mcpServer
 }

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

@@ -0,0 +1,54 @@
+import type { McpServer } from 'next/dist/compiled/@modelcontextprotocol/sdk/server/mcp'
+import { mcpTelemetryTracker } from '../mcp-telemetry-tracker'
+
+export function registerPauseCompilationTool(
+  server: McpServer,
+  pauseCompilation: () => void
+) {
+  server.registerTool(
+    'pause_compilation',
+    {
+      description:
+        'Pause compilation. File watching continues, but compilation is deferred until compile_and_resume is called. Use this at the start of an editing session to prevent wasted intermediate compilations and ephemeral errors.',
+      inputSchema: {},
+    },
+    async () => {
+      mcpTelemetryTracker.recordToolCall('mcp/pause_compilation')
+      pauseCompilation()
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ status: 'compilation_paused' }),
+          },
+        ],
+      }
+    }
+  )
+}
+
+export function registerCompileAndResumeTool(
+  server: McpServer,
+  compileAndResume: () => Promise<void>
+) {
+  server.registerTool(
+    'compile_and_resume',
+    {
+      description:
+        'Compile all accumulated file changes in a single batch, then resume normal compilation. Waits for compilation to complete before returning. No-op if compilation is not paused.',
+      inputSchema: {},
+    },
+    async () => {
+      mcpTelemetryTracker.recordToolCall('mcp/compile_and_resume')
+      await compileAndResume()
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ status: 'compiled_and_resumed' }),
+          },
+        ],
+      }
+    }
+  )
+}

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

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

test/development/mcp-server/fixtures/manual-compile-app/app/layout.tsx

@@ -0,0 +1,11 @@
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  )
+}