Skybridge

https://docs.skybridge.tech
Admin
Skybridge is a modular TypeScript framework for building production-ready ChatGPT and MCP apps with...
Tokens:61,652
Snippets:469
Trust Score:4.7
Update:9 months ago
Show doc for...
Tokens:
Raw
### Start Skybridge Development Server with Package Managers

Source: https://docs.skybridge.tech/quickstart/create-new-app

Commands to start the Skybridge development server after bootstrapping your project. This command initiates the local development environment, including the Express server, MCP endpoint, and HMR for the frontend.

```bash
npm run dev
```

```bash
pnpm dev
```

```bash
yarn dev
```

```bash
bun dev
```

```bash
deno task dev
```

--------------------------------

### Bootstrap Skybridge Project with Package Managers

Source: https://docs.skybridge.tech/quickstart/create-new-app

Use these commands to create a new Skybridge project using different package managers like npm, pnpm, yarn, bun, or deno. This sets up the initial project structure and dependencies.

```bash
npm create skybridge@latest my-chatgpt-app
```

```bash
pnpm create skybridge my-chatgpt-app
```

```bash
yarn create skybridge my-chatgpt-app
```

```bash
bun create skybridge my-chatgpt-app
```

```bash
deno init --npm skybridge my-chatgpt-app
```

--------------------------------

### Full McpServer Example with Widgets

Source: https://docs.skybridge.tech/api-reference/mcp-server

A comprehensive example demonstrating the initialization of McpServer and the registration of two widgets: 'search-hotels' and 'hotel-details'. It utilizes Zod for schema definition and showcases method chaining for type safety.

```typescript
import { McpServer } from "skybridge/server";
import { z } from "zod";

const server = new McpServer(
  { name: "hotel-booking", version: "1.0.0" },
  {}
)
  .registerWidget("search-hotels", {
    description: "Search for hotels",
  }, {
    inputSchema: {
      city: z.string().describe("City to search"),
      checkIn: z.string().describe("Check-in date"),
      checkOut: z.string().describe("Check-out date"),
      guests: z.number().optional().default(2),
    },
    outputSchema: {
      hotels: z.array(z.object({
        id: z.string(),
        name: z.string(),
        price: z.number(),
        rating: z.number(),
      })),
    },
  }, async ({ city, checkIn, checkOut, guests }) => {
    const hotels = await searchHotels({ city, checkIn, checkOut, guests });

    return {
      content: [{ type: "text", text: `Found ${hotels.length} hotels in ${city}` }],
      structuredContent: { hotels },
    };
  })
  .registerWidget("hotel-details", {
    description: "Get hotel details",
  }, {
    inputSchema: {
      hotelId: z.string(),
    },
  }, async ({ hotelId }) => {
    const hotel = await getHotel(hotelId);

    return {
      content: [{ type: "text", text: `Showing details for ${hotel.name}` }],
      structuredContent: hotel,
    };
  });

export type AppType = typeof server;
export default server;
```

--------------------------------

### Example: Displaying Response Metadata with useToolInfo Hook

Source: https://docs.skybridge.tech/api-reference/use-tool-info

This example shows how to access and display `responseMetadata` returned by the `useToolInfo` hook, alongside the tool's output, after the tool execution has successfully completed.

```tsx
import { useToolInfo } from "skybridge/web";

function ApiResultWidget() {
  const { input, output, responseMetadata, isSuccess } = useToolInfo<{ 
    input: { endpoint: string };
    output: { data: unknown };
    responseMetadata: {
      requestId: string;
      duration: number;
      cached: boolean;
    };
  }>();

  if (!isSuccess) {
    return <p>Loading {input.endpoint}...</p>;
  }

  return (
    <div>
      <pre>{JSON.stringify(output.data, null, 2)}</pre>
      <footer className="metadata">
        <span>Request ID: {responseMetadata.requestId}</span>
        <span>Duration: {responseMetadata.duration}ms</span>
        {responseMetadata.cached && <span>Cached</span>}
      </footer>
    </div>
  );
}
```

--------------------------------

### Install skybridge/web Package

Source: https://docs.skybridge.tech/quickstart/add-to-existing-app/web

Installs the Skybridge package using pnpm. This is a prerequisite for using skybridge/web hooks and utilities in your project.

```bash
pnpm add skybridge
```

--------------------------------

### Basic Widget Registration Example (TypeScript)

Source: https://docs.skybridge.tech/api-reference/register-widget

A simple example demonstrating the registration of a 'greeting' widget. It includes a description, an input schema for the widget's name, and an asynchronous handler that returns a greeting message and structured content.

```typescript
server.registerWidget("greeting", {
  description: "Display a greeting",
}, {
  inputSchema: {
    name: z.string(),
  },
}, async ({ name }) => {
  return {
    content: [{ type: "text", text: `Greeting ${name}` }],
    structuredContent: { name, message: `Hello, ${name}!` },
  };
});
```

--------------------------------

### Example: Conditional Rendering with useToolInfo Hook (Loading State)

Source: https://docs.skybridge.tech/api-reference/use-tool-info

An example demonstrating how to use the `isPending` and `isSuccess` flags from `useToolInfo` to conditionally render loading indicators or results in a React component.

