skybridge 2.0.0-beta.78ceed1 → 2.0.0-beta.dba0bc8

package/dist/server/app.d.ts

@@ -1,65 +1,89 @@
 import type { Implementation, Server as SdkServer, ServerOptions } from "@modelcontextprotocol/server";
 import type { ErrorRequestHandler, Express, RequestHandler } from "express";
+import type { OAuthConfig } from "./auth/index.js";
 import type { ExtraClaims } from "./auth.js";
-import { McpServer, type McpServerTypes, type SkybridgeServerOptions, type ToolDef } from "./server.js";
+import { type JsonOptions, McpServer, type McpServerTypes, type ToolDef } from "./server.js";
 /**
- * Everything a Skybridge app needs in one bag: the MCP implementation info
- * (`name`, `version`, …), the SDK's {@link ServerOptions} (`capabilities`,
- * `instructions`, …), and the Skybridge-specific options (`oauth`, `json`,
- * `skills`).
- */
-export type SkybridgeConfig<TAuthExtra extends ExtraClaims = ExtraClaims> = Implementation & ServerOptions & SkybridgeServerOptions<TAuthExtra>;
-/**
- * The bare {@link McpServer} a {@link SkybridgeFactory} receives: no tools
- * registered yet. Use it to annotate a factory extracted into its own
+ * The bare {@link McpServer} a {@link SkybridgeHandler} receives: no tools
+ * registered yet. Use it to annotate a handler extracted into its own
  * declaration — `(server: SkybridgeServer) => server.registerTool(…)` — and
  * pass the claims your OAuth verifier produces to type
- * `extra.http.authInfo.extra` in handlers. Leave the factory's return type
+ * `extra.http.authInfo.extra` in handlers. Leave the handler's return type
  * inferred: the returned chain is what carries the tool registry into
  * `typeof app`.
  */
 export type SkybridgeServer<TAuthExtra extends ExtraClaims = ExtraClaims> = McpServer<Record<never, ToolDef>, TAuthExtra>;
 /**
- * Builds an app's MCP surface. Runs again for **every incoming request**, on a
- * fresh {@link McpServer}, so keep it to registration: hoist pools, timers,
- * clients and any other side effect to module scope and close over them.
+ * The `handler` field of {@link SkybridgeConfig}: builds the app's MCP
+ * surface. Runs again for **every incoming request**, on a fresh
+ * {@link McpServer}, so keep it to registration: hoist pools, timers, clients
+ * and any other side effect to module scope (or into `setup`) and close over
+ * them. It must **return** the chained server so `typeof app` carries the
+ * registered tool types.
  *
- * It must **return** the chained server so `typeof app` carries the registered
- * tool types.
+ * @typeParam TContext - What `setup` resolved to, passed as the second argument.
  */
-export type SkybridgeFactory<TTools extends Record<string, ToolDef>, TAuthExtra extends ExtraClaims> = (server: McpServer<Record<never, ToolDef>, TAuthExtra>) => McpServer<TTools, TAuthExtra>;
+export type SkybridgeHandler<TTools extends Record<string, ToolDef>, TContext, TAuthExtra extends ExtraClaims> = (server: McpServer<Record<never, ToolDef>, TAuthExtra>, context: TContext) => McpServer<TTools, TAuthExtra>;
 /**
- * Async alternative to passing a {@link SkybridgeFactory} directly: a zero-arg
- * function that loads whatever the factory needs (remote config, secrets, …)
- * and resolves to it. It runs once — at {@link Skybridge.run} or on the first
- * request, never at module import — so importing `server.ts` from tests and
- * evals stays free of side effects. The factory it returns is still
- * synchronous and still runs per request.
+ * What the `oauth` field accepts: a resolved {@link OAuthConfig}, a promise of
+ * one (the branded providers are async), or a function of the `setup` result.
+ * A function or promise is resolved once — at {@link Skybridge.run} or on the
+ * first request, never at module import — so prefer a function when building
+ * the config has side effects (network discovery, secrets).
+ */
+export type SkybridgeOAuthInput<TContext, TExtra extends ExtraClaims> = OAuthConfig<TExtra> | Promise<OAuthConfig<TExtra>> | ((context: TContext) => OAuthConfig<TExtra> | Promise<OAuthConfig<TExtra>>);
+/**
+ * Everything a Skybridge app needs in one bag: the MCP implementation info
+ * (`name`, `version`, …), the SDK's {@link ServerOptions} (`capabilities`,
+ * `instructions`, …), the Express and skills options, and the app's behavior
+ * (`setup`, `oauth`, `handler`).
+ *
+ * All type parameters are inferred from the value: the context from `setup`,
+ * the auth claims from `oauth`, and the tool registry from the server
+ * `handler` returns.
  */
-export type SkybridgeFactoryLoader<TTools extends Record<string, ToolDef>, TAuthExtra extends ExtraClaims> = () => Promise<SkybridgeFactory<TTools, TAuthExtra>>;
+export type SkybridgeConfig<TTools extends Record<string, ToolDef> = Record<never, ToolDef>, TContext = undefined, TAuthExtra extends ExtraClaims = ExtraClaims> = Implementation & ServerOptions & {
+    /** Options for the built-in `express.json()` middleware, e.g. `{ limit: "10mb" }`. */
+    json?: JsonOptions;
+    /**
+     * @experimental Serve Agent Skills from `src/skills` over MCP (SEP-2640).
+     * API may change.
+     */
+    skills?: boolean;
+    /**
+     * Loads whatever the app needs up front (remote config, secrets, datasets,
+     * …). Runs **once** — at {@link Skybridge.run} or on the first request,
+     * never at module import — and its awaited return value is passed to an
+     * `oauth` function and to `handler` as the second argument.
+     */
+    setup?: () => TContext;
+    /**
+     * Resource-server OAuth. When set, mounts the well-known metadata routes
+     * and bearer auth on `/mcp`, and the verifier's claims type
+     * `extra.http.authInfo.extra` in tool handlers.
+     */
+    oauth?: SkybridgeOAuthInput<Awaited<TContext>, TAuthExtra>;
+    /** Registers the MCP surface, per request. See {@link SkybridgeHandler}. */
+    handler: SkybridgeHandler<TTools, Awaited<TContext>, TAuthExtra>;
+};
 /**
  * A Skybridge app: the HTTP surface (Express, OAuth metadata, the `/mcp`
- * route) plus a factory that builds the MCP server for each request.
+ * route) plus a handler that builds the MCP server for each request.
  *
- * The factory runs for every request, so tools, resources, prompts and views
+ * The handler runs for every request, so tools, resources, prompts and views
  * are always registered on the instance that serves the request. Anything in
- * the factory body other than registration therefore runs per request too.
- * It also runs once up front — at construction, or as soon as an async
- * loader resolves — which surfaces registration errors at boot and gives the
- * OAuth layer the set of per-tool security schemes.
- *
- * Anything asynchronous the factory needs (remote config, secrets, …) goes in
- * a {@link SkybridgeFactoryLoader} passed in its place:
- * `new Skybridge(config, async () => { const cfg = await load(); return (server) => …; })`.
- *
- * @typeParam TTools - Accumulated tool registry, inferred from the server the
- * factory returns. You almost never set this manually.
+ * the handler body other than registration therefore runs per request too.
+ * Anything asynchronous the app needs (remote config, secrets, …) goes in
+ * `setup`, which runs once and feeds the handler's second argument.
  *
  * @example
  * ```ts
- * export const app = new Skybridge(
- *   { name: "my-app", version: "1.0.0", capabilities: {} },
- *   (server) =>
+ * export const app = new Skybridge({
+ *   name: "my-app",
+ *   version: "1.0.0",
+ *   setup: async () => loadConfig(),
+ *   oauth: (config) => descopeProvider({ url: config.mcpServerUrl }),
+ *   handler: (server, config) =>
  *     server.registerTool(
  *       {
  *         name: "search",
@@ -68,40 +92,45 @@ export type SkybridgeFactoryLoader<TTools extends Record<string, ToolDef>, TAuth
  *       },
  *       async ({ query }) => ({ content: `Results for ${query}` }),
  *     ),
- * );
+ * });
  *
  * export type AppType = typeof app;
  * ```
  *
  * @see https://docs.skybridge.tech/api-reference/mcp-server
  */
