skybridge 2.0.0-alpha.718b53d → 2.0.0-alpha.71beea9

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 (146) hide show
  1. package/README.md +2 -0
  2. package/dist/cli/build-helpers.test.js +4 -2
  3. package/dist/cli/build-helpers.test.js.map +1 -1
  4. package/dist/context-warnings.d.ts +5 -0
  5. package/dist/context-warnings.js +31 -0
  6. package/dist/context-warnings.js.map +1 -0
  7. package/dist/context-warnings.test.d.ts +1 -0
  8. package/dist/context-warnings.test.js +28 -0
  9. package/dist/context-warnings.test.js.map +1 -0
  10. package/dist/server/auth/index.d.ts +16 -4
  11. package/dist/server/auth/index.js.map +1 -1
  12. package/dist/server/auth/providers/auth0.d.ts +24 -2
  13. package/dist/server/auth/providers/auth0.js.map +1 -1
  14. package/dist/server/auth/providers/auth0.test.js +4 -2
  15. package/dist/server/auth/providers/auth0.test.js.map +1 -1
  16. package/dist/server/auth/providers/authplane.d.ts +49 -0
  17. package/dist/server/auth/providers/authplane.js +57 -0
  18. package/dist/server/auth/providers/authplane.js.map +1 -0
  19. package/dist/server/auth/providers/authplane.test.d.ts +1 -0
  20. package/dist/server/auth/providers/authplane.test.js +140 -0
  21. package/dist/server/auth/providers/authplane.test.js.map +1 -0
  22. package/dist/server/auth/providers/clerk.d.ts +39 -2
  23. package/dist/server/auth/providers/clerk.js +4 -1
  24. package/dist/server/auth/providers/clerk.js.map +1 -1
  25. package/dist/server/auth/providers/clerk.test.js +5 -3
  26. package/dist/server/auth/providers/clerk.test.js.map +1 -1
  27. package/dist/server/auth/providers/custom.d.ts +10 -2
  28. package/dist/server/auth/providers/custom.js +10 -3
  29. package/dist/server/auth/providers/custom.js.map +1 -1
  30. package/dist/server/auth/providers/custom.test.js +11 -9
  31. package/dist/server/auth/providers/custom.test.js.map +1 -1
  32. package/dist/server/auth/providers/descope.d.ts +31 -2
  33. package/dist/server/auth/providers/descope.js.map +1 -1
  34. package/dist/server/auth/providers/descope.test.js +6 -4
  35. package/dist/server/auth/providers/descope.test.js.map +1 -1
  36. package/dist/server/auth/providers/stytch.d.ts +15 -2
  37. package/dist/server/auth/providers/stytch.js +4 -1
  38. package/dist/server/auth/providers/stytch.js.map +1 -1
  39. package/dist/server/auth/providers/verify-spy.d.ts +12 -0
  40. package/dist/server/auth/providers/verify-spy.js +21 -0
  41. package/dist/server/auth/providers/verify-spy.js.map +1 -0
  42. package/dist/server/auth/providers/workos.d.ts +24 -2
  43. package/dist/server/auth/providers/workos.js +4 -1
  44. package/dist/server/auth/providers/workos.js.map +1 -1
  45. package/dist/server/auth/setup.d.ts +1 -1
  46. package/dist/server/auth/setup.js +3 -4
  47. package/dist/server/auth/setup.js.map +1 -1
  48. package/dist/server/auth/setup.test.js +25 -8
  49. package/dist/server/auth/setup.test.js.map +1 -1
  50. package/dist/server/auth/verify.d.ts +37 -3
  51. package/dist/server/auth/verify.js +27 -3
  52. package/dist/server/auth/verify.js.map +1 -1
  53. package/dist/server/auth/verify.test.js +49 -0
  54. package/dist/server/auth/verify.test.js.map +1 -1
  55. package/dist/server/auth-extra.test-d.d.ts +1 -0
  56. package/dist/server/auth-extra.test-d.js +71 -0
  57. package/dist/server/auth-extra.test-d.js.map +1 -0
  58. package/dist/server/auth.d.ts +39 -1
  59. package/dist/server/auth.js.map +1 -1
  60. package/dist/server/express.js +8 -1
  61. package/dist/server/express.js.map +1 -1
  62. package/dist/server/express.test.js +28 -0
  63. package/dist/server/express.test.js.map +1 -1
  64. package/dist/server/index.d.ts +11 -7
  65. package/dist/server/index.js +4 -1
  66. package/dist/server/index.js.map +1 -1
  67. package/dist/server/mcp-errors.test.d.ts +1 -0
  68. package/dist/server/mcp-errors.test.js +37 -0
  69. package/dist/server/mcp-errors.test.js.map +1 -0
  70. package/dist/server/middleware.d.ts +33 -6
  71. package/dist/server/middleware.js +33 -0
  72. package/dist/server/middleware.js.map +1 -1
  73. package/dist/server/middleware.test.js +37 -1
  74. package/dist/server/middleware.test.js.map +1 -1
  75. package/dist/server/server.d.ts +72 -34
  76. package/dist/server/server.js +96 -46
  77. package/dist/server/server.js.map +1 -1
  78. package/dist/server/skills-integration.test.js +25 -9
  79. package/dist/server/skills-integration.test.js.map +1 -1
  80. package/dist/server/skills.d.ts +13 -8
  81. package/dist/server/skills.js +39 -28
  82. package/dist/server/skills.js.map +1 -1
  83. package/dist/server/skills.test.js +74 -41
  84. package/dist/server/skills.test.js.map +1 -1
  85. package/dist/server/tool-extra.test.d.ts +1 -0
  86. package/dist/server/tool-extra.test.js +72 -0
  87. package/dist/server/tool-extra.test.js.map +1 -0
  88. package/dist/test/utils.d.ts +3 -3
  89. package/dist/test/view.test.js +16 -15
  90. package/dist/test/view.test.js.map +1 -1
  91. package/dist/web/bridges/adaptor.js +14 -17
  92. package/dist/web/bridges/adaptor.js.map +1 -1
  93. package/dist/web/bridges/adaptor.test.js +23 -6
  94. package/dist/web/bridges/adaptor.test.js.map +1 -1
  95. package/dist/web/bridges/mcp-app/bridge.js +5 -3
  96. package/dist/web/bridges/mcp-app/bridge.js.map +1 -1
  97. package/dist/web/bridges/mcp-app/types.d.ts +2 -0
  98. package/dist/web/bridges/mcp-app/types.js.map +1 -1
  99. package/dist/web/bridges/types.d.ts +13 -5
  100. package/dist/web/bridges/types.js.map +1 -1
  101. package/dist/web/data-llm.test.js +3 -2
  102. package/dist/web/data-llm.test.js.map +1 -1
  103. package/dist/web/hooks/index.d.ts +1 -0
  104. package/dist/web/hooks/index.js +1 -0
  105. package/dist/web/hooks/index.js.map +1 -1
  106. package/dist/web/hooks/test/utils.d.ts +2 -1
  107. package/dist/web/hooks/test/utils.js +1 -1
  108. package/dist/web/hooks/test/utils.js.map +1 -1
  109. package/dist/web/hooks/use-download.d.ts +1 -3
  110. package/dist/web/hooks/use-download.js +1 -2
  111. package/dist/web/hooks/use-download.js.map +1 -1
  112. package/dist/web/hooks/use-download.test.js +4 -4
  113. package/dist/web/hooks/use-download.test.js.map +1 -1
  114. package/dist/web/hooks/use-host-info.d.ts +22 -0
  115. package/dist/web/hooks/use-host-info.js +30 -0
  116. package/dist/web/hooks/use-host-info.js.map +1 -0
  117. package/dist/web/hooks/use-host-info.test.d.ts +1 -0
  118. package/dist/web/hooks/use-host-info.test.js +59 -0
  119. package/dist/web/hooks/use-host-info.test.js.map +1 -0
  120. package/dist/web/hooks/use-register-view-tool.d.ts +2 -3
  121. package/dist/web/hooks/use-register-view-tool.js.map +1 -1
  122. package/dist/web/hooks/use-tool-info.d.ts +1 -20
  123. package/dist/web/hooks/use-tool-info.js +0 -1
  124. package/dist/web/hooks/use-tool-info.js.map +1 -1
  125. package/dist/web/hooks/use-tool-info.test-d.js +0 -5
  126. package/dist/web/hooks/use-tool-info.test-d.js.map +1 -1
  127. package/dist/web/hooks/use-tool-info.test.js +0 -5
  128. package/dist/web/hooks/use-tool-info.test.js.map +1 -1
  129. package/dist/web/hooks/use-view-state.js +19 -9
  130. package/dist/web/hooks/use-view-state.js.map +1 -1
  131. package/dist/web/hooks/use-view-state.test.js +31 -0
  132. package/dist/web/hooks/use-view-state.test.js.map +1 -1
  133. package/dist/web/index.d.ts +1 -0
  134. package/dist/web/index.js.map +1 -1
  135. package/dist/web/mount-view.d.ts +3 -2
  136. package/dist/web/mount-view.js +3 -2
  137. package/dist/web/mount-view.js.map +1 -1
  138. package/dist/web/plugin/plugin-build.test.d.ts +1 -0
  139. package/dist/web/plugin/plugin-build.test.js +54 -0
  140. package/dist/web/plugin/plugin-build.test.js.map +1 -0
  141. package/dist/web/plugin/plugin.js +15 -4
  142. package/dist/web/plugin/plugin.js.map +1 -1
  143. package/dist/web/plugin/plugin.test.d.ts +1 -0
  144. package/dist/web/plugin/plugin.test.js +61 -0
  145. package/dist/web/plugin/plugin.test.js.map +1 -0
  146. package/package.json +10 -10
