@adia-ai/mcp 0.8.37

package/gen-ui/load-env.js

@@ -0,0 +1,72 @@
+/**
+ * Package-local .env loader for the MCP server (gh#1186).
+ *
+ * The server used to side-effect-import the monorepo's own
+ * `scripts/load-env.mjs` by a path that walked three levels out of the
+ * package root. That path only exists inside this repo, so every
+ * standalone `npm install @adia-ai/gen-ui-mcp` died at boot with
+ * ERR_MODULE_NOT_FOUND before a single tool was registered.
+ *
+ * This copy ships IN the package and searches upward from the working
+ * directory instead of from a fixed repo layout — which finds the repo
+ * root `.env` when run from anywhere in this monorepo, and finds the
+ * consumer's project `.env` when installed from npm.
+ *
+ * The walk STOPS at the project root — the first directory holding a
+ * `package.json` or `.git`. An unbounded walk is not merely untidy: from a
+ * git worktree under `.claude/worktrees/` it climbed out into the PARENT
+ * checkout's `.env`, handed the server live API keys a keyless test run was
+ * supposed to prove it could do without, and turned `smoke-6-plan-app-state`
+ * into a real 32k-token call that blew the MCP client's 60s timeout. A
+ * loader must never read credentials from outside the project it belongs to.
+ *
+ * Existing env vars always win; a missing .env is silent (keys are
+ * expected from the environment, which is how MCP clients pass them).
+ * Skipped entirely when ADIA_SKIP_DOTENV is set — selftests that must
+ * prove keyless behaviour on a machine that does have a .env (gh#804).
+ * Note that the MCP SDK's stdio transport passes a FILTERED environment to
+ * the servers it spawns, so that opt-out does not survive a client spawn;
+ * the project-root bound is what actually keeps a test run keyless.
+ *
+ * Usage: import './load-env.js';  // side-effect import, first line
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { resolve, dirname, join } from "node:path";
+const isProjectRoot = (dir) => existsSync(join(dir, "package.json")) || existsSync(join(dir, ".git"));
+function findEnvFile(startDir) {
+    let dir = startDir;
+    for (;;) {
+        const candidate = resolve(dir, ".env");
+        if (existsSync(candidate))
+            return candidate;
+        if (isProjectRoot(dir))
+            return null; // project boundary — never climb past it
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+if (!process.env["ADIA_SKIP_DOTENV"]) {
+    try {
+        const envPath = findEnvFile(process.cwd());
+        if (envPath) {
+            for (const line of readFileSync(envPath, "utf8").split("\n")) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith("#"))
+                    continue;
+                const eqIdx = trimmed.indexOf("=");
+                if (eqIdx < 0)
+                    continue;
+                const key = trimmed.slice(0, eqIdx).trim();
+                const val = trimmed.slice(eqIdx + 1).trim();
+                if (!process.env[key])
+                    process.env[key] = val;
+            }
+        }
+    }
+    catch {
+        // unreadable .env — expect keys from the environment
+    }
+}
+export {};

package/gen-ui/server.d.ts

@@ -0,0 +1,20 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Builds the AdiaUI generation MCP server (30 tools: generation, discovery,
+ * retrieval, synthesis, validation, feedback/eval) with no transport
+ * attached. Exported for tests and for `scripts/build/generate-mcp-tools-md.mjs`;
+ * this file's own top-level `main()` call (unconditional, at module scope —
+ * unlike the protocol server's guarded entry point) is what actually starts a
+ * transport on `node server.js`.
+ */
+export function createServer(): McpServer;
+
+/**
+ * Resolves the LLM adapter to use for the given server (or the single
+ * sampling-capable server, if none is passed): the connected client's MCP
+ * sampling capability when available (no separate API key needed), else the
+ * `.env`-configured provider adapter. Returns `null` when neither is
+ * available.
+ */
+export function resolveAdapter(forServer?: McpServer): Promise<unknown | null>;

