@kitn.ai/ui 0.15.1 → 0.17.0

package/src/agent-tooling/integrations/cloudflare.ts

@@ -0,0 +1,88 @@
+import type { Integration } from '../types';
+
+const cloudflare: Integration = {
+  id: 'cloudflare',
+  title: 'Cloudflare AI',
+  category: 'provider',
+  language: 'ts',
+  streamFormat: 'openai-sse',
+  envVars: ['CF_ACCOUNT_ID', 'CF_API_TOKEN'],
+  routeTemplates: {
+    next: `// app/api/chat/route.ts — proxy Workers AI, keep the token server-side
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const upstream = await fetch(
+    \`https://api.cloudflare.com/client/v4/accounts/\${process.env.CF_ACCOUNT_ID}/ai/v1/chat/completions\`,
+    {
+      method: 'POST',
+      headers: {
+        Authorization: \`Bearer \${process.env.CF_API_TOKEN}\`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: '@cf/meta/llama-3.1-8b-instruct',
+        messages,
+        stream: true,
+      }),
+    },
+  );
+
+  // Workers AI returns OpenAI-format SSE — pass it straight through.
+  return new Response(upstream.body, { headers: { 'Content-Type': 'text/event-stream' } });
+}`,
+    worker: `// Worker handler — env.AI is bound in wrangler.toml
+// env.AI.run emits Cloudflare-native SSE (data: {"response":"<token>"}).
+// The TransformStream below re-frames each chunk to OpenAI-format SSE so
+// kai-chat's reader works without any client-side changes.
+export default {
+  async fetch(req: Request, env: Env): Promise<Response> {
+    const { messages } = await req.json();
+
+    const nativeStream = await env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
+      messages,
+      stream: true,
+    });
+
+    // Re-frame Cloudflare-native SSE → OpenAI-format SSE
+    const { readable, writable } = new TransformStream();
+    const writer = writable.getWriter();
+    const encoder = new TextEncoder();
+    const decoder = new TextDecoder();
+
+    (async () => {
+      const reader = (nativeStream as ReadableStream<Uint8Array>).getReader();
+      let buffer = '';
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\\n');
+        buffer = lines.pop() ?? '';
+        for (const line of lines) {
+          const s = line.trim();
+          if (!s.startsWith('data:')) continue;
+          const payload = s.slice(5).trim();
+          if (payload === '[DONE]') continue;
+          try {
+            const { response } = JSON.parse(payload) as { response?: string };
+            if (response == null) continue;
+            const openaiChunk = JSON.stringify({ choices: [{ delta: { content: response } }] });
+            await writer.write(encoder.encode(\`data: \${openaiChunk}\\n\\n\`));
+          } catch { /* skip malformed lines */ }
+        }
+      }
+      await writer.write(encoder.encode('data: [DONE]\\n\\n'));
+      await writer.close();
+    })();
+
+    return new Response(readable, { headers: { 'Content-Type': 'text/event-stream' } });
+  },
+};`,
+  },
+  streamMapping: "Workers AI via the OpenAI-compatible HTTP endpoint returns OpenAI-format SSE — pipe upstream.body straight to the browser; kai-chat's reader handles it. The native env.AI binding streams Cloudflare's own format (data: {\"response\":\"...token...\"}); the worker route template re-frames these chunks to OpenAI-format SSE via a TransformStream before returning.",
+  runNote: 'Set CF_ACCOUNT_ID and CF_API_TOKEN. Model ids are prefixed with @cf/, e.g. @cf/meta/llama-3.1-8b-instruct. For the AI binding (worker key), add an [ai] block with binding = "AI" in wrangler.toml.',
+  docsSlug: 'integrations/cloudflare-ai',
+};
+
+export default cloudflare;

package/src/agent-tooling/integrations/langgraph.ts

