feat(@angular/cli): standardize MCP tools around workspace/project options

Author: amishne

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

@@ -71,17 +71,29 @@ export class LocalDevserver implements Devserver {
   readonly host: Host;
   readonly port: number;
   readonly project?: string;
+  readonly workspacePath?: 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 }) {
+  constructor({
+    host,
+    port,
+    project,
+    workspacePath,
+  }: {
+    host: Host;
+    port: number;
+    project?: string;
+    workspacePath?: string;
+  }) {
     this.host = host;
     this.project = project;
     this.port = port;
+    this.workspacePath = workspacePath;
   }
 
   start() {
@@ -96,7 +108,10 @@ export class LocalDevserver implements Devserver {
 
     args.push(`--port=${this.port}`);
 
-    this.devserverProcess = this.host.spawn('ng', args, { stdio: 'pipe' });
+    this.devserverProcess = this.host.spawn('ng', args, {
+      stdio: 'pipe',
+      cwd: this.workspacePath,
+    });
     this.devserverProcess.stdout?.on('data', (data) => {
       this.addLog(data.toString());
     });
@@ -142,3 +157,7 @@ export class LocalDevserver implements Devserver {
     return this.buildInProgress;
   }
 }
+
+export function getDevServerKey(workspacePath: string, projectName: string): string {
+  return `${workspacePath}:${projectName}`;
+}

packages/angular/cli/src/commands/mcp/shared-options.ts

@@ -0,0 +1,22 @@
+/**
+ * @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';
+
+export const workspaceAndProjectOptions = {
+  project: z
+    .string()
+    .optional()
+    .describe(
+      'Which project to target in a monorepo context. If not provided, targets the default project.',
+    ),
+  workspace: z
+    .string()
+    .optional()
+    .describe('The path to the workspace directory (containing angular.json).'),
+};

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

@@ -7,22 +7,21 @@
  */
 
 import { z } from 'zod';
-import { CommandError, type Host } from '../host';
-import { createStructuredContentOutput, getCommandErrorLogs } from '../utils';
-import { type McpToolDeclaration, declareTool } from './tool-registry';
+import { workspaceAndProjectOptions } from '../shared-options';
+import {
+  createStructuredContentOutput,
+  getCommandErrorLogs,
+  resolveWorkspaceAndProject,
+} from '../utils';
+import { type McpToolContext, type McpToolDeclaration, declareTool } from './tool-registry';
 
 const DEFAULT_CONFIGURATION = 'development';
 
 const buildStatusSchema = z.enum(['success', 'failure']);
 type BuildStatus = z.infer<typeof buildStatusSchema>;
 
 const buildToolInputSchema = z.object({
-  project: z
-    .string()
-    .optional()
-    .describe(
-      'Which project to build in a monorepo context. If not provided, builds the default project.',
-    ),
+  ...workspaceAndProjectOptions,
   configuration: z
     .string()
     .optional()
@@ -39,11 +38,18 @@ const buildToolOutputSchema = z.object({
 
 export type BuildToolOutput = z.infer<typeof buildToolOutputSchema>;
 
-export async function runBuild(input: BuildToolInput, host: Host) {
+export async function runBuild(input: BuildToolInput, context: McpToolContext) {
+  const { workspacePath, projectName } = await resolveWorkspaceAndProject({
+    host: context.host,
+    workspacePathInput: input.workspace,
+    projectNameInput: input.project,
+    loadedWorkspace: context.workspace,
+  });
+
   // Build "ng"'s command line.
   const args = ['build'];
-  if (input.project) {
-    args.push(input.project);
+  if (projectName) {
+    args.push(projectName);
   }
   args.push('-c', input.configuration ?? DEFAULT_CONFIGURATION);
 
@@ -52,7 +58,7 @@ export async function runBuild(input: BuildToolInput, host: Host) {
   let outputPath: string | undefined;
 
   try {
-    logs = (await host.runCommand('ng', args)).logs;
+    logs = (await context.host.runCommand('ng', args, { cwd: workspacePath })).logs;
   } catch (e) {
     status = 'failure';
     logs = getCommandErrorLogs(e);
@@ -101,5 +107,5 @@ Perform a one-off, non-watched build using "ng build". Use this tool whenever th
   isLocalOnly: true,
   inputSchema: buildToolInputSchema.shape,
   outputSchema: buildToolOutputSchema.shape,
-  factory: (context) => (input) => runBuild(input, context.host),
+  factory: (context) => (input) => runBuild(input, context),
 });

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

@@ -6,36 +6,52 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import { AngularWorkspace } from '../../../utilities/config';
 import { CommandError } from '../host';
 import type { MockHost } from '../testing/mock-host';
-import { createMockHost } from '../testing/test-utils';
+import { addProjectToWorkspace, createMockContext } from '../testing/test-utils';
 import { runBuild } from './build';
+import type { McpToolContext } from './tool-registry';
 
 describe('Build Tool', () => {
   let mockHost: MockHost;
+  let mockContext: McpToolContext;
+  let mockWorkspace: AngularWorkspace;
 
   beforeEach(() => {
-    mockHost = createMockHost();
+    const mock = createMockContext();
+    mockHost = mock.host;
+    mockContext = mock.context;
+    mockWorkspace = mock.workspace;
+    addProjectToWorkspace(mock.projects, 'my-app');
   });
 
   it('should construct the command correctly with default configuration', async () => {
-    await runBuild({}, mockHost);
-    expect(mockHost.runCommand).toHaveBeenCalledWith('ng', ['build', '-c', 'development']);
+    mockWorkspace.extensions['defaultProject'] = 'my-app';
+    await runBuild({}, mockContext);
+    expect(mockHost.runCommand).toHaveBeenCalledWith(
+      'ng',
+      ['build', 'my-app', '-c', 'development'],
+      { cwd: '/test' },
+    );
   });
 
   it('should construct the command correctly with a specified project', async () => {
-    await runBuild({ project: 'another-app' }, mockHost);
-    expect(mockHost.runCommand).toHaveBeenCalledWith('ng', [
-      'build',
-      'another-app',
-      '-c',
-      'development',
-    ]);
+    addProjectToWorkspace(mockWorkspace.projects, 'another-app');
+    await runBuild({ project: 'another-app' }, mockContext);
+    expect(mockHost.runCommand).toHaveBeenCalledWith(
+      'ng',
+      ['build', 'another-app', '-c', 'development'],
+      { cwd: '/test' },
+    );
   });
 
   it('should construct the command correctly for a custom configuration', async () => {
-    await runBuild({ configuration: 'myconfig' }, mockHost);
-    expect(mockHost.runCommand).toHaveBeenCalledWith('ng', ['build', '-c', 'myconfig']);
+    mockWorkspace.extensions['defaultProject'] = 'my-app';
+    await runBuild({ configuration: 'myconfig' }, mockContext);
+    expect(mockHost.runCommand).toHaveBeenCalledWith('ng', ['build', 'my-app', '-c', 'myconfig'], {
+      cwd: '/test',
+    });
   });
 
   it('should handle a successful build and extract the output path and logs', async () => {
@@ -49,35 +65,34 @@ describe('Build Tool', () => {
       logs: buildLogs,
     });
 
-    const { structuredContent } = await runBuild({ project: 'my-app' }, mockHost);
+    const { structuredContent } = await runBuild({ project: 'my-app' }, mockContext);
 
-    expect(mockHost.runCommand).toHaveBeenCalledWith('ng', [
-      'build',
-      'my-app',
-      '-c',
-      'development',
-    ]);
+    expect(mockHost.runCommand).toHaveBeenCalledWith(
+      'ng',
+      ['build', 'my-app', '-c', 'development'],
+      { cwd: '/test' },
+    );
     expect(structuredContent.status).toBe('success');
     expect(structuredContent.logs).toEqual(buildLogs);
     expect(structuredContent.path).toBe('dist/my-app');
   });
 
   it('should handle a failed build and capture logs', async () => {
+    addProjectToWorkspace(mockWorkspace.projects, 'my-failed-app');
     const buildLogs = ['Some output before the crash.', 'Error: Something went wrong!'];
     const error = new CommandError('Build failed', buildLogs, 1);
     mockHost.runCommand.and.rejectWith(error);
 
     const { structuredContent } = await runBuild(
       { project: 'my-failed-app', configuration: 'production' },
-      mockHost,
+      mockContext,
     );
 
-    expect(mockHost.runCommand).toHaveBeenCalledWith('ng', [
-      'build',
-      'my-failed-app',
-      '-c',
-      'production',
-    ]);
+    expect(mockHost.runCommand).toHaveBeenCalledWith(
+      'ng',
+      ['build', 'my-failed-app', '-c', 'production'],
+      { cwd: '/test' },
+    );
     expect(structuredContent.status).toBe('failure');
     expect(structuredContent.logs).toEqual([...buildLogs, 'Build failed']);
     expect(structuredContent.path).toBeUndefined();
@@ -87,7 +102,8 @@ describe('Build Tool', () => {
     const buildLogs = ["Some logs that don't match any output path."];
     mockHost.runCommand.and.resolveTo({ logs: buildLogs });
 
-    const { structuredContent } = await runBuild({}, mockHost);
+    mockWorkspace.extensions['defaultProject'] = 'my-app';
+    const { structuredContent } = await runBuild({}, mockContext);
 
     expect(structuredContent.status).toBe('success');
     expect(structuredContent.logs).toEqual(buildLogs);

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

@@ -7,17 +7,13 @@
  */
 
 import { z } from 'zod';
-import { LocalDevserver } from '../../devserver';
-import { createStructuredContentOutput, getDefaultProjectName } from '../../utils';
+import { LocalDevserver, getDevServerKey } from '../../devserver';
+import { workspaceAndProjectOptions } from '../../shared-options';
+import { createStructuredContentOutput, resolveWorkspaceAndProject } from '../../utils';
 import { type McpToolContext, type McpToolDeclaration, declareTool } from '../tool-registry';
 
 const devserverStartToolInputSchema = z.object({
-  project: z
-    .string()
-    .optional()
-    .describe(
-      'Which project to serve in a monorepo context. If not provided, serves the default project.',
-    ),
+  ...workspaceAndProjectOptions,
 });
 
 export type DevserverStartToolInput = z.infer<typeof devserverStartToolInputSchema>;
@@ -39,15 +35,22 @@ function localhostAddress(port: number) {
 }
 
 export async function startDevserver(input: DevserverStartToolInput, context: McpToolContext) {
-  const projectName = input.project ?? getDefaultProjectName(context);
+  const { workspacePath, projectName } = await resolveWorkspaceAndProject({
+    host: context.host,
+    workspacePathInput: input.workspace,
+    projectNameInput: input.project,
+    loadedWorkspace: context.workspace,
+  });
 
   if (!projectName) {
     return createStructuredContentOutput({
       message: ['Project name not provided, and no default project found.'],
     });
   }
 
-  let devserver = context.devservers.get(projectName);
+  const key = getDevServerKey(workspacePath, projectName);
+
+  let devserver = context.devservers.get(key);
   if (devserver) {
     return createStructuredContentOutput({
       message: `Development server for project '${projectName}' is already running.`,
@@ -57,10 +60,15 @@ export async function startDevserver(input: DevserverStartToolInput, context: Mc
 
   const port = await context.host.getAvailablePort();
 
-  devserver = new LocalDevserver({ host: context.host, project: input.project, port });
+  devserver = new LocalDevserver({
+    host: context.host,
+    project: input.project,
+    port,
+    workspacePath,
+  });
   devserver.start();
 
-  context.devservers.set(projectName, devserver);
+  context.devservers.set(key, devserver);
 
   return createStructuredContentOutput({
     message: `Development server for project '${projectName}' started and watching for workspace changes.`,