Implement React UI Builder and Enhance Greeting Widget (#58)

* feat(ui-builder): Implement React UI definition and HTML generation utilities

- Added `defineReactUI` and `isReactUIDef` functions for defining and validating React-based UI components.
- Introduced `generateHTML` and `generateEntryPoint` functions for creating self-contained HTML documents and entry points for React components.
- Developed transformation utilities to convert React UI definitions to standard UIDef format.
- Created comprehensive type definitions for React UI components and build configurations.
- Implemented unit tests for all new functionalities to ensure reliability and correctness.
- Configured TypeScript and build settings for the new package structure.

* feat(minimal-example): Enhance Greeting Widget with React UI integration and update package configuration

* feat: Add publishing step for ui-react-builder and update release scripts

* feat(ui-react-builder): Update README with ui-react-builder package details and usage examples

* feat: Enhance tool output handling by wrapping results with tool names in MCP and OpenAI adapters

* feat: Enhance type safety across UI components and tools with ClientToolsFromCore integration

* refactor: Simplify JSX structure in Widget component and streamline output type extraction logic

* feat: Enhance UI React Builder with AST-based parsing and improved logging

- Added AST-based parser for discovering defineReactUI calls using @typescript-eslint/typescript-estree.
- Updated buildReactUIs function to include detailed limitations and usage notes.
- Introduced custom logging options for the Vite plugin, allowing for silent or custom loggers.
- Improved component path resolution with better error handling and logging.
- Updated unit tests for the new AST parser, covering various import scenarios and edge cases.
- Added dependencies for @typescript-eslint/typescript-estree and updated package.json accordingly.

Author: gabe4coding

.github/workflows/publish.yml

@@ -56,5 +56,8 @@ jobs:
       - name: Publish @mcp-apps-kit/ui-react
         run: pnpm --filter @mcp-apps-kit/ui-react exec npm publish --access public --provenance
 
+      - name: Publish @mcp-apps-kit/ui-react-builder
+        run: pnpm --filter @mcp-apps-kit/ui-react-builder exec npm publish --access public --provenance
+
       - name: Publish @mcp-apps-kit/create-app
         run: pnpm --filter @mcp-apps-kit/create-app exec npm publish --access public --provenance

README.md

@@ -7,6 +7,7 @@
 [![npm @mcp-apps-kit/core](https://img.shields.io/npm/v/%40mcp-apps-kit%2Fcore?label=%40mcp-apps-kit%2Fcore&logo=npm)](https://www.npmjs.com/package/@mcp-apps-kit/core)
 [![npm @mcp-apps-kit/ui](https://img.shields.io/npm/v/%40mcp-apps-kit%2Fui?label=%40mcp-apps-kit%2Fui&logo=npm)](https://www.npmjs.com/package/@mcp-apps-kit/ui)
 [![npm @mcp-apps-kit/ui-react](https://img.shields.io/npm/v/%40mcp-apps-kit%2Fui-react?label=%40mcp-apps-kit%2Fui-react&logo=npm)](https://www.npmjs.com/package/@mcp-apps-kit/ui-react)
+[![npm @mcp-apps-kit/ui-react-builder](https://img.shields.io/npm/v/%40mcp-apps-kit%2Fui-react-builder?label=%40mcp-apps-kit%2Fui-react-builder&logo=npm)](https://www.npmjs.com/package/@mcp-apps-kit/ui-react-builder)
 [![npm @mcp-apps-kit/create-app](https://img.shields.io/npm/v/%40mcp-apps-kit%2Fcreate-app?label=%40mcp-apps-kit%2Fcreate-app&logo=npm)](https://www.npmjs.com/package/@mcp-apps-kit/create-app)
 
 Build interactive AI apps for [MCP Apps](https://blog.modelcontextprotocol.io/posts/2025-11-21-mcp-apps/) and [ChatGPT](https://developers.openai.com/apps-sdk) from a single codebase.
@@ -21,6 +22,7 @@ MCP AppsKit is a TypeScript framework for building interactive applications with
 - [Compatibility](#compatibility)
 - [Install](#install)
 - [Usage](#usage)
+  - [React Component UIs](#react-component-uis)
 - [Type-Safe Tool Definitions](#type-safe-tool-definitions)
 - [How It Works](#how-it-works)
 - [Deployment Options](#deployment-options)
@@ -70,12 +72,13 @@ This project may be a poor fit if you:
 
 ## Packages
 
-| Package                    | Description                  |
-| -------------------------- | ---------------------------- |
-| `@mcp-apps-kit/core`       | Server-side framework        |
-| `@mcp-apps-kit/ui`         | Client-side SDK (vanilla JS) |
-| `@mcp-apps-kit/ui-react`   | React bindings               |
-| `@mcp-apps-kit/create-app` | CLI scaffolding tool         |
+| Package                          | Description                        |
+| -------------------------------- | ---------------------------------- |
+| `@mcp-apps-kit/core`             | Server-side framework              |
+| `@mcp-apps-kit/ui`               | Client-side SDK (vanilla JS)       |
+| `@mcp-apps-kit/ui-react`         | React bindings                     |
+| `@mcp-apps-kit/ui-react-builder` | Build tool for React component UIs |
+| `@mcp-apps-kit/create-app`       | CLI scaffolding tool               |
 
 ## Compatibility
 
@@ -107,6 +110,12 @@ Vanilla UI SDK:
 npm install @mcp-apps-kit/ui
 ```
 
+React UI builder (for defining UIs with React components):
+
+```bash
+npm install @mcp-apps-kit/ui-react-builder
+```
+
 CLI scaffolding tool:
 
 ```bash
@@ -180,6 +189,7 @@ import { useAppsClient, useToolResult, useHostContext } from "@mcp-apps-kit/ui-r
 import type { AppClientTools } from "../../server";
 
 function RestaurantList() {
+  // Type-safe hooks - tool names, inputs, and outputs are all inferred
   const client = useAppsClient<AppClientTools>();
   const result = useToolResult<AppClientTools>();
   const context = useHostContext();
@@ -207,6 +217,58 @@ function RestaurantList() {
 }
 ```
 
+### React Component UIs
+
+Instead of pre-building HTML files, you can define UIs using React components directly with `@mcp-apps-kit/ui-react-builder`:
+
+```typescript
+// server/index.ts
+import { createApp, defineTool } from "@mcp-apps-kit/core";
+import { defineReactUI } from "@mcp-apps-kit/ui-react-builder";
+import { RestaurantList } from "./ui/RestaurantList";
+import { z } from "zod";
+
+const app = createApp({
+  name: "restaurant-finder",
+  version: "1.0.0",
+  tools: {
+    search_restaurants: defineTool({
+      description: "Search for restaurants",
+      input: z.object({ location: z.string() }),
+      output: z.object({ restaurants: z.array(z.unknown()) }),
+      // Define UI with React component - auto-builds to HTML
+      ui: defineReactUI({
+        component: RestaurantList,
+        name: "Restaurant List",
+        prefersBorder: true,
+      }),
+      handler: async (input) => {
+        return { restaurants: await fetchRestaurants(input.location) };
+      },
+    }),
+  },
+});
+```
+
+Configure the Vite plugin to auto-discover and build React UIs:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import { mcpReactUI } from "@mcp-apps-kit/ui-react-builder/vite";
+
+export default defineConfig({
+  plugins: [
+    mcpReactUI({
+      serverEntry: "./src/index.ts",
+      outDir: "./src/ui/dist",
+    }),
+  ],
+});
+```
+
+The plugin scans your server entry for `defineReactUI` calls, bundles each component with React and `@mcp-apps-kit/ui-react`, and outputs self-contained HTML files.
+
 ### CLI
 
 ```bash
@@ -396,6 +458,7 @@ Detailed package documentation:
 - [packages/core/README.md](packages/core/README.md)
 - [packages/ui/README.md](packages/ui/README.md)
 - [packages/ui-react/README.md](packages/ui-react/README.md)
+- [packages/ui-react-builder/README.md](packages/ui-react-builder/README.md)
 - [packages/create-app/README.md](packages/create-app/README.md)
 
 ## Contributing

eslint.config.js

@@ -12,11 +12,19 @@ export default [
   },
   // Server-side packages (Node.js environment)
   {
-    files: ["packages/core/**/*.ts", "packages/create-app/**/*.ts"],
+    files: [
+      "packages/core/**/*.ts",
+      "packages/create-app/**/*.ts",
+      "packages/ui-react-builder/**/*.ts",
+    ],
     languageOptions: {
       parser: tsparser,
       parserOptions: {
-        project: ["./packages/core/tsconfig.json", "./packages/create-app/tsconfig.json"],
+        project: [
+          "./packages/core/tsconfig.json",
+          "./packages/create-app/tsconfig.json",
+          "./packages/ui-react-builder/tsconfig.json",
+        ],
         tsconfigRootDir: import.meta.dirname,
       },
       globals: {

examples/minimal/package.json

@@ -2,7 +2,7 @@
   "name": "@mcp-apps-kit/example-minimal",
   "version": "0.1.0",
   "private": true,
-  "description": "Minimal example demonstrating basic @mcp-apps-kit/core usage",
+  "description": "Minimal example demonstrating basic @mcp-apps-kit/core usage with React UI",
   "type": "module",
   "scripts": {
     "dev": "concurrently \"pnpm dev:server\" \"pnpm dev:ui\"",
@@ -16,10 +16,17 @@
   "dependencies": {
     "@mcp-apps-kit/core": "workspace:*",
     "@mcp-apps-kit/ui": "workspace:*",
+    "@mcp-apps-kit/ui-react-builder": "workspace:*",
+    "@mcp-apps-kit/ui-react": "workspace:*",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
     "zod": "^4.0.0"
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
     "concurrently": "^9.2.1",
     "tsx": "^4.0.0",
     "typescript": "^5.0.0",

examples/minimal/src/index.ts

@@ -8,7 +8,9 @@
  * - Type-safe handlers using defineTool helper (no type assertions needed!)
  */
 
-import { createApp, defineTool, defineUI, type ClientToolsFromCore } from "@mcp-apps-kit/core";
+import { createApp, defineTool, type ClientToolsFromCore } from "@mcp-apps-kit/core";
+import { defineReactUI } from "@mcp-apps-kit/ui-react-builder";
+import { GreetingWidget } from "./ui/GreetingWidget";
 import { z } from "zod";
 
 // Define schemas separately for clarity
@@ -30,11 +32,11 @@ const greetTool = defineTool({
   output: greetOutput,
   visibility: "both",
 
-  // Colocated UI definition - no separate ui config needed!
-  ui: defineUI({
+  // React component UI - the Vite plugin auto-discovers and builds this!
+  ui: defineReactUI({
+    component: GreetingWidget,
     name: "Greeting Widget",
     description: "Displays greeting messages",
-    html: "./src/ui/dist/index.html",
     prefersBorder: true,
   }),
 

examples/minimal/src/ui/GreetingWidget.tsx

@@ -0,0 +1,47 @@
+/**
+ * Greeting Widget Component
+ *
+ * A React component that displays greeting messages from the greet tool.
+ * Uses @mcp-apps-kit/ui-react hooks for receiving tool output and theme changes.
+ */
+
+import { useEffect } from "react";
+import { useToolResult, useHostContext } from "@mcp-apps-kit/ui-react";
+import type { AppClientTools } from "../index";
+
+export function GreetingWidget() {
+  const result = useToolResult<AppClientTools>();
+  const { theme } = useHostContext();
+
+  // Extract the greet output - result contains the tool outputs keyed by tool name
+  const greetOutput = result?.greet;
+
+  // Apply theme to document
+  useEffect(() => {
+    if (typeof document !== "undefined") {
+      document.documentElement.className = theme;
+    }
+  }, [theme]);
+
+  if (greetOutput?.message) {
+    const date = new Date(greetOutput.timestamp);
+    const timeStr = date.toLocaleTimeString();
+
+    return (
+      <div className="container">
+        <div className="greeting">
+          <h1>{greetOutput.message}</h1>
+          <p className="timestamp">at {timeStr}</p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="container">
+      <p className="waiting">Waiting for greeting...</p>
+    </div>
+  );
+}
+
+export default GreetingWidget;