refactor(@angular/cli): add experimental flag for MCP examples

clydin · alan-agius4 · commit 31d4dfc0fe7b · 2025-09-09T14:57:14.000+02:00
This commit introduces a feature to mark and filter code examples that use experimental APIs, ensuring that the `find_examples` tool provides production-safe results by default.

Key changes:
- The example format now supports an optional `experimental: true` flag in the front matter.
- The database schema is updated with an `experimental` column. Both the build-time and runtime database generators now parse and store this flag.
- The `find_examples` tool's input schema is enhanced with an `includeExperimental` boolean flag, which defaults to `false`.
- The query logic is updated to filter out experimental examples unless `includeExperimental` is explicitly set to `true`.
- The schema description for the new flag includes a strong prescriptive guardrail, instructing the AI to warn the user when it shows an experimental example.
diff --git a/packages/angular/cli/src/commands/mcp/tools/examples.ts b/packages/angular/cli/src/commands/mcp/tools/examples.ts
@@ -55,6 +55,16 @@ const findExampleInputSchema = z.object({
       'A list of high-level concepts to filter by. Use this to find examples related to broader ' +
         'architectural ideas or patterns (e.g., `signals`, `dependency injection`, `routing`).',
     ),
+  includeExperimental: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe(
+      'By default, this tool returns only production-safe examples. Set this to `true` **only if** ' +
+        'the user explicitly asks for a bleeding-edge feature or if a stable solution to their ' +
+        'problem cannot be found. If you set this to `true`, you **MUST** preface your answer by ' +
+        'warning the user that the example uses experimental APIs that are not suitable for production.',
+    ),
 });
 
 type FindExampleInput = z.infer<typeof findExampleInputSchema>;
@@ -181,7 +191,7 @@ async function createFindExampleHandler({ exampleDatabasePath }: McpToolContext)
       db = new DatabaseSync(exampleDatabasePath, { readOnly: true });
     }
 
-    const { query, keywords, required_packages, related_concepts } = input;
+    const { query, keywords, required_packages, related_concepts, includeExperimental } = input;
 
     // Build the query dynamically
     const params: SQLInputValue[] = [];
@@ -209,6 +219,10 @@ async function createFindExampleHandler({ exampleDatabasePath }: McpToolContext)
     addJsonFilter('required_packages', required_packages);
     addJsonFilter('related_concepts', related_concepts);
 
+    if (!includeExperimental) {
+      whereClauses.push('experimental = 0');
+    }
+
     if (whereClauses.length > 0) {
       sql += ` WHERE ${whereClauses.join(' AND ')}`;
     }
@@ -402,6 +416,7 @@ async function setupRuntimeExamples(
       required_packages TEXT,
       related_concepts TEXT,
       related_tools TEXT,
+      experimental INTEGER NOT NULL DEFAULT 0,
       content TEXT NOT NULL
     );
   `);
@@ -435,8 +450,8 @@ async function setupRuntimeExamples(
 
   const insertStatement = db.prepare(
     'INSERT INTO examples(' +
-      'title, summary, keywords, required_packages, related_concepts, related_tools, content' +
-      ') VALUES(?, ?, ?, ?, ?, ?, ?);',
+      'title, summary, keywords, required_packages, related_concepts, related_tools, experimental, content' +
+      ') VALUES(?, ?, ?, ?, ?, ?, ?, ?);',
   );
 
   const frontmatterSchema = z.object({
@@ -446,6 +461,7 @@ async function setupRuntimeExamples(
     required_packages: z.array(z.string()).optional(),
     related_concepts: z.array(z.string()).optional(),
     related_tools: z.array(z.string()).optional(),
+    experimental: z.boolean().optional(),
   });
 
   db.exec('BEGIN TRANSACTION');
@@ -464,8 +480,15 @@ async function setupRuntimeExamples(
       continue;
     }
 
-    const { title, summary, keywords, required_packages, related_concepts, related_tools } =
-      validation.data;
+    const {
+      title,
+      summary,
+      keywords,
+      required_packages,
+      related_concepts,
+      related_tools,
+      experimental,
+    } = validation.data;
 
     insertStatement.run(
       title,
@@ -474,6 +497,7 @@ async function setupRuntimeExamples(
       JSON.stringify(required_packages ?? []),
       JSON.stringify(related_concepts ?? []),
       JSON.stringify(related_tools ?? []),
+      experimental ? 1 : 0,
       content,
     );
   }
diff --git a/tools/example_db_generator.js b/tools/example_db_generator.js
@@ -84,6 +84,7 @@ function generate(inPath, outPath) {
       required_packages TEXT,
       related_concepts TEXT,
       related_tools TEXT,
+      experimental INTEGER NOT NULL DEFAULT 0,
       content TEXT NOT NULL
     );
   `);
@@ -120,8 +121,8 @@ function generate(inPath, outPath) {
 
   const insertStatement = db.prepare(
     'INSERT INTO examples(' +
-      'title, summary, keywords, required_packages, related_concepts, related_tools, content' +
-      ') VALUES(?, ?, ?, ?, ?, ?, ?);',
+      'title, summary, keywords, required_packages, related_concepts, related_tools, experimental, content' +
+      ') VALUES(?, ?, ?, ?, ?, ?, ?, ?);',
   );
 
   const frontmatterSchema = z.object({
@@ -131,6 +132,7 @@ function generate(inPath, outPath) {
     required_packages: z.array(z.string()).optional(),
     related_concepts: z.array(z.string()).optional(),
     related_tools: z.array(z.string()).optional(),
+    experimental: z.boolean().optional(),
   });
 
   db.exec('BEGIN TRANSACTION');
@@ -152,15 +154,23 @@ function generate(inPath, outPath) {
       throw new Error(`Invalid front matter in ${entry.name}`);
     }
 
-    const { title, summary, keywords, required_packages, related_concepts, related_tools } =
-      validation.data;
+    const {
+      title,
+      summary,
+      keywords,
+      required_packages,
+      related_concepts,
+      related_tools,
+      experimental,
+    } = validation.data;
     insertStatement.run(
       title,
       summary,
       JSON.stringify(keywords ?? []),
       JSON.stringify(required_packages ?? []),
       JSON.stringify(related_concepts ?? []),
       JSON.stringify(related_tools ?? []),
+      experimental ? 1 : 0,
       content,
     );
   }
