@mcp-web/app 0.1.0

package/dist/use-mcp-app-props.d.ts

@@ -0,0 +1,116 @@
+/**
+ * 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 declare function useMCPAppProps<T>(): T | null;
+/**
+ * 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 declare function useMCPApp(): {
+    app: import("@modelcontextprotocol/ext-apps").App | null;
+    isConnected: boolean;
+    error: Error | null;
+};
+/**
+ * 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 declare function getMCPAppProps<T>(): T | 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 declare function subscribeMCPAppProps<T>(_listener: (props: T) => void): () => void;
+//# sourceMappingURL=use-mcp-app-props.d.ts.map

package/dist/use-mcp-app-props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-mcp-app-props.d.ts","sourceRoot":"","sources":["../src/use-mcp-app-props.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,wBAAgB,cAAc,CAAC,CAAC,KAAK,CAAC,GAAG,IAAI,CAwC5C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,SAAS;;;;EAGxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,KAAK,CAAC,GAAG,IAAI,CAE5C;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAC5B,MAAM,IAAI,CAEZ"}

package/dist/use-mcp-app-props.js

@@ -0,0 +1,158 @@
+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() {
+    const [props, setProps] = useState(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);
+                        }
+                        catch {
+                            // If JSON parsing fails, treat the text as-is
+                            setProps(block.text);
+                        }
+                        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);
+            }
+        };
+    }, [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() {
+    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(_listener) {
+    return () => { };
+}

package/dist/vite-plugin.d.ts

@@ -0,0 +1,123 @@
+import type { UserConfig, UserConfigExport } from 'vite';
+/**
+ * MCP-specific options for building MCP Apps.
+ *
+ * These options control how app definitions are discovered and where
+ * the bundled HTML files are output.
+ *
+ * @example
+ * ```typescript
+ * defineMCPAppsConfig(
+ *   { plugins: [react()] },
+ *   {
+ *     appsConfig: 'src/mcp-apps.ts',
+ *     outDir: 'dist/apps',
+ *     silenceOverrideWarnings: true,
+ *   }
+ * );
+ * ```
+ */
+export interface MCPAppOptions {
+    /**
+     * Path to the apps configuration file (relative to project root).
+     * This file should export apps created with `createApp()`.
+     *
+     * If not specified, will search for:
+     * - `src/mcp-apps.ts`
+     * - `src/mcp-apps.tsx`
+     * - `src/mcp/apps.ts`
+     * - `src/mcp/apps.tsx`
+     *
+     * @default auto-detected
+     */
+    appsConfig?: string;
+    /**
+     * Output directory for bundled app HTML files (relative to project root).
+     * @default 'public/mcp-web-apps'
+     */
+    outDir?: string;
+    /**
+     * Silence warnings when MCP-required settings override user-provided values.
+     * @default false
+     */
+    silenceOverrideWarnings?: boolean;
+}
+/**
+ * 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 declare function defineMCPAppsConfig(viteConfig?: UserConfig, mcpOptions?: MCPAppOptions): UserConfigExport;
+export default defineMCPAppsConfig;
+//# sourceMappingURL=vite-plugin.d.ts.map

package/dist/vite-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-plugin.d.ts","sourceRoot":"","sources":["../src/vite-plugin.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAU,UAAU,EAAE,gBAAgB,EAAE,MAAM,MAAM,CAAC;AAGjE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;CACnC;AAiZD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2EG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,GAAE,UAAe,EAC3B,UAAU,GAAE,aAAkB,GAC7B,gBAAgB,CAwFlB;AAED,eAAe,mBAAmB,CAAC"}