@adia-ai/a2ui-mcp 0.6.4 → 0.6.6

package/tools/corpus.js

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import {
+  getChunk as getGenUIChunk,
+  lookupChunksByPrimary,
+  searchChunks as searchGenUIChunks
+} from "../../corpus/scripts/chunk-library.js";
+function registerCorpusTools(server) {
+  server.tool(
+    "search_chunks",
+    `Search the gen-UI training-chunk corpus by keyword.
+
+The chunk corpus comes from \`packages/a2ui/corpus/chunks/\` \u2014 JSON records
+extracted from every \`[data-chunk]\` element in site/pages/* and the corpus
+exemplars. There are three kinds:
+  - block (default): atomic UI fragment (KPI grid, sign-in form, table)
+  - panel: tab-panel fragment of a page (e.g. dashboard-overview-panel)
+  - page: full-page composition (e.g. dashboard-admin-page)
+
+Returns ranked candidates with chunk name, kind, primary tag, and a relevance
+score. Use \`get_chunk\` to fetch the full record (HTML + slot bindings + nested
+chunks) for a specific name.`,
+    {
+      query: z.string().describe("Keyword query \u2014 chunk name fragment, intent words, primary-tag name"),
+      kind: z.enum(["block", "panel", "page"]).optional().describe("Filter by chunk kind"),
+      limit: z.number().int().min(1).max(50).default(20).describe("Max results")
+    },
+    async ({ query, kind, limit }) => {
+      const results = searchGenUIChunks(query, { kind, limit });
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ query, kind: kind ?? "any", count: results.length, results }, null, 2)
+        }]
+      };
+    }
+  );
+  server.tool(
+    "get_chunk",
+    `Fetch the full record for a single gen-UI training chunk by name.
+
+Returns the chunk's bounding HTML, slot annotations, nested chunk names, and
+metadata (primary tag, kind, source page). For chunks that appear on multiple
+pages (reusable slot chunks like \`auth-card-header\`, \`reg-step-header\`),
+returns an \`instances\` array \u2014 one entry per page where the chunk appears.
+
+The HTML is suitable for direct rendering / inclusion in an A2UI message
+construction prompt.`,
+    {
+      name: z.string().describe('The chunk name, e.g. "dashboard-kpi-grid", "auth-signin-card-email", "code-language"')
+    },
+    async ({ name }) => {
+      const rec = getGenUIChunk(name);
+      if (!rec) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: JSON.stringify({ error: "chunk not found", name }, null, 2) }]
+        };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(rec, null, 2) }] };
+    }
+  );
+  server.tool(
+    "lookup_chunk",
+    `List every chunk whose primary element is \`<component_name>\`.
+
+Useful for "show me every page that opens with a \`<card-ui raw>\`" or "every
+chunk built around a \`<grid-ui>\` root." Returns chunk names + kinds + sources.
+
+Pair with \`get_chunk\` to fetch full records for any of the returned names.`,
+    {
+      component_name: z.string().describe('Component tag name, e.g. "card-ui", "grid-ui", "drawer-ui"')
+    },
+    async ({ component_name }) => {
+      const recs = lookupChunksByPrimary(component_name);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            component: component_name,
+            count: recs.length,
+            chunks: recs.map((r) => {
+              const rec = r;
+              const instances = rec["instances"];
+              const firstInstance = instances?.[0];
+              const slots = rec["slots"] ?? firstInstance?.["slots"] ?? [];
+              const nested = rec["nested"] ?? firstInstance?.["nested"] ?? [];
+              return {
+                name: rec["name"],
+                kind: rec["kind"],
+                page: rec["page"] ?? firstInstance?.["page"],
+                slots: slots.map((s) => s.name),
+                nested
+              };
+            })
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+export {
+  registerCorpusTools
+};

package/tools/corpus.ts

@@ -0,0 +1,112 @@
+/**
+ * Corpus tools — gen-UI training-chunk search and retrieval.
+ *
+ * Extracted from server.ts. Registers:
+ *   search_chunks, get_chunk, lookup_chunk
+ */
+
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import {
+  getChunk as getGenUIChunk,
+  lookupChunksByPrimary,
+  searchChunks as searchGenUIChunks,
+} from '../../corpus/scripts/chunk-library.js';
+
+export function registerCorpusTools(server: McpServer): void {
+  server.tool(
+    'search_chunks',
+    `Search the gen-UI training-chunk corpus by keyword.
+
+The chunk corpus comes from \`packages/a2ui/corpus/chunks/\` — JSON records
+extracted from every \`[data-chunk]\` element in site/pages/* and the corpus
+exemplars. There are three kinds:
+  - block (default): atomic UI fragment (KPI grid, sign-in form, table)
+  - panel: tab-panel fragment of a page (e.g. dashboard-overview-panel)
+  - page: full-page composition (e.g. dashboard-admin-page)
+
+Returns ranked candidates with chunk name, kind, primary tag, and a relevance
+score. Use \`get_chunk\` to fetch the full record (HTML + slot bindings + nested
+chunks) for a specific name.`,
+    {
+      query: z.string().describe('Keyword query — chunk name fragment, intent words, primary-tag name'),
+      kind: z.enum(['block', 'panel', 'page']).optional().describe('Filter by chunk kind'),
+      limit: z.number().int().min(1).max(50).default(20).describe('Max results'),
+    },
+    async ({ query, kind, limit }) => {
+      const results = searchGenUIChunks(query, { kind, limit });
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({ query, kind: kind ?? 'any', count: results.length, results }, null, 2),
+        }],
+      };
+    },
+  );
+
+  server.tool(
+    'get_chunk',
+    `Fetch the full record for a single gen-UI training chunk by name.
+
+Returns the chunk's bounding HTML, slot annotations, nested chunk names, and
+metadata (primary tag, kind, source page). For chunks that appear on multiple
+pages (reusable slot chunks like \`auth-card-header\`, \`reg-step-header\`),
+returns an \`instances\` array — one entry per page where the chunk appears.
+
+The HTML is suitable for direct rendering / inclusion in an A2UI message
+construction prompt.`,
+    {
+      name: z.string().describe('The chunk name, e.g. "dashboard-kpi-grid", "auth-signin-card-email", "code-language"'),
+    },
+    async ({ name }) => {
+      const rec = getGenUIChunk(name);
+      if (!rec) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: 'chunk not found', name }, null, 2) }],
+        };
+      }
+      return { content: [{ type: 'text', text: JSON.stringify(rec, null, 2) }] };
+    },
+  );
+
+  server.tool(
+    'lookup_chunk',
+    `List every chunk whose primary element is \`<component_name>\`.
+
+Useful for "show me every page that opens with a \`<card-ui raw>\`" or "every
+chunk built around a \`<grid-ui>\` root." Returns chunk names + kinds + sources.
+
+Pair with \`get_chunk\` to fetch full records for any of the returned names.`,
+    {
+      component_name: z.string().describe('Component tag name, e.g. "card-ui", "grid-ui", "drawer-ui"'),
+    },
+    async ({ component_name }) => {
+      const recs = lookupChunksByPrimary(component_name);
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            component: component_name,
+            count: recs.length,
+            chunks: recs.map((r) => {
+              const rec = r as Record<string, unknown>;
+              const instances = rec['instances'] as Array<Record<string, unknown>> | undefined;
+              const firstInstance = instances?.[0];
+              const slots = (rec['slots'] ?? firstInstance?.['slots'] ?? []) as Array<{ name: string }>;
+              const nested = (rec['nested'] ?? firstInstance?.['nested'] ?? []) as unknown[];
+              return {
+                name: rec['name'],
+                kind: rec['kind'],
+                page: rec['page'] ?? firstInstance?.['page'],
+                slots: slots.map((s) => s.name),
+                nested,
+              };
+            }),
+          }, null, 2),
+        }],
+      };
+    },
+  );
+}