```tsx
import { useToolInfo } from "skybridge/web";

function DataWidget() {
  const { input, isPending, isSuccess, output } = useToolInfo<{ 
    input: { query: string };
    output: { results: string[] };
  }>();

  return (
    <div>
      <h3>Search: {input.query}</h3>
      {isPending && (
        <div className="loading">
          <span className="spinner" />
          <p>Searching...</p>
        </div>
      )}
      {isSuccess && (
        <ul>
          {output.results.map((result, i) => (
            <li key={i}>{result}</li>
          ))}
        </ul>
      )}
    </div>
  );
}
```

--------------------------------

### One-Time Setup for generateHelpers

Source: https://docs.skybridge.tech/api-reference/generate-helpers

Illustrates the one-time setup required in a bridge file to create typed `useCallTool` and `useToolInfo` hooks using `generateHelpers`.

```ts
// web/src/helpers.ts
import type { AppType } from "../server"; // type-only import
import { generateHelpers } from "skybridge/web";

export const { useCallTool, useToolInfo } = generateHelpers<AppType>();
```

--------------------------------

### Set up Web Project with Vite and Skybridge

Source: https://docs.skybridge.tech/quickstart/add-to-existing-app/server

Commands to set up a new web project directory, initialize npm, add necessary dependencies (React, Skybridge), and install development dependencies for Vite and TypeScript.

```bash
mkdir web && cd web
pnpm init
pnpm add react react-dom skybridge
pnpm add -D vite typescript @types/react @types/react-dom
```

--------------------------------

### Example: Conditional Rendering Based on Input Type with useToolInfo

Source: https://docs.skybridge.tech/api-reference/use-tool-info

An example demonstrating how to use the `input` property from `useToolInfo` to conditionally render different UI components (e.g., charts) based on the type of data or configuration provided to the tool.

```tsx
import { useToolInfo } from "skybridge/web";

type ChartType = "bar" | "line" | "pie";

function ChartWidget() {
  const { input, output, isSuccess } = useToolInfo<{ 
    input: { type: ChartType; data: number[] };
    output: { processedData: { label: string; value: number }[] };
  }>();

  if (!isSuccess) {
    return <p>Processing chart data...</p>;
  }

  switch (input.type) {
    case "bar":
      return <BarChart data={output.processedData} />;
    case "line":
      return <LineChart data={output.processedData} />;
    case "pie":
      return <PieChart data={output.processedData} />;
    default:
      return <p>Unknown chart type</p>;
  }
}
```

--------------------------------

### Start Skybridge Production Server (Multiple Package Managers)

Source: https://docs.skybridge.tech/quickstart/build-for-production

Starts the production server for your Skybridge application after it has been built. This command runs the compiled application from the `dist/` directory with `NODE_ENV=production`, serving pre-built assets and exposing the MCP endpoint.

```bash
npm start
```

```bash
pnpm start
```

```bash
yarn start
```

```bash
bun start
```

```bash
deno task start
```

--------------------------------

### MCP Server with Method Chaining

Source: https://docs.skybridge.tech/api-reference/generate-helpers

Example of an MCP server setup using method chaining, which is a prerequisite for `generateHelpers` to work correctly for type inference.

```ts
// ✅ Works — chain registerWidget/registerTool calls
const server = new McpServer({ name: "my-app", version: "1.0" }, {})
  .registerWidget("search-voyage", {}, { inputSchema: { destination: z.string() } }, async ({ destination }) => {
    return { content: [{ type: "text", text: `Found trips to ${destination}` }] };
  });

export type AppType = typeof server;
```

--------------------------------

### CSP Merging Example (TypeScript)

Source: https://docs.skybridge.tech/api-reference/register-widget

Illustrates how Skybridge merges CSP domain arrays. User-added domains are appended to the default server domains, ensuring all necessary domains are included.

```typescript
// Skybridge auto-includes: ["https://your-server.com"]
// You add: ["https://api.example.com"]
// Result: ["https://your-server.com", "https://api.example.com"]
```

--------------------------------

### Basic skybridge/web Widget Example

Source: https://docs.skybridge.tech/quickstart/add-to-existing-app/web

A simple React widget demonstrating the use of skybridge/web hooks, specifically `useToolInfo` to fetch tool data and `mountWidget` to render the component. It handles loading and success states for tool information.

```tsx
import { mountWidget, useToolInfo } from "skybridge/web";

const MyWidget: React.FC = () => {
  const toolInfo = useToolInfo();

  if (toolInfo.isPending) {
    return <div>Loading...</div>;
  }

  if (toolInfo.isSuccess) {
    return (
      <div>
        <h2>Results</h2>
        <pre>{JSON.stringify(toolInfo.output.structuredContent, null, 2)}</pre>
      </div>
    );
  }

  return <div>No results</div>;
};

mountWidget(<MyWidget />);
```

--------------------------------

### useMcpAppContext Hook Documentation

Source: https://docs.skybridge.tech/api-reference/use-mcp-app-context

Documentation for the useMcpAppContext hook, detailing its parameters, return values, and usage examples.

