skybridge 0.0.0-dev.efd00e6 → 0.0.0-dev.effc12c

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (274) hide show
  1. package/README.md +9 -7
  2. package/dist/cli/build-helpers.d.ts +1 -1
  3. package/dist/cli/build-helpers.js +4 -4
  4. package/dist/cli/build-helpers.js.map +1 -1
  5. package/dist/cli/build-helpers.test.js +6 -4
  6. package/dist/cli/build-helpers.test.js.map +1 -1
  7. package/dist/cli/build-steps.js +1 -1
  8. package/dist/cli/build-steps.js.map +1 -1
  9. package/dist/cli/build-steps.test.js +3 -3
  10. package/dist/cli/build-steps.test.js.map +1 -1
  11. package/dist/cli/detect-port.js +0 -1
  12. package/dist/cli/detect-port.js.map +1 -1
  13. package/dist/cli/run-plain.js +2 -1
  14. package/dist/cli/run-plain.js.map +1 -1
  15. package/dist/cli/use-execute-steps.d.ts +1 -1
  16. package/dist/cli/use-nodemon.d.ts +11 -1
  17. package/dist/cli/use-nodemon.js +30 -8
  18. package/dist/cli/use-nodemon.js.map +1 -1
  19. package/dist/cli/use-typescript-check.js +1 -1
  20. package/dist/cli/use-typescript-check.js.map +1 -1
  21. package/dist/commands/dev.js +4 -4
  22. package/dist/commands/dev.js.map +1 -1
  23. package/dist/commands/start.js +2 -2
  24. package/dist/commands/start.js.map +1 -1
  25. package/dist/context-warnings.d.ts +5 -0
  26. package/dist/context-warnings.js +31 -0
  27. package/dist/context-warnings.js.map +1 -0
  28. package/dist/context-warnings.test.js +28 -0
  29. package/dist/context-warnings.test.js.map +1 -0
  30. package/dist/server/app.d.ts +194 -0
  31. package/dist/server/app.js +266 -0
  32. package/dist/server/app.js.map +1 -0
  33. package/dist/server/app.test.js +97 -0
  34. package/dist/server/app.test.js.map +1 -0
  35. package/dist/server/auth/discovery.d.ts +2 -1
  36. package/dist/server/auth/discovery.js +2 -2
  37. package/dist/server/auth/discovery.js.map +1 -1
  38. package/dist/server/auth/index.d.ts +35 -5
  39. package/dist/server/auth/index.js.map +1 -1
  40. package/dist/server/auth/providers/auth0.d.ts +25 -3
  41. package/dist/server/auth/providers/auth0.js +13 -8
  42. package/dist/server/auth/providers/auth0.js.map +1 -1
  43. package/dist/server/auth/providers/auth0.test.js +5 -3
  44. package/dist/server/auth/providers/auth0.test.js.map +1 -1
  45. package/dist/server/auth/providers/authplane.d.ts +49 -0
  46. package/dist/server/auth/providers/authplane.js +57 -0
  47. package/dist/server/auth/providers/authplane.js.map +1 -0
  48. package/dist/server/auth/providers/authplane.test.js +143 -0
  49. package/dist/server/auth/providers/authplane.test.js.map +1 -0
  50. package/dist/server/auth/providers/clerk.d.ts +40 -3
  51. package/dist/server/auth/providers/clerk.js +4 -1
  52. package/dist/server/auth/providers/clerk.js.map +1 -1
  53. package/dist/server/auth/providers/clerk.test.js +5 -3
  54. package/dist/server/auth/providers/clerk.test.js.map +1 -1
  55. package/dist/server/auth/providers/custom.d.ts +12 -4
  56. package/dist/server/auth/providers/custom.js +14 -4
  57. package/dist/server/auth/providers/custom.js.map +1 -1
  58. package/dist/server/auth/providers/custom.test.js +24 -19
  59. package/dist/server/auth/providers/custom.test.js.map +1 -1
  60. package/dist/server/auth/providers/descope.d.ts +32 -3
  61. package/dist/server/auth/providers/descope.js.map +1 -1
  62. package/dist/server/auth/providers/descope.test.js +8 -6
  63. package/dist/server/auth/providers/descope.test.js.map +1 -1
  64. package/dist/server/auth/providers/stytch.d.ts +16 -3
  65. package/dist/server/auth/providers/stytch.js +4 -1
  66. package/dist/server/auth/providers/stytch.js.map +1 -1
  67. package/dist/server/auth/providers/verify-spy.d.ts +12 -0
  68. package/dist/server/auth/providers/verify-spy.js +21 -0
  69. package/dist/server/auth/providers/verify-spy.js.map +1 -0
  70. package/dist/server/auth/providers/workos.d.ts +25 -3
  71. package/dist/server/auth/providers/workos.js +4 -1
  72. package/dist/server/auth/providers/workos.js.map +1 -1
  73. package/dist/server/auth/setup.d.ts +1 -1
  74. package/dist/server/auth/setup.js +4 -5
  75. package/dist/server/auth/setup.js.map +1 -1
  76. package/dist/server/auth/setup.test.js +97 -57
  77. package/dist/server/auth/setup.test.js.map +1 -1
  78. package/dist/server/auth/verify.d.ts +37 -3
  79. package/dist/server/auth/verify.js +27 -3
  80. package/dist/server/auth/verify.js.map +1 -1
  81. package/dist/server/auth/verify.test.js +49 -0
  82. package/dist/server/auth/verify.test.js.map +1 -1
  83. package/dist/server/auth-extra.test-d.js +130 -0
  84. package/dist/server/auth-extra.test-d.js.map +1 -0
  85. package/dist/server/auth.d.ts +43 -6
  86. package/dist/server/auth.js +4 -5
  87. package/dist/server/auth.js.map +1 -1
  88. package/dist/server/build-manifest.test.js +7 -6
  89. package/dist/server/build-manifest.test.js.map +1 -1
  90. package/dist/server/content-helpers.d.ts +1 -1
  91. package/dist/server/content-helpers.js.map +1 -1
  92. package/dist/server/express.d.ts +23 -3
  93. package/dist/server/express.js +38 -32
  94. package/dist/server/express.js.map +1 -1
  95. package/dist/server/express.test.js +220 -103
  96. package/dist/server/express.test.js.map +1 -1
  97. package/dist/server/file-ref.d.ts +1 -1
  98. package/dist/server/file-ref.js +1 -1
  99. package/dist/server/file-ref.js.map +1 -1
  100. package/dist/server/index.d.ts +14 -8
  101. package/dist/server/index.js +7 -2
  102. package/dist/server/index.js.map +1 -1
  103. package/dist/server/mcp-errors.test.js +41 -0
  104. package/dist/server/mcp-errors.test.js.map +1 -0
  105. package/dist/server/middleware.d.ts +35 -10
  106. package/dist/server/middleware.js +33 -0
  107. package/dist/server/middleware.js.map +1 -1
  108. package/dist/server/middleware.test-d.js +1 -1
  109. package/dist/server/middleware.test-d.js.map +1 -1
  110. package/dist/server/middleware.test.js +242 -134
  111. package/dist/server/middleware.test.js.map +1 -1
  112. package/dist/server/register-tool.test.js +27 -0
  113. package/dist/server/register-tool.test.js.map +1 -0
  114. package/dist/server/server.d.ts +85 -120
  115. package/dist/server/server.js +112 -297
  116. package/dist/server/server.js.map +1 -1
  117. package/dist/server/skills-integration.test.js +44 -21
  118. package/dist/server/skills-integration.test.js.map +1 -1
  119. package/dist/server/skills.d.ts +14 -10
  120. package/dist/server/skills.js +49 -39
  121. package/dist/server/skills.js.map +1 -1
  122. package/dist/server/skills.test.js +77 -44
  123. package/dist/server/skills.test.js.map +1 -1
  124. package/dist/server/templateHelper.d.ts +0 -3
  125. package/dist/server/templateHelper.js.map +1 -1
  126. package/dist/server/templates.generated.js +4 -8
  127. package/dist/server/templates.generated.js.map +1 -1
  128. package/dist/server/tool-extra.test.d.ts +1 -0
  129. package/dist/server/tool-extra.test.js +88 -0
  130. package/dist/server/tool-extra.test.js.map +1 -0
  131. package/dist/server/view-resource-resolution.test.js +18 -13
  132. package/dist/server/view-resource-resolution.test.js.map +1 -1
  133. package/dist/test/utils.d.ts +9 -11
  134. package/dist/test/utils.js +220 -201
  135. package/dist/test/utils.js.map +1 -1
  136. package/dist/test/view.test.js +41 -37
  137. package/dist/test/view.test.js.map +1 -1
  138. package/dist/views/index.d.ts +10 -0
  139. package/dist/views/index.js +3 -0
  140. package/dist/views/index.js.map +1 -0
  141. package/dist/{web/plugin → views}/scan-views.js +1 -1
  142. package/dist/views/scan-views.js.map +1 -0
  143. package/dist/views/scan-views.test.d.ts +1 -0
  144. package/dist/views/scan-views.test.js.map +1 -0
  145. package/dist/views/validate-view.d.ts +1 -0
  146. package/dist/{web/plugin → views}/validate-view.js +2 -2
  147. package/dist/views/validate-view.js.map +1 -0
  148. package/dist/views/validate-view.test.d.ts +1 -0
  149. package/dist/views/validate-view.test.js.map +1 -0
  150. package/dist/web/bridges/adaptor.js +1 -15
  151. package/dist/web/bridges/adaptor.js.map +1 -1
  152. package/dist/web/bridges/adaptor.test.js +4 -3
  153. package/dist/web/bridges/adaptor.test.js.map +1 -1
  154. package/dist/web/bridges/apps-sdk/use-apps-sdk-context.d.ts +1 -1
  155. package/dist/web/bridges/apps-sdk/use-apps-sdk-context.js +1 -1
  156. package/dist/web/bridges/apps-sdk/use-apps-sdk-context.js.map +1 -1
  157. package/dist/web/bridges/get-adaptor.test.js +2 -2
  158. package/dist/web/bridges/get-adaptor.test.js.map +1 -1
  159. package/dist/web/bridges/mcp-app/bridge.js +1 -1
  160. package/dist/web/bridges/mcp-app/bridge.js.map +1 -1
  161. package/dist/web/bridges/mcp-app/bridge.test.js +2 -2
  162. package/dist/web/bridges/mcp-app/bridge.test.js.map +1 -1
  163. package/dist/web/bridges/mcp-app/use-mcp-app-context.d.ts +1 -1
  164. package/dist/web/bridges/mcp-app/use-mcp-app-context.js +1 -1
  165. package/dist/web/bridges/mcp-app/use-mcp-app-context.js.map +1 -1
  166. package/dist/web/bridges/mcp-app/use-mcp-app-context.test.js +1 -1
  167. package/dist/web/bridges/mcp-app/use-mcp-app-context.test.js.map +1 -1
  168. package/dist/web/bridges/mcp-app/view-tools.test.js +1 -1
  169. package/dist/web/bridges/mcp-app/view-tools.test.js.map +1 -1
  170. package/dist/web/bridges/types.d.ts +17 -12
  171. package/dist/web/bridges/types.js.map +1 -1
  172. package/dist/web/create-store.test.js +2 -2
  173. package/dist/web/create-store.test.js.map +1 -1
  174. package/dist/web/data-llm.test.js +5 -4
  175. package/dist/web/data-llm.test.js.map +1 -1
  176. package/dist/web/generate-helpers.d.ts +22 -18
  177. package/dist/web/generate-helpers.js +19 -15
  178. package/dist/web/generate-helpers.js.map +1 -1
  179. package/dist/web/generate-helpers.test-d.js +3 -3
  180. package/dist/web/generate-helpers.test-d.js.map +1 -1
  181. package/dist/web/generate-helpers.test.js +2 -2
  182. package/dist/web/generate-helpers.test.js.map +1 -1
  183. package/dist/web/hooks/index.d.ts +2 -2
  184. package/dist/web/hooks/index.js +2 -2
  185. package/dist/web/hooks/index.js.map +1 -1
  186. package/dist/web/hooks/use-call-tool.test.js +2 -2
  187. package/dist/web/hooks/use-call-tool.test.js.map +1 -1
  188. package/dist/web/hooks/use-display-mode.d.ts +1 -1
  189. package/dist/web/hooks/use-display-mode.js +1 -1
  190. package/dist/web/hooks/use-display-mode.js.map +1 -1
  191. package/dist/web/hooks/use-display-mode.test.js +1 -1
  192. package/dist/web/hooks/use-display-mode.test.js.map +1 -1
  193. package/dist/web/hooks/use-download.d.ts +1 -3
  194. package/dist/web/hooks/use-download.js +1 -2
  195. package/dist/web/hooks/use-download.js.map +1 -1
  196. package/dist/web/hooks/use-download.test.js +7 -7
  197. package/dist/web/hooks/use-download.test.js.map +1 -1
  198. package/dist/web/hooks/use-files.test.js +1 -1
  199. package/dist/web/hooks/use-files.test.js.map +1 -1
  200. package/dist/web/hooks/{use-host-info.d.ts → use-host.d.ts} +2 -2
  201. package/dist/web/hooks/{use-host-info.js → use-host.js} +3 -3
  202. package/dist/web/hooks/use-host.js.map +1 -0
  203. package/dist/web/hooks/use-host.test.d.ts +1 -0
  204. package/dist/web/hooks/{use-host-info.test.js → use-host.test.js} +7 -7
  205. package/dist/web/hooks/use-host.test.js.map +1 -0
  206. package/dist/web/hooks/use-open-external.test.js +2 -2
  207. package/dist/web/hooks/use-open-external.test.js.map +1 -1
  208. package/dist/web/hooks/use-register-view-tool.d.ts +2 -3
  209. package/dist/web/hooks/use-register-view-tool.js.map +1 -1
  210. package/dist/web/hooks/use-request-close.test.js +1 -1
  211. package/dist/web/hooks/use-request-close.test.js.map +1 -1
  212. package/dist/web/hooks/use-request-modal.test.js +1 -1
  213. package/dist/web/hooks/use-request-modal.test.js.map +1 -1
  214. package/dist/web/hooks/use-request-size.d.ts +1 -1
  215. package/dist/web/hooks/use-request-size.js +1 -1
  216. package/dist/web/hooks/use-request-size.js.map +1 -1
  217. package/dist/web/hooks/use-request-size.test.js +1 -1
  218. package/dist/web/hooks/use-request-size.test.js.map +1 -1
  219. package/dist/web/hooks/use-set-open-in-app-url.test.js +2 -8
  220. package/dist/web/hooks/use-set-open-in-app-url.test.js.map +1 -1
  221. package/dist/web/hooks/use-tool-info.d.ts +1 -20
  222. package/dist/web/hooks/use-tool-info.js +0 -1
  223. package/dist/web/hooks/use-tool-info.js.map +1 -1
  224. package/dist/web/hooks/use-tool-info.test-d.js +0 -5
  225. package/dist/web/hooks/use-tool-info.test-d.js.map +1 -1
  226. package/dist/web/hooks/use-tool-info.test.js +2 -7
  227. package/dist/web/hooks/use-tool-info.test.js.map +1 -1
  228. package/dist/web/hooks/use-user.d.ts +3 -2
  229. package/dist/web/hooks/use-user.js +4 -3
  230. package/dist/web/hooks/use-user.js.map +1 -1
  231. package/dist/web/hooks/use-user.test.js +5 -3
  232. package/dist/web/hooks/use-user.test.js.map +1 -1
  233. package/dist/web/hooks/use-view-state.test.js +2 -2
  234. package/dist/web/hooks/use-view-state.test.js.map +1 -1
  235. package/dist/web/hooks/use-viewport.d.ts +20 -0
  236. package/dist/web/hooks/use-viewport.js +21 -0
  237. package/dist/web/hooks/use-viewport.js.map +1 -0
  238. package/dist/web/hooks/use-viewport.test.d.ts +1 -0
  239. package/dist/web/hooks/{use-layout.test.js → use-viewport.test.js} +12 -32
  240. package/dist/web/hooks/use-viewport.test.js.map +1 -0
  241. package/dist/web/mount-view.d.ts +3 -2
  242. package/dist/web/mount-view.js +5 -8
  243. package/dist/web/mount-view.js.map +1 -1
  244. package/package.json +13 -11
  245. package/dist/web/hooks/use-host-info.js.map +0 -1
  246. package/dist/web/hooks/use-host-info.test.js.map +0 -1
  247. package/dist/web/hooks/use-layout.d.ts +0 -24
  248. package/dist/web/hooks/use-layout.js +0 -25
  249. package/dist/web/hooks/use-layout.js.map +0 -1
  250. package/dist/web/hooks/use-layout.test.js.map +0 -1
  251. package/dist/web/plugin/data-llm.test.js +0 -81
  252. package/dist/web/plugin/data-llm.test.js.map +0 -1
  253. package/dist/web/plugin/plugin.d.ts +0 -39
  254. package/dist/web/plugin/plugin.js +0 -189
  255. package/dist/web/plugin/plugin.js.map +0 -1
  256. package/dist/web/plugin/scan-views.js.map +0 -1
  257. package/dist/web/plugin/scan-views.test.js.map +0 -1
  258. package/dist/web/plugin/transform-data-llm.d.ts +0 -12
  259. package/dist/web/plugin/transform-data-llm.js +0 -96
  260. package/dist/web/plugin/transform-data-llm.js.map +0 -1
  261. package/dist/web/plugin/transform-data-llm.test.js +0 -81
  262. package/dist/web/plugin/transform-data-llm.test.js.map +0 -1
  263. package/dist/web/plugin/validate-view.d.ts +0 -1
  264. package/dist/web/plugin/validate-view.js.map +0 -1
  265. package/dist/web/plugin/validate-view.test.js.map +0 -1
  266. /package/dist/{web/hooks/use-host-info.test.d.ts → context-warnings.test.d.ts} +0 -0
  267. /package/dist/{web/hooks/use-layout.test.d.ts → server/app.test.d.ts} +0 -0
  268. /package/dist/{web/plugin/scan-views.test.d.ts → server/auth/providers/authplane.test.d.ts} +0 -0
  269. /package/dist/{web/plugin/data-llm.test.d.ts → server/auth-extra.test-d.d.ts} +0 -0
  270. /package/dist/{web/plugin/transform-data-llm.test.d.ts → server/mcp-errors.test.d.ts} +0 -0
  271. /package/dist/{web/plugin/validate-view.test.d.ts → server/register-tool.test.d.ts} +0 -0
  272. /package/dist/{web/plugin → views}/scan-views.d.ts +0 -0
  273. /package/dist/{web/plugin → views}/scan-views.test.js +0 -0
  274. /package/dist/{web/plugin → views}/validate-view.test.js +0 -0
