@adia-ai/mcp 0.8.37

package/gen-ui/tools/corpus.js

@@ -0,0 +1,169 @@
+import { defineResource } from "@adia-ai/agent";
+import { zodShape } from "./schema-to-zod.js";
+import {
+  getChunk as getGenUIChunk,
+  lookupChunksByPrimary,
+  searchChunks as searchGenUIChunks
+} from "@adia-ai/gen-ui/corpus/chunk-library";
+const SEARCH_CHUNKS_DESCRIPTION = `Search the gen-UI training-chunk corpus by keyword.
+
+The chunk corpus comes from \`packages/gen-ui/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.`;
+const GET_CHUNK_DESCRIPTION = `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.`;
+const LOOKUP_CHUNK_DESCRIPTION = `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.`;
+const DEFAULT_SEARCH_LIMIT = 20;
+const MAX_SEARCH_LIMIT = 50;
+function searchChunksRead(input = {}) {
+  const query = String(input["query"] ?? "");
+  const kind = input["kind"];
+  const requested = input["limit"] ?? DEFAULT_SEARCH_LIMIT;
+  const limit = Math.min(MAX_SEARCH_LIMIT, Math.max(1, requested));
+  const results = searchGenUIChunks(query, { kind, limit });
+  return { query, kind: kind ?? "any", count: results.length, results };
+}
+function getChunkRead(input = {}) {
+  const name = String(input["name"] ?? "");
+  const rec = getGenUIChunk(name);
+  return rec ?? { error: "chunk not found", name };
+}
+function lookupChunkRead(input = {}) {
+  const component = String(input["component_name"] ?? "");
+  const recs = lookupChunksByPrimary(component);
+  return {
+    component,
+    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
+      };
+    })
+  };
+}
+const CORPUS_RESOURCES = [
+  defineResource({
+    name: "search_chunks",
+    description: SEARCH_CHUNKS_DESCRIPTION,
+    mode: "tool",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Keyword query \u2014 chunk name fragment, intent words, primary-tag name" },
+        kind: { type: "string", enum: ["block", "panel", "page"], description: "Filter by chunk kind" },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: 50,
+          default: DEFAULT_SEARCH_LIMIT,
+          description: "Max results"
+        }
+      },
+      required: ["query"]
+    },
+    get: searchChunksRead
+  }),
+  defineResource({
+    name: "get_chunk",
+    description: GET_CHUNK_DESCRIPTION,
+    mode: "tool",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: 'The chunk name, e.g. "dashboard-kpi-grid", "auth-signin-card-email", "code-language"' }
+      },
+      required: ["name"]
+    },
+    get: getChunkRead
+  }),
+  defineResource({
+    name: "lookup_chunk",
+    description: LOOKUP_CHUNK_DESCRIPTION,
+    mode: "tool",
+    inputSchema: {
+      type: "object",
+      properties: {
+        component_name: { type: "string", description: 'Component tag name, e.g. "card-ui", "grid-ui", "drawer-ui"' }
+      },
+      required: ["component_name"]
+    },
+    get: lookupChunkRead
+  })
+];
+const RESOURCE = Object.fromEntries(CORPUS_RESOURCES.map((r) => [r.name, r]));
+function argsOf(name) {
+  const resource = RESOURCE[name];
+  if (!resource?.inputSchema) throw new Error(`registerCorpusTools: no inputSchema for "${name}"`);
+  return zodShape(resource.inputSchema);
+}
+function registerCorpusTools(server) {
+  server.tool(
+    "search_chunks",
+    SEARCH_CHUNKS_DESCRIPTION,
+    argsOf("search_chunks"),
+    async ({ query, kind, limit }) => ({
+      content: [{
+        type: "text",
+        text: JSON.stringify(searchChunksRead({ query, kind, limit }), null, 2)
+      }]
+    })
+  );
+  server.tool(
+    "get_chunk",
+    GET_CHUNK_DESCRIPTION,
+    argsOf("get_chunk"),
+    async ({ name }) => {
+      const rec = getChunkRead({ name });
+      if (rec["error"]) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: JSON.stringify(rec, null, 2) }]
+        };
+      }
+      return { content: [{ type: "text", text: JSON.stringify(rec, null, 2) }] };
+    }
+  );
+  server.tool(
+    "lookup_chunk",
+    LOOKUP_CHUNK_DESCRIPTION,
+    argsOf("lookup_chunk"),
+    async ({ component_name }) => ({
+      content: [{
+        type: "text",
+        text: JSON.stringify(lookupChunkRead({ component_name }), null, 2)
+      }]
+    })
+  );
+}
+export {
+  CORPUS_RESOURCES,
+  registerCorpusTools
+};