```APIDOC
## useMcpAppContext Hook

### Description
Low-level hook for subscribing to MCP App host context values directly. This hook powers many other Skybridge hooks and can be used when specific context values are needed.

<Tip>
  For most use cases, prefer using specialized hooks like `useLayout`, `useUser`, `useToolInfo`, etc., as they offer a more convenient API across different runtimes.
</Tip>

### Method
`useMcpAppContext(key: keyof McpAppContext, options?: { appInfo?: { name: string; version: string } }, requestTimeout?: number): McpAppContext[K] | undefined`

### Parameters
#### `key`
- **key** (keyof McpAppContext) - Required - The key of the context value to subscribe to. Available keys include:
  - `theme` (string): The current color theme (`"light" | "dark"`).
  - `locale` (string): The user's locale (e.g., `"en-US"`).
  - `displayMode` (string): The widget's display mode (`"inline" | "fullscreen"`).
  - `maxHeight` (number): Maximum height available for the widget.
  - `toolInput` (object | null): The input arguments passed to the tool.
  - `toolResult` (object | null): The tool execution result.
  - `toolCancelled` (object | null): Tool cancellation details (if cancelled).

#### `options`
- **options** (object) - Optional - Initialization options for the MCP App bridge. Only used on first instantiation.
  - **appInfo** (object) - Optional - Application information.
    - **name** (string) - The name of the application.
    - **version** (string) - The version of the application.

#### `requestTimeout`
- **requestTimeout** (number) - Optional - Timeout in milliseconds for the initialization request. Defaults to 10000 (10 seconds).

### Returns
- **value** (McpAppContext[K] | undefined) - The current value of the specified context key, or `undefined` if not yet available.

### Request Example
```tsx
import { useMcpAppContext } from "skybridge/web";

function ThemeDisplay() {
  const theme = useMcpAppContext("theme");

  return <p>Current theme: {theme}</p>;
}
```

### Response Example
```json
{
  "theme": "dark"
}
```

### Examples
#### Reading Theme
```tsx
import { useMcpAppContext } from "skybridge/web";

function ThemedWidget() {
  const theme = useMcpAppContext("theme");

  return (
    <div style={{
      backgroundColor: theme === "dark" ? "#1a1a1a" : "#ffffff",
      color: theme === "dark" ? "#ffffff" : "#000000"
    }}>
      <p>Current theme: {theme}</p>
    </div>
  );
}
```

#### Accessing Tool Input
```tsx
import { useMcpAppContext } from "skybridge/web";

function ToolInputDisplay() {
  const toolInput = useMcpAppContext("toolInput");

  if (!toolInput) {
    return <p>No tool input yet...</p>;
  }

  return (
    <div>
      <h3>Tool Input:</h3>
      <pre>{JSON.stringify(toolInput, null, 2)}</pre>
    </div>
  );
}
```

#### Checking Tool Result
```tsx
import { useMcpAppContext } from "skybridge/web";

function ToolResultDisplay() {
  const toolResult = useMcpAppContext("toolResult");
  const toolCancelled = useMcpAppContext("toolCancelled");

  if (toolCancelled) {
    return <p>Tool was cancelled: {toolCancelled.reason}</p>;
  }

  if (!toolResult) {
    return <p>Waiting for tool result...</p>;
  }

  return (
    <div>
      <h3>Tool Result:</h3>
      <pre>{JSON.stringify(toolResult, null, 2)}</pre>
    </div>
  );
}
```

#### Multiple Context Values
```tsx
import { useMcpAppContext } from "skybridge/web";

function EnvironmentInfo() {
  const theme = useMcpAppContext("theme");
  const locale = useMcpAppContext("locale");
  const displayMode = useMcpAppContext("displayMode");
  const maxHeight = useMcpAppContext("maxHeight");

  return (
    <div>
      <h3>MCP App Environment</h3>
      <ul>
        <li>Theme: {theme}</li>
        <li>Locale: {locale}</li>
        <li>Display Mode: {displayMode}</li>
        <li>Max Height: {maxHeight}px</li>
      </ul>
    </div>
  );
}
```

### Type Reference
#### `McpAppContext`
```typescript
type McpAppContext = McpUiHostContext & McpToolState;
```
Combines the host context from the MCP ext-apps spec with tool execution state.

#### `McpToolState`
```typescript
type McpToolState = {
  toolInput: Record<string, unknown> | null;
  toolResult: {
    content: Array<{ type: string; text?: string }>;
    isError?: boolean;
  } | null;
  toolCancelled: {
    reason?: string;
  } | null;
};
```

### Related
* [useAppsSdkContext](/api-reference/use-apps-sdk-context) - The Apps SDK equivalent for ChatGPT
* [MCP Apps Fundamentals](/fundamentals/mcp-apps) - Understanding the MCP Apps runtime
```

--------------------------------

### Settings Modal Implementation with useRequestModal (React)

Source: https://docs.skybridge.tech/api-reference/use-request-modal

Shows a practical example of using the `useRequestModal` hook to implement a settings modal. It demonstrates managing form state within the modal context and triggering the modal to open for configuration.

```tsx
import { useRequestModal } from "skybridge/web";
import { useState } from "react";

function SettingsWidget() {
  const { open, isOpen } = useRequestModal();
  const [settings, setSettings] = useState({
    notifications: true,
    darkMode: false,
    language: "en",
  });

  if (isOpen) {
    return (
      <form className="settings-form">
        <label>
          <input
            type="checkbox"
            checked={settings.notifications}
            onChange={(e) =>
              setSettings((s) => ({ ...s, notifications: e.target.checked }))
            }
          />
          Enable Notifications
        </label>
        <label>
          <input
            type="checkbox"
            checked={settings.darkMode}
            onChange={(e) =>
              setSettings((s) => ({ ...s, darkMode: e.target.checked }))
            }
          />
          Dark Mode
        </label>
        <label>
          Language:
          <select
            value={settings.language}
            onChange={(e) =>
              setSettings((s) => ({ ...s, language: e.target.value }))
            }
          >
            <option value="en">English</option>
            <option value="fr">French</option>
            <option value="es">Spanish</option>
          </select>
        </label>
      </form>
    );
  }

  return (
    <div className="settings-summary">
      <span>Settings</span>
      <button onClick={() => open({ title: "Settings" })}>
        Configure
      </button>
    </div>
  );
}
```

