skybridge 0.0.0-dev.9b039a8 → 0.0.0-dev.9b61b33

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
@@ -18,7 +19,11 @@ export type ToolDef<TInput = unknown, TOutput = unknown, TResponseMetadata = unk
     output: TOutput;
     responseMetadata: TResponseMetadata;
 };
-/** Which host runtime a view targets — `"apps-sdk"` (ChatGPT) or `"mcp-app"` (MCP Apps spec). */
+/**
+ * @deprecated Views now always emit a single ext-apps resource; host targeting
+ * no longer applies. Retained for backwards compatibility; will be removed in a
+ * future major.
+ */
 export type ViewHostType = "apps-sdk" | "mcp-app";
 /**
  * Content Security Policy origins attached to a view's resource. Each list is
@@ -44,8 +49,16 @@ export interface ViewCsp {
  */
 export interface ViewNameRegistry {
 }
+/**
+ * Resolve view component names from a registry: the union of its keys, or
+ * `string` when the registry is empty. The empty case happens before
+ * `.skybridge/views.d.ts` is generated; falling back to `string` keeps valid
+ * view names from erroring on a fresh checkout, and narrowing kicks in once
+ * the generated file augments the registry.
+ */
+export type ViewNameFor<Registry> = [keyof Registry & string] extends [never] ? string : keyof Registry & string;
 /** Union of valid view component names. Narrowed by {@link ViewNameRegistry}. */
-export type ViewName = keyof ViewNameRegistry & string;
+export type ViewName = ViewNameFor<ViewNameRegistry>;
 /**
  * Pass under `view` in a tool's `registerTool` config to render the tool's
  * result through a Skybridge view instead of a plain text response.
@@ -55,11 +68,14 @@ export interface ViewConfig {
     component: ViewName;
     /** Human-readable label the host may show alongside the view. */
     description?: string;
-    /** Restrict where the view is rendered. Defaults to all known hosts. */
+    /**
+     * @deprecated No-op. Every view emits a single ext-apps resource regardless
+     * of this value. Will be removed in a future major.
+     */
     hosts?: ViewHostType[];
-    /** Apps SDK only: request a visible border around the widget. */
+    /** Request a visible border around the view (forwarded as `ui.prefersBorder`). */
     prefersBorder?: boolean;
-    /** Apps SDK only: override the iframe's served domain (advanced). */
+    /** Override the iframe's served domain (advanced; forwarded as `ui.domain`). */
     domain?: string;
     /** Per-view CSP overrides — see {@link ViewCsp}. */
     csp?: ViewCsp;
@@ -72,6 +88,21 @@ export type SecurityScheme = {
     type: "oauth2";
     scopes?: string[];
 };
+export type ToolAuth = "public" | "required" | {
+    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.
@@ -141,6 +172,7 @@ interface ToolConfig<TInput extends ZodRawShapeCompat | AnySchema> {
     outputSchema?: ZodRawShapeCompat | AnySchema;
     annotations?: ToolAnnotations;
     view?: ViewConfig;
+    auth?: ToolAuth;
     /**
      * Declares which auth schemes this tool supports (e.g. `noauth`, `oauth2`).
      * Lets clients label tools that require sign-in before calling, and pass
@@ -215,7 +247,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.
      *
@@ -228,10 +262,20 @@ 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);
+    private oauthEnabled;
+    private acceptsAnonymous;
+    private securitySchemesByTool;
+    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
@@ -328,6 +372,7 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
     private resolveViewRequestContext;
     private registerViewResources;
     private registerViewResource;
+    private serveLegacyAppsSdkUrl;
     private wrapHandler;
     private computeViewVersionParam;
     private lookupViewFile;

package/dist/server/server.js

@@ -6,9 +6,12 @@ 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 { authToSecuritySchemes, securitySchemesAllowAnonymous, } from "./auth/security-schemes.js";
+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 +20,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;
@@ -87,7 +99,9 @@ export class McpServer extends McpServerBaseOmitted {
      * 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.
      *
@@ -100,15 +114,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) {
+    oauthEnabled = false;
+    acceptsAnonymous = false;
+    securitySchemesByTool = new Map();
+    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) {
+            this.oauthEnabled = true;
+            setupOAuth(this.express, skybridgeOptions.oauth, {
+                acceptsAnonymous: () => this.acceptsAnonymous,
+                securitySchemesForTool: (name) => this.securitySchemesByTool.has(name)
+                    ? { schemes: this.securitySchemesByTool.get(name) }
+                    : undefined,
+            });
+        }
         // 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.
@@ -190,10 +223,61 @@ 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) === stripQuery(canonical)) {
+                            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 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) {
@@ -322,27 +406,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);
@@ -366,111 +430,74 @@ export class McpServer extends McpServerBaseOmitted {
         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://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,
+        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,
                         },
-                        "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 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;
@@ -484,6 +511,8 @@ export class McpServer extends McpServerBaseOmitted {
             }, contentMetaOverrides);
         };
         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);
@@ -506,6 +535,11 @@ export class McpServer extends McpServerBaseOmitted {
             };
         });
     }
+    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);
+    }
     wrapHandler(cb, { attachViewUUID }) {
         return async (args, extra) => {
             const result = await cb(args, extra);
@@ -578,8 +612,20 @@ export class McpServer extends McpServerBaseOmitted {
         }
         const config = args[0];
         const cb = args[1];
-        const { name, view, securitySchemes, _meta: userToolMeta, ...toolFields } = config;
+        const { name, view, auth, securitySchemes: rawSecuritySchemes, _meta: userToolMeta, ...toolFields } = config;
+        if (auth !== undefined) {
+            if (rawSecuritySchemes) {
+                throw new Error(`Tool "${name}" sets both \`auth\` and \`securitySchemes\`; use one.`);
+            }
+            if (!this.oauthEnabled) {
+                throw new Error(`Tool "${name}" sets \`auth\` but the server has no \`oauth\` provider configured.`);
+            }
+        }
+        const securitySchemes = auth
+            ? authToSecuritySchemes(auth)
+            : rawSecuritySchemes;
         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
@@ -587,6 +633,9 @@ export class McpServer extends McpServerBaseOmitted {
             // `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 (securitySchemesAllowAnonymous(securitySchemes)) {
+                this.acceptsAnonymous = true;
+            }
         }
         if (view) {
             this.enforceOneToolPerView(view.component, name);