@mcp-web/app 0.1.0

package/src/create-app.ts

@@ -0,0 +1,213 @@
+import { AppDefinitionSchema } from '@mcp-web/types';
+import type { ComponentType } from 'react';
+import type { z } from 'zod';
+
+/**
+ * Extract props type from a React component.
+ */
+// biome-ignore lint/suspicious/noExplicitAny: Need any for component props extraction
+type ComponentProps<T> = T extends ComponentType<infer P> ? P : any;
+
+/**
+ * Configuration for creating an MCP App.
+ *
+ * An MCP App combines a tool (that AI can call) with a visual component
+ * (rendered in an iframe). The handler returns props that are passed to
+ * your React component via postMessage.
+ *
+ * The component's props type is used to ensure type safety - the handler
+ * must return props that match what the component expects.
+ *
+ * @template TComponent - React component type
+ * @template TInput - Zod schema type for tool input parameters
+ *
+ * @example
+ * ```typescript
+ * import { Statistics } from './components/Statistics';
+ *
+ * const statsApp = createApp({
+ *   name: 'show_stats',
+ *   description: 'Display statistics visualization',
+ *   component: Statistics,
+ *   handler: () => ({
+ *     completionRate: 0.75,
+ *     totalTasks: 100,
+ *   }),
+ * });
+ * ```
+ */
+export interface CreateAppConfig<
+  // biome-ignore lint/suspicious/noExplicitAny: Component can have any props
+  TComponent extends ComponentType<any> = ComponentType<any>,
+  TInput extends z.ZodObject | undefined = undefined,
+> {
+  /** Unique name for the app (also used as tool name) */
+  name: string;
+  /** Description of what the app does (shown to AI) */
+  description: string;
+  /** React component to render - handler must return props matching this component */
+  component: TComponent;
+  /** Optional Zod schema for validating tool input */
+  inputSchema?: TInput;
+  /** Optional Zod schema for validating props output */
+  propsSchema?: z.ZodType<ComponentProps<TComponent>>;
+  /** Handler function that returns props for the component */
+  handler: TInput extends z.ZodObject
+    ? (
+        input: z.infer<TInput>
+      ) => ComponentProps<TComponent> | Promise<ComponentProps<TComponent>>
+    : () => ComponentProps<TComponent> | Promise<ComponentProps<TComponent>>;
+  /** URL to fetch the app HTML from (defaults to /mcp-web-apps/{kebab-case-name}.html) */
+  url?: string;
+  /** Resource URI for the app (defaults to ui://{name}/app.html) */
+  resourceUri?: string;
+}
+
+/**
+ * A created app ready for registration with MCPWeb.
+ *
+ * Created apps are validated at creation time but not yet active.
+ * Register with `mcp.addApp(app)` or the `useMCPApps()` hook to make
+ * the tool available to AI.
+ *
+ * @template TComponent - React component type
+ * @template TInput - Zod schema type for tool input parameters
+ *
+ * @example
+ * ```typescript
+ * const statsApp = createApp({ ... });
+ *
+ * // Register directly
+ * mcp.addApp(statsApp);
+ *
+ * // Or via React hook
+ * useMCPApps(statsApp);
+ * ```
+ */
+export interface CreatedApp<
+  // biome-ignore lint/suspicious/noExplicitAny: Component can have any props
+  TComponent extends ComponentType<any> = ComponentType<any>,
+  TInput extends z.ZodObject | undefined = undefined,
+> {
+  /** Marker to identify this as a created app */
+  readonly __brand: 'CreatedApp';
+  /** The app definition for registration */
+  readonly definition: {
+    name: string;
+    description: string;
+    component: TComponent;
+    inputSchema?: TInput;
+    propsSchema?: z.ZodType<ComponentProps<TComponent>>;
+    handler: CreateAppConfig<TComponent, TInput>['handler'];
+    url?: string;
+    resourceUri?: string;
+  };
+  /** The original config for type inference */
+  readonly config: CreateAppConfig<TComponent, TInput>;
+}
+
+/**
+ * Creates an MCP App definition without registering it.
+ *
+ * MCP Apps combine a tool (that AI can call to get props) with a visual
+ * React component. When AI calls the tool, the handler returns props which
+ * are passed to the component via postMessage.
+ *
+ * The Vite plugin automatically generates entry files for your apps, so you
+ * only need to define the app configuration:
+ *
+ * ```typescript
+ * // src/mcp-apps.ts
+ * 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,
+ *   }),
+ * });
+ * ```
+ *
+ * @example With Input Schema
+ * ```typescript
+ * import { createApp } from '@mcp-web/app';
+ * import { z } from 'zod';
+ * import { Chart } from './components/Chart';
+ *
+ * export const chartApp = createApp({
+ *   name: 'show_chart',
+ *   description: 'Display a chart with the given data',
+ *   component: Chart,
+ *   inputSchema: z.object({
+ *     chartType: z.enum(['bar', 'line', 'pie']).describe('Type of chart'),
+ *     title: z.string().describe('Chart title'),
+ *   }),
+ *   handler: ({ chartType, title }) => ({
+ *     chartType,
+ *     title,
+ *     data: getChartData(),
+ *   }),
+ * });
+ * ```
+ */
+export function createApp<
+  // biome-ignore lint/suspicious/noExplicitAny: Component can have any props
+  TComponent extends ComponentType<any>,
+  TInput extends z.ZodObject | undefined = undefined,
+>(
+  config: CreateAppConfig<TComponent, TInput>
+): CreatedApp<TComponent, TInput> {
+  // Validate at creation time
+  const validationResult = AppDefinitionSchema.safeParse(config);
+  if (!validationResult.success) {
+    throw new Error(
+      `Invalid app definition: ${validationResult.error.message}`
+    );
+  }
+
+  return {
+    __brand: 'CreatedApp' as const,
+    definition: {
+      name: config.name,
+      description: config.description,
+      component: config.component,
+      inputSchema: config.inputSchema,
+      propsSchema: config.propsSchema,
+      handler: config.handler,
+      url: config.url,
+      resourceUri: config.resourceUri,
+    },
+    config,
+  };
+}
+
+/**
+ * Type guard to check if a value is a CreatedApp.
+ *
+ * Useful for validating values passed to `addApp()` or for runtime checks.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a CreatedApp instance
+ *
+ * @example
+ * ```typescript
+ * import { createApp, isCreatedApp } from '@mcp-web/app';
+ *
+ * const maybeApp = getAppFromSomewhere();
+ * if (isCreatedApp(maybeApp)) {
+ *   mcp.addApp(maybeApp);
+ * }
+ * ```
+ */
+export function isCreatedApp(value: unknown): value is CreatedApp {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    '__brand' in value &&
+    (value as CreatedApp).__brand === 'CreatedApp'
+  );
+}

