skybridge 0.0.0-dev.e9705ff → 0.0.0-dev.e99ee17

package/dist/server/server.js

@@ -0,0 +1,799 @@
+import crypto from "node:crypto";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+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 { 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
+ * path. Takes the first hop of a comma-separated proxy chain.
+ * "/v1/", "v1", "/v1, /internal" → "/v1"; "", "/", undefined → "".
+ */
+function normalizeForwardedPrefix(raw) {
+    const firstHop = raw?.split(",")[0]?.trim() ?? "";
+    const trimmed = firstHop.replace(/\/+$/, "");
+    if (trimmed === "") {
+        return "";
+    }
+    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
+ * sidesteps `URL` normalization quirks on the non-special `ui:` scheme.
+ */
+function stripQuery(uri) {
+    const queryIndex = uri.indexOf("?");
+    return queryIndex === -1 ? uri : uri.slice(0, queryIndex);
+}
+/**
+ * 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;
+ * `undefined` produces `[]`. Mostly used internally — exported so consumers
+ * who build content lazily can apply the same normalization.
+ */
+export function normalizeContent(content) {
+    if (content === undefined) {
+        return [];
+    }
+    if (typeof content === "string") {
+        return [{ type: "text", text: content }];
+    }
+    if (Array.isArray(content)) {
+        return content;
+    }
+    return [content];
+}
+const McpServerBaseOmitted = McpServerBase;
+// 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
+// threading it through every call site (including user templates) is exactly
+// the boilerplate this design is trying to hide.
+let pendingBuildManifest = null;
+/**
+ * Prime the build-time Vite manifest before user code constructs its
+ * `McpServer`. Called from the generated `dist/__entry.js`; not part of the
+ * user-facing API.
+ *
+ * @internal
+ */
+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.
+function withSkillsCapability(options, skybridgeOptions) {
+    if (!skybridgeOptions?.skills) {
+        return options;
+    }
+    return {
+        ...options,
+        capabilities: {
+            ...options?.capabilities,
+            extensions: {
+                ...options?.capabilities?.extensions,
+                [SKILLS_EXTENSION_KEY]: { directoryRead: true },
+            },
+        },
+    };
+}
+/**
+ * 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 {
+    claimedViews = new Map();
+    viewMetaBuilders = new Map();
+    /**
+     * Maps a view resource's query-less path to its canonical registered URI
+     * (the one carrying the `?v=` cache key). Lets `resources/read` resolve the
+     * underlying view no matter which version param the consumer sends, since
+     * the param is only a cache key, not part of the resource's identity.
+     */
+    viewUriByPath = new Map();
+    viteManifest = null;
+    oauthEnabled = false;
+    resolveResourceMetadataUrl;
+    toolSecuritySchemes = new Map();
+    userMiddlewareEntries = [];
+    eventRegistry;
+    constructor(serverInfo, options, skybridgeOptions) {
+        super(serverInfo, withSkillsCapability(options, skybridgeOptions));
+        this.oauthEnabled = Boolean(skybridgeOptions?.oauth);
+        // Pick up the manifest if `dist/__entry.js` primed it before importing
+        // user code. Explicit `setViteManifest` calls still win because they
+        // happen after construction.
+        if (pendingBuildManifest) {
+            this.setViteManifest(pendingBuildManifest);
+        }
+        this.setupSkills(Boolean(skybridgeOptions?.skills));
+    }
+    /**
+     * 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
+     */
+    get securitySchemesByTool() {
+        return this.toolSecuritySchemes;
+    }
+    /**
+     * 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) {
+        if (!enabled) {
+            return;
+        }
+        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, discoveredSkills);
+    }
+    mcpMiddleware(filterOrHandler, 
+    // biome-ignore lint/suspicious/noExplicitAny: overloads narrow the handler type at call sites; implementation must accept all variants
+    maybeHandler) {
+        const handler = maybeHandler;
+        if (typeof filterOrHandler === "function") {
+            this.userMiddlewareEntries.push({
+                filter: null,
+                handler: filterOrHandler,
+            });
+        }
+        else if (handler) {
+            this.userMiddlewareEntries.push({
+                filter: filterOrHandler,
+                handler,
+            });
+        }
+        else {
+            throw new Error("mcpMiddleware requires a handler function when a filter is provided");
+        }
+        return this;
+    }
+    /**
+     * 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 = {
+            filter: "resources/list",
+            handler: async (_req, extra, next) => {
+                const result = (await next());
+                for (const resource of result.resources) {
+                    const builder = this.viewMetaBuilders.get(resource.uri);
+                    if (!builder) {
+                        continue;
+                    }
+                    const meta = builder(extra);
+                    resource._meta = {
+                        ...(resource._meta ?? {}),
+                        ...meta,
+                    };
+                }
+                return result;
+            },
+        };
+        // Resolve a view's `resources/read` by its query-less path so the
+        // underlying asset is served no matter the `?v=` value (stale cache key,
+        // no param, etc.). The version param is a cache-busting hint for external
+        // consumers; it must not gate resolution. We rewrite the lookup URI to the
+        // canonical registered one, then restore the requested URI on the response
+        // so the consumer-facing URI is never rewritten.
+        const viewReadResolveEntry = {
+            filter: "resources/read",
+            handler: async (req, _extra, next) => {
+                const requested = req.params.uri;
+                if (typeof requested !== "string") {
+                    return next();
+                }
+                const path = stripQuery(requested);
+                const canonical = this.viewUriByPath.get(path);
+                if (!canonical) {
+                    return next();
+                }
+                req.params.uri = canonical;
+                try {
+                    const result = (await next());
+                    for (const content of result.contents ?? []) {
+                        if (typeof content.uri === "string" &&
+                            stripQuery(content.uri) === stripQuery(canonical)) {
+                            content.uri = requested;
+                        }
+                    }
+                    return result;
+                }
+                finally {
+                    // Restore the shared request params so middleware outer to us never
+                    // observes the rewritten lookup URI after next() unwinds.
+                    req.params.uri = requested;
+                }
+            },
+        };
+        // ChatGPT reads `securitySchemes` at the tool descriptor top level (SEP-1488,
+        // still Draft), but the SDK's registerTool strips unknown top-level fields, so
+        // it's stashed in `_meta` at registration. This restores it to the top level
+        // on tools/list output. Remove once SEP-1488 lands and the SDK preserves it.
+        //   { name: "checkout", _meta: { securitySchemes: [{ type: "oauth2" }] } }
+        //     -> { name: "checkout", _meta: {…}, securitySchemes: [{ type: "oauth2" }] }
+        const toolsListSecuritySchemesEntry = {
+            filter: "tools/list",
+            handler: async (_req, _extra, next) => {
+                const result = (await next());
+                for (const tool of result.tools) {
+                    const schemes = tool._meta?.securitySchemes;
+                    if (schemes && !("securitySchemes" in tool)) {
+                        tool.securitySchemes = schemes;
+                    }
+                }
+                return result;
+            },
+        };
+        return [
+            viewListMetaEntry,
+            viewReadResolveEntry,
+            toolsListSecuritySchemesEntry,
+            ...this.userMiddlewareEntries,
+        ];
+    }
+    enforceOneToolPerView(component, toolName) {
+        const existingTool = this.claimedViews.get(component);
+        if (existingTool) {
+            throw new Error(`skybridge: view "${component}" is already used by tool "${existingTool}". Tool "${toolName}" cannot also reference it — each view backs exactly one tool.`);
+        }
+        this.claimedViews.set(component, toolName);
+    }
+    resolveViewRequestContext(ctx) {
+        const isProduction = process.env.NODE_ENV === "production";
+        const header = (key) => ctx?.http?.req?.headers.get(key) ?? undefined;
+        const isClaude = hostFromUserAgent(header("user-agent")) === "claude";
+        const serverUrl = resolveServerOrigin(header);
+        // Path prefix the proxy routed this request under (e.g. `foo.com/v1`). Read
+        // per-request so one process can serve many hosts/prefixes at once: the
+        // origin is recovered from x-forwarded-host, the prefix from
+        // x-forwarded-prefix. Empty when served at the origin root.
+        const assetsBasePath = normalizeForwardedPrefix(header("x-forwarded-prefix"));
+        const connectDomains = [serverUrl];
+        if (!isProduction) {
+            const wsUrl = new URL(serverUrl);
+            wsUrl.protocol = wsUrl.protocol === "https:" ? "wss:" : "ws:";
+            connectDomains.push(wsUrl.origin);
+        }
+        let contentMetaOverrides = {};
+        if (isClaude) {
+            const pathname = ctx?.http?.req ? new URL(ctx.http.req.url).pathname : "";
+            const rawUrl = header("x-alpic-forwarded-url") ?? `${serverUrl}${pathname}`;
+            // Strip a lone trailing slash so the hash matches the connector URL
+            // as registered with Claude (which has no trailing slash on bare origins).
+            const url = rawUrl.endsWith("/") ? rawUrl.slice(0, -1) : rawUrl;
+            const hash = crypto
+                .createHash("sha256")
+                .update(url)
+                .digest("hex")
+                .slice(0, 32);
+            contentMetaOverrides = { domain: `${hash}.claudemcpcontent.com` };
+        }
+        return { serverUrl, assetsBasePath, connectDomains, contentMetaOverrides };
+    }
+    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 = {
+            uri: `ui://views/ext-apps/${view.component}.html${versionParam}`,
+            mimeType: "text/html;profile=mcp-app",
+            buildContentMeta: ({ resourceDomains, connectDomains, domain, baseUriDomains }, overrides) => {
+                const ui = {
+                    ui: {
+                        ...(view.description && { description: view.description }),
+                        ...(view.prefersBorder !== undefined && {
+                            prefersBorder: view.prefersBorder,
+                        }),
+                        domain: overrides.domain ?? view.domain ?? domain,
+                        csp: {
+                            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,
+                            }),
+                        },
+                    },
+                };
+                const base = {
+                    ...ui,
+                    ...(view.description && {
+                        "openai/widgetDescription": view.description,
+                    }),
+                    ...(view.csp?.redirectDomains && {
+                        "openai/widgetCSP": { redirect_domains: view.csp.redirectDomains },
+                    }),
+                };
+                const meta = { ...base, ...view._meta };
+                mergeOpenAIUi(meta, {
+                    availableDisplayModes: openai?.availableDisplayModes,
+                    preferredDisplayMode: openai?.preferredDisplayMode,
+                });
+                return meta;
+            },
+        };
+        this.registerViewResource({ name: toolName, viewResource, view });
+        // Advertise via the MCP Apps standard pointer only — ChatGPT renders from
+        // ui.resourceUri (verified), and not emitting openai/outputTemplate lets us
+        // retire the legacy apps-sdk resource later. The legacy apps-sdk URL is still
+        // served (see registerViewResource) so already-published apps keep resolving.
+        // @ts-expect-error - For backwards compatibility with Claude current implementation of the specs
+        toolMeta["ui/resourceUri"] = viewResource.uri;
+        toolMeta.ui = { ...toolMeta.ui, resourceUri: viewResource.uri };
+    }
+    registerViewResource({ name, viewResource, view, }) {
+        const { uri: viewUri, mimeType, buildContentMeta } = viewResource;
+        const buildMeta = (extra) => {
+            const { serverUrl, connectDomains, contentMetaOverrides } = this.resolveViewRequestContext(extra);
+            return buildContentMeta({
+                resourceDomains: [serverUrl],
+                connectDomains,
+                domain: serverUrl,
+                baseUriDomains: [serverUrl],
+            }, contentMetaOverrides);
+        };
+        this.viewMetaBuilders.set(viewUri, buildMeta);
+        this.viewUriByPath.set(stripQuery(viewUri), viewUri);
+        this.serveLegacyAppsSdkUrl(view.component, viewUri);
+        this.registerResource(name, viewUri, { description: view.description }, async (uri, extra) => {
+            const isProduction = process.env.NODE_ENV === "production";
+            const { serverUrl, assetsBasePath } = this.resolveViewRequestContext(extra);
+            // The view resolves all assets (template imports + runtime lazy chunks
+            // via `window.skybridge.serverUrl`) against this base, so it carries the
+            // proxy path prefix. CSP domains in `buildMeta` stay the bare origin.
+            const viewBase = `${serverUrl}${assetsBasePath}`;
+            const html = isProduction
+                ? templateHelper.renderProduction({
+                    serverUrl: viewBase,
+                    viewFile: this.lookupViewFile(view.component),
+                    styleFile: this.lookupDistFile("style.css") ?? "",
+                })
+                : templateHelper.renderDevelopment({
+                    serverUrl: viewBase,
+                    viewName: view.component,
+                });
+            return {
+                contents: [
+                    { uri: uri.href, mimeType, text: html, _meta: buildMeta(extra) },
+                ],
+            };
+        });
+    }
+    serveLegacyAppsSdkUrl(component, canonicalUri) {
+        this.viewUriByPath.set(`ui://views/apps-sdk/${component}.html`, canonicalUri);
+        this.viewUriByPath.set(`ui://widgets/apps-sdk/${component}.html`, canonicalUri);
+        this.viewUriByPath.set(`ui://widgets/ext-apps/${component}.html`, canonicalUri);
+    }
+    decorateToolHandler(cb, { attachViewUUID, securitySchemes, toolName, }) {
+        return async (args, extra) => {
+            if (this.oauthEnabled) {
+                const failure = evaluateSecuritySchemes(securitySchemes, extra.http?.authInfo);
+                if (failure) {
+                    const header = (key) => extra.http?.req?.headers.get(key) ?? undefined;
+                    return inBandChallengeResult(failure, this.resolveResourceMetadataUrl?.(header));
+                }
+            }
+            let result;
+            try {
+                result = await cb(args, extra);
+            }
+            catch (error) {
+                captureToolError(extra, error);
+                throw error;
+            }
+            if (isInputRequiredResult(result)) {
+                return result;
+            }
+            warnOnLargeToolOutput(result, toolName);
+            return {
+                ...result,
+                content: normalizeContent(result.content),
+                ...(attachViewUUID && {
+                    _meta: {
+                        ...result._meta,
+                        viewUUID: crypto.randomUUID(),
+                    },
+                }),
+            };
+        };
+    }
+    computeViewVersionParam(viewName) {
+        if (process.env.NODE_ENV !== "production") {
+            return "";
+        }
+        try {
+            const viewFile = this.lookupViewFile(viewName);
+            const styleFile = this.lookupDistFile("style.css") ?? "";
+            const hash = crypto
+                .createHash("sha256")
+                .update(viewFile)
+                .update("\0")
+                .update(styleFile)
+                .digest("hex")
+                .slice(0, 8);
+            return `?v=${hash}`;
+        }
+        catch {
+            return "";
+        }
+    }
+    lookupViewFile(viewName) {
+        const manifest = this.readManifest();
+        for (const entry of Object.values(manifest)) {
+            if (entry?.isEntry && entry.name === viewName && entry.file) {
+                return entry.file;
+            }
+        }
+        throw new Error(`View "${viewName}" not found in Vite manifest. Did the build complete successfully? Look for an entry with name "${viewName}" in dist/assets/.vite/manifest.json.`);
+    }
+    lookupDistFile(key) {
+        const manifest = this.readManifest();
+        return manifest[key]?.file;
+    }
+    /**
+     * Inject the Vite manifest as a value rather than letting `readManifest()`
+     * load it from disk. Required for runtimes without a usable filesystem
+     * (Cloudflare Workers, etc.) — the user's `skybridge build` emits the
+     * manifest as a JS module which the entry imports and passes here.
+     */
+    setViteManifest(manifest) {
+        this.viteManifest = manifest;
+        return this;
+    }
+    readManifest() {
+        if (this.viteManifest) {
+            return this.viteManifest;
+        }
+        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, openai, _meta: userToolMeta, ...toolFields } = config;
+        const authNeedsProvider = auth !== undefined &&
+            (!auth.allowsAnonymous || Boolean(auth.scopes?.length));
+        if (rawSecuritySchemes === undefined &&
+            authNeedsProvider &&
+            !this.oauthEnabled) {
+            throw new Error(`Tool "${name}" sets \`auth: ${JSON.stringify(auth)}\` but the server has no \`oauth\` provider configured.`);
+        }
+        const securitySchemes = rawSecuritySchemes ??
+            (auth && this.oauthEnabled ? authToSecuritySchemes(auth) : undefined);
+        const toolMeta = { ...userToolMeta };
+        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
+            // 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, openai);
+        }
+        const wrappedCb = this.decorateToolHandler(cb, {
+            attachViewUUID: Boolean(view),
+            securitySchemes,
+            toolName: name,
+        });
+        baseFn.call(this, name, { ...toolFields, _meta: toolMeta }, toolFields.inputSchema === undefined
+            ? (extra) => wrappedCb({}, extra)
+            : wrappedCb);
+        return this;
+    }
+}
+//# sourceMappingURL=server.js.map