@@ -0,0 +1,60 @@
+import type { Integration } from '../types';
+
+const langgraph: Integration = {
+  id: 'langgraph',
+  title: 'LangGraph',
+  category: 'framework',
+  language: 'ts',
+  streamFormat: 'openai-sse',
+  envVars: ['OPENAI_API_KEY'],
+  routeTemplates: {
+    next: `// POST /api/chat — stream a compiled LangGraph agent to the browser
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+import { ChatOpenAI } from '@langchain/openai';
+import { tool } from '@langchain/core/tools';
+import { z } from 'zod';
+
+const getWeather = tool(
+  async ({ city }) => \`It's 18°C and clear in \${city}.\`,
+  {
+    name: 'get_weather',
+    description: 'Get the current weather for a city.',
+    schema: z.object({ city: z.string() }),
+  },
+);
+
+const agent = createReactAgent({
+  llm: new ChatOpenAI({ model: 'gpt-4o' }),
+  tools: [getWeather],
+});
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const stream = await agent.stream({ messages }, { streamMode: 'messages' });
+
+  const encoder = new TextEncoder();
+  const body = new ReadableStream({
+    async start(controller) {
+      const send = (obj: unknown) =>
+        controller.enqueue(encoder.encode(\`data: \${JSON.stringify(obj)}\\n\\n\`));
+
+      for await (const [chunk] of stream) {
+        if (typeof chunk.content === 'string' && chunk.content) {
+          send({ choices: [{ delta: { content: chunk.content } }] });
+        }
+      }
+      controller.enqueue(encoder.encode('data: [DONE]\\n\\n'));
+      controller.close();
+    },
+  });
+
+  return new Response(body, { headers: { 'Content-Type': 'text/event-stream' } });
+}`,
+  },
+  streamMapping: "Use graph.stream(input, { streamMode: 'messages' }) to get [messageChunk, metadata] tuples. Extract chunk.content (string) and forward as OpenAI-format SSE frames: data: {choices:[{delta:{content}}]}. Close with data: [DONE]. The kai-chat reader handles it.",
+  runNote: 'Set OPENAI_API_KEY (or the key for your chosen model provider). Install @langchain/langgraph, @langchain/openai, @langchain/core.',
+  docsSlug: 'integrations/langgraph',
+};
+
+export default langgraph;

package/src/agent-tooling/integrations/mastra.ts

@@ -0,0 +1,27 @@
+import type { Integration } from '../types';
+
+const mastra: Integration = {
+  id: 'mastra',
+  title: 'Mastra',
+  category: 'harness',
+  language: 'ts',
+  streamFormat: 'openai-sse',
+  envVars: ['MASTRA_URL'],
+  routeTemplates: {
+    express: `// POST /api/chat — your server proxies a Mastra agent to the browser
+import { MastraClient } from '@mastra/client-js';
+
+const mastra = new MastraClient({ baseUrl: process.env.MASTRA_URL });
+
+const stream = await mastra.getAgent('supportAgent').stream({ messages });
+for await (const delta of stream.textStream) {
+  res.write(\`data: \${JSON.stringify({ choices: [{ delta: { content: delta } }] })}\\n\\n\`);
+}
+res.write('data: [DONE]\\n\\n');`,
+  },
+  streamMapping: "Mastra agents speak Vercel AI SDK v5 and expose stream.textStream (async iterable of string deltas). Iterate textStream and emit data: {choices:[{delta:{content}}]} frames; close with data: [DONE]. kai-chat's SSE reader handles it. For tool calls and reasoning, convert the agent to a UI message stream with @mastra/ai-sdk.",
+  runNote: 'Set MASTRA_URL to your Mastra server base URL (mastra dev exposes POST /api/agents/:agentId/stream on port 4111). Install @mastra/client-js.',
+  docsSlug: 'integrations/harnesses',
+};
+
+export default mastra;

package/src/agent-tooling/integrations/mock.ts

