@mcp-web/app 0.1.0

package/src/mcp-app-context.tsx

@@ -0,0 +1,183 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useState,
+  type ReactNode,
+} from 'react';
+import { useApp, useHostStyles, useDocumentTheme } from '@modelcontextprotocol/ext-apps/react';
+import type { App, McpUiHostContext } from '@modelcontextprotocol/ext-apps';
+
+/**
+ * Value provided by `MCPAppProvider`.
+ *
+ * Contains the ext-apps `App` instance, connection state, and the
+ * current host context (theme, styles, display mode, locale, etc.).
+ */
+export interface MCPAppContextValue {
+  /** The connected ext-apps `App` instance, null during initialization */
+  app: App | null;
+  /** Whether initialization completed successfully */
+  isConnected: boolean;
+  /** Connection error if initialization failed, null otherwise */
+  error: Error | null;
+  /** Current host context, undefined until connected */
+  hostContext: McpUiHostContext | undefined;
+}
+
+const MCPAppContext = createContext<MCPAppContextValue | null>(null);
+
+/**
+ * Provider that creates the ext-apps `App` instance and applies host styles.
+ *
+ * This provider:
+ * - Creates and manages the `App` connection via `useApp()`
+ * - Automatically applies the host's CSS custom properties, theme, and fonts
+ * - Tracks host context changes (theme toggles, display mode changes, etc.)
+ * - Makes the app instance and host context available to child components
+ *
+ * @internal Used by `renderMCPApp` — not typically used directly.
+ */
+export function MCPAppProvider({ children }: { children: ReactNode }) {
+  const [hostContext, setHostContext] = useState<
+    McpUiHostContext | undefined
+  >(undefined);
+
+  const onAppCreated = useCallback((app: App) => {
+    app.onhostcontextchanged = (params) => {
+      setHostContext((prev) => ({ ...prev, ...params }));
+    };
+  }, []);
+
+  const { app, isConnected, error } = useApp({
+    appInfo: {
+      name: 'mcp-web-app',
+      version: '0.1.0',
+    },
+    capabilities: {},
+    onAppCreated,
+  });
+
+  // Capture initial host context once connected
+  const initialContext = app?.getHostContext();
+  if (initialContext && !hostContext) {
+    setHostContext(initialContext);
+  }
+
+  // Automatically apply host CSS variables, theme, and fonts
+  useHostStyles(app, initialContext);
+
+  return (
+    <MCPAppContext.Provider
+      value={{ app, isConnected, error, hostContext }}
+    >
+      {children}
+    </MCPAppContext.Provider>
+  );
+}
+
+/**
+ * Access the full MCP App context including the app instance and host context.
+ *
+ * Must be called within an `MCPAppProvider` (which is set up automatically
+ * by `renderMCPApp`).
+ *
+ * @returns The context value with app, connection state, and host context
+ * @throws If called outside of an MCPAppProvider
+ *
+ * @internal Used by `useMCPAppProps` and `useMCPApp`.
+ */
+export function useMCPAppContext(): MCPAppContextValue {
+  const ctx = useContext(MCPAppContext);
+  if (!ctx) {
+    throw new Error(
+      'useMCPAppContext must be used within an MCPAppProvider. ' +
+        'If you are using renderMCPApp(), this is set up automatically. ' +
+        'Otherwise, wrap your component tree with <MCPAppProvider>.'
+    );
+  }
+  return ctx;
+}
+
+/**
+ * Get the current host context from the MCP host application.
+ *
+ * Returns the full `McpUiHostContext` from the host (e.g., Claude Desktop),
+ * which includes theme, styles, display mode, locale, container dimensions,
+ * and more. The value updates automatically when the host sends
+ * `host-context-changed` notifications.
+ *
+ * Must be called within an `MCPAppProvider` (set up automatically
+ * by `renderMCPApp`).
+ *
+ * @returns The current host context, or undefined if not yet connected
+ *
+ * @example Access host display mode
+ * ```tsx
+ * import { useMCPHostContext } from '@mcp-web/app';
+ *
+ * function MyApp() {
+ *   const hostContext = useMCPHostContext();
+ *
+ *   return (
+ *     <div>
+ *       <p>Display mode: {hostContext?.displayMode}</p>
+ *       <p>Platform: {hostContext?.platform}</p>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useMCPHostContext(): McpUiHostContext | undefined {
+  return useMCPAppContext().hostContext;
+}
+
+/**
+ * Get the current theme preference from the MCP host application.
+ *
+ * Returns `"light"` or `"dark"` based on the host's current theme.
+ * Updates reactively when the user toggles theme in the host.
+ *
+ * This hook reads the theme from the `data-theme` attribute on
+ * `document.documentElement`, which is set automatically by the
+ * host styles system. It uses a `MutationObserver` internally so
+ * it will re-render your component whenever the theme changes.
+ *
+ * Must be called within an `MCPAppProvider` (set up automatically
+ * by `renderMCPApp`).
+ *
+ * @returns The current theme — `"light"` or `"dark"`
+ *
+ * @example Sync with Tailwind CSS dark mode
+ * ```tsx
+ * import { useMCPHostTheme } from '@mcp-web/app';
+ * import { useEffect } from 'react';
+ *
+ * function MyApp(props: MyProps) {
+ *   const theme = useMCPHostTheme();
+ *
+ *   useEffect(() => {
+ *     document.documentElement.classList.toggle('dark', theme === 'dark');
+ *   }, [theme]);
+ *
+ *   return (
+ *     <div className="bg-white dark:bg-gray-900">
+ *       {props.children}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Conditional rendering based on theme
+ * ```tsx
+ * import { useMCPHostTheme } from '@mcp-web/app';
+ *
+ * function Logo() {
+ *   const theme = useMCPHostTheme();
+ *   return <img src={theme === 'dark' ? '/logo-light.svg' : '/logo-dark.svg'} />;
+ * }
+ * ```
+ */
+export function useMCPHostTheme() {
+  return useDocumentTheme();
+}

