@mcp-web/app 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,159 @@
+# MCP Web App
+
+Tooling for simplify creating MCP Apps from UI components. The packages bundles components into single HTML files that AI agents can render inline in chat interfaces like Claude Desktop.
+
+> [!IMPORTANT]
+> We currently only support React. Support for more frameworks will be added in the future.
+
+## Overview
+
+MCP Apps combine a tool (that AI can call) with a visual React component. When the AI calls the tool, the handler returns props which are passed to your component via the [ext-apps protocol](https://github.com/anthropics/anthropic-cookbook/tree/main/misc/model_context_protocol/ext-apps). A Vite plugin handles bundling each app into a self-contained HTML file.
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install @mcp-web/app
+```
+
+### 1. Define an App
+
+Create a file that exports your apps (e.g. `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,
+  }),
+});
+```
+
+### 2. Add the Vite Build Config
+
+Create a separate Vite config for building apps (e.g. `vite.apps.config.ts`):
+
+```typescript
+import react from '@vitejs/plugin-react';
+import { defineMCPAppsConfig } from '@mcp-web/app/vite';
+
+export default defineMCPAppsConfig({
+  plugins: [react()],
+});
+```
+
+Build with:
+
+```bash
+vite build --config vite.apps.config.ts
+```
+
+This auto-discovers apps in `src/mcp-apps.ts` and outputs bundled HTML files to `public/mcp-web-apps/`.
+
+### 3. Register with MCPWeb
+
+In your web app, register the app so the AI agent can call it:
+
+```typescript
+import { statsApp } from './mcp-apps';
+
+mcp.addApp(statsApp);
+```
+
+## Input Schemas
+
+Apps can accept input from the AI agent using Zod schemas:
+
+```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(),
+  }),
+});
+```
+
+## Host Theming
+
+MCP Apps automatically inherit the host's theme. Use these hooks to access it:
+
+```tsx
+import { useMCPHostTheme, useMCPHostContext } from '@mcp-web/app';
+
+function MyApp(props: MyProps) {
+  const theme = useMCPHostTheme(); // "light" or "dark"
+  const hostContext = useMCPHostContext(); // full context (theme, locale, display mode, etc.)
+
+  return <div className={theme === 'dark' ? 'dark' : ''}>{/* ... */}</div>;
+}
+```
+
+## Receiving Props
+
+Use the `useMCPAppProps` hook to receive props from the tool handler:
+
+```tsx
+import { useMCPAppProps } from '@mcp-web/app';
+
+function Statistics() {
+  const props = useMCPAppProps<{ completionRate: number; totalTasks: number }>();
+
+  if (!props) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <p>Completion: {Math.round(props.completionRate * 100)}%</p>
+      <p>Total tasks: {props.totalTasks}</p>
+    </div>
+  );
+}
+```
+
+## Vite Plugin Options
+
+```typescript
+defineMCPAppsConfig(
+  { plugins: [react()] },
+  {
+    appsConfig: 'src/mcp-apps.ts',       // Path to apps config (auto-detected by default)
+    outDir: 'public/mcp-web-apps',        // Output directory (default)
+    silenceOverrideWarnings: false,        // Suppress build setting override warnings
+  }
+);
+```
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `createApp` | Define an app with a handler and component |
+| `useMCPAppProps` | React hook to receive props from the tool handler |
+| `useMCPApp` | Access the ext-apps `App` instance |
+| `useMCPHostTheme` | Get the current host theme (`"light"` or `"dark"`) |
+| `useMCPHostContext` | Get the full host context |
+| `renderMCPApp` | Manually render a component (auto-generated by Vite plugin) |
+| `MCPAppProvider` | Context provider (set up automatically by `renderMCPApp`) |
+| `defineMCPAppsConfig` | Create a Vite config for building MCP Apps (via `@mcp-web/app/vite`) |
+
+## Learn More
+
+For full documentation, guides, and examples, visit [mcp-web.dev](https://mcp-web.dev).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-web/app",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Build tooling for MCP Apps - bundle React components into single HTML files for AI UI rendering",
   "type": "module",
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "@modelcontextprotocol/ext-apps": "^1.0.1",
     "vite-plugin-singlefile": "^2.3.0",
     "zod": "~4.1.12",
-    "@mcp-web/types": "0.1.0"
+    "@mcp-web/types": "0.1.2"
   },
   "devDependencies": {
     "@types/node": "^25.0.9",
@@ -45,6 +45,11 @@
       "optional": true
     }
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flekschas/mcp-web",
+    "directory": "packages/app"
+  },
   "scripts": {
     "build": "tsc",
     "clean": "rm -rf dist",