@mcp-web/app 0.1.0

package/dist/vite-plugin.js

@@ -0,0 +1,450 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { viteSingleFile } from 'vite-plugin-singlefile';
+const CRITICAL_OVERRIDES = [
+    {
+        key: 'build.assetsInlineLimit',
+        required: Number.MAX_SAFE_INTEGER,
+        reason: 'All assets must be inlined for single-file output',
+    },
+    {
+        key: 'build.cssCodeSplit',
+        required: false,
+        reason: 'CSS must be in a single file for inlining',
+    },
+    {
+        key: 'base',
+        required: './',
+        reason: 'Relative paths required for self-contained HTML',
+    },
+];
+/**
+ * Virtual module prefix for generated app entries.
+ */
+const VIRTUAL_PREFIX = 'virtual:mcp-app/';
+const RESOLVED_VIRTUAL_PREFIX = `\0${VIRTUAL_PREFIX}`;
+/**
+ * The MCP App runtime is now handled by the ext-apps protocol
+ * via `@modelcontextprotocol/ext-apps` React hooks bundled
+ * into the app's JavaScript. No injected script is needed.
+ *
+ * Previously, this was a <script> tag that listened for
+ * `postMessage({ props })` from the host. The ext-apps protocol
+ * uses JSON-RPC 2.0 messages instead (ui/initialize, tool-result, etc.)
+ */
+/**
+ * Get a nested property value from an object using dot notation.
+ */
+function getNestedValue(obj, path) {
+    return path.split('.').reduce((current, key) => {
+        if (current && typeof current === 'object' && key in current) {
+            return current[key];
+        }
+        return undefined;
+    }, obj);
+}
+/**
+ * Convert a name to kebab-case for HTML file output.
+ */
+function toKebabCase(name) {
+    return name
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        .replace(/_/g, '-')
+        .toLowerCase();
+}
+/**
+ * Find the apps config file in the project.
+ */
+function findAppsConfigFile(projectRoot, customPath) {
+    if (customPath) {
+        const fullPath = path.resolve(projectRoot, customPath);
+        if (fs.existsSync(fullPath)) {
+            return fullPath;
+        }
+        return null;
+    }
+    const candidates = [
+        'src/mcp-apps.ts',
+        'src/mcp-apps.tsx',
+        'src/mcp/apps.ts',
+        'src/mcp/apps.tsx',
+    ];
+    for (const candidate of candidates) {
+        const fullPath = path.resolve(projectRoot, candidate);
+        if (fs.existsSync(fullPath)) {
+            return fullPath;
+        }
+    }
+    return null;
+}
+/**
+ * Parse the apps config file to extract app definitions.
+ *
+ * Uses simple regex parsing to extract:
+ * - Import statements for components
+ * - createApp calls with name and component properties
+ */
+function parseAppsConfig(configPath) {
+    const content = fs.readFileSync(configPath, 'utf-8');
+    const apps = [];
+    // Parse imports to map component names to their paths
+    const importMap = new Map();
+    const importRegex = /import\s+(?:{([^}]+)}|(\w+))\s+from\s+['"]([^'"]+)['"]/g;
+    let match;
+    while ((match = importRegex.exec(content)) !== null) {
+        const importPath = match[3];
+        if (match[2]) {
+            // Default import: import Foo from './foo'
+            importMap.set(match[2], importPath);
+        }
+        else if (match[1]) {
+            // Named imports: import { Foo, Bar as Baz } from './foo'
+            const namedImports = match[1].split(',').map((s) => s.trim());
+            for (const namedImport of namedImports) {
+                const parts = namedImport.split(/\s+as\s+/);
+                const localName = parts[1] || parts[0];
+                importMap.set(localName.trim(), importPath);
+            }
+        }
+    }
+    // Find createApp calls - match the start, then find balanced braces
+    const createAppStartRegex = /export\s+(?:const|let|var)\s+(\w+)\s*=\s*createApp\s*\(\s*\{/g;
+    while ((match = createAppStartRegex.exec(content)) !== null) {
+        const exportName = match[1];
+        const startIndex = match.index + match[0].length - 1; // Position of opening {
+        // Find the matching closing brace using brace counting
+        let braceCount = 1;
+        let endIndex = startIndex + 1;
+        while (braceCount > 0 && endIndex < content.length) {
+            const char = content[endIndex];
+            if (char === '{')
+                braceCount++;
+            else if (char === '}')
+                braceCount--;
+            endIndex++;
+        }
+        if (braceCount !== 0) {
+            // Unbalanced braces, skip this match
+            continue;
+        }
+        // Extract the config body (between the braces)
+        const configBody = content.slice(startIndex + 1, endIndex - 1);
+        // Extract name property - look for the first name: '...' or name: "..."
+        const nameMatch = configBody.match(/name\s*:\s*['"]([^'"]+)['"]/);
+        if (!nameMatch)
+            continue;
+        const name = nameMatch[1];
+        // Extract component property - look for component: <identifier>
+        const componentMatch = configBody.match(/component\s*:\s*(\w+)/);
+        if (!componentMatch)
+            continue;
+        const componentName = componentMatch[1];
+        // Look up the component's import path
+        const componentImportPath = importMap.get(componentName);
+        if (!componentImportPath) {
+            console.warn(`[mcp-web-app] Warning: Could not find import for component "${componentName}" in app "${name}"`);
+            continue;
+        }
+        apps.push({
+            name,
+            exportName,
+            componentName,
+            componentImportPath,
+        });
+    }
+    return apps;
+}
+/**
+ * Resolve a component import path to an absolute path.
+ */
+function resolveComponentPath(componentImportPath, configDir) {
+    // If it starts with . or /, it's a relative/absolute path
+    if (componentImportPath.startsWith('.') ||
+        componentImportPath.startsWith('/')) {
+        // Resolve relative to the config file's directory
+        const resolved = path.resolve(configDir, componentImportPath);
+        // Try with common extensions
+        const extensions = ['.tsx', '.ts', '.jsx', '.js'];
+        for (const ext of extensions) {
+            if (fs.existsSync(resolved + ext)) {
+                return resolved + ext;
+            }
+        }
+        if (fs.existsSync(resolved)) {
+            return resolved;
+        }
+        // Check for index files
+        for (const ext of extensions) {
+            const indexPath = path.join(resolved, `index${ext}`);
+            if (fs.existsSync(indexPath)) {
+                return indexPath;
+            }
+        }
+        return resolved;
+    }
+    // Otherwise, it's a package import - return as-is for Vite to resolve
+    return componentImportPath;
+}
+/**
+ * Generate a virtual module that renders an MCP App.
+ */
+function generateVirtualModule(componentPath, componentName) {
+    return `
+import { renderMCPApp } from '@mcp-web/app/internal';
+import { ${componentName} } from '${componentPath}';
+
+renderMCPApp(${componentName});
+`;
+}
+/**
+ * Generate HTML content for an app entry.
+ */
+function generateHTMLContent(appName, virtualModulePath) {
+    return `<!DOCTYPE html>
+<html lang="en" style="color-scheme: light dark">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>${appName}</title>
+    <style>body { margin: 0; background: transparent; }</style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="${virtualModulePath}"></script>
+  </body>
+</html>`;
+}
+/**
+ * Internal plugin that handles virtual modules and build process.
+ */
+function mcpAppPlugin(projectRoot, outDir, configPath) {
+    let apps = [];
+    let configDir;
+    const virtualModules = new Map();
+    const htmlEntries = new Map();
+    return {
+        name: 'mcp-web-app',
+        configResolved(_config) {
+            // Store config for potential future use
+        },
+        buildStart() {
+            // Clear previous state
+            virtualModules.clear();
+            htmlEntries.clear();
+            if (!configPath) {
+                console.log('\n\u26A0 No MCP Apps config file found. Looking for src/mcp-apps.ts or src/mcp/apps.ts');
+                return;
+            }
+            configDir = path.dirname(configPath);
+            apps = parseAppsConfig(configPath);
+            if (apps.length === 0) {
+                console.log(`\n\u26A0 No apps found in ${path.relative(projectRoot, configPath)}`);
+                return;
+            }
+            // Generate virtual modules for each app
+            for (const app of apps) {
+                const kebabName = toKebabCase(app.name);
+                const virtualId = `${VIRTUAL_PREFIX}${kebabName}`;
+                const resolvedVirtualId = `${RESOLVED_VIRTUAL_PREFIX}${kebabName}`;
+                // Resolve the component path
+                const absoluteComponentPath = resolveComponentPath(app.componentImportPath, configDir);
+                // Generate the virtual module content
+                const moduleContent = generateVirtualModule(absoluteComponentPath, app.componentName);
+                virtualModules.set(resolvedVirtualId, moduleContent);
+                // Generate HTML entry
+                const htmlContent = generateHTMLContent(kebabName, virtualId);
+                const htmlPath = path.join(outDir, `${kebabName}.html`);
+                htmlEntries.set(kebabName, htmlContent);
+                // Write temporary HTML file for Vite to use as entry
+                fs.mkdirSync(path.dirname(htmlPath), { recursive: true });
+            }
+            console.log(`\n\u2139 Found ${apps.length} MCP App(s) in ${path.relative(projectRoot, configPath)}`);
+        },
+        resolveId(id) {
+            if (id.startsWith(VIRTUAL_PREFIX)) {
+                return `\0${id}`;
+            }
+            return null;
+        },
+        load(id) {
+            // Handle virtual app modules
+            if (id.startsWith(RESOLVED_VIRTUAL_PREFIX)) {
+                return virtualModules.get(id) || null;
+            }
+            return null;
+        },
+        generateBundle() {
+            // Don't emit additional HTML - let vite-plugin-singlefile handle the output
+            // The inlined HTML will be at a nested path which we'll fix in closeBundle
+        },
+        closeBundle() {
+            if (apps.length === 0)
+                return;
+            // The inlined HTML files are output to a nested path matching the temp directory structure
+            // Move them to the root of the output directory
+            const tempSubDir = path.join(outDir, 'node_modules', '.mcp-web-app-temp');
+            if (fs.existsSync(tempSubDir)) {
+                for (const app of apps) {
+                    const kebabName = toKebabCase(app.name);
+                    const srcPath = path.join(tempSubDir, `${kebabName}.html`);
+                    const destPath = path.join(outDir, `${kebabName}.html`);
+                    if (fs.existsSync(srcPath)) {
+                        // Move the inlined HTML to the root
+                        fs.copyFileSync(srcPath, destPath);
+                    }
+                }
+                // Clean up the nested directory
+                fs.rmSync(path.join(outDir, 'node_modules'), { recursive: true, force: true });
+            }
+            const relOutDir = path.relative(projectRoot, outDir);
+            console.log(`\n\u2713 Built ${apps.length} MCP App(s) to ${relOutDir}/`);
+            for (const app of apps) {
+                const kebabName = toKebabCase(app.name);
+                console.log(`   - ${kebabName}.html (${app.exportName})`);
+            }
+        },
+    };
+}
+/**
+ * Define a Vite configuration for building MCP Apps as single HTML files.
+ *
+ * This function creates a complete Vite config that auto-discovers app
+ * definitions and bundles them into self-contained HTML files. These files
+ * can be served as MCP App resources that render inline in AI chat interfaces.
+ *
+ * **How it works:**
+ * 1. Scans for a config file (`src/mcp-apps.ts` or `src/mcp/apps.ts`)
+ * 2. Parses `createApp()` calls to find app names and components
+ * 3. Auto-generates entry files that render each component
+ * 4. Bundles everything into single HTML files
+ *
+ * **Features:**
+ * - No manual entry files needed - just define your apps!
+ * - Full Vite config flexibility - pass any standard Vite options
+ * - Automatic single-file bundling (JS, CSS, assets all inlined)
+ * - Watch mode support for development
+ * - PostMessage runtime for receiving props from the host
+ *
+ * **Critical settings that are always enforced:**
+ * - `build.assetsInlineLimit` → Maximum (for inlining)
+ * - `build.cssCodeSplit` → false (single CSS bundle)
+ * - `base` → './' (relative paths)
+ *
+ * @param viteConfig - Standard Vite configuration options (plugins, build settings, etc.)
+ * @param mcpOptions - MCP-specific options (appsConfig, outDir, silenceOverrideWarnings)
+ * @returns A Vite UserConfigExport ready for use in vite.config.ts
+ *
+ * @example Basic Usage
+ * ```typescript
+ * // vite.apps.config.ts
+ * import react from '@vitejs/plugin-react';
+ * import { defineMCPAppsConfig } from '@mcp-web/app/vite';
+ *
+ * export default defineMCPAppsConfig({
+ *   plugins: [react()],
+ * });
+ * ```
+ *
+ * @example With Custom Options
+ * ```typescript
+ * import react from '@vitejs/plugin-react';
+ * import { defineMCPAppsConfig } from '@mcp-web/app/vite';
+ *
+ * export default defineMCPAppsConfig(
+ *   {
+ *     plugins: [react()],
+ *     build: {
+ *       sourcemap: true,
+ *       minify: 'terser',
+ *     },
+ *   },
+ *   {
+ *     appsConfig: 'src/my-apps.ts',
+ *     outDir: 'dist/apps',
+ *   }
+ * );
+ * ```
+ *
+ * @example Apps Config File (src/mcp-apps.ts)
+ * ```typescript
+ * import { createApp } from '@mcp-web/app';
+ * import { Statistics } from './components/Statistics';
+ *
+ * export const statisticsApp = createApp({
+ *   name: 'show_statistics',
+ *   description: 'Display statistics visualization',
+ *   component: Statistics,
+ *   handler: () => ({
+ *     completionRate: 0.75,
+ *     totalTasks: 100,
+ *   }),
+ * });
+ * ```
+ */
+export function defineMCPAppsConfig(viteConfig = {}, mcpOptions = {}) {
+    const { appsConfig, outDir = 'public/mcp-web-apps', silenceOverrideWarnings = false, } = mcpOptions;
+    const projectRoot = process.cwd();
+    const outDirPath = path.resolve(projectRoot, outDir);
+    // Find the apps config file
+    const configPath = findAppsConfigFile(projectRoot, appsConfig);
+    // Parse apps to generate rollup inputs
+    let apps = [];
+    let tempHtmlDir = null;
+    const input = {};
+    if (configPath) {
+        apps = parseAppsConfig(configPath);
+        if (apps.length > 0) {
+            // Create a temp directory for HTML entries
+            tempHtmlDir = path.join(projectRoot, 'node_modules', '.mcp-web-app-temp');
+            fs.mkdirSync(tempHtmlDir, { recursive: true });
+            // Generate HTML entries for rollup input
+            for (const app of apps) {
+                const kebabName = toKebabCase(app.name);
+                const htmlPath = path.join(tempHtmlDir, `${kebabName}.html`);
+                const virtualModulePath = `${VIRTUAL_PREFIX}${kebabName}`;
+                const htmlContent = generateHTMLContent(kebabName, virtualModulePath);
+                fs.writeFileSync(htmlPath, htmlContent);
+                input[kebabName] = htmlPath;
+            }
+        }
+    }
+    // Check for and warn about overridden settings
+    if (!silenceOverrideWarnings) {
+        const userConfig = viteConfig;
+        for (const override of CRITICAL_OVERRIDES) {
+            const userValue = getNestedValue(userConfig, override.key);
+            if (userValue !== undefined && userValue !== override.required) {
+                console.warn(`[mcp-web-app] Warning: Overriding ${override.key} ` +
+                    `(was: ${JSON.stringify(userValue)}, now: ${JSON.stringify(override.required)}). ` +
+                    `Reason: ${override.reason}`);
+            }
+        }
+    }
+    // Build the merged config
+    const mergedConfig = {
+        ...viteConfig,
+        // These are always set by MCP Apps
+        base: './',
+        plugins: [
+            // User plugins first
+            ...(viteConfig.plugins || []),
+            // Then our plugins
+            viteSingleFile(),
+            mcpAppPlugin(projectRoot, outDirPath, configPath),
+        ],
+        build: {
+            ...viteConfig.build,
+            outDir: outDirPath,
+            emptyOutDir: true,
+            // Critical overrides for single-file output
+            assetsInlineLimit: Number.MAX_SAFE_INTEGER,
+            cssCodeSplit: false,
+            rollupOptions: {
+                ...viteConfig.build?.rollupOptions,
+                input: Object.keys(input).length > 0 ? input : undefined,
+            },
+        },
+    };
+    return mergedConfig;
+}
+export default defineMCPAppsConfig;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@mcp-web/app",
+  "version": "0.1.0",
+  "description": "Build tooling for MCP Apps - bundle React components into single HTML files for AI UI rendering",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./vite": {
+      "import": "./dist/vite-plugin.js",
+      "types": "./dist/vite-plugin.d.ts"
+    },
+    "./internal": {
+      "import": "./dist/internal.js",
+      "types": "./dist/internal.d.ts"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.0.1",
+    "vite-plugin-singlefile": "^2.3.0",
+    "zod": "~4.1.12",
+    "@mcp-web/types": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.9",
+    "@types/react": "^18.3.24",
+    "@types/react-dom": "^18.3.7",
+    "typescript": "~5.9.3",
+    "vite": "^7.3.1"
+  },
+  "peerDependencies": {
+    "react": ">=17.0.0",
+    "react-dom": ">=17.0.0",
+    "vite": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "bun test"
+  }
+}