package/src/index.ts

@@ -0,0 +1,87 @@
+/**
+ * @mcp-web/app - Build tooling for MCP Apps
+ *
+ * This package provides tools for creating MCP Apps - visual UI components
+ * that AI agents can render inline in chat interfaces like Claude Desktop.
+ *
+ * ## Main Exports
+ *
+ * - `createApp` - Define an app with a handler and component
+ *
+ * ## Vite Plugin (via `@mcp-web/app/vite`)
+ *
+ * - `defineMCPAppsConfig` - Create a Vite config for building MCP Apps
+ *
+ * ## Host Theming
+ *
+ * MCP Apps automatically inherit the host's theme. Use these hooks to access
+ * the host's theme and context in your components:
+ *
+ * - `useMCPHostTheme` - Get the current host theme (`"light"` or `"dark"`)
+ * - `useMCPHostContext` - Get the full host context (theme, display mode, locale, etc.)
+ *
+ * ## Advanced Exports
+ *
+ * - `renderMCPApp` - Manually render a component (auto-generated by Vite plugin)
+ * - `useMCPAppProps` - React hook for custom prop handling
+ * - `useMCPApp` - Access the ext-apps `App` instance
+ * - `MCPAppProvider` - Context provider (set up automatically by renderMCPApp)
+ *
+ * @example Define an MCP App (src/mcp-apps.ts)
+ * ```typescript
+ * import { createApp } from '@mcp-web/app';
+ * import { Statistics } from './components/Statistics';
+ *
+ * export const statsApp = createApp({
+ *   name: 'show_stats',
+ *   description: 'Display statistics visualization',
+ *   component: Statistics,
+ *   handler: () => ({
+ *     completionRate: 0.75,
+ *     totalTasks: 100,
+ *   }),
+ * });
+ * ```
+ *
+ * @example Build Config (vite.apps.config.ts)
+ * ```typescript
+ * import react from '@vitejs/plugin-react';
+ * import { defineMCPAppsConfig } from '@mcp-web/app/vite';
+ *
+ * // Automatically discovers apps in src/mcp-apps.ts
+ * export default defineMCPAppsConfig({
+ *   plugins: [react()],
+ * });
+ * ```
+ *
+ * @example Register with MCPWeb (in your app)
+ * ```typescript
+ * import { statsApp } from './mcp-apps';
+ *
+ * mcp.addApp(statsApp);
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+export { createApp, isCreatedApp } from './create-app.js';
+export type { CreateAppConfig, CreatedApp } from './create-app.js';
+
+export {
+  useMCPAppProps,
+  useMCPApp,
+  getMCPAppProps,
+  subscribeMCPAppProps,
+} from './use-mcp-app-props.js';
+
+export {
+  MCPAppProvider,
+  useMCPHostContext,
+  useMCPHostTheme,
+} from './mcp-app-context.js';
+export type { MCPAppContextValue } from './mcp-app-context.js';
+
+export { renderMCPApp } from './render-mcp-app.js';
+export type { RenderMCPAppOptions } from './render-mcp-app.js';
+
+export { useDocumentTheme } from '@modelcontextprotocol/ext-apps/react';

package/src/internal.ts

@@ -0,0 +1,12 @@
+/**
+ * Internal exports for auto-generated MCP App entry files.
+ *
+ * This module is used by the Vite plugin to generate virtual modules
+ * that render MCP Apps. It should not be imported directly by users.
+ *
+ * @internal
+ * @packageDocumentation
+ */
+
+export { renderMCPApp } from './render-mcp-app.js';
+export type { RenderMCPAppOptions } from './render-mcp-app.js';

