skybridge 0.0.0-dev.81fd90a → 0.0.0-dev.8226541

package/dist/server/server.d.ts

@@ -1,10 +1,11 @@
 import type { McpUiToolMeta } from "@modelcontextprotocol/ext-apps";
-import { type CacheHint, type ContentBlock, type Icon, type Implementation, McpServer as McpServerBase, type PromptCallback, type ReadResourceCallback, type ReadResourceTemplateCallback, type RegisteredPrompt, type RegisteredResource, type RegisteredResourceTemplate, type RequestMeta, type ResourceMetadata, type ResourceTemplate, type Server as SdkServer, type ServerOptions, type ServerResult, type StandardSchemaV1, type StandardSchemaWithJSON, type ToolAnnotations } from "@modelcontextprotocol/server";
-import express, { type ErrorRequestHandler, type Express, type RequestHandler } from "express";
-import type { InferSchemaOutput, RawInputShape } from "../standard-schema.js";
-import type { OAuthConfig } from "./auth/index.js";
+import { type ContentBlock, type Icon, type Implementation, type InputRequiredResult, 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 { z } from "zod/v4";
+import type { ResourceMetadataUrlResolver } from "./auth/setup.js";
 import type { ExtraClaims } from "./auth.js";
-import type { McpExtra, McpExtraFor, McpMethodString, McpMiddlewareFilter, McpMiddlewareFn, McpResultFor, McpTypedMiddlewareFn, McpWildcard } from "./middleware.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";
 /**
  * Type marker for a registered tool — carries its input, output, and response
@@ -18,12 +19,6 @@ export type ToolDef<TInput = unknown, TOutput = unknown, TResponseMetadata = unk
     output: TOutput;
     responseMetadata: TResponseMetadata;
 };
-/**
- * The runtime a served view page declares on `window.skybridge`. Every view
- * emits a single ext-apps resource, so this is always `"mcp-app"`; the Apps
- * SDK runtime is detected at load time via `window.openai` instead.
- */
-export type ViewHostType = "mcp-app";
 /**
  * Content Security Policy origins attached to a view's resource. Each list is
  * passed through to the host's CSP for the view iframe; omit a field to inherit
@@ -34,7 +29,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[];
@@ -82,6 +77,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
@@ -102,17 +156,13 @@ export type ToolAuth = {
  */
 export type JsonOptions = NonNullable<Parameters<typeof express.json>[0]>;
 /**
- * Skybridge-specific server options, passed as the third `McpServer` constructor
- * argument.
- *
- * @typeParam TAuthExtra - Claims the `oauth` verifier populates. Inferred from
- * the config a provider returns, and carried on to tool handlers.
+ * The Skybridge-specific options an {@link McpServer} is built with. A
+ * {@link Skybridge} app derives them from its config; pass them directly only
+ * when constructing an `McpServer` by hand.
  */
-export interface SkybridgeServerOptions<TAuthExtra extends ExtraClaims = ExtraClaims> {
-    /** Options for the built-in `express.json()` middleware, e.g. `{ limit: "10mb" }`. */
-    json?: JsonOptions;
-    /** Resource-server OAuth config. When set, mounts well-known metadata and bearer auth on `/mcp`. */
-    oauth?: OAuthConfig<TAuthExtra>;
+export interface SkybridgeServerOptions {
+    /** Whether an OAuth provider guards `/mcp`; enables per-tool scheme enforcement. */
+    oauth?: boolean;
     /**
      * @experimental Serve Agent Skills from `src/skills` over MCP (SEP-2640).
      * API may change.
@@ -123,16 +173,16 @@ export interface SkybridgeServerOptions<TAuthExtra extends ExtraClaims = ExtraCl
  * 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">;
@@ -161,10 +211,10 @@ export interface McpServerTypes<TTools extends Record<string, ToolDef>> {
 type Simplify<T> = {
     [K in keyof T]: T[K];
 };
-type ShapeOutput<Shape extends RawInputShape> = Simplify<{
-    [K in keyof Shape as undefined extends InferSchemaOutput<Shape[K]> ? never : K]: InferSchemaOutput<Shape[K]>;
+type ShapeOutput<Shape extends Record<string, StandardSchemaWithJSON>> = Simplify<{
+    [K in keyof Shape as undefined extends StandardSchemaV1.InferOutput<Shape[K]> ? never : K]: StandardSchemaV1.InferOutput<Shape[K]>;
 } & {
-    [K in keyof Shape as undefined extends InferSchemaOutput<Shape[K]> ? K : never]?: InferSchemaOutput<Shape[K]>;
+    [K in keyof Shape as undefined extends StandardSchemaV1.InferOutput<Shape[K]> ? K : never]?: StandardSchemaV1.InferOutput<Shape[K]>;
 }>;
 type ExtractStructuredContent<T> = T extends {
     structuredContent: infer SC;
@@ -176,17 +226,25 @@ type ExtractMeta<T> = [Extract<T, {
 }> extends {
     _meta: infer M;
 } ? Simplify<M> : unknown;
-type AddTool<TTools, TName extends string, TInput extends RawInputShape, TOutput, TResponseMetadata = unknown, TAuthExtra extends ExtraClaims = ExtraClaims> = McpServer<TTools & {
+type AddTool<TTools, TName extends string, TInput extends Record<string, StandardSchemaWithJSON>, TOutput, TResponseMetadata = unknown, TAuthExtra extends ExtraClaims = ExtraClaims> = McpServer<TTools & {
     [K in TName]: ToolDef<ShapeOutput<TInput>, TOutput, TResponseMetadata>;
 }, TAuthExtra>;
-interface ToolConfigBase<TInput extends RawInputShape | StandardSchemaV1> {
+interface ToolConfigBase<TInput extends Record<string, StandardSchemaWithJSON> | StandardSchemaWithJSON> {
     name: string;
     title?: string;
     description?: string;
     inputSchema?: TInput;
-    outputSchema?: RawInputShape | StandardSchemaV1;
+    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;
 }
 /**
@@ -207,12 +265,28 @@ type ToolAuthConfig = {
      */
     securitySchemes?: SecurityScheme[];
 };
-type ToolConfig<TInput extends RawInputShape | StandardSchemaV1> = ToolConfigBase<TInput> & ToolAuthConfig;
+type ToolConfig<TInput extends Record<string, StandardSchemaWithJSON> | StandardSchemaWithJSON> = ToolConfigBase<TInput> & ToolAuthConfig;
+declare const fileEntrypointInput: {
+    file: z.ZodObject<{
+        name: z.ZodString;
+        resourceUri: z.ZodString;
+    }, z.core.$strip>;
+};
+type FileEntrypointInput = typeof fileEntrypointInput;
+/** A ChatGPT file viewer, registered with `server.registerFileViewer`. */
+export type OpenAIFileViewerConfig<TName extends string = string> = Omit<ToolConfigBase<FileEntrypointInput>, "inputSchema" | "openai" | "view"> & ToolAuthConfig & {
+    name: TName;
+    /** File extensions the viewer opens, each starting with `.`. */
+    extensions: string[];
+    view: ViewConfig;
+    /** Display modes. The file entrypoint is set from `extensions`. */
+    openai?: Omit<OpenAIToolConfig, "entrypoints">;
+};
 /**
  * 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"`). */
@@ -236,17 +310,77 @@ 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;
     };
 };