--------------------------------

### Image Upload and Preview with useFiles (TypeScript)

Source: https://docs.skybridge.tech/api-reference/use-files

An example demonstrating how to upload an image file and then generate a preview URL using `upload` and `getDownloadUrl`. This is useful for providing immediate visual feedback to users after they upload an image.

```tsx
import { useFiles } from "skybridge/web";
import { useState } from "react";

function ImageUploader() {
  const { upload, getDownloadUrl } = useFiles();
  const [previewUrl, setPreviewUrl] = useState<string | null>(null);
  const [isUploading, setIsUploading] = useState(false);

  const handleUpload = async (event: React.ChangeEvent<HTMLInputElement>) => {
    const file = event.target.files?.[0];
    if (!file) return;

    setIsUploading(true);
    try {
      const { fileId } = await upload(file);
      const { downloadUrl } = await getDownloadUrl({ fileId });
      setPreviewUrl(downloadUrl);
    } catch (error) {
      console.error("Upload failed:", error);
    } finally {
      setIsUploading(false);
    }
  };

  return (
    <div>
      <input
        type="file"
        accept="image/*"
        onChange={handleUpload}
        disabled={isUploading}
      />
      {isUploading && <p>Uploading...</p>}
      {previewUrl && <img src={previewUrl} alt="Preview" />}
    </div>
  );
}
```

--------------------------------

### Document Manager with File Upload/Download (TypeScript)

Source: https://docs.skybridge.tech/api-reference/use-files

This example showcases a document manager that allows users to upload files and then download them. It utilizes both `upload` and `getDownloadUrl` to manage a list of documents, associating file IDs with their names.

```tsx
import { useFiles } from "skybridge/web";
import { useState } from "react";

type Document = {
  name: string;
  fileId: string;
};

function DocumentManager() {
  const { upload, getDownloadUrl } = useFiles();
  const [documents, setDocuments] = useState<Document[]>([]);

  const handleUpload = async (event: React.ChangeEvent<HTMLInputElement>) => {
    const file = event.target.files?.[0];
    if (!file) return;

    const { fileId } = await upload(file);
    setDocuments((prev) => [...prev, { name: file.name, fileId }]);
  };

  const handleDownload = async (doc: Document) => {
    const { downloadUrl } = await getDownloadUrl({ fileId: doc.fileId });
    window.open(downloadUrl, "_blank");
  };

  return (
    <div>
      <input type="file" onChange={handleUpload} />
      <ul>
        {documents.map((doc) => (
          <li key={doc.fileId}>
            {doc.name}
            <button onClick={() => handleDownload(doc)}>Download</button>
          </li>
        ))}
      </ul>
    </div>
  );
}
```

--------------------------------

### Adapt UI Controls for Touch vs. Hover Devices

Source: https://docs.skybridge.tech/api-reference/use-user

An example showing how to adjust UI element sizes and interactions based on whether the device supports touch or hover, using `userAgent.capabilities.touch` and `userAgent.capabilities.hover` from the useUser hook.

```tsx
import { useUser } from "skybridge/web";

function Slider({ value, onChange }: { value: number; onChange: (v: number) => void }) {
  const { userAgent } = useUser();

  // Use larger touch targets on touch devices
  const thumbSize = userAgent.capabilities.touch ? 44 : 20;

  return (
    <input
      type="range"
      value={value}
      onChange={(e) => onChange(Number(e.target.value))}
      style={{
        height: thumbSize,
        cursor: userAgent.capabilities.hover ? "pointer" : "default",
      }}
    />
  );
}
```

--------------------------------

### Adapt Widget Theme with CSS Variables using useLayout (React)

Source: https://docs.skybridge.tech/guides/host-environment-context

This example shows how to use CSS variables to adapt widget theming based on the host's theme, detected via the `useLayout` hook. It sets CSS variables `--bg` and `--text` dynamically. Requires `skybridge/web`.

```tsx
function ThemedWidget() {
  const { theme } = useLayout();

  return (
    <div
      className="widget"
      data-theme={theme}
      style={{
        "--bg": theme === "dark" ? "#1a1a1a" : "#ffffff",
        "--text": theme === "dark" ? "#ffffff" : "#000000",
      } as React.CSSProperties}
    >
      {/* Content */}
    </div>
  );
}
```

```css
.widget {
  background: var(--bg);
  color: var(--text);
}
```

--------------------------------

### Initialize McpServer Instance

Source: https://docs.skybridge.tech/api-reference/mcp-server

Demonstrates the constructor for McpServer, requiring server information (name, version) and optional configuration options. This initializes the server object.

```typescript
const server = new McpServer(
  serverInfo: { name: string; version: string },
  options: McpServerOptions
);
```

--------------------------------

### Sending Messages with useSendFollowUpMessage

Source: https://docs.skybridge.tech/guides/communicating-with-model

Utilize the `useSendFollowUpMessage` hook to send active messages to the LLM, enabling user-driven questions and guided actions.