package/gen-ui/server.js

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+import "./load-env.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { idleTtlMs, startIdleSweep } from "./session-sweep.js";
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { generateUI } from "@adia-ai/gen-ui/compose/core";
+import { projectEngineResult } from "@adia-ai/gen-ui/compose/strategies/registry";
+import {
+  getCatalog,
+  getFullCatalog,
+  getTraits
+} from "@adia-ai/gen-ui/retrieval/catalog";
+import { serializeEntry } from "@adia-ai/gen-ui/retrieval/component-entry";
+import { classifyIntent, getDomain, getAllDomains } from "@adia-ai/gen-ui/retrieval/domain-router";
+import { getAntiPatterns } from "@adia-ai/gen-ui/retrieval/anti-patterns";
+import {
+  loadAll as loadZettelCorpus,
+  getAllCompositions as getAllZettelCompositions
+} from "@adia-ai/gen-ui/compose/strategies/zettel/composition-library";
+const _zettelBoot = await loadZettelCorpus();
+console.error(
+  `[gen-ui-mcp] zettel corpus: ${_zettelBoot.compositionCount} compositions`
+);
+import { getChunkIndex } from "@adia-ai/gen-ui/corpus/chunk-library";
+const _chunkIndex = getChunkIndex();
+if (_chunkIndex) {
+  const idx = _chunkIndex;
+  const byKind = idx["by_kind"] ?? {};
+  console.error(
+    `[gen-ui-mcp] gen-ui chunks: ${idx["unique_names"]} unique chunks (${idx["total_instances"]} instances; block=${byKind["block"] ?? 0}, panel=${byKind["panel"] ?? 0}, page=${byKind["page"] ?? 0})`
+  );
+} else {
+  console.error("[gen-ui-mcp] gen-ui chunks: index not found \u2014 run `npm run harvest:chunks`");
+}
+import { registerSynthesisTools } from "./tools/synthesis.js";
+import { registerValidationTools } from "./tools/validation.js";
+import { registerFeedbackTools } from "./tools/feedback.js";
+import { registerCorpusTools } from "./tools/corpus.js";
+import { registerZettelTools } from "./tools/zettel.js";
+import { registerDiscoveryTools } from "./tools/discovery.js";
+import { registerRefineTools } from "./tools/refine.js";
+import { ontologyContextSchema, ONTOLOGY_OUTPUT_SCHEMA_PROMPT } from "./tools/ontology-context.js";
+function createServer() {
+  const server = new McpServer({
+    name: "adia-ui",
+    version: "0.1.0",
+    capabilities: {
+      sampling: {}
+      // allows server to request LLM inference from the host (IDE/client)
+    }
+  });
+  registerAllTools(server);
+  return server;
+}
+let samplingServer = null;
+async function resolveAdapter(forServer) {
+  const active = forServer ?? samplingServer;
+  const hasSampling = active && active.server?._clientCapabilities?.sampling;
+  if (hasSampling) {
+    return {
+      async complete({ messages, systemPrompt }) {
+        const result = await active.server.createMessage({
+          messages: messages.map((m) => ({
+            role: m.role,
+            content: { type: "text", text: m.content }
+          })),
+          ...systemPrompt ? { systemPrompt } : {},
+          maxTokens: 32768
+        });
+        return {
+          content: typeof result.content === "string" ? result.content : result.content?.text ?? "",
+          stopReason: result.stopReason ?? "end",
+          usage: { inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 }
+        };
+      }
+    };
+  }
+  const { createAdapter } = await import("@adia-ai/llm/bridge");
+  return createAdapter();
+}
+function registerAllTools(server) {
+  server.tool(
+    "plan_app_state",
+    `Analyze a natural language prompt and extract the top-level Generative UI Ontology structures (Intent, Domain, Tasks, Experience).
+
+Use this tool BEFORE generating UI to ensure you have walked the Reasoning Ladder and properly modeled the nouns and verbs of the feature. This bounds hallucination and forces a focus on tasks over raw layouts.
+
+Honesty clause (REQ-03, gh#1208): this tool mechanizes only the Reasoning Ladder's ~Tier 0/1 rungs \u2014 one prompt, one LLM pass, no plan a reviewer can gate. It is the agent operator's (P4's) only ladder surface \u2014 a persona that cannot preload skills \u2014 not a substitute for the full rungs 0-19 walk. For anything past Tier 0/1 (roles, decisions, a scored wireframe checkpoint), use a Domain Plan from app-planning-agent's preloaded ladder skill instead.
+
+Output shape \u2014 the four ontology blocks generate_ui's context param accepts (ontologyContextSchema, tools/ontology-context.ts): intent (user_goal, product_goal), domain (entities[], metrics[]), tasks (primary[], inspection[]), experience (mode: workspace|dashboard|wizard|chat, shell: admin|chat|editor|simple|embed|none \u2014 matches the Orientation Record's own Shell axis). The extracted output is validated against this same schema before being returned (gh#1208 review finding 2): a malformed shell/mode value (or any other schema violation) fails loudly with a typed error instead of passing the raw LLM text through.`,
+    {
+      prompt: z.string().describe('The natural language request (e.g., "Build a dashboard for incoming sales leads")')
+    },
+    async ({ prompt }) => {
+      const llm = await resolveAdapter(server);
+      const systemPrompt = `You are the A2UI Ontology Planner.
+Given a user prompt, you must extract the Core App State using the 5-Gate Reasoning Ladder.
+
+Output ONLY a JSON object matching this schema, nothing else:
+${ONTOLOGY_OUTPUT_SCHEMA_PROMPT}`;
+      try {
+        const response = await llm.complete({
+          messages: [{ role: "user", content: prompt }],
+          system: systemPrompt,
+          temperature: 0.2
+        });
+        const jsonMatch = response.content.match(/\{[\s\S]*\}/);
+        if (!jsonMatch) {
+          throw new Error("LLM failed to output valid JSON for the ontology plan.");
+        }
+        const rawPlan = JSON.parse(jsonMatch[0]);
+        const validated = ontologyContextSchema.safeParse(rawPlan);
+        if (!validated.success) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `plan_app_state: extracted plan failed ontology schema validation \u2014 ${validated.error.message}`
+              }
+            ],
+            isError: true
+          };
+        }
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(validated.data, null, 2)
+            }
+          ]
+        };
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        return {
+          content: [
+            { type: "text", text: `Failed to plan app state: ${err.message}` }
+          ],
+          isError: true
+        };
+      }
+    }
+  );
+  server.tool(
+    "generate_ui",
+    `Generate A2UI components from a natural language description.
+
+Engine selection:
+- "monolithic" (default) \u2014 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" \u2014 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) \u2014 LLM-powered generation with pattern adaptation.
+- "thinking" \u2014 Full LLM-powered generation with semantic search, decomposition, and streaming.
+- "instant" \u2014 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."),
+      context: ontologyContextSchema.optional().describe(`Ontology context parsed by plan_app_state \u2014 intent, domain, tasks, experience (REQ-03, gh#1208: all four blocks are accepted and validated here; previously only domain/tasks survived the schema, intent/experience were silently dropped). Per-engine caveat: only the "monolithic" engine's system-prompt injection reads it today, and only five of the schema's leaves (domain.entities, domain.metrics, tasks.primary, experience.mode, experience.shell) \u2014 intent.* and tasks.inspection validate but are not yet interpolated into the prompt. The "zettel" engine (and the free-form tier reachable via engine escalation) ignores context entirely; passing it has no effect there.`)
+    },
+    async ({ intent, engine, mode, sessionId, context }) => {
+      try {
+        const selectedEngine = engine ?? "monolithic";
+        const effectiveMode = selectedEngine === "zettel" ? "instant" : mode ?? "pro";
+        const llmAdapter = effectiveMode !== "instant" ? await resolveAdapter(server) : void 0;
+        const result = await generateUI({
+          intent,
+          engine: selectedEngine,
+          mode: effectiveMode,
+          sessionId,
+          context,
+          // Pass the ontology context down to the composer
+          ...llmAdapter ? { llmAdapter } : {}
+        });
+        return {
+          content: [{
+            type: "text",
+            text: JSON.stringify(projectEngineResult(result, selectedEngine), null, 2)
+          }]
+        };
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        return { content: [{ type: "text", text: `Generation error: ${e.message}` }], isError: true };
+      }
+    }
+  );
+  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(
+    "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("@adia-ai/gen-ui/compose/evals");
+        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) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        return { content: [{ type: "text", text: `Eval error: ${e.message}` }], isError: true };
+      }
+    }
+  );
+  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(
+    "compositions",
+    "a2ui://catalog/compositions",
+    async (uri) => ({
+      contents: [{
+        uri: uri.href,
+        mimeType: "application/json",
+        text: JSON.stringify(getAllZettelCompositions(), 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)
+        }]
+      };
+    }
+  );
+  registerValidationTools(server);
+  registerFeedbackTools(server);
+  registerCorpusTools(server);
+  registerZettelTools(server);
+  registerSynthesisTools(server);
+  registerDiscoveryTools(server);
+  registerRefineTools(server);
+}
+async function startStdio() {
+  const transport = new StdioServerTransport();
+  const server = createServer();
+  samplingServer = server;
+  await server.connect(transport);
+  const catalog = await getCatalog();
+  const traits = getTraits();
+  console.error(`[gen-ui-mcp] stdio transport ready (${catalog.totalTypes} components, ${traits.length} traits, ${_zettelBoot.compositionCount} compositions)`);
+}
+function sendJsonRpcError(res, status, code, message) {
+  if (res.headersSent) return;
+  res.status(status).json({ jsonrpc: "2.0", error: { code, message }, id: null });
+}
+async function startHttp(port) {
+  const sessions = /* @__PURE__ */ new Map();
+  const ttlMs = idleTtlMs();
+  startIdleSweep(sessions, ttlMs);
+  const app = createMcpExpressApp({ host: "0.0.0.0" });
+  app.all("/mcp", async (req, res) => {
+    try {
+      const sessionId = req.headers["mcp-session-id"];
+      const existing = sessionId ? sessions.get(sessionId) : void 0;
+      if (existing) {
+        existing.lastActivity = Date.now();
+        await existing.transport.handleRequest(req, res, req.body);
+        return;
+      }
+      if (req.method === "POST" && isInitializeRequest(req.body)) {
+        const id = randomUUID();
+        const sessionServer = createServer();
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: () => id,
+          onsessioninitialized: (sid) => sessions.set(sid, {
+            transport,
+            server: sessionServer,
+            lastActivity: Date.now()
+          })
+        });
+        let torndown = false;
+        transport.onclose = () => {
+          if (torndown) return;
+          torndown = true;
+          sessions.delete(id);
+          void sessionServer.close().catch(() => {
+          });
+        };
+        await sessionServer.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+        return;
+      }
+      if (sessionId) {
+        sendJsonRpcError(res, 404, -32001, `Unknown or expired session '${sessionId}' \u2014 send an initialize request to start a new one`);
+        return;
+      }
+      sendJsonRpcError(res, 400, -32600, "Invalid request \u2014 send mcp-session-id, or POST an initialize request");
+    } catch (err) {
+      const e = err instanceof Error ? err : new Error(String(err));
+      console.error(`[gen-ui-mcp] HTTP request failed: ${e.stack ?? e.message}`);
+      sendJsonRpcError(res, 500, -32603, `Internal server error: ${e.message}`);
+    }
+  });
+  app.listen(port, () => {
+    const catalog = getCatalog();
+    console.error(`[gen-ui-mcp] HTTP transport ready on http://0.0.0.0:${port}/mcp`);
+    console.error(
+      ttlMs > 0 ? `[gen-ui-mcp] session idle TTL: ${ttlMs}ms (MCP_SESSION_TTL_MS)` : `[gen-ui-mcp] session idle TTL: disabled (MCP_SESSION_TTL_MS<=0)`
+    );
+    console.error(`[gen-ui-mcp] API keys required for pro/thinking mode (no sampling in HTTP mode)`);
+  });
+}
+async function main() {
+  const httpPort = typeof process !== "undefined" && process.env?.MCP_HTTP_PORT ? parseInt(process.env.MCP_HTTP_PORT, 10) : null;
+  if (httpPort) {
+    await startHttp(httpPort);
+  } else {
+    await startStdio();
+  }
+}
+main().catch(console.error);
+export {
+  createServer,
+  resolveAdapter
+};

