skybridge 0.0.0-dev.a05e8da → 0.0.0-dev.a08278b

package/dist/server/server.d.ts

@@ -1,8 +1,9 @@
 import type { McpUiToolMeta } from "@modelcontextprotocol/ext-apps";
-import { type ContentBlock, type Implementation, McpServer as McpServerBase, type RequestMeta, type ServerOptions, type ServerResult, type StandardSchemaV1, type StandardSchemaWithJSON, type ToolAnnotations } from "@modelcontextprotocol/server";
+import { type ContentBlock, type Icon, type Implementation, McpServer as McpServerBase, type RequestMeta, type ResourceLink, type ServerOptions, type ServerResult, type StandardSchemaV1, type StandardSchemaWithJSON, type ToolAnnotations } from "@modelcontextprotocol/server";
 import type express from "express";
 import type { ResourceMetadataUrlResolver } from "./auth/setup.js";
 import type { ExtraClaims } from "./auth.js";
+import { type EventConfig, type EventHooks, type InferEventSchema } from "./events.js";
 import type { McpExtra, McpExtraFor, McpMethodString, McpMiddlewareEntry, McpMiddlewareFilter, McpMiddlewareFn, McpResultFor, McpTypedMiddlewareFn, McpWildcard } from "./middleware.js";
 import { type SkillsManifest } from "./skills.js";
 /**
@@ -27,7 +28,7 @@ export interface ViewCsp {
     resourceDomains?: string[];
     /** Origins the view may contact via fetch/XHR. */
     connectDomains?: string[];
-    /** Origins allowed for iframe embeds (opts into stricter app review). */
+    /** Origins allowed for iframe embeds (opts into stricter plugin review). */
     frameDomains?: string[];
     /** Origins that can receive openExternal redirects without the safe-link modal. */
     redirectDomains?: string[];
@@ -75,6 +76,65 @@ export type SecurityScheme = {
     type: "oauth2";
     scopes?: string[];
 };
