skybridge 0.0.0-dev.99a8152 → 0.0.0-dev.99c619a

package/dist/server/server.d.ts

@@ -1,12 +1,9 @@
 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 { OAuthConfig } from "./auth/index.js";
-import type { McpExtra, McpExtraFor, McpMethodString, McpMiddlewareFilter, McpMiddlewareFn, McpResultFor, McpTypedMiddlewareFn, McpWildcard } from "./middleware.js";
+import { type ContentBlock, type Icon, type Implementation, McpServer as McpServerBase, type RequestMeta, type ServerOptions, type ServerResult, type StandardSchemaV1, type StandardSchemaWithJSON, type ToolAnnotations } from "@modelcontextprotocol/server";
+import type express from "express";
+import type { ResourceMetadataUrlResolver } from "./auth/setup.js";
+import type { ExtraClaims } from "./auth.js";
+import type { McpExtra, McpExtraFor, McpMethodString, McpMiddlewareEntry, 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
@@ -20,12 +17,6 @@ export type ToolDef<TInput = unknown, TOutput = unknown, TResponseMetadata = unk
     output: TOutput;
     responseMetadata: TResponseMetadata;
 };
-/**
- * @deprecated Views now always emit a single ext-apps resource; host targeting
- * no longer applies. Retained for backwards compatibility; will be removed in a
- * future major.
- */
-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
@@ -69,11 +60,6 @@ export interface ViewConfig {
     component: ViewName;
     /** Human-readable label the host may show alongside the view. */
     description?: string;
-    /**
-     * @deprecated No-op. Every view emits a single ext-apps resource regardless
-     * of this value. Will be removed in a future major.
-     */
-    hosts?: ViewHostType[];
     /** Request a visible border around the view (forwarded as `ui.prefersBorder`). */
     prefersBorder?: boolean;
     /** Override the iframe's served domain (advanced; forwarded as `ui.domain`). */
@@ -89,6 +75,65 @@ export type SecurityScheme = {
     type: "oauth2";
     scopes?: string[];
 };
+/** A display mode ChatGPT can render a view in. ChatGPT doesn't support `pip`. */
+export type OpenAIDisplayMode = "inline" | "fullscreen";
+/** A sidebar shortcut that calls another tool of the same server. */
+export interface OpenAIQuickAction {
+    title: string;
+    icons: [Icon, ...Icon[]];
+    target: {
+        type: "tool";
+        name: string;
+        arguments?: Record<string, unknown>;
+    };
+}
+/**
+ * A place in ChatGPT where users can open the tool's view without the model.
+ *
+ * - `global`: an entry in the sidebar, opened fullscreen.
+ * - `thread`: a tab in a conversation's side panel.
+ * - `file`: a viewer for files with these extensions, such as `".stl"`.
+ *   ChatGPT calls the tool with `{ file: { name, resourceUri } }`.
+ * - `settings`: an entry in the plugin settings.
+ *
+ * ChatGPT calls the tool with `{}` for global and thread entrypoints, so the
+ * tool must not require any input.
+ */
+export type OpenAIEntrypoint = {
+    type: "global";
+    quickAction?: OpenAIQuickAction;
+} | {
+    type: "thread";
+} | {
+    type: "file";
+    extensions: string[];
+} | {
+    type: "settings";
+    searchTerms?: string[];
+};
+/**
+ * ChatGPT-only tool options, emitted as `_meta["openai/ui"]` on the tool and
+ * on its view resource. Every field is optional: ChatGPT applies the defaults
+ * of the OpenAI MCP extensions spec when one is omitted. Requires `view`.
+ *
+ * @see https://github.com/openai/mcp-extensions/blob/main/docs/spec.md
+ */
+export interface OpenAIToolConfig {
+    /** Places where users can open the view directly. */
+    entrypoints?: OpenAIEntrypoint[];
+    /**
+     * Display modes the view supports, read before the view loads. Defaults to
+     * `[preferredDisplayMode]` when that is set, otherwise to both modes.
+     */
+    availableDisplayModes?: OpenAIDisplayMode[];
+    /**
+     * Display mode the view prefers to open in. Setting it alone makes it the
+     * only available mode, so also set `availableDisplayModes` to keep the other.
+     */
+    preferredDisplayMode?: OpenAIDisplayMode;
+    /** Display mode the view opens in first when the model calls the tool. */
+    preferredModelDisplayMode?: OpenAIDisplayMode;
+}
 /**
  * Declarative per-tool auth. Enforced when the server has an `oauth` provider:
  * anonymous or under-scoped calls are rejected before the handler runs. Omit
@@ -108,12 +153,14 @@ export type ToolAuth = {
  * 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. */
+/**
+ * The Skybridge-specific options an {@link McpServer} is built with. A
+ * {@link Skybridge} app derives them from its config; pass them directly only
+ * when constructing an `McpServer` by hand.
+ */
 export interface SkybridgeServerOptions {
-    /** 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;
+    /** Whether an OAuth provider guards `/mcp`; enables per-tool scheme enforcement. */
+    oauth?: boolean;
     /**
      * @experimental Serve Agent Skills from `src/skills` over MCP (SEP-2640).
      * API may change.
@@ -137,7 +184,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>;
@@ -163,10 +209,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 Record<string, StandardSchemaWithJSON>> = Simplify<{
+    [K in keyof Shape as undefined extends StandardSchemaV1.InferOutput<Shape[K]> ? never : K]: StandardSchemaV1.InferOutput<Shape[K]>;
 } & {
-    [K in keyof Shape as undefined extends SchemaOutput<Shape[K]> ? K : never]?: SchemaOutput<Shape[K]>;
+    [K in keyof Shape as undefined extends StandardSchemaV1.InferOutput<Shape[K]> ? K : never]?: StandardSchemaV1.InferOutput<Shape[K]>;
 }>;
 type ExtractStructuredContent<T> = T extends {
     structuredContent: infer SC;
@@ -178,17 +224,25 @@ 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 Record<string, StandardSchemaWithJSON>, TOutput, TResponseMetadata = unknown, TAuthExtra extends ExtraClaims = ExtraClaims> = McpServer<TTools & {
     [K in TName]: ToolDef<ShapeOutput<TInput>, TOutput, TResponseMetadata>;
-}>;
-interface ToolConfigBase<TInput extends ZodRawShapeCompat | AnySchema> {
+}, TAuthExtra>;
+interface ToolConfigBase<TInput extends Record<string, StandardSchemaWithJSON> | StandardSchemaWithJSON> {
     name: string;
     title?: string;
     description?: string;
     inputSchema?: TInput;
-    outputSchema?: ZodRawShapeCompat | AnySchema;
+    outputSchema?: Record<string, StandardSchemaWithJSON> | StandardSchemaWithJSON;
     annotations?: ToolAnnotations;
+    /**
+     * Icons for the tool, a standard MCP field. Hosts choose whether and where
+     * to show them. ChatGPT asks for them on every entrypoint tool, as a
+     * monochrome SVG on a 20x20 viewport that uses `currentColor`.
+     */
+    icons?: Icon[];
     view?: ViewConfig;
+    /** ChatGPT-only options. See {@link OpenAIToolConfig}. */
+    openai?: OpenAIToolConfig;
     _meta?: ToolMeta;
 }
 /**
@@ -209,7 +263,7 @@ type ToolAuthConfig = {
      */
     securitySchemes?: SecurityScheme[];
 };
