feat: support adapters

.github/workflows/ci.yml

@@ -23,9 +23,12 @@ jobs:
       example_files: ${{ steps.filter.outputs.example_files }}
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: dorny/paths-filter@v2
         id: filter
         with:
+          base: ${{ github.event_name == 'push' && github.event.before || github.base_ref }}
           filters: |
             ts_client_files:
               - 'sdks/typescript/client/**'
@@ -152,6 +155,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
         with: { fetch-depth: 0 }
+      - name: Fetch all tags
+        run: git fetch --tags --force
       - name: Setup pnpm
         uses: pnpm/action-setup@v2
         with: { version: 10 }
@@ -184,6 +189,8 @@ jobs:
         with: { fetch-depth: 0 }
       - name: Pull latest changes
         run: git pull --rebase origin ${{ github.ref_name }}
+      - name: Fetch all tags
+        run: git fetch --tags --force
       - name: Setup pnpm
         uses: pnpm/action-setup@v2
         with: { version: 10 }
@@ -201,7 +208,7 @@ jobs:
 
   release_ruby_sdk:
     name: Release Ruby SDK
-    needs: [ruby_sdk_test, release_ts_server, filter_changed_paths]
+    needs: [ruby_sdk_test, filter_changed_paths, release_ts_server]
     if: >
       always() &&
       (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/alpha') &&
@@ -244,7 +251,7 @@ jobs:
 
   release_python_sdk:
     name: Release Python SDK
-    needs: [python_sdk_test, release_ruby_sdk, filter_changed_paths]
+    needs: [python_sdk_test, filter_changed_paths, release_ruby_sdk]
     if: >
       always() &&
       (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/alpha') &&

.gitignore

@@ -193,4 +193,7 @@ __pycache__/
 
 # Husky
 .husky/_/
-.husky/.gitignore 
+.husky/.gitignore
+
+# Auto-generated files
+adapter-runtime.bundled.ts

README.md

@@ -39,7 +39,7 @@
 
 ## 💡 What's `mcp-ui`?
 
-`mcp-ui` is a collection of SDKs comprising:
+`mcp-ui` is a playground for the open spec of UI over MCP. It offers a collection of community SDKs comprising:
 
 * **`@mcp-ui/server` (TypeScript)**: Utilities to generate UI resources (`UIResource`) on your MCP server.
 * **`@mcp-ui/client` (TypeScript)**: UI components (e.g., `<UIResourceRenderer />`) to render the UI resources and handle their events.
@@ -143,6 +143,82 @@ Rendered using the internal `<RemoteDOMResourceRenderer />` component, which uti
 
 UI snippets must be able to interact with the agent. In `mcp-ui`, this is done by hooking into events sent from the UI snippet and reacting to them in the host (see `onUIAction` prop). For example, an HTML may trigger a tool call when a button is clicked by sending an event which will be caught handled by the client.
 
+
+### Platform Adapters
+
+MCP-UI SDKs includes adapter support for host-specific implementations, enabling your open MCP-UI widgets to work seamlessly regardless of host. Adapters automatically translate between MCP-UI's `postMessage` protocol and host-specific APIs. Over time, as hosts become compatible with the open spec, these adapters wouldn't be needed.
+
+#### Available Adapters
+
+##### Apps SDK Adapter
+
+For Apps SDK environments (e.g., ChatGPT), this adapter translates MCP-UI protocol to Apps SDK API calls (e.g., `window.openai`).
+
+**How it Works:**
+- Intercepts MCP-UI `postMessage` calls from your widgets
+- Translates them to appropriate Apps SDK API calls
+- Handles bidirectional communication (tools, prompts, state management)
+- Works transparently - your existing MCP-UI code continues to work without changes
+
+**Usage:**
+
+```ts
+import { createUIResource } from '@mcp-ui/server';
+
+const htmlResource = createUIResource({
+  uri: 'ui://greeting/1',
+  content: { 
+    type: 'rawHtml', 
+    htmlString: `
+      <button onclick="window.parent.postMessage({ type: 'tool', payload: { toolName: 'myTool', params: {} } }, '*')">
+        Call Tool
+      </button>
+    ` 
+  },
+  encoding: 'text',
+  // Enable adapters
+  adapters: {
+    appsSdk: {
+      enabled: true,
+      config: ...
+    }
+    // Future adapters can be enabled here
+  }
+});
+```
+
+The adapter scripts are automatically injected into your HTML content and handle all protocol translation.
+
+**Supported Actions:**
+- ✅ **Tool calls** - `{ type: 'tool', payload: { toolName, params } }`
+- ✅ **Prompts** - `{ type: 'prompt', payload: { prompt } }`
+- ✅ **Intents** - `{ type: 'intent', payload: { intent, params } }` (converted to prompts)
+- ✅ **Notifications** - `{ type: 'notify', payload: { message } }`
+- ✅ **Render data** - Access to `toolInput`, `toolOutput`, `widgetState`, `theme`, `locale`
+- ⚠️ **Links** - `{ type: 'link', payload: { url } }` (may not be supported, returns error in some environments)
+
+#### Advanced Usage
+
+You can manually wrap HTML with adapters or access adapter scripts directly:
+
+```ts
+import { wrapHtmlWithAdapters, getAppsSdkAdapterScript } from '@mcp-ui/server';
+
+// Manually wrap HTML with adapters
+const wrappedHtml = wrapHtmlWithAdapters(
+  '<button>Click me</button>',
+  {
+    appsSdk: {
+      enabled: true,
+      config: { intentHandling: 'ignore' }
+    }
+  }
+);
+
+// Get a specific adapter script
+const appsSdkScript = getAppsSdkAdapterScript({ timeout: 60000 });
+```
+
 ## 🏗️ Installation
 
 ### TypeScript

docs/src/guide/apps-sdk.md

@@ -0,0 +1,85 @@
+# OpenAI Apps SDK Integration
+
+The Apps SDK adapter in `@mcp-ui/server` ensures your MCP-UI HTML runs inside ChatGPT. However, for now, you still need to manually wire the resource according to the Apps SDK resource pattern. This guide walks through the manual flow the adapter expects today.
+
+## Why two resources?
+
+- **Static template for Apps SDK** – referenced from your tool descriptor via `_meta["openai/outputTemplate"]`. This version must enable the Apps SDK adapter so ChatGPT injects the bridge script and uses the `text/html+skybridge` MIME type.
+- **Embedded resource in tool results** – returned each time your tool runs. This version should *not* enable the adapter so MCP-native hosts continue to receive standard MCP-UI HTML.
+
+## Step-by-step workflow
+
+### 1. Register the Apps SDK template
+
+Use `createUIResource` with `adapters.appsSdk.enabled: true` and expose it through the MCP Resources API so both Apps SDK and traditional MCP hosts can fetch it.
+
+```ts
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { createUIResource } from '@mcp-ui/server';
+
+const server = new McpServer({ name: 'weather-bot', version: '1.0.0' });
+const TEMPLATE_URI = 'ui://widgets/weather';
+
+const appsSdkTemplate = createUIResource({
+  uri: TEMPLATE_URI,
+  encoding: 'text',
+  adapters: {
+    appsSdk: {
+      enabled: true,
+      config: { intentHandling: 'prompt' },
+    },
+  },
+  content: {
+    type: 'rawHtml',
+    htmlString: renderInitialShell(),
+  },
+});
+
+server.registerResource(TEMPLATE_URI, async () => appsSdkTemplate.resource);
+```
+
+> **Note:** The adapter switches the MIME type to `text/html+skybridge` and injects the Apps bridge script automatically. No extra HTML changes are required.
+
+### 2. Reference the template in your tool descriptor
+
+The Apps SDK looks for `_meta["openai/outputTemplate"]` to know which resource to render. Mirror the rest of the Apps-specific metadata you need (status text, accessibility hints, security schemes, etc.).
+
+```ts
+server.registerTool(
+  'forecast',
+  {
+    title: 'Get the forecast',
+    description: 'Returns a UI that displays the current weather.',
+    inputSchema: {
+      type: 'object',
+      properties: { city: { type: 'string' } },
+      required: ['city'],
+    },
+    _meta: {
+      'openai/outputTemplate': TEMPLATE_URI,
+      'openai/toolInvocation/invoking': 'Fetching forecast…',
+      'openai/toolInvocation/invoked': 'Forecast ready',
+      'openai/widgetAccessible': true,
+    },
+  },
+  async ({ city }) => {
+    const forecast = await fetchForecast(city);
+
+    // Step 3 happens inside the handler.
+    return {
+      content: [
+        {
+          type: 'text',
+          text: `Forecast prepared for ${city}.`,
+        },
+      ],
+      structuredContent: {
+        forecast,
+      },
+    };
+  },
+);
+```
+
+For the complete list of supported metadata fields, refer to the official documentation. [Apps SDK Reference](https://developers.openai.com/apps-sdk/reference)
+

docs/src/guide/introduction.md

@@ -156,4 +156,5 @@ This project is an experimental playground for MCP-UI ideas, that aims to test o
 - [Client SDK](./client/overview.md) - Learn to render UI resources
 - [Typescript Server SDK](./server/typescript/overview.md) - Learn to create UI resources in Typescript
 - [Ruby Server SDK](./server/ruby/overview.md) - Learn to create UI resources in Ruby
+- [Apps SDK Integration](./apps-sdk.md) - Wire the existing adapter into ChatGPT's Apps SDK
 - [Protocol Details](./protocol-details.md) - Understand the underlying protocol

docs/src/index.md

@@ -24,6 +24,8 @@ hero:
       link: /about
 
 features:
+  - title: 🌐 Open Protocol
+    details: MCP-UI is an open spec to standardize UI over MCP. Write once, run everywhere!
   - title: ⚛️ Client SDK
     details: Provides a React component and Web Component for easy frontend integration. Render interactive UI resources and handle UI actions effortlessly.
   - title: 🛠️ Server SDKs