-type ToolHandler<TInput extends RawInputShape, TReturn extends {
+/** 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[];
+    };
+}
+/** One setting, registered with `server.registerSettings`. */
+export interface OpenAISettingsField {
+    /** A boolean, string, string enum, number or integer schema, without a default. */
+    schema: z.ZodType<boolean | string | number>;
+    title: string;
+    description?: string;
+}
+/** Values of every setting, keyed by field name. */
+export type OpenAISettingsValues<TFields extends Record<string, OpenAISettingsField>> = {
+    [K in keyof TFields]-?: Exclude<z.output<TFields[K]["schema"]>, undefined>;
+};
+/** App settings in ChatGPT, registered with `server.registerSettings`. */
+export interface OpenAISettingsConfig<TFields extends Record<string, OpenAISettingsField>, TAuthExtra extends ExtraClaims = ExtraClaims> {
+    fields: TFields;
+    /** Sections of the settings page. Fields left out appear under "Other settings". */
+    layout?: {
+        kind: "group";
+        title: string;
+        items: ({
+            kind: "property";
+            property: Extract<keyof TFields, string>;
+        } | {
+            kind: "tool";
+            tool: string;
+            title: string;
+            description?: string;
+        })[];
+    }[];
+    /** Returns the current value of every field. */
+    read: (extra: ToolHandlerExtra<TAuthExtra>) => OpenAISettingsValues<TFields> | Promise<OpenAISettingsValues<TFields>>;
+    /** Saves the changed fields and returns the value of every field. */
+    update: (set: Partial<OpenAISettingsValues<TFields>>, extra: ToolHandlerExtra<TAuthExtra>) => OpenAISettingsValues<TFields> | Promise<OpenAISettingsValues<TFields>>;
+    /** Name of the read tool. Defaults to `settings.read`. */
+    readTool?: string;
+    /** Name of the update tool. Defaults to `settings.update`. */
+    updateTool?: string;
+}
+type ToolHandler<TInput extends Record<string, StandardSchemaWithJSON>, TReturn extends {
     content?: HandlerContent;
 } = {
     content?: HandlerContent;
-}, TAuthExtra extends ExtraClaims = ExtraClaims> = (args: ShapeOutput<TInput>, extra: ToolHandlerExtra<TAuthExtra>) => TReturn | Promise<TReturn>;
+}, TAuthExtra extends ExtraClaims = ExtraClaims> = (args: ShapeOutput<TInput>, extra: ToolHandlerExtra<TAuthExtra>) => TReturn | InputRequiredResult | Promise<TReturn | InputRequiredResult>;
 /**
  * Coerce a tool handler's return value into an MCP `content` array. Strings
  * become a single `TextContent`; a single block is wrapped in an array;
@@ -254,7 +388,7 @@ type ToolHandler<TInput extends RawInputShape, TReturn extends {
  * who build content lazily can apply the same normalization.
  */
 export declare function normalizeContent(content: HandlerContent | undefined): ContentBlock[];
