From 174eb820fb5c77d64927812a480e56374f6f9072 Mon Sep 17 00:00:00 2001 From: Charles Lyding <19598772+clydin@users.noreply.github.com> Date: Thu, 28 Aug 2025 20:01:59 -0400 Subject: [PATCH 1/2] refactor(@angular/cli): add structured output to examples MCP tool The `find_examples` MCP tool is updated to frame it as a RAG (Retrieval-Augmented Generation) source, focusing on modern and recently updated Angular features. The tool's description is rewritten to guide the AI on when to use this tool versus the documentation search. A structured output schema is also added to make the results more reliable, and the handler is updated to return data in the new format. --- .../cli/src/commands/mcp/tools/examples.ts | 53 ++++++++++++++----- 1 file changed, 40 insertions(+), 13 deletions(-) diff --git a/packages/angular/cli/src/commands/mcp/tools/examples.ts b/packages/angular/cli/src/commands/mcp/tools/examples.ts index 0690be04f523..21cacd5454c5 100644 --- a/packages/angular/cli/src/commands/mcp/tools/examples.ts +++ b/packages/angular/cli/src/commands/mcp/tools/examples.ts @@ -42,16 +42,39 @@ type FindExampleInput = z.infer; export const FIND_EXAMPLE_TOOL = declareTool({ name: 'find_examples', title: 'Find Angular Code Examples', - description: - 'Before writing or modifying any Angular code including templates, ' + - '**ALWAYS** use this tool to find current best-practice examples. ' + - 'This is critical for ensuring code quality and adherence to modern Angular standards. ' + - 'This tool searches a curated database of approved Angular code examples and returns the most relevant results for your query. ' + - 'Example Use Cases: ' + - "1) Creating new components, directives, or services (e.g., query: 'standalone component' or 'signal input'). " + - "2) Implementing core features (e.g., query: 'lazy load route', 'httpinterceptor', or 'route guard'). " + - "3) Refactoring existing code to use modern patterns (e.g., query: 'ngfor trackby' or 'form validation').", + description: ` + +Augments your knowledge base with a curated database of official, best-practice code examples, +focusing on **modern, new, and recently updated** Angular features. This tool acts as a RAG +(Retrieval-Augmented Generation) source, providing ground-truth information on the latest Angular +APIs and patterns. You **MUST** use it to understand and apply current standards when working with +new or evolving features. + + +* **Knowledge Augmentation:** Learning about new or updated Angular features (e.g., query: 'signal input' or 'deferrable views'). +* **Modern Implementation:** Finding the correct modern syntax for features + (e.g., query: 'functional route guard' or 'http client with fetch'). +* **Refactoring to Modern Patterns:** Upgrading older code by finding examples of new syntax + (e.g., query: 'built-in control flow' to replace "*ngIf'). + + +* **Tool Selection:** This database primarily contains examples for new and recently updated Angular + features. For established, core features, the main documentation (via the + \`search_documentation\` tool) may be a better source of information. +* The examples in this database are the single source of truth for modern Angular coding patterns. +* The search query uses a powerful full-text search syntax (FTS5). Refer to the 'query' + parameter description for detailed syntax rules and examples. +`, inputSchema: findExampleInputSchema.shape, + outputSchema: { + examples: z.array( + z.object({ + content: z + .string() + .describe('A complete, self-contained Angular code example in Markdown format.'), + }), + ), + }, isReadOnly: true, isLocalOnly: true, shouldRegister: ({ logger }) => { @@ -96,14 +119,18 @@ async function createFindExampleHandler({ exampleDatabasePath }: McpToolContext) const sanitizedQuery = escapeSearchQuery(query); - // Query database and return results as text content - const content = []; + // Query database and return results + const examples = []; + const textContent = []; for (const exampleRecord of queryStatement.all(sanitizedQuery)) { - content.push({ type: 'text' as const, text: exampleRecord['content'] as string }); + const exampleContent = exampleRecord['content'] as string; + examples.push({ content: exampleContent }); + textContent.push({ type: 'text' as const, text: exampleContent }); } return { - content, + content: textContent, + structuredContent: { examples }, }; }; } From 86b90f2e9608a2667b172470fbde50918e221ee5 Mon Sep 17 00:00:00 2001 From: Charles Lyding <19598772+clydin@users.noreply.github.com> Date: Thu, 28 Aug 2025 20:07:55 -0400 Subject: [PATCH 2/2] refactor(@angular/cli): rewrite best-practices MCP tool description for clarity The description for the `get_best_practices` MCP tool is rewritten to use a structured format with ``, ``, and `` tags. This change makes the tool's purpose and mandatory nature clearer and more actionable for an AI model, ensuring it understands the importance of adhering to the official Angular Best Practices Guide. --- .../src/commands/mcp/tools/best-practices.ts | 21 +++++++++++++------ 1 file changed, 15 insertions(+), 6 deletions(-) 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 b5b207ea3b08..4d9e74ac34b6 100644 --- a/packages/angular/cli/src/commands/mcp/tools/best-practices.ts +++ b/packages/angular/cli/src/commands/mcp/tools/best-practices.ts @@ -13,12 +13,21 @@ import { declareTool } from './tool-registry'; export const BEST_PRACTICES_TOOL = declareTool({ name: 'get_best_practices', title: 'Get Angular Coding Best Practices Guide', - description: - 'You **MUST** use this tool to retrieve the Angular Best Practices Guide ' + - 'before any interaction with Angular code (creating, analyzing, modifying). ' + - 'It is mandatory to follow this guide to ensure all code adheres to ' + - 'modern standards, including standalone components, typed forms, and ' + - 'modern control flow. This is the first step for any Angular task.', + 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. + + +* 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. + + +* 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. +`, isReadOnly: true, isLocalOnly: true, factory: () => {