package/gen-ui/session-sweep.js

@@ -0,0 +1,56 @@
+const DEFAULT_IDLE_TTL_MS = 30 * 6e4;
+const MIN_SWEEP_MS = 250;
+const MAX_SWEEP_MS = 6e4;
+function idleTtlMs(env = typeof process !== "undefined" ? process.env : void 0) {
+  const raw = env?.["MCP_SESSION_TTL_MS"];
+  if (raw === void 0 || raw === "") return DEFAULT_IDLE_TTL_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed)) {
+    console.error(
+      `[gen-ui-mcp] MCP_SESSION_TTL_MS='${raw}' is not a number \u2014 using ${DEFAULT_IDLE_TTL_MS}ms`
+    );
+    return DEFAULT_IDLE_TTL_MS;
+  }
+  return parsed <= 0 ? 0 : parsed;
+}
+function sweepIntervalMs(ttlMs) {
+  return Math.min(MAX_SWEEP_MS, Math.max(MIN_SWEEP_MS, Math.floor(ttlMs / 4)));
+}
+function evictIdleSessions(sessions, ttlMs, now = Date.now()) {
+  if (ttlMs <= 0) return [];
+  const evicted = [];
+  for (const [id, session] of [...sessions]) {
+    if (now - session.lastActivity < ttlMs) continue;
+    sessions.delete(id);
+    evicted.push(id);
+    try {
+      const closing = session.transport.close();
+      if (closing && typeof closing.catch === "function") {
+        void closing.catch(() => {
+        });
+      }
+    } catch {
+    }
+  }
+  return evicted;
+}
+function startIdleSweep(sessions, ttlMs) {
+  if (ttlMs <= 0) {
+    console.error("[gen-ui-mcp] session idle eviction disabled (MCP_SESSION_TTL_MS<=0)");
+    return null;
+  }
+  const timer = setInterval(() => {
+    for (const id of evictIdleSessions(sessions, ttlMs)) {
+      console.error(`[gen-ui-mcp] session ${id} evicted after ${ttlMs}ms idle`);
+    }
+  }, sweepIntervalMs(ttlMs));
+  timer.unref?.();
+  return timer;
+}
+export {
+  DEFAULT_IDLE_TTL_MS,
+  evictIdleSessions,
+  idleTtlMs,
+  startIdleSweep,
+  sweepIntervalMs
+};