skybridge 1.0.1 → 1.0.3

package/dist/server/file-ref.js

@@ -1,4 +1,23 @@
 import { z } from "zod";
+/**
+ * Zod schema for a host-managed file reference passed between tools and views.
+ *
+ * Use it inside a tool's `inputSchema` or `outputSchema` so the host can
+ * recognize the field as a file and surface attach / preview affordances.
+ *
+ * @example
+ * ```ts
+ * server.registerTool({
+ *   name: "summarize-document",
+ *   inputSchema: { document: FileRef },
+ * }, async ({ document }) => {
+ *   const res = await fetch(document.download_url);
+ *   // …
+ * });
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/file-ref
+ */
 export const FileRef = z.object({
     file_id: z.string(),
     download_url: z.string(),

package/dist/server/file-ref.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-ref.js","sourceRoot":"","sources":["../../src/server/file-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC","sourcesContent":["import { z } from \"zod\";\n\nexport const FileRef = z.object({\n  file_id: z.string(),\n  download_url: z.string(),\n  mime_type: z.string().optional(),\n  file_name: z.string().optional(),\n});\n\nexport type FileRef = z.infer<typeof FileRef>;\n"]}
+{"version":3,"file":"file-ref.js","sourceRoot":"","sources":["../../src/server/file-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE;IACxB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAChC,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC","sourcesContent":["import { z } from \"zod\";\n\n/**\n * Zod schema for a host-managed file reference passed between tools and views.\n *\n * Use it inside a tool's `inputSchema` or `outputSchema` so the host can\n * recognize the field as a file and surface attach / preview affordances.\n *\n * @example\n * ```ts\n * server.registerTool({\n *   name: \"summarize-document\",\n *   inputSchema: { document: FileRef },\n * }, async ({ document }) => {\n *   const res = await fetch(document.download_url);\n *   // …\n * });\n * ```\n *\n * @see https://docs.skybridge.tech/api-reference/file-ref\n */\nexport const FileRef = z.object({\n  file_id: z.string(),\n  download_url: z.string(),\n  mime_type: z.string().optional(),\n  file_name: z.string().optional(),\n});\n\n/** Inferred TypeScript type for {@link FileRef}. */\nexport type FileRef = z.infer<typeof FileRef>;\n"]}

package/dist/server/index.d.ts

@@ -1,7 +1,8 @@
+export { type AuthInfo, type AuthMetadataOptions, type BearerAuthMiddlewareOptions, InvalidTokenError, mcpAuthMetadataRouter, optionalBearerAuth, requireBearerAuth, } from "./auth.js";
 export { audio, embeddedResource, image, resourceLink, text, } from "./content-helpers.js";
 export { FileRef } from "./file-ref.js";
 export type { AnyToolRegistry, InferTools, ToolInput, ToolNames, ToolOutput, ToolResponseMetadata, } from "./inferUtilityTypes.js";
 export type { McpExtra, McpMethodString, McpMiddlewareFilter, McpMiddlewareFn, McpResultFor, McpTypedMiddlewareFn, McpWildcard, } from "./middleware.js";
-export type { HandlerContent, KnownToolMeta, McpServerTypes, ToolDef, ToolMeta, ViewConfig, ViewCsp, ViewHostType, ViewName, ViewNameRegistry, } from "./server.js";
+export type { HandlerContent, KnownToolMeta, McpServerTypes, SecurityScheme, ToolDef, ToolMeta, ViewConfig, ViewCsp, ViewHostType, ViewName, ViewNameRegistry, } from "./server.js";
 export { McpServer, normalizeContent, } from "./server.js";
 export { viewsDevServer } from "./viewsDevServer.js";

package/dist/server/index.js

@@ -1,3 +1,4 @@
+export { InvalidTokenError, mcpAuthMetadataRouter, optionalBearerAuth, requireBearerAuth, } from "./auth.js";
 export { audio, embeddedResource, image, resourceLink, text, } from "./content-helpers.js";
 export { FileRef } from "./file-ref.js";
 export { McpServer, normalizeContent, } from "./server.js";

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,gBAAgB,EAChB,KAAK,EACL,YAAY,EACZ,IAAI,GACL,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AA8BxC,OAAO,EACL,SAAS,EACT,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC","sourcesContent":["export {\n  audio,\n  embeddedResource,\n  image,\n  resourceLink,\n  text,\n} from \"./content-helpers.js\";\nexport { FileRef } from \"./file-ref.js\";\nexport type {\n  AnyToolRegistry,\n  InferTools,\n  ToolInput,\n  ToolNames,\n  ToolOutput,\n  ToolResponseMetadata,\n} from \"./inferUtilityTypes.js\";\nexport type {\n  McpExtra,\n  McpMethodString,\n  McpMiddlewareFilter,\n  McpMiddlewareFn,\n  McpResultFor,\n  McpTypedMiddlewareFn,\n  McpWildcard,\n} from \"./middleware.js\";\nexport type {\n  HandlerContent,\n  KnownToolMeta,\n  McpServerTypes,\n  ToolDef,\n  ToolMeta,\n  ViewConfig,\n  ViewCsp,\n  ViewHostType,\n  ViewName,\n  ViewNameRegistry,\n} from \"./server.js\";\nexport {\n  McpServer,\n  normalizeContent,\n} from \"./server.js\";\nexport { viewsDevServer } from \"./viewsDevServer.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,iBAAiB,EACjB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,KAAK,EACL,gBAAgB,EAChB,KAAK,EACL,YAAY,EACZ,IAAI,GACL,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AA+BxC,OAAO,EACL,SAAS,EACT,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC","sourcesContent":["export {\n  type AuthInfo,\n  type AuthMetadataOptions,\n  type BearerAuthMiddlewareOptions,\n  InvalidTokenError,\n  mcpAuthMetadataRouter,\n  optionalBearerAuth,\n  requireBearerAuth,\n} from \"./auth.js\";\nexport {\n  audio,\n  embeddedResource,\n  image,\n  resourceLink,\n  text,\n} from \"./content-helpers.js\";\nexport { FileRef } from \"./file-ref.js\";\nexport type {\n  AnyToolRegistry,\n  InferTools,\n  ToolInput,\n  ToolNames,\n  ToolOutput,\n  ToolResponseMetadata,\n} from \"./inferUtilityTypes.js\";\nexport type {\n  McpExtra,\n  McpMethodString,\n  McpMiddlewareFilter,\n  McpMiddlewareFn,\n  McpResultFor,\n  McpTypedMiddlewareFn,\n  McpWildcard,\n} from \"./middleware.js\";\nexport type {\n  HandlerContent,\n  KnownToolMeta,\n  McpServerTypes,\n  SecurityScheme,\n  ToolDef,\n  ToolMeta,\n  ViewConfig,\n  ViewCsp,\n  ViewHostType,\n  ViewName,\n  ViewNameRegistry,\n} from \"./server.js\";\nexport {\n  McpServer,\n  normalizeContent,\n} from \"./server.js\";\nexport { viewsDevServer } from \"./viewsDevServer.js\";\n"]}

