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

package/dist/server/server.js

@@ -1,27 +1,32 @@
 import crypto from "node:crypto";
 import { readFileSync } from "node:fs";
-import http from "node:http";
 import path from "node:path";
-import { McpServer as McpServerBase, } from "@modelcontextprotocol/server";
-import { mergeWith, union } from "es-toolkit";
-import express, {} from "express";
+import { isInputRequiredResult, 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 { setupOAuth } from "./auth/setup.js";
-import { createApp } from "./express.js";
+import { EventRegistry, } from "./events.js";
 import { hostFromUserAgent } from "./host.js";
-import { createMiddlewareEntry } from "./metric.js";
-import { buildMiddlewareChain, captureToolError, getHandlerMaps, } from "./middleware.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 mergeWithUnion = (target, source) => {
-    return mergeWith(target, source, (targetVal, sourceVal) => {
-        if (Array.isArray(targetVal) && Array.isArray(sourceVal)) {
-            return union(targetVal, sourceVal);
-        }
-    });
-};
+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
@@ -36,6 +41,12 @@ function normalizeForwardedPrefix(raw) {
     }
     return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
 }
+const fileEntrypointInput = {
+    file: z.object({
+        name: z.string().min(1),
+        resourceUri: z.string().trim().min(1),
+    }),
+};
 /**
  * Drop the query string from a `ui://` view URI, leaving the bare path. The
  * `?v=` cache key is the only query we append, so a plain split is enough and
@@ -64,35 +75,6 @@ export function normalizeContent(content) {
     return [content];
 }
 const McpServerBaseOmitted = McpServerBase;
-/**
- * The Skybridge server. Extends the MCP SDK's `McpServer` with a typed tool
- * registry, view resources, an embedded Express app, and protocol-level
- * middleware. Construct it with the same `Implementation` info you would pass
- * to the SDK, chain {@link McpServer.registerTool} calls to declare tools,
- * then call {@link McpServer.run} to start the HTTP server.
- *
- * The `TTools` generic accumulates each registered tool's input/output/meta
- * shape, so `typeof server` 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
- * const server = new McpServer({ name: "my-app", version: "1.0.0" }, {})
- *   .registerTool({
- *     name: "search",
- *     inputSchema: { query: z.string() },
- *     view: { component: "search" },
- *   }, async ({ query }) => ({ content: `Results for ${query}` }));
- *
- * await server.run();
- * export type AppType = typeof server;
- * ```
- *
- * @see https://docs.skybridge.tech/api-reference/mcp-server
- */
 // Side channel populated by `dist/__entry.js` before user code is imported.
 // Set at module scope rather than passed through the constructor because the
 // wrapper has the manifest before the user's `new McpServer(...)` runs, and
@@ -110,8 +92,12 @@ export function __setBuildManifest(manifest) {
     pendingBuildManifest = manifest;
 }
 let pendingSkillsManifest = null;
+let cachedDiskManifest = null;
+let discoveredSkills = null;
+let warnedOnMissingSkills = false;
 export function __setSkillsManifest(manifest) {
     pendingSkillsManifest = manifest;
+    discoveredSkills = null;
 }
 // Pure and `this`-free so it can run inside the `super(...)` call, before `this`
 // exists — the capability must be present for the `initialize` response.
@@ -130,27 +116,37 @@ function withSkillsCapability(options, skybridgeOptions) {
         },
     };
 }
+/**
+ * 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 class McpServer extends McpServerBaseOmitted {
-    /**
-     * 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.
-     */
-    express;
-    customErrorMiddleware = [];
-    mcpMiddlewareEntries = [];
-    mcpMiddlewareApplied = false;
-    middlewareEntriesCache = null;
-    registrations = [];
     claimedViews = new Map();
     viewMetaBuilders = new Map();
     /**
@@ -161,119 +157,65 @@ export class McpServer extends McpServerBaseOmitted {
      */
     viewUriByPath = new Map();
     viteManifest = null;
-    serverInfo;
-    serverOptions;
     oauthEnabled = false;
     resolveResourceMetadataUrl;