package/tools/feedback.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { FeedbackCollector } from "../../retrieval/feedback/feedback.js";
+import { feedbackStore } from "../../retrieval/feedback/feedback-store.js";
+const feedbackCollector = new FeedbackCollector();
+function registerFeedbackTools(server) {
+  server.tool(
+    "submit_feedback",
+    "Submit structured feedback for a generation execution. Used by the evolution engine to learn from each generation.",
+    {
+      executionId: z.string().describe("Execution ID from generate_ui"),
+      rating: z.number().min(1).max(5).describe("Overall quality 1-5"),
+      intent: z.string().optional(),
+      domain: z.string().optional(),
+      intentAlignment: z.number().min(1).max(5).optional(),
+      visualQuality: z.number().min(1).max(5).optional(),
+      componentChoice: z.number().min(1).max(5).optional(),
+      userEdited: z.boolean().optional(),
+      editSummary: z.string().optional(),
+      notes: z.string().optional(),
+      shouldBePattern: z.boolean().optional(),
+      suggestedName: z.string().optional()
+    },
+    async (args) => {
+      feedbackCollector.collectFeedback(args.executionId, {
+        rating: args.rating,
+        intentAlignment: args.intentAlignment,
+        visualQuality: args.visualQuality,
+        componentChoice: args.componentChoice,
+        userEdited: args.userEdited,
+        editSummary: args.editSummary,
+        notes: args.notes
+      });
+      if (args.shouldBePattern != null) {
+        feedbackCollector.collectPatternFeedback(args.executionId, {
+          shouldBePattern: args.shouldBePattern,
+          suggestedName: args.suggestedName
+        });
+      }
+      return { content: [{ type: "text", text: JSON.stringify({ recorded: true, executionId: args.executionId, totalEntries: feedbackCollector.size }) }] };
+    }
+  );
+  server.tool(
+    "get_quality_metrics",
+    "Get aggregated quality metrics from the feedback store: avg score, thumb-up rate, per-domain breakdown, training gaps.",
+    {},
+    async () => {
+      const metrics = await feedbackStore.getQualityMetrics();
+      return { content: [{ type: "text", text: JSON.stringify(metrics, null, 2) }] };
+    }
+  );
+  server.tool(
+    "get_training_gaps",
+    "Get training gap signals from LLM self-critique: missing patterns, weak domain keywords, component gaps.",
+    {},
+    async () => {
+      const gaps = await feedbackStore.getGapSummary();
+      return { content: [{ type: "text", text: JSON.stringify(gaps, null, 2) }] };
+    }
+  );
+}
+export {
+  registerFeedbackTools
+};

