@mcp-web/app 0.1.0

package/dist/mcp-app-context.d.ts

@@ -0,0 +1,122 @@
+import { type ReactNode } from '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;
+}
+/**
+ * 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 declare function MCPAppProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * 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 declare function useMCPAppContext(): MCPAppContextValue;
+/**
+ * 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 declare function useMCPHostContext(): McpUiHostContext | undefined;
+/**
+ * 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 declare function useMCPHostTheme(): import("@modelcontextprotocol/ext-apps").McpUiTheme;
+//# sourceMappingURL=mcp-app-context.d.ts.map

package/dist/mcp-app-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-app-context.d.ts","sourceRoot":"","sources":["../src/mcp-app-context.tsx"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAE5E;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC;IAChB,oDAAoD;IACpD,WAAW,EAAE,OAAO,CAAC;IACrB,gEAAgE;IAChE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,sDAAsD;IACtD,WAAW,EAAE,gBAAgB,GAAG,SAAS,CAAC;CAC3C;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,2CAoCnE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,IAAI,kBAAkB,CAUrD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,iBAAiB,IAAI,gBAAgB,GAAG,SAAS,CAEhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,eAAe,wDAE9B"}

package/dist/mcp-app-context.js

@@ -0,0 +1,140 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useState, } from 'react';
+import { useApp, useHostStyles, useDocumentTheme } from '@modelcontextprotocol/ext-apps/react';
+const MCPAppContext = createContext(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 }) {
+    const [hostContext, setHostContext] = useState(undefined);
+    const onAppCreated = useCallback((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 (_jsx(MCPAppContext.Provider, { value: { app, isConnected, error, hostContext }, children: children }));
+}
+/**
+ * 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() {
+    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() {
+    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/dist/mcp-app-context.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=mcp-app-context.test.d.ts.map

package/dist/mcp-app-context.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-app-context.test.d.ts","sourceRoot":"","sources":["../src/mcp-app-context.test.tsx"],"names":[],"mappings":""}

package/dist/mcp-app-context.test.js

@@ -0,0 +1,254 @@
+import { describe, expect, mock, test, beforeEach } from 'bun:test';
+import { createElement } from 'react';
+import { renderToString } from 'react-dom/server';
+// --- Mocks ---
+// Track calls to ext-apps hooks
+let mockUseAppReturn = {
+    app: null,
+    isConnected: false,
+    error: null,
+};
+let mockUseAppOptions = null;
+let mockUseHostStylesCalls = [];
+let mockUseDocumentThemeReturn = 'light';
+// Mock `@modelcontextprotocol/ext-apps/react` before importing our module
+mock.module('@modelcontextprotocol/ext-apps/react', () => ({
+    useApp: (options) => {
+        mockUseAppOptions = options;
+        return mockUseAppReturn;
+    },
+    useHostStyles: (...args) => {
+        mockUseHostStylesCalls.push(args);
+    },
+    useDocumentTheme: () => mockUseDocumentThemeReturn,
+}));
+// Import after mocking
+const { MCPAppProvider, useMCPAppContext, useMCPHostContext, useMCPHostTheme, } = await import('./mcp-app-context.js');
+// --- Helpers ---
+/** Decode HTML entities produced by renderToString. */
+function decodeHtml(html) {
+    return html
+        .replace(/<[^>]+>/g, '')
+        .replace(/&quot;/g, '"')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&#x27;/g, "'")
+        .replace(/&#39;/g, "'");
+}
+/** Render a component inside MCPAppProvider and return the HTML string. */
+function renderWithProvider(children) {
+    return renderToString(createElement(MCPAppProvider, null, children));
+}
+/** Render with provider and extract the decoded text content. */
+function renderText(component) {
+    const html = renderWithProvider(createElement(component));
+    return decodeHtml(html);
+}
+/** Component that reads context and renders its values for assertion. */
+function ContextReader() {
+    const ctx = useMCPAppContext();
+    return createElement('div', { 'data-testid': 'context' }, JSON.stringify({
+        hasApp: ctx.app !== null,
+        isConnected: ctx.isConnected,
+        hasError: ctx.error !== null,
+        hasHostContext: ctx.hostContext !== undefined,
+    }));
+}
+/** Component that reads host context and renders it. */
+function HostContextReader() {
+    const hostContext = useMCPHostContext();
+    return createElement('div', null, hostContext ? JSON.stringify(hostContext) : 'undefined');
+}
+/** Component that reads theme and renders it. */
+function ThemeReader() {
+    const theme = useMCPHostTheme();
+    return createElement('div', null, theme);
+}
+// --- Tests ---
+beforeEach(() => {
+    mockUseAppReturn = {
+        app: null,
+        isConnected: false,
+        error: null,
+    };
+    mockUseAppOptions = null;
+    mockUseHostStylesCalls = [];
+    mockUseDocumentThemeReturn = 'light';
+});
+describe('MCPAppProvider', () => {
+    test('renders children', () => {
+        const html = renderWithProvider(createElement('span', null, 'hello world'));
+        expect(html).toContain('hello world');
+    });
+    test('calls useApp with correct appInfo', () => {
+        renderWithProvider(createElement('div'));
+        expect(mockUseAppOptions).toBeDefined();
+        const options = mockUseAppOptions;
+        expect(options.appInfo).toEqual({
+            name: 'mcp-web-app',
+            version: '0.1.0',
+        });
+        expect(options.capabilities).toEqual({});
+        expect(typeof options.onAppCreated).toBe('function');
+    });
+    test('calls useHostStyles with app and initial context', () => {
+        mockUseAppReturn = {
+            app: { getHostContext: () => null },
+            isConnected: true,
+            error: null,
+        };
+        renderWithProvider(createElement('div'));
+        expect(mockUseHostStylesCalls.length).toBeGreaterThan(0);
+        const lastCall = mockUseHostStylesCalls[mockUseHostStylesCalls.length - 1];
+        // First arg is app, second is initial context
+        expect(lastCall[0]).toBe(mockUseAppReturn.app);
+    });
+    test('provides context with disconnected state initially', () => {
+        mockUseAppReturn = {
+            app: null,
+            isConnected: false,
+            error: null,
+        };
+        const text = renderText(ContextReader);
+        const parsed = JSON.parse(text);
+        expect(parsed).toEqual({
+            hasApp: false,
+            isConnected: false,
+            hasError: false,
+            hasHostContext: false,
+        });
+    });
+    test('provides context with connected state and app', () => {
+        const mockHostContext = { theme: 'dark', displayMode: 'inline' };
+        mockUseAppReturn = {
+            app: { getHostContext: () => mockHostContext },
+            isConnected: true,
+            error: null,
+        };
+        const text = renderText(ContextReader);
+        const parsed = JSON.parse(text);
+        expect(parsed).toEqual({
+            hasApp: true,
+            isConnected: true,
+            hasError: false,
+            hasHostContext: true,
+        });
+    });
+    test('provides context with error state', () => {
+        mockUseAppReturn = {
+            app: null,
+            isConnected: false,
+            error: new Error('Connection failed'),
+        };
+        const text = renderText(ContextReader);
+        const parsed = JSON.parse(text);
+        expect(parsed).toEqual({
+            hasApp: false,
+            isConnected: false,
+            hasError: true,
+            hasHostContext: false,
+        });
+    });
+    test('sets initial host context from app.getHostContext()', () => {
+        const mockHostContext = {
+            theme: 'dark',
+            displayMode: 'inline',
+            locale: 'en-US',
+        };
+        mockUseAppReturn = {
+            app: { getHostContext: () => mockHostContext },
+            isConnected: true,
+            error: null,
+        };
+        const text = renderText(HostContextReader);
+        const parsed = JSON.parse(text);
+        expect(parsed).toEqual(mockHostContext);
+    });
+    test('host context is undefined when app has no context', () => {
+        mockUseAppReturn = {
+            app: { getHostContext: () => null },
+            isConnected: true,
+            error: null,
+        };
+        const text = renderText(HostContextReader);
+        expect(text).toBe('undefined');
+    });
+    test('onAppCreated callback registers onhostcontextchanged handler', () => {
+        renderWithProvider(createElement('div'));
+        const options = mockUseAppOptions;
+        // Simulate what useApp does: call onAppCreated with an app instance
+        const fakeApp = {};
+        options.onAppCreated(fakeApp);
+        // The handler should be registered
+        expect(typeof fakeApp.onhostcontextchanged).toBe('function');
+    });
+});
+describe('useMCPAppContext', () => {
+    test('throws when used outside MCPAppProvider', () => {
+        expect(() => {
+            renderToString(createElement(ContextReader));
+        }).toThrow('useMCPAppContext must be used within an MCPAppProvider');
+    });
+    test('error message includes guidance about renderMCPApp', () => {
+        try {
+            renderToString(createElement(ContextReader));
+            // Should not reach here
+            expect(true).toBe(false);
+        }
+        catch (error) {
+            expect(error.message).toContain('renderMCPApp');
+            expect(error.message).toContain('MCPAppProvider');
+        }
+    });
+});
+describe('useMCPHostContext', () => {
+    test('throws when used outside MCPAppProvider', () => {
+        expect(() => {
+            renderToString(createElement(HostContextReader));
+        }).toThrow('useMCPAppContext must be used within an MCPAppProvider');
+    });
+    test('returns undefined when not connected', () => {
+        mockUseAppReturn = {
+            app: null,
+            isConnected: false,
+            error: null,
+        };
+        const text = renderText(HostContextReader);
+        expect(text).toBe('undefined');
+    });
+    test('returns host context when connected', () => {
+        const context = {
+            theme: 'light',
+            displayMode: 'full',
+            platform: 'darwin',
+        };
+        mockUseAppReturn = {
+            app: { getHostContext: () => context },
+            isConnected: true,
+            error: null,
+        };
+        const text = renderText(HostContextReader);
+        expect(JSON.parse(text)).toEqual(context);
+    });
+});
+describe('useMCPHostTheme', () => {
+    test('returns light theme by default', () => {
+        mockUseDocumentThemeReturn = 'light';
+        const text = renderText(ThemeReader);
+        expect(text).toBe('light');
+    });
+    test('returns dark theme when host is dark', () => {
+        mockUseDocumentThemeReturn = 'dark';
+        const text = renderText(ThemeReader);
+        expect(text).toBe('dark');
+    });
+    test('delegates to useDocumentTheme from ext-apps', () => {
+        // The mock already tracks that useDocumentTheme is called.
+        // If it weren't called, useMCPHostTheme would not return the mock value.
+        mockUseDocumentThemeReturn = 'dark';
+        const text = renderText(ThemeReader);
+        // This confirms useMCPHostTheme delegates to our mocked useDocumentTheme
+        expect(text).toBe('dark');
+    });
+});

package/dist/render-mcp-app.d.ts

@@ -0,0 +1,71 @@
+import type { ComponentType } from 'react';
+/**
+ * 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;
+}
+/**
+ * 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 declare function renderMCPApp<P extends Record<string, unknown>>(Component: ComponentType<P>, options?: RenderMCPAppOptions): void;
+//# sourceMappingURL=render-mcp-app.d.ts.map

package/dist/render-mcp-app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-mcp-app.d.ts","sourceRoot":"","sources":["../src/render-mcp-app.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAM3C;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AA0CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5D,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,mBAAwB,GAChC,IAAI,CAoBN"}

package/dist/render-mcp-app.js

@@ -0,0 +1,87 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+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';
+/**
+ * Default loading component shown while waiting for props.
+ * Uses host CSS variable with fallback for theme-aware loading text.
+ */
+function DefaultLoading() {
+    return (_jsx("div", { style: {
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            height: '100%',
+            fontFamily: 'var(--font-sans, system-ui, sans-serif)',
+            color: 'var(--color-text-secondary, #666)',
+        }, children: "Loading..." }));
+}
+/**
+ * Internal wrapper that handles props subscription.
+ */
+function MCPAppWrapper({ Component, Loading, }) {
+    const props = useMCPAppProps();
+    if (!props) {
+        return _jsx(Loading, {});
+    }
+    return _jsx(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(Component, options = {}) {
+    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 = (_jsx(Suspense, { fallback: _jsx(Loading, {}), children: _jsx(MCPAppProvider, { children: _jsx(MCPAppWrapper, { Component: Component, Loading: Loading }) }) }));
+    createRoot(rootElement).render(strictMode ? _jsx(StrictMode, { children: app }) : app);
+}