-interface McpServerBaseOmitted extends Omit<McpServerBase, "registerTool" | "registerResource" | "registerPrompt" | "connect"> {
+interface McpServerBaseOmitted extends Omit<McpServerBase, "registerTool" | "connect"> {
 }
 declare const McpServerBaseOmitted: new (...args: ConstructorParameters<typeof McpServerBase>) => McpServerBaseOmitted;
 /**
@@ -268,28 +402,38 @@ export declare function __setBuildManifest(manifest: Record<string, {
     file: string;
 }>): void;
 export declare function __setSkillsManifest(manifest: SkillsManifest): void;
+/**
+ * Typed registration sugar over the MCP SDK's `McpServer`: a tool registry
+ * that carries input/output/meta shapes, view resources, per-tool security
+ * schemes, and prompt/resource registration. A {@link Skybridge} app builds
+ * one of these per request and hands it to your `handler`; chain
+ * {@link McpServer.registerTool} calls on it and return the result.
+ *
+ * The `TTools` generic accumulates each registered tool's input/output/meta
+ * shape, so `typeof app` carries enough information for view-side helpers
+ * like {@link generateHelpers} to produce fully-typed hooks.
+ *
+ * @typeParam TTools - Accumulated tool registry. Filled in by `registerTool`
+ * chaining; you almost never set this manually.
+ *
+ * @example
+ * ```ts
+ * export const app = new Skybridge({
+ *   name: "my-app",
+ *   version: "1.0.0",
+ *   handler: (server) =>
+ *     server.registerTool({
+ *       name: "search",
+ *       inputSchema: { query: z.string() },
+ *       view: { component: "search" },
+ *     }, async ({ query }) => ({ content: `Results for ${query}` })),
+ * });
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/mcp-server
+ */
 export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>, TAuthExtra extends ExtraClaims = ExtraClaims> extends McpServerBaseOmitted {
     readonly $types: McpServerTypes<TTools>;
-    /**
-     * The underlying Express app. Use this to extend the HTTP server with
-     * custom routes, middleware, or settings — e.g.
-     * `server.express.get("/health", ...)`.
-     *
-     * `express.json()` is pre-applied — tune it via the constructor's third
-     * argument, e.g. `new McpServer(info, {}, { json: { limit: "10mb" } })`.
-     * Register your handlers before `run()`;
-     * after `run()`, dev-mode middleware, the `/mcp` route, and the default
-     * error handler are appended in that order.
-     *
-     * Note: Alpic Cloud only routes traffic to `/mcp` — custom routes work
-     * locally and on self-hosted deployments.
-     */
-    readonly express: Express;
-    private customErrorMiddleware;
-    private mcpMiddlewareEntries;
-    private mcpMiddlewareApplied;
-    private middlewareEntriesCache;
-    private readonly registrations;
     private claimedViews;
     private viewMetaBuilders;
     /**
@@ -300,63 +444,28 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
      */
     private viewUriByPath;
     private viteManifest;
-    private readonly serverInfo;
-    private readonly serverOptions?;
     private oauthEnabled;
     private resolveResourceMetadataUrl?;
-    private securitySchemesByTool;
-    constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions<TAuthExtra>);
-    /**
-     * Register a resource, recorded so every per-request instance carries it.
-     * Signature owned by Skybridge (not inherited) so a typed wrapper can land
-     * in a minor without a type-level break.
-     */
-    registerResource(name: string, uri: string, config: ResourceMetadata & {
-        cacheHint?: CacheHint;
-    }, readCallback: ReadResourceCallback): RegisteredResource;
-    registerResource(name: string, template: ResourceTemplate, config: ResourceMetadata & {
-        cacheHint?: CacheHint;
-    }, readCallback: ReadResourceTemplateCallback): RegisteredResourceTemplate;
-    /**
-     * Register a prompt, recorded so every per-request instance carries it.
-     * Signature owned by Skybridge (not inherited) so a typed wrapper can land
-     * in a minor without a type-level break.
-     */
-    registerPrompt<Args extends StandardSchemaWithJSON>(name: string, config: {
-        title?: string;
-        description?: string;
-        argsSchema?: Args;
-        icons?: Icon[];
-        _meta?: Record<string, unknown>;
-    }, cb: PromptCallback<Args>): RegisteredPrompt;
-    private recordInherited;
-    private skillRegistrar;
-    private setupSkills;
+    private readonly toolSecuritySchemes;
+    private readonly userMiddlewareEntries;
+    private eventRegistry?;
+    constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions);
     /**
-     * Register Express middleware on the underlying app. Mirrors `app.use` —
-     * pass handlers directly or a path-prefixed handler list. Register before
-     * {@link McpServer.run}; ordering matches Express.
+     * The per-tool security schemes collected during registration, keyed by tool
+     * name. Read by the OAuth layer to decide whether anonymous requests are
+     * allowed and which schemes gate a given `tools/call`.
      *
-     * Note: Alpic Cloud only routes traffic to `/mcp`. Custom paths work
-     * locally and on self-hosted deployments.
+     * @internal
      */
