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

package/dist/server/server.js

@@ -2,15 +2,18 @@ import crypto from "node:crypto";
 import { readFileSync } from "node:fs";
 import http from "node:http";
 import path from "node:path";
-import { Server as SdkServer, } from "@modelcontextprotocol/sdk/server/index.js";
-import { McpServer as McpServerBase } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer as McpServerBase, } from "@modelcontextprotocol/server";
 import { mergeWith, union } from "es-toolkit";
 import express, {} from "express";
+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 { hostFromUserAgent } from "./host.js";
 import { createMiddlewareEntry } from "./metric.js";
-import { buildMiddlewareChain, getHandlerMaps } from "./middleware.js";
+import { buildMiddlewareChain, captureToolError, getHandlerMaps, } 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) => {
@@ -19,6 +22,20 @@ const mergeWithUnion = (target, source) => {
         }
     });
 };
+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}`;
+}
 /**
  * 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
@@ -92,6 +109,27 @@ let pendingBuildManifest = null;
 export function __setBuildManifest(manifest) {
     pendingBuildManifest = manifest;
 }
+let pendingSkillsManifest = null;
+export function __setSkillsManifest(manifest) {
+    pendingSkillsManifest = manifest;
+}
+// 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 },
+            },
+        },
+    };
+}
 export class McpServer extends McpServerBaseOmitted {
     /**
      * The underlying Express app. Use this to extend the HTTP server with
@@ -111,6 +149,8 @@ export class McpServer extends McpServerBaseOmitted {
     customErrorMiddleware = [];
     mcpMiddlewareEntries = [];
     mcpMiddlewareApplied = false;
+    middlewareEntriesCache = null;
+    registrations = [];
     claimedViews = new Map();
     viewMetaBuilders = new Map();
     /**
@@ -123,14 +163,19 @@ export class McpServer extends McpServerBaseOmitted {
     viteManifest = null;
     serverInfo;
     serverOptions;
+    oauthEnabled = false;
+    resolveResourceMetadataUrl;
+    securitySchemesByTool = new Map();
     constructor(serverInfo, options, skybridgeOptions) {
-        super(serverInfo, options);
+        const mergedOptions = withSkillsCapability(options, skybridgeOptions);
+        super(serverInfo, mergedOptions);
         this.serverInfo = serverInfo;
-        this.serverOptions = options;
+        this.serverOptions = mergedOptions;
         this.express = express();
         this.express.use(express.json(skybridgeOptions?.json));
         if (skybridgeOptions?.oauth) {
-            setupOAuth(this.express, skybridgeOptions.oauth);
+            this.oauthEnabled = true;
+            this.resolveResourceMetadataUrl = setupOAuth(this.express, skybridgeOptions.oauth, this.securitySchemesByTool);
         }
         // Pick up the manifest if `dist/__entry.js` primed it before importing
         // user code. Consume-once: clear after the first construction so a
@@ -141,6 +186,56 @@ export class McpServer extends McpServerBaseOmitted {
             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.
+     */
+    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;
+    }
+    skillRegistrar() {
+        const registerResource = this.registerResource.bind(this);
+        return {
+            registerResource,
+            server: {
+                setRequestHandler: ((...args) => {
+                    this.recordRequestHandler(...args);
+                }),
+            },
+        };
+    }
+    setupSkills(enabled) {
+        const manifest = pendingSkillsManifest;
+        pendingSkillsManifest = null;
+        if (!enabled) {
+            return;
+        }
+        const skills = manifest ?? discoverSkills(SKILLS_DIR);
+        if (skills.length === 0) {
+            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
@@ -236,7 +331,7 @@ export class McpServer extends McpServerBaseOmitted {
                     const result = (await next());
                     for (const content of result.contents ?? []) {
                         if (typeof content.uri === "string" &&
-                            stripQuery(content.uri) === path) {
+                            stripQuery(content.uri) === stripQuery(canonical)) {
                             content.uri = requested;
                         }
                     }
@@ -249,17 +344,39 @@ export class McpServer extends McpServerBaseOmitted {
                 }
             },
         };
+        // 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;
+            },
+        };
         const monitoringEntry = createMiddlewareEntry();
         const entries = [
             ...(monitoringEntry ? [monitoringEntry] : []),
             viewListMetaEntry,
             viewReadResolveEntry,
+            toolsListSecuritySchemesEntry,
             ...this.mcpMiddlewareEntries,
         ];
-        if (entries.length === 0) {
-            return;
-        }
-        const { requestHandlers, notificationHandlers } = getHandlerMaps(this.server);
+        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));
@@ -283,23 +400,36 @@ export class McpServer extends McpServerBaseOmitted {
         return McpServerBase.prototype.connect.call(this, transport);
     }
     /**
-     * Per-request stateless connect. The SDK's `Protocol` only allows one
-     * transport per instance, so we can't reuse this `McpServer` across
-     * concurrent requests. The SDK's idiomatic fix is a `() => McpServer`
-     * factory, but that would break Skybridge's singleton API — so instead
-     * we build a fresh underlying `Server` per request and share the main
-     * server's handler maps by reference. The cast is unavoidable: there's
-     * no public API to inject handler maps. `getHandlerMaps` validates the
-     * read side and fails fast on SDK field renames.
+     * 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.
      */
-    async connectStatelessTransport(transport) {
+    createStatelessServerInstance() {
         this.applyMcpMiddleware();
-        const { requestHandlers, notificationHandlers } = getHandlerMaps(this.server);
-        const fresh = new SdkServer(this.serverInfo, this.serverOptions);
-        const target = fresh;
-        target._requestHandlers = requestHandlers;
-        target._notificationHandlers = notificationHandlers;
-        await fresh.connect(transport);
+        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`),
@@ -374,15 +504,16 @@ export class McpServer extends McpServerBaseOmitted {
         }
         this.claimedViews.set(component, toolName);
     }
