feat(@angular/cli): Split "driver" MCP tool into start/stop/wait.

Author: amishne

packages/angular/cli/src/commands/mcp/dev-server.ts

@@ -0,0 +1,135 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { ChildProcess } from 'child_process';
+import { Host } from './host';
+
+const BUILD_SUCCEEDED_MESSAGE = 'Application bundle generation complete.';
+const BUILD_FAILED_MESSAGE = 'Application bundle generation failed.';
+const WAITING_FOR_CHANGES_MESSAGE = 'Watch mode enabled. Watching for file changes...';
+const CHANGES_DETECTED_START_MESSAGE = '❯ Changes detected. Rebuilding...';
+const CHANGES_DETECTED_SUCCESS_MESSAGE = '✔ Changes detected. Rebuilding...';
+
+const BUILD_START_MESSAGES = [CHANGES_DETECTED_START_MESSAGE];
+const BUILD_END_MESSAGES = [
+  BUILD_SUCCEEDED_MESSAGE,
+  BUILD_FAILED_MESSAGE,
+  WAITING_FOR_CHANGES_MESSAGE,
+  CHANGES_DETECTED_SUCCESS_MESSAGE,
+];
+
+export type BuildStatus = 'success' | 'failure' | 'unknown';
+
+/**
+ * An Angular development server managed by the MCP server.
+ */
+export interface DevServer {
+  /**
+   * Launches the dev server and returns immediately.
+   *
+   * Throws if this server is already running.
+   */
+  start(): void;
+
+  /**
+   * If the dev server is running, stops it.
+   */
+  stop(): void;
+
+  /**
+   * Gets all the server logs so far (stdout + stderr).
+   */
+  getServerLogs(): string[];
+
+  /**
+   * Gets all the server logs from the latest build.
+   */
+  getMostRecentBuild(): { status: BuildStatus; logs: string[] };
+
+  /**
+   * Whether the dev server is currently being built, or is awaiting further changes.
+   */
+  isBuilding(): boolean;
+}
+
+/**
+ * A local Angular development server managed by the MCP server.
+ */
+export class LocalDevServer implements DevServer {
+  readonly host: Host;
+  readonly port?: number;
+  readonly project?: string;
+
+  private devServerProcess: ChildProcess | null = null;
+  private serverLogs: string[] = [];
+  private buildInProgress = false;
+  private latestBuildLogStartIndex = 0;
+  private latestBuildLogEndIndex = 0;
+  private latestBuildStatus?: BuildStatus;
+
+  constructor({ host, port, project }: { host: Host; port?: number; project?: string }) {
+    this.host = host;
+    this.project = project;
+    this.port = port;
+  }
+
+  start() {
+    if (this.devServerProcess) {
+      throw Error('Dev server already started.');
+    }
+
+    const args = ['serve'];
+    if (this.project) {
+      args.push(this.project);
+    }
+    if (this.port) {
+      args.push(`--port=${this.port}`);
+    }
+
+    this.devServerProcess = this.host.spawn('ng', args, { stdio: 'pipe' });
+    this.devServerProcess.stdout?.on('data', (data) => {
+      this.serverLogs.push(data.toString());
+    });
+    this.devServerProcess.stderr?.on('data', (data) => {
+      this.serverLogs.push(data.toString());
+    });
+  }
+
+  private addLog(log: string) {
+    this.serverLogs.push(log);
+
+    if (BUILD_START_MESSAGES.some((message) => log.startsWith(message))) {
+      this.buildInProgress = true;
+      this.latestBuildLogStartIndex = this.serverLogs.length;
+    } else if (BUILD_END_MESSAGES.some((message) => log.startsWith(message))) {
+      this.buildInProgress = false;
+      this.latestBuildLogEndIndex = this.serverLogs.length;
+      this.latestBuildStatus = log.startsWith(BUILD_FAILED_MESSAGE) ? 'success' : 'failure';
+    }
+  }
+
+  stop() {
+    this.devServerProcess?.kill();
+    this.devServerProcess = null;
+  }
+
+  getServerLogs(): string[] {
+    return [...this.serverLogs];
+  }
+
+  getMostRecentBuild() {
+    return {
+      status: this.latestBuildStatus ?? 'unknown',
+      logs: this.serverLogs.slice(this.latestBuildLogStartIndex, this.latestBuildLogEndIndex),
+    };
+  }
+
+  isBuilding() {
+    return this.buildInProgress;
+  }
+}

packages/angular/cli/src/commands/mcp/mcp-server.ts

@@ -19,8 +19,10 @@ import { FIND_EXAMPLE_TOOL } from './tools/examples';
 import { MODERNIZE_TOOL } from './tools/modernize';
 import { ZONELESS_MIGRATION_TOOL } from './tools/onpush-zoneless-migration/zoneless-migration';
 import { LIST_PROJECTS_TOOL } from './tools/projects';