```APIDOC
## Sending Messages with useSendFollowUpMessage

### Description
The `useSendFollowUpMessage` hook allows users to send messages to the language model directly from the application's UI. These messages appear in the conversation as if typed by the user, and the model responds naturally.

### Method
N/A (Hook-based)

### Endpoint
N/A

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **prompt** (string) - Required - The message content to send to the LLM.

### Request Example
```javascript
import { useSendFollowUpMessage } from "skybridge/web";

const sendMessage = useSendFollowUpMessage();

// Example: Asking about baggage policy
sendMessage({ prompt: "What's the baggage policy for this flight?" });

// Example: Guided action to book a flight
sendMessage({
  prompt: "I'd like to book this flight. Please proceed with the booking."
});

// Example: Quick question
sendMessage({ prompt: "What are the return policy terms?" });

// Example: Help request
sendMessage({
  prompt: "I'm having trouble completing checkout. Can you help?"
});
```

### Response
N/A (The model's response is handled asynchronously within the chat interface)

### Related
* [useSendFollowUpMessage API](/api-reference/use-send-follow-up-message)
```

--------------------------------

### Initial Data Hydration with useToolInfo

Source: https://docs.skybridge.tech/guides/fetching-data

Fetches data when the widget loads, typically provided by the server. It uses the `useToolInfo` hook and expects structured content in the `output`. The hook provides status flags like `isSuccess` to manage loading and error states.

```tsx
import { useToolInfo } from "skybridge/web";

type FlightData = {
  flights: Array<{ id: string; name: string; price: number }>;
};

export function FlightWidget() {
  const { isSuccess, output } = useToolInfo<FlightData>();

  if (!isSuccess) {
    return <div>Loading...</div>;
  }

  const { flights } = output.structuredContent;

  return (
    <ul>
      {flights.map(flight => (
        <li key={flight.id}>{flight.name} - ${flight.price}</li>
      ))}
    </ul>
  );
}
```

```tsx
const { isIdle, isPending, isSuccess, isError, output, error } = useToolInfo();
```

--------------------------------

### Configure Vite for Skybridge Web Integration

Source: https://docs.skybridge.tech/quickstart/add-to-existing-app/server

Configures Vite to use the skybridge plugin for web development. This setup is crucial for handling Skybridge widgets within the web project.

```typescript
import { defineConfig } from "vite";
import { skybridge } from "skybridge/web";

export default defineConfig({
  plugins: [skybridge()],
});
```

--------------------------------

### Responsive Widget Design with Multiple Hooks (React)

Source: https://docs.skybridge.tech/guides/host-environment-context

This example demonstrates a responsive widget design by combining several hooks: `useLayout` for theme, safe area, and max height; `useUser` for locale and user agent; and `useDisplayMode` for controlling the widget's display state. It adapts styling and content based on device type and theme, switching between inline and picture-in-picture modes.

```tsx
function ResponsiveWidget() {
  const { theme, safeArea, maxHeight } = useLayout();
  const { locale, userAgent } = useUser();
  const { displayMode, setDisplayMode } = useDisplayMode();

  const isMobile = userAgent.device.type === "mobile";
  const isDark = theme === "dark";

  return (
    <div
      style={{
        backgroundColor: isDark ? "#1a1a1a" : "#ffffff",
        color: isDark ? "#ffffff" : "#000000",
        paddingTop: safeArea.top,
        paddingBottom: safeArea.bottom,
        maxHeight: maxHeight ?? "100vh",
        overflow: "auto",
      }}
    >
      {displayMode === "pip" ? (
        <MiniView onExpand={() => setDisplayMode("inline")} />
      ) : (
        <FullView
          isMobile={isMobile}
          locale={locale}
          onMinimize={() => setDisplayMode("pip")}
        />
      )}
    </div>
  );
}
```

--------------------------------

### Get Specific Tool Output Type

Source: https://docs.skybridge.tech/api-reference/infer-utility-types

Retrieves the output type for a specific tool using ToolOutput. This utility defines the expected structure of data returned by a particular tool.

```typescript
import type { ToolOutput } from "skybridge/web";
import type { AppType } from "../../server/src/index";

type SearchOutput = ToolOutput<AppType, "search-hotels">;
// { hotels: Array<{ id: string; name: string; price: number }> }
```

--------------------------------

### Build Skybridge App for Production (Multiple Package Managers)

Source: https://docs.skybridge.tech/quickstart/build-for-production

Compiles your Skybridge application's widgets and server code for production deployment. This command should be run from your project's root directory. It prepares your application by bundling assets and optimizing code.

```bash
npm run build
```

```bash
pnpm build
```

```bash
yarn build
```

```bash
bun build
```

```bash
deno task build
```

--------------------------------

### Get Union of Tool Names

Source: https://docs.skybridge.tech/api-reference/infer-utility-types

Retrieves a union type of all available tool names from the server definition using ToolNames. This is useful for creating type-safe parameters for tool invocation.

```typescript
import type { ToolNames } from "skybridge/web";
import type { AppType } from "../../server/src/index";

type Names = ToolNames<AppType>;
// "search-hotels" | "hotel-details"
```

--------------------------------

### Progressive Enhancement with React Hooks

Source: https://docs.skybridge.tech/api-reference/use-tool-info

