skybridge 2.0.0-beta.dd3cba3 → 2.0.1

package/README.md

@@ -15,7 +15,7 @@
 
 <p align="center">
   <a href="https://docs.skybridge.tech">Documentation</a> ·
-  <a href="https://docs.skybridge.tech/quickstart/create-new-app">Quickstart</a> ·
+  <a href="https://docs.skybridge.tech/get-started/quickstart">Quickstart</a> ·
   <a href="https://github.com/alpic-ai/skybridge/tree/main/examples">Examples</a>
 </p>
 
@@ -62,7 +62,7 @@ They chose to build their MCP apps with Skybridge:
 
 **For agents**
 
-Install our [skill](https://docs.skybridge.tech/devtools/skills) for building MCP apps and ChatGPT apps:
+Install our [skill](https://docs.skybridge.tech/guides/migrate) for building MCP apps and ChatGPT apps:
 ```bash
 npx skills add alpic-ai/skybridge -s skybridge
 ```
@@ -78,22 +78,22 @@ Bootstrap a new project with:
 ```bash
 npm create skybridge@latest my-app
 ```
-For full install instructions, read our [**Quickstart guide**](https://docs.skybridge.tech/quickstart/create-new-app).
+For full install instructions, read our [**Quickstart guide**](https://docs.skybridge.tech/get-started/quickstart).
 
 ## Documentation
 
 The [Skybridge documentation](https://docs.skybridge.tech) covers the full lifecycle of building MCP Apps:
 
-- [Fundamentals](https://docs.skybridge.tech/fundamentals): understand MCP Apps, ChatGPT Apps, and how Skybridge bridges both runtimes.
-- [Core concepts](https://docs.skybridge.tech/concepts): learn about server <> model <> UI data flows, LLM context sync, type safety, and instant local iteration with our devtools.
-- [Guides](https://docs.skybridge.tech/guides/fetching-data): build real app behavior with tools, views, state, and model communication.
+- [Fundamentals](https://docs.skybridge.tech/get-started/architecture): understand MCP Apps, ChatGPT Apps, and how Skybridge bridges both runtimes.
+- [Core concepts](https://docs.skybridge.tech/get-started/architecture): learn about server <> model <> UI data flows, LLM context sync, type safety, and instant local iteration with our devtools.
+- [Guides](https://docs.skybridge.tech/build/tools): build real app behavior with tools, views, state, and model communication.
 - [API Reference](https://docs.skybridge.tech/api-reference): browse our MCP server APIs, React hooks, CLI commands, and runtime compatibility.
 
 ## Deploy
 
 Deploy Skybridge apps instantly on [Alpic](https://alpic.ai) for scalable hosting, MCP-specific analytics, permanent tunneling, app store compliance auditing and submission help. You can also self-host on any Node.js-compatible platform.
 
-See our [deployment guide](https://docs.skybridge.tech/quickstart/deploy) for the full production path.
+See our [deployment guide](https://docs.skybridge.tech/ship/deploy) for the full production path.
 
 ## Community & Contributing
 

package/dist/cli/telemetry.js

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import ci from "ci-info";
 import { PostHog } from "posthog-node";
+import { agent } from "std-env";
 const POSTHOG_API_KEY = "phc_rQdkCYr0DO4NcZBQXZnUwsHAbau9zuNwKIpil9FQP6v";
 const POSTHOG_HOST = "https://us.i.posthog.com";
 const ENV_TELEMETRY_DISABLED = "SKYBRIDGE_TELEMETRY_DISABLED";
@@ -98,6 +99,7 @@ const hook = async ({ id: command, config: { version }, error, }) => {
         machineId: getMachineId(),
         sessionId: crypto.randomUUID(),
         isCI: ci.isCI,
+        agent,
         nodeVersion: process.version,
         platform: process.platform,
         outcome: error ? "failure" : "success",

package/dist/cli/telemetry.js.map

@@ -1 +1 @@
-{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/cli/telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,eAAe,GAAG,iDAAiD,CAAC;AAC1E,MAAM,YAAY,GAAG,0BAA0B,CAAC;AAEhD,MAAM,sBAAsB,GAAG,8BAA8B,CAAC;AAC9D,MAAM,mBAAmB,GAAG,2BAA2B,CAAC;AACxD,MAAM,gBAAgB,GAAG,cAAc,CAAC;AAExC,MAAM,iBAAiB,GAAG,IAAI,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC,CAAC;AACxD,MAAM,kBAAkB,GAAG,IAAI,CAAC,iBAAiB,EAAE,aAAa,CAAC,CAAC;AAoBlE,IAAI,aAAa,GAAmB,IAAI,CAAC;AAEzC,SAAS,gBAAgB;IACvB,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,aAAa,GAAG,IAAI,OAAO,CAAC,eAAe,EAAE;YAC3C,IAAI,EAAE,YAAY;YAClB,OAAO,EAAE,CAAC;YACV,aAAa,EAAE,CAAC;SACjB,CAAC,CAAC;IACL,CAAC;IAED,OAAO,aAAa,CAAC;AACvB,CAAC;AAED,SAAS,YAAY,CAAI,QAAgB;IACvC,IAAI,CAAC;QACH,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAChD,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAM,CAAC;QAClC,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,+BAA+B;IACjC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,aAAa,CAAC,QAAgB,EAAE,IAAa;IACpD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACjC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,CAAC;QACD,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;IAClE,CAAC;IAAC,MAAM,CAAC;QACP,+BAA+B;IACjC,CAAC;AACH,CAAC;AAED,SAAS,eAAe;IACtB,MAAM,QAAQ,GAAG,YAAY,CAAe,kBAAkB,CAAC,CAAC;IAChE,IAAI,QAAQ,EAAE,SAAS,IAAI,QAAQ,EAAE,SAAS,KAAK,SAAS,EAAE,CAAC;QAC7D,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAiB;QAC3B,SAAS,EAAE,QAAQ,EAAE,SAAS,IAAI,MAAM,CAAC,UAAU,EAAE;QACrD,SAAS,EAAE;YACT,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,IAAI,IAAI;SAC9C;KACF,CAAC;IAEF,aAAa,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;IAC1C,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,IACE,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,KAAK,GAAG;QAC3C,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC,EAAE,WAAW,EAAE,KAAK,MAAM,EAC7D,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IACE,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,GAAG;QACrC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,EAAE,WAAW,EAAE,KAAK,MAAM,EACvD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;QACZ,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IACjC,OAAO,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,OAAO,CACL,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,KAAK,GAAG;QACxC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,EAAE,WAAW,EAAE,KAAK,MAAM,CAC3D,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,OAAgB;IACzC,MAAM,MAAM,GAAG,eAAe,EAAE,CAAC;IACjC,MAAM,CAAC,SAAS,CAAC,OAAO,GAAG,OAAO,CAAC;IACnC,aAAa,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC,IAAI,IAAI,YAAY,CAAC;IACjC,CAAC;IAED,OAAO,eAAe,EAAE,CAAC,SAAS,CAAC;AACrC,CAAC;AAED,MAAM,IAAI,GAAoB,KAAK,EAAE,EACnC,EAAE,EAAE,OAAO,EACX,MAAM,EAAE,EAAE,OAAO,EAAE,EACnB,KAAK,GACN,EAAE,EAAE;IACH,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;QACjB,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAmB;QAC5B,OAAO;QACP,SAAS,EAAE,YAAY,EAAE;QACzB,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE;QAC9B,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,WAAW,EAAE,OAAO,CAAC,OAAO;QAC5B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;QACtC,KAAK,EAAE,KAAK,EAAE,OAAO;KACtB,CAAC;IAEF,IAAI,WAAW,EAAE,EAAE,CAAC;QAClB,OAAO,CAAC,KAAK,CACX,qCAAqC,EACrC,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAC/B,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC;QAClC,MAAM,CAAC,OAAO,CAAC;YACb,UAAU,EAAE,KAAK,CAAC,SAAS;YAC3B,KAAK,EAAE,OAAO;YACd,UAAU,EAAE,KAAK;SAClB,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;IACjE,CAAC;AACH,CAAC,CAAC;AAEF,eAAe,IAAI,CAAC","sourcesContent":["import { existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport type { Hook } from \"@oclif/core\";\nimport ci from \"ci-info\";\nimport { PostHog } from \"posthog-node\";\n\nconst POSTHOG_API_KEY = \"phc_rQdkCYr0DO4NcZBQXZnUwsHAbau9zuNwKIpil9FQP6v\";\nconst POSTHOG_HOST = \"https://us.i.posthog.com\";\n\nconst ENV_TELEMETRY_DISABLED = \"SKYBRIDGE_TELEMETRY_DISABLED\";\nconst ENV_TELEMETRY_DEBUG = \"SKYBRIDGE_TELEMETRY_DEBUG\";\nconst ENV_DO_NOT_TRACK = \"DO_NOT_TRACK\";\n\nconst GLOBAL_CONFIG_DIR = join(homedir(), \".skybridge\");\nconst GLOBAL_CONFIG_FILE = join(GLOBAL_CONFIG_DIR, \"config.json\");\n\ninterface GlobalConfig {\n  machineId: string;\n  telemetry: {\n    enabled: boolean;\n  };\n}\n\ninterface TelemetryEvent {\n  version: string;\n  machineId: string;\n  sessionId: string;\n  isCI: boolean;\n  nodeVersion: string;\n  platform: NodeJS.Platform;\n  outcome: \"success\" | \"failure\";\n  error?: string;\n}\n\nlet posthogClient: PostHog | null = null;\n\nfunction getPostHogClient(): PostHog {\n  if (!posthogClient) {\n    posthogClient = new PostHog(POSTHOG_API_KEY, {\n      host: POSTHOG_HOST,\n      flushAt: 1,\n      flushInterval: 0,\n    });\n  }\n\n  return posthogClient;\n}\n\nfunction readJsonFile<T>(filePath: string): T | null {\n  try {\n    if (existsSync(filePath)) {\n      const content = readFileSync(filePath, \"utf-8\");\n      return JSON.parse(content) as T;\n    }\n  } catch {\n    // Ignore errors reading config\n  }\n  return null;\n}\n\nfunction writeJsonFile(filePath: string, data: unknown): void {\n  try {\n    const dir = join(filePath, \"..\");\n    if (!existsSync(dir)) {\n      mkdirSync(dir, { recursive: true });\n    }\n    writeFileSync(filePath, JSON.stringify(data, null, 2), \"utf-8\");\n  } catch {\n    // Ignore errors writing config\n  }\n}\n\nfunction getGlobalConfig(): GlobalConfig {\n  const existing = readJsonFile<GlobalConfig>(GLOBAL_CONFIG_FILE);\n  if (existing?.machineId && existing?.telemetry !== undefined) {\n    return existing;\n  }\n\n  const config: GlobalConfig = {\n    machineId: existing?.machineId || crypto.randomUUID(),\n    telemetry: {\n      enabled: existing?.telemetry?.enabled ?? true,\n    },\n  };\n\n  writeJsonFile(GLOBAL_CONFIG_FILE, config);\n  return config;\n}\n\nexport function isEnabled(): boolean {\n  if (\n    process.env[ENV_TELEMETRY_DISABLED] === \"1\" ||\n    process.env[ENV_TELEMETRY_DISABLED]?.toLowerCase() === \"true\"\n  ) {\n    return false;\n  }\n\n  if (\n    process.env[ENV_DO_NOT_TRACK] === \"1\" ||\n    process.env[ENV_DO_NOT_TRACK]?.toLowerCase() === \"true\"\n  ) {\n    return false;\n  }\n\n  if (ci.isCI) {\n    return true;\n  }\n\n  const config = getGlobalConfig();\n  return config.telemetry.enabled;\n}\n\nexport function isDebugMode(): boolean {\n  return (\n    process.env[ENV_TELEMETRY_DEBUG] === \"1\" ||\n    process.env[ENV_TELEMETRY_DEBUG]?.toLowerCase() === \"true\"\n  );\n}\n\nexport function setEnabled(enabled: boolean): void {\n  const config = getGlobalConfig();\n  config.telemetry.enabled = enabled;\n  writeJsonFile(GLOBAL_CONFIG_FILE, config);\n}\n\nexport function getMachineId(): string {\n  if (ci.isCI) {\n    return ci.name ?? \"unknown-ci\";\n  }\n\n  return getGlobalConfig().machineId;\n}\n\nconst hook: Hook<\"finally\"> = async ({\n  id: command,\n  config: { version },\n  error,\n}) => {\n  if (!isEnabled()) {\n    return;\n  }\n\n  const event: TelemetryEvent = {\n    version,\n    machineId: getMachineId(),\n    sessionId: crypto.randomUUID(),\n    isCI: ci.isCI,\n    nodeVersion: process.version,\n    platform: process.platform,\n    outcome: error ? \"failure\" : \"success\",\n    error: error?.message,\n  };\n\n  if (isDebugMode()) {\n    console.error(\n      \"[Telemetry Debug] Would send event:\",\n      JSON.stringify(event, null, 2),\n    );\n    return;\n  }\n\n  try {\n    const client = getPostHogClient();\n    client.capture({\n      distinctId: event.machineId,\n      event: command,\n      properties: event,\n    });\n  } catch {\n    // Silently ignore telemetry errors - never block CLI operation\n  }\n};\n\nexport default hook;\n"]}
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../src/cli/telemetry.ts"],"names":[],"mappings":"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","sourcesContent":["import { existsSync, mkdirSync, readFileSync, writeFileSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport type { Hook } from \"@oclif/core\";\nimport ci from \"ci-info\";\nimport { PostHog } from \"posthog-node\";\nimport { agent } from \"std-env\";\n\nconst POSTHOG_API_KEY = \"phc_rQdkCYr0DO4NcZBQXZnUwsHAbau9zuNwKIpil9FQP6v\";\nconst POSTHOG_HOST = \"https://us.i.posthog.com\";\n\nconst ENV_TELEMETRY_DISABLED = \"SKYBRIDGE_TELEMETRY_DISABLED\";\nconst ENV_TELEMETRY_DEBUG = \"SKYBRIDGE_TELEMETRY_DEBUG\";\nconst ENV_DO_NOT_TRACK = \"DO_NOT_TRACK\";\n\nconst GLOBAL_CONFIG_DIR = join(homedir(), \".skybridge\");\nconst GLOBAL_CONFIG_FILE = join(GLOBAL_CONFIG_DIR, \"config.json\");\n\ninterface GlobalConfig {\n  machineId: string;\n  telemetry: {\n    enabled: boolean;\n  };\n}\n\ninterface TelemetryEvent {\n  version: string;\n  machineId: string;\n  sessionId: string;\n  isCI: boolean;\n  agent?: string;\n  nodeVersion: string;\n  platform: NodeJS.Platform;\n  outcome: \"success\" | \"failure\";\n  error?: string;\n}\n\nlet posthogClient: PostHog | null = null;\n\nfunction getPostHogClient(): PostHog {\n  if (!posthogClient) {\n    posthogClient = new PostHog(POSTHOG_API_KEY, {\n      host: POSTHOG_HOST,\n      flushAt: 1,\n      flushInterval: 0,\n    });\n  }\n\n  return posthogClient;\n}\n\nfunction readJsonFile<T>(filePath: string): T | null {\n  try {\n    if (existsSync(filePath)) {\n      const content = readFileSync(filePath, \"utf-8\");\n      return JSON.parse(content) as T;\n    }\n  } catch {\n    // Ignore errors reading config\n  }\n  return null;\n}\n\nfunction writeJsonFile(filePath: string, data: unknown): void {\n  try {\n    const dir = join(filePath, \"..\");\n    if (!existsSync(dir)) {\n      mkdirSync(dir, { recursive: true });\n    }\n    writeFileSync(filePath, JSON.stringify(data, null, 2), \"utf-8\");\n  } catch {\n    // Ignore errors writing config\n  }\n}\n\nfunction getGlobalConfig(): GlobalConfig {\n  const existing = readJsonFile<GlobalConfig>(GLOBAL_CONFIG_FILE);\n  if (existing?.machineId && existing?.telemetry !== undefined) {\n    return existing;\n  }\n\n  const config: GlobalConfig = {\n    machineId: existing?.machineId || crypto.randomUUID(),\n    telemetry: {\n      enabled: existing?.telemetry?.enabled ?? true,\n    },\n  };\n\n  writeJsonFile(GLOBAL_CONFIG_FILE, config);\n  return config;\n}\n\nexport function isEnabled(): boolean {\n  if (\n    process.env[ENV_TELEMETRY_DISABLED] === \"1\" ||\n    process.env[ENV_TELEMETRY_DISABLED]?.toLowerCase() === \"true\"\n  ) {\n    return false;\n  }\n\n  if (\n    process.env[ENV_DO_NOT_TRACK] === \"1\" ||\n    process.env[ENV_DO_NOT_TRACK]?.toLowerCase() === \"true\"\n  ) {\n    return false;\n  }\n\n  if (ci.isCI) {\n    return true;\n  }\n\n  const config = getGlobalConfig();\n  return config.telemetry.enabled;\n}\n\nexport function isDebugMode(): boolean {\n  return (\n    process.env[ENV_TELEMETRY_DEBUG] === \"1\" ||\n    process.env[ENV_TELEMETRY_DEBUG]?.toLowerCase() === \"true\"\n  );\n}\n\nexport function setEnabled(enabled: boolean): void {\n  const config = getGlobalConfig();\n  config.telemetry.enabled = enabled;\n  writeJsonFile(GLOBAL_CONFIG_FILE, config);\n}\n\nexport function getMachineId(): string {\n  if (ci.isCI) {\n    return ci.name ?? \"unknown-ci\";\n  }\n\n  return getGlobalConfig().machineId;\n}\n\nconst hook: Hook<\"finally\"> = async ({\n  id: command,\n  config: { version },\n  error,\n}) => {\n  if (!isEnabled()) {\n    return;\n  }\n\n  const event: TelemetryEvent = {\n    version,\n    machineId: getMachineId(),\n    sessionId: crypto.randomUUID(),\n    isCI: ci.isCI,\n    agent,\n    nodeVersion: process.version,\n    platform: process.platform,\n    outcome: error ? \"failure\" : \"success\",\n    error: error?.message,\n  };\n\n  if (isDebugMode()) {\n    console.error(\n      \"[Telemetry Debug] Would send event:\",\n      JSON.stringify(event, null, 2),\n    );\n    return;\n  }\n\n  try {\n    const client = getPostHogClient();\n    client.capture({\n      distinctId: event.machineId,\n      event: command,\n      properties: event,\n    });\n  } catch {\n    // Silently ignore telemetry errors - never block CLI operation\n  }\n};\n\nexport default hook;\n"]}

package/dist/server/app.d.ts

@@ -1,65 +1,79 @@
 import type { Implementation, Server as SdkServer, ServerOptions } from "@modelcontextprotocol/server";
 import type { ErrorRequestHandler, Express, RequestHandler } from "express";
+import type { OAuthConfig, OAuthProvider } 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`).
+ * 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: pools, clients and any other
+ * one-time work belong in `setup`, whose result is the second argument. It
+ * must **return** the chained server so `typeof app` carries the registered
+ * tool types.
+ *
+ * @typeParam TConfig - What `setup` resolved to, passed as the second argument.
  */
-export type SkybridgeConfig<TAuthExtra extends ExtraClaims = ExtraClaims> = Implementation & ServerOptions & SkybridgeServerOptions<TAuthExtra>;
+export type SkybridgeHandler<TTools extends Record<string, ToolDef>, TConfig, TAuthExtra extends ExtraClaims> = (server: McpServer<Record<never, ToolDef>, TAuthExtra>, config: TConfig) => McpServer<TTools, TAuthExtra>;
 /**
- * The bare {@link McpServer} a {@link SkybridgeFactory} receives: no tools
- * registered yet. Use it to annotate a factory 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
- * inferred: the returned chain is what carries the tool registry into
- * `typeof app`.
+ * What the `oauth` field accepts: an {@link OAuthConfig}, a provider
+ * (`oauth: auth0Provider(...)`), or a function of the `setup` result returning
+ * either. Providers and functions resolve once, at {@link Skybridge.run} or on
+ * the first request, never at module import. Anything asynchronous belongs in
+ * a provider's `resolve`.
  */
-export type SkybridgeServer<TAuthExtra extends ExtraClaims = ExtraClaims> = McpServer<Record<never, ToolDef>, TAuthExtra>;
+export type SkybridgeOAuthInput<TConfig, TExtra extends ExtraClaims> = OAuthConfig<TExtra> | OAuthProvider<TExtra> | ((config: TConfig) => OAuthConfig<TExtra> | OAuthProvider<TExtra>);
 /**
- * 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.
+ * 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`).
  *
- * It must **return** the chained server so `typeof app` carries the registered
- * tool types.
- */
-export type SkybridgeFactory<TTools extends Record<string, ToolDef>, TAuthExtra extends ExtraClaims> = (server: McpServer<Record<never, ToolDef>, TAuthExtra>) => 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.
+ * All type parameters are inferred from the value: the config 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>, TConfig = 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?: () => TConfig;
+    /**
+     * 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<TConfig>, TAuthExtra>;
+    /** Registers the MCP surface, per request. See {@link SkybridgeHandler}. */
+    handler: SkybridgeHandler<TTools, Awaited<TConfig>, 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 +82,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>, TConfig = 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 config?;
     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({ name, title, version, description, icons, websiteUrl, json, skills, setup, oauth, handler, ...serverOptions }: SkybridgeConfig<TTools, TConfig, 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 +130,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,34 @@
 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;
+async function resolveOAuthInput(input, config) {
+    const resolved = typeof input === "function" ? input(config) : input;
+    return resolved && "resolve" in resolved
+        ? await resolved.resolve()
+        : resolved;
+}
 /**
  * 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 +37,7 @@ const SLOW_FACTORY_THRESHOLD_MS = 50;
  *       },
  *       async ({ query }) => ({ content: `Results for ${query}` }),
  *     ),
- * );
+ * });
  *
  * export type AppType = typeof app;
  * ```
@@ -46,56 +47,50 @@ const SLOW_FACTORY_THRESHOLD_MS = 50;
 export class Skybridge {
     serverInfo;
     serverOptions;
-    skybridgeOptions;
-    factory;
-    factoryLoader;
+    skills;
+    oauthEnabled = false;
+    handler;
+    setup;
+    oauthInput;
+    config;
     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({ name, title, version, description, icons, websiteUrl, json, skills, setup, oauth, handler, ...serverOptions }) {
         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.config = await this.setup();
             }
-            const { oauth } = this.skybridgeOptions;
-            const resolvedOauth = typeof oauth === "function" ? await oauth() : oauth;
+            const oauth = await resolveOAuthInput(this.oauthInput, this.config);
+            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 +98,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 +110,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 +169,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 +182,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 +216,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 +227,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.config);
         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. Move expensive work into \`setup\`, whose result is passed to the handler.`);
         }
         return built;
     }