package/gen-ui/tools/discovery.js

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { getCatalog } from "@adia-ai/gen-ui/retrieval/catalog";
+import {
+  getAllCompositions
+} from "@adia-ai/gen-ui/compose/strategies/zettel/composition-library";
+import { getChunk, getChunkIndex } from "@adia-ai/gen-ui/corpus/chunk-library";
+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/gen-ui/tools/feedback.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { FeedbackCollector } from "@adia-ai/gen-ui/retrieval/feedback/feedback";
+import { feedbackStore } from "@adia-ai/gen-ui/retrieval/feedback/feedback-store";
+import { submitFeedback } from "@adia-ai/gen-ui/retrieval/feedback/submit-feedback";
+import { WEIGHTING_RULE } from "@adia-ai/gen-ui/retrieval/feedback/human-signal";
+const feedbackCollector = new FeedbackCollector();
+function registerFeedbackTools(server) {
+  server.tool(
+    "submit_feedback",
+    // ADR-0048 P4 / gh#1222: second paragraph recovered from the hand-edited
+    // TOOLS.md, which no MCP client could read. TOOLS.md is generated from here now.
+    `Submit structured feedback for a generation execution. Used by the evolution engine to learn from each generation.
+
+Persists the rating to \`packages/gen-ui/corpus/feedback/<date>.jsonl\` through the shared \`submitFeedback\` path \u2014 the same one the gen-UI gallery's thumbs affordance posts to (gh#668). Optional \`engine\` / \`strategy\` / \`score\` / \`source\` context is carried onto the stored rating so human signal can rank weak domains.`,
+    {
+      executionId: z.string().describe("Execution ID from generate_ui"),
+      rating: z.number().min(1).max(5).describe("Overall quality 1-5 (>=4 counts as a thumbs-up)"),
+      intent: z.string().optional(),
+      domain: z.string().optional(),
+      // Additive optional context (gh#668) — carried onto the persisted rating
+      // so human signal can rank weak domains without an execution join.
+      engine: z.string().optional().describe("Engine that produced the output (zettel, free-form, \u2026)"),
+      strategy: z.string().optional().describe("Strategy label from the generation result"),
+      score: z.number().optional().describe("Self-graded validator score at generation time"),
+      source: z.string().optional().describe('Where the rating came from; defaults to "mcp"'),
+      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
+        });
+      }
+      const persisted = await submitFeedback({
+        executionId: args.executionId,
+        rating: args.rating,
+        intent: args.intent,
+        domain: args.domain,
+        engine: args.engine,
+        strategy: args.strategy,
+        score: args.score,
+        source: args.source ?? "mcp",
+        notes: args.notes
+      });
+      return { content: [{ type: "text", text: JSON.stringify({ recorded: true, executionId: args.executionId, totalEntries: feedbackCollector.size, persisted: true, thumb: persisted.thumb }) }] };
+    }
+  );
+  server.tool(
+    "get_quality_metrics",
+    // ADR-0048 P4 / gh#1222: second paragraph recovered from the hand-edited TOOLS.md.
+    `Get aggregated quality metrics from the feedback store: avg score, thumb-up rate, per-domain breakdown, training gaps.
+
+\`thumbUpRate\` is a percentage over rating entries alone, reported even when the read window holds no executions (a rated surface whose generation happened offline). Adds a \`ratings\` summary and \`humanRatings\` / \`thumbUpRate\` per domain (gh#668).`,
+    {},
+    async () => {
+      const metrics = await feedbackStore.getQualityMetrics();
+      return { content: [{ type: "text", text: JSON.stringify(metrics, null, 2) }] };
+    }
+  );
+  server.tool(
+    "get_training_gaps",
+    // ADR-0048 P4 / gh#1222: this output-shape note used to live only in
+    // TOOLS.md, so no MCP client ever saw it. TOOLS.md is now generated from
+    // this description — tool prose belongs here or nowhere.
+    `Get training gap signals: LLM self-critique gaps by type, plus weak domains ranked with human thumbs weighted above the self-grade.
+
+Output (gh#668, backward compatible \u2014 the gap-type keys stay at the top level): \`{ ...gapsByType, gapsByType, weakDomains, weighting }\`. \`weakDomains\` is ranked weakest-first by \`blendedScore\`: \`0.7 * humanScore + 0.3 * selfScore\` where a domain has both signals (\`signal: "human+self"\`), \`humanScore\` alone where it has no self-grade (\`"human"\`), \`selfScore\` alone where it has no thumbs (\`"self-only"\`). A missing signal is not a zero \u2014 a domain with NEITHER (executions logged, none graded, nobody rated) is \`signal: "none"\` and sorts after every ranked domain rather than at the weak end, ordered by execution count (gh#678). \`selfScore\` averages execution scores plus any \`score\` carried inline on a rating (\`selfScoreSamples\` counts them); \`engine\` / \`strategy\` are recorded on ratings for triage but are not ranked on.`,
+    {},
+    async () => {
+      const gapsByType = await feedbackStore.getGapSummary();
+      const weakDomains = await feedbackStore.getWeakDomains(10);
+      return {
+        content: [{
+          type: "text",
+          text: JSON.stringify({ ...gapsByType, gapsByType, weakDomains, weighting: WEIGHTING_RULE }, null, 2)
+        }]
+      };
+    }
+  );
+}
+export {
+  registerFeedbackTools
+};