package/src/create-app.test.ts

@@ -0,0 +1,181 @@
+import { describe, expect, test } from 'bun:test';
+import type { ComponentType } from 'react';
+import { z } from 'zod';
+import { createApp, isCreatedApp } from '../src/create-app';
+
+// Mock components for testing
+const MockComponent: ComponentType<{ value: number }> = () => null;
+const MockResultComponent: ComponentType<{ result: string }> = () => null;
+const MockInputComponent: ComponentType<{
+  greeting: string;
+  doubled: number;
+}> = () => null;
+const MockEmptyComponent: ComponentType<Record<string, unknown>> = () => null;
+const MockOutputComponent: ComponentType<{ output: string }> = () => null;
+const MockAsyncComponent: ComponentType<{ async: boolean }> = () => null;
+
+describe('createApp', () => {
+  test('creates a valid app definition', () => {
+    const app = createApp({
+      name: 'test_app',
+      description: 'A test app',
+      component: MockComponent,
+      handler: () => ({ value: 42 }),
+    });
+
+    expect(app.__brand).toBe('CreatedApp');
+    expect(app.definition.name).toBe('test_app');
+    expect(app.definition.description).toBe('A test app');
+    expect(typeof app.definition.handler).toBe('function');
+    expect(app.definition.component).toBe(MockComponent);
+  });
+
+  test('preserves handler functionality', async () => {
+    const app = createApp({
+      name: 'handler_test',
+      description: 'Test handler',
+      component: MockResultComponent,
+      handler: () => ({ result: 'success' }),
+    });
+
+    const result = await app.definition.handler();
+    expect(result).toEqual({ result: 'success' });
+  });
+
+  test('handler receives input when inputSchema is defined', async () => {
+    const InputSchema = z.object({
+      name: z.string(),
+      count: z.number(),
+    });
+
+    const app = createApp({
+      name: 'input_test',
+      description: 'Test input',
+      component: MockInputComponent,
+      inputSchema: InputSchema,
+      handler: ({ name, count }) => ({
+        greeting: `Hello ${name}`,
+        doubled: count * 2,
+      }),
+    });
+
+    const result = await app.definition.handler({ name: 'World', count: 21 });
+    expect(result).toEqual({
+      greeting: 'Hello World',
+      doubled: 42,
+    });
+  });
+
+  test('preserves optional url and resourceUri', () => {
+    const app = createApp({
+      name: 'custom_urls',
+      description: 'Custom URLs',
+      component: MockEmptyComponent,
+      handler: () => ({}),
+      url: '/custom/app.html',
+      resourceUri: 'ui://custom/app',
+    });
+
+    expect(app.definition.url).toBe('/custom/app.html');
+    expect(app.definition.resourceUri).toBe('ui://custom/app');
+  });
+
+  test('preserves inputSchema and propsSchema', () => {
+    const InputSchema = z.object({ input: z.string() });
+    const PropsSchema = z.object({ output: z.string() });
+
+    const app = createApp({
+      name: 'schema_test',
+      description: 'Schema test',
+      component: MockOutputComponent,
+      inputSchema: InputSchema,
+      propsSchema: PropsSchema,
+      handler: ({ input }) => ({ output: input.toUpperCase() }),
+    });
+
+    expect(app.definition.inputSchema).toBe(InputSchema);
+    expect(app.definition.propsSchema).toBe(PropsSchema);
+  });
+
+  test('throws error for invalid app definition - missing name', () => {
+    expect(() => {
+      createApp({
+        name: '',
+        description: 'Test',
+        component: MockEmptyComponent,
+        handler: () => ({}),
+      });
+    }).toThrow('Invalid app definition');
+  });
+
+  test('throws error for invalid app definition - missing description', () => {
+    expect(() => {
+      createApp({
+        name: 'test',
+        description: '',
+        component: MockEmptyComponent,
+        handler: () => ({}),
+      });
+    }).toThrow('Invalid app definition');
+  });
+
+  test('async handler works correctly', async () => {
+    const app = createApp({
+      name: 'async_test',
+      description: 'Async handler test',
+      component: MockAsyncComponent,
+      handler: async () => {
+        await new Promise((resolve) => setTimeout(resolve, 10));
+        return { async: true };
+      },
+    });
+
+    const result = await app.definition.handler();
+    expect(result).toEqual({ async: true });
+  });
+});
+
+describe('isCreatedApp', () => {
+  test('returns true for CreatedApp', () => {
+    const app = createApp({
+      name: 'test',
+      description: 'test',
+      component: MockEmptyComponent,
+      handler: () => ({}),
+    });
+
+    expect(isCreatedApp(app)).toBe(true);
+  });
+
+  test('returns false for null', () => {
+    expect(isCreatedApp(null)).toBe(false);
+  });
+
+  test('returns false for undefined', () => {
+    expect(isCreatedApp(undefined)).toBe(false);
+  });
+
+  test('returns false for plain object', () => {
+    expect(isCreatedApp({})).toBe(false);
+  });
+
+  test('returns false for object with wrong brand', () => {
+    expect(isCreatedApp({ __brand: 'NotCreatedApp' })).toBe(false);
+  });
+
+  test('returns false for app definition without brand', () => {
+    expect(
+      isCreatedApp({
+        name: 'test',
+        description: 'test',
+        handler: () => ({}),
+      })
+    ).toBe(false);
+  });
+
+  test('returns false for primitives', () => {
+    expect(isCreatedApp('string')).toBe(false);
+    expect(isCreatedApp(123)).toBe(false);
+    expect(isCreatedApp(true)).toBe(false);
+  });
+});