-    resolveViewRequestContext(extra) {
+    resolveViewRequestContext(ctx) {
         const isProduction = process.env.NODE_ENV === "production";
-        const headers = extra?.requestInfo?.headers || {};
-        const header = (key) => {
-            const val = headers[key];
-            return Array.isArray(val) ? val[0] : val;
-        };
-        const isClaude = header("user-agent") === "Claude-User";
+        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);
@@ -391,7 +522,7 @@ export class McpServer extends McpServerBaseOmitted {
         }
         let contentMetaOverrides = {};
         if (isClaude) {
-            const pathname = extra?.requestInfo?.url?.pathname ?? "";
+            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).
@@ -403,114 +534,77 @@ export class McpServer extends McpServerBaseOmitted {
                 .slice(0, 32);
             contentMetaOverrides = { domain: `${hash}.claudemcpcontent.com` };
         }
-        return { serverUrl, connectDomains, contentMetaOverrides };
+        return { serverUrl, assetsBasePath, connectDomains, contentMetaOverrides };
     }
     registerViewResources(toolName, view, toolMeta) {
-        const hosts = view.hosts ?? ["apps-sdk", "mcp-app"];
         // 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);
-        if (hosts.includes("apps-sdk")) {
-            const viewResource = {
-                hostType: "apps-sdk",
-                uri: `ui://views/apps-sdk/${view.component}.html${versionParam}`,
-                mimeType: "text/html+skybridge",
-                buildContentMeta: ({ resourceDomains, connectDomains, domain }, overrides) => {
-                    const defaults = {
-                        "openai/widgetCSP": {
-                            resource_domains: resourceDomains,
-                            connect_domains: connectDomains,
-                        },
-                        "openai/widgetDomain": domain,
-                        "openai/widgetDescription": view.description,
-                    };
-                    const fromView = {
-                        "openai/widgetCSP": {
-                            resource_domains: view.csp?.resourceDomains,
-                            connect_domains: view.csp?.connectDomains,
-                            frame_domains: view.csp?.frameDomains,
-                            redirect_domains: view.csp?.redirectDomains,
-                        },
-                        "openai/widgetDomain": view.domain,
-                        "openai/widgetPrefersBorder": view.prefersBorder,
-                    };
-                    const base = mergeWithUnion(mergeWithUnion(defaults, fromView), {
-                        "openai/widgetDomain": overrides.domain,
-                    });
-                    if (view._meta) {
-                        return { ...base, ...view._meta };
-                    }
-                    return base;
-                },
-            };
-            this.registerViewResource({
-                name: toolName,
-                viewResource,
-                view,
-            });
-            toolMeta["openai/outputTemplate"] = viewResource.uri;
-        }
-        if (hosts.includes("mcp-app")) {
-            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 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,
                         },
-                    };
-                    const fromView = {
-                        ui: {
-                            ...(view.description && { description: view.description }),
-                            ...(view.prefersBorder !== undefined && {
-                                prefersBorder: view.prefersBorder,
+                        domain,
+                    },
+                };
+                const fromView = {
+                    ui: {
+                        ...(view.description && { description: view.description }),
+                        ...(view.prefersBorder !== undefined && {
+                            prefersBorder: view.prefersBorder,
+                        }),
+                        ...(view.domain && { domain: view.domain }),
+                        csp: {
+                            ...(view.csp?.resourceDomains && {
+                                resourceDomains: view.csp.resourceDomains,
+                            }),
+                            ...(view.csp?.connectDomains && {
+                                connectDomains: view.csp.connectDomains,
+                            }),
+                            ...(view.csp?.frameDomains && {
+                                frameDomains: view.csp.frameDomains,
+                            }),
+                            ...(view.csp?.baseUriDomains && {
+                                baseUriDomains: view.csp.baseUriDomains,
                             }),
-                            ...(view.domain && { domain: view.domain }),
-                            csp: {
-                                ...(view.csp?.resourceDomains && {
-                                    resourceDomains: view.csp.resourceDomains,
-                                }),
-                                ...(view.csp?.connectDomains && {
-                                    connectDomains: view.csp.connectDomains,
-                                }),
-                                ...(view.csp?.frameDomains && {
-                                    frameDomains: view.csp.frameDomains,
-                                }),
-                                ...(view.csp?.baseUriDomains && {
-                                    baseUriDomains: view.csp.baseUriDomains,
-                                }),
-                                ...(view.csp?.redirectDomains && {
-                                    redirectDomains: view.csp.redirectDomains,
-                                }),
-                            },
                         },
-                    };
-                    const base = mergeWithUnion(mergeWithUnion(defaults, fromView), {
-                        ui: overrides,
-                    });
-                    if (view._meta) {
-                        return { ...base, ...view._meta };
-                    }
-                    return base;
-                },
-            };
-            this.registerViewResource({
-                name: toolName,
-                viewResource,
-                view,
-            });
-            // @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 };
-        }
+                    },
+                };
+                const ui = mergeWithUnion(mergeWithUnion(defaults, fromView), {
+                    ui: overrides,
+                });
+                const base = {
+                    ...ui,
+                    ...(view.description && {
+                        "openai/widgetDescription": view.description,
+                    }),
+                    ...(view.csp?.redirectDomains && {
+                        "openai/widgetCSP": { redirect_domains: view.csp.redirectDomains },
+                    }),
+                };
+                if (view._meta) {
+                    return { ...base, ...view._meta };
+                }
+                return base;
+            },
+        };
+        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 { hostType, uri: viewUri, mimeType, buildContentMeta } = viewResource;
@@ -525,19 +619,24 @@ export class McpServer extends McpServerBaseOmitted {
         };
         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 } = this.resolveViewRequestContext(extra);