@@ -0,0 +1,34 @@
+import type { Integration } from '../types';
+
+/**
+ * mock — the zero-config first-win.
+ *
+ * Not a real backend: there's no provider, no API key, no `/api` route. The
+ * scaffolder special-cases `integration === 'mock'` and emits a front-end whose
+ * `onSubmit` SIMULATES a streamed assistant reply CLIENT-SIDE (token-by-token,
+ * a new array/object reference per chunk — honouring the messages contract).
+ *
+ * This lets `scaffold(useCase, integration: 'mock', framework: 'react')` run with
+ * zero config so a developer sees a live, streaming chat before wiring a model.
+ * Swap `integration` for a real provider (openrouter, ollama, …) when ready.
+ *
+ * It carries an empty `routeTemplates` on purpose: there is no server route to
+ * emit. `category: 'mock'` keeps it out of the real provider/gateway/framework/
+ * harness catalogs.
+ */
+const mock: Integration = {
+  id: 'mock',
+  title: 'Mock (local preview)',
+  category: 'mock',
+  language: 'ts',
+  streamFormat: 'native',
+  envVars: [],
+  routeTemplates: {},
+  streamMapping:
+    'No backend. onSubmit streams a canned assistant reply client-side, one token at a time, reassigning messages (new array/object reference) per chunk so kai-chat re-renders. Swap integration for a real provider when ready.',
+  runNote:
+    'No backend or API key needed — replies stream locally for preview. Run the front-end as-is; swap `integration` for a real provider (e.g. openrouter, ollama) when ready.',
+  docsSlug: 'integrations/mock',
+};
+
+export default mock;

package/src/agent-tooling/integrations/ollama.ts

@@ -0,0 +1,47 @@
+import type { Integration } from '../types';
+
+const ollama: Integration = {
+  id: 'ollama',
+  title: 'Ollama',
+  category: 'provider',
+  language: 'ts',
+  streamFormat: 'openai-sse',
+  envVars: [],
+  routeTemplates: {
+    next: `// app/api/chat/route.ts — proxy the browser to local Ollama
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const upstream = await fetch('http://localhost:11434/v1/chat/completions', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ model: 'llama3.2', messages, stream: true }),
+  });
+
+  // Ollama returns OpenAI-format SSE — stream it straight to the browser.
+  return new Response(upstream.body, { headers: { 'Content-Type': 'text/event-stream' } });
+}`,
+    html: `<kai-chat id="chat"></kai-chat>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';
+  const chat = document.getElementById('chat');
+
+  chat.addEventListener('kai-submit', async (e) => {
+    const history = [...chat.messages, { id: crypto.randomUUID(), role: 'user', content: e.detail.value }];
+    chat.messages = [...history, { id: crypto.randomUUID(), role: 'assistant', content: '' }];
+    await fetch('/api/chat', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ messages: history }),
+    });
+    // stream the reply into the last message — see the Streaming recipe
+  });
+</script>`,
+  },
+  streamMapping: "Ollama's OpenAI-compatible endpoint (http://localhost:11434/v1/chat/completions) returns OpenAI-format SSE — pipe upstream.body straight to the browser; kai-chat's reader handles it. No API key needed; pass any string if a client requires one (Ollama ignores it).",
+  runNote: 'No API key required. Run: ollama serve (starts on 127.0.0.1:11434), then ollama pull <model>. For browser-direct access, set OLLAMA_ORIGINS to allow the page origin; restart Ollama after any env change.',
+  docsSlug: 'integrations/ollama',
+};
+
+export default ollama;

package/src/agent-tooling/integrations/openrouter.ts

@@ -0,0 +1,26 @@
+import type { Integration } from '../types';
+
+const openrouter: Integration = {
+  id: 'openrouter',
+  title: 'OpenRouter',
+  category: 'gateway',
+  language: 'ts',
+  streamFormat: 'openai-sse',
+  envVars: ['OPENROUTER_API_KEY'],
+  routeTemplates: {
+    next: `export async function POST(req: Request) {
+  const { model, messages } = await req.json();
+  const upstream = await fetch('https://openrouter.ai/api/v1/chat/completions', {
+    method: 'POST',
+    headers: { Authorization: \`Bearer \${process.env.OPENROUTER_API_KEY}\`, 'Content-Type': 'application/json' },
+    body: JSON.stringify({ model, messages, stream: true }),
+  });
+  return new Response(upstream.body, { headers: { 'Content-Type': 'text/event-stream' } });
+}`,
+  },
+  streamMapping: 'OpenRouter returns OpenAI-format SSE — pipe upstream.body straight to the browser; the Streaming-recipe reader handles it.',
+  runNote: 'Set OPENROUTER_API_KEY. Model ids are vendor/model, e.g. openai/gpt-4o.',
+  docsSlug: 'integrations/connect-any-model',
+};
+
+export default openrouter;

