skybridge 0.0.0-dev.891b84f → 0.0.0-dev.896eb66

package/dist/server/server.js

@@ -2,8 +2,10 @@ 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 { mergeWith, union } from "es-toolkit";
+import express, {} from "express";
 import { createApp } from "./express.js";
 import { createMiddlewareEntry } from "./metric.js";
 import { buildMiddlewareChain, getHandlerMaps } from "./middleware.js";
@@ -15,6 +17,21 @@ const mergeWithUnion = (target, source) => {
         }
     });
 };
+/**
+ * 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 [];
@@ -28,24 +45,106 @@ export function normalizeContent(content) {
     return [content];
 }
 const McpServerBaseOmitted = McpServerBase;
+/**
+ * The Skybridge server. Extends the MCP SDK's `McpServer` with a typed tool
+ * registry, view resources, an embedded Express app, and protocol-level
+ * middleware. Construct it with the same `Implementation` info you would pass
+ * to the SDK, chain {@link McpServer.registerTool} calls to declare tools,
+ * then call {@link McpServer.run} to start the HTTP server.
+ *
+ * The `TTools` generic accumulates each registered tool's input/output/meta
+ * shape, so `typeof server` carries enough information for view-side helpers
+ * like {@link generateHelpers} to produce fully-typed hooks.
+ *
+ * @typeParam TTools - Accumulated tool registry. Filled in by `registerTool`
+ * chaining; you almost never set this manually.
+ *
+ * @example
+ * ```ts
+ * const server = new McpServer({ name: "my-app", version: "1.0.0" }, {})
+ *   .registerTool({
+ *     name: "search",
+ *     inputSchema: { query: z.string() },
+ *     view: { component: "search" },
+ *   }, async ({ query }) => ({ content: `Results for ${query}` }));
+ *
+ * await server.run();
+ * export type AppType = typeof server;
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/mcp-server
+ */
+// Side channel populated by `dist/__entry.js` before user code is imported.
+// Set at module scope rather than passed through the constructor because the
+// wrapper has the manifest before the user's `new McpServer(...)` runs, and
+// 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;
+}
 export class McpServer extends McpServerBaseOmitted {
+    /**
+     * The underlying Express app. Use this to extend the HTTP server with
+     * custom routes, middleware, or settings — e.g.
+     * `server.express.get("/health", ...)`.
+     *
+     * `express.json()` is pre-applied — tune it via the constructor's third
+     * argument, e.g. `new McpServer(info, {}, { json: { limit: "10mb" } })`.
+     * Register your handlers before `run()`;
+     * after `run()`, dev-mode middleware, the `/mcp` route, and the default
+     * error handler are appended in that order.
+     *
+     * Note: Alpic Cloud only routes traffic to `/mcp` — custom routes work
+     * locally and on self-hosted deployments.
+     */
     express;
-    customMiddleware = [];
     customErrorMiddleware = [];
     mcpMiddlewareEntries = [];
     mcpMiddlewareApplied = false;
     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;
+    serverInfo;
+    serverOptions;
+    constructor(serverInfo, options, skybridgeOptions) {
+        super(serverInfo, options);
+        this.serverInfo = serverInfo;
+        this.serverOptions = options;
+        this.express = express();
+        this.express.use(express.json(skybridgeOptions?.json));
+        // Pick up the manifest if `dist/__entry.js` primed it before importing
+        // user code. Consume-once: clear after the first construction so a
+        // subsequent test that doesn't prime can't inherit stale state.
+        // Explicit `setViteManifest` calls still win because they happen after
+        // construction.
+        if (pendingBuildManifest) {
+            this.setViteManifest(pendingBuildManifest);
+            pendingBuildManifest = null;
+        }
+    }
     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.customMiddleware.push({
-                handlers: [pathOrHandler, ...handlers],
-            });
+            this.express.use(pathOrHandler, ...handlers);
         }
         return this;
     }
@@ -89,10 +188,69 @@ export class McpServer extends McpServerBaseOmitted {
             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;
+            },
+        };
+        // 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) === path) {
+                            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;
+                }
+            },
+        };
         const monitoringEntry = createMiddlewareEntry();
-        const entries = monitoringEntry
-            ? [monitoringEntry, ...this.mcpMiddlewareEntries]
-            : this.mcpMiddlewareEntries;
+        const entries = [
+            ...(monitoringEntry ? [monitoringEntry] : []),
+            viewListMetaEntry,
+            viewReadResolveEntry,
+            ...this.mcpMiddlewareEntries,
+        ];
         if (entries.length === 0) {
             return;
         }
@@ -107,32 +265,102 @@ export class McpServer extends McpServerBaseOmitted {
         instrumentMap(requestHandlers, false);
         instrumentMap(notificationHandlers, true);
     }
+    /**
+     * Connect to an MCP transport (override of the SDK's `connect`). Use this
+     * when you're embedding Skybridge in a host that already manages its own
+     * transport (e.g. stdio for desktop apps); for HTTP, prefer {@link McpServer.run}
+     * which sets the transport up for you. Locks in any middleware registered
+     * via {@link McpServer.mcpMiddleware} — further calls to that method will
+     * throw afterwards.
+     */
     async connect(transport) {
         this.applyMcpMiddleware();
         return McpServerBase.prototype.connect.call(this, transport);
     }
