@adia-ai/a2ui-mcp 0.6.5 → 0.6.7

package/tools/discovery.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { getCatalog } from "../../retrieval/catalog.js";
+import {
+  getAllCompositions
+} from "../../compose/strategies/zettel/composition-library.js";
+import { getChunk, getChunkIndex } from "../../corpus/scripts/chunk-library.js";
+function registerDiscoveryTools(server) {
+  server.tool(
+    "list_patterns",
+    `List all composition patterns in the A2UI corpus. Optional filters narrow by domain (auth, settings, dashboard, etc.) or category (block, page, flow).`,
+    {
+      domain: z.string().optional().describe('Filter by domain (e.g. "forms", "data", "navigation")'),
+      category: z.string().optional().describe('Filter by category ("block", "page", "flow")')
+    },
+    async ({ domain, category }) => {
+      const all = getAllCompositions();
+      let filtered = all;
+      if (domain) filtered = filtered.filter((c) => c.domain === domain);
+      if (category) {
+        filtered = filtered.filter((c) => {
+          const raw = c.name ? getChunk(c.name) : null;
+          const k = raw?.kind ?? c.kind;
+          return k === category;
+        });
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                total: filtered.length,
+                patterns: filtered.map((c) => {
+                  const raw = c.name ? getChunk(c.name) : null;
+                  return {
+                    name: c.name,
+                    domain: c.domain,
+                    kind: raw?.kind ?? c.kind ?? "composition",
+                    description: c.description,
+                    keywords: c.keywords ?? []
+                  };
+                })
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "server_status",
+    `Returns operational status of the MCP server: transport, sampling capability, corpus stats, version.`,
+    {},
+    async () => {
+      const catalog = await getCatalog();
+      const compositionCount = getAllCompositions().length;
+      const chunkIndex = getChunkIndex();
+      const chunkCount = chunkIndex ? chunkIndex["unique_names"] ?? null : null;
+      const hasSampling = server.server?._clientCapabilities?.sampling ? true : false;
+      const transport = typeof process !== "undefined" && process.env?.MCP_HTTP_PORT ? "http" : "stdio";
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                version: "0.1.0",
+                transport,
+                sampling: hasSampling,
+                corpus: {
+                  totalComponents: catalog.totalTypes ?? null,
+                  compositionCount,
+                  chunkCount
+                }
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
+}
+export {
+  registerDiscoveryTools
+};

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/refine.js

@@ -0,0 +1,151 @@
+import { z } from "zod";
+import { resolveAdapter } from "../server.js";
+const SYSTEM_PROMPT = `You are the A2UI Refiner.
+
+You receive:
+  1. The user's original intent.
+  2. A previously generated A2UI message array (the "previous output").
+  3. A list of validation errors that the previous output failed.
+
+Your job: produce a corrected A2UI message array that fixes ONLY the
+listed errors and preserves everything else about the previous output
+(component types, ids, intent, layout, copy). Do not refactor.
+
+Output ONLY a JSON object of the shape:
+{
+  "messages": [ ...A2UI messages... ]
+}
+
+No prose, no markdown fences. The "messages" array must be valid A2UI
+output \u2014 every component carries an id, a type, and the parent/layout
+fields it had before unless the error explicitly required changing
+them.`;
+function extractJsonObject(text) {
+  const stripped = text.replace(/^\s*```(?:json)?\s*/i, "").replace(/\s*```\s*$/i, "").trim();
+  try {
+    return JSON.parse(stripped);
+  } catch {
+  }
+  const start = stripped.indexOf("{");
+  if (start < 0) throw new Error("No JSON object found in LLM response");
+  let depth = 0;
+  let inStr = false;
+  let esc = false;
+  for (let i = start; i < stripped.length; i++) {
+    const ch = stripped[i];
+    if (inStr) {
+      if (esc) esc = false;
+      else if (ch === "\\") esc = true;
+      else if (ch === '"') inStr = false;
+      continue;
+    }
+    if (ch === '"') inStr = true;
+    else if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) {
+        return JSON.parse(stripped.slice(start, i + 1));
+      }
+    }
+  }
+  throw new Error("Unbalanced JSON object in LLM response");
+}
+function registerRefineTools(server) {
+  server.tool(
+    "refine_ui",
+    `Refine a previous generate_ui result whose validation failed. Pass the messages from the prior result + the validation errors, and the tool produces a corrected version. For monolithic engine; zettel has refine_composition.`,
+    {
+      intent: z.string().describe("Original intent string"),
+      previousMessages: z.array(z.any()).describe("Messages from the prior generate_ui call"),
+      validationErrors: z.array(z.any()).describe("Errors from the prior result.validation.errors")
+    },
+    async ({ intent, previousMessages, validationErrors }) => {
+      try {
+        const llm = await resolveAdapter();
+        const userPrompt = [
+          `INTENT:`,
+          intent,
+          ``,
+          `PREVIOUS OUTPUT (messages):`,
+          JSON.stringify(previousMessages, null, 2),
+          ``,
+          `VALIDATION ERRORS:`,
+          JSON.stringify(validationErrors, null, 2),
+          ``,
+          `Return ONLY: {"messages": [...]} with the errors above fixed and everything else preserved.`
+        ].join("\n");
+        const result = await llm.complete({
+          messages: [{ role: "user", content: userPrompt }],
+          systemPrompt: SYSTEM_PROMPT
+        });
+        const raw = result?.content ?? "";
+        let parsed;
+        try {
+          parsed = extractJsonObject(raw);
+        } catch (err) {
+          const e = err instanceof Error ? err : new Error(String(err));
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    error: `Refiner returned unparseable output: ${e.message}`,
+                    raw
+                  },
+                  null,
+                  2
+                )
+              }
+            ],
+            isError: true
+          };
+        }
+        const refinedMessages = Array.isArray(parsed?.messages) ? parsed.messages : null;
+        if (!refinedMessages) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(
+                  {
+                    error: `Refiner response missing "messages" array`,
+                    parsed
+                  },
+                  null,
+                  2
+                )
+              }
+            ],
+            isError: true
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  intent,
+                  messages: refinedMessages,
+                  errorsAddressed: validationErrors.length
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        return {
+          content: [{ type: "text", text: `refine_ui error: ${e.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+export {
+  registerRefineTools
+};

package/tools/validation.js

@@ -0,0 +1,131 @@
+import { z } from "zod";
+import { validateSchema } from "../../validator/validator.js";
+import { validateMessages as validateCatalogMessages } from "../../validator/catalog-validator.js";
+import {
+  getCatalog,
+  getComponent,
+  getTraits,
+  getTraitsByCategory
+} from "../../retrieval/catalog.js";
+import { serializeEntry } from "../../retrieval/component-entry.js";
+import { getAntiPatterns, checkAllAntiPatterns } from "../../retrieval/anti-patterns.js";
+import { assembleContext } from "../../retrieval/context-assembler.js";
+import { transpileHTML } from "../../compose/transpiler/transpiler.js";
+import { getWiringCatalog } from "../../retrieval/wiring-catalog.js";
+function registerValidationTools(server) {
+  server.tool(
+    "validate_schema",
+    "Validate A2UI messages against schema rules.",
+    {
+      messages: z.string().describe("JSON array of A2UI messages")
+    },
+    async ({ messages }) => {
+      try {
+        const parsed = JSON.parse(messages);
+        const msgs = Array.isArray(parsed) ? parsed : [parsed];
+        const scored = validateSchema(msgs);
+        const catalog = await validateCatalogMessages(msgs);
+        const result = { ...scored, catalog };
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        return { content: [{ type: "text", text: `Parse error: ${e.message}` }], isError: true };
+      }
+    }
+  );
+  server.tool(
+    "lookup_component",
+    "Look up a AdiaUI component by type name.",
+    {
+      type: z.string().describe('Component type (e.g., "Card", "Button")'),
+      level: z.enum(["index", "summary", "reference"]).optional().describe("Detail level (default: reference)")
+    },
+    async ({ type, level }) => {
+      const entry = await getComponent(type);
+      if (!entry) return { content: [{ type: "text", text: `Not found: ${type}` }], isError: true };
+      const serialized = serializeEntry(entry, level ?? "reference");
+      return { content: [{ type: "text", text: JSON.stringify(serialized, null, 2) }] };
+    }
+  );
+  server.tool(
+    "get_component_map",
+    "Get the full AdiaUI component catalog.",
+    {},
+    async () => {
+      const catalog = await getCatalog();
+      const summary = [...catalog.entries.values()].map((e) => {
+        const entry = e;
+        const desc = typeof entry["description"] === "string" ? entry["description"].slice(0, 80) : "";
+        return `${entry["type"]} -> <${entry["tag"]}>: ${desc}`;
+      }).join("\n");
+      return { content: [{ type: "text", text: summary }] };
+    }
+  );
+  server.tool(
+    "check_anti_patterns",
+    "Check HTML against all anti-patterns. Returns only violations.",
+    {
+      html: z.string().describe("HTML string to check")
+    },
+    async ({ html }) => {
+      const violations = checkAllAntiPatterns(html);
+      return { content: [{ type: "text", text: JSON.stringify(violations, null, 2) }] };
+    }
+  );
+  server.tool(
+    "get_traits",
+    "Get the trait catalog, optionally filtered by category.",
+    {
+      category: z.string().optional().describe('Trait category filter (e.g., "input-interaction", "motion-positioning")')
+    },
+    async ({ category }) => {
+      const traits = category ? getTraitsByCategory(category) : getTraits();
+      return { content: [{ type: "text", text: JSON.stringify(traits, null, 2) }] };
+    }
+  );
+  server.tool(
+    "assemble_context",
+    `Assemble progressive-disclosure context for a given intent and budget tier. Returns domain-relevant components, matching patterns, and anti-patterns.
+
+Tier 0: domain only. Tier 1: components. Tier 2: +patterns. Tier 3: +anti-patterns. Tier 4: full catalog.
+
+Use this when you want to manually compose A2UI output rather than using generate_ui. The returned context gives you the building blocks.`,
+    {
+      intent: z.string().describe("Natural language intent"),
+      tier: z.number().min(0).max(4).optional().describe("Budget tier 0-4 (default: 1)")
+    },
+    async ({ intent, tier }) => {
+      const result = assembleContext({ intent, tier: tier ?? 1 });
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+  );
+  server.tool(
+    "convert_html",
+    "Convert HTML markup to A2UI flat adjacency component messages. Maps HTML tags to AdiaUI components, infers layout from styles, enforces Card content model.",
+    {
+      html: z.string().describe("HTML markup to convert"),
+      mode: z.enum(["instant", "reasoning"]).optional().describe("instant = rules only, reasoning = LLM for complex layouts")
+    },
+    async ({ html, mode }) => {
+      try {
+        const result = await transpileHTML(html, { mode: mode ?? "instant" });
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        return { content: [{ type: "text", text: `Transpile error: ${e.message}` }], isError: true };
+      }
+    }
+  );
+  server.tool(
+    "get_wiring_catalog",
+    "Get the AdiaUI wiring catalog: available controllers, action handlers, refresh strategies, value sources, and association types.",
+    {},
+    async () => {
+      const catalog = getWiringCatalog();
+      return { content: [{ type: "text", text: JSON.stringify(catalog, null, 2) }] };
+    }
+  );
+}
+export {
+  registerValidationTools
+};

package/tools/zettel.js

@@ -0,0 +1,87 @@
+import { z } from "zod";
+import {
+  getComposition as getZettelComposition,
+  getAllCompositions as getAllZettelCompositions,
+  getGraph as getZettelGraph,
+  searchAll as searchCompositions
+} from "../../compose/strategies/zettel/composition-library.js";
+import {
+  resolveComposition as resolveZettelComposition,
+  templateToMessages as zettelTemplateToMessages
+} from "../../compose/strategies/zettel/composer.js";
+function registerZettelTools(server) {
+  server.tool(
+    "search_patterns",
+    `Search the composition library for reusable UI templates. Returns matching compositions with full A2UI component trees that can be used directly or adapted.
+
+Use this to find a starting point before generating from scratch. If a good composition exists, pass it to generate_ui with instant mode. If no composition matches, use generate_ui with thinking mode.
+
+Keyword search (\xA764 v0.4.6 migration: now backed by composition-library; the historical "pattern" library is retired).`,
+    {
+      query: z.string().describe("Search query (natural language)")
+    },
+    async ({ query }) => {
+      const results = searchCompositions(query);
+      return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
+    }
+  );
+  server.tool(
+    "get_composition",
+    "Fetch a composition by name. Returns the flat A2UI template (compositions are pre-inlined; no $fragment refs). Zettel-only.",
+    { name: z.string() },
+    async ({ name }) => {
+      const c = getZettelComposition(name);
+      if (!c) return { content: [{ type: "text", text: `Composition not found: ${name}` }], isError: true };
+      return { content: [{ type: "text", text: JSON.stringify(c, null, 2) }] };
+    }
+  );
+  server.tool(
+    "resolve_composition",
+    "Return the flat A2UI template + updateComponents messages for a composition. Zettel-only. (Pre-inlined since \xA737 \u2014 `resolve` is now a defensive copy + strip pass.)",
+    { name: z.string() },
+    async ({ name }) => {
+      const c = getZettelComposition(name);
+      if (!c) return { content: [{ type: "text", text: `Composition not found: ${name}` }], isError: true };
+      const template = resolveZettelComposition(c);
+      const messages = zettelTemplateToMessages(template);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ template, messages }, null, 2)
+        }]
+      };
+    }
+  );
+  server.tool(
+    "get_graph",
+    "Return the composition catalog. Zettel-only. (Backlinks to fragments retired in \xA737; only composition nodes remain.)",
+    {},
+    async () => ({ content: [{ type: "text", text: JSON.stringify(getZettelGraph(), null, 2) }] })
+  );
+  server.tool(
+    "zettel_stats",
+    "Zettel corpus stats \u2014 composition count + average node count. (Fragment stats retired in \xA737.)",
+    {},
+    async () => {
+      const comps = getAllZettelCompositions();
+      const totalNodes = comps.reduce((s, c) => {
+        const comp = c;
+        const tpl = comp["template"];
+        return s + (Array.isArray(tpl) ? tpl.length : 0);
+      }, 0);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({
+            compositions: comps.length,
+            avg_nodes_per_composition: comps.length ? Math.round(totalNodes / comps.length) : 0,
+            total_nodes: totalNodes
+          }, null, 2)
+        }]
+      };
+    }
+  );
+}
+export {
+  registerZettelTools
+};