-    securitySchemesByTool = new Map();
+    toolSecuritySchemes = new Map();
+    userMiddlewareEntries = [];
+    eventRegistry;
     constructor(serverInfo, options, skybridgeOptions) {
-        const mergedOptions = withSkillsCapability(options, skybridgeOptions);
-        super(serverInfo, mergedOptions);
-        this.serverInfo = serverInfo;
-        this.serverOptions = mergedOptions;
-        this.express = express();
-        this.express.use(express.json(skybridgeOptions?.json));
-        if (skybridgeOptions?.oauth) {
-            this.oauthEnabled = true;
-            this.resolveResourceMetadataUrl = setupOAuth(this.express, skybridgeOptions.oauth, this.securitySchemesByTool);
-        }
+        super(serverInfo, withSkillsCapability(options, skybridgeOptions));
+        this.oauthEnabled = Boolean(skybridgeOptions?.oauth);
         // Pick up the manifest if `dist/__entry.js` primed it before importing
-        // user code. Consume-once: clear after the first construction so a
-        // subsequent test that doesn't prime can't inherit stale state.
-        // Explicit `setViteManifest` calls still win because they happen after
-        // construction.
+        // user code. Explicit `setViteManifest` calls still win because they
+        // happen after construction.
         if (pendingBuildManifest) {
             this.setViteManifest(pendingBuildManifest);
-            pendingBuildManifest = null;
         }
         this.setupSkills(Boolean(skybridgeOptions?.skills));
     }
-    registerResource(...args) {
-        return this.recordInherited("registerResource", args);
-    }
     /**
-     * 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.
+     * 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`.
+     *
+     * @internal
      */
