mcp-app-studio 0.3.2

package/README.md

@@ -0,0 +1,152 @@
+# MCP App Studio
+
+**Build interactive apps for AI assistants (ChatGPT, Claude, MCP hosts).**
+
+Create widgets that work across multiple platforms with a single codebase. The SDK auto-detects whether you're running in ChatGPT, Claude Desktop, or another MCP-compatible host.
+
+## What You Get
+
+- **Local workbench** — Preview widgets without deploying
+- **Universal SDK** — Single API works on ChatGPT and MCP hosts
+- **Platform detection** — Auto-adapts to the host environment
+- **One-command export** — Generate production bundle + MCP server
+
+## Quick Start
+
+```bash
+npx mcp-app-studio my-app
+cd my-app
+npm install
+npm run dev
+```
+
+Open http://localhost:3000 — you're in the workbench.
+
+## Universal SDK
+
+The SDK provides React hooks that work identically across platforms:
+
+```tsx
+import {
+  UniversalProvider,
+  usePlatform,
+  useToolInput,
+  useCallTool,
+  useTheme,
+  useFeature
+} from "mcp-app-studio";
+
+function MyWidget() {
+  const platform = usePlatform(); // "chatgpt" | "mcp" | "unknown"
+  const input = useToolInput<{ query: string }>();
+  const callTool = useCallTool();
+  const theme = useTheme();
+
+  // Platform-specific features
+  const hasWidgetState = useFeature('widgetState'); // ChatGPT only
+  const hasModelContext = useFeature('modelContext'); // MCP only
+
+  return (
+    <div className={theme === 'dark' ? 'bg-gray-900' : 'bg-white'}>
+      {/* Your widget */}
+    </div>
+  );
+}
+
+// Wrap your app
+function App() {
+  return (
+    <UniversalProvider>
+      <MyWidget />
+    </UniversalProvider>
+  );
+}
+```
+
+## Platform Capabilities
+
+| Feature | ChatGPT | MCP |
+|---------|---------|-----|
+| `callTool` | ✅ | ✅ |
+| `openLink` | ✅ | ✅ |
+| `sendMessage` | ✅ | ✅ |
+| `widgetState` (persistence) | ✅ | ❌ |
+| `modelContext` (dynamic context) | ❌ | ✅ |
+| `fileUpload` / `fileDownload` | ✅ | ❌ |
+| `partialToolInput` (streaming) | ❌ | ✅ |
+
+## Workflow
+
+```
+1. DEVELOP     npm run dev       Edit widgets, test with mock tools
+2. EXPORT      npm run export    Generate widget bundle + manifest
+3. DEPLOY      Your choice       Vercel, Netlify, any static host
+4. REGISTER    Platform dashboard  Connect your app
+```
+
+## Generated Project
+
+```
+my-app/
+├── app/                    Next.js app
+├── components/
+│   └── examples/           Example widgets
+├── lib/
+│   ├── workbench/          Dev environment + React hooks
+│   └── export/             Production bundler
+└── server/                 MCP server (if selected)
+```
+
+## Export Output
+
+```bash
+npm run export
+```
+
+Generates:
+
+```
+export/
+├── widget/
+│   └── index.html      Self-contained widget (deploy to static host)
+├── manifest.json       App manifest
+└── README.md           Deployment instructions
+```
+
+## Debugging
+
+Enable debug mode to troubleshoot platform detection:
+
+```ts
+import { enableDebugMode, detectPlatformDetailed } from "mcp-app-studio";
+
+// In browser console or before app init
+enableDebugMode();
+
+// Get detailed detection info
+const result = detectPlatformDetailed();
+console.log('Platform:', result.platform);
+console.log('Detected by:', result.detectedBy);
+console.log('Checks:', result.checks);
+```
+
+## MCP Server
+
+If you selected "Include MCP server" during setup:
+
+```bash
+cd server
+npm install
+npm run dev          # http://localhost:3001/mcp
+npm run inspect      # Test with MCP Inspector
+```
+
+## Learn More
+
+- [MCP Apps Specification](https://modelcontextprotocol.io/specification/)
+- [ChatGPT Apps SDK](https://developers.openai.com/apps-sdk/)
+- [assistant-ui](https://www.assistant-ui.com/)
+
+## License
+
+MIT

package/bin/mcp-app-studio.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import("../dist/cli/index.js").catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/dist/bridge-BOSEqpaS.d.ts

@@ -0,0 +1,66 @@
+import { McpUiHostCapabilities, App } from '@modelcontextprotocol/ext-apps';
+import { DisplayMode, ExtendedBridge, HostCapabilities, HostContext, ToolInputCallback, ToolInputPartialCallback, ToolResultCallback, ToolCancelledCallback, HostContextChangedCallback, TeardownCallback, ToolResult, ChatMessage, ContentBlock } from './core/index.js';
+
+interface AppCapabilities {
+    tools?: {
+        listChanged?: boolean;
+    };
+    resources?: {
+        listChanged?: boolean;
+    };
+    prompts?: {
+        listChanged?: boolean;
+    };
+    displayMode?: {
+        supported: DisplayMode[];
+    };
+}
+interface MCPBridgeOptions {
+    autoResize?: boolean;
+}
+type CallToolHandler = (name: string, args: Record<string, unknown>, extra: unknown) => Promise<ToolResult>;
+type ListToolsHandler = (cursor?: string) => Promise<string[]>;
+declare class MCPBridge implements ExtendedBridge {
+    readonly platform: "mcp";
+    readonly capabilities: HostCapabilities;
+    private app;
+    private toolInputCallbacks;
+    private toolInputPartialCallbacks;
+    private toolResultCallbacks;
+    private toolCancelledCallbacks;
+    private contextCallbacks;
+    private teardownCallbacks;
+    constructor(appInfo?: {
+        name: string;
+        version: string;
+    }, appCapabilities?: AppCapabilities, options?: MCPBridgeOptions);
+    connect(): Promise<void>;
+    getHostContext(): HostContext | null;
+    private mapHostContext;
+    onToolInput(callback: ToolInputCallback): () => void;
+    onToolInputPartial(callback: ToolInputPartialCallback): () => void;
+    onToolResult(callback: ToolResultCallback): () => void;
+    onToolCancelled(callback: ToolCancelledCallback): () => void;
+    onHostContextChanged(callback: HostContextChangedCallback): () => void;
+    onTeardown(callback: TeardownCallback): () => void;
+    callTool(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    openLink(url: string): Promise<void>;
+    requestDisplayMode(mode: DisplayMode): Promise<DisplayMode>;
+    sendSizeChanged(size: {
+        width?: number;
+        height?: number;
+    }): void;
+    sendMessage(message: ChatMessage): Promise<void>;
+    updateModelContext(ctx: {
+        content?: ContentBlock[];
+        structuredContent?: Record<string, unknown>;
+    }): Promise<void>;
+    sendLog(level: "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency", data: string, logger?: string): void;
+    setCallToolHandler(handler: CallToolHandler): void;
+    setListToolsHandler(handler: ListToolsHandler): void;
+    getHostCapabilities(): McpUiHostCapabilities | undefined;
+    setupSizeChangedNotifications(): () => void;
+    getApp(): App;
+}
+
+export { type AppCapabilities as A, MCPBridge as M, type MCPBridgeOptions as a };

package/dist/chunk-4LAH4JH6.js

@@ -0,0 +1,47 @@
+// src/core/capabilities.ts
+var CHATGPT_CAPABILITIES = {
+  platform: "chatgpt",
+  callTool: true,
+  openLink: true,
+  displayModes: ["pip", "inline", "fullscreen"],
+  sizeReporting: true,
+  closeWidget: true,
+  sendMessage: true,
+  modal: true,
+  fileUpload: true,
+  fileDownload: true,
+  widgetState: true,
+  modelContext: false,
+  logging: false,
+  partialToolInput: false,
+  toolCancellation: false,
+  teardown: false
+};
+var MCP_CAPABILITIES = {
+  platform: "mcp",
+  callTool: true,
+  openLink: true,
+  displayModes: ["inline", "fullscreen", "pip"],
+  sizeReporting: true,
+  closeWidget: false,
+  sendMessage: true,
+  modal: false,
+  fileUpload: false,
+  fileDownload: false,
+  widgetState: false,
+  modelContext: true,
+  logging: true,
+  partialToolInput: true,
+  toolCancellation: true,
+  teardown: true
+};
+function hasFeature(capabilities, feature) {
+  if (!capabilities) return false;
+  return capabilities[feature] === true;
+}
+
+export {
+  CHATGPT_CAPABILITIES,
+  MCP_CAPABILITIES,
+  hasFeature
+};

package/dist/chunk-KRCGOYZ5.js

@@ -0,0 +1,16 @@
+// src/core/types.ts
+function textBlock(text, annotations) {
+  const block = { type: "text", text };
+  if (annotations) block.annotations = annotations;
+  return block;
+}
+function imageBlock(data, mimeType, annotations) {
+  const block = { type: "image", data, mimeType };
+  if (annotations) block.annotations = annotations;
+  return block;
+}
+
+export {
+  textBlock,
+  imageBlock
+};

package/dist/chunk-L2RRNF7V.js

@@ -0,0 +1,140 @@
+import {
+  CHATGPT_CAPABILITIES
+} from "./chunk-4LAH4JH6.js";
+
+// src/platforms/chatgpt/bridge.ts
+var ChatGPTBridge = class {
+  platform = "chatgpt";
+  capabilities = CHATGPT_CAPABILITIES;
+  toolInputCallbacks = /* @__PURE__ */ new Set();
+  toolResultCallbacks = /* @__PURE__ */ new Set();
+  contextCallbacks = /* @__PURE__ */ new Set();
+  lastContext = null;
+  connected = false;
+  get openai() {
+    if (!window.openai) {
+      throw new Error("ChatGPT bridge not available");
+    }
+    return window.openai;
+  }
+  async connect() {
+    if (!window.openai) {
+      throw new Error(
+        "ChatGPT bridge not available. Is this running inside ChatGPT?"
+      );
+    }
+    window.addEventListener("openai:set_globals", this.handleGlobalsChange);
+    this.lastContext = this.buildHostContext();
+    if (this.openai.toolInput) {
+      this.toolInputCallbacks.forEach((cb) => cb(this.openai.toolInput));
+    }
+    if (this.openai.toolOutput) {
+      this.toolResultCallbacks.forEach(
+        (cb) => cb({
+          structuredContent: this.openai.toolOutput
+        })
+      );
+    }
+    this.connected = true;
+  }
+  buildHostContext() {
+    const g = this.openai;
+    return {
+      theme: g.theme,
+      locale: g.locale,
+      displayMode: g.displayMode,
+      availableDisplayModes: ["pip", "inline", "fullscreen"],
+      containerDimensions: { maxHeight: g.maxHeight },
+      platform: this.mapDeviceType(g.userAgent?.device?.type),
+      deviceCapabilities: g.userAgent?.capabilities,
+      safeAreaInsets: g.safeArea?.insets,
+      userAgent: "ChatGPT"
+    };
+  }
+  mapDeviceType(type) {
+    if (type === "mobile" || type === "tablet") return "mobile";
+    return "web";
+  }
+  handleGlobalsChange = () => {
+    const newContext = this.buildHostContext();
+    if (JSON.stringify(newContext) !== JSON.stringify(this.lastContext)) {
+      this.lastContext = newContext;
+      this.contextCallbacks.forEach((cb) => cb(newContext));
+    }
+    if (this.openai.toolInput) {
+      this.toolInputCallbacks.forEach((cb) => cb(this.openai.toolInput));
+    }
+    if (this.openai.toolOutput) {
+      const result = {
+        structuredContent: this.openai.toolOutput
+      };
+      if (this.openai.toolResponseMetadata) {
+        result._meta = this.openai.toolResponseMetadata;
+      }
+      this.toolResultCallbacks.forEach((cb) => cb(result));
+    }
+  };
+  getHostContext() {
+    return this.lastContext;
+  }
+  onToolInput(callback) {
+    this.toolInputCallbacks.add(callback);
+    if (this.connected && this.openai.toolInput) {
+      callback(this.openai.toolInput);
+    }
+    return () => this.toolInputCallbacks.delete(callback);
+  }
+  onToolResult(callback) {
+    this.toolResultCallbacks.add(callback);
+    if (this.connected && this.openai.toolOutput) {
+      callback({ structuredContent: this.openai.toolOutput });
+    }
+    return () => this.toolResultCallbacks.delete(callback);
+  }
+  onHostContextChanged(callback) {
+    this.contextCallbacks.add(callback);
+    return () => this.contextCallbacks.delete(callback);
+  }
+  async callTool(name, args) {
+    const result = await this.openai.callTool(name, args);
+    return { structuredContent: result };
+  }
+  async openLink(url) {
+    this.openai.openExternal({ href: url });
+  }
+  async requestDisplayMode(mode) {
+    const result = await this.openai.requestDisplayMode({ mode });
+    return result.mode;
+  }
+  sendSizeChanged(size) {
+    if (size.height != null) {
+      this.openai.notifyIntrinsicHeight(size.height);
+    }
+  }
+  async sendMessage(message) {
+    const text = message.content.filter((c) => c.type === "text").map((c) => c.text).join("\n");
+    await this.openai.sendFollowUpMessage({ prompt: text });
+  }
+  setWidgetState(state) {
+    this.openai.setWidgetState(state);
+  }
+  getWidgetState() {
+    return this.openai.widgetState;
+  }
+  async uploadFile(file) {
+    return this.openai.uploadFile(file);
+  }
+  async getFileDownloadUrl(fileId) {
+    return this.openai.getFileDownloadUrl({ fileId });
+  }
+  requestClose() {
+    this.openai.requestClose();
+  }
+  async requestModal(options) {
+    await this.openai.requestModal(options);
+  }
+};
+
+export {
+  ChatGPTBridge
+};

package/dist/chunk-QO43ZGJI.js

@@ -0,0 +1,174 @@
+import {
+  MCP_CAPABILITIES
+} from "./chunk-4LAH4JH6.js";
+
+// src/platforms/mcp/bridge.ts
+import { App } from "@modelcontextprotocol/ext-apps";
+var MCPBridge = class {
+  platform = "mcp";
+  capabilities = MCP_CAPABILITIES;
+  app;
+  toolInputCallbacks = /* @__PURE__ */ new Set();
+  toolInputPartialCallbacks = /* @__PURE__ */ new Set();
+  toolResultCallbacks = /* @__PURE__ */ new Set();
+  toolCancelledCallbacks = /* @__PURE__ */ new Set();
+  contextCallbacks = /* @__PURE__ */ new Set();
+  teardownCallbacks = /* @__PURE__ */ new Set();
+  constructor(appInfo, appCapabilities, options) {
+    const autoResize = options?.autoResize ?? true;
+    this.app = new App(
+      appInfo ?? { name: "MCP App", version: "1.0.0" },
+      appCapabilities ?? {},
+      { autoResize }
+    );
+    this.app.ontoolinput = (params) => {
+      this.toolInputCallbacks.forEach(
+        (cb) => cb(params.arguments)
+      );
+    };
+    this.app.ontoolinputpartial = (params) => {
+      this.toolInputPartialCallbacks.forEach(
+        (cb) => cb(params.arguments)
+      );
+    };
+    this.app.ontoolresult = (params) => {
+      const result = {
+        content: params.content,
+        structuredContent: params.structuredContent
+      };
+      if (params.isError !== void 0) {
+        result.isError = params.isError;
+      }
+      if (params._meta) {
+        result._meta = params._meta;
+      }
+      this.toolResultCallbacks.forEach((cb) => cb(result));
+    };
+    this.app.ontoolcancelled = (params) => {
+      this.toolCancelledCallbacks.forEach((cb) => cb(params.reason));
+    };
+    this.app.onhostcontextchanged = (params) => {
+      const ctx = this.mapHostContext(params);
+      this.contextCallbacks.forEach((cb) => cb(ctx));
+    };
+    this.app.onteardown = async () => {
+      for (const cb of this.teardownCallbacks) {
+        await cb();
+      }
+      return {};
+    };
+  }
+  async connect() {
+    await this.app.connect();
+  }
+  getHostContext() {
+    const ctx = this.app.getHostContext();
+    return ctx ? this.mapHostContext(ctx) : null;
+  }
+  mapHostContext(ctx) {
+    return ctx;
+  }
+  onToolInput(callback) {
+    this.toolInputCallbacks.add(callback);
+    return () => this.toolInputCallbacks.delete(callback);
+  }
+  onToolInputPartial(callback) {
+    this.toolInputPartialCallbacks.add(callback);
+    return () => this.toolInputPartialCallbacks.delete(callback);
+  }
+  onToolResult(callback) {
+    this.toolResultCallbacks.add(callback);
+    return () => this.toolResultCallbacks.delete(callback);
+  }
+  onToolCancelled(callback) {
+    this.toolCancelledCallbacks.add(callback);
+    return () => this.toolCancelledCallbacks.delete(callback);
+  }
+  onHostContextChanged(callback) {
+    this.contextCallbacks.add(callback);
+    return () => this.contextCallbacks.delete(callback);
+  }
+  onTeardown(callback) {
+    this.teardownCallbacks.add(callback);
+    return () => this.teardownCallbacks.delete(callback);
+  }
+  async callTool(name, args) {
+    const result = await this.app.callServerTool({ name, arguments: args });
+    const toolResult = {
+      content: result.content,
+      structuredContent: result.structuredContent
+    };
+    if (result.isError !== void 0) {
+      toolResult.isError = result.isError;
+    }
+    return toolResult;
+  }
+  async openLink(url) {
+    await this.app.openLink({ url });
+  }
+  async requestDisplayMode(mode) {
+    const result = await this.app.requestDisplayMode({ mode });
+    return result.mode;
+  }
+  sendSizeChanged(size) {
+    this.app.sendSizeChanged(size);
+  }
+  async sendMessage(message) {
+    await this.app.sendMessage({
+      role: message.role,
+      content: message.content.map((c) => {
+        if (c.type === "text") {
+          return { type: "text", text: c.text };
+        }
+        return c;
+      })
+    });
+  }
+  async updateModelContext(ctx) {
+    await this.app.updateModelContext(ctx);
+  }
+  sendLog(level, data, logger) {
+    this.app.sendLog({ level, data, logger });
+  }
+  setCallToolHandler(handler) {
+    this.app.oncalltool = async (params, extra) => {
+      const result = await handler(params.name, params.arguments ?? {}, extra);
+      const content = result.content?.map((c) => {
+        if (c.type === "text") {
+          return { type: "text", text: c.text };
+        }
+        if (c.type === "image" || c.type === "audio") {
+          return { type: c.type, data: c.data, mimeType: c.mimeType };
+        }
+        return c;
+      }) ?? [];
+      const response = { content };
+      if (result.structuredContent !== void 0) {
+        response.structuredContent = result.structuredContent;
+      }
+      if (result.isError !== void 0) {
+        response.isError = result.isError;
+      }
+      return response;
+    };
+  }
+  setListToolsHandler(handler) {
+    this.app.onlisttools = async (params) => {
+      const tools = await handler(params?.cursor);
+      return { tools };
+    };
+  }
+  getHostCapabilities() {
+    return this.app.getHostCapabilities();
+  }
+  setupSizeChangedNotifications() {
+    return this.app.setupSizeChangedNotifications();
+  }
+  getApp() {
+    return this.app;
+  }
+};
+
+export {
+  MCPBridge
+};

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }