skybridge

Extends the official @modelcontextprotocol/sdk with a generic McpServer<TTools> class that accumulates tool definitions while preserving TypeScript type information across server and client boundaries. The framework uses a type inference system that propagates tool schemas from server registration through to React hooks on the client, enabling compile-time type checking for tool invocations without runtime type assertions. This is achieved through TypeScript generics and a manifest system that maps tool definitions to their implementations.

Wraps ChatGPT's injected window.openai global object with declarative React hooks (useToolInfo, useCallTool, useWidgetState, useOpenAiGlobal) that abstract away imperative callback patterns and state management. The hooks handle lifecycle management of tool invocations, state persistence, and environment access within widget iframes. This approach eliminates boilerplate for accessing tool metadata, invoking tools asynchronously, and managing widget-scoped state without requiring developers to interact directly with the low-level window.openai API.

Skybridge provides environment hooks (useEnvironment, useConfig) that inject environment variables and configuration into widgets at runtime, with separate handling for development and production environments. Configuration is defined in a centralized file and automatically injected into widget iframes, eliminating the need for hardcoded values or manual environment variable passing. The system supports environment-specific overrides, allowing different configurations for development, staging, and production deployments.

Skybridge provides action hooks that enable widgets to trigger MCP tool invocations in response to user events (clicks, form submissions, etc.) without manually managing async state or error handling. These hooks abstract the complexity of tool invocation lifecycle (loading, success, error states) and provide callbacks for handling results. The hooks integrate with React's event system, allowing declarative specification of which tools to invoke on which events.

The TemplateHelper class renders widget HTML from Handlebars templates, injecting typed context data derived from tool definitions and widget metadata. Templates can reference tool parameters, descriptions, and other schema information through Handlebars syntax, enabling dynamic UI generation based on tool structure. The system supports both development and production modes, with development mode allowing hot-reload of template changes and production mode bundling templates into optimized assets.

A custom Vite plugin scans the src/widgets/ directory to discover widget components, bundles each widget as an independent asset, and generates a manifest.json file mapping widget source files to their bundled outputs. The plugin handles both development and production modes: in development, it enables Hot Module Replacement (HMR) for rapid iteration; in production, it optimizes widget bundles for size and performance. The manifest enables the MCP server to locate and serve widget assets dynamically at runtime.

Skybridge provides a DevTools application that runs locally during development, offering a web-based UI for testing widgets without deploying to ChatGPT. The DevTools includes a tool panel for selecting and invoking MCP tools, a widget renderer that displays the selected widget's UI, and a development server that serves widget assets with HMR enabled. The DevTools communicates with the MCP server via stdio or HTTP, allowing developers to test tool invocations and widget interactions in an isolated environment before deploying to production.

The generateHelpers<AppType>() factory function creates a set of typed utility functions scoped to a specific widget's tool context. These helpers provide type-safe wrappers around useCallTool and other hooks, with pre-bound tool names and parameter types inferred from the AppType generic. This eliminates the need to manually specify tool names and types in every hook call, reducing boilerplate and improving IDE autocomplete for tool invocations within a widget.

Skybridge manages widget initialization, mounting, and cleanup differently in development and production environments. In development mode, widgets are loaded from the local DevTools server with HMR enabled, allowing instant updates without page reload. In production mode, widgets are served from bundled assets with optimized loading and error handling. The framework handles iframe creation, context injection (window.openai API, environment variables), and cleanup on widget unmount, abstracting away the complexity of ChatGPT's widget lifecycle.

Skybridge uses a data-llm HTML attribute system to mark elements within widgets that should receive LLM context or trigger specific behaviors. This attribute enables declarative specification of which widget elements correspond to tool parameters, outputs, or state, allowing the framework to automatically pass context to the LLM without explicit JavaScript code. The system integrates with the widget rendering pipeline to inject data-llm attributes into template-rendered HTML, enabling semantic markup that ChatGPT can interpret for better context understanding.

Skybridge extends the official MCP SDK's transport layer to support both stdio and HTTP communication protocols, with built-in support for ChatGPT's widget environment. The McpServer class handles transport initialization, message routing, and error handling transparently, allowing developers to focus on tool and widget registration without managing low-level protocol details. The framework automatically configures the appropriate transport based on the deployment context (local development vs ChatGPT production).

Skybridge provides useWidgetState hook that manages persistent state within a widget's scope, automatically syncing state across tool invocations and widget re-renders. The hook abstracts the underlying storage mechanism (which may be iframe-local storage, ChatGPT's widget context, or external state store) and provides a React-like setState interface. State is scoped to the widget instance, preventing cross-widget state pollution while enabling widgets to maintain context across multiple tool calls.