package/src/render-mcp-app.tsx

@@ -0,0 +1,141 @@
+import type { ComponentType } from 'react';
+import { StrictMode, Suspense } from 'react';
+import { createRoot } from 'react-dom/client';
+import { MCPAppProvider } from './mcp-app-context.js';
+import { useMCPAppProps } from './use-mcp-app-props.js';
+
+/**
+ * Options for rendering an MCP App.
+ */
+export interface RenderMCPAppOptions {
+  /**
+   * Component to show while waiting for props.
+   * @default A simple "Loading..." div
+   */
+  loading?: ComponentType;
+
+  /**
+   * ID of the root element to mount the app.
+   * @default 'root'
+   */
+  rootId?: string;
+
+  /**
+   * Whether to wrap the app in React.StrictMode.
+   * @default true
+   */
+  strictMode?: boolean;
+}
+
+/**
+ * Default loading component shown while waiting for props.
+ * Uses host CSS variable with fallback for theme-aware loading text.
+ */
+function DefaultLoading() {
+  return (
+    <div
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        height: '100%',
+        fontFamily: 'var(--font-sans, system-ui, sans-serif)',
+        color: 'var(--color-text-secondary, #666)',
+      }}
+    >
+      Loading...
+    </div>
+  );
+}
+
+/**
+ * Internal wrapper that handles props subscription.
+ */
+function MCPAppWrapper<P extends Record<string, unknown>>({
+  Component,
+  Loading,
+}: {
+  Component: ComponentType<P>;
+  Loading: ComponentType;
+}) {
+  const props = useMCPAppProps<P>();
+
+  if (!props) {
+    return <Loading />;
+  }
+
+  return <Component {...props} />;
+}
+
+/**
+ * Render a React component as an MCP App.
+ *
+ * This helper sets up the React root and handles props subscription,
+ * so your component can be a regular React component that receives props -
+ * no MCP-specific code required in your component.
+ *
+ * @param Component - Your React component (receives props from the MCP handler)
+ * @param options - Optional configuration for loading state and root element
+ *
+ * @example Basic usage with an existing component
+ * ```tsx
+ * // src/apps/stats.tsx
+ * import { renderMCPApp } from '@mcp-web/app';
+ * import { Stats } from '../components/Stats';
+ *
+ * // Stats is a regular component: function Stats({ total, completed }: StatsProps) { ... }
+ * renderMCPApp(Stats);
+ * ```
+ *
+ * @example With custom loading component
+ * ```tsx
+ * import { renderMCPApp } from '@mcp-web/app';
+ * import { Stats } from '../components/Stats';
+ * import { Spinner } from '../components/Spinner';
+ *
+ * renderMCPApp(Stats, {
+ *   loading: Spinner,
+ * });
+ * ```
+ *
+ * @example Inline component definition
+ * ```tsx
+ * import { renderMCPApp } from '@mcp-web/app';
+ *
+ * interface ChartProps {
+ *   data: number[];
+ *   title: string;
+ * }
+ *
+ * renderMCPApp<ChartProps>(({ data, title }) => (
+ *   <div>
+ *     <h1>{title}</h1>
+ *     <Chart data={data} />
+ *   </div>
+ * ));
+ * ```
+ */
+export function renderMCPApp<P extends Record<string, unknown>>(
+  Component: ComponentType<P>,
+  options: RenderMCPAppOptions = {}
+): void {
+  const { loading: Loading = DefaultLoading, rootId = 'root', strictMode = true } = options;
+
+  const rootElement = document.getElementById(rootId);
+  if (!rootElement) {
+    throw new Error(
+      `[renderMCPApp] Could not find element with id "${rootId}". ` +
+        `Make sure your HTML has <div id="${rootId}"></div>`
+    );
+  }
+
+  const app = (
+    <Suspense fallback={<Loading />}>
+      <MCPAppProvider>
+        <MCPAppWrapper Component={Component} Loading={Loading} />
+      </MCPAppProvider>
+    </Suspense>
+  );
+
+  createRoot(rootElement).render(strictMode ? <StrictMode>{app}</StrictMode> : app);
+}