package/src/mcp-app-context.test.tsx

@@ -0,0 +1,323 @@
+import { describe, expect, mock, test, beforeEach } from 'bun:test';
+import { createElement, type ReactNode } from 'react';
+import { renderToString } from 'react-dom/server';
+
+// --- Mocks ---
+
+// Track calls to ext-apps hooks
+let mockUseAppReturn = {
+  app: null as unknown,
+  isConnected: false,
+  error: null as Error | null,
+};
+let mockUseAppOptions: unknown = null;
+let mockUseHostStylesCalls: unknown[][] = [];
+let mockUseDocumentThemeReturn: 'light' | 'dark' = 'light';
+
+// Mock `@modelcontextprotocol/ext-apps/react` before importing our module
+mock.module('@modelcontextprotocol/ext-apps/react', () => ({
+  useApp: (options: unknown) => {
+    mockUseAppOptions = options;
+    return mockUseAppReturn;
+  },
+  useHostStyles: (...args: unknown[]) => {
+    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: string): string {
+  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: ReactNode): string {
+  return renderToString(
+    createElement(MCPAppProvider, null, children)
+  );
+}
+
+/** Render with provider and extract the decoded text content. */
+function renderText(component: () => ReactNode): string {
+  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 as {
+      appInfo: { name: string; version: string };
+      capabilities: Record<string, unknown>;
+      onAppCreated: (app: unknown) => void;
+    };
+    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 as {
+      onAppCreated: (app: {
+        onhostcontextchanged?: (params: unknown) => void;
+      }) => void;
+    };
+
+    // Simulate what useApp does: call onAppCreated with an app instance
+    const fakeApp: { onhostcontextchanged?: (params: unknown) => void } = {};
+    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 as Error).message).toContain('renderMCPApp');
+      expect((error as 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');
+  });
+});