@@ -1,27 +1,15 @@
1
1
  import crypto from "node:crypto";
2
2
  import { readFileSync } from "node:fs";
3
- import http from "node:http";
4
3
  import path from "node:path";
5
- import { Server as SdkServer, } from "@modelcontextprotocol/sdk/server/index.js";
6
- import { McpServer as McpServerBase } from "@modelcontextprotocol/sdk/server/mcp.js";
7
- import { mergeWith, union } from "es-toolkit";
8
- import express, {} from "express";
4
+ import { McpServer as McpServerBase, } from "@modelcontextprotocol/server";
5
+ import { warnOnLargeToolOutput } from "../context-warnings.js";
9
6
  import { authToSecuritySchemes, evaluateSecuritySchemes, inBandChallengeResult, } from "./auth/security-schemes.js";
10
- import { setupOAuth } from "./auth/setup.js";
11
- import { createApp } from "./express.js";
12
7
  import { hostFromUserAgent } from "./host.js";
13
- import { createMiddlewareEntry } from "./metric.js";
14
- import { buildMiddlewareChain, getHandlerMaps } from "./middleware.js";
8
+ import { captureToolError } from "./middleware.js";
15
9
  import { resolveServerOrigin } from "./requestOrigin.js";
16
10
  import { discoverSkills, registerSkills, SKILLS_EXTENSION_KEY, } from "./skills.js";
