skybridge 0.0.0-dev.b7b87ee → 0.0.0-dev.b7f4548

package/dist/server/requestOrigin.js

@@ -0,0 +1,25 @@
+/**
+ * Resolves this server's public origin from request headers, in precedence
+ * `x-forwarded-host` → `host` → localhost dev fallback. Shared by view serving
+ * and OAuth metadata so the two can't drift. `Origin` is deliberately ignored:
+ * it carries the *caller's* site, not this server's.
+ */
+export function resolveServerOrigin(header) {
+    // Proxies may send X-Forwarded-* as a comma-separated chain; the client-facing
+    // hop is the first entry.
+    const firstHop = (value) => value?.split(",")[0]?.trim();
+    const forwardedHost = firstHop(header("x-forwarded-host"));
+    if (forwardedHost) {
+        const proto = firstHop(header("x-forwarded-proto")) || "https";
+        return `${proto}://${forwardedHost}`;
+    }
+    const host = header("host");
+    if (host) {
+        const proto = ["127.0.0.1:", "localhost:"].some((p) => host.startsWith(p))
+            ? "http"
+            : "https";
+        return `${proto}://${host}`;
+    }
+    return `http://localhost:${process.env.__PORT || "3000"}`;
+}
+//# sourceMappingURL=requestOrigin.js.map