Demonstrates progressive enhancement using React hooks to display product information. It shows a loading state with skeletons and a success state with full details. Relies on the `useToolInfo` hook from 'skybridge/web'.

```tsx
import { useToolInfo } from "skybridge/web";

function ProductWidget() {
  const { input, output, isPending, isSuccess } = useToolInfo<{ 
    input: { productId: string; name: string };
    output: {
      price: number;
      stock: number;
      reviews: { rating: number; count: number };
    };
  }>();

  return (
    <div className="product-card">
      {/* Always show name from input */}
      <h2>{input.name}</h2>

      {/* Show skeleton while loading */}
      {isPending && (
        <>
          <div className="skeleton price-skeleton" />
          <div className="skeleton stock-skeleton" />
        </>
      )}

      {/* Show full details when loaded */}
      {isSuccess && (
        <>
          <p className="price">${output.price}</p>
          <p className="stock">
            {output.stock > 0 ? `${output.stock} in stock` : "Out of stock"}
          </p>
          <div className="reviews">
            <span>⭐ {output.reviews.rating}</span>
            <span>({output.reviews.count} reviews)</span>
          </div>
        </>
      )}
    </div>
  );
}

```

--------------------------------

### Get Specific Tool Input Type

Source: https://docs.skybridge.tech/api-reference/infer-utility-types

Extracts the input type for a particular tool using ToolInput. This utility helps define the expected structure of data sent to a specific tool.

```typescript
import type { ToolInput } from "skybridge/web";
import type { AppType } from "../../server/src/index";

type SearchInput = ToolInput<AppType, "search-hotels">;
// { city: string; checkIn: string; checkOut: string; guests?: number }
```

--------------------------------

### Chained Calls with useCallTool in React

Source: https://docs.skybridge.tech/guides/fetching-data

Demonstrates how to chain asynchronous tool calls in a React component using the `useCallTool` hook. It first checks availability and then creates a booking if the room is available. Assumes `useCallTool` is available and correctly configured.

```tsx
function BookingWidget() {
  const { callToolAsync: checkAvailability } = useCallTool("check_availability");
  const { callToolAsync: createBooking } = useCallTool("create_booking");

  const handleBook = async (roomId: string, dates: DateRange) => {
    const availability = await checkAvailability({ roomId, ...dates });

    if (!availability.structuredContent.available) {
      setError("Room not available for these dates");
      return;
    }

    const booking = await createBooking({
      roomId,
      ...dates,
      priceId: availability.structuredContent.priceId,
    });

    setConfirmation(booking.structuredContent);
  };
}
```

--------------------------------

### Component Lifecycle Management (TSX)

Source: https://docs.skybridge.tech/api-reference/data-llm

Provides code examples for managing the lifecycle of components that use the `data-llm` attribute. It demonstrates how to update and remove nodes from the global map and synchronize widget state.

```tsx
// On mount or content change
setNode({ id, parentId, content });
window.openai.setWidgetState({
  ...window.openai.widgetState,
  __widget_context: formatTree()
});

// On unmount
removeNode(id);
window.openai.setWidgetState({
  ...window.openai.widgetState,
  __widget_context: formatTree()
});
```
```

--------------------------------

### Configure CSP Domains for Widget (TypeScript)

Source: https://docs.skybridge.tech/api-reference/register-widget

Demonstrates comprehensive CSP configuration for a 'flight-search' widget. It includes settings for connectDomains, resourceDomains, frameDomains, and redirectDomains within the _meta.ui.csp object.

```typescript
server.registerWidget("flight-search", {
  description: "Search for flights",
  _meta: {
    ui: {
      csp: {
        // APIs your widget calls via fetch/XHR
        connectDomains: ["https://api.flights.com"],
        // CDNs for images, fonts, scripts
        resourceDomains: ["https://cdn.flights.com", "https://fonts.googleapis.com"],
        // External sites for iframe embeds (stricter app review)
        frameDomains: ["https://maps.google.com"],
        // Allowed redirect destinations (skips safe-link modal)
        redirectDomains: ["https://booking.flights.com"],
      },
      // Removes default widget border
      prefersBorder: false,
    },
  },
}, { ... }, async (input) => { ... });
```

--------------------------------

### Common Pattern: Loading State Management

Source: https://docs.skybridge.tech/guides/fetching-data

Demonstrates how to handle loading states during data fetching using the `isPending` flag from `useCallTool`. It shows rendering a skeleton component while data is being fetched and displaying an empty state if no data is returned.

```tsx
function ProductWidget() {
  const { isPending, data } = useCallTool("get_product");

  if (isPending) {
    return <Skeleton />;
  }

  if (!data) {
    return <EmptyState />;
  }

  return <ProductDetails product={data.structuredContent} />;
}
```

--------------------------------

### Basic Usage of useOpenExternal Hook

Source: https://docs.skybridge.tech/api-reference/use-open-external

Demonstrates the fundamental use of the `useOpenExternal` hook to get a function for opening external URLs. This is typically used within a React component's event handler.

```tsx
import { useOpenExternal } from "skybridge/web";

function ExternalLink() {
  const openExternal = useOpenExternal();

  return (
    <button onClick={() => openExternal("https://example.com")}>
      Visit Website
    </button>
  );
}
```

--------------------------------

### Manual vs. generateHelpers useCallTool Hook

Source: https://docs.skybridge.tech/api-reference/generate-helpers

Demonstrates the difference between manually typing `useCallTool` and using `generateHelpers` for automatic type inference. The latter requires zero annotations.

```tsx
// ❌ Without generateHelpers - manual type annotations required
const { callTool } = useCallTool<
  { destination: string },
  { structuredContent: { results: string[] } }