package/src/use-mcp-app-props.ts

@@ -0,0 +1,166 @@
+import { useEffect, useState } from 'react';
+import { useMCPAppContext } from './mcp-app-context.js';
+
+/**
+ * React hook to receive props from the MCP host via the ext-apps protocol.
+ *
+ * This hook connects to the host (e.g., Claude Desktop) using the
+ * `@modelcontextprotocol/ext-apps` JSON-RPC protocol. It listens for
+ * `tool-result` notifications, which contain the props returned by the
+ * tool handler as JSON in `content[0].text`.
+ *
+ * Must be called within an `MCPAppProvider` (set up automatically
+ * by `renderMCPApp`).
+ *
+ * @template T - The type of props expected from the handler
+ * @returns The props object, or null if not yet received
+ *
+ * @example Basic Usage
+ * ```tsx
+ * import { useMCPAppProps } from '@mcp-web/app';
+ *
+ * interface MyAppProps {
+ *   title: string;
+ *   data: number[];
+ * }
+ *
+ * function MyApp() {
+ *   const props = useMCPAppProps<MyAppProps>();
+ *
+ *   if (!props) {
+ *     return <div>Waiting for data...</div>;
+ *   }
+ *
+ *   return (
+ *     <div>
+ *       <h1>{props.title}</h1>
+ *       <ul>
+ *         {props.data.map((item, i) => (
+ *           <li key={i}>{item}</li>
+ *         ))}
+ *       </ul>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example With Default Props for Development
+ * ```tsx
+ * function MyApp() {
+ *   const props = useMCPAppProps<MyAppProps>() ?? {
+ *     title: 'Development Preview',
+ *     data: [1, 2, 3],
+ *   };
+ *
+ *   return <div>{props.title}</div>;
+ * }
+ * ```
+ */
+export function useMCPAppProps<T>(): T | null {
+  const [props, setProps] = useState<T | null>(null);
+  const { app } = useMCPAppContext();
+
+  useEffect(() => {
+    if (!app) return;
+
+    // Listen for tool result - this is where our props come from.
+    // The tool handler returns props which the bridge wraps into
+    // CallToolResult.content[0].text as JSON.
+    app.ontoolresult = async (result) => {
+      if (result?.content) {
+        for (const block of result.content) {
+          if (block.type === 'text' && typeof block.text === 'string') {
+            try {
+              const parsed = JSON.parse(block.text);
+              setProps(parsed as T);
+            } catch {
+              // If JSON parsing fails, treat the text as-is
+              setProps(block.text as unknown as T);
+            }
+            return;
+          }
+        }
+      }
+    };
+
+    // Also listen for tool input - useful for apps that need
+    // the raw tool call arguments
+    app.ontoolinput = async (input) => {
+      // If we have arguments and no result yet, use them as initial props.
+      // This enables apps to render immediately with the tool input
+      // before the full result arrives.
+      if (input?.arguments) {
+        setProps((prev) => prev ?? (input.arguments as unknown as T));
+      }
+    };
+  }, [app]);
+
+  return props;
+}
+
+/**
+ * Get the ext-apps `App` instance for advanced use cases.
+ *
+ * This hook provides access to the underlying `App` class from
+ * `@modelcontextprotocol/ext-apps`, enabling bidirectional communication
+ * with the host (e.g., calling server tools, sending messages).
+ *
+ * Must be called within an `MCPAppProvider` (set up automatically
+ * by `renderMCPApp`).
+ *
+ * @returns The App state including app instance, connection status, and errors
+ *
+ * @example Calling a server tool from the app
+ * ```tsx
+ * import { useMCPApp } from '@mcp-web/app';
+ *
+ * function MyApp() {
+ *   const { app, isConnected } = useMCPApp();
+ *
+ *   const handleClick = async () => {
+ *     if (app) {
+ *       const result = await app.callServerTool({
+ *         name: 'update_data',
+ *         arguments: { key: 'value' },
+ *       });
+ *       console.log('Server tool result:', result);
+ *     }
+ *   };
+ *
+ *   return <button onClick={handleClick}>Update</button>;
+ * }
+ * ```
+ */
+export function useMCPApp() {
+  const { app, isConnected, error } = useMCPAppContext();
+  return { app, isConnected, error };
+}
+
+/**
+ * Get current MCP App props synchronously.
+ *
+ * @deprecated Use `useMCPAppProps` hook instead. This function is maintained
+ * for backward compatibility but does not work with the ext-apps protocol.
+ *
+ * @template T - The type of props expected
+ * @returns null (ext-apps protocol is async-only)
+ */
+export function getMCPAppProps<T>(): T | null {
+  return null;
+}
+
+/**
+ * Subscribe to MCP App props changes.
+ *
+ * @deprecated Use `useMCPAppProps` hook instead. This function is maintained
+ * for backward compatibility but does not work with the ext-apps protocol.
+ *
+ * @template T - The type of props expected
+ * @param _listener - Function called when props are received or updated
+ * @returns No-op unsubscribe function
+ */
+export function subscribeMCPAppProps<T>(
+  _listener: (props: T) => void
+): () => void {
+  return () => {};
+}