-    registerPrompt(name, config, cb) {
-        return this.recordInherited("registerPrompt", [
-            name,
-            config,
-            cb,
-        ]);
-    }
-    recordInherited(method, args) {
-        const base = McpServerBase.prototype[method];
-        let registered;
-        this.record((target) => {
-            const result = base.apply(target, args);
-            if (target === this) {
-                registered = result;
-            }
-        });
-        return registered;
+    get securitySchemesByTool() {
+        return this.toolSecuritySchemes;
     }
-    skillRegistrar() {
-        const registerResource = this.registerResource.bind(this);
-        return {
-            registerResource,
-            server: {
-                setRequestHandler: ((...args) => {
-                    this.recordRequestHandler(...args);
-                }),
-            },
-        };
+    /**
+     * Inject the resolver the app uses to build the protected-resource metadata
+     * URL, so tool handlers can emit in-band auth challenges.
+     *
+     * @internal
+     */
+    setResourceMetadataUrlResolver(resolve) {
+        this.resolveResourceMetadataUrl = resolve;
+        return this;
     }
     setupSkills(enabled) {
-        const manifest = pendingSkillsManifest;
-        pendingSkillsManifest = null;
         if (!enabled) {
             return;
         }
-        const skills = manifest ?? discoverSkills(SKILLS_DIR);
-        if (skills.length === 0) {
+        discoveredSkills ??= pendingSkillsManifest ?? discoverSkills(SKILLS_DIR);
+        if (discoveredSkills.length === 0 && !warnedOnMissingSkills) {
+            warnedOnMissingSkills = true;
             console.warn(`skybridge: the "skills" option is enabled but no skills were found in "${SKILLS_DIR}". Add a <name>/SKILL.md there, or remove the option.`);
         }
-        registerSkills(this.skillRegistrar(), skills);
-    }
-    use(pathOrHandler, ...handlers) {
-        // Branching is load-bearing: Express's `app.use` overloads can't be
-        // resolved against a `string | RequestHandler` union, so we narrow.
-        if (typeof pathOrHandler === "string") {
-            this.express.use(pathOrHandler, ...handlers);
-        }
-        else {
-            this.express.use(pathOrHandler, ...handlers);
-        }
-        return this;
-    }
-    useOnError(pathOrHandler, ...handlers) {
-        if (typeof pathOrHandler === "string") {
-            this.customErrorMiddleware.push({ path: pathOrHandler, handlers });
-        }
-        else {
-            this.customErrorMiddleware.push({
-                handlers: [pathOrHandler, ...handlers],
-            });
-        }
-        return this;
+        registerSkills(this, discoveredSkills);
     }
     mcpMiddleware(filterOrHandler, 
     // biome-ignore lint/suspicious/noExplicitAny: overloads narrow the handler type at call sites; implementation must accept all variants
     maybeHandler) {
-        if (this.mcpMiddlewareApplied) {
-            throw new Error("Cannot register MCP middleware after run() or connect() has been called");
-        }
         const handler = maybeHandler;
         if (typeof filterOrHandler === "function") {
-            this.mcpMiddlewareEntries.push({
+            this.userMiddlewareEntries.push({
                 filter: null,
                 handler: filterOrHandler,
             });
         }
         else if (handler) {
-            this.mcpMiddlewareEntries.push({
+            this.userMiddlewareEntries.push({
                 filter: filterOrHandler,
                 handler,
             });
@@ -283,11 +225,15 @@ export class McpServer extends McpServerBaseOmitted {
         }
         return this;
     }
-    applyMcpMiddleware() {
-        if (this.mcpMiddlewareApplied) {
-            return;
-        }
-        this.mcpMiddlewareApplied = true;
+    /**
+     * 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}.
+     *
+     * @internal
+     */
+    protocolMiddlewareEntries() {
         // Surface view-resource _meta on `resources/list` (per ext-apps spec:
         // hosts/checkers read CSP & domain at list time before fetching content).
         const viewListMetaEntry = {
@@ -363,139 +309,12 @@ export class McpServer extends McpServerBaseOmitted {
                 return result;
             },
         };
-        const monitoringEntry = createMiddlewareEntry();
-        const entries = [
-            ...(monitoringEntry ? [monitoringEntry] : []),
+        return [
             viewListMetaEntry,
             viewReadResolveEntry,
             toolsListSecuritySchemesEntry,
-            ...this.mcpMiddlewareEntries,
+            ...this.userMiddlewareEntries,
         ];
-        this.middlewareEntriesCache = entries;
-        this.instrumentHandlers(this.server);
-    }
-    instrumentHandlers(server) {
-        const entries = this.middlewareEntriesCache ?? [];
-        const { requestHandlers, notificationHandlers } = getHandlerMaps(server);
-        const instrumentMap = (map, isNotification) => {
-            for (const [method, handler] of map) {
-                map.set(method, buildMiddlewareChain(method, isNotification, handler, entries));
-            }
-            const originalSet = map.set.bind(map);
-            map.set = (method, handler) => originalSet(method, buildMiddlewareChain(method, isNotification, handler, entries));
-        };
-        instrumentMap(requestHandlers, false);
-        instrumentMap(notificationHandlers, true);
-    }
-    /**
-     * 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.
-     */
-    async connect(transport) {
-        this.applyMcpMiddleware();
-        return McpServerBase.prototype.connect.call(this, transport);
-    }
-    /**
-     * 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() {
-        this.applyMcpMiddleware();
-        const fresh = new McpServerBase(this.serverInfo, this.serverOptions);
-        for (const apply of this.registrations) {
-            apply(fresh);
-        }
-        this.instrumentHandlers(fresh.server);
-        return fresh.server;
-    }
-    /**
-     * Apply an SDK registration to the singleton and remember it, so each
-     * per-request instance can be built with the same surface.
-     */
-    record(apply) {
-        this.registrations.push(apply);
-        apply(this);
-    }
-    /** Records a raw request handler (used for methods the SDK has no sugar for). */
-    recordRequestHandler(...args) {
-        this.record((target) => {
-            target.server.setRequestHandler(...args);
-        });
-    }
-    /**
-     * 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}.
-     *
-     * 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.
-     */
-    async run() {
-        this.applyMcpMiddleware();
-        if (process.env.VERCEL === "1") {
-            // createApp only reads httpServer inside its dev-only branch
-            // (viewsDevServer); under VERCEL=1 + NODE_ENV=production it's a
-            // bare object passed to satisfy the required parameter.
-            const httpServer = http.createServer();
-            await createApp({
-                mcpServer: this,
-                httpServer,
-                errorMiddleware: this.customErrorMiddleware,
-            });
-            return this.express;
-        }
-        const httpServer = http.createServer();
-        await createApp({
-            mcpServer: this,
-            httpServer,
-            errorMiddleware: this.customErrorMiddleware,
-        });
-        httpServer.on("request", this.express);
-        const port = parseInt(process.env.__PORT ?? "3000", 10);
-        await new Promise((resolve, reject) => {
-            httpServer.on("error", (error) => {
-                console.error("Failed to start server:", error);
-                reject(error);
-            });
-            httpServer.listen(port, () => {
-                resolve();
-            });
-        });
-        // On workerd, bridge the Node http server to a Workers fetch handler.
-        // The specifier is held in a variable to sidestep tsc's module resolution
-        // (`cloudflare:node` only exists under wrangler/workerd).
-        if (typeof navigator !== "undefined" &&
-            navigator.userAgent === "Cloudflare-Workers") {
-            const cloudflareNode = "cloudflare:node";
-            const { httpServerHandler } = await import(cloudflareNode);
-            return httpServerHandler({ port });
-        }
-        const shutdown = () => {
-            // Drop both handlers so a second signal falls through to Node's default
-            // (force-quit on a second Ctrl+C while drain is hanging).
-            process.off("SIGTERM", shutdown);
-            process.off("SIGINT", shutdown);
-            httpServer.close(() => process.exit(0));
-            // Force exit if connections don't drain in time so the port is still
-            // released promptly (e.g. for nodemon restarts).
-            setTimeout(() => process.exit(0), 3000).unref();
-        };
-        process.on("SIGTERM", shutdown);
-        process.on("SIGINT", shutdown);
-        return undefined;
     }
     enforceOneToolPerView(component, toolName) {
         const existingTool = this.claimedViews.get(component);
@@ -536,52 +355,32 @@ 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.
         const versionParam = this.computeViewVersionParam(view.component);
         const viewResource = {
-            hostType: "mcp-app",
             uri: `ui://views/ext-apps/${view.component}.html${versionParam}`,
             mimeType: "text/html;profile=mcp-app",
             buildContentMeta: ({ resourceDomains, connectDomains, domain, baseUriDomains }, overrides) => {
-                const defaults = {
-                    ui: {
-                        csp: {
-                            resourceDomains,
-                            connectDomains,
-                            baseUriDomains,
-                        },
-                        domain,
-                    },
-                };
-                const fromView = {
+                const ui = {
                     ui: {
                         ...(view.description && { description: view.description }),
                         ...(view.prefersBorder !== undefined && {
                             prefersBorder: view.prefersBorder,
                         }),
-                        ...(view.domain && { domain: view.domain }),
+                        domain: overrides.domain ?? view.domain ?? domain,
                         csp: {
-                            ...(view.csp?.resourceDomains && {
-                                resourceDomains: view.csp.resourceDomains,
-                            }),
-                            ...(view.csp?.connectDomains && {
-                                connectDomains: view.csp.connectDomains,
-                            }),
+                            resourceDomains: unionOf(resourceDomains, view.csp?.resourceDomains),
+                            connectDomains: unionOf(connectDomains, view.csp?.connectDomains),
+                            baseUriDomains: unionOf(baseUriDomains, view.csp?.baseUriDomains),
                             ...(view.csp?.frameDomains && {
                                 frameDomains: view.csp.frameDomains,
                             }),
-                            ...(view.csp?.baseUriDomains && {
-                                baseUriDomains: view.csp.baseUriDomains,
-                            }),
                         },
                     },
                 };
-                const ui = mergeWithUnion(mergeWithUnion(defaults, fromView), {
-                    ui: overrides,
-                });
                 const base = {
                     ...ui,
                     ...(view.description && {
@@ -591,10 +390,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 });
@@ -607,7 +408,7 @@ export class McpServer extends McpServerBaseOmitted {
         toolMeta.ui = { ...toolMeta.ui, resourceUri: viewResource.uri };
     }
     registerViewResource({ name, viewResource, view, }) {
-        const { hostType, uri: viewUri, mimeType, buildContentMeta } = viewResource;
+        const { uri: viewUri, mimeType, buildContentMeta } = viewResource;
         const buildMeta = (extra) => {
             const { serverUrl, connectDomains, contentMetaOverrides } = this.resolveViewRequestContext(extra);
             return buildContentMeta({
@@ -629,13 +430,11 @@ export class McpServer extends McpServerBaseOmitted {
             const viewBase = `${serverUrl}${assetsBasePath}`;
             const html = isProduction
                 ? templateHelper.renderProduction({
-                    hostType,
                     serverUrl: viewBase,
                     viewFile: this.lookupViewFile(view.component),
                     styleFile: this.lookupDistFile("style.css") ?? "",
                 })
                 : templateHelper.renderDevelopment({
-                    hostType,
                     serverUrl: viewBase,
                     viewName: view.component,
                 });
@@ -668,6 +467,9 @@ export class McpServer extends McpServerBaseOmitted {
                 captureToolError(extra, error);
                 throw error;
             }
+            if (isInputRequiredResult(result)) {
+                return result;
+            }
             warnOnLargeToolOutput(result, toolName);
             return {
                 ...result,
@@ -728,13 +530,219 @@ export class McpServer extends McpServerBaseOmitted {
         if (this.viteManifest) {
             return this.viteManifest;
         }
-        return JSON.parse(readFileSync(path.join(process.cwd(), "dist", "assets", ".vite", "manifest.json"), "utf-8"));
+        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 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(config, cb) {
+        const { extensions, openai, ...toolConfig } = config;
+        return this.registerTool({
+            ...toolConfig,
+            inputSchema: fileEntrypointInput,
+            openai: { ...openai, entrypoints: [{ type: "file", extensions }] },
+        }, cb);
+    }
+    /**
+     * 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;
+    }
+    /**
+     * 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(config) {
+        const { fields, layout, readTool = "settings.read", updateTool = "settings.update", } = config;
+        const values = z
+            .strictObject(Object.fromEntries(Object.entries(fields).map(([name, { schema, title, description }]) => [
+            name,
+            schema.meta({
+                title,
+                ...(description !== undefined && { description }),
+            }),
+        ])))
+            .required();
+        const { $schema: _, ...schema } = z.toJSONSchema(values);
+        for (const [name, property] of Object.entries(schema.properties ?? {})) {
+            if (fields[name]?.schema.safeParse(undefined).data !== undefined) {
+                throw new Error(`Setting "${name}" declares a default: return current values from \`read\` instead.`);
+            }
+            if (typeof property === "boolean" ||
+                !["boolean", "string", "number", "integer"].includes(String(property.type)) ||
+                (property.enum !== undefined && property.type !== "string")) {
+                throw new Error(`Setting "${name}" must be a boolean, string, string enum, number or integer.`);
+            }
+        }
+        const placed = new Set();
+        for (const group of layout ?? []) {
+            for (const item of group.items) {
+                if (item.kind !== "property") {
+                    continue;
+                }
+                if (!Object.hasOwn(fields, item.property) ||
+                    placed.has(item.property)) {
+                    throw new Error(`Settings layout names an unknown or duplicate field "${item.property}".`);
+                }
+                placed.add(item.property);
+            }
+        }
+        this.registerTool({
+            name: readTool,
+            description: "Read the app settings.",
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            inputSchema: {},
+            outputSchema: {
+                schema: z.record(z.string(), z.unknown()),
+                values,
+                layout: z.array(z.record(z.string(), z.unknown())).optional(),
+            },
+        }, async (_args, extra) => ({
+            content: [],
+            structuredContent: {
+                schema,
+                values: values.parse(await config.read(extra)),
+                layout,
+            },
+        }));
+        this.registerTool({
+            name: updateTool,
+            description: "Update the app settings.",
+            annotations: {
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+            inputSchema: {
+                set: values
+                    .partial()
+                    .refine((set) => Object.keys(set).length > 0)
+                    .meta({ minProperties: 1 }),
+            },
+            outputSchema: { values },
+        }, async ({ set }, extra) => ({
+            content: [],
+            structuredContent: {
+                values: values.parse(await config.update(set, extra)),
+            },
+        }));
+        const capability = { readTool, updateTool };
+        this.server.registerCapabilities({
+            extensions: { "openai/settings": capability },
+            experimental: { "openai/settings": capability },
+        });
+        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 &&
@@ -745,29 +753,46 @@ export class McpServer extends McpServerBaseOmitted {
         const securitySchemes = rawSecuritySchemes ??
             (auth && this.oauthEnabled ? authToSecuritySchemes(auth) : undefined);
         const toolMeta = { ...userToolMeta };
-        this.securitySchemesByTool.set(name, securitySchemes);
+        this.toolSecuritySchemes.set(name, securitySchemes);
         if (securitySchemes) {
             // SEP-1488 puts `securitySchemes` at the top level of the tool
             // 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),
             securitySchemes,
             toolName: name,
         });
-        this.record((target) => {
-            baseFn.call(target, name, { ...toolFields, _meta: toolMeta }, toolFields.inputSchema === undefined
-                ? (extra) => wrappedCb({}, extra)
-                : wrappedCb);
-        });
+        baseFn.call(this, name, { ...toolFields, _meta: toolMeta }, toolFields.inputSchema === undefined
+            ? (extra) => wrappedCb({}, extra)
+            : wrappedCb);
         return this;
     }
 }