@adia-ai/a2ui-mcp 0.0.1 → 0.0.2

package/CHANGELOG.md

@@ -9,8 +9,71 @@ zettel strategies.
 
 ## [Unreleased]
 
-### Changed
-- Registry / transpilation scripts at `packages/web-components/scripts/a2ui-to-html.cjs` and `packages/web-components/scripts/mcp-pipeline.cjs` now mirror the canonical `packages/web-components/a2ui/registry.js` for all A2UI component → custom-element mappings. Previously these scripts had several stale mappings that diverged from the runtime registry.
+---
+
+## [0.0.2] - 2026-04-28
+
+Adds **gen-UI training-chunk tools** that expose the new chunk corpus
+(shipped in `@adia-ai/a2ui-corpus@0.0.3`) via the MCP transport. Also
+adds a chunk-aware composition synthesizer that mixes-and-matches chunks
+when retrieval can't find a 1:1 match — the LLM picks a page chunk + binds
+block/panel chunks to its slots, validated against the chunk catalog
+before HTML is materialized.
+
+### Added (MCP tools)
+
+- **`search_chunks(query, kind?, limit?)`** — keyword search over the
+  chunk corpus. Filters by `kind` (`block` | `panel` | `page`); returns
+  ranked candidates with relevance score, primary tag, and chunk name.
+- **`get_chunk(name)`** — full record for a single chunk by name. For
+  reusable slot chunks (e.g. `auth-card-header`, `reg-step-header`)
+  returns an `instances` array — one entry per page.
+- **`lookup_chunk(component_name)`** — 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."
+- **`compose_from_chunks(intent?, plan?, max_attempts?)`** — two-tier
+  composition tool: retrieval-first (returns matched chunk HTML
+  directly), synthesis-fallback (LLM picks a page chunk + binds
+  block/panel chunks to its slots when retrieval is weak). The
+  synthesizer mirrors the existing fragment synthesizer's prompt
+  pattern, repointed at the chunk catalog. Pre-search filters the
+  catalog to ~30 candidates before the LLM sees them. Plan-only
+  invocation skips the LLM and just materializes HTML from a
+  pre-baked binding.
+
+### Added (engine internals)
+
+- `packages/a2ui/compose/engines/zettel/chunk-composer.js` —
+  HTML-string-level composer that walks a page chunk and substitutes
+  each `data-chunk-slot` region with the bound block-level chunks'
+  HTML. Companion `validatePlan()` checks slot names + chunk-kind
+  contracts before composition.
+- `packages/a2ui/compose/engines/zettel/chunk-synthesizer.js` —
+  LLM-driven mix-and-match composition; pre-searches the catalog,
+  builds a prompt with a one-shot in-context example, validates the
+  LLM's binding plan against the catalog, retries with feedback on
+  validation failure (default 2 attempts).
+
+### Smoke
+
+- `npm run smoke:chunks` (33/33 passing, 2026-04-28) — covers
+  chunk-library indexing, retrieval scoring, plan validation, plan
+  composition, and synthesis fallback path with a stub LLM adapter.
+
+### Convention reference
+
+- Spec: [`docs/specs/genui-chunk-marker.md`](../../../docs/specs/genui-chunk-marker.md).
+- Plan: [`docs/plans/training-pipeline-chunk-harvest-2026-04-27.md`](../../../docs/plans/training-pipeline-chunk-harvest-2026-04-27.md).
+
+### Other
+
+- Registry / transpilation scripts at
+  `packages/web-components/scripts/a2ui-to-html.cjs` and
+  `packages/web-components/scripts/mcp-pipeline.cjs` now mirror the
+  canonical `packages/web-components/a2ui/registry.js` for all A2UI
+  component → custom-element mappings. Previously these scripts had
+  several stale mappings that diverged from the runtime registry.
 
 ---
 

package/README.md

@@ -6,9 +6,9 @@ feedback loop as stdio tools for Claude Desktop, Claude Code, and any
 other MCP-speaking host.
 
 > Runtime only. Generation logic lives in `@adia-ai/a2ui-compose`; UI atoms in