+            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({
                     hostType,
-                    serverUrl,
+                    serverUrl: viewBase,
                     viewFile: this.lookupViewFile(view.component),
                     styleFile: this.lookupDistFile("style.css") ?? "",
                 })
                 : templateHelper.renderDevelopment({
                     hostType,
-                    serverUrl,
+                    serverUrl: viewBase,
                     viewName: view.component,
                 });
             return {
@@ -547,9 +646,29 @@ export class McpServer extends McpServerBaseOmitted {
             };
         });
     }
-    wrapHandler(cb, { attachViewUUID }) {
+    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) => {
-            const result = await cb(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;
+            }
+            warnOnLargeToolOutput(result, toolName);
             return {
                 ...result,
                 content: normalizeContent(result.content),
@@ -611,16 +730,22 @@ export class McpServer extends McpServerBaseOmitted {
         }
         return JSON.parse(readFileSync(path.join(process.cwd(), "dist", "assets", ".vite", "manifest.json"), "utf-8"));
     }
-    registerTool(...args) {
+    registerTool(rawConfig, rawCb) {
         const baseFn = McpServerBase.prototype.registerTool;
-        if (typeof args[0] === "string") {
-            baseFn.call(this, args[0], args[1], args[2]);
-            return this;
+        const config = rawConfig;
+        const cb = rawCb;
+        const { name, view, auth, securitySchemes: rawSecuritySchemes, _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 config = args[0];
-        const cb = args[1];
-        const { name, view, securitySchemes, _meta: userToolMeta, ...toolFields } = config;
+        const securitySchemes = rawSecuritySchemes ??
+            (auth && this.oauthEnabled ? authToSecuritySchemes(auth) : undefined);
         const toolMeta = { ...userToolMeta };
+        this.securitySchemesByTool.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
@@ -633,8 +758,16 @@ export class McpServer extends McpServerBaseOmitted {
             this.enforceOneToolPerView(view.component, name);
             this.registerViewResources(name, view, toolMeta);
         }
-        const wrappedCb = this.wrapHandler(cb, { attachViewUUID: Boolean(view) });
-        baseFn.call(this, name, { ...toolFields, _meta: toolMeta }, wrappedCb);
+        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);
+        });
         return this;
     }
 }