-type ToolConfig<TInput extends ZodRawShapeCompat | AnySchema> = ToolConfigBase<TInput> & ToolAuthConfig;
+type ToolConfig<TInput extends Record<string, StandardSchemaWithJSON> | StandardSchemaWithJSON> = 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
@@ -238,15 +292,26 @@ export interface ClientHintsMeta {
     "openai/organization"?: string;
     /** Stable id for the currently mounted widget instance. */
     "openai/widgetSessionId"?: string;
+    /**
+     * Set by ChatGPT desktop on tool calls from a view opened through a file
+     * entrypoint. `path` is the absolute path of the opened file. Any MCP client
+     * can send this key: never use it for authorization, and resolve the path
+     * and keep it inside an allowed directory before touching the filesystem.
+     */
+    "openai/resource"?: {
+        path?: 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 Record<string, StandardSchemaWithJSON>, 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;
@@ -268,26 +333,38 @@ export declare function __setBuildManifest(manifest: Record<string, {
     file: string;
 }>): void;
 export declare function __setSkillsManifest(manifest: SkillsManifest): void;
-export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>> extends McpServerBaseOmitted {
+/**
+ * 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 `handler`; 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",
+ *   handler: (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;
     /**
@@ -298,45 +375,34 @@ export declare class McpServer<TTools extends Record<string, ToolDef> = Record<n
      */
     private viewUriByPath;
     private viteManifest;
-    private readonly serverInfo;
-    private readonly serverOptions?;
     private oauthEnabled;
     private resolveResourceMetadataUrl?;
-    private securitySchemesByTool;
+    private readonly toolSecuritySchemes;
+    private readonly userMiddlewareEntries;
     constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions);
-    private setupSkills;
     /**
-     * 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);
-     * });
-     * ```
+     * @internal
      */
-    useOnError(...handlers: ErrorRequestHandler[]): this;
-    useOnError(path: string, ...handlers: ErrorRequestHandler[]): this;
+    setResourceMetadataUrlResolver(resolve: ResourceMetadataUrlResolver): this;
+    private setupSkills;
     /** 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;
@@ -346,7 +412,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.
@@ -354,49 +420,22 @@ 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;
-    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>;
+    mcpMiddleware(filter: McpMiddlewareFilter, handler: McpMiddlewareFn<TAuthExtra>): this;
     /**
-     * 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}.
+     * This instance's protocol-level middleware: the framework's own entries
+     * (view `_meta` on `resources/list`, version-agnostic view resolution on
+     * `resources/read`, the top-level `securitySchemes` mirror on `tools/list`)
+     * followed by the ones 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
-     * 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;
@@ -445,11 +484,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 Record<string, StandardSchemaWithJSON>, 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 Record<string, StandardSchemaWithJSON>>(config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs, {
+        content?: HandlerContent;
+    }, TAuthExtra>): this;
 }
 export {};