skybridge 0.0.0-dev.e068fc7 → 0.0.0-dev.e071d95

package/dist/server/server.js

@@ -2,11 +2,14 @@ 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/sdk/server/mcp.js";
+import { Server as SdkServer, } from "@modelcontextprotocol/sdk/server/index.js";
+import { McpServer as McpServerBase } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { mergeWith, union } from "es-toolkit";
-import { createServer } from "./express.js";
+import express, {} from "express";
+import { createApp } from "./express.js";
+import { createMiddlewareEntry } from "./metric.js";
+import { buildMiddlewareChain, getHandlerMaps } from "./middleware.js";
 import { templateHelper } from "./templateHelper.js";
-import { DEFAULT_HMR_PORT } from "./const.js";
 const mergeWithUnion = (target, source) => {
     return mergeWith(target, source, (targetVal, sourceVal) => {
         if (Array.isArray(targetVal) && Array.isArray(sourceVal)) {
@@ -14,185 +17,492 @@ const mergeWithUnion = (target, source) => {
         }
     });
 };
-export class McpServer extends McpServerBase {
+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;
+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. 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;
-    customMiddleware = [];
+    customErrorMiddleware = [];
+    mcpMiddlewareEntries = [];
+    mcpMiddlewareApplied = false;
+    claimedViews = new Map();
+    viewMetaBuilders = new Map();
+    viteManifest = null;
+    serverInfo;
+    serverOptions;
+    constructor(serverInfo, options) {
+        super(serverInfo, options);
+        this.serverInfo = serverInfo;
+        this.serverOptions = options;
+        this.express = express();
+        this.express.use(express.json());
+    }
     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.customMiddleware.push({
-                path: pathOrHandler,
-                handlers,
-            });
+            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.customMiddleware.push({
+            this.customErrorMiddleware.push({
                 handlers: [pathOrHandler, ...handlers],
             });
         }
         return this;
     }
-    async run() {
-        if (!this.express) {
-            this.express = await createServer({
-                server: this,
-                customMiddleware: this.customMiddleware,
+    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({
+                filter: null,
+                handler: filterOrHandler,
+            });
+        }
+        else if (handler) {
+            this.mcpMiddlewareEntries.push({
+                filter: filterOrHandler,
+                handler,
             });
         }
-        const express = this.express;
-        return new Promise((resolve, reject) => {
-            const server = http.createServer(express);
-            server.on("error", (error) => {
+        else {
+            throw new Error("mcpMiddleware requires a handler function when a filter is provided");
+        }
+        return this;
+    }
+    applyMcpMiddleware() {
+        if (this.mcpMiddlewareApplied) {
+            return;
+        }
+        this.mcpMiddlewareApplied = true;
+        // 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;
+            },
+        };
+        const monitoringEntry = createMiddlewareEntry();
+        const entries = [
+            ...(monitoringEntry ? [monitoringEntry] : []),
+            viewListMetaEntry,
+            ...this.mcpMiddlewareEntries,
+        ];
+        if (entries.length === 0) {
+            return;
+        }
+        const { requestHandlers, notificationHandlers } = getHandlerMaps(this.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);
+    }
+    async connect(transport) {
+        this.applyMcpMiddleware();
+        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.
+     */
+    async connectStatelessTransport(transport) {
+        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);
+    }
+    async run() {
+        this.applyMcpMiddleware();
+        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);
             });
-            const port = parseInt(process.env.SKYBRIDGE_PORT ?? "3000", 10);
-            server.listen(port, () => {
+            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);
+        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);
     }
-    registerWidget(name, resourceConfig, toolConfig, toolCallback) {
-        const userMeta = resourceConfig._meta;
-        const toolMeta = {
-            ...toolConfig._meta,
+    resolveViewRequestContext(extra) {
+        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;
         };
-        if (!resourceConfig.hosts || resourceConfig.hosts.includes("apps-sdk")) {
-            const widgetConfig = {
+        const isClaude = header("user-agent") === "Claude-User";
+        let serverUrl;
+        const forwardedHost = header("x-forwarded-host");
+        const origin = header("origin");
+        const host = header("host");
+        if (forwardedHost) {
+            const proto = header("x-forwarded-proto") || "https";
+            serverUrl = `${proto}://${forwardedHost}`;
+        }
+        else if (origin) {
+            serverUrl = origin;
+        }
+        else if (host) {
+            const proto = ["127.0.0.1:", "localhost:"].some((p) => host.startsWith(p))
+                ? "http"
+                : "https";
+            serverUrl = `${proto}://${host}`;
+        }
+        else {
+            const devPort = process.env.__PORT || "3000";
+            serverUrl = `http://localhost:${devPort}`;
+        }
+        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 = extra?.requestInfo?.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, 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://widgets/apps-sdk/${name}.html`,
+                uri: `ui://views/apps-sdk/${view.component}.html${versionParam}`,
                 mimeType: "text/html+skybridge",
-                buildContentMeta: ({ resourceDomains, connectDomains, domain }) => {
-                    const userUi = userMeta?.ui;
-                    const userCsp = userUi?.csp;
+                buildContentMeta: ({ resourceDomains, connectDomains, domain }, overrides) => {
                     const defaults = {
                         "openai/widgetCSP": {
                             resource_domains: resourceDomains,
                             connect_domains: connectDomains,
                         },
                         "openai/widgetDomain": domain,
-                        "openai/widgetDescription": resourceConfig.description,
+                        "openai/widgetDescription": view.description,
                     };
-                    const fromUi = {
+                    const fromView = {
                         "openai/widgetCSP": {
-                            resource_domains: userCsp?.resourceDomains,
-                            connect_domains: userCsp?.connectDomains,
-                            frame_domains: userCsp?.frameDomains,
-                            redirect_domains: userCsp?.redirectDomains,
+                            resource_domains: view.csp?.resourceDomains,
+                            connect_domains: view.csp?.connectDomains,
+                            frame_domains: view.csp?.frameDomains,
+                            redirect_domains: view.csp?.redirectDomains,
                         },
-                        "openai/widgetDomain": userUi?.domain,
-                        "openai/widgetPrefersBorder": userUi?.prefersBorder,
+                        "openai/widgetDomain": view.domain,
+                        "openai/widgetPrefersBorder": view.prefersBorder,
                     };
-                    const directOpenaiKeys = Object.fromEntries(Object.entries(userMeta ?? {}).filter(([key]) => key.startsWith("openai/")));
-                    return mergeWithUnion(mergeWithUnion(defaults, fromUi), directOpenaiKeys);
+                    const base = mergeWithUnion(mergeWithUnion(defaults, fromView), {
+                        "openai/widgetDomain": overrides.domain,
+                    });
+                    if (view._meta) {
+                        return { ...base, ...view._meta };
+                    }
+                    return base;
                 },
             };
-            this.registerWidgetResource({
-                name,
-                widgetConfig,
-                resourceConfig,
+            this.registerViewResource({
+                name: toolName,
+                viewResource,
+                view,
             });
-            toolMeta["openai/outputTemplate"] = widgetConfig.uri;
+            toolMeta["openai/outputTemplate"] = viewResource.uri;
         }
-        if (!resourceConfig.hosts || resourceConfig.hosts.includes("mcp-app")) {
-            const widgetConfig = {
+        if (hosts.includes("mcp-app")) {
+            const viewResource = {
                 hostType: "mcp-app",
-                uri: `ui://widgets/ext-apps/${name}.html`,
+                uri: `ui://views/ext-apps/${view.component}.html${versionParam}`,
                 mimeType: "text/html;profile=mcp-app",
-                buildContentMeta: ({ resourceDomains, connectDomains, domain }) => {
+                buildContentMeta: ({ resourceDomains, connectDomains, domain, baseUriDomains }, overrides) => {
                     const defaults = {
                         ui: {
                             csp: {
                                 resourceDomains,
                                 connectDomains,
+                                baseUriDomains,
                             },
                             domain,
                         },
                     };
-                    return mergeWithUnion(defaults, { ui: userMeta?.ui });
+                    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.csp?.redirectDomains && {
+                                    redirectDomains: view.csp.redirectDomains,
+                                }),
+                            },
+                        },
+                    };
+                    const base = mergeWithUnion(mergeWithUnion(defaults, fromView), {
+                        ui: overrides,
+                    });
+                    if (view._meta) {
+                        return { ...base, ...view._meta };
+                    }
+                    return base;
                 },
             };
-            this.registerWidgetResource({
-                name,
-                widgetConfig,
-                resourceConfig,
+            this.registerViewResource({
+                name: toolName,
+                viewResource,
+                view,
             });
             // @ts-expect-error - For backwards compatibility with Claude current implementation of the specs
-            toolMeta["ui/resourceUri"] = widgetConfig.uri;
-            toolMeta.ui = { resourceUri: widgetConfig.uri };
+            toolMeta["ui/resourceUri"] = viewResource.uri;
+            toolMeta.ui = { ...toolMeta.ui, resourceUri: viewResource.uri };
         }
-        this.registerTool(name, {
-            ...toolConfig,
-            _meta: toolMeta,
-        }, toolCallback);
-        return this;
-    }
-    registerTool(name, config, cb) {
-        super.registerTool(name, config, cb);
-        return this;
     }
-    registerWidgetResource({ name, widgetConfig, resourceConfig, }) {
-        const { hostType, uri: widgetUri, mimeType, buildContentMeta, } = widgetConfig;
-        this.registerResource(name, widgetUri, { ...resourceConfig, _meta: resourceConfig._meta }, async (uri, extra) => {
+    registerViewResource({ name, viewResource, view, }) {
+        const { hostType, 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.registerResource(name, viewUri, { description: view.description }, async (uri, extra) => {
             const isProduction = process.env.NODE_ENV === "production";
-            const useForwardedHost = process.env.SKYBRIDGE_USE_FORWARDED_HOST === "true";
-            const isClaude = extra?.requestInfo?.headers?.["user-agent"] === "Claude-User";
-            const hostFromHeaders = extra?.requestInfo?.headers?.["x-forwarded-host"] ??
-                extra?.requestInfo?.headers?.host;
-            const useExternalHost = isProduction || useForwardedHost || isClaude;
-            const devPort = process.env.SKYBRIDGE_PORT || "3000";
-            const serverUrl = useExternalHost
-                ? `https://${hostFromHeaders}`
-                : `http://localhost:${devPort}`;
+            const { serverUrl } = this.resolveViewRequestContext(extra);
             const html = isProduction
                 ? templateHelper.renderProduction({
                     hostType,
                     serverUrl,
-                    widgetFile: this.lookupDistFileWithIndexFallback(`src/widgets/${name}`),
-                    styleFile: this.lookupDistFile("style.css"),
+                    viewFile: this.lookupViewFile(view.component),
+                    styleFile: this.lookupDistFile("style.css") ?? "",
                 })
                 : templateHelper.renderDevelopment({
                     hostType,
                     serverUrl,
-                    useLocalNetworkAccess: !useExternalHost,
-                    widgetName: name,
+                    viewName: view.component,
                 });
-            const connectDomains = [serverUrl];
-            if (!isProduction) {
-                const hmrPort = process.env.SKYBRIDGE_HMR_PORT ?? DEFAULT_HMR_PORT;
-                const VITE_HMR_WEBSOCKET_DEFAULT_URL = `ws://localhost:${hmrPort}`;
-                connectDomains.push(VITE_HMR_WEBSOCKET_DEFAULT_URL);
-            }
-            const contentMeta = buildContentMeta({
-                resourceDomains: [serverUrl],
-                connectDomains,
-                domain: isClaude
-                    ? `${crypto
-                        .createHash("sha256")
-                        .update(`https://${hostFromHeaders}/mcp`)
-                        .digest("hex")
-                        .slice(0, 32)}.claudemcpcontent.com`
-                    : serverUrl,
-                baseUriDomains: [serverUrl],
-            });
             return {
                 contents: [
-                    { uri: uri.href, mimeType, text: html, _meta: contentMeta },
+                    { uri: uri.href, mimeType, text: html, _meta: buildMeta(extra) },
                 ],
             };
         });
     }
+    wrapHandler(cb, { attachViewUUID }) {
+        return async (args, extra) => {
+            const result = await cb(args, extra);
+            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;
     }
-    lookupDistFileWithIndexFallback(basePath) {
-        const manifest = this.readManifest();
-        const flatFileKey = `${basePath}.tsx`;
-        const indexFileKey = `${basePath}/index.tsx`;
-        return manifest[flatFileKey]?.file ?? manifest[indexFileKey]?.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;
+        }
         return JSON.parse(readFileSync(path.join(process.cwd(), "dist", "assets", ".vite", "manifest.json"), "utf-8"));
     }
+    registerTool(...args) {
+        const baseFn = McpServerBase.prototype.registerTool;
+        if (typeof args[0] === "string") {
+            baseFn.call(this, args[0], args[1], args[2]);
+            return this;
+        }
+        const config = args[0];
+        const cb = args[1];
+        const { name, view, securitySchemes, _meta: userToolMeta, ...toolFields } = config;
+        const toolMeta = { ...userToolMeta };
+        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.
+            toolMeta.securitySchemes = securitySchemes;
+        }
+        if (view) {
+            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);
+        return this;
+    }
 }
 //# sourceMappingURL=server.js.map