@@ -1,8 +1,9 @@
1
1
  import type { McpUiToolMeta } from "@modelcontextprotocol/ext-apps";
2
- import { type ContentBlock, type Implementation, McpServer as McpServerBase, type RequestMeta, Server as SdkServer, type ServerOptions, type ServerResult, type StandardSchemaV1, type ToolAnnotations } from "@modelcontextprotocol/server";
2
+ import { type CacheHint, type ContentBlock, type Icon, type Implementation, McpServer as McpServerBase, type PromptCallback, type ReadResourceCallback, type ReadResourceTemplateCallback, type RegisteredPrompt, type RegisteredResource, type RegisteredResourceTemplate, type RequestMeta, type ResourceMetadata, type ResourceTemplate, type Server as SdkServer, type ServerOptions, type ServerResult, type StandardSchemaV1, type StandardSchemaWithJSON, type ToolAnnotations } from "@modelcontextprotocol/server";
3
3
  import express, { type ErrorRequestHandler, type Express, type RequestHandler } from "express";
4
4
  import type { InferSchemaOutput, RawInputShape } from "../standard-schema.js";
5
5
  import type { OAuthConfig } from "./auth/index.js";
6
+ import type { ExtraClaims } from "./auth.js";
6
7
  import type { McpExtra, McpExtraFor, McpMethodString, McpMiddlewareFilter, McpMiddlewareFn, McpResultFor, McpTypedMiddlewareFn, McpWildcard } from "./middleware.js";
