skybridge 2.0.3 → 2.1.0

package/dist/server/server.js

@@ -1,15 +1,32 @@
 import crypto from "node:crypto";
 import { readFileSync } from "node:fs";
 import path from "node:path";
-import { McpServer as McpServerBase, } from "@modelcontextprotocol/server";
+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
@@ -24,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
@@ -138,6 +161,7 @@ export class McpServer extends McpServerBaseOmitted {
     resolveResourceMetadataUrl;
     toolSecuritySchemes = new Map();
     userMiddlewareEntries = [];
+    eventRegistry;
     constructor(serverInfo, options, skybridgeOptions) {
         super(serverInfo, withSkillsCapability(options, skybridgeOptions));
         this.oauthEnabled = Boolean(skybridgeOptions?.oauth);
@@ -331,7 +355,7 @@ export class McpServer extends McpServerBaseOmitted {
         }
         return { serverUrl, assetsBasePath, connectDomains, contentMetaOverrides };
     }
-    registerViewResources(toolName, view, toolMeta) {
+    registerViewResources(toolName, view, toolMeta, openai) {
         // Append a content-derived version param so hosts (e.g. ChatGPT) bust
         // their cache when the bundle changes, but keep the URI stable across
         // `tools/list` calls when the bundle hasn't changed.
@@ -366,10 +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 });
@@ -441,6 +467,9 @@ export class McpServer extends McpServerBaseOmitted {
                 captureToolError(extra, error);
                 throw error;
             }
+            if (isInputRequiredResult(result)) {
+                return result;
+            }
             warnOnLargeToolOutput(result, toolName);
             return {
                 ...result,
@@ -504,11 +533,216 @@ export class McpServer extends McpServerBaseOmitted {
         cachedDiskManifest ??= JSON.parse(readFileSync(path.join(process.cwd(), "dist", "assets", ".vite", "manifest.json"), "utf-8"));
         return cachedDiskManifest ?? {};
     }
+    /**
+     * @experimental Register an MCP Events type that hosts can subscribe to, per
+     * the Triggers & Events working group draft. Skybridge serves `events/list`,
+     * `events/subscribe` and `events/unsubscribe`, checks auth and arguments,
+     * verifies the callback URL, then hands each subscription to `onSubscribe`.
+     * Delivering the events is up to you, for example with {@link deliverEvent}.
+     * API may change.
+     *
+     * @example
+     * ```ts
+     * server.registerEvent(
+     *   {
+     *     name: "comment.created",
+     *     description: "Fires when someone comments on a document",
+     *     inputSchema: { documentId: z.string() },
+     *     payloadSchema: { documentId: z.string(), excerpt: z.string() },
+     *   },
+     *   {
+     *     onSubscribe: ({ documentId }, { subscription }) =>
+     *       webhooks.upsert({ ...subscription, filter: { documentId } }),
+     *     onUnsubscribe: (_args, { subscription }) =>
+     *       webhooks.remove(subscription.id),
+     *   },
+     * );
+     * ```
+     *
+     * @see https://docs.skybridge.tech/api-reference/register-event
+     */
+    registerEvent(config, hooks) {
+        if (!this.eventRegistry) {
+            this.server.registerCapabilities({ events: {} });
+            this.eventRegistry = new EventRegistry(this.server);
+        }
+        this.eventRegistry.add(config, hooks);
+        return this;
+    }
+    /**
+     * Register 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 &&
@@ -525,12 +759,31 @@ export class McpServer extends McpServerBaseOmitted {
             // descriptor, but the SDK's `registerTool` drops unknown top-level
             // fields, so the canonical spot isn't reachable without intercepting
             // `tools/list`. Use the `_meta` back-compat mirror documented in the
-            // Apps SDK reference until SEP-1488 lands in the spec.
+            // ChatGPT plugin reference until SEP-1488 lands in the spec.
             toolMeta.securitySchemes = securitySchemes;
         }
+        if (openai) {
+            if (!view) {
+                throw new Error(`skybridge: tool "${name}" sets \`openai\` options but has no \`view\`.`);
+            }
+            const opensWithoutInput = openai.entrypoints?.some(({ type }) => type === "global" || type === "thread");
+            if (opensWithoutInput && !acceptsEmptyInput(toolFields.inputSchema)) {
+                throw new Error(`skybridge: tool "${name}" has a global or thread entrypoint, so ChatGPT calls it with \`{}\`, but its input schema rejects \`{}\`. Make every input optional.`);
+            }
+            const badExtension = openai.entrypoints
+                ?.flatMap((entrypoint) => entrypoint.type === "file" ? entrypoint.extensions : [])
+                .find((extension) => !extension.startsWith("."));
+            if (badExtension !== undefined) {
+                throw new Error(`skybridge: tool "${name}" has a file entrypoint extension "${badExtension}" that doesn't start with ".".`);
+            }
+            mergeOpenAIUi(toolMeta, {
+                entrypoints: openai.entrypoints,
+                preferredModelDisplayMode: openai.preferredModelDisplayMode,
+            });
+        }
         if (view) {
             this.enforceOneToolPerView(view.component, name);
-            this.registerViewResources(name, view, toolMeta);
+            this.registerViewResources(name, view, toolMeta, openai);
         }
         const wrappedCb = this.decorateToolHandler(cb, {
             attachViewUUID: Boolean(view),