fix(@angular/cli): improve list_projects MCP tool to find all workspaces in monorepos

clydin · clydin · commit f099c91570b3 · 2025-09-02T07:34:57.000-04:00
The `list_projects` MCP tool is enhanced with better monorepo support by correctly discovering all `angular.json` files in any subdirectory.

The tool's description is also rewritten to follow best practices for LLM consumption, using structured tags like `&lt;Purpose&gt;`, `&lt;Use Cases&gt;`, and `&lt;Operational Notes&gt;` to provide clear and actionable guidance.
diff --git a/packages/angular/cli/src/commands/mcp/tools/projects.ts b/packages/angular/cli/src/commands/mcp/tools/projects.ts
@@ -6,53 +6,173 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
+import { readdir } from 'node:fs/promises';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import z from 'zod';
+import { AngularWorkspace } from '../../../utilities/config';
+import { assertIsError } from '../../../utilities/error';
 import { McpToolContext, declareTool } from './tool-registry';
 
 export const LIST_PROJECTS_TOOL = declareTool({
   name: 'list_projects',
   title: 'List Angular Projects',
-  description:
-    'Lists the names of all applications and libraries defined within an Angular workspace. ' +
-    'It reads the `angular.json` configuration file to identify the projects. ',
+  description: `
+<Purpose>
+Provides a comprehensive overview of all Angular workspaces and projects within a monorepo.
+It is essential to use this tool as a first step before performing any project-specific actions to understand the available projects,
+their types, and their locations.
+</Purpose>
+<Use Cases>
+* Finding the correct project name to use in other commands (e.g., \`ng generate component my-comp --project=my-app\`).
+* Identifying the \`root\` and \`sourceRoot\` of a project to read, analyze, or modify its files.
+* Determining if a project is an \`application\` or a \`library\`.
+* Getting the \`selectorPrefix\` for a project before generating a new component to ensure it follows conventions.
+</Use Cases>
+<Operational Notes>
+* **Working Directory:** Shell commands for a project (like \`ng generate\`) **MUST**
+  be executed from the parent directory of the \`path\` field for the relevant workspace.
+* **Disambiguation:** A monorepo may contain multiple workspaces (e.g., for different applications or even in output directories).
+  Use the \`path\` of each workspace to understand its context and choose the correct project.
+</Operational Notes>`,
   outputSchema: {
-    projects: z.array(
+    workspaces: z.array(
       z.object({
-        name: z
-          .string()
-          .describe('The name of the project, as defined in the `angular.json` file.'),
-        type: z
-          .enum(['application', 'library'])
-          .optional()
-          .describe(`The type of the project, either 'application' or 'library'.`),
-        root: z
-          .string()
-          .describe('The root directory of the project, relative to the workspace root.'),
-        sourceRoot: z
-          .string()
-          .describe(
-            `The root directory of the project's source files, relative to the workspace root.`,
-          ),
-        selectorPrefix: z
-          .string()
-          .optional()
-          .describe(
-            'The prefix to use for component selectors.' +
-              ` For example, a prefix of 'app' would result in selectors like '<app-my-component>'.`,
-          ),
+        path: z.string().describe('The path to the `angular.json` file for this workspace.'),
+        projects: z.array(
+          z.object({
+            name: z
+              .string()
+              .describe('The name of the project, as defined in the `angular.json` file.'),
+            type: z
+              .enum(['application', 'library'])
+              .optional()
+              .describe(`The type of the project, either 'application' or 'library'.`),
+            root: z
+              .string()
+              .describe('The root directory of the project, relative to the workspace root.'),
+            sourceRoot: z
+              .string()
+              .describe(
+                `The root directory of the project's source files, relative to the workspace root.`,
+              ),
+            selectorPrefix: z
+              .string()
+              .optional()
+              .describe(
+                'The prefix to use for component selectors.' +
+                  ` For example, a prefix of 'app' would result in selectors like '<app-my-component>'.`,
+              ),
+          }),
+        ),
       }),
     ),
+    parsingErrors: z
+      .array(
+        z.object({
+          filePath: z.string().describe('The path to the file that could not be parsed.'),
+          message: z.string().describe('The error message detailing why parsing failed.'),
+        }),
+      )
+      .optional()
+      .describe('A list of files that looked like workspaces but failed to parse.'),
   },
   isReadOnly: true,
   isLocalOnly: true,
-  shouldRegister: (context) => !!context.workspace,
   factory: createListProjectsHandler,
 });
 
-function createListProjectsHandler({ workspace }: McpToolContext) {
+/**
+ * Recursively finds all 'angular.json' files in a directory, skipping 'node_modules'.
+ * @param dir The directory to start the search from.
+ * @returns An async generator that yields the full path of each found 'angular.json' file.
+ */
+async function* findAngularJsonFiles(dir: string): AsyncGenerator<string> {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules') {
+          continue;
+        }
+        yield* findAngularJsonFiles(fullPath);
+      } else if (entry.name === 'angular.json') {
+        yield fullPath;
+      }
+    }
+  } catch (error) {
+    assertIsError(error);
+    // Silently ignore errors for directories that cannot be read
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      return;
+    }
+    throw error;
+  }
+}
+
+async function createListProjectsHandler({ server }: McpToolContext) {
   return async () => {
-    if (!workspace) {
+    const workspaces = [];
+    const parsingErrors: { filePath: string; message: string }[] = [];
+    const seenPaths = new Set<string>();
+
+    let searchRoots: string[];
+    const clientCapabilities = server.server.getClientCapabilities();
+    if (clientCapabilities?.roots) {
+      const { roots } = await server.server.listRoots();
+      searchRoots = roots?.map((r) => path.normalize(fileURLToPath(r.uri))) ?? [];
+      throw new Error('hi');
+    } else {
+      // Fallback to the current working directory if client does not support roots
+      searchRoots = [process.cwd()];
+    }
+
+    for (const root of searchRoots) {
+      for await (const configFile of findAngularJsonFiles(root)) {
+        try {
+          // A workspace may be found multiple times in a monorepo
+          const resolvedPath = path.resolve(configFile);
+          if (seenPaths.has(resolvedPath)) {
+            continue;
+          }
+          seenPaths.add(resolvedPath);
+
+          const ws = await AngularWorkspace.load(configFile);
+
+          const projects = [];
+          for (const [name, project] of ws.projects.entries()) {
+            projects.push({
+              name,
+              type: project.extensions['projectType'] as 'application' | 'library' | undefined,
+              root: project.root,
+              sourceRoot: project.sourceRoot ?? path.posix.join(project.root, 'src'),
+              selectorPrefix: project.extensions['prefix'] as string,
+            });
+          }
+
+          workspaces.push({
+            path: configFile,
+            projects,
+          });
+        } catch (error) {
+          let message;
+          if (error instanceof Error) {
+            message = error.message;
+          } else {
+            // For any non-Error objects thrown, use a generic message
+            message = 'An unknown error occurred while parsing the file.';
+          }
+
+          parsingErrors.push({
+            filePath: configFile,
+            message,
+          });
+        }
+      }
+    }
+
+    if (workspaces.length === 0 && parsingErrors.length === 0) {
       return {
         content: [
           {
@@ -63,32 +183,19 @@ function createListProjectsHandler({ workspace }: McpToolContext) {
               ' could not be located in the current directory or any of its parent directories.',
           },
         ],
-        structuredContent: { projects: [] },
+        structuredContent: { workspaces: [] },
       };
     }
 
-    const projects = [];
-    // Convert to output format
-    for (const [name, project] of workspace.projects.entries()) {
-      projects.push({
-        name,
-        type: project.extensions['projectType'] as 'application' | 'library' | undefined,
-        root: project.root,
-        sourceRoot: project.sourceRoot ?? path.posix.join(project.root, 'src'),
-        selectorPrefix: project.extensions['prefix'] as string,
-      });
+    let text = `Found ${workspaces.length} workspace(s).\n${JSON.stringify({ workspaces })}`;
+    if (parsingErrors.length > 0) {
+      text += `\n\nWarning: The following ${parsingErrors.length} file(s) could not be parsed and were skipped:\n`;
+      text += parsingErrors.map((e) => `- ${e.filePath}: ${e.message}`).join('\n');
     }
 
-    // The structuredContent field is newer and may not be supported by all hosts.
-    // A text representation of the content is also provided for compatibility.
     return {
-      content: [
-        {
-          type: 'text' as const,
-          text: `Projects in the Angular workspace:\n${JSON.stringify(projects)}`,
-        },
-      ],
-      structuredContent: { projects },
+      content: [{ type: 'text' as const, text }],
+      structuredContent: { workspaces, parsingErrors },
     };
   };
 }
diff --git a/packages/angular/cli/src/commands/mcp/tools/tool-registry.ts b/packages/angular/cli/src/commands/mcp/tools/tool-registry.ts
@@ -13,6 +13,7 @@ import type { AngularWorkspace } from '../../../utilities/config';
 type ToolConfig = Parameters<McpServer['registerTool']>[1];
 
 export interface McpToolContext {
+  server: McpServer;
   workspace?: AngularWorkspace;
   logger: { warn(text: string): void };
   exampleDatabasePath?: string;
@@ -46,17 +47,18 @@ export function declareTool<TInput extends ZodRawShape, TOutput extends ZodRawSh
 
 export async function registerTools(
   server: McpServer,
-  context: McpToolContext,
+  context: Omit<McpToolContext, 'server'>,
   declarations: AnyMcpToolDeclaration[],
 ): Promise<void> {
   for (const declaration of declarations) {
-    if (declaration.shouldRegister && !(await declaration.shouldRegister(context))) {
+    const toolContext = { ...context, server };
+    if (declaration.shouldRegister && !(await declaration.shouldRegister(toolContext))) {
       continue;
     }
 
     const { name, factory, shouldRegister, isReadOnly, isLocalOnly, ...config } = declaration;
 
-    const handler = await factory(context);
+    const handler = await factory(toolContext);
 
     // Add declarative characteristics to annotations
     config.annotations ??= {};
diff --git a/tests/legacy-cli/e2e/tests/mcp/registers-tools.ts b/tests/legacy-cli/e2e/tests/mcp/registers-tools.ts
@@ -40,7 +40,7 @@ export default async function () {
 
     const { stdout: stdoutOutsideWorkspace } = await runInspector('--method', 'tools/list');
 
-    assert.doesNotMatch(stdoutOutsideWorkspace, /"list_projects"/);
+    assert.match(stdoutOutsideWorkspace, /"list_projects"/);
     assert.match(stdoutOutsideWorkspace, /"get_best_practices"/);
     assert.match(stdoutInsideWorkspace, /"search_documentation"/);
   } finally {