package/src/agent-tooling/integrations/pi.ts

@@ -0,0 +1,40 @@
+import type { Integration } from '../types';
+
+const pi: Integration = {
+  id: 'pi',
+  title: 'Pi',
+  category: 'harness',
+  language: 'ts',
+  streamFormat: 'native',
+  envVars: [],
+  routeTemplates: {
+    express: `import { spawn } from 'node:child_process';
+
+// POST /api/chat — bridge a Pi RPC session to the browser as SSE
+const pi = spawn('pi', ['--mode', 'rpc', '--no-session']);
+
+// Send the user's turn. Pi commands are { type, message }.
+pi.stdin.write(JSON.stringify({ type: 'prompt', message: prompt }) + '\\n');
+
+let buffer = '';
+pi.stdout.on('data', (chunk) => {
+  buffer += chunk.toString();
+  const lines = buffer.split('\\n');
+  buffer = lines.pop(); // hold the partial line for the next chunk
+  for (const line of lines) {
+    if (!line) continue;
+    const event = JSON.parse(line);
+    const part = event.assistantMessageEvent;
+    if (event.type === 'message_update' && part?.type === 'text_delta') {
+      res.write(\`data: \${JSON.stringify({ choices: [{ delta: { content: part.delta } }] })}\\n\\n\`);
+    }
+  }
+});
+pi.on('close', () => { res.write('data: [DONE]\\n\\n'); res.end(); });`,
+  },
+  streamMapping: "Pi runs as a local stdio process in RPC mode (pi --mode rpc --no-session). It emits newline-delimited JSON events on stdout. Map message_update events where assistantMessageEvent.type === 'text_delta' to data: {choices:[{delta:{content:part.delta}}]} SSE frames; send data: [DONE] on close. Split stdout on \\n (not readline, which breaks on Unicode separators U+2028/U+2029). Pi also emits thinking_delta (map to reasoning) and toolcall_* events (map to tool calls).",
+  runNote: "Pi must be installed locally and available on PATH as 'pi'. No API key is required by the bridge itself; Pi uses its own credentials. Pi runs with full user permissions — sandbox before exposing to a public endpoint. See the RPC reference: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/rpc.md",
+  docsSlug: 'integrations/harnesses',
+};
+
+export default pi;

package/src/agent-tooling/integrations/pydantic-ai.ts

@@ -0,0 +1,52 @@
+import type { Integration } from '../types';
+
+const pydanticAi: Integration = {
+  id: 'pydantic-ai',
+  title: 'Pydantic AI',
+  category: 'framework',
+  language: 'python',
+  streamFormat: 'openai-sse',
+  envVars: ['OPENAI_API_KEY'],
+  routeTemplates: {
+    fastapi: `# main.py
+import json
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+from pydantic_ai import Agent
+
+agent = Agent('openai:gpt-4o')
+
+app = FastAPI()
+app.add_middleware(
+    CORSMiddleware, allow_origins=['*'], allow_methods=['*'], allow_headers=['*']
+)
+
+class Message(BaseModel):
+    role: str
+    content: str
+
+class ChatRequest(BaseModel):
+    messages: list[Message]
+
+async def openai_sse(messages: list[Message]):
+    prompt = messages[-1].content if messages else ''
+    async with agent.run_stream(prompt) as result:
+        async for delta in result.stream_text(delta=True):
+            chunk = {'choices': [{'delta': {'content': delta}}]}
+            yield f'data: {json.dumps(chunk)}\\n\\n'
+    yield 'data: [DONE]\\n\\n'
+
+@app.post('/api/chat')
+async def chat(req: ChatRequest):
+    return StreamingResponse(openai_sse(req.messages), media_type='text/event-stream')`,
+  },
+  streamMapping:
+    "Pydantic AI's agent.run_stream() yields text deltas via result.stream_text(delta=True). Each delta is re-framed as a data: {choices:[{delta:{content}}]} SSE line and the stream closes with data: [DONE]. The kai-chat reader is unchanged — it sees standard OpenAI-format SSE.",
+  runNote:
+    'Install: pip install pydantic-ai fastapi uvicorn. Set OPENAI_API_KEY. Run: uvicorn main:app --reload (default port 8000). Point kai-chat at http://localhost:8000/api/chat.',
+  docsSlug: 'integrations/pydantic-ai',
+};
+
+export default pydanticAi;