7
8
  import { type SkillsManifest } from "./skills.js";
8
9
  /**
@@ -66,11 +67,6 @@ export interface ViewConfig {
66
67
  component: ViewName;
67
68
  /** Human-readable label the host may show alongside the view. */
68
69
  description?: string;
69
- /**
70
- * @deprecated No-op. Every view emits a single ext-apps resource regardless
71
- * of this value. Will be removed in a future major.
72
- */
73
- hosts?: ViewHostType[];
74
70
  /** Request a visible border around the view (forwarded as `ui.prefersBorder`). */
75
71
  prefersBorder?: boolean;
76
72
  /** Override the iframe's served domain (advanced; forwarded as `ui.domain`). */
@@ -105,12 +101,18 @@ export type ToolAuth = {
105
101
  * from Express's own types so the public API doesn't depend on `body-parser`.
106
102
  */
107
103
  export type JsonOptions = NonNullable<Parameters<typeof express.json>[0]>;
108
- /** Skybridge-specific server options, passed as the third `McpServer` constructor argument. */
109
- export interface SkybridgeServerOptions {
104
+ /**
105
+ * Skybridge-specific server options, passed as the third `McpServer` constructor
106
+ * argument.
107
+ *
108
+ * @typeParam TAuthExtra - Claims the `oauth` verifier populates. Inferred from
109
+ * the config a provider returns, and carried on to tool handlers.
110
+ */
111
+ export interface SkybridgeServerOptions<TAuthExtra extends ExtraClaims = ExtraClaims> {
110
112
  /** Options for the built-in `express.json()` middleware, e.g. `{ limit: "10mb" }`. */
111
113
  json?: JsonOptions;
112
114
  /** Resource-server OAuth config. When set, mounts well-known metadata and bearer auth on `/mcp`. */
113
- oauth?: OAuthConfig;
115
+ oauth?: OAuthConfig<TAuthExtra>;
114
116
  /**
115
117
  * @experimental Serve Agent Skills from `src/skills` over MCP (SEP-2640).
116
118
  * API may change.
@@ -134,7 +136,6 @@ export interface KnownToolMeta {
134
136
  "openai/fileParams"?: string[];
135
137
  /** MCP Apps: control whether the tool is exposed to the model, the app, or both. */
136
138
  ui?: Pick<McpUiToolMeta, "visibility">;
137
- securitySchemes?: SecurityScheme[];
138
139
  }
139
140
  /** {@link KnownToolMeta} merged with arbitrary string-keyed metadata for custom flags. */
140
141
  export type ToolMeta = KnownToolMeta & Record<string, unknown>;
@@ -175,9 +176,9 @@ type ExtractMeta<T> = [Extract<T, {
175
176
  }> extends {
176
177
  _meta: infer M;
177
178
  } ? Simplify<M> : unknown;
178
- type AddTool<TTools, TName extends string, TInput extends RawInputShape, TOutput, TResponseMetadata = unknown> = McpServer<TTools & {
179
+ type AddTool<TTools, TName extends string, TInput extends RawInputShape, TOutput, TResponseMetadata = unknown, TAuthExtra extends ExtraClaims = ExtraClaims> = McpServer<TTools & {
179
180
  [K in TName]: ToolDef<ShapeOutput<TInput>, TOutput, TResponseMetadata>;
180
- }>;
181
+ }, TAuthExtra>;
181
182
  interface ToolConfigBase<TInput extends RawInputShape | StandardSchemaV1> {
182
183
  name: string;
183
184
  title?: string;
@@ -236,14 +237,16 @@ export interface ClientHintsMeta {
236
237
  /** Stable id for the currently mounted widget instance. */
237
238
  "openai/widgetSessionId"?: string;
238
239
  }
239
- type ToolHandlerExtra = Omit<McpExtra, "_meta"> & {
240
- _meta?: RequestMeta & ClientHintsMeta;
240
+ type ToolHandlerExtra<TAuthExtra extends ExtraClaims = ExtraClaims> = Omit<McpExtra<TAuthExtra>, "mcpReq"> & {
241
+ mcpReq: Omit<McpExtra<TAuthExtra>["mcpReq"], "_meta"> & {
242
+ _meta?: RequestMeta & ClientHintsMeta;
243
+ };
241
244
  };
242
245
  type ToolHandler<TInput extends RawInputShape, TReturn extends {
243
246
  content?: HandlerContent;
244
247
  } = {
245
248
  content?: HandlerContent;
246
- }> = (args: ShapeOutput<TInput>, extra: ToolHandlerExtra) => TReturn | Promise<TReturn>;
249
+ }, TAuthExtra extends ExtraClaims = ExtraClaims> = (args: ShapeOutput<TInput>, extra: ToolHandlerExtra<TAuthExtra>) => TReturn | Promise<TReturn>;
247
250
  /**
248
251
  * Coerce a tool handler's return value into an MCP `content` array. Strings
249
252
  * become a single `TextContent`; a single block is wrapped in an array;
@@ -251,7 +254,7 @@ type ToolHandler<TInput extends RawInputShape, TReturn extends {
251
254
  * who build content lazily can apply the same normalization.
252
255
  */
253
256
  export declare function normalizeContent(content: HandlerContent | undefined): ContentBlock[];
254
- interface McpServerBaseOmitted extends Omit<McpServerBase, "registerTool" | "connect"> {
257
+ interface McpServerBaseOmitted extends Omit<McpServerBase, "registerTool" | "registerResource" | "registerPrompt" | "connect"> {
255
258
  }
256
259
  declare const McpServerBaseOmitted: new (...args: ConstructorParameters<typeof McpServerBase>) => McpServerBaseOmitted;
257
260
  /**
@@ -265,7 +268,7 @@ export declare function __setBuildManifest(manifest: Record<string, {
265
268
  file: string;
266
269
  }>): void;
267
270
  export declare function __setSkillsManifest(manifest: SkillsManifest): void;
268
- export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>> extends McpServerBaseOmitted {
271
+ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>, TAuthExtra extends ExtraClaims = ExtraClaims> extends McpServerBaseOmitted {
269
272
  readonly $types: McpServerTypes<TTools>;
270
273
  /**
271
274
  * The underlying Express app. Use this to extend the HTTP server with
@@ -285,6 +288,8 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
285
288
  private customErrorMiddleware;
286
289
  private mcpMiddlewareEntries;
287
290
  private mcpMiddlewareApplied;
291
+ private middlewareEntriesCache;
292
+ private readonly registrations;
288
293
  private claimedViews;
289
294
  private viewMetaBuilders;
290
295
  /**
@@ -300,7 +305,32 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
300
305
  private oauthEnabled;
301
306
  private resolveResourceMetadataUrl?;
302
307
  private securitySchemesByTool;
303
- constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions);
308
+ constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions<TAuthExtra>);
309
+ /**
310
+ * Register a resource, recorded so every per-request instance carries it.
311
+ * Signature owned by Skybridge (not inherited) so a typed wrapper can land
312
+ * in a minor without a type-level break.
313
+ */
314
+ registerResource(name: string, uri: string, config: ResourceMetadata & {
315
+ cacheHint?: CacheHint;
316
+ }, readCallback: ReadResourceCallback): RegisteredResource;
317
+ registerResource(name: string, template: ResourceTemplate, config: ResourceMetadata & {
318
+ cacheHint?: CacheHint;
319
+ }, readCallback: ReadResourceTemplateCallback): RegisteredResourceTemplate;
320
+ /**
321
+ * Register a prompt, recorded so every per-request instance carries it.
322
+ * Signature owned by Skybridge (not inherited) so a typed wrapper can land
323
+ * in a minor without a type-level break.
324
+ */
325
+ registerPrompt<Args extends StandardSchemaWithJSON>(name: string, config: {
326
+ title?: string;
327
+ description?: string;
328
+ argsSchema?: Args;
329
+ icons?: Icon[];
330
+ _meta?: Record<string, unknown>;
331
+ }, cb: PromptCallback<Args>): RegisteredPrompt;
332
+ private recordInherited;
333
+ private skillRegistrar;
304
334
  private setupSkills;
305
335
  /**
306
336
  * Register Express middleware on the underlying app. Mirrors `app.use` —
@@ -328,12 +358,12 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
328
358
  useOnError(...handlers: ErrorRequestHandler[]): this;
329
359
  useOnError(path: string, ...handlers: ErrorRequestHandler[]): this;
330
360
  /** Register MCP protocol-level middleware (catch-all). */
331
- mcpMiddleware(handler: McpMiddlewareFn): this;
361
+ mcpMiddleware(handler: McpMiddlewareFn<TAuthExtra>): this;
332
362
  /** Register MCP protocol-level middleware for all requests (`extra` is `McpExtra`). */
333
363
  mcpMiddleware(filter: "request", handler: (request: {
334
364
  method: string;
335
365
  params: Record<string, unknown>;
336
- }, extra: McpExtra, next: () => Promise<ServerResult>) => Promise<unknown> | unknown): this;
366
+ }, extra: McpExtra<TAuthExtra>, next: () => Promise<ServerResult>) => Promise<unknown> | unknown): this;
337
367
  /** Register MCP protocol-level middleware for all notifications (`extra` is `undefined`). */
338
368
  mcpMiddleware(filter: "notification", handler: (request: {
339
369
  method: string;
@@ -343,7 +373,7 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
343
373
  * Register MCP protocol-level middleware for an exact method.
344
374
  * Narrows `params`, `extra`, and `next()` result based on the method string.
345
375
  */
346
- mcpMiddleware<M extends McpMethodString>(filter: M, handler: McpTypedMiddlewareFn<M>): this;
376
+ mcpMiddleware<M extends McpMethodString>(filter: M, handler: McpTypedMiddlewareFn<M, TAuthExtra>): this;
347
377
  /**
348
378
  * Register MCP protocol-level middleware for a wildcard pattern (e.g. `"tools/*"`).
349
379
  * `next()` returns the union of result types for matching methods.
@@ -351,14 +381,15 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
351
381
  mcpMiddleware<W extends McpWildcard>(filter: W, handler: (request: {
352
382
  method: string;
353
383
  params: Record<string, unknown>;
354
- }, extra: McpExtraFor<W>, next: () => Promise<McpResultFor<W>>) => Promise<unknown> | unknown): this;
384
+ }, extra: McpExtraFor<W, TAuthExtra>, next: () => Promise<McpResultFor<W>>) => Promise<unknown> | unknown): this;
355
385
  /**
356
386
  * Register MCP protocol-level middleware with a method filter.
357
387
  * Filter can be an exact method (`"tools/call"`), wildcard (`"tools/*"`),
358
388
  * category (`"request"` | `"notification"`), or an array of those.
359
389
  */
360
- mcpMiddleware(filter: McpMiddlewareFilter, handler: McpMiddlewareFn): this;
390
+ mcpMiddleware(filter: McpMiddlewareFilter, handler: McpMiddlewareFn<TAuthExtra>): this;
361
391
  private applyMcpMiddleware;
392
+ private instrumentHandlers;
362
393
  /**
363
394
  * Connect to an MCP transport (override of the SDK's `connect`). Use this
364
395
  * when you're embedding Skybridge in a host that already manages its own
@@ -369,17 +400,22 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
369
400
  */
370
401
  connect(transport: Parameters<typeof McpServerBase.prototype.connect>[0]): Promise<void>;
371
402
  /**
372
- * Build a fresh underlying `Server` for one stateless HTTP request. The
373
- * SDK's `Protocol` only allows one transport per instance, so we can't
374
- * reuse this `McpServer` across concurrent requests. The SDK's idiomatic
375
- * fix is a `() => Server` factory (passed to `createMcpHandler`), but a
376
- * singleton API is Skybridge's contract — so the factory returns a fresh
377
- * `Server` that shares the main server's handler maps by reference. The
378
- * cast is unavoidable: there's no public API to inject handler maps.
379
- * `getHandlerMaps` validates the read side and fails fast on SDK field
380
- * renames.
403
+ * Build a fresh server for one stateless HTTP request, as
404
+ * `createMcpHandler`'s factory contract requires: every registration is
405
+ * replayed onto the new instance so the SDK's handler closures belong to
406
+ * the instance whose protocol era it stamps. Sharing the singleton's
407
+ * handler maps instead would bind them to an instance that is never
408
+ * marked, pinning every request to the 2025 codec and letting concurrent
409
+ * callers overwrite each other's negotiated version.
381
410
  */
382
411
  createStatelessServerInstance(): SdkServer;
412
+ /**
413
+ * Apply an SDK registration to the singleton and remember it, so each
414
+ * per-request instance can be built with the same surface.
415
+ */
416
+ private record;
417
+ /** Records a raw request handler (used for methods the SDK has no sugar for). */
418
+ private recordRequestHandler;
383
419
  /**
384
420
  * Start the HTTP server. Listens on `process.env.__PORT` (default `3000`),
385
421
  * mounts the `/mcp` route, applies any custom Express middleware registered
@@ -447,7 +483,9 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
447
483
  content?: HandlerContent;
448
484
  }>(config: ToolConfig<InputArgs> & {
449
485
  name: TName;
450
- }, cb: ToolHandler<InputArgs, TReturn>): AddTool<TTools, TName, InputArgs, ExtractStructuredContent<TReturn>, ExtractMeta<TReturn>>;
451
- registerTool<InputArgs extends RawInputShape>(config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs>): this;
486
+ }, cb: ToolHandler<InputArgs, TReturn, TAuthExtra>): AddTool<TTools, TName, InputArgs, ExtractStructuredContent<TReturn>, ExtractMeta<TReturn>, TAuthExtra>;
487
+ registerTool<InputArgs extends RawInputShape>(config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs, {
488
+ content?: HandlerContent;
489
+ }, TAuthExtra>): this;
452
490
  }
453
491
  export {};
@@ -2,15 +2,16 @@ import crypto from "node:crypto";
2
2
  import { readFileSync } from "node:fs";
3
3
  import http from "node:http";
4
4
  import path from "node:path";
5
- import { McpServer as McpServerBase, Server as SdkServer, } from "@modelcontextprotocol/server";
5
+ import { McpServer as McpServerBase, } from "@modelcontextprotocol/server";
6
6
  import { mergeWith, union } from "es-toolkit";
7
7
  import express, {} from "express";
8
+ import { warnOnLargeToolOutput } from "../context-warnings.js";
8
9
  import { authToSecuritySchemes, evaluateSecuritySchemes, inBandChallengeResult, } from "./auth/security-schemes.js";
9
10
  import { setupOAuth } from "./auth/setup.js";
10
11
  import { createApp } from "./express.js";
11
12
  import { hostFromUserAgent } from "./host.js";
12
13
  import { createMiddlewareEntry } from "./metric.js";
13
- import { buildMiddlewareChain, getHandlerMaps } from "./middleware.js";
14
+ import { buildMiddlewareChain, captureToolError, getHandlerMaps, } from "./middleware.js";
14
15
  import { resolveServerOrigin } from "./requestOrigin.js";
15
16
  import { discoverSkills, registerSkills, SKILLS_EXTENSION_KEY, } from "./skills.js";
16
17
  import { templateHelper } from "./templateHelper.js";
@@ -129,26 +130,6 @@ function withSkillsCapability(options, skybridgeOptions) {
129
130
  },
130
131
  };
131
132
  }
132
- // Collapses registerTool's two overloads into a single { config, cb } shape.
133
- // registerTool("greet", { description }, handler)
134
- // -> { config: { name: "greet", description }, cb: handler }
135
- // registerTool({ name: "greet", description }, handler)
136
- // -> { config: { name: "greet", description }, cb: handler }
137
- function normalizeRegisterToolArgs(args) {
138
- if (typeof args[0] === "string") {
139
- return {
140
- config: {
141
- name: args[0],
142
- ...args[1],
143
- },
144
- cb: args[2],
145
- };
146
- }
147
- return {
148
- config: args[0],
149
- cb: args[1],
150
- };
151
- }
152
133
  export class McpServer extends McpServerBaseOmitted {
153
134
  /**
154
135
  * The underlying Express app. Use this to extend the HTTP server with
@@ -168,6 +149,8 @@ export class McpServer extends McpServerBaseOmitted {
168
149
  customErrorMiddleware = [];
169
150
  mcpMiddlewareEntries = [];
170
151
  mcpMiddlewareApplied = false;
152
+ middlewareEntriesCache = null;
153
+ registrations = [];
171
154
  claimedViews = new Map();
172
155
  viewMetaBuilders = new Map();
173
156
  /**
@@ -205,6 +188,43 @@ export class McpServer extends McpServerBaseOmitted {
205
188
  }
206
189
  this.setupSkills(Boolean(skybridgeOptions?.skills));
207
190
  }
191
+ registerResource(...args) {
192
+ return this.recordInherited("registerResource", args);
193
+ }
194
+ /**
195
+ * Register a prompt, recorded so every per-request instance carries it.
196
+ * Signature owned by Skybridge (not inherited) so a typed wrapper can land
197
+ * in a minor without a type-level break.
198
+ */
199
+ registerPrompt(name, config, cb) {
200
+ return this.recordInherited("registerPrompt", [
201
+ name,
202
+ config,
203
+ cb,
204
+ ]);
205
+ }
206
+ recordInherited(method, args) {
207
+ const base = McpServerBase.prototype[method];
208
+ let registered;
209
+ this.record((target) => {
210
+ const result = base.apply(target, args);
211
+ if (target === this) {
212
+ registered = result;
213
+ }
214
+ });
215
+ return registered;
216
+ }
217
+ skillRegistrar() {
218
+ const registerResource = this.registerResource.bind(this);
219
+ return {
220
+ registerResource,
221
+ server: {
222
+ setRequestHandler: ((...args) => {
223
+ this.recordRequestHandler(...args);
224
+ }),
225
+ },
226
+ };
227
+ }
208
228
  setupSkills(enabled) {
209
229
  const manifest = pendingSkillsManifest;
210
230
  pendingSkillsManifest = null;
@@ -215,7 +235,7 @@ export class McpServer extends McpServerBaseOmitted {
215
235
  if (skills.length === 0) {
216
236
  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.`);
217
237
  }
218
- registerSkills(this, skills);
238
+ registerSkills(this.skillRegistrar(), skills);
219
239
  }
220
240
  use(pathOrHandler, ...handlers) {
221
241
  // Branching is load-bearing: Express's `app.use` overloads can't be
@@ -351,7 +371,12 @@ export class McpServer extends McpServerBaseOmitted {
351
371
  toolsListSecuritySchemesEntry,
352
372
  ...this.mcpMiddlewareEntries,
353
373
  ];
354
- const { requestHandlers, notificationHandlers } = getHandlerMaps(this.server);
374
+ this.middlewareEntriesCache = entries;
375
+ this.instrumentHandlers(this.server);
376
+ }
377
+ instrumentHandlers(server) {
378
+ const entries = this.middlewareEntriesCache ?? [];
379
+ const { requestHandlers, notificationHandlers } = getHandlerMaps(server);
355
380
  const instrumentMap = (map, isNotification) => {
356
381
  for (const [method, handler] of map) {
357
382
  map.set(method, buildMiddlewareChain(method, isNotification, handler, entries));
@@ -375,24 +400,36 @@ export class McpServer extends McpServerBaseOmitted {
375
400
  return McpServerBase.prototype.connect.call(this, transport);
376
401
  }
377
402
  /**
378
- * Build a fresh underlying `Server` for one stateless HTTP request. The
379
- * SDK's `Protocol` only allows one transport per instance, so we can't
380
- * reuse this `McpServer` across concurrent requests. The SDK's idiomatic
381
- * fix is a `() => Server` factory (passed to `createMcpHandler`), but a
382
- * singleton API is Skybridge's contract — so the factory returns a fresh
383
- * `Server` that shares the main server's handler maps by reference. The
384
- * cast is unavoidable: there's no public API to inject handler maps.
385
- * `getHandlerMaps` validates the read side and fails fast on SDK field
386
- * renames.
403
+ * Build a fresh server for one stateless HTTP request, as
404
+ * `createMcpHandler`'s factory contract requires: every registration is
405
+ * replayed onto the new instance so the SDK's handler closures belong to
406
+ * the instance whose protocol era it stamps. Sharing the singleton's
407
+ * handler maps instead would bind them to an instance that is never
408
+ * marked, pinning every request to the 2025 codec and letting concurrent
409
+ * callers overwrite each other's negotiated version.
387
410
  */
388
411
  createStatelessServerInstance() {
389
412
  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
- return fresh;
413
+ const fresh = new McpServerBase(this.serverInfo, this.serverOptions);
414
+ for (const apply of this.registrations) {
415
+ apply(fresh);
416
+ }
417
+ this.instrumentHandlers(fresh.server);
418
+ return fresh.server;
419
+ }
420
+ /**
421
+ * Apply an SDK registration to the singleton and remember it, so each
422
+ * per-request instance can be built with the same surface.
423
+ */
424
+ record(apply) {
425
+ this.registrations.push(apply);
426
+ apply(this);
427
+ }
428
+ /** Records a raw request handler (used for methods the SDK has no sugar for). */
429
+ recordRequestHandler(...args) {
430
+ this.record((target) => {
431
+ target.server.setRequestHandler(...args);
432
+ });
396
433
  }
397
434
  /**
398
435
  * Start the HTTP server. Listens on `process.env.__PORT` (default `3000`),
@@ -614,16 +651,25 @@ export class McpServer extends McpServerBaseOmitted {
614
651
  this.viewUriByPath.set(`ui://widgets/apps-sdk/${component}.html`, canonicalUri);
615
652
  this.viewUriByPath.set(`ui://widgets/ext-apps/${component}.html`, canonicalUri);
616
653
  }
617
- decorateToolHandler(cb, { attachViewUUID, securitySchemes, }) {
654
+ decorateToolHandler(cb, { attachViewUUID, securitySchemes, toolName, }) {
618
655
  return async (args, extra) => {
656
+ const toolExtra = extra ?? args;
619
657
  if (this.oauthEnabled) {
620
- const failure = evaluateSecuritySchemes(securitySchemes, extra.http?.authInfo);
658
+ const failure = evaluateSecuritySchemes(securitySchemes, toolExtra?.http?.authInfo);
621
659
  if (failure) {
622
- const header = (key) => extra.http?.req?.headers.get(key) ?? undefined;
660
+ const header = (key) => toolExtra?.http?.req?.headers.get(key) ?? undefined;
623
661
  return inBandChallengeResult(failure, this.resolveResourceMetadataUrl?.(header));
624
662
  }
625
663
  }
626
- const result = await cb(args, extra);
664
+ let result;
665
+ try {
666
+ result = await cb(args, extra);
667
+ }
668
+ catch (error) {
669
+ captureToolError(toolExtra, error);
670
+ throw error;
671
+ }
672
+ warnOnLargeToolOutput(result, toolName);
627
673
  return {
628
674
  ...result,
629
675
  content: normalizeContent(result.content),
@@ -685,9 +731,10 @@ export class McpServer extends McpServerBaseOmitted {
685
731
  }
686
732
  return JSON.parse(readFileSync(path.join(process.cwd(), "dist", "assets", ".vite", "manifest.json"), "utf-8"));
687
733
  }
688
- registerTool(...args) {
734
+ registerTool(rawConfig, rawCb) {
689
735
  const baseFn = McpServerBase.prototype.registerTool;
690
- const { config, cb } = normalizeRegisterToolArgs(args);
736
+ const config = rawConfig;
737
+ const cb = rawCb;
691
738
  const { name, view, auth, securitySchemes: rawSecuritySchemes, _meta: userToolMeta, ...toolFields } = config;
692
739
  const authNeedsProvider = auth !== undefined &&
693
740
  (!auth.allowsAnonymous || Boolean(auth.scopes?.length));
@@ -715,8 +762,11 @@ export class McpServer extends McpServerBaseOmitted {
715
762
  const wrappedCb = this.decorateToolHandler(cb, {
716
763
  attachViewUUID: Boolean(view),
717
764
  securitySchemes,
765
+ toolName: name,
766
+ });
767
+ this.record((target) => {
768
+ baseFn.call(target, name, { ...toolFields, _meta: toolMeta }, wrappedCb);
718
769
  });
719
- baseFn.call(this, name, { ...toolFields, _meta: toolMeta }, wrappedCb);
720
770
  return this;
721
771
  }
722
772
  }