package/dist/server/middleware.d.ts

@@ -19,7 +19,12 @@ export type McpMiddlewareFn = (request: {
  * MCP methods the server handles (incoming from client).
  */
 export type McpMethodString = ClientRequest["method"] | ClientNotification["method"];
-/** Extract params type for a specific MCP method from SDK unions. */
+/**
+ * Resolve the `params` type for a specific MCP method (request or notification)
+ * from the SDK's typed unions. Falls back to `Record<string, unknown>` for
+ * unknown methods. Used by {@link McpTypedMiddlewareFn} to narrow the request
+ * shape in typed middleware.
+ */
 export type McpRequestParams<M extends string> = Extract<ClientRequest, {
     method: M;
 }> extends {
@@ -29,7 +34,11 @@ export type McpRequestParams<M extends string> = Extract<ClientRequest, {
 }> extends {
     params: infer P;
 } ? P : Record<string, unknown>;
-/** Resolve extra type: McpExtra for requests, undefined for notifications. */
+/**
+ * Resolve the `extra` arg type for a specific MCP method: {@link McpExtra} for
+ * request methods, `undefined` for notification methods (the SDK does not
+ * pass extra context for notifications).
+ */
 export type McpExtraFor<M extends string> = M extends ClientRequest["method"] ? McpExtra : M extends ClientNotification["method"] ? undefined : McpExtra | undefined;
 /** Maps each MCP request method to its SDK result type. */
 interface McpResultMap {
@@ -59,7 +68,11 @@ interface McpResultMap {
  * For unknown/unmatched methods, falls back to `ServerResult`.
  */
 export type McpResultFor<M extends string> = M extends keyof McpResultMap ? McpResultMap[M] : M extends `${infer Prefix}/*` ? [McpResultMap[keyof McpResultMap & `${Prefix}/${string}`]] extends [never] ? M extends ToWildcard<ClientNotification["method"]> ? undefined : ServerResult : McpResultMap[keyof McpResultMap & `${Prefix}/${string}`] : M extends ClientNotification["method"] ? undefined : ServerResult;
-/** Typed middleware fn for a specific method — narrows params, extra, and next() result. */
+/**
+ * Typed middleware function for a specific method. Narrows `request.params`
+ * via {@link McpRequestParams}, `extra` via {@link McpExtraFor}, and the
+ * resolved value of `next()` via {@link McpResultFor}.
+ */
 export type McpTypedMiddlewareFn<M extends string> = (request: {
     method: M;
     params: McpRequestParams<M>;

package/dist/server/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/server/middleware.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport type { RequestHandlerExtra } from \"@modelcontextprotocol/sdk/shared/protocol.js\";\nimport type {\n  CallToolResult,\n  CancelTaskResult,\n  ClientNotification,\n  ClientRequest,\n  CompleteResult,\n  EmptyResult,\n  GetPromptResult,\n  GetTaskPayloadResult,\n  GetTaskResult,\n  InitializeResult,\n  ListPromptsResult,\n  ListResourcesResult,\n  ListResourceTemplatesResult,\n  ListTasksResult,\n  ListToolsResult,\n  ReadResourceResult,\n  ServerNotification,\n  ServerRequest,\n  ServerResult,\n} from \"@modelcontextprotocol/sdk/types.js\";\n\n/**\n * The `extra` context object provided by the MCP SDK to request handlers.\n */\nexport type McpExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;\n\n/**\n * A single MCP middleware function following the onion model.\n * Call `next()` to invoke the next middleware or the final handler.\n * For notifications, `extra` is `undefined` (SDK does not provide extra context)\n * and `next()` resolves to `undefined`.\n */\nexport type McpMiddlewareFn = (\n  request: { method: string; params: Record<string, unknown> },\n  extra: McpExtra | undefined,\n  next: () => Promise<unknown>,\n) => Promise<unknown> | unknown;\n\n/**\n * MCP methods the server handles (incoming from client).\n */\nexport type McpMethodString =\n  | ClientRequest[\"method\"]\n  | ClientNotification[\"method\"];\n\n/** Extract params type for a specific MCP method from SDK unions. */\nexport type McpRequestParams<M extends string> =\n  Extract<ClientRequest, { method: M }> extends { params: infer P }\n    ? P\n    : Extract<ClientNotification, { method: M }> extends { params: infer P }\n      ? P\n      : Record<string, unknown>;\n\n/** Resolve extra type: McpExtra for requests, undefined for notifications. */\nexport type McpExtraFor<M extends string> = M extends ClientRequest[\"method\"]\n  ? McpExtra\n  : M extends ClientNotification[\"method\"]\n    ? undefined\n    : McpExtra | undefined;\n\n/** Maps each MCP request method to its SDK result type. */\ninterface McpResultMap {\n  ping: EmptyResult;\n  initialize: InitializeResult;\n  \"tools/list\": ListToolsResult;\n  \"tools/call\": CallToolResult;\n  \"resources/list\": ListResourcesResult;\n  \"resources/templates/list\": ListResourceTemplatesResult;\n  \"resources/read\": ReadResourceResult;\n  \"resources/subscribe\": EmptyResult;\n  \"resources/unsubscribe\": EmptyResult;\n  \"prompts/list\": ListPromptsResult;\n  \"prompts/get\": GetPromptResult;\n  \"completion/complete\": CompleteResult;\n  \"logging/setLevel\": EmptyResult;\n  \"tasks/get\": GetTaskResult;\n  \"tasks/result\": GetTaskPayloadResult;\n  \"tasks/list\": ListTasksResult;\n  \"tasks/cancel\": CancelTaskResult;\n}\n\n/**\n * Map an MCP method string to its corresponding result type.\n * For request methods, resolves to the specific SDK result type.\n * For wildcard patterns (e.g. `\"tools/*\"`), resolves to the union of matching result types.\n * For notification methods, resolves to `undefined`.\n * For unknown/unmatched methods, falls back to `ServerResult`.\n */\nexport type McpResultFor<M extends string> = M extends keyof McpResultMap\n  ? McpResultMap[M]\n  : M extends `${infer Prefix}/*`\n    ? [McpResultMap[keyof McpResultMap & `${Prefix}/${string}`]] extends [never]\n      ? M extends ToWildcard<ClientNotification[\"method\"]>\n        ? undefined\n        : ServerResult\n      : McpResultMap[keyof McpResultMap & `${Prefix}/${string}`]\n    : M extends ClientNotification[\"method\"]\n      ? undefined\n      : ServerResult;\n\n/** Typed middleware fn for a specific method — narrows params, extra, and next() result. */\nexport type McpTypedMiddlewareFn<M extends string> = (\n  request: { method: M; params: McpRequestParams<M> },\n  extra: McpExtraFor<M>,\n  next: () => Promise<McpResultFor<M>>,\n) => Promise<unknown> | unknown;\n\n/** Extracts `\"prefix/*\"` from `\"prefix/anything\"` — distributive over unions. */\ntype ToWildcard<T extends string> = T extends `${infer Prefix}/${string}`\n  ? `${Prefix}/*`\n  : never;\n\n/** Wildcard prefixes derived from method strings (e.g. `\"tools/*\"` from `\"tools/call\"`). */\nexport type McpWildcard = ToWildcard<McpMethodString>;\n\n/** Category keywords matching all requests or all notifications. */\ntype McpCategory = \"request\" | \"notification\";\n\n/**\n * A single filter pattern for MCP middleware:\n * - Exact method: `\"tools/call\"`\n * - Wildcard: `\"tools/*\"`\n * - Category: `\"request\"` | `\"notification\"`\n * - Escape hatch: arbitrary string via `string & {}`\n */\ntype McpMiddlewareFilterPattern =\n  | McpMethodString\n  | McpWildcard\n  | McpCategory\n  | (string & {});\n\n/**\n * Filter determining which MCP methods a middleware applies to.\n * A single pattern or an array of patterns (OR logic).\n */\nexport type McpMiddlewareFilter =\n  | McpMiddlewareFilterPattern\n  | McpMiddlewareFilterPattern[];\n\n/**\n * Internal entry stored for each registered middleware.\n * `filter: null` means catch-all (matches everything).\n */\nexport type McpMiddlewareEntry = {\n  filter: McpMiddlewareFilter | null;\n  handler: McpMiddlewareFn;\n};\n\ntype HandlerMap = Map<string, (...args: unknown[]) => Promise<unknown>>;\n\n/**\n * Extract the TS-private `_requestHandlers` and `_notificationHandlers` maps\n * from the SDK's `Server` (extends `Protocol`). These are runtime-accessible\n * but declared `private` in TypeScript.\n *\n * Validates with `instanceof Map` so an incompatible SDK version fails fast\n * instead of silently breaking.\n */\nexport function getHandlerMaps(server: Server) {\n  const obj: object = server;\n\n  if (\n    !(\"_requestHandlers\" in obj && obj._requestHandlers instanceof Map) ||\n    !(\n      \"_notificationHandlers\" in obj && obj._notificationHandlers instanceof Map\n    )\n  ) {\n    throw new Error(\n      \"Incompatible MCP SDK version: expected _requestHandlers and _notificationHandlers on Server\",\n    );\n  }\n\n  return {\n    requestHandlers: obj._requestHandlers as HandlerMap,\n    notificationHandlers: obj._notificationHandlers as HandlerMap,\n  };\n}\n\n/**\n * Check if a single filter pattern matches a given method.\n *\n * - Exact: `\"tools/call\"` matches only `\"tools/call\"`\n * - Wildcard: `\"tools/*\"` matches any method starting with `\"tools/\"`\n * - Category `\"request\"`: matches when `isNotification` is false\n * - Category `\"notification\"`: matches when `isNotification` is true\n */\nexport function matchesFilter(\n  method: string,\n  filter: string,\n  isNotification: boolean,\n): boolean {\n  if (filter === \"request\") {\n    return !isNotification;\n  }\n  if (filter === \"notification\") {\n    return isNotification;\n  }\n  if (filter.endsWith(\"/*\")) {\n    const prefix = filter.slice(0, -1); // \"tools/*\" → \"tools/\"\n    return method.startsWith(prefix);\n  }\n  return method === filter;\n}\n\nfunction matchesAnyFilter(\n  method: string,\n  filter: McpMiddlewareFilter | null,\n  isNotification: boolean,\n): boolean {\n  if (filter === null) {\n    return true;\n  }\n  if (typeof filter === \"string\") {\n    return matchesFilter(method, filter, isNotification);\n  }\n  return filter.some((pattern) =>\n    matchesFilter(method, pattern, isNotification),\n  );\n}\n\n/**\n * Build an onion-model middleware chain for a specific method.\n *\n * Filters `entries` to those matching `method`, then composes them\n * so the first registered middleware is the outermost layer.\n * `next()` is guarded against multiple calls within a single middleware.\n */\nexport function buildMiddlewareChain(\n  method: string,\n  isNotification: boolean,\n  originalHandler: (...args: unknown[]) => Promise<unknown>,\n  entries: McpMiddlewareEntry[],\n) {\n  const applicable = entries.filter((entry) =>\n    matchesAnyFilter(method, entry.filter, isNotification),\n  );\n\n  if (applicable.length === 0) {\n    return originalHandler;\n  }\n\n  return (...args: unknown[]) => {\n    const rawRequest = args[0] as Record<string, unknown> | undefined;\n    // SDK calls request handlers as handler(request, extra) but\n    // notification handlers as handler(notification) — no extra arg.\n    const extra = isNotification ? undefined : (args[1] as McpExtra);\n    const mcpRequest = {\n      method,\n      params: (rawRequest?.params as Record<string, unknown>) ?? {},\n    };\n\n    let index = 0;\n\n    const executeLayer = (): Promise<unknown> => {\n      const entry = applicable[index++];\n      if (!entry) {\n        if (rawRequest) {\n          rawRequest.params = mcpRequest.params;\n        }\n        return originalHandler(...args);\n      }\n\n      let nextCalled = false;\n\n      const next = (): Promise<unknown> => {\n        if (nextCalled) {\n          throw new Error(\n            `next() called multiple times in middleware for \"${method}\"`,\n          );\n        }\n        nextCalled = true;\n        return executeLayer();\n      };\n\n      return Promise.resolve(entry.handler(mcpRequest, extra, next));\n    };\n\n    return executeLayer();\n  };\n}\n"]}
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/server/middleware.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Server } from \"@modelcontextprotocol/sdk/server/index.js\";\nimport type { RequestHandlerExtra } from \"@modelcontextprotocol/sdk/shared/protocol.js\";\nimport type {\n  CallToolResult,\n  CancelTaskResult,\n  ClientNotification,\n  ClientRequest,\n  CompleteResult,\n  EmptyResult,\n  GetPromptResult,\n  GetTaskPayloadResult,\n  GetTaskResult,\n  InitializeResult,\n  ListPromptsResult,\n  ListResourcesResult,\n  ListResourceTemplatesResult,\n  ListTasksResult,\n  ListToolsResult,\n  ReadResourceResult,\n  ServerNotification,\n  ServerRequest,\n  ServerResult,\n} from \"@modelcontextprotocol/sdk/types.js\";\n\n/**\n * The `extra` context object provided by the MCP SDK to request handlers.\n */\nexport type McpExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;\n\n/**\n * A single MCP middleware function following the onion model.\n * Call `next()` to invoke the next middleware or the final handler.\n * For notifications, `extra` is `undefined` (SDK does not provide extra context)\n * and `next()` resolves to `undefined`.\n */\nexport type McpMiddlewareFn = (\n  request: { method: string; params: Record<string, unknown> },\n  extra: McpExtra | undefined,\n  next: () => Promise<unknown>,\n) => Promise<unknown> | unknown;\n\n/**\n * MCP methods the server handles (incoming from client).\n */\nexport type McpMethodString =\n  | ClientRequest[\"method\"]\n  | ClientNotification[\"method\"];\n\n/**\n * Resolve the `params` type for a specific MCP method (request or notification)\n * from the SDK's typed unions. Falls back to `Record<string, unknown>` for\n * unknown methods. Used by {@link McpTypedMiddlewareFn} to narrow the request\n * shape in typed middleware.\n */\nexport type McpRequestParams<M extends string> =\n  Extract<ClientRequest, { method: M }> extends { params: infer P }\n    ? P\n    : Extract<ClientNotification, { method: M }> extends { params: infer P }\n      ? P\n      : Record<string, unknown>;\n\n/**\n * Resolve the `extra` arg type for a specific MCP method: {@link McpExtra} for\n * request methods, `undefined` for notification methods (the SDK does not\n * pass extra context for notifications).\n */\nexport type McpExtraFor<M extends string> = M extends ClientRequest[\"method\"]\n  ? McpExtra\n  : M extends ClientNotification[\"method\"]\n    ? undefined\n    : McpExtra | undefined;\n\n/** Maps each MCP request method to its SDK result type. */\ninterface McpResultMap {\n  ping: EmptyResult;\n  initialize: InitializeResult;\n  \"tools/list\": ListToolsResult;\n  \"tools/call\": CallToolResult;\n  \"resources/list\": ListResourcesResult;\n  \"resources/templates/list\": ListResourceTemplatesResult;\n  \"resources/read\": ReadResourceResult;\n  \"resources/subscribe\": EmptyResult;\n  \"resources/unsubscribe\": EmptyResult;\n  \"prompts/list\": ListPromptsResult;\n  \"prompts/get\": GetPromptResult;\n  \"completion/complete\": CompleteResult;\n  \"logging/setLevel\": EmptyResult;\n  \"tasks/get\": GetTaskResult;\n  \"tasks/result\": GetTaskPayloadResult;\n  \"tasks/list\": ListTasksResult;\n  \"tasks/cancel\": CancelTaskResult;\n}\n\n/**\n * Map an MCP method string to its corresponding result type.\n * For request methods, resolves to the specific SDK result type.\n * For wildcard patterns (e.g. `\"tools/*\"`), resolves to the union of matching result types.\n * For notification methods, resolves to `undefined`.\n * For unknown/unmatched methods, falls back to `ServerResult`.\n */\nexport type McpResultFor<M extends string> = M extends keyof McpResultMap\n  ? McpResultMap[M]\n  : M extends `${infer Prefix}/*`\n    ? [McpResultMap[keyof McpResultMap & `${Prefix}/${string}`]] extends [never]\n      ? M extends ToWildcard<ClientNotification[\"method\"]>\n        ? undefined\n        : ServerResult\n      : McpResultMap[keyof McpResultMap & `${Prefix}/${string}`]\n    : M extends ClientNotification[\"method\"]\n      ? undefined\n      : ServerResult;\n\n/**\n * Typed middleware function for a specific method. Narrows `request.params`\n * via {@link McpRequestParams}, `extra` via {@link McpExtraFor}, and the\n * resolved value of `next()` via {@link McpResultFor}.\n */\nexport type McpTypedMiddlewareFn<M extends string> = (\n  request: { method: M; params: McpRequestParams<M> },\n  extra: McpExtraFor<M>,\n  next: () => Promise<McpResultFor<M>>,\n) => Promise<unknown> | unknown;\n\n/** Extracts `\"prefix/*\"` from `\"prefix/anything\"` — distributive over unions. */\ntype ToWildcard<T extends string> = T extends `${infer Prefix}/${string}`\n  ? `${Prefix}/*`\n  : never;\n\n/** Wildcard prefixes derived from method strings (e.g. `\"tools/*\"` from `\"tools/call\"`). */\nexport type McpWildcard = ToWildcard<McpMethodString>;\n\n/** Category keywords matching all requests or all notifications. */\ntype McpCategory = \"request\" | \"notification\";\n\n/**\n * A single filter pattern for MCP middleware:\n * - Exact method: `\"tools/call\"`\n * - Wildcard: `\"tools/*\"`\n * - Category: `\"request\"` | `\"notification\"`\n * - Escape hatch: arbitrary string via `string & {}`\n */\ntype McpMiddlewareFilterPattern =\n  | McpMethodString\n  | McpWildcard\n  | McpCategory\n  | (string & {});\n\n/**\n * Filter determining which MCP methods a middleware applies to.\n * A single pattern or an array of patterns (OR logic).\n */\nexport type McpMiddlewareFilter =\n  | McpMiddlewareFilterPattern\n  | McpMiddlewareFilterPattern[];\n\n/**\n * Internal entry stored for each registered middleware.\n * `filter: null` means catch-all (matches everything).\n */\nexport type McpMiddlewareEntry = {\n  filter: McpMiddlewareFilter | null;\n  handler: McpMiddlewareFn;\n};\n\ntype HandlerMap = Map<string, (...args: unknown[]) => Promise<unknown>>;\n\n/**\n * Extract the TS-private `_requestHandlers` and `_notificationHandlers` maps\n * from the SDK's `Server` (extends `Protocol`). These are runtime-accessible\n * but declared `private` in TypeScript.\n *\n * Validates with `instanceof Map` so an incompatible SDK version fails fast\n * instead of silently breaking.\n */\nexport function getHandlerMaps(server: Server) {\n  const obj: object = server;\n\n  if (\n    !(\"_requestHandlers\" in obj && obj._requestHandlers instanceof Map) ||\n    !(\n      \"_notificationHandlers\" in obj && obj._notificationHandlers instanceof Map\n    )\n  ) {\n    throw new Error(\n      \"Incompatible MCP SDK version: expected _requestHandlers and _notificationHandlers on Server\",\n    );\n  }\n\n  return {\n    requestHandlers: obj._requestHandlers as HandlerMap,\n    notificationHandlers: obj._notificationHandlers as HandlerMap,\n  };\n}\n\n/**\n * Check if a single filter pattern matches a given method.\n *\n * - Exact: `\"tools/call\"` matches only `\"tools/call\"`\n * - Wildcard: `\"tools/*\"` matches any method starting with `\"tools/\"`\n * - Category `\"request\"`: matches when `isNotification` is false\n * - Category `\"notification\"`: matches when `isNotification` is true\n */\nexport function matchesFilter(\n  method: string,\n  filter: string,\n  isNotification: boolean,\n): boolean {\n  if (filter === \"request\") {\n    return !isNotification;\n  }\n  if (filter === \"notification\") {\n    return isNotification;\n  }\n  if (filter.endsWith(\"/*\")) {\n    const prefix = filter.slice(0, -1); // \"tools/*\" → \"tools/\"\n    return method.startsWith(prefix);\n  }\n  return method === filter;\n}\n\nfunction matchesAnyFilter(\n  method: string,\n  filter: McpMiddlewareFilter | null,\n  isNotification: boolean,\n): boolean {\n  if (filter === null) {\n    return true;\n  }\n  if (typeof filter === \"string\") {\n    return matchesFilter(method, filter, isNotification);\n  }\n  return filter.some((pattern) =>\n    matchesFilter(method, pattern, isNotification),\n  );\n}\n\n/**\n * Build an onion-model middleware chain for a specific method.\n *\n * Filters `entries` to those matching `method`, then composes them\n * so the first registered middleware is the outermost layer.\n * `next()` is guarded against multiple calls within a single middleware.\n */\nexport function buildMiddlewareChain(\n  method: string,\n  isNotification: boolean,\n  originalHandler: (...args: unknown[]) => Promise<unknown>,\n  entries: McpMiddlewareEntry[],\n) {\n  const applicable = entries.filter((entry) =>\n    matchesAnyFilter(method, entry.filter, isNotification),\n  );\n\n  if (applicable.length === 0) {\n    return originalHandler;\n  }\n\n  return (...args: unknown[]) => {\n    const rawRequest = args[0] as Record<string, unknown> | undefined;\n    // SDK calls request handlers as handler(request, extra) but\n    // notification handlers as handler(notification) — no extra arg.\n    const extra = isNotification ? undefined : (args[1] as McpExtra);\n    const mcpRequest = {\n      method,\n      params: (rawRequest?.params as Record<string, unknown>) ?? {},\n    };\n\n    let index = 0;\n\n    const executeLayer = (): Promise<unknown> => {\n      const entry = applicable[index++];\n      if (!entry) {\n        if (rawRequest) {\n          rawRequest.params = mcpRequest.params;\n        }\n        return originalHandler(...args);\n      }\n\n      let nextCalled = false;\n\n      const next = (): Promise<unknown> => {\n        if (nextCalled) {\n          throw new Error(\n            `next() called multiple times in middleware for \"${method}\"`,\n          );\n        }\n        nextCalled = true;\n        return executeLayer();\n      };\n\n      return Promise.resolve(entry.handler(mcpRequest, extra, next));\n    };\n\n    return executeLayer();\n  };\n}\n"]}

package/dist/server/server.d.ts

@@ -6,12 +6,25 @@ import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/proto
 import type { ContentBlock, Implementation, RequestMeta, ServerNotification, ServerRequest, ServerResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
 import { type ErrorRequestHandler, type Express, type RequestHandler } from "express";
 import type { McpExtra, McpExtraFor, McpMethodString, McpMiddlewareFilter, McpMiddlewareFn, McpResultFor, McpTypedMiddlewareFn, McpWildcard } from "./middleware.js";
+/**
+ * Type marker for a registered tool — carries its input, output, and response
+ * metadata shapes so views can infer types from `typeof server`.
+ *
+ * You normally never construct this by hand; it is produced by `registerTool`
+ * and consumed by helpers like {@link InferTools} and {@link generateHelpers}.
+ */
 export type ToolDef<TInput = unknown, TOutput = unknown, TResponseMetadata = unknown> = {
     input: TInput;
     output: TOutput;
     responseMetadata: TResponseMetadata;
 };
+/** Which host runtime a view targets — `"apps-sdk"` (ChatGPT) or `"mcp-app"` (MCP Apps spec). */
 export type ViewHostType = "apps-sdk" | "mcp-app";
+/**
+ * Content Security Policy origins attached to a view's resource. Each list is
+ * passed through to the host's CSP for the view iframe; omit a field to inherit
+ * the host's default for that directive.
+ */
 export interface ViewCsp {
     /** Origins for static assets (images, fonts, scripts, styles). */
     resourceDomains?: string[];
@@ -24,26 +37,67 @@ export interface ViewCsp {
     /** Origins allowed in `<base href>` tags (mcp-apps only). */
     baseUriDomains?: string[];
 }
+/**
+ * Registry of view component names. The Skybridge Vite plugin augments this
+ * interface in the generated `.skybridge/views.d.ts` with one key per view
+ * file, which narrows {@link ViewName} from `string` to the concrete union.
+ */
 export interface ViewNameRegistry {
 }
+/** Union of valid view component names. Narrowed by {@link ViewNameRegistry}. */
 export type ViewName = keyof ViewNameRegistry & string;
+/**
+ * Pass under `view` in a tool's `registerTool` config to render the tool's
+ * result through a Skybridge view instead of a plain text response.
+ */
 export interface ViewConfig {
+    /** Filename of the view module (without extension) — matches a file in your `viewsDir`. */
     component: ViewName;
+    /** Human-readable label the host may show alongside the view. */
     description?: string;
+    /** Restrict where the view is rendered. Defaults to all known hosts. */
     hosts?: ViewHostType[];
+    /** Apps SDK only: request a visible border around the widget. */
     prefersBorder?: boolean;
+    /** Apps SDK only: override the iframe's served domain (advanced). */
     domain?: string;
+    /** Per-view CSP overrides — see {@link ViewCsp}. */
     csp?: ViewCsp;
+    /** Free-form metadata forwarded on the view resource's `_meta`. */
     _meta?: Record<string, unknown>;
 }
+export type SecurityScheme = {
+    type: "noauth";
+} | {
+    type: "oauth2";
+    scopes?: string[];
+};
+/**
+ * Well-known keys recognized by host runtimes when set on a tool's `_meta`.
+ * Use {@link ToolMeta} to also pass arbitrary custom metadata alongside these.
+ *
+ * @see https://developers.openai.com/apps-sdk/reference#tool-descriptor-parameters
+ */
 export interface KnownToolMeta {
+    /** Apps SDK: allow the rendered view to call this tool from inside its iframe. */
     "openai/widgetAccessible"?: boolean;
+    /** Apps SDK: status text shown while the tool is running (e.g. `"Searching trips"`). */
     "openai/toolInvocation/invoking"?: string;
+    /** Apps SDK: status text shown once the tool returns (e.g. `"Found 3 trips"`). */
     "openai/toolInvocation/invoked"?: string;
+    /** Apps SDK: input parameters that hold file references — the host attaches uploaded files to them. */
     "openai/fileParams"?: string[];
+    /** MCP Apps: control whether the tool is exposed to the model, the app, or both. */
     ui?: Pick<McpUiToolMeta, "visibility">;
+    securitySchemes?: SecurityScheme[];
 }
+/** {@link KnownToolMeta} merged with arbitrary string-keyed metadata for custom flags. */
 export type ToolMeta = KnownToolMeta & Record<string, unknown>;
+/**
+ * Convenient return type for tool handlers — a plain string, a single
+ * {@link ContentBlock}, or an array. Skybridge normalizes it to the MCP
+ * `content: ContentBlock[]` shape before responding.
+ */
 export type HandlerContent = string | ContentBlock | ContentBlock[];
 /**
  * Type-level marker interface for cross-package type inference.
@@ -87,6 +141,14 @@ interface ToolConfig<TInput extends ZodRawShapeCompat | AnySchema> {
     outputSchema?: ZodRawShapeCompat | AnySchema;
     annotations?: ToolAnnotations;
     view?: ViewConfig;
+    /**
+     * Declares which auth schemes this tool supports (e.g. `noauth`, `oauth2`).
+     * Lets clients label tools that require sign-in before calling, and pass
+     * the right scopes through the OAuth flow. Listing both `noauth` and
+     * `oauth2` signals that the tool works for anonymous callers and gives
+     * enhanced behavior to authenticated ones.
+     */
+    securitySchemes?: SecurityScheme[];
     _meta?: ToolMeta;
 }
 /**
@@ -126,10 +188,45 @@ type ToolHandler<TInput extends ZodRawShapeCompat, TReturn extends {
 } = {
     content?: HandlerContent;
 }> = (args: ShapeOutput<TInput>, extra: ToolHandlerExtra) => TReturn | Promise<TReturn>;
+/**
+ * Coerce a tool handler's return value into an MCP `content` array. Strings
+ * become a single `TextContent`; a single block is wrapped in an array;
+ * `undefined` produces `[]`. Mostly used internally — exported so consumers
+ * who build content lazily can apply the same normalization.
+ */
 export declare function normalizeContent(content: HandlerContent | undefined): ContentBlock[];
 interface McpServerBaseOmitted extends Omit<McpServerBase, "registerTool" | "connect"> {
 }
 declare const McpServerBaseOmitted: new (...args: ConstructorParameters<typeof McpServerBase>) => McpServerBaseOmitted;
+/**
+ * The Skybridge server. Extends the MCP SDK's `McpServer` with a typed tool
+ * registry, view resources, an embedded Express app, and protocol-level
+ * middleware. Construct it with the same `Implementation` info you would pass
+ * to the SDK, chain {@link McpServer.registerTool} calls to declare tools,
+ * then call {@link McpServer.run} to start the HTTP server.
+ *
+ * The `TTools` generic accumulates each registered tool's input/output/meta
+ * shape, so `typeof server` carries enough information for view-side helpers
+ * like {@link generateHelpers} to produce fully-typed hooks.
+ *
+ * @typeParam TTools - Accumulated tool registry. Filled in by `registerTool`
+ * chaining; you almost never set this manually.
+ *
+ * @example
+ * ```ts
+ * const server = new McpServer({ name: "my-app", version: "1.0.0" }, {})
+ *   .registerTool({
+ *     name: "search",
+ *     inputSchema: { query: z.string() },
+ *     view: { component: "search" },
+ *   }, async ({ query }) => ({ content: `Results for ${query}` }));
+ *
+ * await server.run();
+ * export type AppType = typeof server;
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/mcp-server
+ */
 export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>> extends McpServerBaseOmitted {
     readonly $types: McpServerTypes<TTools>;
     /**
@@ -149,12 +246,34 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
     private mcpMiddlewareEntries;
     private mcpMiddlewareApplied;
     private claimedViews;
+    private viewMetaBuilders;
     private viteManifest;
     private readonly serverInfo;
     private readonly serverOptions?;
     constructor(serverInfo: Implementation, options?: ServerOptions);
+    /**
+     * Register Express middleware on the underlying app. Mirrors `app.use` —
+     * pass handlers directly or a path-prefixed handler list. Register before
+     * {@link McpServer.run}; ordering matches Express.
+     *
+     * Note: Alpic Cloud only routes traffic to `/mcp`. Custom paths work
+     * locally and on self-hosted deployments.
+     */
     use(...handlers: RequestHandler[]): this;
     use(path: string, ...handlers: RequestHandler[]): this;
+    /**
+     * Register Express error-handling middleware to run after the built-in
+     * `/mcp` route (or your custom route). Use this to log or transform errors
+     * thrown by tool handlers before the default error handler responds.
+     *
+     * @example
+     * ```ts
+     * server.useOnError((err, _req, _res, next) => {
+     *   logger.error(err);
+     *   next(err);
+     * });
+     * ```
+     */
     useOnError(...handlers: ErrorRequestHandler[]): this;
     useOnError(path: string, ...handlers: ErrorRequestHandler[]): this;
     /** Register MCP protocol-level middleware (catch-all). */
@@ -189,6 +308,14 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
      */
     mcpMiddleware(filter: McpMiddlewareFilter, handler: McpMiddlewareFn): this;
     private applyMcpMiddleware;
+    /**
+     * Connect to an MCP transport (override of the SDK's `connect`). Use this
+     * when you're embedding Skybridge in a host that already manages its own
+     * transport (e.g. stdio for desktop apps); for HTTP, prefer {@link McpServer.run}
+     * which sets the transport up for you. Locks in any middleware registered
+     * via {@link McpServer.mcpMiddleware} — further calls to that method will
+     * throw afterwards.
+     */
     connect(transport: Parameters<typeof McpServerBase.prototype.connect>[0]): Promise<void>;
     /**
      * Per-request stateless connect. The SDK's `Protocol` only allows one
@@ -201,10 +328,21 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
      * read side and fails fast on SDK field renames.
      */
     connectStatelessTransport(transport: Parameters<typeof McpServerBase.prototype.connect>[0]): Promise<void>;
+    /**
+     * Start the HTTP server. Listens on `process.env.__PORT` (default `3000`),
+     * mounts the `/mcp` route, applies any custom Express middleware registered
+     * via {@link McpServer.use} / {@link McpServer.useOnError}, and locks in
+     * any MCP middleware registered via {@link McpServer.mcpMiddleware}.
+     *
+     * On Cloudflare Workers / workerd, returns an object exposing `fetch` so
+     * the runtime can bridge incoming requests to the Node HTTP server. On
+     * Node, returns `undefined` once listening.
+     */
     run(): Promise<{
         fetch: (...args: unknown[]) => unknown;
     } | undefined>;
     private enforceOneToolPerView;
+    private resolveViewRequestContext;
     private registerViewResources;
     private registerViewResource;
     private wrapHandler;
@@ -221,6 +359,35 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
         file: string;
     }>): this;
     private readManifest;
+    /**
+     * Register a tool. Pass a `config` describing the tool (name, schemas,
+     * optional {@link ViewConfig}, optional {@link ToolMeta}) and a handler that
+     * returns the tool's result.
+     *
+     * Chain calls to build up a server: each call returns a new `McpServer`
+     * type that captures the tool's input/output/`_meta` shape so the
+     * resulting `typeof server` can drive {@link generateHelpers}.
+     *
+     * The handler's return shape determines the output types: the
+     * `structuredContent` field becomes the tool's typed output, and `_meta`
+     * becomes its `responseMetadata`. The `content` field is normalized through
+     * {@link normalizeContent}.
+     *
+     * @example
+     * ```ts
+     * server.registerTool({
+     *   name: "search",
+     *   inputSchema: { query: z.string() },
+     *   outputSchema: { results: z.array(z.string()) },
+     *   view: { component: "search" },
+     * }, async ({ query }) => ({
+     *   content: `Found results for ${query}`,
+     *   structuredContent: { results: [...] },
+     * }));
+     * ```
+     *
+     * @see https://docs.skybridge.tech/api-reference/register-tool
+     */
     registerTool<TName extends string, InputArgs extends ZodRawShapeCompat, TReturn extends {
         content?: HandlerContent;
     }>(config: ToolConfig<InputArgs> & {