>("search-voyage");
```

```tsx
// ✅ With generateHelpers - fully typed, zero annotations needed
const { callTool } = useCallTool("search-voyage");
// TypeScript knows everything: tool name, input shape, output shape
```

--------------------------------

### Concise data-llm Attribute Usage (TSX)

Source: https://docs.skybridge.tech/api-reference/data-llm

Demonstrates the correct way to use the `data-llm` attribute for clear and concise LLM context. It contrasts with overly verbose examples and highlights the importance of user-focused descriptions.

```tsx
<div data-llm="User viewing Flight AF123 details. Price: $450. Departure: 10:30 AM">
```
```

```tsx
// Bad: Too verbose
<div data-llm="The user is currently in the process of viewing the detailed information panel for the flight with the identifier AF123, which has a price point of $450.00 USD and is scheduled to depart at 10:30 AM local time">
```
```

--------------------------------

### Widget Handler Response Fields (TypeScript)

Source: https://docs.skybridge.tech/api-reference/register-widget

Provides an example of the return object from a widget handler function, showcasing the `content` field for text, `structuredContent` for widget data, and optional `_meta` for additional information.

```typescript
return {
  content: [{ type: "text", text: "Found 5 flights to Paris" }],
  structuredContent: { flights: [...] },  // Access via useToolInfo
  _meta: { searchId: "abc123" }           // Optional metadata
};
```

--------------------------------

### Access Tool Input, Output, and Status with useToolInfo Hook

Source: https://docs.skybridge.tech/api-reference/use-tool-info

Demonstrates the basic usage of the useToolInfo hook to access tool input, output, and execution status (pending/success) within a React component. It shows conditional rendering based on the tool's execution state.

```tsx
import { useToolInfo } from "skybridge/web";

function WeatherWidget() {
  const { input, output, isPending, isSuccess } = useToolInfo<{ 
    input: { city: string };
    output: { temperature: number; conditions: string };
  }>();

  if (isPending) {
    return <p>Loading weather for {input.city}...</p>;
  }

  if (isSuccess) {
    return (
      <div>
        <h3>Weather in {input.city}</h3>
        <p>{output.temperature}°C - {output.conditions}</p>
      </div>
    );
  }

  return null;
}
```

--------------------------------

### Simplified InferTools Implementation

Source: https://docs.skybridge.tech/api-reference/infer-utility-types

Provides a simplified, conceptual example of how the InferTools utility might work internally using TypeScript's conditional and mapped types to extract type information from a server definition.

```typescript
// Simplified version of how InferTools works
type InferTools<ServerType> = ServerType extends {
  $types: McpServerTypes<infer Registry>;
}
  ? Registry
  : never;

// The $types property carries type information without runtime cost
class McpServer<Registry = {}> {
  $types!: McpServerTypes<Registry>;

  registerWidget<Name, Input, Output>(...): McpServer<
    Registry & { [K in Name]: ToolDef<Input, Output> }
  > {
    // Each call returns a new type with the tool added
  }
}
```

--------------------------------

### Create a Basic Skybridge Widget Component

Source: https://docs.skybridge.tech/quickstart/add-to-existing-app/server

Defines a simple React component for a Skybridge widget and mounts it using `mountWidget`. This serves as the basic structure for a UI widget.

```tsx
import { mountWidget } from "skybridge/web";

const MyWidget: React.FC = () => {
  return (
    <div>
      <h2>Hello from Skybridge!</h2>
      <p>Your widget is working!</p>
    </div>
  );
};

mountWidget(<MyWidget />);
```

--------------------------------

### Reading Multiple Context Values with useMcpAppContext (React)

Source: https://docs.skybridge.tech/api-reference/use-mcp-app-context

This example illustrates how to simultaneously subscribe to multiple context values ('theme', 'locale', 'displayMode', 'maxHeight') using the useMcpAppContext hook and display them in a list.

```tsx
import { useMcpAppContext } from "skybridge/web";

function EnvironmentInfo() {
  const theme = useMcpAppContext("theme");
  const locale = useMcpAppContext("locale");
  const displayMode = useMcpAppContext("displayMode");
  const maxHeight = useMcpAppContext("maxHeight");

  return (
    <div>
      <h3>MCP App Environment</h3>
      <ul>
        <li>Theme: {theme}</li>
        <li>Locale: {locale}</li>
        <li>Display Mode: {displayMode}</li>
        <li>Max Height: {maxHeight}px</li>
      </ul>
    </div>
  );
}
```

--------------------------------

### React: Best Practices for data-llm

Source: https://docs.skybridge.tech/concepts/llm-context-sync

This code snippet provides examples of best practices for using the `data-llm` attribute. It covers describing visible state, updating on user interaction, avoiding sensitive data, and nesting for hierarchy.

```tsx
// Good: Describes visible state
<div data-llm={`Showing ${items.length} search results for \"${query}\"`}>

// Good: Context changes when user acts
<div data-llm={selectedTab === "details"
  ? "User is viewing product details"
  : "User is viewing reviews"
}>

// Bad: Don't expose internal IDs or tokens
<div data-llm={`Session ID: ${sessionId}`}