package/gen-ui/tools/ontology-context.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+const SHELL_ENUM = ["admin", "chat", "editor", "simple", "embed", "none"];
+const EXPERIENCE_MODE_ENUM = ["workspace", "dashboard", "wizard", "chat"];
+const ontologyContextSchema = z.object({
+  intent: z.object({
+    user_goal: z.string().optional(),
+    product_goal: z.string().optional()
+  }).optional(),
+  domain: z.object({
+    entities: z.array(z.string()).optional(),
+    metrics: z.array(z.string()).optional()
+  }).optional(),
+  tasks: z.object({
+    primary: z.array(z.string()).optional(),
+    inspection: z.array(z.string()).optional()
+  }).optional(),
+  experience: z.object({
+    mode: z.enum(EXPERIENCE_MODE_ENUM).optional(),
+    shell: z.enum(SHELL_ENUM).optional()
+  }).optional()
+});
+const ONTOLOGY_OUTPUT_SCHEMA_PROMPT = `{
+  "intent": {
+    "user_goal": "string",
+    "product_goal": "string"
+  },
+  "domain": {
+    "entities": ["string"],
+    "metrics": ["string"]
+  },
+  "tasks": {
+    "primary": ["string"],
+    "inspection": ["string"]
+  },
+  "experience": {
+    "mode": "${EXPERIENCE_MODE_ENUM.join(" | ")}",
+    "shell": "${SHELL_ENUM.join(" | ")}"
+  }
+}`;
+export {
+  EXPERIENCE_MODE_ENUM,
+  ONTOLOGY_OUTPUT_SCHEMA_PROMPT,
+  SHELL_ENUM,
+  ontologyContextSchema
+};

package/gen-ui/tools/refine.js

