skybridge 0.0.0-dev.81dc563 → 0.0.0-dev.81fd90a

package/dist/server/server.d.ts

@@ -1,12 +1,11 @@
 import type { McpUiToolMeta } from "@modelcontextprotocol/ext-apps";
-import { type ServerOptions } from "@modelcontextprotocol/sdk/server/index.js";
-import { McpServer as McpServerBase } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { AnySchema, SchemaOutput, ZodRawShapeCompat } from "@modelcontextprotocol/sdk/server/zod-compat.js";
-import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
-import type { ContentBlock, Implementation, RequestMeta, ServerNotification, ServerRequest, ServerResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+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";
 import express, { type ErrorRequestHandler, type Express, type RequestHandler } from "express";
+import type { InferSchemaOutput, RawInputShape } from "../standard-schema.js";
 import type { OAuthConfig } from "./auth/index.js";
+import type { ExtraClaims } from "./auth.js";
 import type { McpExtra, McpExtraFor, McpMethodString, McpMiddlewareFilter, McpMiddlewareFn, McpResultFor, McpTypedMiddlewareFn, McpWildcard } from "./middleware.js";
+import { type SkillsManifest } from "./skills.js";
 /**
  * Type marker for a registered tool — carries its input, output, and response
  * metadata shapes so views can infer types from `typeof server`.
@@ -19,8 +18,12 @@ export type ToolDef<TInput = unknown, TOutput = unknown, TResponseMetadata = unk
     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";
+/**
+ * The runtime a served view page declares on `window.skybridge`. Every view
+ * emits a single ext-apps resource, so this is always `"mcp-app"`; the Apps
+ * SDK runtime is detected at load time via `window.openai` instead.
+ */
+export type ViewHostType = "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
@@ -45,8 +48,16 @@ export interface ViewCsp {
  */
 export interface ViewNameRegistry {
 }
+/**
+ * Resolve view component names from a registry: the union of its keys, or
+ * `string` when the registry is empty. The empty case happens before
+ * `.skybridge/views.d.ts` is generated; falling back to `string` keeps valid
+ * view names from erroring on a fresh checkout, and narrowing kicks in once
+ * the generated file augments the registry.
+ */
+export type ViewNameFor<Registry> = [keyof Registry & string] extends [never] ? string : keyof Registry & string;
 /** Union of valid view component names. Narrowed by {@link ViewNameRegistry}. */
-export type ViewName = keyof ViewNameRegistry & string;
+export type ViewName = ViewNameFor<ViewNameRegistry>;
 /**
  * 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.
@@ -56,11 +67,9 @@ export interface ViewConfig {
     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. */
+    /** Request a visible border around the view (forwarded as `ui.prefersBorder`). */
     prefersBorder?: boolean;
-    /** Apps SDK only: override the iframe's served domain (advanced). */
+    /** Override the iframe's served domain (advanced; forwarded as `ui.domain`). */
     domain?: string;
     /** Per-view CSP overrides — see {@link ViewCsp}. */
     csp?: ViewCsp;
@@ -73,17 +82,42 @@ export type SecurityScheme = {
     type: "oauth2";
     scopes?: string[];
 };
+/**
+ * Declarative per-tool auth. Enforced when the server has an `oauth` provider:
+ * anonymous or under-scoped calls are rejected before the handler runs. Omit
+ * `auth` entirely for the secure default (sign-in required, no specific scope).
+ */
+export type ToolAuth = {
+    /**
+     * When `true`, the tool is callable signed out; the token is still used when
+     * one is present. Omit (or `false`) to require sign-in.
+     */
+    allowsAnonymous?: boolean;
+    /** OAuth scopes the caller's token must carry to invoke the tool. */
+    scopes?: string[];
+};
 /**
  * Options forwarded to the built-in `express.json()` body parser. Derived
  * from Express's own types so the public API doesn't depend on `body-parser`.
  */
 export type JsonOptions = NonNullable<Parameters<typeof express.json>[0]>;
-/** Skybridge-specific server options, passed as the third `McpServer` constructor argument. */
-export interface SkybridgeServerOptions {
+/**
+ * Skybridge-specific server options, passed as the third `McpServer` constructor
+ * argument.
+ *
+ * @typeParam TAuthExtra - Claims the `oauth` verifier populates. Inferred from
+ * the config a provider returns, and carried on to tool handlers.
+ */
+export interface SkybridgeServerOptions<TAuthExtra extends ExtraClaims = ExtraClaims> {
     /** Options for the built-in `express.json()` middleware, e.g. `{ limit: "10mb" }`. */
     json?: JsonOptions;
     /** Resource-server OAuth config. When set, mounts well-known metadata and bearer auth on `/mcp`. */
-    oauth?: OAuthConfig;
+    oauth?: OAuthConfig<TAuthExtra>;
+    /**
+     * @experimental Serve Agent Skills from `src/skills` over MCP (SEP-2640).
+     * API may change.
+     */
+    skills?: boolean;
 }
 /**
  * Well-known keys recognized by host runtimes when set on a tool's `_meta`.
@@ -102,7 +136,6 @@ export interface KnownToolMeta {
     "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>;
@@ -128,10 +161,10 @@ export interface McpServerTypes<TTools extends Record<string, ToolDef>> {
 type Simplify<T> = {
     [K in keyof T]: T[K];
 };
-type ShapeOutput<Shape extends ZodRawShapeCompat> = Simplify<{
-    [K in keyof Shape as undefined extends SchemaOutput<Shape[K]> ? never : K]: SchemaOutput<Shape[K]>;
+type ShapeOutput<Shape extends RawInputShape> = Simplify<{
+    [K in keyof Shape as undefined extends InferSchemaOutput<Shape[K]> ? never : K]: InferSchemaOutput<Shape[K]>;
 } & {
-    [K in keyof Shape as undefined extends SchemaOutput<Shape[K]> ? K : never]?: SchemaOutput<Shape[K]>;
+    [K in keyof Shape as undefined extends InferSchemaOutput<Shape[K]> ? K : never]?: InferSchemaOutput<Shape[K]>;
 }>;
 type ExtractStructuredContent<T> = T extends {
     structuredContent: infer SC;
@@ -143,17 +176,28 @@ type ExtractMeta<T> = [Extract<T, {
 }> extends {
     _meta: infer M;
 } ? Simplify<M> : unknown;
-type AddTool<TTools, TName extends string, TInput extends ZodRawShapeCompat, TOutput, TResponseMetadata = unknown> = McpServer<TTools & {
+type AddTool<TTools, TName extends string, TInput extends RawInputShape, TOutput, TResponseMetadata = unknown, TAuthExtra extends ExtraClaims = ExtraClaims> = McpServer<TTools & {
     [K in TName]: ToolDef<ShapeOutput<TInput>, TOutput, TResponseMetadata>;
-}>;
-interface ToolConfig<TInput extends ZodRawShapeCompat | AnySchema> {
+}, TAuthExtra>;
+interface ToolConfigBase<TInput extends RawInputShape | StandardSchemaV1> {
     name: string;
     title?: string;
     description?: string;
     inputSchema?: TInput;
-    outputSchema?: ZodRawShapeCompat | AnySchema;
+    outputSchema?: RawInputShape | StandardSchemaV1;
     annotations?: ToolAnnotations;
     view?: ViewConfig;
+    _meta?: ToolMeta;
+}
+/**
+ * The auth face of a tool config: either the high-level `auth` shorthand or the
+ * low-level `securitySchemes` escape hatch, never both.
+ */
+type ToolAuthConfig = {
+    auth?: ToolAuth;
+    securitySchemes?: never;
+} | {
+    auth?: never;
     /**
      * Declares which auth schemes this tool supports (e.g. `noauth`, `oauth2`).
      * Lets clients label tools that require sign-in before calling, and pass
@@ -162,8 +206,8 @@ interface ToolConfig<TInput extends ZodRawShapeCompat | AnySchema> {
      * enhanced behavior to authenticated ones.
      */
     securitySchemes?: SecurityScheme[];
-    _meta?: ToolMeta;
-}
+};
+type ToolConfig<TInput extends RawInputShape | StandardSchemaV1> = ToolConfigBase<TInput> & ToolAuthConfig;
 /**
  * Optional client-supplied hints attached to `params._meta` on every tool call
  * by the Apps SDK host. Hints only: never use for authorization, and tolerate
@@ -193,14 +237,16 @@ export interface ClientHintsMeta {
     /** Stable id for the currently mounted widget instance. */
     "openai/widgetSessionId"?: string;
 }
-type ToolHandlerExtra = Omit<RequestHandlerExtra<ServerRequest, ServerNotification>, "_meta"> & {
-    _meta?: RequestMeta & ClientHintsMeta;
+type ToolHandlerExtra<TAuthExtra extends ExtraClaims = ExtraClaims> = Omit<McpExtra<TAuthExtra>, "mcpReq"> & {
+    mcpReq: Omit<McpExtra<TAuthExtra>["mcpReq"], "_meta"> & {
+        _meta?: RequestMeta & ClientHintsMeta;
+    };
 };
-type ToolHandler<TInput extends ZodRawShapeCompat, TReturn extends {
+type ToolHandler<TInput extends RawInputShape, TReturn extends {
     content?: HandlerContent;
 } = {
     content?: HandlerContent;
-}> = (args: ShapeOutput<TInput>, extra: ToolHandlerExtra) => TReturn | Promise<TReturn>;
+}, TAuthExtra extends ExtraClaims = ExtraClaims> = (args: ShapeOutput<TInput>, extra: ToolHandlerExtra<TAuthExtra>) => 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;
@@ -208,7 +254,7 @@ type ToolHandler<TInput extends ZodRawShapeCompat, TReturn extends {
  * who build content lazily can apply the same normalization.
  */
 export declare function normalizeContent(content: HandlerContent | undefined): ContentBlock[];
-interface McpServerBaseOmitted extends Omit<McpServerBase, "registerTool" | "connect"> {
+interface McpServerBaseOmitted extends Omit<McpServerBase, "registerTool" | "registerResource" | "registerPrompt" | "connect"> {
 }
 declare const McpServerBaseOmitted: new (...args: ConstructorParameters<typeof McpServerBase>) => McpServerBaseOmitted;
 /**
@@ -221,7 +267,8 @@ declare const McpServerBaseOmitted: new (...args: ConstructorParameters<typeof M
 export declare function __setBuildManifest(manifest: Record<string, {
     file: string;
 }>): void;
-export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>> extends McpServerBaseOmitted {
+export declare function __setSkillsManifest(manifest: SkillsManifest): void;
+export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>, TAuthExtra extends ExtraClaims = ExtraClaims> extends McpServerBaseOmitted {
     readonly $types: McpServerTypes<TTools>;
     /**
      * The underlying Express app. Use this to extend the HTTP server with
@@ -241,6 +288,8 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
     private customErrorMiddleware;
     private mcpMiddlewareEntries;
     private mcpMiddlewareApplied;
+    private middlewareEntriesCache;
+    private readonly registrations;
     private claimedViews;
     private viewMetaBuilders;
     /**
@@ -253,7 +302,36 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
     private viteManifest;
     private readonly serverInfo;
     private readonly serverOptions?;
-    constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions);
+    private oauthEnabled;
+    private resolveResourceMetadataUrl?;
+    private securitySchemesByTool;
+    constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions<TAuthExtra>);
+    /**
+     * Register a resource, recorded so every per-request instance carries it.
+     * Signature owned by Skybridge (not inherited) so a typed wrapper can land
+     * in a minor without a type-level break.
+     */
+    registerResource(name: string, uri: string, config: ResourceMetadata & {
+        cacheHint?: CacheHint;
+    }, readCallback: ReadResourceCallback): RegisteredResource;
+    registerResource(name: string, template: ResourceTemplate, config: ResourceMetadata & {
+        cacheHint?: CacheHint;
+    }, readCallback: ReadResourceTemplateCallback): RegisteredResourceTemplate;
+    /**
+     * Register a prompt, recorded so every per-request instance carries it.
+     * Signature owned by Skybridge (not inherited) so a typed wrapper can land
+     * in a minor without a type-level break.
+     */
+    registerPrompt<Args extends StandardSchemaWithJSON>(name: string, config: {
+        title?: string;
+        description?: string;
+        argsSchema?: Args;
+        icons?: Icon[];
+        _meta?: Record<string, unknown>;
+    }, cb: PromptCallback<Args>): RegisteredPrompt;
+    private recordInherited;
+    private skillRegistrar;
+    private setupSkills;
     /**
      * Register Express middleware on the underlying app. Mirrors `app.use` —
      * pass handlers directly or a path-prefixed handler list. Register before
@@ -280,12 +358,12 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
     useOnError(...handlers: ErrorRequestHandler[]): this;
     useOnError(path: string, ...handlers: ErrorRequestHandler[]): this;
     /** Register MCP protocol-level middleware (catch-all). */
-    mcpMiddleware(handler: McpMiddlewareFn): this;
+    mcpMiddleware(handler: McpMiddlewareFn<TAuthExtra>): this;
     /** Register MCP protocol-level middleware for all requests (`extra` is `McpExtra`). */
     mcpMiddleware(filter: "request", handler: (request: {
         method: string;
         params: Record<string, unknown>;
-    }, extra: McpExtra, next: () => Promise<ServerResult>) => Promise<unknown> | unknown): this;
+    }, extra: McpExtra<TAuthExtra>, next: () => Promise<ServerResult>) => Promise<unknown> | unknown): this;
     /** Register MCP protocol-level middleware for all notifications (`extra` is `undefined`). */
     mcpMiddleware(filter: "notification", handler: (request: {
         method: string;
@@ -295,7 +373,7 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
      * Register MCP protocol-level middleware for an exact method.
      * Narrows `params`, `extra`, and `next()` result based on the method string.
      */
-    mcpMiddleware<M extends McpMethodString>(filter: M, handler: McpTypedMiddlewareFn<M>): this;
+    mcpMiddleware<M extends McpMethodString>(filter: M, handler: McpTypedMiddlewareFn<M, TAuthExtra>): this;
     /**
      * Register MCP protocol-level middleware for a wildcard pattern (e.g. `"tools/*"`).
      * `next()` returns the union of result types for matching methods.
@@ -303,14 +381,15 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
     mcpMiddleware<W extends McpWildcard>(filter: W, handler: (request: {
         method: string;
         params: Record<string, unknown>;
-    }, extra: McpExtraFor<W>, next: () => Promise<McpResultFor<W>>) => Promise<unknown> | unknown): this;
+    }, extra: McpExtraFor<W, TAuthExtra>, next: () => Promise<McpResultFor<W>>) => Promise<unknown> | unknown): this;
     /**
      * Register MCP protocol-level middleware with a method filter.
      * Filter can be an exact method (`"tools/call"`), wildcard (`"tools/*"`),
      * category (`"request"` | `"notification"`), or an array of those.
      */
-    mcpMiddleware(filter: McpMiddlewareFilter, handler: McpMiddlewareFn): this;
+    mcpMiddleware(filter: McpMiddlewareFilter, handler: McpMiddlewareFn<TAuthExtra>): this;
     private applyMcpMiddleware;
+    private instrumentHandlers;
     /**
      * 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
@@ -321,16 +400,22 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
      */
     connect(transport: Parameters<typeof McpServerBase.prototype.connect>[0]): Promise<void>;
     /**
-     * Per-request stateless connect. The SDK's `Protocol` only allows one
-     * transport per instance, so we can't reuse this `McpServer` across
-     * concurrent requests. The SDK's idiomatic fix is a `() => McpServer`
-     * factory, but that would break Skybridge's singleton API — so instead
-     * we build a fresh underlying `Server` per request and share the main
-     * server's handler maps by reference. The cast is unavoidable: there's
-     * no public API to inject handler maps. `getHandlerMaps` validates the
-     * read side and fails fast on SDK field renames.
+     * Build a fresh server for one stateless HTTP request, as
+     * `createMcpHandler`'s factory contract requires: every registration is
+     * replayed onto the new instance so the SDK's handler closures belong to
+     * the instance whose protocol era it stamps. Sharing the singleton's
+     * handler maps instead would bind them to an instance that is never
+     * marked, pinning every request to the 2025 codec and letting concurrent
+     * callers overwrite each other's negotiated version.
+     */
+    createStatelessServerInstance(): SdkServer;
+    /**
+     * Apply an SDK registration to the singleton and remember it, so each
+     * per-request instance can be built with the same surface.
      */
-    connectStatelessTransport(transport: Parameters<typeof McpServerBase.prototype.connect>[0]): Promise<void>;
+    private record;
+    /** Records a raw request handler (used for methods the SDK has no sugar for). */
+    private recordRequestHandler;
     /**
      * Start the HTTP server. Listens on `process.env.__PORT` (default `3000`),
      * mounts the `/mcp` route, applies any custom Express middleware registered
@@ -350,7 +435,8 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
     private resolveViewRequestContext;
     private registerViewResources;
     private registerViewResource;
-    private wrapHandler;
+    private serveLegacyAppsSdkUrl;
+    private decorateToolHandler;
     private computeViewVersionParam;
     private lookupViewFile;
     private lookupDistFile;
@@ -393,11 +479,13 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
      *
      * @see https://docs.skybridge.tech/api-reference/register-tool
      */
-    registerTool<TName extends string, InputArgs extends ZodRawShapeCompat, TReturn extends {
+    registerTool<TName extends string, InputArgs extends RawInputShape, TReturn extends {
         content?: HandlerContent;
     }>(config: ToolConfig<InputArgs> & {
         name: TName;
-    }, cb: ToolHandler<InputArgs, TReturn>): AddTool<TTools, TName, InputArgs, ExtractStructuredContent<TReturn>, ExtractMeta<TReturn>>;
-    registerTool<InputArgs extends ZodRawShapeCompat>(config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs>): this;
+    }, cb: ToolHandler<InputArgs, TReturn, TAuthExtra>): AddTool<TTools, TName, InputArgs, ExtractStructuredContent<TReturn>, ExtractMeta<TReturn>, TAuthExtra>;
+    registerTool<InputArgs extends RawInputShape>(config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs, {
+        content?: HandlerContent;
+    }, TAuthExtra>): this;
 }
 export {};