skybridge 0.0.0-dev.815d058 → 0.0.0-dev.8164d23

package/dist/server/server.d.ts

@@ -1,12 +1,12 @@
 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 express, { type ErrorRequestHandler, type Express, type RequestHandler } from "express";
+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 ServerOptions, type StandardSchemaV1, type StandardSchemaWithJSON, type ToolAnnotations } from "@modelcontextprotocol/server";
+import type express from "express";
+import type { InferSchemaOutput, RawInputShape } from "../standard-schema.js";
 import type { OAuthConfig } from "./auth/index.js";
-import type { McpExtra, McpExtraFor, McpMethodString, McpMiddlewareFilter, McpMiddlewareFn, McpResultFor, McpTypedMiddlewareFn, McpWildcard } from "./middleware.js";
+import type { ResourceMetadataUrlResolver } from "./auth/setup.js";
+import type { ExtraClaims } from "./auth.js";
+import type { McpExtra, McpMiddlewareEntry } 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 +19,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 +49,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 +68,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 +83,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 options, part of the {@link SkybridgeConfig} bag passed to
+ * the `Skybridge` constructor.
+ *
+ * @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 +137,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 +162,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 +177,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 +207,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 +238,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 +255,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,26 +268,36 @@ 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;
+/**
+ * Typed registration sugar over the MCP SDK's `McpServer`: a tool registry
+ * that carries input/output/meta shapes, view resources, per-tool security
+ * schemes, and prompt/resource registration. A {@link Skybridge} app builds
+ * one of these per request and hands it to your setup factory; chain
+ * {@link McpServer.registerTool} calls on it and return the result.
+ *
+ * The `TTools` generic accumulates each registered tool's input/output/meta
+ * shape, so `typeof app` 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
+ * export const app = new Skybridge({ name: "my-app", version: "1.0.0" }, (server) =>
+ *   server.registerTool({
+ *     name: "search",
+ *     inputSchema: { query: z.string() },
+ *     view: { component: "search" },
+ *   }, async ({ query }) => ({ content: `Results for ${query}` })),
+ * );
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/mcp-server
+ */
+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
-     * custom routes, middleware, or settings — e.g.
-     * `server.express.get("/health", ...)`.
-     *
-     * `express.json()` is pre-applied — tune it via the constructor's third
-     * argument, e.g. `new McpServer(info, {}, { json: { limit: "10mb" } })`.
-     * Register your handlers before `run()`;
-     * after `run()`, dev-mode middleware, the `/mcp` route, and the default
-     * error handler are appended in that order.
-     *
-     * Note: Alpic Cloud only routes traffic to `/mcp` — custom routes work
-     * locally and on self-hosted deployments.
-     */
-    readonly express: Express;
-    private customErrorMiddleware;
-    private mcpMiddlewareEntries;
-    private mcpMiddlewareApplied;
     private claimedViews;
     private viewMetaBuilders;
     /**
@@ -251,106 +308,65 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
      */
     private viewUriByPath;
     private viteManifest;
-    private readonly serverInfo;
-    private readonly serverOptions?;
-    constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions);
+    private diskManifest;
+    private oauthEnabled;
+    private resolveResourceMetadataUrl?;
+    private readonly toolSecuritySchemes;
+    constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions<TAuthExtra>);
     /**
-     * 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.
+     * The per-tool security schemes collected during registration, keyed by tool
+     * name. Read by the OAuth layer to decide whether anonymous requests are
+     * allowed and which schemes gate a given `tools/call`.
      *
-     * Note: Alpic Cloud only routes traffic to `/mcp`. Custom paths work
-     * locally and on self-hosted deployments.
+     * @internal
      */
-    use(...handlers: RequestHandler[]): this;
-    use(path: string, ...handlers: RequestHandler[]): this;
+    get securitySchemesByTool(): ReadonlyMap<string, SecurityScheme[] | undefined>;
     /**
-     * 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.
+     * Inject the resolver the app uses to build the protected-resource metadata
+     * URL, so tool handlers can emit in-band auth challenges.
      *
-     * @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). */
-    mcpMiddleware(handler: McpMiddlewareFn): 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;
-    /** Register MCP protocol-level middleware for all notifications (`extra` is `undefined`). */
-    mcpMiddleware(filter: "notification", handler: (request: {
-        method: string;
-        params: Record<string, unknown>;
-    }, extra: undefined, next: () => Promise<undefined>) => Promise<unknown> | unknown): this;
-    /**
-     * Register MCP protocol-level middleware for an exact method.
-     * Narrows `params`, `extra`, and `next()` result based on the method string.
+     * @internal
      */
-    mcpMiddleware<M extends McpMethodString>(filter: M, handler: McpTypedMiddlewareFn<M>): this;
+    setResourceMetadataUrlResolver(resolve: ResourceMetadataUrlResolver): this;
     /**
-     * Register MCP protocol-level middleware for a wildcard pattern (e.g. `"tools/*"`).
-     * `next()` returns the union of result types for matching methods.
+     * Register a resource. Signature owned by Skybridge (not inherited) so a
+     * typed wrapper can land in a minor without a type-level break.
      */
-    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;
+    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 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.
+     * Register a prompt. Signature owned by Skybridge (not inherited) so a
+     * typed wrapper can land in a minor without a type-level break.
      */
-    mcpMiddleware(filter: McpMiddlewareFilter, handler: McpMiddlewareFn): this;
-    private applyMcpMiddleware;
+    registerPrompt<Args extends StandardSchemaWithJSON>(name: string, config: {
+        title?: string;
+        description?: string;
+        argsSchema?: Args;
+        icons?: Icon[];
+        _meta?: Record<string, unknown>;
+    }, cb: PromptCallback<Args>): RegisteredPrompt;
+    private applyInherited;
+    private skillRegistrar;
+    private setupSkills;
     /**
-     * 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
-     * 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.
-     */
-    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}.
+     * The framework's own protocol-level middleware for this instance: view
+     * `_meta` on `resources/list`, version-agnostic view resolution on
+     * `resources/read`, and the top-level `securitySchemes` mirror on
+     * `tools/list`. Composed by {@link Skybridge} around user middleware.
      *
-     * On Cloudflare Workers / workerd, returns an object exposing `fetch` so
-     * the runtime can bridge incoming requests to the Node HTTP server. On
-     * Vercel (`VERCEL === "1"`), returns the Express app directly so the
-     * serverless function entry can call it as a `(req, res)` handler. On
-     * Node, returns `undefined` once listening.
+     * @internal
      */
-    run(): Promise<{
-        fetch: (...args: unknown[]) => unknown;
-    } | Express | undefined>;
+    protocolMiddlewareEntries(): McpMiddlewareEntry[];
     private enforceOneToolPerView;
     private resolveViewRequestContext;
     private registerViewResources;
     private registerViewResource;
-    private wrapHandler;
+    private serveLegacyAppsSdkUrl;
+    private decorateToolHandler;
     private computeViewVersionParam;
     private lookupViewFile;
     private lookupDistFile;
@@ -393,11 +409,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 {};