repository·main·Indexed 23 days ago
https://github.com/alpic-ai/skybridgeA full-stack React framework for building Model Context Protocol (MCP) Apps and Servers. Skybridge bridges low-level MCP SDKs with type-safe, interactive user interfaces for LLM clients such as Claude and ChatGPT. It includes tooling for widget creation, OAuth authentication integration via Auth0 and Authplane, and a Hooks Conformance suite for verifying host support of web hooks.
Skybridge is a full-stack React framework designed for building Model Context Protocol (MCP) Apps and MCP Servers. It enables developers to create type-safe, interactive UI views that can be rendered within MCP-compatible clients like Claude, ChatGPT, and VSCode.
Key features include:
Skybridge Hooks Conformance is a self-testing MCP app designed to verify how different hosts (such as ChatGPT, Claude, or the DevTools emulator) support various Skybridge web hooks.
It runs a sequence of tests via a stepper. Some tests are 'silent' (automatic), while others with user-visible side effects (like opening a link or a modal) require user interaction or automated confirmation.
Each test results in one of four verdicts:
supported: The hook functions correctly on the host.partial: Only part of the hook works (details are provided in a results table).unsupported: The host lacks the capability, but handles it gracefully (e.g., a documented no-op or a throw). This is still considered conformant.error: An unexpected failure occurred.Skybridge documentation is organized into specific sections designed to support different stages of the developer journey. Understanding these sections helps you find the right information based on your current goal:
Focuses on initial discovery and getting a working app running in under 5 minutes.
create command or the Skybridge Skill to scaffold an app.Provides the mental models required to understand Skybridge internals:
Step-by-step implementation patterns for specific tasks:
Focuses on the build and debug experience:
Technical specifications for precision implementation:
create, build, and dev.McpServer class, registerTool, and type exports.useCallTool, useUser, useViewState).createStore, generateHelpers, and data-llm attribute.useAppsSdkContext, useMcpAppContext).Example applications categorized by type (Basic, Auth, Third-party integrations).
The example follows this directory structure:
server.ts: The main server entry point.src/data/: Contains game data like suspects, puzzles, and images.src/views/: Contains the UI layer.murder-in-the-valley.tsx: The main widget entry point.screens/: Individual screen components (e.g., Start, Intro, Main, Victory).components/: Shared UI components (e.g., SuspectCard, DialogueBox).hooks/: Custom React hooks (e.g., useTypewriter).src/index.css: Global styles.vite.config.ts: Vite configuration.alpic.json: Deployment configuration.The starter template follows this directory structure:
src/server.ts: The main server entry point where tools are registered.src/views/: Contains React components. Each file represents a single view.src/components/: Shared UI components used across different views.src/helpers.ts: Shared utility functions.src/index.css: Global CSS styles.vite.config.ts: Vite configuration.alpic.json: Deployment configuration for Alpic.package.json: Project dependencies and scripts.A deployed MCP App is a server hosted on a public URL. It must satisfy two requirements:
/mcp endpoint to interact with the Model Context Protocol server.Deployment can be performed on any Node.js-compatible platform.
https://your-domain.com/v1/mcp). It determines the prefix by reading the x-forwarded-prefix header, allowing it to serve assets correctly under that path. This is useful for hosting multiple versions of an app on a single domain.The Ecommerce Carousel example demonstrates several core Skybridge hooks for building interactive widgets:
useCallTool(): Used within a widget to invoke MCP server tools (e.g., calling create-checkout or check-checkout-status).useLayout(): Used to adapt the UI to light/dark modes.useUser(): Used for localization, providing access to the user's locale (supports English, French, Spanish, and German).useWidgetState(): Used to maintain persistent state (like a shopping cart) across re-renders.You can implement full OAuth authentication using the stytchProvider. This provider automates several steps:
/mcp transport level. Unauthenticated requests receive an HTTP 401 before reaching any tool handlers.oauth: await stytchProvider(...), the server auto-mounts well-known metadata endpoints and handles Bearer verification.To use this, you must serve static HTML files (e.g., authorize.html, login.html, authenticate.html) from your MCP server to handle the Stytch IDP flows via @stytch/vanilla-js.
The Productivity Example demonstrates several core Skybridge hooks used to build interactive widgets:
useToolInfo(): Accesses tool input, output, and metadata.useCallTool(): Provides a type-safe way to call backend tools directly from the widget.useWidgetState(): Maintains persistent state (like selected items or chart data) across re-renders.useUser(): Handles localization; automatically provides translations based on user locale (e.g., English, French, Spanish, Chinese).useLayout(): Used to adapt the UI to light or dark themes.useDisplayMode(): Allows switching between inline and fullscreen views.useSendFollowUpMessage(): Enables the widget to send follow-up messages back to the AI.useOpenExternal(): Used to open external URLs.The ChatGPT Files example utilizes the following stack:
useFiles() (upload, selectFiles, getDownloadUrl) from the ChatGPT Apps SDK.useCallTool() with _meta["openai/widgetAccessible"] set to enable widget access.fflate (zipSync) for server-side ZIP creation (Node's zlib is insufficient for the ZIP container).aws4fetch for signing presigned download URLs.useOpenExternal() to open the generated download URLs.