-> [`@adia-ai/web-components`](../web-components); the A2UI protocol runtime
+> [`@adia-ai/web-components`](../../web-components); the A2UI protocol runtime
 > (renderer, registry, streams, wiring) in
-> [`@adia-ai/a2ui-utils`](../a2ui/utils); corpus in
+> [`@adia-ai/a2ui-utils`](../utils); corpus in
 > [`@adia-ai/a2ui-corpus`](../corpus).
 
 ## Quick start
@@ -116,12 +116,12 @@ npm run eval:diff -- --engine zettel
   └─────────────┘                      │
                                        ├── @adia-ai/a2ui-compose          (engines, validator, LLM bridge)
                                        ├── @adia-ai/a2ui-corpus (catalog, fragments, feedback)
-                                       └── @adiahealth/web-components  (component schemas via .a2ui.json)
+                                       └── @adia-ai/web-components  (component schemas via .a2ui.json)
 ```
 
 On start, the server:
 
-1. Loads the component catalog (`gen-ui-training/catalog-a2ui_0_9.json`)
+1. Loads the component catalog (`@adia-ai/a2ui-corpus/catalog-a2ui_0_9.json`)
 2. Lazy-initializes the zettel corpus on first `generate_ui`/`zettel_*` call
 3. Resolves LLM adapter from env vars
 4. Registers tools + opens stdio transport

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-mcp",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "AdiaUI A2UI MCP server. Exposes the compose engine over MCP with an engine selector for monolithic + zettel strategies.",
   "type": "module",
   "bin": {
@@ -29,7 +29,7 @@
     "@adia-ai/a2ui-compose": "^0.0.1",
     "@adia-ai/a2ui-retrieval": "^0.0.1",
     "@adia-ai/a2ui-validator": "^0.0.1",
-    "@adia-ai/a2ui-corpus": "^0.0.1",
+    "@adia-ai/a2ui-corpus": "^0.0.3",
     "zod": "^3.24.0"
   }
 }

package/scripts/test-chunks.mjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+/**
+ * Smoke test for the gen-UI chunk MCP tools.
+ *
+ * Tests search_chunks / get_chunk / lookup_chunk against known chunks
+ * harvested from site/pages/* and corpus/exemplars/*.
+ *
+ * Wired into:
+ *   - npm run smoke:chunks
+ *   - Phase D verification gate (docs/plans/training-pipeline-chunk-harvest-2026-04-27.md)
+ */
+
+import {
+  getChunk,
+  getChunkIndex,
+  lookupChunksByPrimary,
+  searchChunks,
+} from '../../corpus/scripts/chunk-library.js';
+
+let passed = 0;
+let failed = 0;
+const failures = [];
+
+function assert(name, cond, detail) {
+  if (cond) { passed++; console.log(`  ✓ ${name}`); }
+  else { failed++; failures.push(`${name}: ${detail || 'failed'}`); console.log(`  ✗ ${name}: ${detail || 'failed'}`); }
+}
+
+console.log('── chunk-library smoke ──');
+
+const idx = getChunkIndex();
+assert('index loaded', idx && idx.unique_names > 0, idx ? `got ${idx.unique_names}` : 'no index');
+assert('expected counts', idx && idx.unique_names >= 700 && idx.total_instances >= 800,
+  idx ? `${idx.unique_names} unique / ${idx.total_instances} instances (need ≥700/800)` : 'no index');
+assert('by_kind covers block + panel + page', idx && idx.by_kind.block && idx.by_kind.panel && idx.by_kind.page,
+  idx ? JSON.stringify(idx.by_kind) : 'no index');
+
+console.log('\n── get_chunk ──');
+
+const signin = getChunk('auth-signin-card-email');
+assert('get_chunk(auth-signin-card-email) returns record', signin && signin.name === 'auth-signin-card-email');
+assert('record has primary=card-ui', signin && signin.primary === 'card-ui',
+  signin ? `got primary=${signin.primary}` : '');
+assert('record HTML is non-empty', signin && typeof signin.html === 'string' && signin.html.length > 100);
+
+const kpi = getChunk('dashboard-kpi-grid');
+assert('get_chunk(dashboard-kpi-grid) returns record', kpi && kpi.name === 'dashboard-kpi-grid');
+assert('kpi primary=grid-ui', kpi && kpi.primary === 'grid-ui',
+  kpi ? `got primary=${kpi.primary}` : '');
+
+const adminPage = getChunk('dashboard-admin-page');
+assert('get_chunk(dashboard-admin-page) returns record', adminPage && adminPage.name === 'dashboard-admin-page');
+assert('admin-page is kind=page', adminPage && adminPage.kind === 'page',
+  adminPage ? `got kind=${adminPage.kind}` : '');
+assert('admin-page declares page-header + page-content slots',
+  adminPage && (adminPage.slots || []).map(s => s.name).includes('page-header') &&
+  (adminPage.slots || []).map(s => s.name).includes('page-content'),
+  adminPage ? JSON.stringify((adminPage.slots || []).map(s => s.name)) : '');
+
+const reusable = getChunk('reg-step-header');
+assert('reusable slot chunk has instances array', reusable && Array.isArray(reusable.instances) && reusable.instances.length >= 18,
+  reusable ? `instances=${reusable.instances?.length}` : '');
+
+const missing = getChunk('definitely-does-not-exist');
+assert('non-existent chunk returns null', missing === null);
+
+console.log('\n── search_chunks ──');
+
+const results = searchChunks('dashboard');
+assert('search_chunks(dashboard) returns ≥10', results.length >= 10, `got ${results.length}`);
+assert('search results sorted by score', results.length === 0 || results.every((r, i, a) => i === 0 || a[i - 1].score >= r.score));
+
+const blockOnly = searchChunks('dashboard', { kind: 'block' });
+assert('kind=block filter excludes pages', blockOnly.every((r) => r.kind === 'block'));
+
+const auth = searchChunks('auth signin');
+assert('search_chunks(auth signin) finds auth-signin-card-email',
+  auth.some((r) => r.name === 'auth-signin-card-email'));
+
+const code = searchChunks('code language');
+assert('search_chunks(code language) finds code-language', code.some((r) => r.name === 'code-language'));
+
+console.log('\n── lookup_chunk ──');
+
+const cardChunks = lookupChunksByPrimary('card-ui');
+assert('lookup_chunk(card-ui) returns ≥5', cardChunks.length >= 5, `got ${cardChunks.length}`);
+assert('all card-ui chunks have primary=card-ui', cardChunks.every((c) => c.primary === 'card-ui'));
+
+const drawerChunks = lookupChunksByPrimary('drawer-ui');
+assert('lookup_chunk(drawer-ui) returns ≥10', drawerChunks.length >= 10, `got ${drawerChunks.length}`);
+
+const articleChunks = lookupChunksByPrimary('article');
+assert('lookup_chunk(article) finds dashboard-admin-page',
+  articleChunks.some((c) => c.name === 'dashboard-admin-page'));
+
+// ── chunk-composer + chunk-synthesizer ──
+import { composeFromPlan, validatePlan } from '../../compose/engines/zettel/chunk-composer.js';
+import { composeFromIntent } from '../../compose/engines/zettel/chunk-synthesizer.js';
+
+console.log('\n── validatePlan ──');
+
+const goodPlan = {
+  page: 'dashboard-admin-page',
+  slot_bindings: {
+    'page-header': 'dashboard-page-header',
+    'page-content': ['dashboard-overview-panel', 'dashboard-funnel'],
+  },
+};
+const v1 = validatePlan(goodPlan);
+assert('validatePlan(goodPlan) ok', v1.ok, JSON.stringify(v1.errors));
+
+const badPagePlan = { page: 'definitely-not-real', slot_bindings: {} };
+const v2 = validatePlan(badPagePlan);
+assert('validatePlan(bad page) fails', !v2.ok && v2.errors.length > 0);
+
+const badSlotPlan = {
+  page: 'dashboard-admin-page',
+  slot_bindings: { 'made-up-slot': 'dashboard-funnel' },
+};
+const v3 = validatePlan(badSlotPlan);
+assert('validatePlan(undeclared slot) fails', !v3.ok && v3.errors.some((e) => e.includes('slot')));
+
+const badBoundPlan = {
+  page: 'dashboard-admin-page',
+  slot_bindings: { 'page-content': 'no-such-chunk' },
+};
+const v4 = validatePlan(badBoundPlan);
+assert('validatePlan(bad bound chunk) fails', !v4.ok && v4.errors.some((e) => e.includes('not found')));
+
+console.log('\n── composeFromPlan ──');
+
+const composed = composeFromPlan(goodPlan);
+assert('composeFromPlan returns html', composed.html && composed.html.length > 1000,
+  composed.html ? `len=${composed.html.length}` : 'null');
+assert('composed html includes admin-page wrapper', composed.html && composed.html.includes('dashboard-admin-page'));
+assert('composed html injects funnel content',
+  composed.html && composed.html.includes('Conversion funnel'),
+  composed.html ? 'no funnel text found' : 'no html');
+
+console.log('\n── composeFromIntent (retrieval-first, no LLM) ──');
+
+// Use a stub adapter — synthesis path shouldn't be hit when retrieval matches
+const stubLLM = { complete: async () => ({ content: '{"page":"dashboard-admin-page","slot_bindings":{"page-content":["dashboard-funnel"]}}' }) };
+
+const direct = await composeFromIntent({ intent: 'dashboard-kpi-grid', llmAdapter: stubLLM });
+assert('retrieval direct hit returns html', direct.html && direct.html.length > 50,
+  direct.warnings?.join('; '));
+assert('retrieval source labeled correctly', direct.source === 'retrieval',
+  `got ${direct.source}`);
+
+const synthesized = await composeFromIntent({ intent: 'admin dashboard with KPIs', llmAdapter: stubLLM });
+assert('synthesis path produces html when retrieval is weak',
+  synthesized.html && synthesized.html.length > 1000,
+  synthesized.warnings?.join('; ') || 'no html');
+// Source could be either retrieval or synthesis depending on score — both are
+// acceptable as long as we got HTML out.
+assert('synthesis source labeled', ['retrieval', 'synthesis'].includes(synthesized.source));
+
+console.log(`\n${passed} passed, ${failed} failed`);
+if (failed) {
+  console.log('\nFailures:');
+  for (const f of failures) console.log(`  ${f}`);
+  process.exit(1);
+}

package/server.js

@@ -19,7 +19,7 @@
  */
 
 // ── Load .env for API keys (Node doesn't read .env automatically) ──
-import '../../scripts/load-env.mjs';
+import '../../../scripts/load-env.mjs';
 
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -66,6 +66,23 @@ console.error(
   `[adiaui-mcp] zettel corpus: ${_zettelBoot.fragmentCount} fragments, ${_zettelBoot.compositionCount} compositions`,
 );
 
+// ── Gen-UI training-chunk corpus ──
+import {
+  getChunk as getGenUIChunk,
+  getChunkIndex,
+  lookupChunksByPrimary,
+  searchChunks as searchGenUIChunks,
+} from '../corpus/scripts/chunk-library.js';
+
+const _chunkIndex = getChunkIndex();
+if (_chunkIndex) {
+  console.error(
+    `[adiaui-mcp] gen-ui chunks: ${_chunkIndex.unique_names} unique chunks (${_chunkIndex.total_instances} instances; block=${_chunkIndex.by_kind.block || 0}, panel=${_chunkIndex.by_kind.panel || 0}, page=${_chunkIndex.by_kind.page || 0})`,
+  );
+} else {
+  console.error('[adiaui-mcp] gen-ui chunks: index not found — run `npm run harvest:chunks`');
+}
+
 // ── Server ──
 
 const server = new McpServer({
@@ -547,6 +564,189 @@ server.tool(
   },
 );
 
+// ── Gen-UI training-chunk tools ──────────────────────────────────────
+// Spec: docs/specs/genui-chunk-marker.md (Draft v0.1.0).
+// Plan: docs/plans/training-pipeline-chunk-harvest-2026-04-27.md.
+
+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) => ({
+            name: r.name,
+            kind: r.kind,
+            page: r.page || r.instances?.[0]?.page,
+            slots: (r.slots || r.instances?.[0]?.slots || []).map((s) => s.name),
+            nested: r.nested || r.instances?.[0]?.nested || [],
+          })),
+        }, null, 2),
+      }],
+    };
+  },
+);
+
+// ── Chunk-aware composition synthesizer (Phase C.2) ──────────────────
+// Mix-and-match: when retrieval returns no strong match, the LLM picks a
+// page chunk + binds block/panel chunks to its slots. Validator checks
+// chunk names + kind contracts; composer materializes to HTML.
+//
+// Spec: docs/specs/genui-chunk-marker.md (§ "Harvester contract", future:
+// composition reasoning). Plan: docs/plans/training-pipeline-chunk-harvest-2026-04-27.md.
+
+import { composeFromIntent as composeFromChunksImpl } from '../compose/engines/zettel/chunk-synthesizer.js';
+import { composeFromPlan, validatePlan } from '../compose/engines/zettel/chunk-composer.js';
+import { createAdapter as createLLMAdapter } from '../compose/llm/llm-bridge.js';
+
+server.tool(
+  'compose_from_chunks',
+  `Compose a UI page from training chunks — retrieval-first, synthesis-fallback.
+
+Mix-and-match composition for intents that don't have a 1:1 chunk match. Workflow:
+  1. Pure-retrieval tier: if \`search_chunks\` returns a strong direct match, return
+     that chunk's HTML immediately (no LLM call).
+  2. Synthesis tier: when retrieval is weak, the LLM picks a page-kind chunk and
+     binds block/panel chunks to its named slots. Output validated against the
+     chunk catalog (slot names exist, bound chunks exist, kinds match).
+
+Returns the composed HTML string + a binding plan describing which chunks plug
+where. Useful when the prompt is novel ("dashboard with KPI grid + funnel +
+country list") and no exact chunk has all those parts together — the LLM mixes
+and matches from the corpus.
+
+Two-call mode also available via \`plan\` parameter — pass a pre-baked binding
+plan to skip the LLM call and just materialize HTML.`,
+  {
+    intent: z.string().optional().describe('Natural-language description of what to build (uses LLM synthesis)'),
+    plan: z.object({
+      page: z.string(),
+      slot_bindings: z.record(z.union([z.string(), z.array(z.string())])),
+    }).optional().describe('Pre-baked binding plan (skips LLM, materializes directly)'),
+    max_attempts: z.number().int().min(1).max(5).default(2).describe('LLM retry budget for synthesis'),
+  },
+  async ({ intent, plan, max_attempts }) => {
+    if (plan) {
+      const validation = validatePlan(plan);
+      if (!validation.ok) {
+        return {
+          isError: true,
+          content: [{ type: 'text', text: JSON.stringify({ error: 'invalid plan', errors: validation.errors }, null, 2) }],
+        };
+      }
+      const result = composeFromPlan(plan);
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          html: result.html,
+          plan: result.plan,
+          warnings: result.warnings,
+          source: 'plan',
+        }, null, 2) }],
+      };
+    }
+
+    if (!intent) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: 'must provide either intent or plan' }, null, 2) }],
+      };
+    }
+
+    try {
+      const llmAdapter = await createLLMAdapter();
+      const result = await composeFromChunksImpl({
+        intent,
+        llmAdapter,
+        maxAttempts: max_attempts,
+      });
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          html: result.html,
+          plan: result.plan,
+          source: result.source,
+          score: result.score,
+          warnings: result.warnings,
+          synthesis: result.synthesis ? { attempts: result.synthesis.attempts } : undefined,
+        }, null, 2) }],
+      };
+    } catch (e) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: e.message }, null, 2) }],
+      };
+    }
+  },
+);
+
 // ── Start ──
 
 async function main() {