package/src/agent-tooling/integrations/vercel-ai-sdk.ts

@@ -0,0 +1,44 @@
+import type { Integration } from '../types';
+
+const vercelAiSdk: Integration = {
+  id: 'vercel-ai-sdk',
+  title: 'Vercel AI SDK',
+  category: 'framework',
+  language: 'ts',
+  streamFormat: 'ai-sdk',
+  envVars: ['AI_GATEWAY_API_KEY'],
+  routeTemplates: {
+    next: `// app/api/chat/route.ts
+import { streamText } from 'ai';
+
+export const maxDuration = 30; // allow long streaming responses
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+
+  const result = streamText({
+    model: 'openai/gpt-4o', // AI Gateway id; needs AI_GATEWAY_API_KEY
+    messages,
+  });
+
+  const encoder = new TextEncoder();
+  const sse = new ReadableStream({
+    async start(controller) {
+      for await (const delta of result.textStream) {
+        const chunk = { choices: [{ delta: { content: delta } }] };
+        controller.enqueue(encoder.encode(\`data: \${JSON.stringify(chunk)}\\n\\n\`));
+      }
+      controller.enqueue(encoder.encode('data: [DONE]\\n\\n'));
+      controller.close();
+    },
+  });
+
+  return new Response(sse, { headers: { 'Content-Type': 'text/event-stream' } });
+}`,
+  },
+  streamMapping: "The Vercel AI SDK's toUIMessageStreamResponse() and toTextStreamResponse() don't emit OpenAI-format SSE. Wrap result.textStream manually: iterate text deltas and emit data: {choices:[{delta:{content}}]} frames, closing with data: [DONE]. The kai-chat SSE reader handles it.",
+  runNote: 'Set AI_GATEWAY_API_KEY for the AI Gateway (string model id form: creator/model-name). For direct provider access, import its provider package (e.g. @ai-sdk/openai) and set the corresponding key (e.g. OPENAI_API_KEY).',
+  docsSlug: 'integrations/vercel-ai-sdk',
+};
+
+export default vercelAiSdk;

package/src/agent-tooling/mcp/manifest.ts

@@ -0,0 +1,128 @@
+/**
+ * manifest.ts — reads dist/custom-elements.json (a Custom Elements Manifest)
+ * and exposes helpers for the component_reference tool.
+ *
+ * Resolution strategy (dual-context):
+ *  1. Bundled bin: dist/mcp.es.js lives in dist/, so custom-elements.json is
+ *     a sibling → try ./custom-elements.json relative to import.meta.url.
+ *  2. Vitest (source): manifest.ts lives in src/agent-tooling/mcp/, so we walk
+ *     up parent directories looking for <dir>/dist/custom-elements.json.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, dirname } from 'node:path';
+
+// ── CEM types ────────────────────────────────────────────────────────────────
+
+export interface CemType {
+  text: string;
+}
+
+export interface CemMember {
+  kind: 'field' | 'method';
+  privacy?: 'public' | 'private' | 'protected';
+  name: string;
+  type?: CemType;
+  description?: string;
+}
+
+export interface CemAttribute {
+  name: string;
+  fieldName?: string;
+  type?: CemType;
+  description?: string;
+}
+
+export interface CemEvent {
+  name: string;
+  type?: CemType;
+  description?: string;
+}
+
+export interface CemCssProperty {
+  name: string;
+  description?: string;
+  default?: string;
+}
+
+export interface Declaration {
+  tagName?: string;
+  name: string;
+  kind: string;
+  description?: string;
+  members?: CemMember[];
+  attributes?: CemAttribute[];
+  events?: CemEvent[];
+  cssProperties?: CemCssProperty[];
+}
+
+interface CemModule {
+  path?: string;
+  declarations?: Declaration[];
+}
+
+interface CustomElementsManifest {
+  modules: CemModule[];
+}
+
+// ── Manifest resolution ───────────────────────────────────────────────────────
+
+function resolveManifestPath(): string {
+  const thisFile = fileURLToPath(import.meta.url);
+  const thisDir = dirname(thisFile);
+
+  // 1. Bundled bin: sibling in the same directory
+  const sibling = join(thisDir, 'custom-elements.json');
+  if (existsSync(sibling)) {
+    return sibling;
+  }
+
+  // 2. Source/Vitest: walk up parent directories looking for dist/custom-elements.json
+  let dir = thisDir;
+  for (let i = 0; i < 10; i++) {
+    const candidate = join(dir, 'dist', 'custom-elements.json');
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) break; // reached filesystem root
+    dir = parent;
+  }
+
+  throw new Error(
+    `Could not find custom-elements.json. Searched from: ${thisDir}`,
+  );
+}
+
+// ── Parsed manifest (module-level cache) ─────────────────────────────────────
+
+let _manifest: CustomElementsManifest | undefined;
+
+function getManifest(): CustomElementsManifest {
+  if (!_manifest) {
+    const path = resolveManifestPath();
+    const raw = readFileSync(path, 'utf-8');
+    _manifest = JSON.parse(raw) as CustomElementsManifest;
+  }
+  return _manifest;
+}
+
+function getDeclarations(): Declaration[] {
+  return getManifest().modules.flatMap((m) => m.declarations ?? []);
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/** Returns the Declaration for a given custom-element tag, or undefined. */
+export function getElement(tag: string): Declaration | undefined {
+  return getDeclarations().find((d) => d.tagName === tag);
+}
+
+/** Returns all custom-element tagNames, sorted alphabetically. */
+export function listElements(): string[] {
+  return getDeclarations()
+    .filter((d) => d.tagName)
+    .map((d) => d.tagName!)
+    .sort();
+}

