@adia-ai/a2ui-mcp 0.6.4 → 0.6.6

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/validation.ts

@@ -0,0 +1,153 @@
+/**
+ * Validation tools — schema validation, component lookup, catalog, anti-patterns,
+ * traits, context assembly, HTML transpilation, and wiring catalog.
+ *
+ * Extracted from server.ts. Registers:
+ *   validate_schema, lookup_component, get_component_map, check_anti_patterns,
+ *   get_traits, assemble_context, convert_html, get_wiring_catalog
+ */
+
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+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';
+
+export function registerValidationTools(server: McpServer): void {
+  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) as unknown;
+        const msgs = Array.isArray(parsed) ? parsed : [parsed];
+        // Two orthogonal checks:
+        //   1. scored — weighted heuristic validator (intent alignment, card model, etc.)
+        //   2. catalog — AJV against v0.9 catalog schema (type-level structural correctness)
+        // Both run; results returned together so callers see structural + quality signal.
+        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 as Record<string, unknown>;
+          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) }] };
+    }
+  );
+}

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
+};

package/tools/zettel.ts

@@ -0,0 +1,98 @@
+/**
+ * Zettel composition-inspection tools.
+ *
+ * Extracted from server.ts. Registers:
+ *   get_composition, resolve_composition, get_graph, zettel_stats, search_patterns
+ */
+
+import { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+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';
+
+export function registerZettelTools(server: McpServer): void {
+  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 (§64 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 §37 — `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 §37; only composition nodes remain.)',
+    {},
+    async () => ({ content: [{ type: 'text', text: JSON.stringify(getZettelGraph(), null, 2) }] }),
+  );
+
+  server.tool(
+    'zettel_stats',
+    'Zettel corpus stats — composition count + average node count. (Fragment stats retired in §37.)',
+    {},
+    async () => {
+      const comps = getAllZettelCompositions();
+      const totalNodes = comps.reduce((s, c) => {
+        const comp = c as Record<string, unknown>;
+        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),
+        }],
+      };
+    },
+  );
+}