create-mcp-use-app 0.3.5 → 0.4.0

package/dist/templates/apps_sdk/README.md

@@ -0,0 +1,398 @@
+# Pizzaz MCP Server - OpenAI Apps SDK Reference
+
+An MCP server demonstrating OpenAI Apps SDK integration using `mcp-use`. This implementation showcases the **pizzaz reference widgets** that demonstrate Apps SDK best practices.
+
+## 🌟 Features
+
+- **🍕 Pizzaz Widgets**: 5 reference widgets from OpenAI's Apps SDK examples
+- **🚀 Apps SDK Integration**: Full OpenAI Apps SDK metadata support
+- **📦 Automatic Registration**: Tools and resources created automatically
+- **🔒 Content Security Policy**: Proper CSP configuration for external resources
+- **⚡ Tool Invocation Status**: Real-time status messages during tool execution
+- **🎨 External Resources**: Load scripts and styles from OpenAI's CDN
+- **🛠️ TypeScript Support**: Complete type safety and IntelliSense
+
+## 📋 What's Included
+
+### Pizzaz Widgets
+
+This server includes all 5 pizzaz reference widgets:
+
+1. **pizza-map** - Interactive map widget
+2. **pizza-carousel** - Carousel browsing widget
+3. **pizza-albums** - Album gallery widget
+4. **pizza-list** - List view widget
+5. **pizza-video** - Video player widget
+
+Each widget demonstrates:
+
+- External resource loading from OpenAI CDN
+- Apps SDK metadata configuration
+- Structured content injection
+- Tool invocation status messages
+
+## 🚀 Getting Started
+
+### Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start development server with hot reloading
+npm run dev
+```
+
+This will start:
+
+- MCP server on port 8000
+- Inspector UI at `/inspector`
+- SSE endpoint at `/mcp`
+
+### Production
+
+```bash
+# Build the server
+npm run build
+
+# Run the built server
+npm start
+```
+
+## 📖 Usage
+
+### Via MCP Client
+
+```typescript
+import { createMCPClient } from 'mcp-use/client'
+
+const client = createMCPClient({
+  serverUrl: 'http://localhost:8000/mcp',
+})
+
+// Call a pizzaz widget tool
+const result = await client.callTool('ui_pizza-map', {
+  pizzaTopping: 'pepperoni',
+})
+
+// Access widget template as resource
+const resource = await client.readResource('ui://widget/pizza-map.html')
+
+// List all available widgets
+const widgetList = await client.callTool('list-widgets', {})
+
+// Get info about a specific widget
+const widgetInfo = await client.callTool('get-widget-info', {
+  widgetId: 'pizza-carousel',
+})
+```
+
+### Via Inspector UI
+
+1. Start the server: `npm run dev`
+2. Open: `http://localhost:8000/inspector`
+3. Test tools and resources interactively
+
+### Direct HTTP Access
+
+```bash
+# SSE connection
+curl -N http://localhost:8000/mcp
+
+# Post message (requires sessionId)
+curl -X POST http://localhost:8000/mcp/messages?sessionId=<session-id> \
+  -H "Content-Type: application/json" \
+  -d '{"method": "tools/list"}'
+```
+
+## 🎯 How It Works
+
+### Apps SDK Integration
+
+The server uses `mcp-use`'s `AppsSdkUIResource` type to create Apps SDK compatible widgets:
+
+```typescript
+import type { AppsSdkUIResource } from 'mcp-use/server'
+
+const widget: AppsSdkUIResource = {
+  type: 'appsSdk',
+  name: 'pizza-map',
+  title: 'Show Pizza Map',
+  description: 'Interactive map widget',
+  htmlTemplate: `
+    <div id="pizzaz-root"></div>
+    <link rel="stylesheet" href="https://persistent.oaistatic.com/...">
+    <script type="module" src="https://persistent.oaistatic.com/..."></script>
+  `,
+  props: {
+    pizzaTopping: {
+      type: 'string',
+      description: 'Topping to mention',
+      required: true,
+    },
+  },
+  appsSdkMetadata: {
+    'openai/widgetDescription': 'Interactive map widget',
+    'openai/toolInvocation/invoking': 'Hand-tossing a map',
+    'openai/toolInvocation/invoked': 'Served a fresh map',
+    'openai/widgetAccessible': true,
+    'openai/widgetCSP': {
+      connect_domains: [],
+      resource_domains: ['https://persistent.oaistatic.com'],
+    },
+  },
+}
+
+server.uiResource(widget)
+```
+
+This automatically:
+
+1. Creates a tool (`ui_pizza-map`)
+2. Creates a resource (`ui://widget/pizza-map.html`)
+3. Sets MIME type to `text/html+skybridge`
+4. Injects Apps SDK metadata
+5. Handles structured content injection
+
+### Widget Registration
+
+Widgets are defined in `src/widgets.ts` and registered in `src/server.ts`:
+
+```typescript
+import { getPizzazUIResources } from './widgets.js'
+
+const pizzazWidgets = getPizzazUIResources()
+
+pizzazWidgets.forEach((widget) => {
+  server.uiResource(widget)
+})
+```
+
+### Structured Content
+
+When a tool is called, the `structuredContent` is automatically injected as `window.openai.toolOutput`:
+
+```typescript
+// In your tool handler
+return {
+  content: [
+    {
+      type: 'text',
+      text: 'Rendered a pizza map!',
+    },
+  ],
+  structuredContent: {
+    pizzaTopping: params.pizzaTopping,
+  },
+}
+
+// Widget can access it via:
+// window.openai.toolOutput.pizzaTopping
+```
+
+## 📚 Apps SDK Metadata
+
+Each widget includes rich Apps SDK metadata:
+
+### Widget Description
+
+```typescript
+'openai/widgetDescription': 'Interactive map widget for displaying pizza locations'
+```
+
+### Tool Invocation Status
+
+```typescript
+'openai/toolInvocation/invoking': 'Hand-tossing a map'
+'openai/toolInvocation/invoked': 'Served a fresh map'
+```
+
+### Content Security Policy
+
+```typescript
+'openai/widgetCSP': {
+  connect_domains: [],  // Domains widget can connect to
+  resource_domains: ['https://persistent.oaistatic.com']  // CDN domains
+}
+```
+
+### Accessibility
+
+```typescript
+'openai/widgetAccessible': true
+```
+
+### Output Template
+
+```typescript
+'openai/outputTemplate': 'ui://widget/pizza-map.html'
+```
+
+## 🔧 Configuration
+
+### Port Configuration
+
+Set the port via environment variable:
+
+```bash
+PORT=3000 npm start
+```
+
+Default port is `8000`.
+
+### Widget Customization
+
+To add or modify widgets, edit `src/widgets.ts`:
+
+```typescript
+export const pizzazWidgets: PizzazWidgetDefinition[] = [
+  {
+    id: 'my-widget',
+    title: 'My Custom Widget',
+    description: 'A custom widget',
+    templateUri: 'ui://widget/my-widget.html',
+    invoking: 'Loading widget...',
+    invoked: 'Widget ready!',
+    html: `
+      <div id="widget-root"></div>
+      <script>
+        // Your widget code
+      </script>
+    `,
+    responseText: 'Widget rendered!',
+  },
+  // ... other widgets
+]
+```
+
+## 🎨 Widget Structure
+
+Each pizzaz widget follows this structure:
+
+```html
+<!-- Container div with specific ID -->
+<div id="pizzaz-root"></div>
+
+<!-- External stylesheet -->
+<link rel="stylesheet" href="https://persistent.oaistatic.com/..." />
+
+<!-- External script (type="module") -->
+<script type="module" src="https://persistent.oaistatic.com/..."></script>
+```
+
+The external scripts:
+
+- Render interactive components into the container
+- Access structured content via `window.openai.toolOutput`
+- Handle user interactions
+- Communicate with parent via postMessage
+
+## 🛠️ Available Tools
+
+### Widget Tools
+
+Each pizzaz widget creates a tool:
+
+- `ui_pizza-map` - Display interactive map
+- `ui_pizza-carousel` - Browse in carousel format
+- `ui_pizza-albums` - Show album gallery
+- `ui_pizza-list` - Display list view
+- `ui_pizza-video` - Play video content
+
+All accept a `pizzaTopping` parameter:
+
+```typescript
+await client.callTool('ui_pizza-map', {
+  pizzaTopping: 'pepperoni',
+})
+```
+
+### Helper Tools
+
+- `list-widgets` - Get list of all available widgets
+- `get-widget-info` - Get detailed info about a specific widget
+
+## 📦 Available Resources
+
+Each widget template is available as a resource:
+
+- `ui://widget/pizza-map.html`
+- `ui://widget/pizza-carousel.html`
+- `ui://widget/pizza-albums.html`
+- `ui://widget/pizza-list.html`
+- `ui://widget/pizza-video.html`
+
+Plus:
+
+- `config://server` - Server configuration (JSON)
+
+## 🔍 Testing
+
+### Test with Inspector
+
+1. Start server: `npm run dev`
+2. Open inspector: `http://localhost:8000/inspector`
+3. Click on any widget tool
+4. Enter a pizza topping
+5. Execute and view the result
+
+### Test with MCP Client
+
+```typescript
+import { createMCPClient } from 'mcp-use/client'
+
+const client = createMCPClient({
+  serverUrl: 'http://localhost:8000/mcp',
+})
+
+// Test listing tools
+const tools = await client.listTools()
+console.log('Available tools:', tools)
+
+// Test calling a widget
+const result = await client.callTool('ui_pizza-map', {
+  pizzaTopping: 'mushroom',
+})
+console.log('Result:', result)
+
+// Test reading resource
+const resource = await client.readResource('ui://widget/pizza-map.html')
+console.log('Resource:', resource)
+```
+
+## 📂 Project Structure
+
+```
+apps_sdk/
+├── index.ts                # Entry point
+├── package.json            # Dependencies
+├── tsconfig.json          # TypeScript config
+├── README.md              # This file
+└── src/
+    ├── server.ts          # Main server implementation
+    └── widgets.ts         # Pizzaz widget definitions
+```
+
+## 🔗 Related Documentation
+
+- [MCP Documentation](https://modelcontextprotocol.io)
+- [MCP-UI Apps SDK Guide](https://mcpui.dev/guide/apps-sdk)
+- [mcp-use Documentation](https://github.com/pyroprompt/mcp-use)
+- [OpenAI Apps SDK](https://platform.openai.com/docs/guides/apps)
+
+## 🤝 Contributing
+
+This is a reference implementation demonstrating Apps SDK integration patterns. Feel free to:
+
+- Add new widget types
+- Customize existing widgets
+- Extend Apps SDK metadata
+- Add additional tools and resources
+
+## 📝 License
+
+MIT
+
+---
+
+Built with ❤️ using [mcp-use](https://github.com/pyroprompt/mcp-use) and [OpenAI Apps SDK](https://platform.openai.com/docs/guides/apps)

package/dist/templates/apps_sdk/index.ts

@@ -0,0 +1,11 @@
+/**
+ * MCP Apps SDK Server Entry Point
+ * 
+ * This file serves as the main entry point for the MCP server with Apps SDK support.
+ * It re-exports all functionality from the server implementation, allowing
+ * the CLI and other tools to locate and start the server.
+ * 
+ * The server demonstrates OpenAI Apps SDK integration using mcp-use's uiResource method.
+ */
+export * from './src/server.js'
+

package/dist/templates/apps_sdk/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "mcp-apps-sdk-server",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "MCP server with OpenAI Apps SDK integration using mcp-use",
+  "author": "",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "server",
+    "apps-sdk",
+    "openai",
+    "chatgpt",
+    "widgets",
+    "pizzaz",
+    "ai",
+    "tools"
+  ],
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "mcp-use build",
+    "dev": "mcp-use dev",
+    "start": "mcp-use start"
+  },
+  "dependencies": {
+    "@mcp-ui/server": "^5.11.0",
+    "cors": "^2.8.5",
+    "express": "^4.18.0",
+    "mcp-use": "workspace:*",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mcp-use/cli": "workspace:*",
+    "@mcp-use/inspector": "workspace:*",
+    "@types/cors": "^2.8.0",
+    "@types/express": "^4.17.0",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}
+

package/dist/templates/apps_sdk/src/server.ts

@@ -0,0 +1,239 @@
+import { createMCPServer } from 'mcp-use/server'
+import { getPizzazUIResources, getPizzazWidgetsSummary } from './widgets.js'
+
+/**
+ * ════════════════════════════════════════════════════════════════════
+ * Pizzaz MCP Server - OpenAI Apps SDK Reference Implementation
+ * ════════════════════════════════════════════════════════════════════
+ * 
+ * This server demonstrates OpenAI Apps SDK integration using mcp-use's
+ * uiResource method. It implements the pizzaz reference widgets that
+ * showcase best practices for Apps SDK widgets.
+ * 
+ * Key Features:
+ * - Apps SDK metadata (CSP, tool invocation status, widget description)
+ * - External resource loading (OpenAI CDN assets)
+ * - Structured content injection via window.openai.toolOutput
+ * - text/html+skybridge MIME type for Apps SDK compatibility
+ * - Automatic tool and resource registration
+ */
+
+// Create the MCP server
+const server = createMCPServer('pizzaz-node', {
+  version: '0.1.0',
+  description: 'OpenAI Apps SDK reference implementation with pizzaz widgets',
+})
+
+const PORT = process.env.PORT || 8000
+
+/**
+ * ════════════════════════════════════════════════════════════════════
+ * Register Pizzaz Widgets
+ * ════════════════════════════════════════════════════════════════════
+ * 
+ * Using mcp-use's uiResource method with AppsSdkUIResource type:
+ * 
+ * This automatically:
+ * 1. Creates tools (ui_pizza-map, ui_pizza-carousel, etc.)
+ * 2. Creates resources (ui://widget/pizza-map.html, etc.)
+ * 3. Sets MIME type to text/html+skybridge
+ * 4. Injects Apps SDK metadata
+ * 5. Handles structuredContent injection
+ */
+
+const pizzazWidgets = getPizzazUIResources()
+
+pizzazWidgets.forEach(widget => {
+  server.uiResource(widget)
+})
+
+/**
+ * ════════════════════════════════════════════════════════════════════
+ * Helper Tools
+ * ════════════════════════════════════════════════════════════════════
+ * 
+ * Additional tools for discovering and testing widgets
+ */
+
+server.tool({
+  name: 'list-widgets',
+  title: 'List Available Widgets',
+  description: 'Get a list of all available pizzaz widgets',
+  cb: async () => {
+    const widgets = getPizzazWidgetsSummary()
+
+    return {
+      content: [{
+        type: 'text',
+        text: `Available Pizzaz Widgets (${widgets.length} total):\n\n${widgets.map(w =>
+          `🍕 ${w.title}\n` +
+          `   ID: ${w.id}\n` +
+          `   Tool: ${w.tool}\n` +
+          `   Resource: ${w.resource}\n` +
+          `   Description: ${w.description}\n`
+        ).join('\n')}\n` +
+          `\nUsage:\n` +
+          `await client.callTool('ui_${widgets[0].id}', { pizzaTopping: 'pepperoni' })\n` +
+          `await client.readResource('${widgets[0].resource}')`
+      }]
+    }
+  }
+})
+
+server.tool({
+  name: 'get-widget-info',
+  title: 'Get Widget Information',
+  description: 'Get detailed information about a specific widget',
+  inputs: [{
+    name: 'widgetId',
+    type: 'string',
+    description: 'Widget ID (e.g., pizza-map, pizza-carousel)',
+    required: true
+  }],
+  cb: async (params) => {
+    const widgets = getPizzazWidgetsSummary()
+    const widget = widgets.find(w => w.id === params.widgetId)
+
+    if (!widget) {
+      return {
+        content: [{
+          type: 'text',
+          text: `Widget '${params.widgetId}' not found. Available widgets: ${widgets.map(w => w.id).join(', ')}`
+        }]
+      }
+    }
+
+    return {
+      content: [{
+        type: 'text',
+        text: `Widget Information:\n\n` +
+          `ID: ${widget.id}\n` +
+          `Title: ${widget.title}\n` +
+          `Description: ${widget.description}\n` +
+          `Tool Name: ${widget.tool}\n` +
+          `Resource URI: ${widget.resource}\n` +
+          `Response Text: ${widget.responseText}\n\n` +
+          `Usage:\n` +
+          `await client.callTool('${widget.tool}', { pizzaTopping: 'mushroom' })\n` +
+          `await client.readResource('${widget.resource}')`
+      }]
+    }
+  }
+})
+
+/**
+ * ════════════════════════════════════════════════════════════════════
+ * Server Configuration Resource
+ * ════════════════════════════════════════════════════════════════════
+ */
+
+server.resource({
+  name: 'server-config',
+  uri: 'config://server',
+  title: 'Server Configuration',
+  description: 'Current server configuration and capabilities',
+  mimeType: 'application/json',
+  readCallback: async () => ({
+    contents: [{
+      uri: 'config://server',
+      mimeType: 'application/json',
+      text: JSON.stringify({
+        name: 'pizzaz-node',
+        version: '0.1.0',
+        port: PORT,
+        widgets: {
+          total: pizzazWidgets.length,
+          ids: pizzazWidgets.map(w => w.name)
+        },
+        endpoints: {
+          mcp: `http://localhost:${PORT}/mcp`,
+          inspector: `http://localhost:${PORT}/inspector`,
+        },
+        features: {
+          appsSdk: true,
+          externalResources: true,
+          structuredContent: true,
+          pizzazWidgets: true
+        },
+        appsSdk: {
+          mimeType: 'text/html+skybridge',
+          metadata: [
+            'openai/widgetDescription',
+            'openai/widgetCSP',
+            'openai/widgetAccessible',
+            'openai/outputTemplate',
+            'openai/toolInvocation/invoking',
+            'openai/toolInvocation/invoked',
+            'openai/resultCanProduceWidget'
+          ]
+        }
+      }, null, 2)
+    }]
+  })
+})
+
+/**
+ * ════════════════════════════════════════════════════════════════════
+ * Start the Server
+ * ════════════════════════════════════════════════════════════════════
+ */
+
+server.listen(PORT)
+
+// Display helpful startup message
+console.log(`
+╔═══════════════════════════════════════════════════════════════╗
+║           🍕 Pizzaz MCP Server - Apps SDK Reference           ║
+╚═══════════════════════════════════════════════════════════════╝
+
+Server is running on port ${PORT}
+
+📍 Endpoints:
+   MCP Protocol:  http://localhost:${PORT}/mcp
+   Inspector UI:  http://localhost:${PORT}/inspector
+
+🍕 Available Pizzaz Widgets (${pizzazWidgets.length} total):
+
+${pizzazWidgets.map((w, i) => `   ${i + 1}. ${w.name}
+      Tool:      ui_${w.name}
+      Resource:  ${w.appsSdkMetadata?.['openai/outputTemplate'] || 'N/A'}
+`).join('\n')}
+
+📝 Usage Examples:
+
+   // Call a widget tool with parameters
+   await client.callTool('ui_pizza-map', {
+     pizzaTopping: 'pepperoni'
+   })
+
+   // Access widget template as resource
+   await client.readResource('ui://widget/pizza-map.html')
+
+   // List all widgets
+   await client.callTool('list-widgets', {})
+
+   // Get widget info
+   await client.callTool('get-widget-info', {
+     widgetId: 'pizza-map'
+   })
+
+🔧 Apps SDK Features:
+   ✓ text/html+skybridge MIME type
+   ✓ External resource loading (OpenAI CDN)
+   ✓ Structured content injection
+   ✓ Tool invocation status messages
+   ✓ Content Security Policy (CSP)
+   ✓ Widget accessibility metadata
+
+💡 Tip: Open the Inspector UI to test all widgets interactively!
+🎨 These widgets demonstrate OpenAI's Apps SDK best practices.
+`)
+
+// Handle graceful shutdown
+process.on('SIGINT', () => {
+  console.log('\n\n👋 Shutting down pizzaz server...')
+  process.exit(0)
+})
+
+export default server
+