feat(@angular/cli): Add a "build" MCP tool

Author: amishne

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

@@ -0,0 +1,149 @@
+/**
+ * @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';
+
+// Log messages that we want to catch to identify the build status.
+
+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;
+
+  /**
+   * `ng serve` port to use.
+   */
+  port: number;
+}
+
+export function devServerKey(project?: string) {
+  return project ?? '<default>';
+}
+
+/**
+ * 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?: number = undefined;
+  private latestBuildStatus: BuildStatus = 'unknown';
+
+  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.addLog(data.toString());
+    });
+    this.devServerProcess.stderr?.on('data', (data) => {
+      this.addLog(data.toString());
+    });
+    this.devServerProcess.stderr?.on('close', () => {
+      this.stop();
+    });
+    this.buildInProgress = true;
+  }
+
+  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 - 1;
+    } else if (BUILD_END_MESSAGES.some((message) => log.startsWith(message))) {
+      this.buildInProgress = false;
+      // We consider everything except a specific failure message to be a success.
+      this.latestBuildStatus = log.startsWith(BUILD_FAILED_MESSAGE) ? 'failure' : 'success';
+    }
+  }
+
+  stop() {
+    this.devServerProcess?.kill();
+    this.devServerProcess = null;
+  }
+
+  getServerLogs(): string[] {
+    return [...this.serverLogs];
+  }
+
+  getMostRecentBuild() {
+    return {
+      status: this.latestBuildStatus,
+      logs: this.serverLogs.slice(this.latestBuildLogStartIndex),
+    };
+  }
+
+  isBuilding() {
+    return this.buildInProgress;
+  }
+}

packages/angular/cli/src/commands/mcp/host.ts

@@ -14,9 +14,10 @@
  */
 
 import { existsSync as nodeExistsSync } from 'fs';
-import { spawn } from 'node:child_process';
+import { ChildProcess, spawn } from 'node:child_process';
 import { Stats } from 'node:fs';
 import { stat } from 'node:fs/promises';
+import { createServer } from 'node:net';
 
 /**
  * An error thrown when a command fails to execute.
@@ -68,14 +69,38 @@ export interface Host {
       env?: Record<string, string>;
     },
   ): Promise<{ stdout: string; stderr: string }>;
+
+  /**
+   * Spawns a long-running child process and returns the `ChildProcess` object.
+   * @param command The command to run.
+   * @param args The arguments to pass to the command.
+   * @param options Options for the child process.
+   * @returns The spawned `ChildProcess` instance.
+   */
+  spawn(
+    command: string,
+    args: readonly string[],
+    options?: {
+      stdio?: 'pipe' | 'ignore';
+      cwd?: string;
+      env?: Record<string, string>;
+    },
+  ): ChildProcess;
+
+  /**
+   * Finds an available TCP port on the system.
+   */
+  getAvailablePort(): Promise<number>;
 }
 
 /**
  * A concrete implementation of the `Host` interface that runs on a local workspace.
  */
 export const LocalWorkspaceHost: Host = {
   stat,
+
   existsSync: nodeExistsSync,
+
   runCommand: async (
     command: string,
     args: readonly string[],
@@ -127,4 +152,50 @@ export const LocalWorkspaceHost: Host = {
       });
     });
   },
+
+  spawn(
+    command: string,
+    args: readonly string[],
+    options: {
+      stdio?: 'pipe' | 'ignore';
+      cwd?: string;
+      env?: Record<string, string>;
+    } = {},
+  ): ChildProcess {
+    return spawn(command, args, {
+      shell: false,
+      stdio: options.stdio ?? 'pipe',
+      cwd: options.cwd,
+      env: {
+        ...process.env,
+        ...options.env,
+      },
+    });
+  },
+
+  getAvailablePort(): Promise<number> {
+    return new Promise((resolve, reject) => {
+      // Create a new temporary server from Node's net library.
+      const server = createServer();
+
+      server.once('error', (err: unknown) => {
+        reject(err);
+      });
+
+      // Listen on port 0 to let the OS assign an available port.
+      server.listen(0, () => {
+        const address = server.address();
+
+        // Ensure address is an object with a port property.
+        if (address && typeof address === 'object') {
+          const port = address.port;
+
+          server.close();
+          resolve(port);
+        } else {
+          reject(new Error('Unable to retrieve address information from server.'));
+        }
+      });
+    });
+  },
 };

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

@@ -10,15 +10,25 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import path from 'node:path';
 import type { AngularWorkspace } from '../../utilities/config';
 import { VERSION } from '../../utilities/version';
+import { DevServer } from './dev-server';
 import { registerInstructionsResource } from './resources/instructions';
 import { AI_TUTOR_TOOL } from './tools/ai-tutor';
 import { BEST_PRACTICES_TOOL } from './tools/best-practices';
+import { BUILD_TOOL } from './tools/build';
 import { DOC_SEARCH_TOOL } from './tools/doc-search';
 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 { 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';
+
+/**
+ * Tools to manage devservers. Should be bundled together, then added to experimental or stable as a group.
+ */
+const SERVE_TOOLS = [START_DEVSERVER_TOOL, STOP_DEVSERVER_TOOL, WAIT_FOR_DEVSERVER_BUILD_TOOL];
 
 /**
  * The set of tools that are enabled by default for the MCP server.
@@ -36,7 +46,12 @@ const STABLE_TOOLS = [
  * 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] as const;
+export const EXPERIMENTAL_TOOLS = [
+  BUILD_TOOL,
+  MODERNIZE_TOOL,
+  ZONELESS_MIGRATION_TOOL,
+  ...SERVE_TOOLS,
+] as const;
 
 export async function createMcpServer(
   options: {
@@ -103,6 +118,7 @@ equivalent actions.
       workspace: options.workspace,
       logger,
       exampleDatabasePath: path.join(__dirname, '../../../lib/code-examples.db'),
+      devServers: new Map<string, DevServer>(),
     },
     toolDeclarations,
   );