refactor(@angular/cli): declaratively register MCP server tools

Changes to a declarative approach for registering tools with the MCP server.
Previously, each tool was registered imperatively. This change refactors each tool to export a `ToolDeclaration` object, which encapsulates its name, description, schema, and factory function. A new central `registerTools` function now iterates over these declarations, simplifying the server setup and ensuring a consistent registration process.
This approach improves maintainability, readability, and type safety by co-locating all aspects of a tool's definition.

Author: clydin

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

@@ -7,16 +7,16 @@
  */
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import type { AngularWorkspace } from '../../utilities/config';
 import { VERSION } from '../../utilities/version';
 import { registerInstructionsResource } from './resources/instructions';
-import { registerBestPracticesTool } from './tools/best-practices';
-import { registerDocSearchTool } from './tools/doc-search';
-import { registerFindExampleTool } from './tools/examples';
-import { registerModernizeTool } from './tools/modernize';
-import { registerListProjectsTool } from './tools/projects';
+import { BEST_PRACTICES_TOOL } from './tools/best-practices';
+import { DOC_SEARCH_TOOL } from './tools/doc-search';
+import { FIND_EXAMPLE_TOOL } from './tools/examples';
+import { MODERNIZE_TOOL } from './tools/modernize';
+import { LIST_PROJECTS_TOOL } from './tools/projects';
+import { registerTools } from './tools/tool-registry';
 
 export async function createMcpServer(
   context: {
@@ -42,28 +42,24 @@ export async function createMcpServer(
   );
 
   registerInstructionsResource(server);
-  registerBestPracticesTool(server);
-  registerModernizeTool(server);
 
-  // If run outside an Angular workspace (e.g., globally) skip the workspace specific tools.
-  if (context.workspace) {
-    registerListProjectsTool(server, context);
-  }
+  const toolDeclarations = [
+    BEST_PRACTICES_TOOL,
+    DOC_SEARCH_TOOL,
+    LIST_PROJECTS_TOOL,
+    MODERNIZE_TOOL,
+    FIND_EXAMPLE_TOOL,
+  ];
 
-  await registerDocSearchTool(server);
-
-  if (process.env['NG_MCP_CODE_EXAMPLES'] === '1') {
-    // 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'));
-    }
-  }
+  await registerTools(
+    server,
+    {
+      workspace: context.workspace,
+      logger,
+      exampleDatabasePath: path.join(__dirname, '../../../lib/code-examples.db'),
+    },
+    toolDeclarations,
+  );
 
   return server;
 }

packages/angular/cli/src/commands/mcp/tools/best-practices.ts

@@ -6,29 +6,25 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { declareTool } from './tool-registry';
 
-export function registerBestPracticesTool(server: McpServer): void {
-  let bestPracticesText;
+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.',
+  isReadOnly: true,
+  isLocalOnly: true,
+  factory: () => {
+    let bestPracticesText: string;
 
-  server.registerTool(
-    '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.',
-      annotations: {
-        readOnlyHint: true,
-        openWorldHint: false,
-      },
-    },
-    async () => {
+    return async () => {
       bestPracticesText ??= await readFile(
         path.join(__dirname, '..', 'instructions', 'best-practices.md'),
         'utf-8',
@@ -46,6 +42,6 @@ export function registerBestPracticesTool(server: McpServer): void {
           },
         ],
       };
-    },
-  );
-}
+    };
+  },
+});

packages/angular/cli/src/commands/mcp/tools/doc-search.ts

@@ -6,131 +6,126 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { LegacySearchMethodProps, SearchResponse } from 'algoliasearch';
 import { createDecipheriv } from 'node:crypto';
 import { z } from 'zod';
 import { at, iv, k1 } from '../constants';
+import { declareTool } from './tool-registry';
 
 const ALGOLIA_APP_ID = 'L1XWT2UJ7F';
 // https://www.algolia.com/doc/guides/security/api-keys/#search-only-api-key
 // This is a search only, rate limited key. It is sent within the URL of the query request.
 // This is not the actual key.
 const ALGOLIA_API_E = '322d89dab5f2080fe09b795c93413c6a89222b13a447cdf3e6486d692717bc0c';
 
