@adia-ai/a2ui-mcp 0.0.1

package/server.js

@@ -0,0 +1,573 @@
+#!/usr/bin/env node
+
+/**
+ * AdiaUI MCP Server
+ *
+ * Exposes A2UI generative tools via MCP protocol.
+ * Runs as a stdio server for Claude Desktop / Claude Code.
+ *
+ * Tools:
+ *   generate_ui       — Generate A2UI components from intent
+ *   validate_schema   — Validate A2UI messages
+ *   lookup_component  — Component API lookup
+ *   get_component_map — Full catalog
+ *   search_patterns   — Pattern library search
+ *   classify_intent   — Domain classification
+ *
+ * Usage:
+ *   node packages/a2ui/mcp/server.js
+ */
+
+// ── Load .env for API keys (Node doesn't read .env automatically) ──
+import '../../scripts/load-env.mjs';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+
+// ── Import from a2ui ──
+import { generateUI } from '../compose/engine/generator.js';
+import { validateSchema } from '../validator/validator.js';
+import { validateMessages as validateCatalogMessages } from '../validator/catalog-validator.js';
+import {
+  getCatalog,
+  getComponent,
+  getComponentsByCategory,
+  getTraits,
+  getTraitsByCategory,
+  getFullCatalog,
+} from '../retrieval/catalog.js';
+import { serializeEntry } from '../retrieval/component-entry.js';
+import { classifyIntent, getDomain, getAllDomains } from '../retrieval/domain-router.js';
+import { getPattern, searchPatterns, getAllPatterns } from '../retrieval/pattern-library.js';
+import { getAntiPatterns, checkAllAntiPatterns } from '../retrieval/anti-patterns.js';
+import { assembleContext } from '../retrieval/context-assembler.js';
+
+// ── Zettel (fragment-graph) engine ──
+import {
+  loadAll as loadZettelCorpus,
+  getFragment as getZettelFragment,
+  getComposition as getZettelComposition,
+  getAllFragments as getAllZettelFragments,
+  getAllCompositions as getAllZettelCompositions,
+  searchAll as searchZettelAll,
+  getGraph as getZettelGraph,
+} from '../compose/engines/zettel/fragment-library.js';
+import {
+  resolveComposition as resolveZettelComposition,
+  templateToMessages as zettelTemplateToMessages,
+} from '../compose/engines/zettel/composer.js';
+// Zettel bootstrap is still needed for get_fragment/resolve_composition tools;
+// the generate_ui tool now dispatches through the unified registry in gen-ui.
+
+// Bootstrap zettel corpus alongside the monolithic pattern library
+const _zettelBoot = loadZettelCorpus();
+console.error(
+  `[adiaui-mcp] zettel corpus: ${_zettelBoot.fragmentCount} fragments, ${_zettelBoot.compositionCount} compositions`,
+);
+
+// ── Server ──
+
+const server = new McpServer({
+  name: 'adia-ui',
+  version: '0.1.0',
+});
+
+server.tool(
+  'generate_ui',
+  `Generate A2UI components from a natural language description.
+
+Engine selection:
+- "monolithic" (default) — pattern-match + adapt. Searches a corpus of 96+ pre-authored monolithic templates and adapts the best match. Battle-tested; highest F1 on held-out intents.
+- "zettel" — fragment-graph composer. Composes UI from named atomic fragments (labeled-input, card-header-with-description, etc.) with a precomputed backlink graph. Higher reusability; supports composition-iterated refinement on multi-turn edits.
+
+Mode selection (monolithic only; zettel uses "instant"):
+- "pro" (default) — LLM-powered generation with pattern adaptation.
+- "thinking" — Full LLM-powered generation with semantic search, decomposition, and streaming.
+- "instant" — fast pattern matching, no LLM.
+
+The generator knows 96+ UI patterns across 5 domains: forms, data, layout, agent, navigation.`,
+  {
+    intent: z.string().describe('Description of the UI to generate'),
+    engine: z.enum(['monolithic', 'zettel']).optional().describe('Generation engine. "monolithic" (default) is pattern-match + adapt. "zettel" is fragment-graph composition.'),
+    mode: z.enum(['instant', 'pro', 'thinking']).optional().describe('Generation mode (monolithic). "pro" (default) uses LLM with pattern adaptation. "thinking" uses full LLM generation. "instant" uses fast pattern matching.'),
+    sessionId: z.string().optional().describe('Opaque session identifier for multi-turn iteration (zettel only). When provided, follow-up calls with the same sessionId modify the prior turn\'s canvas instead of regenerating from scratch. Omit for stateless generation.'),
+  },
+  async ({ intent, engine, mode, sessionId }) => {
+    try {
+      const selectedEngine = engine || 'monolithic';
+      const effectiveMode = selectedEngine === 'zettel' ? 'instant' : (mode || 'pro');
+      const result = await generateUI({
+        intent,
+        engine: selectedEngine,
+        mode: effectiveMode,
+        sessionId,
+      });
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            engine: result.engine || selectedEngine,
+            executionId: result.executionId,
+            strategy: result.strategy,
+            messages: result.messages,
+            validation: result.validation,
+            suggestions: result.suggestions,
+            composition: result.composition,
+            fragments_used: result.fragments_used,
+            sessionTurns: result.sessionTurns,
+          }, null, 2),
+        }],
+      };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `Generation error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+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];
+      // 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) {
+      return { content: [{ type: 'text', text: `Parse error: ${err.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 => `${e.type} -> <${e.tag}>: ${e.description?.slice(0, 80) || ''}`)
+      .join('\n');
+    return { content: [{ type: 'text', text: summary }] };
+  }
+);
+
+server.tool(
+  'search_patterns',
+  `Search the pattern library for reusable UI templates. Returns matching patterns 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 pattern exists, pass it to generate_ui with instant mode. If no pattern matches, use generate_ui with thinking mode.
+
+Keyword search by default. Set semantic=true for LLM-powered conceptual matching. Set remix=true to compose a new pattern by combining existing ones.`,
+  {
+    query: z.string().describe('Search query (natural language)'),
+    semantic: z.boolean().optional().describe('Use LLM for conceptual matching (default: false)'),
+    remix: z.boolean().optional().describe('Compose a new pattern by remixing existing ones (default: false)'),
+  },
+  async ({ query, semantic, remix }) => {
+    if (semantic || remix) {
+      const { semanticSearchPatterns } = await import('../a2ui/intelligence/pattern-library.js');
+      const { createAdapter } = await import('../a2ui/llm-bridge.js');
+      try {
+        const adapter = await createAdapter();
+        const results = await semanticSearchPatterns(query, { llmAdapter: adapter, remix });
+        return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+      } catch (err) {
+        // Fall back to keyword search on LLM failure
+        const results = searchPatterns(query);
+        return { content: [{ type: 'text', text: JSON.stringify({ matches: results, note: 'Semantic search unavailable, using keyword fallback' }, null, 2) }] };
+      }
+    }
+    const results = searchPatterns(query);
+    return { content: [{ type: 'text', text: JSON.stringify(results, null, 2) }] };
+  }
+);
+
+server.tool(
+  'classify_intent',
+  'Classify intent into a UI domain.',
+  {
+    text: z.string().describe('Intent text'),
+  },
+  async ({ text }) => {
+    return { content: [{ type: 'text', text: JSON.stringify(classifyIntent(text), 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(
+  '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) }] };
+  }
+);
+
+// ── Transpiler & Wiring Tools ──
+
+import { transpileHTML } from '../compose/transpiler/transpiler.js';
+import { getWiringCatalog } from '../retrieval/wiring-catalog.js';
+
+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) {
+      return { content: [{ type: 'text', text: `Transpile error: ${err.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) }] };
+  }
+);
+
+// ── Pattern & Feedback Tools ──
+
+import { registerPattern } from '../retrieval/pattern-library.js';
+import { FeedbackCollector } from '../retrieval/feedback.js';
+
+const feedbackCollector = new FeedbackCollector();
+
+server.tool(
+  'import_pattern',
+  'Import a saved pattern JSON into the runtime pattern library.',
+  {
+    pattern: z.string().describe('JSON string of pattern object { name, description, domain, components, template }'),
+  },
+  async ({ pattern }) => {
+    try {
+      const parsed = JSON.parse(pattern);
+      if (!parsed.name || !parsed.template || !Array.isArray(parsed.template)) {
+        return { content: [{ type: 'text', text: 'Invalid: must have name and template array' }], isError: true };
+      }
+      const success = registerPattern(parsed);
+      if (!success) {
+        return { content: [{ type: 'text', text: `Pattern "${parsed.name}" already exists` }], isError: true };
+      }
+      return { content: [{ type: 'text', text: JSON.stringify({ imported: parsed.name, components: parsed.components?.length || 0 }) }] };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `Parse error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+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 }) }] };
+  }
+);
+
+// ── Quality metrics tool ──
+
+import { feedbackStore } from '../retrieval/feedback-store.js';
+
+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) }] };
+  }
+);
+
+server.tool(
+  'run_eval',
+  'Run the offline eval harness against the held-out intent set. Returns aggregate scores and per-intent results.',
+  {
+    domain: z.string().optional().describe('Filter by domain (forms, data, layout, agent, navigation)'),
+    limit: z.number().optional().describe('Max intents to evaluate'),
+  },
+  async ({ domain, limit }) => {
+    try {
+      const { runHarness } = await import('../a2ui/evals/harness.mjs');
+      const summary = await runHarness({
+        generate: (args) => generateUI({ intent: args.intent, mode: 'instant' }),
+        domain,
+        limit,
+        mode: 'instant',
+      });
+      return { content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `Eval error: ${err.message}` }], isError: true };
+    }
+  }
+);
+
+// ── Resources ──
+
+server.resource(
+  'catalog',
+  'a2ui://catalog/manifest',
+  async (uri) => {
+    const catalog = await getFullCatalog();
+    const serializable = {
+      version: catalog.version,
+      totalTypes: catalog.totalTypes,
+      totalTraits: catalog.totalTraits,
+      components: [...catalog.entries.values()].map(e => serializeEntry(e, 'summary')),
+      traits: catalog.traits,
+    };
+    return {
+      contents: [{
+        uri: uri.href,
+        mimeType: 'application/json',
+        text: JSON.stringify(serializable, null, 2),
+      }],
+    };
+  }
+);
+
+server.resource(
+  'patterns',
+  'a2ui://catalog/patterns',
+  async (uri) => ({
+    contents: [{
+      uri: uri.href,
+      mimeType: 'application/json',
+      text: JSON.stringify(getAllPatterns(), null, 2),
+    }],
+  })
+);
+
+server.resource(
+  'anti-patterns',
+  'a2ui://catalog/anti-patterns',
+  async (uri) => ({
+    contents: [{
+      uri: uri.href,
+      mimeType: 'application/json',
+      text: JSON.stringify(getAntiPatterns(), null, 2),
+    }],
+  })
+);
+
+server.resource(
+  'domains',
+  'a2ui://catalog/domains',
+  async (uri) => {
+    const domains = getAllDomains().map(name => ({
+      name,
+      ...getDomain(name),
+    }));
+    return {
+      contents: [{
+        uri: uri.href,
+        mimeType: 'application/json',
+        text: JSON.stringify(domains, null, 2),
+      }],
+    };
+  }
+);
+
+// ── Zettel-only tools (fragment-graph inspection) ────────────────────────
+
+server.tool(
+  'get_fragment',
+  'Fetch a fragment (A2UI chunk + metadata + slots + backlinks) by name. Zettel-only.',
+  { name: z.string() },
+  async ({ name }) => {
+    const f = getZettelFragment(name);
+    if (!f) return { content: [{ type: 'text', text: `Fragment not found: ${name}` }], isError: true };
+    return { content: [{ type: 'text', text: JSON.stringify(f, null, 2) }] };
+  },
+);
+
+server.tool(
+  'get_composition',
+  'Fetch a composition by name. Returns the fragment-referencing template (not yet resolved). 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',
+  'Expand a composition into a flat A2UI template ($fragment refs resolved, slot bindings applied). Returns both the template and updateComponents messages. Zettel-only.',
+  { 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 full backlink graph — fragments with their used_by lists, compositions with their uses_fragments lists. Use this to answer: what uses this fragment? what fragments does this composition depend on? Zettel-only.',
+  {},
+  async () => ({ content: [{ type: 'text', text: JSON.stringify(getZettelGraph(), null, 2) }] }),
+);
+
+server.tool(
+  'zettel_stats',
+  'Zettel corpus stats — fragment/composition counts, top fragments by leverage, orphans.',
+  {},
+  async () => {
+    const frags = getAllZettelFragments();
+    const comps = getAllZettelCompositions();
+    const byLeverage = [...frags]
+      .sort((a, b) => (b.metrics?.leverage || 0) - (a.metrics?.leverage || 0))
+      .slice(0, 10)
+      .map((f) => ({ name: f.name, leverage: f.metrics?.leverage || 0, used_by: (f.links?.used_by || []).length }));
+    const orphans = frags.filter((f) => !(f.links?.used_by || []).length).map((f) => f.name);
+    return {
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          fragments: frags.length,
+          compositions: comps.length,
+          top_leverage: byLeverage,
+          orphans,
+        }, null, 2),
+      }],
+    };
+  },
+);
+
+// ── Start ──
+
+async function main() {
+  const transport = new StdioServerTransport();
+
+  // Auto-ingest training data into pattern library
+  try {
+    const { ingestAll } = await import('../corpus/scripts/ingest.js');
+    const result = await ingestAll();
+    if (result.registered > 0 || result.replaced > 0) {
+      console.error(`Training: ingested ${result.registered} new + ${result.replaced} replaced patterns (${result.pages} pages, ${result.chunks} chunks)`);
+    }
+  } catch (e) {
+    console.error(`Training: ingest skipped — ${e.message}`);
+  }
+
+  await server.connect(transport);
+  const catalog = await getCatalog();
+  const patterns = getAllPatterns();
+  const traits = getTraits();
+  console.error(`AdiaUI MCP Server running (${catalog.totalTypes} components, ${patterns.length} patterns, ${traits.length} traits, ${_zettelBoot.fragmentCount} zettel fragments, ${_zettelBoot.compositionCount} compositions)`);
+}
+
+main().catch(console.error);