-export declare class Skybridge<TTools extends Record<string, ToolDef> = Record<never, ToolDef>, TAuthExtra extends ExtraClaims = ExtraClaims> {
+export declare class Skybridge<TTools extends Record<string, ToolDef> = Record<never, ToolDef>, TContext = undefined, TAuthExtra extends ExtraClaims = ExtraClaims> {
     readonly $types: McpServerTypes<TTools>;
     private readonly serverInfo;
     private readonly serverOptions;
-    private readonly skybridgeOptions;
-    private factory?;
-    private readonly factoryLoader?;
+    private readonly skills?;
+    private oauthEnabled;
+    private readonly handler;
+    private readonly setup?;
+    private readonly oauthInput?;
+    private context?;
     private readonly expressApp;
     private readonly errorMiddleware;
     private readonly monitoringEntry;
     private resolveResourceMetadataUrl?;
-    private ready?;
-    private slowFactoryWarned;
-    constructor(config: SkybridgeConfig<TAuthExtra>, factory: SkybridgeFactory<TTools, TAuthExtra> | SkybridgeFactoryLoader<TTools, TAuthExtra>);
+    private readyPromise?;
+    private slowHandlerWarned;
+    constructor(config: SkybridgeConfig<TTools, TContext, TAuthExtra>);
     /**
-     * Resolve the factory loader and the OAuth config thunk, then wire OAuth
-     * onto the Express app. Runs once; every entry point that needs a built
-     * server awaits it. Immediate no-op when both were passed synchronously.
+     * Resolve `setup` and `oauth`, then wire OAuth onto the Express app. Runs
+     * once; every entry point that needs a built server awaits it, and a failed
+     * attempt is retried on the next call.
+     *
+     * @internal
      */
-    private ensureReady;
+    ready(): Promise<void>;
     /**
      * The underlying Express app. Use this to extend the HTTP server with
      * custom routes, middleware, or settings — e.g.
      * `app.express.get("/health", ...)`.
      *
      * `express.json()` is pre-applied — tune it via the `json` config field,
-     * e.g. `new Skybridge({ name, version, json: { limit: "10mb" } }, setup)`.
+     * e.g. `new Skybridge({ name, version, json: { limit: "10mb" }, handler })`.
      * Register your handlers before `run()`; after `run()`, dev-mode middleware,
      * the `/mcp` route, and the default error handler are appended in that order.
      *
@@ -111,13 +140,13 @@ export declare class Skybridge<TTools extends Record<string, ToolDef> = Record<n
     get express(): Express;
     /**
      * Build a fresh server for one stateless HTTP request, as
-     * `createMcpHandler`'s factory contract requires: the factory runs again so
+     * `createMcpHandler`'s factory contract requires: the handler runs again so
      * the SDK's handler closures belong to the instance whose protocol era it
      * stamps. Sharing one instance's handler maps instead would bind them to an
      * instance that is never marked, pinning every request to the 2025 codec and
      * letting concurrent callers overwrite each other's negotiated version.
      *
-     * Awaits the async factory loader and the lazy OAuth config on first use.
+     * Awaits `setup` and the `oauth` input on first use.
      */
     createServerInstance(): Promise<SdkServer>;
     /**

package/dist/server/app.js

@@ -1,33 +1,28 @@
 import http from "node:http";
 import { setupOAuth } from "./auth/setup.js";
-import { createApp, createBaseApp, getMcpHandler } from "./express.js";
+import { buildMcpHandler, createApp, createBaseApp } from "./express.js";
 import { createMiddlewareEntry } from "./metric.js";
 import { buildMiddlewareChain, getHandlerMaps } from "./middleware.js";
 import { McpServer, } from "./server.js";
-const SLOW_FACTORY_THRESHOLD_MS = 50;
+const SLOW_HANDLER_THRESHOLD_MS = 50;
 /**
  * A Skybridge app: the HTTP surface (Express, OAuth metadata, the `/mcp`
- * route) plus a factory that builds the MCP server for each request.
+ * route) plus a handler that builds the MCP server for each request.
  *
- * The factory runs for every request, so tools, resources, prompts and views
+ * The handler runs for every request, so tools, resources, prompts and views
  * are always registered on the instance that serves the request. Anything in
- * the factory body other than registration therefore runs per request too.
- * It also runs once up front — at construction, or as soon as an async
- * loader resolves — which surfaces registration errors at boot and gives the
- * OAuth layer the set of per-tool security schemes.
- *
- * Anything asynchronous the factory needs (remote config, secrets, …) goes in
- * a {@link SkybridgeFactoryLoader} passed in its place:
- * `new Skybridge(config, async () => { const cfg = await load(); return (server) => …; })`.
- *
- * @typeParam TTools - Accumulated tool registry, inferred from the server the
- * factory returns. You almost never set this manually.
+ * the handler body other than registration therefore runs per request too.
+ * Anything asynchronous the app needs (remote config, secrets, …) goes in
+ * `setup`, which runs once and feeds the handler's second argument.
  *
  * @example
  * ```ts
- * export const app = new Skybridge(
- *   { name: "my-app", version: "1.0.0", capabilities: {} },
- *   (server) =>
+ * export const app = new Skybridge({
+ *   name: "my-app",
+ *   version: "1.0.0",
+ *   setup: async () => loadConfig(),
+ *   oauth: (config) => descopeProvider({ url: config.mcpServerUrl }),
+ *   handler: (server, config) =>
  *     server.registerTool(
  *       {
  *         name: "search",
@@ -36,7 +31,7 @@ const SLOW_FACTORY_THRESHOLD_MS = 50;
  *       },
  *       async ({ query }) => ({ content: `Results for ${query}` }),
  *     ),
- * );
+ * });
  *
  * export type AppType = typeof app;
  * ```
@@ -46,56 +41,53 @@ const SLOW_FACTORY_THRESHOLD_MS = 50;
 export class Skybridge {
     serverInfo;
     serverOptions;
-    skybridgeOptions;
-    factory;
-    factoryLoader;
+    skills;
+    oauthEnabled = false;
+    handler;
+    setup;
+    oauthInput;
+    context;
     expressApp;
     errorMiddleware = [];
     monitoringEntry = createMiddlewareEntry();
     resolveResourceMetadataUrl;
-    ready;
-    slowFactoryWarned = false;
-    constructor(config, factory) {
-        const { name, title, version, description, icons, websiteUrl, json, oauth, skills, ...serverOptions } = config;
+    readyPromise;
+    slowHandlerWarned = false;
+    constructor(config) {
+        const { name, title, version, description, icons, websiteUrl, json, skills, setup, oauth, handler, ...serverOptions } = config;
         this.serverInfo = { name, title, version, description, icons, websiteUrl };
         this.serverOptions = serverOptions;
-        this.skybridgeOptions = { json, oauth, skills };
+        this.skills = skills;
+        this.setup = setup;
+        this.oauthInput = oauth;
+        this.handler = handler;
         this.expressApp = createBaseApp(json);
-        if (factory.length === 0) {
-            this.factoryLoader = factory;
-            return;
-        }
-        this.factory = factory;
-        if (typeof oauth === "function") {
-            return;
-        }
-        const sample = this.buildServer();
-        if (oauth) {
-            this.resolveResourceMetadataUrl = setupOAuth(this.expressApp, oauth, sample.securitySchemesByTool);
-        }
-        this.ready = Promise.resolve();
     }
     /**
-     * Resolve the factory loader and the OAuth config thunk, then wire OAuth
-     * onto the Express app. Runs once; every entry point that needs a built
-     * server awaits it. Immediate no-op when both were passed synchronously.
+     * Resolve `setup` and `oauth`, then wire OAuth onto the Express app. Runs
+     * once; every entry point that needs a built server awaits it, and a failed
+     * attempt is retried on the next call.
+     *
+     * @internal
      */
-    ensureReady() {
-        this.ready ??= (async () => {
-            if (this.factoryLoader) {
-                this.factory = await this.factoryLoader();
+    ready() {
+        this.readyPromise ??= (async () => {
+            if (this.setup) {
+                this.context = await this.setup();
             }
-            const { oauth } = this.skybridgeOptions;
-            const resolvedOauth = typeof oauth === "function" ? await oauth() : oauth;
+            const oauth = typeof this.oauthInput === "function"
+                ? await this.oauthInput(this.context)
+                : await this.oauthInput;
+            this.oauthEnabled = Boolean(oauth);
             const sample = this.buildServer();
-            if (resolvedOauth) {
-                this.resolveResourceMetadataUrl = setupOAuth(this.expressApp, resolvedOauth, sample.securitySchemesByTool);
+            if (oauth) {
+                this.resolveResourceMetadataUrl = setupOAuth(this.expressApp, oauth, sample.securitySchemesByTool);
             }
         })().catch((error) => {
-            this.ready = undefined;
+            this.readyPromise = undefined;
             throw error;
         });
-        return this.ready;
+        return this.readyPromise;
     }
     /**
      * The underlying Express app. Use this to extend the HTTP server with
@@ -103,7 +95,7 @@ export class Skybridge {
      * `app.express.get("/health", ...)`.
      *
      * `express.json()` is pre-applied — tune it via the `json` config field,
-     * e.g. `new Skybridge({ name, version, json: { limit: "10mb" } }, setup)`.
+     * e.g. `new Skybridge({ name, version, json: { limit: "10mb" }, handler })`.
      * Register your handlers before `run()`; after `run()`, dev-mode middleware,
      * the `/mcp` route, and the default error handler are appended in that order.
      *
@@ -115,16 +107,16 @@ export class Skybridge {
     }
     /**
      * Build a fresh server for one stateless HTTP request, as
-     * `createMcpHandler`'s factory contract requires: the factory runs again so
+     * `createMcpHandler`'s factory contract requires: the handler runs again so
      * the SDK's handler closures belong to the instance whose protocol era it
      * stamps. Sharing one instance's handler maps instead would bind them to an
      * instance that is never marked, pinning every request to the 2025 codec and
      * letting concurrent callers overwrite each other's negotiated version.
      *
-     * Awaits the async factory loader and the lazy OAuth config on first use.
+     * Awaits `setup` and the `oauth` input on first use.
      */
     async createServerInstance() {
-        await this.ensureReady();
+        await this.ready();
         const server = this.buildServer();
         this.instrumentHandlers(server);
         return server.server;
@@ -174,7 +166,6 @@ export class Skybridge {
      * wait on instead of polling.
      */
     async run() {
-        await this.ensureReady();
         if (process.env.VERCEL === "1") {
             // createApp only reads httpServer inside its dev-only branch
             // (viewsDevServer); under VERCEL=1 + NODE_ENV=production it's a
@@ -188,9 +179,11 @@ export class Skybridge {
             return this.expressApp;
         }
         const httpServer = http.createServer();
+        const mcpHandler = buildMcpHandler(this);
         await createApp({
             app: this,
             httpServer,
+            mcpHandler,
             errorMiddleware: this.errorMiddleware,
         });
         httpServer.on("request", this.expressApp);
@@ -220,9 +213,7 @@ export class Skybridge {
             // (force-quit on a second Ctrl+C while drain is hanging).
             process.off("SIGTERM", shutdown);
             process.off("SIGINT", shutdown);
-            getMcpHandler(this)
-                .close()
-                .catch(() => { });
+            mcpHandler.close().catch(() => { });
             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).
@@ -233,22 +224,19 @@ export class Skybridge {
         return undefined;
     }
     buildServer() {
-        if (!this.factory) {
-            throw new Error("Skybridge factory not loaded yet: this app was constructed with an async factory loader. Await run(), connect(), or createServerInstance().");
-        }
-        const server = new McpServer(this.serverInfo, this.serverOptions, this.skybridgeOptions);
+        const server = new McpServer(this.serverInfo, this.serverOptions, { skills: this.skills, oauth: this.oauthEnabled });
         if (this.resolveResourceMetadataUrl) {
             server.setResourceMetadataUrlResolver(this.resolveResourceMetadataUrl);
         }
         const startedAt = performance.now();
-        const built = this.factory(server);
+        const built = this.handler(server, this.context);
         const elapsed = performance.now() - startedAt;
         if (typeof built.then === "function") {
-            throw new Error("The Skybridge factory must be synchronous — it runs on every request. To load config or secrets asynchronously, pass a loader instead: new Skybridge(config, async () => factory).");
+            throw new Error("The Skybridge handler must be synchronous — it runs on every request. Load config or secrets in `setup` instead and read them from the handler's second argument.");
         }
-        if (elapsed > SLOW_FACTORY_THRESHOLD_MS && !this.slowFactoryWarned) {
-            this.slowFactoryWarned = true;
-            console.warn(`The Skybridge factory took ${Math.round(elapsed)}ms — it runs on every request, so this cost is paid per request. Hoist expensive work to module scope, or move awaited setup into an async loader: new Skybridge(config, async () => factory).`);
+        if (elapsed > SLOW_HANDLER_THRESHOLD_MS && !this.slowHandlerWarned) {
+            this.slowHandlerWarned = true;
+            console.warn(`The Skybridge handler took ${Math.round(elapsed)}ms — it runs on every request, so this cost is paid per request. Hoist expensive work to module scope or into \`setup\`, whose result is passed to the handler.`);
         }
         return built;
     }

package/dist/server/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/server/app.ts"],"names":[],"mappings":"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","sourcesContent":["import http from \"node:http\";\nimport type { AddressInfo } from \"node:net\";\nimport type {\n  Implementation,\n  Server as SdkServer,\n  ServerOptions,\n} from \"@modelcontextprotocol/server\";\nimport type { ErrorRequestHandler, Express, RequestHandler } from \"express\";\nimport { type ResourceMetadataUrlResolver, setupOAuth } from \"./auth/setup.js\";\nimport type { ExtraClaims } from \"./auth.js\";\nimport { createApp, createBaseApp, getMcpHandler } from \"./express.js\";\nimport { createMiddlewareEntry } from \"./metric.js\";\nimport type { McpMiddlewareEntry } from \"./middleware.js\";\nimport { buildMiddlewareChain, getHandlerMaps } from \"./middleware.js\";\nimport {\n  McpServer,\n  type McpServerTypes,\n  type SkybridgeServerOptions,\n  type ToolDef,\n} from \"./server.js\";\n\nconst SLOW_FACTORY_THRESHOLD_MS = 50;\n\ntype ErrorMiddlewareConfig = {\n  path?: string;\n  handlers: ErrorRequestHandler[];\n};\n\n/**\n * Everything a Skybridge app needs in one bag: the MCP implementation info\n * (`name`, `version`, …), the SDK's {@link ServerOptions} (`capabilities`,\n * `instructions`, …), and the Skybridge-specific options (`oauth`, `json`,\n * `skills`).\n */\nexport type SkybridgeConfig<TAuthExtra extends ExtraClaims = ExtraClaims> =\n  Implementation & ServerOptions & SkybridgeServerOptions<TAuthExtra>;\n\n/**\n * The bare {@link McpServer} a {@link SkybridgeFactory} receives: no tools\n * registered yet. Use it to annotate a factory extracted into its own\n * declaration — `(server: SkybridgeServer) => server.registerTool(…)` — and\n * pass the claims your OAuth verifier produces to type\n * `extra.http.authInfo.extra` in handlers. Leave the factory's return type\n * inferred: the returned chain is what carries the tool registry into\n * `typeof app`.\n */\nexport type SkybridgeServer<TAuthExtra extends ExtraClaims = ExtraClaims> =\n  McpServer<Record<never, ToolDef>, TAuthExtra>;\n\n/**\n * Builds an app's MCP surface. Runs again for **every incoming request**, on a\n * fresh {@link McpServer}, so keep it to registration: hoist pools, timers,\n * clients and any other side effect to module scope and close over them.\n *\n * It must **return** the chained server so `typeof app` carries the registered\n * tool types.\n */\nexport type SkybridgeFactory<\n  TTools extends Record<string, ToolDef>,\n  TAuthExtra extends ExtraClaims,\n> = (\n  server: McpServer<Record<never, ToolDef>, TAuthExtra>,\n) => McpServer<TTools, TAuthExtra>;\n\n/**\n * Async alternative to passing a {@link SkybridgeFactory} directly: a zero-arg\n * function that loads whatever the factory needs (remote config, secrets, …)\n * and resolves to it. It runs once — at {@link Skybridge.run} or on the first\n * request, never at module import — so importing `server.ts` from tests and\n * evals stays free of side effects. The factory it returns is still\n * synchronous and still runs per request.\n */\nexport type SkybridgeFactoryLoader<\n  TTools extends Record<string, ToolDef>,\n  TAuthExtra extends ExtraClaims,\n> = () => Promise<SkybridgeFactory<TTools, TAuthExtra>>;\n\n/**\n * A Skybridge app: the HTTP surface (Express, OAuth metadata, the `/mcp`\n * route) plus a factory that builds the MCP server for each request.\n *\n * The factory runs for every request, so tools, resources, prompts and views\n * are always registered on the instance that serves the request. Anything in\n * the factory body other than registration therefore runs per request too.\n * It also runs once up front — at construction, or as soon as an async\n * loader resolves — which surfaces registration errors at boot and gives the\n * OAuth layer the set of per-tool security schemes.\n *\n * Anything asynchronous the factory needs (remote config, secrets, …) goes in\n * a {@link SkybridgeFactoryLoader} passed in its place:\n * `new Skybridge(config, async () => { const cfg = await load(); return (server) => …; })`.\n *\n * @typeParam TTools - Accumulated tool registry, inferred from the server the\n * factory returns. You almost never set this manually.\n *\n * @example\n * ```ts\n * export const app = new Skybridge(\n *   { name: \"my-app\", version: \"1.0.0\", capabilities: {} },\n *   (server) =>\n *     server.registerTool(\n *       {\n *         name: \"search\",\n *         inputSchema: { query: z.string() },\n *         view: { component: \"search\" },\n *       },\n *       async ({ query }) => ({ content: `Results for ${query}` }),\n *     ),\n * );\n *\n * export type AppType = typeof app;\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/mcp-server\n */\nexport class Skybridge<\n  TTools extends Record<string, ToolDef> = Record<never, ToolDef>,\n  TAuthExtra extends ExtraClaims = ExtraClaims,\n> {\n  declare readonly $types: McpServerTypes<TTools>;\n  private readonly serverInfo: Implementation;\n  private readonly serverOptions: ServerOptions;\n  private readonly skybridgeOptions: SkybridgeServerOptions<TAuthExtra>;\n  private factory?: SkybridgeFactory<TTools, TAuthExtra>;\n  private readonly factoryLoader?: SkybridgeFactoryLoader<TTools, TAuthExtra>;\n  private readonly expressApp: Express;\n  private readonly errorMiddleware: ErrorMiddlewareConfig[] = [];\n  private readonly monitoringEntry: McpMiddlewareEntry | null =\n    createMiddlewareEntry();\n  private resolveResourceMetadataUrl?: ResourceMetadataUrlResolver;\n  private ready?: Promise<void>;\n  private slowFactoryWarned = false;\n\n  constructor(\n    config: SkybridgeConfig<TAuthExtra>,\n    factory:\n      | SkybridgeFactory<TTools, TAuthExtra>\n      | SkybridgeFactoryLoader<TTools, TAuthExtra>,\n  ) {\n    const {\n      name,\n      title,\n      version,\n      description,\n      icons,\n      websiteUrl,\n      json,\n      oauth,\n      skills,\n      ...serverOptions\n    } = config;\n\n    this.serverInfo = { name, title, version, description, icons, websiteUrl };\n    this.serverOptions = serverOptions;\n    this.skybridgeOptions = { json, oauth, skills };\n    this.expressApp = createBaseApp(json);\n\n    if (factory.length === 0) {\n      this.factoryLoader = factory as SkybridgeFactoryLoader<\n        TTools,\n        TAuthExtra\n      >;\n      return;\n    }\n    this.factory = factory as SkybridgeFactory<TTools, TAuthExtra>;\n\n    if (typeof oauth === \"function\") {\n      return;\n    }\n\n    const sample = this.buildServer();\n    if (oauth) {\n      this.resolveResourceMetadataUrl = setupOAuth(\n        this.expressApp,\n        oauth,\n        sample.securitySchemesByTool,\n      );\n    }\n    this.ready = Promise.resolve();\n  }\n\n  /**\n   * Resolve the factory loader and the OAuth config thunk, then wire OAuth\n   * onto the Express app. Runs once; every entry point that needs a built\n   * server awaits it. Immediate no-op when both were passed synchronously.\n   */\n  private ensureReady(): Promise<void> {\n    this.ready ??= (async () => {\n      if (this.factoryLoader) {\n        this.factory = await this.factoryLoader();\n      }\n      const { oauth } = this.skybridgeOptions;\n      const resolvedOauth = typeof oauth === \"function\" ? await oauth() : oauth;\n      const sample = this.buildServer();\n      if (resolvedOauth) {\n        this.resolveResourceMetadataUrl = setupOAuth(\n          this.expressApp,\n          resolvedOauth,\n          sample.securitySchemesByTool,\n        );\n      }\n    })().catch((error) => {\n      this.ready = undefined;\n      throw error;\n    });\n    return this.ready;\n  }\n\n  /**\n   * The underlying Express app. Use this to extend the HTTP server with\n   * custom routes, middleware, or settings — e.g.\n   * `app.express.get(\"/health\", ...)`.\n   *\n   * `express.json()` is pre-applied — tune it via the `json` config field,\n   * e.g. `new Skybridge({ name, version, json: { limit: \"10mb\" } }, setup)`.\n   * Register your handlers before `run()`; after `run()`, dev-mode middleware,\n   * the `/mcp` route, and the default error handler are appended in that order.\n   *\n   * Note: Alpic Cloud only routes traffic to `/mcp` — custom routes work\n   * locally and on self-hosted deployments.\n   */\n  get express(): Express {\n    return this.expressApp;\n  }\n\n  /**\n   * Build a fresh server for one stateless HTTP request, as\n   * `createMcpHandler`'s factory contract requires: the factory runs again so\n   * the SDK's handler closures belong to the instance whose protocol era it\n   * stamps. Sharing one instance's handler maps instead would bind them to an\n   * instance that is never marked, pinning every request to the 2025 codec and\n   * letting concurrent callers overwrite each other's negotiated version.\n   *\n   * Awaits the async factory loader and the lazy OAuth config on first use.\n   */\n  async createServerInstance(): Promise<SdkServer> {\n    await this.ensureReady();\n    const server = this.buildServer();\n    this.instrumentHandlers(server);\n    return server.server;\n  }\n\n  /**\n   * Connect a Skybridge app to an MCP transport. Use this when you're\n   * embedding Skybridge in a host that already manages its own transport\n   * (e.g. stdio for desktop apps); for HTTP, prefer {@link Skybridge.run}\n   * which sets the transport up for you.\n   */\n  async connect(transport: Parameters<SdkServer[\"connect\"]>[0]): Promise<void> {\n    const instance = await this.createServerInstance();\n    await instance.connect(transport);\n  }\n\n  /**\n   * Register Express middleware on the underlying app. Mirrors `app.use` —\n   * pass handlers directly or a path-prefixed handler list. Register before\n   * {@link Skybridge.run}; ordering matches Express.\n   *\n   * Note: Alpic Cloud only routes traffic to `/mcp`. Custom paths work\n   * locally and on self-hosted deployments.\n   */\n  use(...handlers: RequestHandler[]): this;\n  use(path: string, ...handlers: RequestHandler[]): this;\n  use(\n    pathOrHandler: string | RequestHandler,\n    ...handlers: RequestHandler[]\n  ): this {\n    // Branching is load-bearing: Express's `app.use` overloads can't be\n    // resolved against a `string | RequestHandler` union, so we narrow.\n    if (typeof pathOrHandler === \"string\") {\n      this.expressApp.use(pathOrHandler, ...handlers);\n    } else {\n      this.expressApp.use(pathOrHandler, ...handlers);\n    }\n    return this;\n  }\n\n  /**\n   * Register Express error-handling middleware to run after the built-in\n   * `/mcp` route (or your custom route). Use this to log or transform errors\n   * thrown by tool handlers before the default error handler responds.\n   *\n   * @example\n   * ```ts\n   * app.useOnError((err, _req, _res, next) => {\n   *   logger.error(err);\n   *   next(err);\n   * });\n   * ```\n   */\n  useOnError(...handlers: ErrorRequestHandler[]): this;\n  useOnError(path: string, ...handlers: ErrorRequestHandler[]): this;\n  useOnError(\n    pathOrHandler: string | ErrorRequestHandler,\n    ...handlers: ErrorRequestHandler[]\n  ): this {\n    if (typeof pathOrHandler === \"string\") {\n      this.errorMiddleware.push({ path: pathOrHandler, handlers });\n    } else {\n      this.errorMiddleware.push({ handlers: [pathOrHandler, ...handlers] });\n    }\n    return this;\n  }\n\n  /**\n   * Start the HTTP server. Listens on `process.env.__PORT` (default `3000`),\n   * mounts the `/mcp` route, and applies any custom Express middleware\n   * registered via {@link Skybridge.use} / {@link Skybridge.useOnError}.\n   *\n   * On Cloudflare Workers / workerd, returns an object exposing `fetch` so\n   * the runtime can bridge incoming requests to the Node HTTP server. On\n   * Vercel (`VERCEL === \"1\"`), returns the Express app directly so the\n   * serverless function entry can call it as a `(req, res)` handler. On\n   * Node, returns `undefined` once listening. When the process was spawned\n   * with an IPC channel, the bound port is reported to the parent as\n   * `{ type: \"skybridge:listening\", port }`, the readiness signal test runners\n   * wait on instead of polling.\n   */\n  async run(): Promise<\n    { fetch: (...args: unknown[]) => unknown } | Express | undefined\n  > {\n    await this.ensureReady();\n\n    if (process.env.VERCEL === \"1\") {\n      // createApp only reads httpServer inside its dev-only branch\n      // (viewsDevServer); under VERCEL=1 + NODE_ENV=production it's a\n      // bare object passed to satisfy the required parameter.\n      const httpServer = http.createServer();\n      await createApp({\n        app: this,\n        httpServer,\n        errorMiddleware: this.errorMiddleware,\n      });\n      return this.expressApp;\n    }\n\n    const httpServer = http.createServer();\n\n    await createApp({\n      app: this,\n      httpServer,\n      errorMiddleware: this.errorMiddleware,\n    });\n\n    httpServer.on(\"request\", this.expressApp);\n    const intendedPort = parseInt(process.env.__PORT ?? \"3000\", 10);\n    await new Promise<void>((resolve, reject) => {\n      httpServer.on(\"error\", (error: Error) => {\n        console.error(\"Failed to start server:\", error);\n        reject(error);\n      });\n      httpServer.listen(intendedPort, () => {\n        resolve();\n      });\n    });\n\n    const { port } = httpServer.address() as AddressInfo;\n    process.send?.({ type: \"skybridge:listening\", port });\n\n    // On workerd, bridge the Node http server to a Workers fetch handler.\n    // The specifier is held in a variable to sidestep tsc's module resolution\n    // (`cloudflare:node` only exists under wrangler/workerd).\n    if (\n      typeof navigator !== \"undefined\" &&\n      navigator.userAgent === \"Cloudflare-Workers\"\n    ) {\n      const cloudflareNode = \"cloudflare:node\";\n      const { httpServerHandler } = await import(cloudflareNode);\n      return httpServerHandler({ port });\n    }\n\n    const shutdown = () => {\n      // Drop both handlers so a second signal falls through to Node's default\n      // (force-quit on a second Ctrl+C while drain is hanging).\n      process.off(\"SIGTERM\", shutdown);\n      process.off(\"SIGINT\", shutdown);\n      getMcpHandler(this)\n        .close()\n        .catch(() => {});\n      httpServer.close(() => process.exit(0));\n      // Force exit if connections don't drain in time so the port is still\n      // released promptly (e.g. for nodemon restarts).\n      setTimeout(() => process.exit(0), 3000).unref();\n    };\n    process.on(\"SIGTERM\", shutdown);\n    process.on(\"SIGINT\", shutdown);\n    return undefined;\n  }\n\n  private buildServer(): McpServer<TTools, TAuthExtra> {\n    if (!this.factory) {\n      throw new Error(\n        \"Skybridge factory not loaded yet: this app was constructed with an async factory loader. Await run(), connect(), or createServerInstance().\",\n      );\n    }\n    const server = new McpServer<Record<never, ToolDef>, TAuthExtra>(\n      this.serverInfo,\n      this.serverOptions,\n      this.skybridgeOptions,\n    );\n    if (this.resolveResourceMetadataUrl) {\n      server.setResourceMetadataUrlResolver(this.resolveResourceMetadataUrl);\n    }\n    const startedAt = performance.now();\n    const built = this.factory(server);\n    const elapsed = performance.now() - startedAt;\n    if (typeof (built as { then?: unknown }).then === \"function\") {\n      throw new Error(\n        \"The Skybridge factory must be synchronous — it runs on every request. To load config or secrets asynchronously, pass a loader instead: new Skybridge(config, async () => factory).\",\n      );\n    }\n    if (elapsed > SLOW_FACTORY_THRESHOLD_MS && !this.slowFactoryWarned) {\n      this.slowFactoryWarned = true;\n      console.warn(\n        `The Skybridge factory took ${Math.round(elapsed)}ms — it runs on every request, so this cost is paid per request. Hoist expensive work to module scope, or move awaited setup into an async loader: new Skybridge(config, async () => factory).`,\n      );\n    }\n    return built;\n  }\n\n  private middlewareEntries(\n    server: McpServer<Record<never, ToolDef>, TAuthExtra>,\n  ): McpMiddlewareEntry[] {\n    return [\n      ...(this.monitoringEntry ? [this.monitoringEntry] : []),\n      ...server.protocolMiddlewareEntries(),\n    ];\n  }\n\n  private instrumentHandlers(\n    server: McpServer<Record<never, ToolDef>, TAuthExtra>,\n  ): void {\n    const entries = this.middlewareEntries(server);\n    const { requestHandlers, notificationHandlers } = getHandlerMaps(\n      server.server,\n    );\n\n    const instrumentMap = (\n      map: Map<string, (...args: unknown[]) => Promise<unknown>>,\n      isNotification: boolean,\n    ) => {\n      for (const [method, handler] of map) {\n        map.set(\n          method,\n          buildMiddlewareChain(method, isNotification, handler, entries),\n        );\n      }\n      const originalSet = map.set.bind(map);\n      map.set = (\n        method: string,\n        handler: (...args: unknown[]) => Promise<unknown>,\n      ) =>\n        originalSet(\n          method,\n          buildMiddlewareChain(method, isNotification, handler, entries),\n        );\n    };\n\n    instrumentMap(requestHandlers, false);\n    instrumentMap(notificationHandlers, true);\n  }\n}\n"]}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/server/app.ts"],"names":[],"mappings":"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","sourcesContent":["import http from \"node:http\";\nimport type { AddressInfo } from \"node:net\";\nimport type {\n  Implementation,\n  Server as SdkServer,\n  ServerOptions,\n} from \"@modelcontextprotocol/server\";\nimport type { ErrorRequestHandler, Express, RequestHandler } from \"express\";\nimport type { OAuthConfig } from \"./auth/index.js\";\nimport { type ResourceMetadataUrlResolver, setupOAuth } from \"./auth/setup.js\";\nimport type { ExtraClaims } from \"./auth.js\";\nimport { buildMcpHandler, createApp, createBaseApp } from \"./express.js\";\nimport { createMiddlewareEntry } from \"./metric.js\";\nimport type { McpMiddlewareEntry } from \"./middleware.js\";\nimport { buildMiddlewareChain, getHandlerMaps } from \"./middleware.js\";\nimport {\n  type JsonOptions,\n  McpServer,\n  type McpServerTypes,\n  type ToolDef,\n} from \"./server.js\";\n\nconst SLOW_HANDLER_THRESHOLD_MS = 50;\n\ntype ErrorMiddlewareConfig = {\n  path?: string;\n  handlers: ErrorRequestHandler[];\n};\n\n/**\n * The bare {@link McpServer} a {@link SkybridgeHandler} receives: no tools\n * registered yet. Use it to annotate a handler extracted into its own\n * declaration — `(server: SkybridgeServer) => server.registerTool(…)` — and\n * pass the claims your OAuth verifier produces to type\n * `extra.http.authInfo.extra` in handlers. Leave the handler's return type\n * inferred: the returned chain is what carries the tool registry into\n * `typeof app`.\n */\nexport type SkybridgeServer<TAuthExtra extends ExtraClaims = ExtraClaims> =\n  McpServer<Record<never, ToolDef>, TAuthExtra>;\n\n/**\n * The `handler` field of {@link SkybridgeConfig}: builds the app's MCP\n * surface. Runs again for **every incoming request**, on a fresh\n * {@link McpServer}, so keep it to registration: hoist pools, timers, clients\n * and any other side effect to module scope (or into `setup`) and close over\n * them. It must **return** the chained server so `typeof app` carries the\n * registered tool types.\n *\n * @typeParam TContext - What `setup` resolved to, passed as the second argument.\n */\nexport type SkybridgeHandler<\n  TTools extends Record<string, ToolDef>,\n  TContext,\n  TAuthExtra extends ExtraClaims,\n> = (\n  server: McpServer<Record<never, ToolDef>, TAuthExtra>,\n  context: TContext,\n) => McpServer<TTools, TAuthExtra>;\n\n/**\n * What the `oauth` field accepts: a resolved {@link OAuthConfig}, a promise of\n * one (the branded providers are async), or a function of the `setup` result.\n * A function or promise is resolved once — at {@link Skybridge.run} or on the\n * first request, never at module import — so prefer a function when building\n * the config has side effects (network discovery, secrets).\n */\nexport type SkybridgeOAuthInput<TContext, TExtra extends ExtraClaims> =\n  | OAuthConfig<TExtra>\n  | Promise<OAuthConfig<TExtra>>\n  | ((context: TContext) => OAuthConfig<TExtra> | Promise<OAuthConfig<TExtra>>);\n\n/**\n * Everything a Skybridge app needs in one bag: the MCP implementation info\n * (`name`, `version`, …), the SDK's {@link ServerOptions} (`capabilities`,\n * `instructions`, …), the Express and skills options, and the app's behavior\n * (`setup`, `oauth`, `handler`).\n *\n * All type parameters are inferred from the value: the context from `setup`,\n * the auth claims from `oauth`, and the tool registry from the server\n * `handler` returns.\n */\nexport type SkybridgeConfig<\n  TTools extends Record<string, ToolDef> = Record<never, ToolDef>,\n  TContext = undefined,\n  TAuthExtra extends ExtraClaims = ExtraClaims,\n> = Implementation &\n  ServerOptions & {\n    /** Options for the built-in `express.json()` middleware, e.g. `{ limit: \"10mb\" }`. */\n    json?: JsonOptions;\n    /**\n     * @experimental Serve Agent Skills from `src/skills` over MCP (SEP-2640).\n     * API may change.\n     */\n    skills?: boolean;\n    /**\n     * Loads whatever the app needs up front (remote config, secrets, datasets,\n     * …). Runs **once** — at {@link Skybridge.run} or on the first request,\n     * never at module import — and its awaited return value is passed to an\n     * `oauth` function and to `handler` as the second argument.\n     */\n    setup?: () => TContext;\n    /**\n     * Resource-server OAuth. When set, mounts the well-known metadata routes\n     * and bearer auth on `/mcp`, and the verifier's claims type\n     * `extra.http.authInfo.extra` in tool handlers.\n     */\n    oauth?: SkybridgeOAuthInput<Awaited<TContext>, TAuthExtra>;\n    /** Registers the MCP surface, per request. See {@link SkybridgeHandler}. */\n    handler: SkybridgeHandler<TTools, Awaited<TContext>, TAuthExtra>;\n  };\n\n/**\n * A Skybridge app: the HTTP surface (Express, OAuth metadata, the `/mcp`\n * route) plus a handler that builds the MCP server for each request.\n *\n * The handler runs for every request, so tools, resources, prompts and views\n * are always registered on the instance that serves the request. Anything in\n * the handler body other than registration therefore runs per request too.\n * Anything asynchronous the app needs (remote config, secrets, …) goes in\n * `setup`, which runs once and feeds the handler's second argument.\n *\n * @example\n * ```ts\n * export const app = new Skybridge({\n *   name: \"my-app\",\n *   version: \"1.0.0\",\n *   setup: async () => loadConfig(),\n *   oauth: (config) => descopeProvider({ url: config.mcpServerUrl }),\n *   handler: (server, config) =>\n *     server.registerTool(\n *       {\n *         name: \"search\",\n *         inputSchema: { query: z.string() },\n *         view: { component: \"search\" },\n *       },\n *       async ({ query }) => ({ content: `Results for ${query}` }),\n *     ),\n * });\n *\n * export type AppType = typeof app;\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/mcp-server\n */\nexport class Skybridge<\n  TTools extends Record<string, ToolDef> = Record<never, ToolDef>,\n  TContext = undefined,\n  TAuthExtra extends ExtraClaims = ExtraClaims,\n> {\n  declare readonly $types: McpServerTypes<TTools>;\n  private readonly serverInfo: Implementation;\n  private readonly serverOptions: ServerOptions;\n  private readonly skills?: boolean;\n  private oauthEnabled = false;\n  private readonly handler: SkybridgeHandler<\n    TTools,\n    Awaited<TContext>,\n    TAuthExtra\n  >;\n  private readonly setup?: () => TContext;\n  private readonly oauthInput?: SkybridgeOAuthInput<\n    Awaited<TContext>,\n    TAuthExtra\n  >;\n  private context?: Awaited<TContext>;\n  private readonly expressApp: Express;\n  private readonly errorMiddleware: ErrorMiddlewareConfig[] = [];\n  private readonly monitoringEntry: McpMiddlewareEntry | null =\n    createMiddlewareEntry();\n  private resolveResourceMetadataUrl?: ResourceMetadataUrlResolver;\n  private readyPromise?: Promise<void>;\n  private slowHandlerWarned = false;\n\n  constructor(config: SkybridgeConfig<TTools, TContext, TAuthExtra>) {\n    const {\n      name,\n      title,\n      version,\n      description,\n      icons,\n      websiteUrl,\n      json,\n      skills,\n      setup,\n      oauth,\n      handler,\n      ...serverOptions\n    } = config;\n\n    this.serverInfo = { name, title, version, description, icons, websiteUrl };\n    this.serverOptions = serverOptions;\n    this.skills = skills;\n    this.setup = setup;\n    this.oauthInput = oauth;\n    this.handler = handler;\n    this.expressApp = createBaseApp(json);\n  }\n\n  /**\n   * Resolve `setup` and `oauth`, then wire OAuth onto the Express app. Runs\n   * once; every entry point that needs a built server awaits it, and a failed\n   * attempt is retried on the next call.\n   *\n   * @internal\n   */\n  ready(): Promise<void> {\n    this.readyPromise ??= (async () => {\n      if (this.setup) {\n        this.context = await this.setup();\n      }\n      const oauth =\n        typeof this.oauthInput === \"function\"\n          ? await this.oauthInput(this.context as Awaited<TContext>)\n          : await this.oauthInput;\n      this.oauthEnabled = Boolean(oauth);\n      const sample = this.buildServer();\n      if (oauth) {\n        this.resolveResourceMetadataUrl = setupOAuth(\n          this.expressApp,\n          oauth,\n          sample.securitySchemesByTool,\n        );\n      }\n    })().catch((error) => {\n      this.readyPromise = undefined;\n      throw error;\n    });\n    return this.readyPromise;\n  }\n\n  /**\n   * The underlying Express app. Use this to extend the HTTP server with\n   * custom routes, middleware, or settings — e.g.\n   * `app.express.get(\"/health\", ...)`.\n   *\n   * `express.json()` is pre-applied — tune it via the `json` config field,\n   * e.g. `new Skybridge({ name, version, json: { limit: \"10mb\" }, handler })`.\n   * Register your handlers before `run()`; after `run()`, dev-mode middleware,\n   * the `/mcp` route, and the default error handler are appended in that order.\n   *\n   * Note: Alpic Cloud only routes traffic to `/mcp` — custom routes work\n   * locally and on self-hosted deployments.\n   */\n  get express(): Express {\n    return this.expressApp;\n  }\n\n  /**\n   * Build a fresh server for one stateless HTTP request, as\n   * `createMcpHandler`'s factory contract requires: the handler runs again so\n   * the SDK's handler closures belong to the instance whose protocol era it\n   * stamps. Sharing one instance's handler maps instead would bind them to an\n   * instance that is never marked, pinning every request to the 2025 codec and\n   * letting concurrent callers overwrite each other's negotiated version.\n   *\n   * Awaits `setup` and the `oauth` input on first use.\n   */\n  async createServerInstance(): Promise<SdkServer> {\n    await this.ready();\n    const server = this.buildServer();\n    this.instrumentHandlers(server);\n    return server.server;\n  }\n\n  /**\n   * Connect a Skybridge app to an MCP transport. Use this when you're\n   * embedding Skybridge in a host that already manages its own transport\n   * (e.g. stdio for desktop apps); for HTTP, prefer {@link Skybridge.run}\n   * which sets the transport up for you.\n   */\n  async connect(transport: Parameters<SdkServer[\"connect\"]>[0]): Promise<void> {\n    const instance = await this.createServerInstance();\n    await instance.connect(transport);\n  }\n\n  /**\n   * Register Express middleware on the underlying app. Mirrors `app.use` —\n   * pass handlers directly or a path-prefixed handler list. Register before\n   * {@link Skybridge.run}; ordering matches Express.\n   *\n   * Note: Alpic Cloud only routes traffic to `/mcp`. Custom paths work\n   * locally and on self-hosted deployments.\n   */\n  use(...handlers: RequestHandler[]): this;\n  use(path: string, ...handlers: RequestHandler[]): this;\n  use(\n    pathOrHandler: string | RequestHandler,\n    ...handlers: RequestHandler[]\n  ): this {\n    // Branching is load-bearing: Express's `app.use` overloads can't be\n    // resolved against a `string | RequestHandler` union, so we narrow.\n    if (typeof pathOrHandler === \"string\") {\n      this.expressApp.use(pathOrHandler, ...handlers);\n    } else {\n      this.expressApp.use(pathOrHandler, ...handlers);\n    }\n    return this;\n  }\n\n  /**\n   * Register Express error-handling middleware to run after the built-in\n   * `/mcp` route (or your custom route). Use this to log or transform errors\n   * thrown by tool handlers before the default error handler responds.\n   *\n   * @example\n   * ```ts\n   * app.useOnError((err, _req, _res, next) => {\n   *   logger.error(err);\n   *   next(err);\n   * });\n   * ```\n   */\n  useOnError(...handlers: ErrorRequestHandler[]): this;\n  useOnError(path: string, ...handlers: ErrorRequestHandler[]): this;\n  useOnError(\n    pathOrHandler: string | ErrorRequestHandler,\n    ...handlers: ErrorRequestHandler[]\n  ): this {\n    if (typeof pathOrHandler === \"string\") {\n      this.errorMiddleware.push({ path: pathOrHandler, handlers });\n    } else {\n      this.errorMiddleware.push({ handlers: [pathOrHandler, ...handlers] });\n    }\n    return this;\n  }\n\n  /**\n   * Start the HTTP server. Listens on `process.env.__PORT` (default `3000`),\n   * mounts the `/mcp` route, and applies any custom Express middleware\n   * registered via {@link Skybridge.use} / {@link Skybridge.useOnError}.\n   *\n   * On Cloudflare Workers / workerd, returns an object exposing `fetch` so\n   * the runtime can bridge incoming requests to the Node HTTP server. On\n   * Vercel (`VERCEL === \"1\"`), returns the Express app directly so the\n   * serverless function entry can call it as a `(req, res)` handler. On\n   * Node, returns `undefined` once listening. When the process was spawned\n   * with an IPC channel, the bound port is reported to the parent as\n   * `{ type: \"skybridge:listening\", port }`, the readiness signal test runners\n   * wait on instead of polling.\n   */\n  async run(): Promise<\n    { fetch: (...args: unknown[]) => unknown } | Express | undefined\n  > {\n    if (process.env.VERCEL === \"1\") {\n      // createApp only reads httpServer inside its dev-only branch\n      // (viewsDevServer); under VERCEL=1 + NODE_ENV=production it's a\n      // bare object passed to satisfy the required parameter.\n      const httpServer = http.createServer();\n      await createApp({\n        app: this,\n        httpServer,\n        errorMiddleware: this.errorMiddleware,\n      });\n      return this.expressApp;\n    }\n\n    const httpServer = http.createServer();\n    const mcpHandler = buildMcpHandler(this);\n\n    await createApp({\n      app: this,\n      httpServer,\n      mcpHandler,\n      errorMiddleware: this.errorMiddleware,\n    });\n\n    httpServer.on(\"request\", this.expressApp);\n    const intendedPort = parseInt(process.env.__PORT ?? \"3000\", 10);\n    await new Promise<void>((resolve, reject) => {\n      httpServer.on(\"error\", (error: Error) => {\n        console.error(\"Failed to start server:\", error);\n        reject(error);\n      });\n      httpServer.listen(intendedPort, () => {\n        resolve();\n      });\n    });\n\n    const { port } = httpServer.address() as AddressInfo;\n    process.send?.({ type: \"skybridge:listening\", port });\n\n    // On workerd, bridge the Node http server to a Workers fetch handler.\n    // The specifier is held in a variable to sidestep tsc's module resolution\n    // (`cloudflare:node` only exists under wrangler/workerd).\n    if (\n      typeof navigator !== \"undefined\" &&\n      navigator.userAgent === \"Cloudflare-Workers\"\n    ) {\n      const cloudflareNode = \"cloudflare:node\";\n      const { httpServerHandler } = await import(cloudflareNode);\n      return httpServerHandler({ port });\n    }\n\n    const shutdown = () => {\n      // Drop both handlers so a second signal falls through to Node's default\n      // (force-quit on a second Ctrl+C while drain is hanging).\n      process.off(\"SIGTERM\", shutdown);\n      process.off(\"SIGINT\", shutdown);\n      mcpHandler.close().catch(() => {});\n      httpServer.close(() => process.exit(0));\n      // Force exit if connections don't drain in time so the port is still\n      // released promptly (e.g. for nodemon restarts).\n      setTimeout(() => process.exit(0), 3000).unref();\n    };\n    process.on(\"SIGTERM\", shutdown);\n    process.on(\"SIGINT\", shutdown);\n    return undefined;\n  }\n\n  private buildServer(): McpServer<TTools, TAuthExtra> {\n    const server = new McpServer<Record<never, ToolDef>, TAuthExtra>(\n      this.serverInfo,\n      this.serverOptions,\n      { skills: this.skills, oauth: this.oauthEnabled },\n    );\n    if (this.resolveResourceMetadataUrl) {\n      server.setResourceMetadataUrlResolver(this.resolveResourceMetadataUrl);\n    }\n    const startedAt = performance.now();\n    const built = this.handler(server, this.context as Awaited<TContext>);\n    const elapsed = performance.now() - startedAt;\n    if (typeof (built as { then?: unknown }).then === \"function\") {\n      throw new Error(\n        \"The Skybridge handler must be synchronous — it runs on every request. Load config or secrets in `setup` instead and read them from the handler's second argument.\",\n      );\n    }\n    if (elapsed > SLOW_HANDLER_THRESHOLD_MS && !this.slowHandlerWarned) {\n      this.slowHandlerWarned = true;\n      console.warn(\n        `The Skybridge handler took ${Math.round(elapsed)}ms — it runs on every request, so this cost is paid per request. Hoist expensive work to module scope or into \\`setup\\`, whose result is passed to the handler.`,\n      );\n    }\n    return built;\n  }\n\n  private middlewareEntries(\n    server: McpServer<Record<never, ToolDef>, TAuthExtra>,\n  ): McpMiddlewareEntry[] {\n    return [\n      ...(this.monitoringEntry ? [this.monitoringEntry] : []),\n      ...server.protocolMiddlewareEntries(),\n    ];\n  }\n\n  private instrumentHandlers(\n    server: McpServer<Record<never, ToolDef>, TAuthExtra>,\n  ): void {\n    const entries = this.middlewareEntries(server);\n    const { requestHandlers, notificationHandlers } = getHandlerMaps(\n      server.server,\n    );\n\n    const instrumentMap = (\n      map: Map<string, (...args: unknown[]) => Promise<unknown>>,\n      isNotification: boolean,\n    ) => {\n      for (const [method, handler] of map) {\n        map.set(\n          method,\n          buildMiddlewareChain(method, isNotification, handler, entries),\n        );\n      }\n      const originalSet = map.set.bind(map);\n      map.set = (\n        method: string,\n        handler: (...args: unknown[]) => Promise<unknown>,\n      ) =>\n        originalSet(\n          method,\n          buildMiddlewareChain(method, isNotification, handler, entries),\n        );\n    };\n\n    instrumentMap(requestHandlers, false);\n    instrumentMap(notificationHandlers, true);\n  }\n}\n"]}