17
11
  import { templateHelper } from "./templateHelper.js";
18
- const mergeWithUnion = (target, source) => {
19
- return mergeWith(target, source, (targetVal, sourceVal) => {
20
- if (Array.isArray(targetVal) && Array.isArray(sourceVal)) {
21
- return union(targetVal, sourceVal);
22
- }
23
- });
24
- };
12
+ const unionOf = (base, extra) => extra ? [...new Set([...base, ...extra])] : base;
25
13
  const SKILLS_DIR = "src/skills";
26
14
  /**
27
15
  * Normalize an `x-forwarded-prefix` value into a leading-slash, no-trailing-slash
@@ -64,35 +52,6 @@ export function normalizeContent(content) {
64
52
  return [content];
65
53
  }
66
54
  const McpServerBaseOmitted = McpServerBase;
67
- /**
68
- * The Skybridge server. Extends the MCP SDK's `McpServer` with a typed tool
69
- * registry, view resources, an embedded Express app, and protocol-level
70
- * middleware. Construct it with the same `Implementation` info you would pass
71
- * to the SDK, chain {@link McpServer.registerTool} calls to declare tools,
72
- * then call {@link McpServer.run} to start the HTTP server.
73
- *
74
- * The `TTools` generic accumulates each registered tool's input/output/meta
75
- * shape, so `typeof server` carries enough information for view-side helpers
76
- * like {@link generateHelpers} to produce fully-typed hooks.
77
- *
78
- * @typeParam TTools - Accumulated tool registry. Filled in by `registerTool`
79
- * chaining; you almost never set this manually.
80
- *
81
- * @example
82
- * ```ts
83
- * const server = new McpServer({ name: "my-app", version: "1.0.0" }, {})
84
- * .registerTool({
85
- * name: "search",
86
- * inputSchema: { query: z.string() },
87
- * view: { component: "search" },
88
- * }, async ({ query }) => ({ content: `Results for ${query}` }));
89
- *
90
- * await server.run();
91
- * export type AppType = typeof server;
92
- * ```
93
- *
94
- * @see https://docs.skybridge.tech/api-reference/mcp-server
95
- */
96
55
  // Side channel populated by `dist/__entry.js` before user code is imported.