-    use(...handlers: RequestHandler[]): this;
-    use(path: string, ...handlers: RequestHandler[]): this;
+    get securitySchemesByTool(): ReadonlyMap<string, SecurityScheme[] | undefined>;
     /**
-     * Register Express error-handling middleware to run after the built-in
-     * `/mcp` route (or your custom route). Use this to log or transform errors
-     * thrown by tool handlers before the default error handler responds.
+     * Inject the resolver the app uses to build the protected-resource metadata
+     * URL, so tool handlers can emit in-band auth challenges.
      *
-     * @example
-     * ```ts
-     * server.useOnError((err, _req, _res, next) => {
-     *   logger.error(err);
-     *   next(err);
-     * });
-     * ```
+     * @internal
      */
-    useOnError(...handlers: ErrorRequestHandler[]): this;
-    useOnError(path: string, ...handlers: ErrorRequestHandler[]): this;
+    setResourceMetadataUrlResolver(resolve: ResourceMetadataUrlResolver): this;
+    private setupSkills;
     /** Register MCP protocol-level middleware (catch-all). */
     mcpMiddleware(handler: McpMiddlewareFn<TAuthExtra>): this;
     /** Register MCP protocol-level middleware for all requests (`extra` is `McpExtra`). */
@@ -388,49 +497,15 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
      * category (`"request"` | `"notification"`), or an array of those.
      */
     mcpMiddleware(filter: McpMiddlewareFilter, handler: McpMiddlewareFn<TAuthExtra>): this;
-    private applyMcpMiddleware;
-    private instrumentHandlers;
-    /**
-     * Connect to an MCP transport (override of the SDK's `connect`). Use this
-     * when you're embedding Skybridge in a host that already manages its own
-     * transport (e.g. stdio for desktop apps); for HTTP, prefer {@link McpServer.run}
-     * which sets the transport up for you. Locks in any middleware registered
-     * via {@link McpServer.mcpMiddleware} — further calls to that method will
-     * throw afterwards.
-     */
-    connect(transport: Parameters<typeof McpServerBase.prototype.connect>[0]): Promise<void>;
-    /**
-     * Build a fresh server for one stateless HTTP request, as
-     * `createMcpHandler`'s factory contract requires: every registration is
-     * replayed onto the new instance so the SDK's handler closures belong to
-     * the instance whose protocol era it stamps. Sharing the singleton's
-     * handler maps instead would bind them to an instance that is never
-     * marked, pinning every request to the 2025 codec and letting concurrent
-     * callers overwrite each other's negotiated version.
-     */
-    createStatelessServerInstance(): SdkServer;
-    /**
-     * Apply an SDK registration to the singleton and remember it, so each
-     * per-request instance can be built with the same surface.
-     */
-    private record;
-    /** Records a raw request handler (used for methods the SDK has no sugar for). */
-    private recordRequestHandler;
     /**
-     * Start the HTTP server. Listens on `process.env.__PORT` (default `3000`),
-     * mounts the `/mcp` route, applies any custom Express middleware registered
-     * via {@link McpServer.use} / {@link McpServer.useOnError}, and locks in
-     * any MCP middleware registered via {@link McpServer.mcpMiddleware}.
+     * This instance's protocol-level middleware: the framework's own entries
+     * (view `_meta` on `resources/list`, version-agnostic view resolution on
+     * `resources/read`, the top-level `securitySchemes` mirror on `tools/list`)
+     * followed by the ones registered via {@link McpServer.mcpMiddleware}.
      *
-     * On Cloudflare Workers / workerd, returns an object exposing `fetch` so
-     * the runtime can bridge incoming requests to the Node HTTP server. On
-     * Vercel (`VERCEL === "1"`), returns the Express app directly so the
-     * serverless function entry can call it as a `(req, res)` handler. On
-     * Node, returns `undefined` once listening.
+     * @internal
      */