// Good: Describe the semantic meaning
<div data-llm="User is logged in">

// Bad: Too much noise
<div data-llm={`Button hovered: ${isHovered}, scroll: ${scrollY}`}

// Good: Only meaningful state
<div data-llm={`Viewing page ${currentPage} of ${totalPages}`}

<div data-llm="Shopping cart">
  {items.map(item => (
    <div key={item.id} data-llm={`${item.name}: ${item.quantity}x $${item.price}`}>
      {item.name}
    </div>
  ))}
  <div data-llm={`Total: $${total}`}>Total: ${total}</div>
</div>
```

--------------------------------

### Multi-step Wizard Context with data-llm in React

Source: https://docs.skybridge.tech/api-reference/data-llm

Example of using data-llm in a multi-step wizard to inform the model about the user's current step and collected data. This allows for contextual guidance throughout the wizard process.

```tsx
export function BookingWizard() {
  const [step, setStep] = useState<"dates" | "rooms" | "payment">("dates");
  const [bookingData, setBookingData] = useState({
    checkIn: null,
    checkOut: null,
    roomType: null,
  });

  const stepDescriptions = {
    dates: "User is selecting check-in and check-out dates",
    rooms: `User is selecting a room type. Dates: ${bookingData.checkIn} to ${bookingData.checkOut}`,
    payment: `User is on the payment page. Room: ${bookingData.roomType}, Dates: ${bookingData.checkIn} to ${bookingData.checkOut}`,
  };

  return (
    <div data-llm={stepDescriptions[step]}>
      {step === "dates" && <DateSelector onNext={(dates) => {
        setBookingData({ ...bookingData, ...dates });
        setStep("rooms");
      }} />}
      {step === "rooms" && <RoomSelector onNext={(room) => {
        setBookingData({ ...bookingData, roomType: room });
        setStep("payment");
      }} />}
      {step === "payment" && <PaymentForm bookingData={bookingData} />}
    </div>
  );
}
```

--------------------------------

### Output Schema Definition with Zod (TypeScript)

Source: https://docs.skybridge.tech/api-reference/register-widget

Shows how to define optional type hints for the widget's output using Zod. This helps with documentation and type inference, although runtime validation is not enforced.

```typescript
{
  inputSchema: { ... },
  outputSchema: {
    results: z.array(z.object({
      id: z.string(),
      name: z.string(),
      price: z.number(),
    })),
    totalCount: z.number(),
  }
}
```

--------------------------------

### useToolInfo Hook Properties: Input, Output, Response Metadata

Source: https://docs.skybridge.tech/api-reference/use-tool-info

Explains the `input`, `output`, and `responseMetadata` properties of the object returned by `useToolInfo`. `input` is always available, while `output` and `responseMetadata` are only available when the tool status is 'success'.

```tsx
input: ToolInput
output: ToolOutput | undefined
responseMetadata: ToolResponseMetadata | undefined
```

--------------------------------

### Type-Safe API Wrapper for Server Tools

Source: https://docs.skybridge.tech/api-reference/infer-utility-types

An example of a type-safe asynchronous function that wraps calls to server tools. It uses ToolNames, ToolInput, and ToolOutput to ensure type correctness for tool names and their associated data.

```typescript
import type { ToolInput, ToolOutput, ToolNames } from "skybridge/web";
import type { AppType } from "../../server/src/index";

async function callServerTool<T extends ToolNames<AppType>>(
  name: T,
  input: ToolInput<AppType, T>
): Promise<ToolOutput<AppType, T>> {
  // Implementation
}

// Usage - fully typed
const result = await callServerTool("search-hotels", {
  city: "Paris",
  checkIn: "2025-01-01",
  checkOut: "2025-01-05",
});
// result is typed as SearchOutput
```

--------------------------------

### Type Safety with skybridge/web without Server

Source: https://docs.skybridge.tech/quickstart/add-to-existing-app/web

Demonstrates how to manually add type safety to skybridge/web hooks when not using skybridge/server. It defines an interface for tool input and uses it with `useToolInfo` to provide type inference for widget inputs.

```tsx
import { useToolInfo } from "skybridge/web";

interface MyToolInput {
  query: string;
  limit?: number;
}

const MyWidget: React.FC = () => {
  const toolInfo = useToolInfo<MyToolInput>();

  // toolInfo.input is now typed as MyToolInput
  console.log(toolInfo.input.query);

  return <div>Widget content</div>;
};

```

--------------------------------

### Upload and Download Files with Skybridge useFiles Hook (TypeScript)

Source: https://docs.skybridge.tech/fundamentals/apps-sdk

Demonstrates how to upload a file and retrieve its download URL using the `useFiles` hook from the 'skybridge/web' library. This function takes a File object as input and returns the fileId and downloadUrl. It's useful for integrating file management into web applications.

```tsx
import { useFiles } from "skybridge/web";

function Widget() {
  const { upload, getDownloadUrl } = useFiles();

  const handleUpload = async (event: React.ChangeEvent<HTMLInputElement>) => {
    if (event.target.files && event.target.files.length > 0) {
      const file = event.target.files[0];
      const { fileId } = await upload(file);
      const { downloadUrl } = await getDownloadUrl({ fileId });
      console.log("File uploaded successfully:", { fileId, downloadUrl });
      // Use downloadUrl to display or share the file...
    }
  };

  return <input type="file" onChange={handleUpload} />;
}
```
Tokens:
Raw