97
56
  // Set at module scope rather than passed through the constructor because the
98
57
  // wrapper has the manifest before the user's `new McpServer(...)` runs, and
@@ -110,8 +69,12 @@ export function __setBuildManifest(manifest) {
110
69
  pendingBuildManifest = manifest;
111
70
  }
112
71
  let pendingSkillsManifest = null;
72
+ let cachedDiskManifest = null;
73
+ let discoveredSkills = null;
74
+ let warnedOnMissingSkills = false;
113
75
  export function __setSkillsManifest(manifest) {
114
76
  pendingSkillsManifest = manifest;
77
+ discoveredSkills = null;
115
78
  }
116
79
  // Pure and `this`-free so it can run inside the `super(...)` call, before `this`
117
80
  // exists — the capability must be present for the `initialize` response.
@@ -130,45 +93,37 @@ function withSkillsCapability(options, skybridgeOptions) {
130
93
  },
131
94
  };
132
95
  }
133
- // Collapses registerTool's two overloads into a single { config, cb } shape.
134
- // registerTool("greet", { description }, handler)
135
- // -> { config: { name: "greet", description }, cb: handler }
136
- // registerTool({ name: "greet", description }, handler)
137
- // -> { config: { name: "greet", description }, cb: handler }
138
- function normalizeRegisterToolArgs(args) {
139
- if (typeof args[0] === "string") {
140
- return {
141
- config: {
142
- name: args[0],
143
- ...args[1],
144
- },
145
- cb: args[2],
146
- };
147
- }
148
- return {
149
- config: args[0],
150
- cb: args[1],
151
- };
152
- }
96
+ /**
97
+ * Typed registration sugar over the MCP SDK's `McpServer`: a tool registry
98
+ * that carries input/output/meta shapes, view resources, per-tool security
99
+ * schemes, and prompt/resource registration. A {@link Skybridge} app builds
100
+ * one of these per request and hands it to your `handler`; chain
101
+ * {@link McpServer.registerTool} calls on it and return the result.
102
+ *
103
+ * The `TTools` generic accumulates each registered tool's input/output/meta
104
+ * shape, so `typeof app` carries enough information for view-side helpers
105
+ * like {@link generateHelpers} to produce fully-typed hooks.
106
+ *
107
+ * @typeParam TTools - Accumulated tool registry. Filled in by `registerTool`
108
+ * chaining; you almost never set this manually.
109
+ *
110
+ * @example
111
+ * ```ts
112
+ * export const app = new Skybridge({
113
+ * name: "my-app",
114
+ * version: "1.0.0",
115
+ * handler: (server) =>
116
+ * server.registerTool({
117
+ * name: "search",
118
+ * inputSchema: { query: z.string() },
119
+ * view: { component: "search" },
120
+ * }, async ({ query }) => ({ content: `Results for ${query}` })),
121
+ * });
122
+ * ```
123
+ *
124
+ * @see https://docs.skybridge.tech/api-reference/mcp-server
125
+ */
153
126
  export class McpServer extends McpServerBaseOmitted {
154
- /**
155
- * The underlying Express app. Use this to extend the HTTP server with
156
- * custom routes, middleware, or settings — e.g.
157
- * `server.express.get("/health", ...)`.
158
- *
159
- * `express.json()` is pre-applied — tune it via the constructor's third
160
- * argument, e.g. `new McpServer(info, {}, { json: { limit: "10mb" } })`.
161
- * Register your handlers before `run()`;
162
- * after `run()`, dev-mode middleware, the `/mcp` route, and the default
163
- * error handler are appended in that order.
164
- *
165
- * Note: Alpic Cloud only routes traffic to `/mcp` — custom routes work
166
- * locally and on self-hosted deployments.
167
- */
168
- express;
169
- customErrorMiddleware = [];
170
- mcpMiddlewareEntries = [];
171
- mcpMiddlewareApplied = false;
172
127
  claimedViews = new Map();
173
128
  viewMetaBuilders = new Map();
174
129
  /**
@@ -179,82 +134,64 @@ export class McpServer extends McpServerBaseOmitted {
179
134
  */
180
135
  viewUriByPath = new Map();
181
136
  viteManifest = null;
182
- serverInfo;
183
- serverOptions;
184
137
  oauthEnabled = false;
185
138
  resolveResourceMetadataUrl;
186
- securitySchemesByTool = new Map();
139
+ toolSecuritySchemes = new Map();
140
+ userMiddlewareEntries = [];
187
141
  constructor(serverInfo, options, skybridgeOptions) {
188
- const mergedOptions = withSkillsCapability(options, skybridgeOptions);
189
- super(serverInfo, mergedOptions);
190
- this.serverInfo = serverInfo;
191
- this.serverOptions = mergedOptions;
192
- this.express = express();
193
- this.express.use(express.json(skybridgeOptions?.json));
194
- if (skybridgeOptions?.oauth) {
195
- this.oauthEnabled = true;
196
- this.resolveResourceMetadataUrl = setupOAuth(this.express, skybridgeOptions.oauth, this.securitySchemesByTool);
197
- }
142
+ super(serverInfo, withSkillsCapability(options, skybridgeOptions));
143
+ this.oauthEnabled = Boolean(skybridgeOptions?.oauth);
198
144
  // Pick up the manifest if `dist/__entry.js` primed it before importing
199
- // user code. Consume-once: clear after the first construction so a
200
- // subsequent test that doesn't prime can't inherit stale state.
201
- // Explicit `setViteManifest` calls still win because they happen after
202
- // construction.
145
+ // user code. Explicit `setViteManifest` calls still win because they
146
+ // happen after construction.
203
147
  if (pendingBuildManifest) {
204
148
  this.setViteManifest(pendingBuildManifest);
205
- pendingBuildManifest = null;
206
149
  }
207
150
  this.setupSkills(Boolean(skybridgeOptions?.skills));
208
151
  }
152
+ /**
153
+ * The per-tool security schemes collected during registration, keyed by tool
154
+ * name. Read by the OAuth layer to decide whether anonymous requests are
155
+ * allowed and which schemes gate a given `tools/call`.
156
+ *
157
+ * @internal
158
+ */
159
+ get securitySchemesByTool() {
160
+ return this.toolSecuritySchemes;
161
+ }
162
+ /**
163
+ * Inject the resolver the app uses to build the protected-resource metadata
164
+ * URL, so tool handlers can emit in-band auth challenges.
165
+ *
166
+ * @internal
167
+ */
168
+ setResourceMetadataUrlResolver(resolve) {
169
+ this.resolveResourceMetadataUrl = resolve;
170
+ return this;
171
+ }
209
172
  setupSkills(enabled) {
210
- const manifest = pendingSkillsManifest;
211
- pendingSkillsManifest = null;
212
173
  if (!enabled) {
213
174
  return;
214
175
  }
215
- const skills = manifest ?? discoverSkills(SKILLS_DIR);
216
- if (skills.length === 0) {
176
+ discoveredSkills ??= pendingSkillsManifest ?? discoverSkills(SKILLS_DIR);
177
+ if (discoveredSkills.length === 0 && !warnedOnMissingSkills) {
178
+ warnedOnMissingSkills = true;
217
179
  console.warn(`skybridge: the "skills" option is enabled but no skills were found in "${SKILLS_DIR}". Add a <name>/SKILL.md there, or remove the option.`);
218
180
  }
219
- registerSkills(this, skills);
220
- }
221
- use(pathOrHandler, ...handlers) {
222
- // Branching is load-bearing: Express's `app.use` overloads can't be
223
- // resolved against a `string | RequestHandler` union, so we narrow.
224
- if (typeof pathOrHandler === "string") {
225
- this.express.use(pathOrHandler, ...handlers);
226
- }
227
- else {
228
- this.express.use(pathOrHandler, ...handlers);
229
- }
230
- return this;
231
- }
232
- useOnError(pathOrHandler, ...handlers) {
233
- if (typeof pathOrHandler === "string") {
234
- this.customErrorMiddleware.push({ path: pathOrHandler, handlers });
235
- }
236
- else {
237
- this.customErrorMiddleware.push({
238
- handlers: [pathOrHandler, ...handlers],
239
- });
240
- }
241
- return this;
181
+ registerSkills(this, discoveredSkills);
242
182
  }
243
183
  mcpMiddleware(filterOrHandler,
244
184
  // biome-ignore lint/suspicious/noExplicitAny: overloads narrow the handler type at call sites; implementation must accept all variants
245
185
  maybeHandler) {
246
- if (this.mcpMiddlewareApplied) {
247
- throw new Error("Cannot register MCP middleware after run() or connect() has been called");
248
- }
249
186
  const handler = maybeHandler;
250
187
  if (typeof filterOrHandler === "function") {
251
- this.mcpMiddlewareEntries.push({
188
+ this.userMiddlewareEntries.push({
252
189
  filter: null,
253
190
  handler: filterOrHandler,
254
191
  });
255
192
  }
256
193
  else if (handler) {
257
- this.mcpMiddlewareEntries.push({
194
+ this.userMiddlewareEntries.push({
258
195
  filter: filterOrHandler,
259
196
  handler,
260
197
  });
@@ -264,11 +201,15 @@ export class McpServer extends McpServerBaseOmitted {
264
201
  }
265
202
  return this;
266
203
  }
267
- applyMcpMiddleware() {
268
- if (this.mcpMiddlewareApplied) {
269
- return;
270
- }
271
- this.mcpMiddlewareApplied = true;
204
+ /**
205
+ * This instance's protocol-level middleware: the framework's own entries
206
+ * (view `_meta` on `resources/list`, version-agnostic view resolution on
207
+ * `resources/read`, the top-level `securitySchemes` mirror on `tools/list`)
208
+ * followed by the ones registered via {@link McpServer.mcpMiddleware}.
209
+ *
210
+ * @internal
211
+ */
212
+ protocolMiddlewareEntries() {
272
213
  // Surface view-resource _meta on `resources/list` (per ext-apps spec:
273
214
  // hosts/checkers read CSP & domain at list time before fetching content).
274
215
  const viewListMetaEntry = {
@@ -344,121 +285,12 @@ export class McpServer extends McpServerBaseOmitted {
344
285
  return result;
345
286
  },
346
287
  };
347
- const monitoringEntry = createMiddlewareEntry();
348
- const entries = [
349
- ...(monitoringEntry ? [monitoringEntry] : []),
288
+ return [
350
289
  viewListMetaEntry,
351
290
  viewReadResolveEntry,
352
291
  toolsListSecuritySchemesEntry,
353
- ...this.mcpMiddlewareEntries,
292
+ ...this.userMiddlewareEntries,
354
293
  ];
355
- const { requestHandlers, notificationHandlers } = getHandlerMaps(this.server);
356
- const instrumentMap = (map, isNotification) => {
357
- for (const [method, handler] of map) {
358
- map.set(method, buildMiddlewareChain(method, isNotification, handler, entries));
359
- }
360
- const originalSet = map.set.bind(map);
361
- map.set = (method, handler) => originalSet(method, buildMiddlewareChain(method, isNotification, handler, entries));
362
- };
363
- instrumentMap(requestHandlers, false);
364
- instrumentMap(notificationHandlers, true);
365
- }
366
- /**
367
- * Connect to an MCP transport (override of the SDK's `connect`). Use this
368
- * when you're embedding Skybridge in a host that already manages its own
369
- * transport (e.g. stdio for desktop apps); for HTTP, prefer {@link McpServer.run}
370
- * which sets the transport up for you. Locks in any middleware registered
371
- * via {@link McpServer.mcpMiddleware} — further calls to that method will
372
- * throw afterwards.
373
- */
374
- async connect(transport) {
375
- this.applyMcpMiddleware();
376
- return McpServerBase.prototype.connect.call(this, transport);
377
- }
378
- /**
379
- * Per-request stateless connect. The SDK's `Protocol` only allows one
380
- * transport per instance, so we can't reuse this `McpServer` across
381
- * concurrent requests. The SDK's idiomatic fix is a `() => McpServer`
382
- * factory, but that would break Skybridge's singleton API — so instead
383
- * we build a fresh underlying `Server` per request and share the main
384
- * server's handler maps by reference. The cast is unavoidable: there's
385
- * no public API to inject handler maps. `getHandlerMaps` validates the
386
- * read side and fails fast on SDK field renames.
387
- */
388
- async connectStatelessTransport(transport) {
389
- this.applyMcpMiddleware();
390
- const { requestHandlers, notificationHandlers } = getHandlerMaps(this.server);
391
- const fresh = new SdkServer(this.serverInfo, this.serverOptions);
392
- const target = fresh;
393
- target._requestHandlers = requestHandlers;
394
- target._notificationHandlers = notificationHandlers;
395
- await fresh.connect(transport);
396
- }
397
- /**
398
- * Start the HTTP server. Listens on `process.env.__PORT` (default `3000`),
399
- * mounts the `/mcp` route, applies any custom Express middleware registered
400
- * via {@link McpServer.use} / {@link McpServer.useOnError}, and locks in
401
- * any MCP middleware registered via {@link McpServer.mcpMiddleware}.
402
- *
403
- * On Cloudflare Workers / workerd, returns an object exposing `fetch` so
404
- * the runtime can bridge incoming requests to the Node HTTP server. On
405
- * Vercel (`VERCEL === "1"`), returns the Express app directly so the
406
- * serverless function entry can call it as a `(req, res)` handler. On
407
- * Node, returns `undefined` once listening.
408
- */
409
- async run() {
410
- this.applyMcpMiddleware();
411
- if (process.env.VERCEL === "1") {
412
- // createApp only reads httpServer inside its dev-only branch
413
- // (viewsDevServer); under VERCEL=1 + NODE_ENV=production it's a
414
- // bare object passed to satisfy the required parameter.
415
- const httpServer = http.createServer();
416
- await createApp({
417
- mcpServer: this,
418
- httpServer,
419
- errorMiddleware: this.customErrorMiddleware,
420
- });
421
- return this.express;
422
- }
423
- const httpServer = http.createServer();
424
- await createApp({
425
- mcpServer: this,
426
- httpServer,
427
- errorMiddleware: this.customErrorMiddleware,
428
- });
429
- httpServer.on("request", this.express);
430
- const port = parseInt(process.env.__PORT ?? "3000", 10);
431
- await new Promise((resolve, reject) => {
432
- httpServer.on("error", (error) => {
433
- console.error("Failed to start server:", error);
434
- reject(error);
435
- });
436
- httpServer.listen(port, () => {
437
- resolve();
438
- });
439
- });
440
- // On workerd, bridge the Node http server to a Workers fetch handler.
441
- // The specifier is held in a variable to sidestep tsc's module resolution
442
- // (`cloudflare:node` only exists under wrangler/workerd).
443
- if (typeof navigator !== "undefined" &&
444
- navigator.userAgent === "Cloudflare-Workers") {
445
- const cloudflareNode = "cloudflare:node";
446
- const { httpServerHandler } = await import(cloudflareNode);
447
- return httpServerHandler({ port });
448
- }
449
- const shutdown = () => {
450
- // Drop both handlers so a second signal falls through to Node's default
451
- // (force-quit on a second Ctrl+C while drain is hanging).
452
- process.off("SIGTERM", shutdown);
453
- process.off("SIGINT", shutdown);
454
- httpServer.close(() => process.exit(0));
455
- // Force exit if connections don't drain in time so the port is still
456
- // released promptly (e.g. for nodemon restarts).
457
- setTimeout(() => process.exit(0), 3000).unref();
458
- };
459
- process.on("SIGTERM", shutdown);
460
- process.on("SIGINT", shutdown);
461
- return undefined;
462
294
  }
463
295
  enforceOneToolPerView(component, toolName) {
464
296
  const existingTool = this.claimedViews.get(component);
@@ -467,13 +299,9 @@ export class McpServer extends McpServerBaseOmitted {
467
299
  }
468
300
  this.claimedViews.set(component, toolName);
469
301
  }
470
- resolveViewRequestContext(extra) {
302
+ resolveViewRequestContext(ctx) {
471
303
  const isProduction = process.env.NODE_ENV === "production";
472
- const headers = extra?.requestInfo?.headers || {};
473
- const header = (key) => {
474
- const val = headers[key];
475
- return Array.isArray(val) ? val[0] : val;
476
- };
304
+ const header = (key) => ctx?.http?.req?.headers.get(key) ?? undefined;
477
305
  const isClaude = hostFromUserAgent(header("user-agent")) === "claude";
478
306
  const serverUrl = resolveServerOrigin(header);
479
307
  // Path prefix the proxy routed this request under (e.g. `foo.com/v1`). Read
@@ -489,7 +317,7 @@ export class McpServer extends McpServerBaseOmitted {
489
317
  }
490
318
  let contentMetaOverrides = {};
491
319
  if (isClaude) {
492
- const pathname = extra?.requestInfo?.url?.pathname ?? "";
320
+ const pathname = ctx?.http?.req ? new URL(ctx.http.req.url).pathname : "";
493
321
  const rawUrl = header("x-alpic-forwarded-url") ?? `${serverUrl}${pathname}`;
494
322
  // Strip a lone trailing slash so the hash matches the connector URL
495
323
  // as registered with Claude (which has no trailing slash on bare origins).
@@ -509,46 +337,26 @@ export class McpServer extends McpServerBaseOmitted {
509
337
  // `tools/list` calls when the bundle hasn't changed.
510
338
  const versionParam = this.computeViewVersionParam(view.component);
511
339
  const viewResource = {
512
- hostType: "mcp-app",
513
340
  uri: `ui://views/ext-apps/${view.component}.html${versionParam}`,
514
341
  mimeType: "text/html;profile=mcp-app",
515
342
  buildContentMeta: ({ resourceDomains, connectDomains, domain, baseUriDomains }, overrides) => {
516
- const defaults = {
517
- ui: {
518
- csp: {
519
- resourceDomains,
520
- connectDomains,
521
- baseUriDomains,
522
- },
523
- domain,
524
- },
525
- };
526
- const fromView = {
343
+ const ui = {
527
344
  ui: {
528
345
  ...(view.description && { description: view.description }),
529
346
  ...(view.prefersBorder !== undefined && {
530
347
  prefersBorder: view.prefersBorder,
531
348
  }),
532
- ...(view.domain && { domain: view.domain }),
349
+ domain: overrides.domain ?? view.domain ?? domain,
533
350
  csp: {
534
- ...(view.csp?.resourceDomains && {
535
- resourceDomains: view.csp.resourceDomains,
536
- }),
537
- ...(view.csp?.connectDomains && {
538
- connectDomains: view.csp.connectDomains,
539
- }),
351
+ resourceDomains: unionOf(resourceDomains, view.csp?.resourceDomains),
352
+ connectDomains: unionOf(connectDomains, view.csp?.connectDomains),
353
+ baseUriDomains: unionOf(baseUriDomains, view.csp?.baseUriDomains),
540
354
  ...(view.csp?.frameDomains && {
541
355
  frameDomains: view.csp.frameDomains,
542
356
  }),
543
- ...(view.csp?.baseUriDomains && {
544
- baseUriDomains: view.csp.baseUriDomains,
545
- }),
546
357
  },
547
358
  },
548
359
  };
549
- const ui = mergeWithUnion(mergeWithUnion(defaults, fromView), {
550
- ui: overrides,
551
- });
552
360
  const base = {
553
361
  ...ui,
554
362
  ...(view.description && {
@@ -574,7 +382,7 @@ export class McpServer extends McpServerBaseOmitted {
574
382
  toolMeta.ui = { ...toolMeta.ui, resourceUri: viewResource.uri };
575
383
  }
576
384
  registerViewResource({ name, viewResource, view, }) {
577
- const { hostType, uri: viewUri, mimeType, buildContentMeta } = viewResource;
385
+ const { uri: viewUri, mimeType, buildContentMeta } = viewResource;
578
386
  const buildMeta = (extra) => {
579
387
  const { serverUrl, connectDomains, contentMetaOverrides } = this.resolveViewRequestContext(extra);
580
388
  return buildContentMeta({
@@ -596,13 +404,11 @@ export class McpServer extends McpServerBaseOmitted {
596
404
  const viewBase = `${serverUrl}${assetsBasePath}`;
597
405
  const html = isProduction
598
406
  ? templateHelper.renderProduction({
599
- hostType,
600
407
  serverUrl: viewBase,
601
408
  viewFile: this.lookupViewFile(view.component),
602
409
  styleFile: this.lookupDistFile("style.css") ?? "",
603
410
  })
604
411
  : templateHelper.renderDevelopment({
605
- hostType,
606
412
  serverUrl: viewBase,
607
413
  viewName: view.component,
608
414
  });
@@ -618,20 +424,24 @@ export class McpServer extends McpServerBaseOmitted {
618
424
  this.viewUriByPath.set(`ui://widgets/apps-sdk/${component}.html`, canonicalUri);
619
425
  this.viewUriByPath.set(`ui://widgets/ext-apps/${component}.html`, canonicalUri);
620
426
  }
621
- decorateToolHandler(cb, { attachViewUUID, securitySchemes, }) {
427
+ decorateToolHandler(cb, { attachViewUUID, securitySchemes, toolName, }) {
622
428
  return async (args, extra) => {
623
429
  if (this.oauthEnabled) {
624
- const failure = evaluateSecuritySchemes(securitySchemes, extra.authInfo);
430
+ const failure = evaluateSecuritySchemes(securitySchemes, extra.http?.authInfo);
625
431
  if (failure) {
626
- const headers = extra?.requestInfo?.headers ?? {};
627
- const header = (key) => {
628
- const value = headers[key];
629
- return Array.isArray(value) ? value[0] : value;
630
- };
432
+ const header = (key) => extra.http?.req?.headers.get(key) ?? undefined;
631
433
  return inBandChallengeResult(failure, this.resolveResourceMetadataUrl?.(header));
632
434
  }
633
435
  }
634
- const result = await cb(args, extra);
436
+ let result;
437
+ try {
438
+ result = await cb(args, extra);
439
+ }
440
+ catch (error) {
441
+ captureToolError(extra, error);
442
+ throw error;
443
+ }
444
+ warnOnLargeToolOutput(result, toolName);
635
445
  return {
636
446
  ...result,
637
447
  content: normalizeContent(result.content),
@@ -691,11 +501,13 @@ export class McpServer extends McpServerBaseOmitted {
691
501
  if (this.viteManifest) {
692
502
  return this.viteManifest;
693
503
  }
694
- return JSON.parse(readFileSync(path.join(process.cwd(), "dist", "assets", ".vite", "manifest.json"), "utf-8"));
504
+ cachedDiskManifest ??= JSON.parse(readFileSync(path.join(process.cwd(), "dist", "assets", ".vite", "manifest.json"), "utf-8"));
505
+ return cachedDiskManifest ?? {};
695
506
  }
696
- registerTool(...args) {
507
+ registerTool(rawConfig, rawCb) {
697
508
  const baseFn = McpServerBase.prototype.registerTool;
698
- const { config, cb } = normalizeRegisterToolArgs(args);
509
+ const config = rawConfig;
510
+ const cb = rawCb;
699
511
  const { name, view, auth, securitySchemes: rawSecuritySchemes, _meta: userToolMeta, ...toolFields } = config;
700
512
  const authNeedsProvider = auth !== undefined &&
701
513
  (!auth.allowsAnonymous || Boolean(auth.scopes?.length));
@@ -707,7 +519,7 @@ export class McpServer extends McpServerBaseOmitted {
707
519
  const securitySchemes = rawSecuritySchemes ??
708
520
  (auth && this.oauthEnabled ? authToSecuritySchemes(auth) : undefined);
709
521
  const toolMeta = { ...userToolMeta };
710
- this.securitySchemesByTool.set(name, securitySchemes);
522
+ this.toolSecuritySchemes.set(name, securitySchemes);
711
523
  if (securitySchemes) {
712
524
  // SEP-1488 puts `securitySchemes` at the top level of the tool
713
525
  // descriptor, but the SDK's `registerTool` drops unknown top-level
@@ -723,8 +535,11 @@ export class McpServer extends McpServerBaseOmitted {
723
535
  const wrappedCb = this.decorateToolHandler(cb, {
724
536
  attachViewUUID: Boolean(view),
725
537
  securitySchemes,
538
+ toolName: name,
726
539
  });
727
- baseFn.call(this, name, { ...toolFields, _meta: toolMeta }, wrappedCb);
540
+ baseFn.call(this, name, { ...toolFields, _meta: toolMeta }, toolFields.inputSchema === undefined
541
+ ? (extra) => wrappedCb({}, extra)
542
+ : wrappedCb);
728
543
  return this;
729
544
  }
730
545
  }