feat(@angular/cli): Working build and serve MCP tools

Author: amishne

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

@@ -9,6 +9,8 @@
 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...';
@@ -55,24 +57,32 @@ export interface DevServer {
    * 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 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;
+  private latestBuildLogStartIndex?: number = undefined;
+  private latestBuildStatus: BuildStatus = 'unknown';
 
-  constructor({ host, port, project }: { host: Host; port?: number; project?: string }) {
+  constructor({ host, port, project }: { host: Host; port: number; project?: string }) {
     this.host = host;
     this.project = project;
     this.port = port;
@@ -93,10 +103,10 @@ export class LocalDevServer implements DevServer {
 
     this.devServerProcess = this.host.spawn('ng', args, { stdio: 'pipe' });
     this.devServerProcess.stdout?.on('data', (data) => {
-      this.serverLogs.push(data.toString());
+      this.addLog(data.toString());
     });
     this.devServerProcess.stderr?.on('data', (data) => {
-      this.serverLogs.push(data.toString());
+      this.addLog(data.toString());
     });
   }
 
@@ -108,8 +118,8 @@ export class LocalDevServer implements DevServer {
       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';
+      // We consider everything except a specific failure message to be a success.
+      this.latestBuildStatus = log.startsWith(BUILD_FAILED_MESSAGE) ? 'failure' : 'success';
     }
   }
 
@@ -124,8 +134,8 @@ export class LocalDevServer implements DevServer {
 
   getMostRecentBuild() {
     return {
-      status: this.latestBuildStatus ?? 'unknown',
-      logs: this.serverLogs.slice(this.latestBuildLogStartIndex, this.latestBuildLogEndIndex),
+      status: this.latestBuildStatus,
+      logs: this.serverLogs.slice(this.latestBuildLogStartIndex),
     };
   }
 

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

@@ -10,6 +10,7 @@ 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';
@@ -24,29 +25,29 @@ 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.
+ */
+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.
  * These tools are considered stable and suitable for general use.
  */
 const STABLE_TOOLS = [
   AI_TUTOR_TOOL,
   BEST_PRACTICES_TOOL,
-  BUILD_TOOL,
   DOC_SEARCH_TOOL,
   FIND_EXAMPLE_TOOL,
   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 = [
+  BUILD_TOOL,
   MODERNIZE_TOOL,
   ZONELESS_MIGRATION_TOOL,
   ...SERVE_TOOLS,
@@ -117,6 +118,7 @@ equivalent actions.
       workspace: options.workspace,
       logger,
       exampleDatabasePath: path.join(__dirname, '../../../lib/code-examples.db'),
+      devServers: new Map<string, DevServer>(),
     },
     toolDeclarations,
   );

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

@@ -9,7 +9,7 @@
 import { z } from 'zod';
 import { CommandError, Host, LocalWorkspaceHost } from '../host';
 import { createStructureContentOutput } from '../utils';
-import { McpToolContext, McpToolDeclaration, declareTool } from './tool-registry';
+import { McpToolDeclaration, declareTool } from './tool-registry';
 
 const CONFIGURATIONS = {
   development: {
@@ -50,6 +50,7 @@ export type BuildToolOutput = z.infer<typeof buildToolOutputSchema>;
 export async function runBuild(input: BuildToolInput, host: Host) {
   const configurationName = input.configuration ?? 'development';
   const configuration = CONFIGURATIONS[configurationName as keyof typeof CONFIGURATIONS];
+
   const args = ['build'];
   if (input.project) {
     args.push(input.project);
@@ -99,18 +100,18 @@ export const BUILD_TOOL: McpToolDeclaration<
   title: 'Build Tool',
   description: `
 <Purpose>
-Perform a one-off, non-watched build with "ng build". Use this tool whenever
-the user wants to build an Angular project; this is similar to "ng build", but
-the tool is smarter about using the right configuration and collecting the
-output logs.
+Perform a one-off, non-watched build with "ng build". Use this tool whenever the user wants to build an Angular project; this is similar to
+"ng build", but the tool is smarter about using the right configuration and collecting the output logs.
 </Purpose>
 <Use Cases>
 * Building the Angular project and getting build logs back.
 </Use Cases>
 <Operational Notes>
 * This tool runs "ng build" so it expects to run within an Angular workspace.
-* You can provide a project instead of building the root one. The
-  "list_projects" MCP tool could be used to obtain the list of projects.
+* If you want a watched build which updates as files are changed, use "start_devserver" instead, which also serves the app.
+* You can provide a project instead of building the root one. The "list_projects" MCP tool could be used to obtain the list of projects.
+* This tool defaults to a development environment while a regular "ng build" defaults to a production environment. An unexpected build
+  failure might suggest the project is not configured for the requested environment.
 </Operational Notes>
 `,
   isReadOnly: false,

packages/angular/cli/src/commands/mcp/tools/start-devserver.ts

@@ -6,8 +6,9 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import { createServer } from 'net';
 import { z } from 'zod';
-import { DevServer, LocalDevServer } from '../dev-server';
+import { LocalDevServer, devServerKey } from '../dev-server';
 import { Host, LocalWorkspaceHost } from '../host';
 import { createStructureContentOutput } from '../utils';
 import { McpToolContext, McpToolDeclaration, declareTool } from './tool-registry';
@@ -19,37 +20,76 @@ const startDevserverToolInputSchema = z.object({
     .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.'),
+  address: z
+    .string()
+    .optional()
+    .describe(
+      'If the operation was successful, this is the HTTP address that the server can be found at.',
+    ),
 });
 
 export type StartDevserverToolOutput = z.infer<typeof startDevserverToolOutputSchema>;
 
-export const DEFAULT_PROJECT_KEY = '<default>';
+/**
+ * Finds an available TCP port on the system.
+ */
+function 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;
 
-function startDevserver(input: StartDevserverToolInput, context: McpToolContext, host: Host) {
-  const projectKey = input.project ?? DEFAULT_PROJECT_KEY;
-  if (context.devServers?.has(projectKey)) {
+        server.close();
+        resolve(port);
+      } else {
+        reject(new Error('Unable to retrieve address information from server.'));
+      }
+    });
+  });
+}
+
+function localhostAddress(port: number) {
+  return `http://localhost:${port}/`;
+}
+
+async function startDevserver(input: StartDevserverToolInput, context: McpToolContext, host: Host) {
+  const projectKey = devServerKey(input.project);
+
+  let devServer = context.devServers.get(projectKey);
+  if (devServer) {
     return createStructureContentOutput({
       message: `Development server for project '${projectKey}' is already running.`,
+      address: localhostAddress(devServer.port),
     });
   }
 
-  const devServer = new LocalDevServer({ host, project: input.project, port: input.port });
+  const port = await getAvailablePort();
+
+  devServer = new LocalDevServer({ host, project: input.project, 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.`,
+    message: `Development server for project '${projectKey}' started and watching for workspace changes.`,
+    address: localhostAddress(port),
   });
 }
 
@@ -64,12 +104,14 @@ export const START_DEVSERVER_TOOL: McpToolDeclaration<
 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.
+* **Starting the Server:** Use this tool to begin serving the application. The tool will return immediately while the server runs in the
+  background.
+* **Get Build Logs:** Once a dev server has started, use the "wait_for_devserver_build" tool to ensure it's alive. If there are any build
+  errors, "wait_for_devserver_build" would provide them back and you can give them to the user or rely on them to propose a fix.
 </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.
+* This tool manages development servers by itself. It maintains at most a single dev server instance for each project in the monorepo.
+* This is an asynchronous operation. Subsequent commands can be ran while the server is active.
 * Use 'stop_devserver' to gracefully shut down the server and access the full log output.
 </Operational Notes>
 `,

packages/angular/cli/src/commands/mcp/tools/stop-devserver.ts

@@ -7,8 +7,8 @@
  */
 
 import { z } from 'zod';
+import { devServerKey } from '../dev-server';
 import { createStructureContentOutput } from '../utils';
-import { DEFAULT_PROJECT_KEY } from './start-devserver';
 import { McpToolContext, McpToolDeclaration, declareTool } from './tool-registry';
 
 const stopDevserverToolInputSchema = z.object({
@@ -24,14 +24,14 @@ export type StopDevserverToolInput = z.infer<typeof stopDevserverToolInputSchema
 
 const stopDevserverToolOutputSchema = z.object({
   message: z.string().describe('A message indicating the result of the operation.'),
-  logs: z.array(z.string()).optional().describe('The logs from the dev server.'),
+  logs: z.array(z.string()).optional().describe('The full logs from the dev server.'),
 });
 
 export type StopDevserverToolOutput = z.infer<typeof stopDevserverToolOutputSchema>;
 
 function stopDevserver(input: StopDevserverToolInput, context: McpToolContext) {
-  const projectKey = input.project ?? DEFAULT_PROJECT_KEY;
-  const devServer = context.devServers?.get(projectKey);
+  const projectKey = devServerKey(input.project);
+  const devServer = context.devServers.get(projectKey);
 
   if (!devServer) {
     return createStructureContentOutput({
@@ -40,7 +40,7 @@ function stopDevserver(input: StopDevserverToolInput, context: McpToolContext) {
   }
 
   devServer.stop();
-  context.devServers?.delete(projectKey);
+  context.devServers.delete(projectKey);
 
   return createStructureContentOutput({
     message: `Development server for project '${projectKey}' stopped.`,
@@ -56,7 +56,7 @@ export const STOP_DEVSERVER_TOOL: McpToolDeclaration<
   title: 'Stop Development Server',
   description: `
 <Purpose>
-Stops a running Angular development server ("ng serve").
+Stops a running Angular development server ("ng serve") that was started with the "start_devserver" tool.
 </Purpose>
 <Use Cases>
 * **Stopping the Server:** Use this tool to terminate a running development server and retrieve the logs.

packages/angular/cli/src/commands/mcp/tools/tool-registry.ts

@@ -18,7 +18,7 @@ export interface McpToolContext {
   workspace?: AngularWorkspace;
   logger: { warn(text: string): void };
   exampleDatabasePath?: string;
-  devServers?: Map<string, DevServer>;
+  devServers: Map<string, DevServer>;
 }
 
 export type McpToolFactory<TInput extends ZodRawShape> = (