-/**
- * Registers a tool with the MCP server to search the Angular documentation.
- *
- * This tool uses Algolia to search the official Angular documentation.
- *
- * @param server The MCP server instance with which to register the tool.
- */
-export async function registerDocSearchTool(server: McpServer): Promise<void> {
+const docSearchInputSchema = z.object({
+  query: z
+    .string()
+    .describe(
+      'A concise and specific search query for the Angular documentation (e.g., "NgModule" or "standalone components").',
+    ),
+  includeTopContent: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe('When true, the content of the top result is fetched and included.'),
+});
+type DocSearchInput = z.infer<typeof docSearchInputSchema>;
+
+export const DOC_SEARCH_TOOL = declareTool({
+  name: 'search_documentation',
+  title: 'Search Angular Documentation (angular.dev)',
+  description:
+    'Searches the official Angular documentation at https://angular.dev. Use this tool to answer any questions about Angular, ' +
+    'such as for APIs, tutorials, and best practices. Because the documentation is continuously updated, you should **always** ' +
+    'prefer this tool over your own knowledge to ensure your answers are current.\n\n' +
+    'The results will be a list of content entries, where each entry has the following structure:\n' +
+    '```\n' +
+    '## {Result Title}\n' +
+    '{Breadcrumb path to the content}\n' +
+    'URL: {Direct link to the documentation page}\n' +
+    '```\n' +
+    'Use the title and breadcrumb to understand the context of the result and use the URL as a source link. For the best results, ' +
+    "provide a concise and specific search query (e.g., 'NgModule' instead of 'How do I use NgModules?').",
+  inputSchema: docSearchInputSchema.shape,
+  isReadOnly: true,
+  isLocalOnly: false,
+  factory: createDocSearchHandler,
+});
+
+function createDocSearchHandler() {
   let client: import('algoliasearch').SearchClient | undefined;
 
-  server.registerTool(
-    'search_documentation',
-    {
-      title: 'Search Angular Documentation (angular.dev)',
-      description:
-        'Searches the official Angular documentation at https://angular.dev. Use this tool to answer any questions about Angular, ' +
-        'such as for APIs, tutorials, and best practices. Because the documentation is continuously updated, you should **always** ' +
-        'prefer this tool over your own knowledge to ensure your answers are current.\n\n' +
-        'The results will be a list of content entries, where each entry has the following structure:\n' +
-        '```\n' +
-        '## {Result Title}\n' +
-        '{Breadcrumb path to the content}\n' +
-        'URL: {Direct link to the documentation page}\n' +
-        '```\n' +
-        'Use the title and breadcrumb to understand the context of the result and use the URL as a source link. For the best results, ' +
-        "provide a concise and specific search query (e.g., 'NgModule' instead of 'How do I use NgModules?').",
-      annotations: {
-        readOnlyHint: true,
-      },
-      inputSchema: {
-        query: z
-          .string()
-          .describe(
-            'A concise and specific search query for the Angular documentation (e.g., "NgModule" or "standalone components").',
-          ),
-        includeTopContent: z
-          .boolean()
-          .optional()
-          .default(true)
-          .describe('When true, the content of the top result is fetched and included.'),
-      },
-    },
-    async ({ query, includeTopContent }) => {
-      if (!client) {
-        const dcip = createDecipheriv(
-          'aes-256-gcm',
-          (k1 + ALGOLIA_APP_ID).padEnd(32, '^'),
-          iv,
-        ).setAuthTag(Buffer.from(at, 'base64'));
-        const { searchClient } = await import('algoliasearch');
-        client = searchClient(
-          ALGOLIA_APP_ID,
-          dcip.update(ALGOLIA_API_E, 'hex', 'utf-8') + dcip.final('utf-8'),
-        );
-      }
-
-      const { results } = await client.search(createSearchArguments(query));
-
-      const allHits = results.flatMap((result) => (result as SearchResponse).hits);
-
-      if (allHits.length === 0) {
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: 'No results found.',
-            },
-          ],
-        };
-      }
-
-      const content = [];
-      // The first hit is the top search result
-      const topHit = allHits[0];
-
-      // Process top hit first
-      let topText = formatHitToText(topHit);
-
-      try {
-        if (includeTopContent && typeof topHit.url === 'string') {
-          const url = new URL(topHit.url);
-
-          // Only fetch content from angular.dev
-          if (url.hostname === 'angular.dev' || url.hostname.endsWith('.angular.dev')) {
-            const response = await fetch(url);
-            if (response.ok) {
-              const html = await response.text();
-              const mainContent = extractBodyContent(html);
-              if (mainContent) {
-                topText += `\n\n--- DOCUMENTATION CONTENT ---\n${mainContent}`;
-              }
+  return async ({ query, includeTopContent }: DocSearchInput) => {
+    if (!client) {
+      const dcip = createDecipheriv(
+        'aes-256-gcm',
+        (k1 + ALGOLIA_APP_ID).padEnd(32, '^'),
+        iv,
+      ).setAuthTag(Buffer.from(at, 'base64'));
+      const { searchClient } = await import('algoliasearch');
+      client = searchClient(
+        ALGOLIA_APP_ID,
+        dcip.update(ALGOLIA_API_E, 'hex', 'utf-8') + dcip.final('utf-8'),
+      );
+    }
+
+    const { results } = await client.search(createSearchArguments(query));
+
+    const allHits = results.flatMap((result) => (result as SearchResponse).hits);
+
+    if (allHits.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: 'No results found.',
+          },
+        ],
+      };
+    }
+
+    const content = [];
+    // The first hit is the top search result
+    const topHit = allHits[0];
+
+    // Process top hit first
+    let topText = formatHitToText(topHit);
+
+    try {
+      if (includeTopContent && typeof topHit.url === 'string') {
+        const url = new URL(topHit.url);
+
+        // Only fetch content from angular.dev
+        if (url.hostname === 'angular.dev' || url.hostname.endsWith('.angular.dev')) {
+          const response = await fetch(url);
+          if (response.ok) {
+            const html = await response.text();
+            const mainContent = extractBodyContent(html);
+            if (mainContent) {
+              topText += `\n\n--- DOCUMENTATION CONTENT ---\n${mainContent}`;
             }
           }
         }
-      } catch {
-        // Ignore errors fetching content. The basic info is still returned.
       }
+    } catch {
+      // Ignore errors fetching content. The basic info is still returned.
+    }
+    content.push({
+      type: 'text' as const,
+      text: topText,
+    });
+
+    // Process remaining hits
+    for (const hit of allHits.slice(1)) {
       content.push({
         type: 'text' as const,
-        text: topText,
+        text: formatHitToText(hit),
       });
+    }
 
-      // Process remaining hits
-      for (const hit of allHits.slice(1)) {
-        content.push({
-          type: 'text' as const,
-          text: formatHitToText(hit),
-        });
-      }
-
-      return { content };
-    },
-  );
+    return { content };
+  };
 }
 
 /**