-    run(): Promise<{
-        fetch: (...args: unknown[]) => unknown;
-    } | Express | undefined>;
+    protocolMiddlewareEntries(): McpMiddlewareEntry[];
     private enforceOneToolPerView;
     private resolveViewRequestContext;
     private registerViewResources;
@@ -450,6 +525,104 @@ 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 a ChatGPT file viewer, from the OpenAI MCP extensions: a tool
+     * with a file entrypoint for `extensions` and a view. ChatGPT desktop calls
+     * it with the file the user opened, as `{ file: { name, resourceUri } }`.
+     * Read and save the file from the view with `useFileResource`.
+     *
+     * @example
+     * ```ts
+     * server.registerFileViewer(
+     *   {
+     *     name: "part-viewer",
+     *     title: "Part Viewer",
+     *     extensions: [".stl", ".step"],
+     *     view: { component: "part-viewer" },
+     *   },
+     *   async ({ file }) => ({ structuredContent: { name: file.name } }),
+     * );
+     * ```
+     *
+     * @see https://docs.skybridge.tech/api-reference/register-file-viewer
+     */
+    registerFileViewer<TName extends string, TReturn extends {
+        content?: HandlerContent;
+    }>(config: OpenAIFileViewerConfig<TName>, cb: ToolHandler<FileEntrypointInput, TReturn, TAuthExtra>): AddTool<TTools, TName, FileEntrypointInput, ExtractStructuredContent<TReturn>, ExtractMeta<TReturn>, TAuthExtra>;
+    /**
+     * 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 app settings for ChatGPT, from the OpenAI MCP extensions.
+     * Skybridge registers a read tool and an update tool from `fields`, and
+     * advertises them in the `openai/settings` server capability. ChatGPT shows
+     * the settings page and calls `update` with the changed fields only. Store
+     * the values yourself, for example per user.
+     *
+     * @example
+     * ```ts
+     * server.registerSettings({
+     *   fields: {
+     *     units: { title: "Units", schema: z.enum(["mm", "in"]) },
+     *     showGrid: { title: "Show grid", schema: z.boolean() },
+     *   },
+     *   read: (extra) => loadSettings(extra),
+     *   update: (set, extra) => saveSettings(set, extra),
+     * });
+     * ```
+     *
+     * @see https://docs.skybridge.tech/api-reference/register-settings
+     */
+    registerSettings<TFields extends Record<string, OpenAISettingsField>>(config: OpenAISettingsConfig<TFields, TAuthExtra>): this;
     /**
      * Register a tool. Pass a `config` describing the tool (name, schemas,
      * optional {@link ViewConfig}, optional {@link ToolMeta}) and a handler that
@@ -479,12 +652,12 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
      *
      * @see https://docs.skybridge.tech/api-reference/register-tool
      */
-    registerTool<TName extends string, InputArgs extends RawInputShape, TReturn extends {
+    registerTool<TName extends string, InputArgs extends Record<string, StandardSchemaWithJSON>, TReturn extends {
         content?: HandlerContent;
     }>(config: ToolConfig<InputArgs> & {
         name: TName;
     }, cb: ToolHandler<InputArgs, TReturn, TAuthExtra>): AddTool<TTools, TName, InputArgs, ExtractStructuredContent<TReturn>, ExtractMeta<TReturn>, TAuthExtra>;
-    registerTool<InputArgs extends RawInputShape>(config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs, {
+    registerTool<InputArgs extends Record<string, StandardSchemaWithJSON>>(config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs, {
         content?: HandlerContent;
     }, TAuthExtra>): this;
 }