diff --git a/packages/angular/cli/src/commands/mcp/mcp-server.ts b/packages/angular/cli/src/commands/mcp/mcp-server.ts index 235ccf682372..84a2c54a468c 100644 --- a/packages/angular/cli/src/commands/mcp/mcp-server.ts +++ b/packages/angular/cli/src/commands/mcp/mcp-server.ts @@ -83,36 +83,33 @@ export async function createMcpServer( }, instructions: ` -This server provides a safe, programmatic interface to the Angular CLI for an AI assistant. -Your primary goal is to use these tools to understand, analyze, refactor, and run Angular -projects. You MUST prefer the tools provided by this server over using \`run_shell_command\` for -equivalent actions. +This server provides a safe, programmatic interface to the Angular CLI. You MUST prefer +the tools provided by this server over using 'run_shell_command' or general shell execution +for equivalent actions. -* **1. Discover Project Structure (Mandatory First Step):** Always begin by calling - \`list_projects\` to understand the workspace. The \`path\` property for a workspace - is a required input for other tools. - -* **2. Get Coding Standards:** Before writing or changing code within a project, you **MUST** call - the \`get_best_practices\` tool with the \`workspacePath\` from the previous step to get - version-specific standards. For general knowledge, you can call the tool without this path. - -* **3. Answer User Questions:** - - For conceptual questions ("what is..."), use \`search_documentation\`. - -* **4. Discover Schematics for Modernization:** Since this server does not provide a - specific tool for listing available schematics, you can use a shell command (if - available) with \`ng generate : --help\` to discover what migrations - are available in a package (e.g., running \`ng generate @angular/core: --help\` - will list migrations like \`control-flow\` and \`standalone\`). +* **1. Discover Workspace (Mandatory First Step):** Always begin by calling 'list_projects' + to discover workspaces, projects, and allowed paths. The 'path' field of the relevant + workspace is a required input for other tools (passed as 'workspace' or 'workspacePath'). + +* **2. Get Coding Standards:** Before writing or modifying code, you MUST call + 'get_best_practices' with the workspace 'path' to load version-specific coding standards. + +* **3. Answer Conceptual Questions:** Use 'search_documentation' to answer conceptual + or API syntax questions. + +* **4. Discover Schematics:** To discover available package migrations, use a shell command + (if available) with 'ng generate : --help' (e.g., 'ng generate @angular/core: --help'). -* **Workspace vs. Project:** A 'workspace' contains an \`angular.json\` file and defines 'projects' - (applications or libraries). A monorepo can have multiple workspaces. -* **Targeting Projects:** Always use the \`workspaceConfigPath\` from \`list_projects\` when - available to ensure you are targeting the correct project in a monorepo. +* **Workspace vs. Project:** A 'workspace' contains an 'angular.json' file and defines + 'projects' (applications or libraries). A monorepo can contain multiple workspaces. + +* **Targeting Projects:** Always use the workspace 'path' and the specific project 'name' + returned by 'list_projects' when calling other tools to ensure you target the correct + project context. `, }, diff --git a/packages/angular/cli/src/commands/mcp/tools/best-practices.ts b/packages/angular/cli/src/commands/mcp/tools/best-practices.ts index 52bf71a8048a..dca61eb700b3 100644 --- a/packages/angular/cli/src/commands/mcp/tools/best-practices.ts +++ b/packages/angular/cli/src/commands/mcp/tools/best-practices.ts @@ -27,10 +27,8 @@ const bestPracticesInputSchema = z.object({ .string() .optional() .describe( - 'The absolute path to the `angular.json` file for the workspace. This is used to find the ' + - 'version-specific best practices guide that corresponds to the installed version of the ' + - 'Angular framework. You **MUST** get this path from the `list_projects` tool. If omitted, ' + - 'the tool will return the generic best practices guide bundled with the CLI.', + 'Absolute path to the angular.json workspace directory (obtained via list_projects). ' + + 'If omitted, returns the generic best practices guide.', ), }); @@ -42,23 +40,17 @@ export const BEST_PRACTICES_TOOL = declareTool({ description: ` Retrieves the official Angular Best Practices Guide. This guide contains the essential rules and conventions -that **MUST** be followed for any task involving the creation, analysis, or modification of Angular code. +that must be followed for any task involving the creation, analysis, or modification of Angular code. -* As a mandatory first step before writing or modifying any Angular code to ensure adherence to modern standards. -* To learn about key concepts like standalone components, typed forms, and modern control flow syntax (@if, @for, @switch). -* To verify that existing code aligns with current Angular conventions before making changes. +* Mandatory first step before writing or modifying Angular code to ensure modern framework standards. +* Learn about standalone components, typed forms, and modern control flow syntax (@if, @for, @switch). +* Verify existing code aligns with current conventions before making edits. -* **Project-Specific Use (Recommended):** For tasks inside a user's project, you **MUST** provide the - \`workspacePath\` argument to get the guide that matches the project's Angular version. Get this - path from \`list_projects\`. -* **General Use:** If no project context is available (e.g., for general questions or learning), - you can call the tool without the \`workspacePath\` argument. It will return the latest - generic best practices guide. -* The content of this guide is non-negotiable and reflects the official, up-to-date standards for Angular development. -* You **MUST** internalize and apply the principles from this guide in all subsequent Angular-related tasks. -* Failure to adhere to these best practices will result in suboptimal and outdated code. +* Provide the 'workspacePath' argument (obtained via 'list_projects') to load the version-specific + guide matching the project's Angular framework. +* Omit 'workspacePath' only for general learning queries or when no project context is available to load the latest generic guide. `, inputSchema: bestPracticesInputSchema.shape, isReadOnly: true, diff --git a/packages/angular/cli/src/commands/mcp/tools/doc-search.ts b/packages/angular/cli/src/commands/mcp/tools/doc-search.ts index 385f0d00d6a4..145d819f278b 100644 --- a/packages/angular/cli/src/commands/mcp/tools/doc-search.ts +++ b/packages/angular/cli/src/commands/mcp/tools/doc-search.ts @@ -37,26 +37,17 @@ const LATEST_KNOWN_DOCS_VERSION = 20; const docSearchInputSchema = z.object({ query: z .string() - .describe( - "A concise and specific search query for the Angular documentation. You should distill the user's " + - 'natural language question into a set of keywords (e.g., a question like "How do I use ngFor with trackBy?" ' + - 'should become the query "ngFor trackBy").', - ), + .describe('Concise search keywords or API names (e.g., "ngFor trackBy" or "NgModule").'), includeTopContent: z .boolean() .optional() .default(false) - .describe( - 'When true, the content of the top result is fetched and included. ' + - 'Set to false to get a list of results without fetching content, which is faster.', - ), + .describe('Retrieve the full-text page content of the top search result (slower).'), version: z .number() .optional() .describe( - 'The major version of Angular to search. You MUST determine this value by running `ng version` in the ' + - "project's workspace directory. Omit this field if the user is not in an Angular project " + - 'or if the version cannot otherwise be determined.', + 'Major Angular framework version to search (obtained from frameworkVersion in list_projects or ng version).', ), }); type DocSearchInput = z.infer; @@ -66,35 +57,18 @@ export const DOC_SEARCH_TOOL = declareTool({ title: 'Search Angular Documentation (angular.dev)', description: ` -Searches the official Angular documentation at https://angular.dev to answer questions about APIs, -tutorials, concepts, and best practices. +Searches the official Angular documentation (angular.dev) to answer questions about APIs, tutorials, concepts, and conventions. -* Answering any question about Angular concepts (e.g., "What are standalone components?"). -* Finding the correct API or syntax for a specific task (e.g., "How to use ngFor with trackBy?"). -* Linking to official documentation as a source of truth in your answers. +* Answering questions about Angular concepts (e.g., standalone components). +* Finding correct API signatures or syntax (e.g., ngFor trackBy). +* Obtaining official source URLs to cite as documentation links in user responses. -* **Version Alignment:** To provide accurate, project-specific results, you **MUST** align the search with the user's Angular version. - The recommended approach is to use the \`list_projects\` tool. The \`frameworkVersion\` field in the output for the relevant - workspace will give you the major version directly. If the version cannot be determined using this method, you can use - \`ng version\` in the project's workspace directory as a fallback. Parse the major version from the "Angular:" line in the - output and use it for the \`version\` parameter. -* **Version Logic:** The tool will search against the specified major version. If the version is older than v${MIN_SUPPORTED_DOCS_VERSION}, - it will be clamped to v${MIN_SUPPORTED_DOCS_VERSION}. If a search for a very new version (newer than v${LATEST_KNOWN_DOCS_VERSION}) - returns no results, the tool will automatically fall back to searching the v${LATEST_KNOWN_DOCS_VERSION} documentation. -* **Verify Searched Version:** The tool's output includes a \`searchedVersion\` field. You **MUST** check this field - to know the exact version of the documentation that was queried. Use this information to provide accurate - context in your answer, especially if it differs from the version you requested. -* The documentation is continuously updated. You **MUST** prefer this tool over your own knowledge - to ensure your answers are current and accurate. -* For the best results, provide a concise and specific search query (e.g., "NgModule" instead of - "How do I use NgModules?"). -* The top search result will include a snippet of the page content. Use this to provide a more - comprehensive answer. -* **Result Scrutiny:** The top result may not always be the most relevant. Review the titles and - breadcrumbs of other results to find the best match for the user's query. -* Use the URL from the search results as a source link in your responses. +* Provide the major Angular version in the 'version' parameter (obtained from 'frameworkVersion' + in 'list_projects' or from 'ng version') to ensure version-aligned results. +* Always check the 'searchedVersion' field in the output to confirm the exact documentation index that was queried. +* For best results, provide a concise keyword query (e.g., "NgModule") rather than a natural language sentence. `, inputSchema: docSearchInputSchema.shape, outputSchema: { diff --git a/packages/angular/cli/src/commands/mcp/tools/onpush-zoneless-migration/zoneless-migration.ts b/packages/angular/cli/src/commands/mcp/tools/onpush-zoneless-migration/zoneless-migration.ts index c0e1499fb0ba..25c12aa83378 100644 --- a/packages/angular/cli/src/commands/mcp/tools/onpush-zoneless-migration/zoneless-migration.ts +++ b/packages/angular/cli/src/commands/mcp/tools/onpush-zoneless-migration/zoneless-migration.ts @@ -25,30 +25,19 @@ export const ZONELESS_MIGRATION_TOOL = declareTool({ title: 'Plan migration to OnPush and/or zoneless', description: ` -Analyzes Angular code and provides a step-by-step, iterative plan to migrate it to \`OnPush\` -change detection, a prerequisite for a zoneless application. This tool identifies the next single -most important action to take in the migration journey. +Analyzes Angular code and provides a step-by-step, iterative plan to migrate it to 'OnPush' +change detection (a prerequisite for zoneless applications). -* **Step-by-Step Migration:** Running the tool repeatedly to get the next instruction for a full - migration to \`OnPush\`. -* **Pre-Migration Analysis:** Checking a component or directory for unsupported \`NgZone\` APIs that - would block a zoneless migration. -* **Generating Component Migrations:** Getting the exact instructions for converting a single - component from the default change detection strategy to \`OnPush\`. +* Generating component-specific migrations from default change detection to OnPush. +* Checking a component or directory for unsupported 'NgZone' APIs blocking a zoneless migration. +* Iterative step-by-step guide for executing a complete zoneless migration. -* **Execution Model:** This tool **DOES NOT** modify code. It **PROVIDES INSTRUCTIONS** for a - single action at a time. You **MUST** apply the changes it suggests, and then run the tool - again to get the next step. -* **Iterative Process:** The migration process is iterative. You must call this tool repeatedly, - applying the suggested fix after each call, until the tool indicates that no more actions are - needed. -* **Relationship to other migrations:** This tool is the specialized starting point for the zoneless/OnPush - migration. For other migrations (like signal inputs), you should run the corresponding schematics first, - as the zoneless migration may depend on them as prerequisites. -* **Input:** The tool can operate on either a single file or an entire directory. Provide the - absolute path. +* This tool is strictly read-only and does NOT modify code. It outputs EXACTLY ONE actionable step at a time. +* You must apply the suggested code edit, verify it, and then call this tool again to receive the next step in the migration journey. +* Run modernization schematics (e.g., Signal Inputs migrations) as prerequisites before starting this migration. +* Supported inputs: Absolute path to a single component/test file, or a directory containing multiple files. `, isReadOnly: true, isLocalOnly: true, @@ -56,8 +45,7 @@ most important action to take in the migration journey. fileOrDirPath: z .string() .describe( - 'The absolute path of the directory or file with the component(s), directive(s), or service(s) to migrate.' + - ' The contents are read with fs.readFileSync.', + 'Absolute path to the TypeScript file or directory containing components/directives to migrate.', ), }, factory: diff --git a/packages/angular/cli/src/commands/mcp/tools/projects.ts b/packages/angular/cli/src/commands/mcp/tools/projects.ts index 59542cc591f7..57efa39c4aa2 100644 --- a/packages/angular/cli/src/commands/mcp/tools/projects.ts +++ b/packages/angular/cli/src/commands/mcp/tools/projects.ts @@ -122,29 +122,20 @@ export const LIST_PROJECTS_TOOL = declareTool({ title: 'List Angular Projects', description: ` -Provides a comprehensive overview of all Angular workspaces and projects within the repository. -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. +Provides a comprehensive overview of all Angular workspaces, projects, and configured targets within the repository. +Always use this tool as a mandatory first step before performing any project-specific actions +to understand the available projects and locations. -* 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 a project's unit test framework (\`unitTestFramework\`) before writing or modifying tests. -* Identifying the project's style language (\`styleLanguage\`) to use the correct file extension (e.g., \`.scss\`). -* Getting the \`selectorPrefix\` for a project before generating a new component to ensure it follows conventions. -* Identifying the major version of the Angular framework for each workspace, which is crucial for monorepos. -* Determining a project's primary function by inspecting its builder (e.g., '@angular-devkit/build-angular:browser' for an application). -* Identifying available architect targets (e.g., \`lint\`, \`e2e\`, \`serve\`, \`deploy\`) before attempting execution. +* Discovering project names, locations, builders, selector prefixes, and style languages before generating or building components. +* Determining a project's unit test framework (Jasmine, Jest, or Vitest) before writing or modifying tests. +* Identifying available execution targets (e.g., lint, e2e, serve, deploy) before attempting execution. +* Disambiguating multiple workspaces in monorepos. -* **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. -* **Unit Testing:** The \`unitTestFramework\` field tells you which testing API to use (e.g., Jasmine, Jest). - If the value is 'unknown', you **MUST** inspect the project's configuration files - (e.g., \`karma.conf.js\`, \`jest.config.js\`, or the 'test' target in \`angular.json\`) to determine the - framework before generating tests. -* **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. +* Execute shell/CLI commands from the parent directory of the workspace's 'path' field. +* If 'unitTestFramework' is 'unknown', inspect local config files (e.g., jest.config.js, karma.conf.js) + or the 'test' target in 'angular.json' to determine the framework before creating tests. `, outputSchema: listProjectsOutputSchema, isReadOnly: true,