package/tools/feedback.ts

@@ -0,0 +1,73 @@
+/**
+ * Feedback tools — generation feedback collection and quality metrics.
+ *
+ * Extracted from server.ts. Registers:
+ *   submit_feedback, get_quality_metrics, get_training_gaps
+ */
+
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+import { FeedbackCollector } from '../../retrieval/feedback/feedback.js';
+import { feedbackStore } from '../../retrieval/feedback/feedback-store.js';
+
+const feedbackCollector = new FeedbackCollector();
+
+export function registerFeedbackTools(server: McpServer): void {
+  server.tool(
+    'submit_feedback',
+    'Submit structured feedback for a generation execution. Used by the evolution engine to learn from each generation.',
+    {
+      executionId: z.string().describe('Execution ID from generate_ui'),
+      rating: z.number().min(1).max(5).describe('Overall quality 1-5'),
+      intent: z.string().optional(),
+      domain: z.string().optional(),
+      intentAlignment: z.number().min(1).max(5).optional(),
+      visualQuality: z.number().min(1).max(5).optional(),
+      componentChoice: z.number().min(1).max(5).optional(),
+      userEdited: z.boolean().optional(),
+      editSummary: z.string().optional(),
+      notes: z.string().optional(),
+      shouldBePattern: z.boolean().optional(),
+      suggestedName: z.string().optional(),
+    },
+    async (args) => {
+      feedbackCollector.collectFeedback(args.executionId, {
+        rating: args.rating,
+        intentAlignment: args.intentAlignment,
+        visualQuality: args.visualQuality,
+        componentChoice: args.componentChoice,
+        userEdited: args.userEdited,
+        editSummary: args.editSummary,
+        notes: args.notes,
+      });
+      if (args.shouldBePattern != null) {
+        feedbackCollector.collectPatternFeedback(args.executionId, {
+          shouldBePattern: args.shouldBePattern,
+          suggestedName: args.suggestedName,
+        });
+      }
+      return { content: [{ type: 'text', text: JSON.stringify({ recorded: true, executionId: args.executionId, totalEntries: feedbackCollector.size }) }] };
+    }
+  );
+
+  server.tool(
+    'get_quality_metrics',
+    'Get aggregated quality metrics from the feedback store: avg score, thumb-up rate, per-domain breakdown, training gaps.',
+    {},
+    async () => {
+      const metrics = await feedbackStore.getQualityMetrics();
+      return { content: [{ type: 'text', text: JSON.stringify(metrics, null, 2) }] };
+    }
+  );
+
+  server.tool(
+    'get_training_gaps',
+    'Get training gap signals from LLM self-critique: missing patterns, weak domain keywords, component gaps.',
+    {},
+    async () => {
+      const gaps = await feedbackStore.getGapSummary();
+      return { content: [{ type: 'text', text: JSON.stringify(gaps, null, 2) }] };
+    }
+  );
+}