refactor(@angular/cli): provide a find examples MCP server tool

The built-in stdio MCP server (`ng mcp`) for the Angular CLI now includes
a tool that can find Angular code usage examples. The code examples are
indexed and stored locally within the Angular CLI install. This removes
the need for network requests to find the examples. It also ensures that
the examples are relevant for the version of Angular currently being used.
This tool requires Node.js 22.16 or higher. Lower versions will not have
this specific tool available for use.

Author: clydin

package.json

@@ -82,7 +82,7 @@
     "@types/less": "^3.0.3",
     "@types/loader-utils": "^2.0.0",
     "@types/lodash": "^4.17.0",
-    "@types/node": "^20.17.19",
+    "@types/node": "^22.12.0",
     "@types/npm-package-arg": "^6.1.0",
     "@types/pacote": "^11.1.3",
     "@types/picomatch": "^4.0.0",

packages/angular/cli/BUILD.bazel

@@ -5,6 +5,7 @@
 
 load("@npm//:defs.bzl", "npm_link_all_packages")
 load("//tools:defaults.bzl", "jasmine_test", "npm_package", "ts_project")
+load("//tools:example_db_generator.bzl", "cli_example_db")
 load("//tools:ng_cli_schema_generator.bzl", "cli_json_schema")
 load("//tools:ts_json_schema.bzl", "ts_json_schema")
 
@@ -25,6 +26,7 @@ RUNTIME_ASSETS = glob(
     ],
 ) + [
     "//packages/angular/cli:lib/config/schema.json",
+    "//packages/angular/cli:lib/code-examples.db",
 ]
 
 ts_project(
@@ -73,6 +75,17 @@ ts_project(
     ],
 )
 
+cli_example_db(
+    name = "cli_example_database",
+    srcs = glob(
+        include = [
+            "lib/examples/**/*.md",
+        ],
+    ),
+    out = "lib/code-examples.db",
+    path = "packages/angular/cli/lib/examples",
+)
+
 CLI_SCHEMA_DATA = [
     "//packages/angular/build:schemas",
     "//packages/angular_devkit/build_angular:schemas",

packages/angular/cli/lib/examples/if-block.md

@@ -0,0 +1,28 @@
+# Angular @if Control Flow Example
+
+This example demonstrates how to use the `@if` control flow block in an Angular template. The visibility of a `<div>` element is controlled by a boolean field in the component's TypeScript code.
+
+## Angular Template
+
+```html
+<!-- The @if directive will only render this div if the 'isVisible' field in the component is true. -->
+@if (isVisible) {
+<div>This content is conditionally displayed.</div>
+}
+```
+
+## Component TypeScript
+
+```typescript
+import { Component } from '@angular/core';
+
+@Component({
+  selector: 'app-example',
+  templateUrl: './example.component.html',
+  styleUrls: ['./example.component.css'],
+})
+export class ExampleComponent {
+  // This boolean field controls the visibility of the element in the template.
+  isVisible: boolean = true;
+}
+```

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

@@ -43,7 +43,10 @@ export default class McpCommandModule extends CommandModule implements CommandMo
       return;
     }
 
-    const server = await createMcpServer({ workspace: this.context.workspace });
+    const server = await createMcpServer(
+      { workspace: this.context.workspace },
+      this.context.logger,
+    );
     const transport = new StdioServerTransport();
     await server.connect(transport);
   }

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

@@ -12,10 +12,14 @@ import path from 'node:path';
 import { z } from 'zod';
 import type { AngularWorkspace } from '../../utilities/config';
 import { VERSION } from '../../utilities/version';
+import { registerFindExampleTool } from './tools/examples';
 
-export async function createMcpServer(context: {
-  workspace?: AngularWorkspace;
-}): Promise<McpServer> {
+export async function createMcpServer(
+  context: {
+    workspace?: AngularWorkspace;
+  },
+  logger: { warn(text: string): void },
+): Promise<McpServer> {
   const server = new McpServer({
     name: 'angular-cli-server',
     version: VERSION.full,
@@ -129,5 +133,16 @@ export async function createMcpServer(context: {
     },
   );
 
+  // sqlite database support requires Node.js 22.16+
+  const [nodeMajor, nodeMinor] = process.versions.node.split('.', 2).map(Number);
+  if (nodeMajor < 22 || (nodeMajor === 22 && nodeMinor < 16)) {
+    logger.warn(
+      `MCP tool 'find_examples' requires Node.js 22.16 (or higher). ` +
+        ' Registration of this tool has been skipped.',
+    );
+  } else {
+    await registerFindExampleTool(server, path.join(__dirname, '../../../lib/code-examples.db'));
+  }
+
   return server;
 }

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

@@ -0,0 +1,78 @@
+/**
+ * @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 type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+/**
+ * Registers the `find_examples` tool with the MCP server.
+ *
+ * This tool allows users to search for best-practice Angular code examples
+ * from a local SQLite database.
+ *
+ * @param server The MCP server instance.
+ * @param exampleDatabasePath The path to the SQLite database file containing the examples.
+ */
+export async function registerFindExampleTool(
+  server: McpServer,
+  exampleDatabasePath: string,
+): Promise<void> {
+  let db: import('node:sqlite').DatabaseSync | undefined;
+  let queryStatement: import('node:sqlite').StatementSync | undefined;
+
+  server.registerTool(
+    'find_examples',
+    {
+      title: 'Find Angular Code Examples',
+      description:
+        'Searches for and returns best-practice Angular code examples based on a query from a local set of packaged examples.' +
+        ' This should be used before creating any Angular code to ensure that best practices are followed.' +
+        ' Results are ranked in order of relevance with most relevant being first.',
+      inputSchema: {
+        query: z.string().describe('The search query to find Angular code examples.'),
+      },
+    },
+    async ({ query }) => {
+      if (!db || !queryStatement) {
+        suppressSqliteWarning();
+
+        const { DatabaseSync } = await import('node:sqlite');
+        db = new DatabaseSync(exampleDatabasePath, { readOnly: true });
+        queryStatement = db.prepare('SELECT * from examples WHERE examples MATCH ? ORDER BY rank;');
+      }
+
+      // Query database and return results as text content
+      const content = [];
+      for (const exampleRecord of queryStatement.all(query)) {
+        content.push({ type: 'text' as const, text: exampleRecord['content'] as string });
+      }
+
+      return {
+        content,
+      };
+    },
+  );
+}
+
+function suppressSqliteWarning() {
+  const originalProcessEmit = process.emit;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  process.emit = function (event: string, error?: unknown): any {
+    if (
+      event === 'warning' &&
+      error instanceof Error &&
+      error.name === 'ExperimentalWarning' &&
+      error.message.includes('SQLite')
+    ) {
+      return false;
+    }
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, prefer-rest-params
+    return originalProcessEmit.apply(process, arguments as any);
+  };
+}