-import { SERVE_TOOL } from './tools/serve';
+import { START_DEVSERVER_TOOL } from './tools/start-devserver';
+import { STOP_DEVSERVER_TOOL } from './tools/stop-devserver';
 import { AnyMcpToolDeclaration, registerTools } from './tools/tool-registry';
+import { WAIT_FOR_DEVSERVER_BUILD_TOOL } from './tools/wait-for-devserver-build';
 
 /**
  * The set of tools that are enabled by default for the MCP server.
@@ -35,11 +37,20 @@ const STABLE_TOOLS = [
   LIST_PROJECTS_TOOL,
 ] as const;
 
+/**
+ * Tools to manage devservers. Should be bundled together.
+ */
+const SERVE_TOOLS = [START_DEVSERVER_TOOL, STOP_DEVSERVER_TOOL, WAIT_FOR_DEVSERVER_BUILD_TOOL];
+
 /**
  * The set of tools that are available but not enabled by default.
  * These tools are considered experimental and may have limitations.
  */
-export const EXPERIMENTAL_TOOLS = [MODERNIZE_TOOL, ZONELESS_MIGRATION_TOOL, SERVE_TOOL] as const;
+export const EXPERIMENTAL_TOOLS = [
+  MODERNIZE_TOOL,
+  ZONELESS_MIGRATION_TOOL,
+  ...SERVE_TOOLS,
+] as const;
 
 export async function createMcpServer(
   options: {

packages/angular/cli/src/commands/mcp/tools/build.ts

@@ -8,6 +8,7 @@
 
 import { z } from 'zod';
 import { CommandError, Host, LocalWorkspaceHost } from '../host';
+import { createStructureContentOutput } from '../utils';
 import { McpToolContext, McpToolDeclaration, declareTool } from './tool-registry';
 
 const CONFIGURATIONS = {

packages/angular/cli/src/commands/mcp/tools/serve.ts

@@ -0,0 +1,83 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+import { z } from 'zod';
+import { DevServer, LocalDevServer } from '../dev-server';
+import { Host, LocalWorkspaceHost } from '../host';
+import { createStructureContentOutput } from '../utils';
+import { McpToolContext, McpToolDeclaration, declareTool } from './tool-registry';
+
+const startDevserverToolInputSchema = z.object({
+  project: z
+    .string()
+    .optional()
+    .describe(
+      'Which project to serve in a monorepo context. If not provided, serves the default project.',
+    ),
+  port: z.number().optional().describe('Port to listen on.'),
+});
+
+export type StartDevserverToolInput = z.infer<typeof startDevserverToolInputSchema>;
+
+const startDevserverToolOutputSchema = z.object({
+  message: z.string().describe('A message indicating the result of the operation.'),
+});
+
+export type StartDevserverToolOutput = z.infer<typeof startDevserverToolOutputSchema>;
+
+export const DEFAULT_PROJECT_KEY = '<default>';
+
+function startDevserver(input: StartDevserverToolInput, context: McpToolContext, host: Host) {
+  const projectKey = input.project ?? DEFAULT_PROJECT_KEY;
+  if (context.devServers?.has(projectKey)) {
+    return createStructureContentOutput({
+      message: `Development server for project '${projectKey}' is already running.`,
+    });
+  }
+
+  const devServer = new LocalDevServer({ host, project: input.project, port: input.port });
+  devServer.start();
+
+  if (!context.devServers) {
+    context.devServers = new Map<string, DevServer>();
+  }
+  context.devServers.set(projectKey, devServer);
+
+  return createStructureContentOutput({
+    message: `Development server for project '${projectKey}' started.`,
+  });
+}
+
+export const START_DEVSERVER_TOOL: McpToolDeclaration<
+  typeof startDevserverToolInputSchema.shape,
+  typeof startDevserverToolOutputSchema.shape
+> = declareTool({
+  name: 'start_devserver',
+  title: 'Start Development Server',
+  description: `
+<Purpose>
+Starts the Angular development server ("ng serve") as a background process.
+</Purpose>
+<Use Cases>
+* **Starting the Server:** Use this tool to begin serving the application. The tool will return immediately
+  while the server runs in the background.
+</Use Cases>
+<Operational Notes>
+* This tool manages a development server instance for each project.
+* This is an asynchronous operation. Subsequent commands can be run while the server is active.
+* Use 'stop_devserver' to gracefully shut down the server and access the full log output.
+</Operational Notes>
+`,
+  isReadOnly: false,
+  isLocalOnly: true,
+  inputSchema: startDevserverToolInputSchema.shape,
+  outputSchema: startDevserverToolOutputSchema.shape,
+  factory: (context) => (input) => {
+    return startDevserver(input, context, LocalWorkspaceHost);
+  },
+});