@@ -0,0 +1,158 @@
+import { defineTool } from "@adia-ai/agent";
+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");
+}
+const DESCRIPTION = `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.`;
+class RefineFailure extends Error {
+  body;
+  constructor(body) {
+    super(String(body["error"]));
+    this.name = "RefineFailure";
+    this.body = body;
+  }
+}
+const refineUiTool = defineTool({
+  name: "refine_ui",
+  description: DESCRIPTION,
+  inputSchema: {
+    type: "object",
+    properties: {
+      intent: { type: "string", description: "Original intent string" },
+      previousMessages: { type: "array", description: "Messages from the prior generate_ui call" },
+      validationErrors: { type: "array", description: "Errors from the prior result.validation.errors" }
+    },
+    required: ["intent", "previousMessages", "validationErrors"]
+  },
+  execute: async (input) => {
+    const intent = input["intent"];
+    const previousMessages = input["previousMessages"];
+    const validationErrors = input["validationErrors"];
+    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));
+      throw new RefineFailure({
+        error: `Refiner returned unparseable output: ${e.message}`,
+        raw
+      });
+    }
+    const refinedMessages = Array.isArray(parsed?.messages) ? parsed.messages : null;
+    if (!refinedMessages) {
+      throw new RefineFailure({
+        error: `Refiner response missing "messages" array`,
+        parsed
+      });
+    }
+    return {
+      intent,
+      messages: refinedMessages,
+      errorsAddressed: validationErrors.length
+    };
+  }
+});
+function registerRefineTools(server) {
+  server.tool(
+    "refine_ui",
+    DESCRIPTION,
+    {
+      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 payload = await refineUiTool.execute(
+          { intent, previousMessages, validationErrors },
+          { sessionId: "mcp" }
+        );
+        return {
+          content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
+        };
+      } catch (err) {
+        if (err instanceof RefineFailure) {
+          return {
+            content: [{ type: "text", text: JSON.stringify(err.body, null, 2) }],
+            isError: true
+          };
+        }
+        const e = err instanceof Error ? err : new Error(String(err));
+        return {
+          content: [{ type: "text", text: `refine_ui error: ${e.message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+}
+export {
+  refineUiTool,
+  registerRefineTools
+};

package/gen-ui/tools/schema-to-zod.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+const HONORED_KEYWORDS = /* @__PURE__ */ new Set([
+  "type",
+  "enum",
+  "description",
+  "default",
+  "minimum",
+  "maximum",
+  "items"
+]);
+function checkKeywords(name, prop) {
+  const unsupported = Object.keys(prop).filter((key) => !HONORED_KEYWORDS.has(key));
+  if (unsupported.length) {
+    throw new Error(
+      `zodShape: "${name}" \u2014 unsupported schema keyword(s) ${unsupported.join(", ")}; the MCP shape would silently drop them (honor them in schema-to-zod.ts or drop them from the schema)`
+    );
+  }
+}
+function leaf(name, prop) {
+  checkKeywords(name, prop);
+  const type = prop["type"];
+  const enumValues = prop["enum"];
+  if (Array.isArray(enumValues)) {
+    if (!enumValues.every((v) => typeof v === "string")) {
+      throw new Error(`zodShape: "${name}" \u2014 only string enums are supported`);
+    }
+    return z.enum(enumValues);
+  }
+  switch (type) {
+    case "string":
+      return z.string();
+    case "integer":
+    case "number": {
+      let num = type === "integer" ? z.number().int() : z.number();
+      if (typeof prop["minimum"] === "number") num = num.min(prop["minimum"]);
+      if (typeof prop["maximum"] === "number") num = num.max(prop["maximum"]);
+      return num;
+    }
+    case "boolean":
+      return z.boolean();
+    case "array": {
+      const items = prop["items"] ?? {};
+      if (items["type"] !== "string") {
+        throw new Error(`zodShape: "${name}" \u2014 only string arrays are supported`);
+      }
+      return z.array(z.string());
+    }
+    default:
+      throw new Error(`zodShape: "${name}" \u2014 unsupported schema type "${String(type)}"`);
+  }
+}
+function zodShape(schema) {
+  const properties = schema.properties ?? {};
+  const required = new Set(schema.required ?? []);
+  const shape = {};
+  for (const [name, prop] of Object.entries(properties)) {
+    let field = leaf(name, prop);
+    const description = prop["description"];
+    if (typeof description === "string") field = field.describe(description);
+    if ("default" in prop) field = field.default(prop["default"]);
+    else if (!required.has(name)) field = field.optional();
+    shape[name] = field;
+  }
+  return shape;
+}
+export {
+  zodShape
+};