package/dist/server/requestOrigin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestOrigin.js","sourceRoot":"","sources":["../../src/server/requestOrigin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,MAA2C;IAE3C,+EAA+E;IAC/E,0BAA0B;IAC1B,MAAM,QAAQ,GAAG,CAAC,KAAyB,EAAE,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IAC7E,MAAM,aAAa,GAAG,QAAQ,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAC;IAC3D,IAAI,aAAa,EAAE,CAAC;QAClB,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC,IAAI,OAAO,CAAC;QAC/D,OAAO,GAAG,KAAK,MAAM,aAAa,EAAE,CAAC;IACvC,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5B,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,KAAK,GAAG,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;YACxE,CAAC,CAAC,MAAM;YACR,CAAC,CAAC,OAAO,CAAC;QACZ,OAAO,GAAG,KAAK,MAAM,IAAI,EAAE,CAAC;IAC9B,CAAC;IACD,OAAO,oBAAoB,OAAO,CAAC,GAAG,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC;AAC5D,CAAC","sourcesContent":["/**\n * Resolves this server's public origin from request headers, in precedence\n * `x-forwarded-host` → `host` → localhost dev fallback. Shared by view serving\n * and OAuth metadata so the two can't drift. `Origin` is deliberately ignored:\n * it carries the *caller's* site, not this server's.\n */\nexport function resolveServerOrigin(\n  header: (key: string) => string | undefined,\n): string {\n  // Proxies may send X-Forwarded-* as a comma-separated chain; the client-facing\n  // hop is the first entry.\n  const firstHop = (value: string | undefined) => value?.split(\",\")[0]?.trim();\n  const forwardedHost = firstHop(header(\"x-forwarded-host\"));\n  if (forwardedHost) {\n    const proto = firstHop(header(\"x-forwarded-proto\")) || \"https\";\n    return `${proto}://${forwardedHost}`;\n  }\n  const host = header(\"host\");\n  if (host) {\n    const proto = [\"127.0.0.1:\", \"localhost:\"].some((p) => host.startsWith(p))\n      ? \"http\"\n      : \"https\";\n    return `${proto}://${host}`;\n  }\n  return `http://localhost:${process.env.__PORT || \"3000\"}`;\n}\n"]}

package/dist/server/server.d.ts

@@ -4,7 +4,8 @@ import { McpServer as McpServerBase } from "@modelcontextprotocol/sdk/server/mcp
 import type { AnySchema, SchemaOutput, ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
 import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
 import type { ContentBlock, Implementation, RequestMeta, ServerNotification, ServerRequest, ServerResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
-import { type ErrorRequestHandler, type Express, type RequestHandler } from "express";
+import express, { type ErrorRequestHandler, type Express, type RequestHandler } from "express";
+import type { OAuthConfig } from "./auth/index.js";
 import type { McpExtra, McpExtraFor, McpMethodString, McpMiddlewareFilter, McpMiddlewareFn, McpResultFor, McpTypedMiddlewareFn, McpWildcard } from "./middleware.js";
 /**
  * Type marker for a registered tool — carries its input, output, and response
@@ -72,6 +73,18 @@ export type SecurityScheme = {
     type: "oauth2";
     scopes?: string[];
 };
+/**
+ * Options forwarded to the built-in `express.json()` body parser. Derived
+ * from Express's own types so the public API doesn't depend on `body-parser`.
+ */
+export type JsonOptions = NonNullable<Parameters<typeof express.json>[0]>;
+/** Skybridge-specific server options, passed as the third `McpServer` constructor argument. */
+export interface SkybridgeServerOptions {
+    /** Options for the built-in `express.json()` middleware, e.g. `{ limit: "10mb" }`. */
+    json?: JsonOptions;
+    /** Resource-server OAuth config. When set, mounts well-known metadata and bearer auth on `/mcp`. */
+    oauth?: OAuthConfig;
+}
 /**
  * Well-known keys recognized by host runtimes when set on a tool's `_meta`.
  * Use {@link ToolMeta} to also pass arbitrary custom metadata alongside these.
@@ -199,34 +212,15 @@ interface McpServerBaseOmitted extends Omit<McpServerBase, "registerTool" | "con
 }
 declare const McpServerBaseOmitted: new (...args: ConstructorParameters<typeof McpServerBase>) => McpServerBaseOmitted;
 /**
- * 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.
+ * 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.
  *
- * @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
+ * @internal
  */
+export declare function __setBuildManifest(manifest: Record<string, {
+    file: string;
+}>): void;
 export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>> extends McpServerBaseOmitted {
     readonly $types: McpServerTypes<TTools>;
     /**
@@ -234,7 +228,9 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
      * custom routes, middleware, or settings — e.g.
      * `server.express.get("/health", ...)`.
      *
-     * `express.json()` is pre-applied. Register your handlers before `run()`;
+     * `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.
      *
@@ -247,10 +243,17 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
     private mcpMiddlewareApplied;
     private claimedViews;
     private viewMetaBuilders;
+    /**
+     * 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.
+     */
+    private viewUriByPath;
     private viteManifest;
     private readonly serverInfo;
     private readonly serverOptions?;
-    constructor(serverInfo: Implementation, options?: ServerOptions);
+    constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions);
     /**
      * Register Express middleware on the underlying app. Mirrors `app.use` —
      * pass handlers directly or a path-prefixed handler list. Register before
@@ -336,11 +339,13 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
      *
      * 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.
      */
     run(): Promise<{
         fetch: (...args: unknown[]) => unknown;
-    } | undefined>;
+    } | Express | undefined>;
     private enforceOneToolPerView;
     private resolveViewRequestContext;
     private registerViewResources;

package/dist/server/server.js

@@ -6,9 +6,11 @@ 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 { setupOAuth } from "./auth/setup.js";
 import { createApp } from "./express.js";
 import { createMiddlewareEntry } from "./metric.js";
 import { buildMiddlewareChain, getHandlerMaps } from "./middleware.js";
+import { resolveServerOrigin } from "./requestOrigin.js";
 import { templateHelper } from "./templateHelper.js";
 const mergeWithUnion = (target, source) => {
     return mergeWith(target, source, (targetVal, sourceVal) => {
@@ -17,6 +19,15 @@ 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;
@@ -65,13 +76,31 @@ const McpServerBaseOmitted = McpServerBase;
  *
  * @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. Register your handlers before `run()`;
+     * `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.
      *
@@ -84,15 +113,34 @@ export class McpServer extends McpServerBaseOmitted {
     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) {
+    constructor(serverInfo, options, skybridgeOptions) {
         super(serverInfo, options);
         this.serverInfo = serverInfo;
         this.serverOptions = options;
         this.express = express();
-        this.express.use(express.json());
+        this.express.use(express.json(skybridgeOptions?.json));
+        if (skybridgeOptions?.oauth) {
+            setupOAuth(this.express, skybridgeOptions.oauth);
+        }
+        // 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
@@ -165,10 +213,47 @@ export class McpServer extends McpServerBaseOmitted {
                 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] : []),
             viewListMetaEntry,
+            viewReadResolveEntry,
             ...this.mcpMiddlewareEntries,
         ];
         if (entries.length === 0) {
@@ -224,10 +309,24 @@ export class McpServer extends McpServerBaseOmitted {
      *
      * 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();
+        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,
+                errorMiddleware: this.customErrorMiddleware,
+            });
+            return this.express;
+        }
         const httpServer = http.createServer();
         await createApp({
             mcpServer: this,
@@ -283,27 +382,7 @@ export class McpServer extends McpServerBaseOmitted {
             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 serverUrl = resolveServerOrigin(header);
         const connectDomains = [serverUrl];
         if (!isProduction) {
             const wsUrl = new URL(serverUrl);
@@ -445,6 +524,7 @@ export class McpServer extends McpServerBaseOmitted {
             }, 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 { serverUrl } = this.resolveViewRequestContext(extra);