+    /**
+     * 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);
+    }
+    /**
+     * Start the HTTP server. Listens on `process.env.__PORT` (default `3000`),
+     * mounts the `/mcp` route, applies any custom Express middleware registered
+     * via {@link McpServer.use} / {@link McpServer.useOnError}, and locks in
+     * any MCP middleware registered via {@link McpServer.mcpMiddleware}.
+     *
+     * On Cloudflare Workers / workerd, returns an object exposing `fetch` so
+     * the runtime can bridge incoming requests to the Node HTTP server. On
+     * Vercel (`VERCEL === "1"`), returns the Express app directly so the
+     * serverless function entry can call it as a `(req, res)` handler. On
+     * Node, returns `undefined` once listening.
+     */
     async run() {
         this.applyMcpMiddleware();
-        const httpServer = http.createServer();
-        if (!this.express) {
-            this.express = await createApp({
+        if (process.env.VERCEL === "1") {
+            // createApp only reads httpServer inside its dev-only branch
+            // (viewsDevServer); under VERCEL=1 + NODE_ENV=production it's a
+            // bare object passed to satisfy the required parameter.
+            const httpServer = http.createServer();
+            await createApp({
                 mcpServer: this,
                 httpServer,
-                customMiddleware: this.customMiddleware,
                 errorMiddleware: this.customErrorMiddleware,
             });
+            return this.express;
         }
+        const httpServer = http.createServer();
+        await createApp({
+            mcpServer: this,
+            httpServer,
+            errorMiddleware: this.customErrorMiddleware,
+        });
         httpServer.on("request", this.express);
-        return new Promise((resolve, reject) => {
+        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.__PORT ?? "3000", 10);
             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);
@@ -141,12 +369,67 @@ export class McpServer extends McpServerBaseOmitted {
         }
         this.claimedViews.set(component, toolName);
     }
+    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;
+        };
+        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/${view.component}.html`,
+                uri: `ui://views/apps-sdk/${view.component}.html${versionParam}`,
                 mimeType: "text/html+skybridge",
                 buildContentMeta: ({ resourceDomains, connectDomains, domain }, overrides) => {
                     const defaults = {
@@ -186,7 +469,7 @@ export class McpServer extends McpServerBaseOmitted {
         if (hosts.includes("mcp-app")) {
             const viewResource = {
                 hostType: "mcp-app",
-                uri: `ui://widgets/ext-apps/${view.component}.html`,
+                uri: `ui://views/ext-apps/${view.component}.html${versionParam}`,
                 mimeType: "text/html;profile=mcp-app",
                 buildContentMeta: ({ resourceDomains, connectDomains, domain, baseUriDomains }, overrides) => {
                     const defaults = {
@@ -241,40 +524,25 @@ export class McpServer extends McpServerBaseOmitted {
             });
             // @ts-expect-error - For backwards compatibility with Claude current implementation of the specs
             toolMeta["ui/resourceUri"] = viewResource.uri;
-            toolMeta.ui = { resourceUri: viewResource.uri };
+            toolMeta.ui = { ...toolMeta.ui, resourceUri: viewResource.uri };
         }
     }
     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.viewUriByPath.set(stripQuery(viewUri), viewUri);
         this.registerResource(name, viewUri, { description: view.description }, async (uri, extra) => {
             const isProduction = process.env.NODE_ENV === "production";
-            const isClaude = extra?.requestInfo?.headers?.["user-agent"] === "Claude-User";
-            const headers = extra?.requestInfo?.headers || {};
-            const header = (key) => {
-                const val = headers[key];
-                return Array.isArray(val) ? val[0] : val;
-            };
-            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 { serverUrl } = this.resolveViewRequestContext(extra);
             const html = isProduction
                 ? templateHelper.renderProduction({
                     hostType,
@@ -287,35 +555,9 @@ export class McpServer extends McpServerBaseOmitted {
                     serverUrl,
                     viewName: view.component,
                 });
-            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` };
-            }
-            const contentMeta = buildContentMeta({
-                resourceDomains: [serverUrl],
-                connectDomains,
-                domain: serverUrl,
-                baseUriDomains: [serverUrl],
-            }, contentMetaOverrides);
             return {
                 contents: [
-                    { uri: uri.href, mimeType, text: html, _meta: contentMeta },
+                    { uri: uri.href, mimeType, text: html, _meta: buildMeta(extra) },
                 ],
             };
         });
@@ -335,6 +577,26 @@ export class McpServer extends McpServerBaseOmitted {
             };
         };
     }
+    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)) {
@@ -348,7 +610,20 @@ export class McpServer extends McpServerBaseOmitted {
         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;
+        }
         return JSON.parse(readFileSync(path.join(process.cwd(), "dist", "assets", ".vite", "manifest.json"), "utf-8"));
     }
     registerTool(...args) {
@@ -359,8 +634,16 @@ export class McpServer extends McpServerBaseOmitted {
         }
         const config = args[0];
         const cb = args[1];
-        const { name, view, _meta: userToolMeta, ...toolFields } = config;
+        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);