package/src/agent-tooling/mcp/server.ts

@@ -0,0 +1,59 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { reference } from './tools/reference';
+import { scaffold } from './tools/scaffold';
+import { theme } from './tools/theme';
+import { debug } from './tools/debug';
+import type { Tool } from './tools/types';
+
+const tools: Tool[] = [reference, scaffold, theme, debug];
+
+/**
+ * The AI/UI MCP server. A stdio server (see ./stdio.ts) exposing the AI/UI tools
+ * to any MCP harness. Registers four tools; Tasks 2–5 fill in each handler.
+ *
+ * The returned `Server` is augmented with `__listToolsForTest()`, a test-only
+ * helper that returns the registered tool names without touching the transport.
+ */
+export interface AiUiServer extends Server {
+  __listToolsForTest(): string[];
+}
+
+export function createServer(): AiUiServer {
+  const server = new Server(
+    { name: '@kitn.ai/ui', version: '0.15.0' },
+    { capabilities: { tools: {} } },
+  ) as AiUiServer;
+
+  const byName = new Map(tools.map((t) => [t.name, t]));
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      // The protocol requires a JSON Schema. We use zod 4's native converter
+      // (the repo is on zod 4); the SDK-bundled zod-to-json-schema only
+      // understands zod 3 and emits an empty schema for our zod 4 objects.
+      inputSchema: z.toJSONSchema(t.inputSchema) as Record<string, unknown>,
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = byName.get(request.params.name);
+    if (!tool) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }],
+      };
+    }
+    return tool.handler(request.params.arguments ?? {});
+  });
+
+  server.__listToolsForTest = () => tools.map((t) => t.name);
+
+  return server;
+}

package/src/agent-tooling/mcp/stdio.ts

@@ -0,0 +1,18 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server';
+
+/**
+ * Build entry for the AI/UI MCP server. Connects the server (./server.ts) to a
+ * stdio transport so any MCP harness (Claude Code, Codex, …) can drive it over
+ * stdin/stdout. Compiled to dist/mcp.es.js by vite.config.mcp.ts and launched by
+ * bin/mcp.js, which handles fatal errors / exit (this file stays free of Node
+ * globals so it typechecks under the repo's vite/client-only tsconfig).
+ */
+export async function startStdioServer(): Promise<void> {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+// Auto-start when imported as the entry (the only consumer is bin/mcp.js).
+startStdioServer();