package/src/vite-plugin.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from 'bun:test';
+import { defineMCPAppsConfig } from '../src/vite-plugin';
+import type { UserConfig } from 'vite';
+
+describe('defineMCPAppsConfig', () => {
+  test('returns a Vite config object', () => {
+    const config = defineMCPAppsConfig() as UserConfig;
+
+    expect(config).toBeDefined();
+    expect(config.base).toBe('./');
+    expect(config.build).toBeDefined();
+  });
+
+  test('sets critical build options for single-file output', () => {
+    const config = defineMCPAppsConfig() as UserConfig;
+
+    expect(config.build?.assetsInlineLimit).toBe(Number.MAX_SAFE_INTEGER);
+    expect(config.build?.cssCodeSplit).toBe(false);
+    expect(config.build?.emptyOutDir).toBe(true);
+  });
+
+  test('includes viteSingleFile and mcpAppPlugin plugins', () => {
+    const config = defineMCPAppsConfig() as UserConfig;
+
+    expect(config.plugins).toBeDefined();
+    expect(Array.isArray(config.plugins)).toBe(true);
+
+    const pluginNames = (config.plugins as Array<{ name?: string }>)
+      .filter((p) => p && typeof p === 'object' && 'name' in p)
+      .map((p) => p.name);
+
+    expect(pluginNames).toContain('vite:singlefile');
+    expect(pluginNames).toContain('mcp-web-app');
+  });
+
+  test('merges user plugins with internal plugins', () => {
+    const userPlugin = { name: 'user-plugin' };
+    const config = defineMCPAppsConfig({
+      plugins: [userPlugin],
+    }) as UserConfig;
+
+    const pluginNames = (config.plugins as Array<{ name?: string }>)
+      .filter((p) => p && typeof p === 'object' && 'name' in p)
+      .map((p) => p.name);
+
+    expect(pluginNames).toContain('user-plugin');
+    expect(pluginNames).toContain('vite:singlefile');
+    expect(pluginNames).toContain('mcp-web-app');
+  });
+
+  test('user plugins come before internal plugins', () => {
+    const userPlugin = { name: 'user-plugin' };
+    const config = defineMCPAppsConfig({
+      plugins: [userPlugin],
+    }) as UserConfig;
+
+    const pluginNames = (config.plugins as Array<{ name?: string }>)
+      .filter((p) => p && typeof p === 'object' && 'name' in p)
+      .map((p) => p.name);
+
+    const userIndex = pluginNames.indexOf('user-plugin');
+    const singleFileIndex = pluginNames.indexOf('vite:singlefile');
+
+    expect(userIndex).toBeLessThan(singleFileIndex);
+  });
+
+  test('accepts custom appsConfig and outDir', () => {
+    const config = defineMCPAppsConfig(
+      {},
+      {
+        appsConfig: 'custom/apps.ts',
+        outDir: 'custom/output',
+      }
+    ) as UserConfig;
+
+    expect(config).toBeDefined();
+    expect(config.build?.outDir).toContain('custom/output');
+  });
+
+  test('preserves user build options that are not critical', () => {
+    const config = defineMCPAppsConfig({
+      build: {
+        sourcemap: true,
+        minify: 'terser',
+      },
+    }) as UserConfig;
+
+    expect(config.build?.sourcemap).toBe(true);
+    expect(config.build?.minify).toBe('terser');
+  });
+
+  test('overrides critical settings even if user provides them', () => {
+    const config = defineMCPAppsConfig({
+      build: {
+        assetsInlineLimit: 100,
+        cssCodeSplit: true,
+      },
+    }) as UserConfig;
+
+    // Critical settings should be overridden
+    expect(config.build?.assetsInlineLimit).toBe(Number.MAX_SAFE_INTEGER);
+    expect(config.build?.cssCodeSplit).toBe(false);
+  });
+
+  test('default export is same as named export', async () => {
+    const { default: defaultExport, defineMCPAppsConfig: namedExport } =
+      await import('../src/vite-plugin');
+    expect(defaultExport).toBe(namedExport);
+  });
+});