+/** A display mode ChatGPT can render a view in. ChatGPT doesn't support `pip`. */
+export type OpenAIDisplayMode = "inline" | "fullscreen";
+/** A sidebar shortcut that calls another tool of the same server. */
+export interface OpenAIQuickAction {
+    title: string;
+    icons: [Icon, ...Icon[]];
+    target: {
+        type: "tool";
+        name: string;
+        arguments?: Record<string, unknown>;
+    };
+}
+/**
+ * A place in ChatGPT where users can open the tool's view without the model.
+ *
+ * - `global`: an entry in the sidebar, opened fullscreen.
+ * - `thread`: a tab in a conversation's side panel.
+ * - `file`: a viewer for files with these extensions, such as `".stl"`.
+ *   ChatGPT calls the tool with `{ file: { name, resourceUri } }`.
+ * - `settings`: an entry in the plugin settings.
+ *
+ * ChatGPT calls the tool with `{}` for global and thread entrypoints, so the
+ * tool must not require any input.
+ */
+export type OpenAIEntrypoint = {
+    type: "global";
+    quickAction?: OpenAIQuickAction;
+} | {
+    type: "thread";
+} | {
+    type: "file";
+    extensions: string[];
+} | {
+    type: "settings";
+    searchTerms?: string[];
+};
+/**
+ * ChatGPT-only tool options, emitted as `_meta["openai/ui"]` on the tool and
+ * on its view resource. Every field is optional: ChatGPT applies the defaults
+ * of the OpenAI MCP extensions spec when one is omitted. Requires `view`.
+ *
+ * @see https://github.com/openai/mcp-extensions/blob/main/docs/spec.md
+ */
+export interface OpenAIToolConfig {
+    /** Places where users can open the view directly. */
+    entrypoints?: OpenAIEntrypoint[];
+    /**
+     * Display modes the view supports, read before the view loads. Defaults to
+     * `[preferredDisplayMode]` when that is set, otherwise to both modes.
+     */
+    availableDisplayModes?: OpenAIDisplayMode[];
+    /**
+     * Display mode the view prefers to open in. Setting it alone makes it the
+     * only available mode, so also set `availableDisplayModes` to keep the other.
+     */
+    preferredDisplayMode?: OpenAIDisplayMode;
+    /** Display mode the view opens in first when the model calls the tool. */
+    preferredModelDisplayMode?: OpenAIDisplayMode;
+}
 /**
  * Declarative per-tool auth. Enforced when the server has an `oauth` provider:
  * anonymous or under-scoped calls are rejected before the handler runs. Omit
@@ -112,16 +172,16 @@ export interface SkybridgeServerOptions {
  * Well-known keys recognized by host runtimes when set on a tool's `_meta`.
  * Use {@link ToolMeta} to also pass arbitrary custom metadata alongside these.
  *
- * @see https://developers.openai.com/apps-sdk/reference#tool-descriptor-parameters
+ * @see https://developers.openai.com/plugins/reference#tool-descriptor-parameters
  */
 export interface KnownToolMeta {
-    /** Apps SDK: allow the rendered view to call this tool from inside its iframe. */
+    /** ChatGPT: allow the rendered view to call this tool from inside its iframe. */
     "openai/widgetAccessible"?: boolean;
-    /** Apps SDK: status text shown while the tool is running (e.g. `"Searching trips"`). */
+    /** ChatGPT: status text shown while the tool is running (e.g. `"Searching trips"`). */
     "openai/toolInvocation/invoking"?: string;
-    /** Apps SDK: status text shown once the tool returns (e.g. `"Found 3 trips"`). */
+    /** ChatGPT: status text shown once the tool returns (e.g. `"Found 3 trips"`). */
     "openai/toolInvocation/invoked"?: string;
-    /** Apps SDK: input parameters that hold file references — the host attaches uploaded files to them. */
+    /** ChatGPT: input parameters that hold file references — the host attaches uploaded files to them. */
     "openai/fileParams"?: string[];
     /** MCP Apps: control whether the tool is exposed to the model, the app, or both. */
     ui?: Pick<McpUiToolMeta, "visibility">;
@@ -175,7 +235,15 @@ interface ToolConfigBase<TInput extends Record<string, StandardSchemaWithJSON> |
     inputSchema?: TInput;
     outputSchema?: Record<string, StandardSchemaWithJSON> | StandardSchemaWithJSON;
     annotations?: ToolAnnotations;
+    /**
+     * Icons for the tool, a standard MCP field. Hosts choose whether and where
+     * to show them. ChatGPT asks for them on every entrypoint tool, as a
+     * monochrome SVG on a 20x20 viewport that uses `currentColor`.
+     */
+    icons?: Icon[];
     view?: ViewConfig;
+    /** ChatGPT-only options. See {@link OpenAIToolConfig}. */
+    openai?: OpenAIToolConfig;
     _meta?: ToolMeta;
 }
 /**
@@ -199,9 +267,9 @@ type ToolAuthConfig = {
 type ToolConfig<TInput extends Record<string, StandardSchemaWithJSON> | StandardSchemaWithJSON> = ToolConfigBase<TInput> & ToolAuthConfig;
 /**
  * Optional client-supplied hints attached to `params._meta` on every tool call
- * by the Apps SDK host. Hints only: never use for authorization, and tolerate
+ * by the ChatGPT host. Hints only: never use for authorization, and tolerate
  * absence.
- * @see https://developers.openai.com/apps-sdk/reference#_meta-fields-the-client-provides
+ * @see https://developers.openai.com/plugins/reference#_meta-fields-the-client-provides
  */
 export interface ClientHintsMeta {
     /** Requested locale (BCP-47, e.g. `"en-US"`). */
@@ -225,12 +293,35 @@ export interface ClientHintsMeta {
     "openai/organization"?: string;
     /** Stable id for the currently mounted widget instance. */
     "openai/widgetSessionId"?: string;
+    /**
+     * Set by ChatGPT desktop on tool calls from a view opened through a file
+     * entrypoint. `path` is the absolute path of the opened file. Any MCP client
+     * can send this key: never use it for authorization, and resolve the path
+     * and keep it inside an allowed directory before touching the filesystem.
+     */
+    "openai/resource"?: {
+        path?: string;
+    };
 }
 type ToolHandlerExtra<TAuthExtra extends ExtraClaims = ExtraClaims> = Omit<McpExtra<TAuthExtra>, "mcpReq"> & {
     mcpReq: Omit<McpExtra<TAuthExtra>["mcpReq"], "_meta"> & {
         _meta?: RequestMeta & ClientHintsMeta;
     };
 };
+/** Composer at-mention search, registered with `server.registerMentions`. */
+export interface OpenAIMentionsConfig<TAuthExtra extends ExtraClaims = ExtraClaims> {
+    /** Name of the tool ChatGPT calls for each search. */
+    name: string;
+    description?: string;
+    /** Returns the items matching the typed text, which may be empty. */
+    handler: (params: {
+        query: string;
+    }, extra: ToolHandlerExtra<TAuthExtra>) => Promise<{
+        items: ResourceLink[];
+    }> | {
+        items: ResourceLink[];
+    };
+}
 type ToolHandler<TInput extends Record<string, StandardSchemaWithJSON>, TReturn extends {
     content?: HandlerContent;
 } = {
@@ -303,6 +394,7 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
     private resolveResourceMetadataUrl?;
     private readonly toolSecuritySchemes;
     private readonly userMiddlewareEntries;
+    private eventRegistry?;
     constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions);
     /**
      * The per-tool security schemes collected during registration, keyed by tool
@@ -379,6 +471,58 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
         file: string;
     }>): this;
     private readManifest;
+    /**
+     * @experimental Register an MCP Events type that hosts can subscribe to, per
+     * the Triggers & Events working group draft. Skybridge serves `events/list`,
+     * `events/subscribe` and `events/unsubscribe`, checks auth and arguments,
+     * verifies the callback URL, then hands each subscription to `onSubscribe`.
+     * Delivering the events is up to you, for example with {@link deliverEvent}.
+     * API may change.
+     *
+     * @example
+     * ```ts
+     * server.registerEvent(
+     *   {
+     *     name: "comment.created",
+     *     description: "Fires when someone comments on a document",
+     *     inputSchema: { documentId: z.string() },
+     *     payloadSchema: { documentId: z.string(), excerpt: z.string() },
+     *   },
+     *   {
+     *     onSubscribe: ({ documentId }, { subscription }) =>
+     *       webhooks.upsert({ ...subscription, filter: { documentId } }),
+     *     onUnsubscribe: (_args, { subscription }) =>
+     *       webhooks.remove(subscription.id),
+     *   },
+     * );
+     * ```
+     *
+     * @see https://docs.skybridge.tech/api-reference/register-event
+     */
+    registerEvent<TInput extends Record<string, StandardSchemaWithJSON> | StandardSchemaWithJSON = Record<never, StandardSchemaWithJSON>>(config: EventConfig<TInput>, hooks: EventHooks<InferEventSchema<TInput>, McpExtra<TAuthExtra>>): this;
+    /**
+     * Register the composer at-mention search for ChatGPT, from the OpenAI MCP
+     * extensions. When the user types `@` and your app name, ChatGPT calls
+     * `handler` with the typed text and lists the returned resource links.
+     * Skybridge registers it as a tool hidden from the model.
+     *
+     * @example
+     * ```ts
+     * server.registerMentions({
+     *   name: "search_parts",
+     *   handler: async ({ query }) => ({
+     *     items: findParts(query).map((part) => ({
+     *       type: "resource_link",
+     *       uri: `parts://${part.id}`,
+     *       name: part.name,
+     *     })),
+     *   }),
+     * });
+     * ```
+     *
+     * @see https://docs.skybridge.tech/api-reference/register-mentions
+     */
+    registerMentions(config: OpenAIMentionsConfig<TAuthExtra>): this;
     /**
      * Register a tool. Pass a `config` describing the tool (name, schemas,
      * optional {@link ViewConfig}, optional {@link ToolMeta}) and a handler that

package/dist/server/server.js

@@ -2,14 +2,31 @@ import crypto from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
 import { McpServer as McpServerBase, } from "@modelcontextprotocol/server";
+import { z } from "zod/v4";
 import { warnOnLargeToolOutput } from "../context-warnings.js";
 import { authToSecuritySchemes, evaluateSecuritySchemes, inBandChallengeResult, } from "./auth/security-schemes.js";
+import { EventRegistry, } from "./events.js";
 import { hostFromUserAgent } from "./host.js";
 import { captureToolError } from "./middleware.js";
 import { resolveServerOrigin } from "./requestOrigin.js";
 import { discoverSkills, registerSkills, SKILLS_EXTENSION_KEY, } from "./skills.js";
 import { templateHelper } from "./templateHelper.js";
 const unionOf = (base, extra) => extra ? [...new Set([...base, ...extra])] : base;
+function mergeOpenAIUi(meta, values) {
+    const defined = Object.fromEntries(Object.entries(values).filter(([, value]) => value !== undefined));
+    if (Object.keys(defined).length > 0) {
+        meta["openai/ui"] = { ...meta["openai/ui"], ...defined };
+    }
+}
+function acceptsEmptyInput(inputSchema) {
+    if (inputSchema === undefined) {
+        return true;
+    }
+    const checks = "~standard" in inputSchema
+        ? [inputSchema["~standard"].validate({})]
+        : Object.values(inputSchema).map((schema) => schema["~standard"].validate(undefined));
+    return checks.every((result) => result instanceof Promise || result.issues === undefined);
+}
 const SKILLS_DIR = "src/skills";
 /**
  * Normalize an `x-forwarded-prefix` value into a leading-slash, no-trailing-slash
@@ -138,6 +155,7 @@ export class McpServer extends McpServerBaseOmitted {
     resolveResourceMetadataUrl;
     toolSecuritySchemes = new Map();
     userMiddlewareEntries = [];
+    eventRegistry;
     constructor(serverInfo, options, skybridgeOptions) {
         super(serverInfo, withSkillsCapability(options, skybridgeOptions));
         this.oauthEnabled = Boolean(skybridgeOptions?.oauth);
@@ -331,7 +349,7 @@ export class McpServer extends McpServerBaseOmitted {
         }
         return { serverUrl, assetsBasePath, connectDomains, contentMetaOverrides };
     }
-    registerViewResources(toolName, view, toolMeta) {
+    registerViewResources(toolName, view, toolMeta, openai) {
         // Append a content-derived version param so hosts (e.g. ChatGPT) bust
         // their cache when the bundle changes, but keep the URI stable across
         // `tools/list` calls when the bundle hasn't changed.
@@ -366,10 +384,12 @@ export class McpServer extends McpServerBaseOmitted {
                         "openai/widgetCSP": { redirect_domains: view.csp.redirectDomains },
                     }),
                 };
-                if (view._meta) {
-                    return { ...base, ...view._meta };
-                }
-                return base;
+                const meta = { ...base, ...view._meta };
+                mergeOpenAIUi(meta, {
+                    availableDisplayModes: openai?.availableDisplayModes,
+                    preferredDisplayMode: openai?.preferredDisplayMode,
+                });
+                return meta;
             },
         };
         this.registerViewResource({ name: toolName, viewResource, view });
@@ -504,11 +524,85 @@ export class McpServer extends McpServerBaseOmitted {
         cachedDiskManifest ??= JSON.parse(readFileSync(path.join(process.cwd(), "dist", "assets", ".vite", "manifest.json"), "utf-8"));
         return cachedDiskManifest ?? {};
     }
+    /**
+     * @experimental Register an MCP Events type that hosts can subscribe to, per
+     * the Triggers & Events working group draft. Skybridge serves `events/list`,
+     * `events/subscribe` and `events/unsubscribe`, checks auth and arguments,
+     * verifies the callback URL, then hands each subscription to `onSubscribe`.
+     * Delivering the events is up to you, for example with {@link deliverEvent}.
+     * API may change.
+     *
+     * @example
+     * ```ts
+     * server.registerEvent(
+     *   {
+     *     name: "comment.created",
+     *     description: "Fires when someone comments on a document",
+     *     inputSchema: { documentId: z.string() },
+     *     payloadSchema: { documentId: z.string(), excerpt: z.string() },
+     *   },
+     *   {
+     *     onSubscribe: ({ documentId }, { subscription }) =>
+     *       webhooks.upsert({ ...subscription, filter: { documentId } }),
+     *     onUnsubscribe: (_args, { subscription }) =>
+     *       webhooks.remove(subscription.id),
+     *   },
+     * );
+     * ```
+     *
+     * @see https://docs.skybridge.tech/api-reference/register-event
+     */
+    registerEvent(config, hooks) {
+        if (!this.eventRegistry) {
+            this.server.registerCapabilities({ events: {} });
+            this.eventRegistry = new EventRegistry(this.server);
+        }
+        this.eventRegistry.add(config, hooks);
+        return this;
+    }
+    /**
+     * Register the composer at-mention search for ChatGPT, from the OpenAI MCP
+     * extensions. When the user types `@` and your app name, ChatGPT calls
+     * `handler` with the typed text and lists the returned resource links.
+     * Skybridge registers it as a tool hidden from the model.
+     *
+     * @example
+     * ```ts
+     * server.registerMentions({
+     *   name: "search_parts",
+     *   handler: async ({ query }) => ({
+     *     items: findParts(query).map((part) => ({
+     *       type: "resource_link",
+     *       uri: `parts://${part.id}`,
+     *       name: part.name,
+     *     })),
+     *   }),
+     * });
+     * ```
+     *
+     * @see https://docs.skybridge.tech/api-reference/register-mentions
+     */
+    registerMentions(config) {
+        this.registerTool({
+            name: config.name,
+            description: config.description ?? "Search items to mention.",
+            annotations: { readOnlyHint: true },
+            inputSchema: { query: z.string() },
+            _meta: {
+                "openai/extensions": { "mentions/search": {} },
+                ui: { visibility: ["app"] },
+            },
+        }, async ({ query }, extra) => ({
+            content: [],
+            structuredContent: await config.handler({ query }, extra),
+        }));
+        return this;
+    }
     registerTool(rawConfig, rawCb) {
         const baseFn = McpServerBase.prototype.registerTool;
         const config = rawConfig;
         const cb = rawCb;
-        const { name, view, auth, securitySchemes: rawSecuritySchemes, _meta: userToolMeta, ...toolFields } = config;
+        const { name, view, auth, securitySchemes: rawSecuritySchemes, openai, _meta: userToolMeta, ...toolFields } = config;
         const authNeedsProvider = auth !== undefined &&
             (!auth.allowsAnonymous || Boolean(auth.scopes?.length));
         if (rawSecuritySchemes === undefined &&
@@ -525,12 +619,31 @@ export class McpServer extends McpServerBaseOmitted {
             // descriptor, but the SDK's `registerTool` drops unknown top-level
             // fields, so the canonical spot isn't reachable without intercepting
             // `tools/list`. Use the `_meta` back-compat mirror documented in the
-            // Apps SDK reference until SEP-1488 lands in the spec.
+            // ChatGPT plugin reference until SEP-1488 lands in the spec.
             toolMeta.securitySchemes = securitySchemes;
         }
+        if (openai) {
+            if (!view) {
+                throw new Error(`skybridge: tool "${name}" sets \`openai\` options but has no \`view\`.`);
+            }
+            const opensWithoutInput = openai.entrypoints?.some(({ type }) => type === "global" || type === "thread");
+            if (opensWithoutInput && !acceptsEmptyInput(toolFields.inputSchema)) {
+                throw new Error(`skybridge: tool "${name}" has a global or thread entrypoint, so ChatGPT calls it with \`{}\`, but its input schema rejects \`{}\`. Make every input optional.`);
+            }
+            const badExtension = openai.entrypoints
+                ?.flatMap((entrypoint) => entrypoint.type === "file" ? entrypoint.extensions : [])
+                .find((extension) => !extension.startsWith("."));
+            if (badExtension !== undefined) {
+                throw new Error(`skybridge: tool "${name}" has a file entrypoint extension "${badExtension}" that doesn't start with ".".`);
+            }
+            mergeOpenAIUi(toolMeta, {
+                entrypoints: openai.entrypoints,
+                preferredModelDisplayMode: openai.preferredModelDisplayMode,
+            });
+        }
         if (view) {
             this.enforceOneToolPerView(view.component, name);
-            this.registerViewResources(name, view, toolMeta);
+            this.registerViewResources(name, view, toolMeta, openai);
         }
         const wrappedCb = this.decorateToolHandler(cb, {
             attachViewUUID: Boolean(view),