skybridge 0.0.0-dev.e1b8fe1 → 0.0.0-dev.e1ca873

package/dist/server/server.d.ts

@@ -0,0 +1,495 @@
+import type { McpUiToolMeta } from "@modelcontextprotocol/ext-apps";
+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
+ * 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;
+};
+/**
+ * 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[];
+    /** Origins the view may contact via fetch/XHR. */
+    connectDomains?: string[];
+    /** Origins allowed for iframe embeds (opts into stricter app review). */
+    frameDomains?: string[];
+    /** Origins that can receive openExternal redirects without the safe-link modal. */
+    redirectDomains?: string[];
+    /** 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 {
+}
+/**
+ * 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 = 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.
+ */
+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;
+    /** Request a visible border around the view (forwarded as `ui.prefersBorder`). */
+    prefersBorder?: boolean;
+    /** Override the iframe's served domain (advanced; forwarded as `ui.domain`). */
+    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[];
+};
+/** 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[];
+    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"`.
+ * - `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
+ * `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]>;
+/**
+ * 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 {
+    /** 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.
+     */
+    skills?: boolean;
+}
+/**
+ * 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">;
+}
+/** {@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.
+ *
+ * Consumers infer tool types via the structural `$types` property rather than
+ * the `McpServer` class generic, because class-generic inference breaks when
+ * `McpServer` comes from different package installations (e.g. a consumer
+ * with its own `skybridge` dep vs. the in-tree workspace version).
+ *
+ * Inspired by tRPC's `_def` pattern and Hono's type markers.
+ */
+export interface McpServerTypes<TTools extends Record<string, ToolDef>> {
+    readonly tools: TTools;
+}
+type Simplify<T> = {
+    [K in keyof T]: T[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 StandardSchemaV1.InferOutput<Shape[K]> ? K : never]?: StandardSchemaV1.InferOutput<Shape[K]>;
+}>;
+type ExtractStructuredContent<T> = T extends {
+    structuredContent: infer SC;
+} ? Simplify<SC> : never;
+type ExtractMeta<T> = [Extract<T, {
+    _meta: unknown;
+}>] extends [never] ? unknown : Extract<T, {
+    _meta: unknown;
+}> extends {
+    _meta: infer M;
+} ? Simplify<M> : unknown;
+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>;
+}, TAuthExtra>;
+interface ToolConfigBase<TInput extends Record<string, StandardSchemaWithJSON> | StandardSchemaWithJSON> {
+    name: string;
+    title?: string;
+    description?: string;
+    inputSchema?: TInput;
+    outputSchema?: Record<string, StandardSchemaWithJSON> | StandardSchemaWithJSON;
+    annotations?: ToolAnnotations;
+    /**
+     * Icons for the tool. The server's `icons` already cover every entrypoint,
+     * so set these only to tell several entrypoints apart. ChatGPT expects a
+     * monochrome SVG on a 20x20 viewport that uses `currentColor`.
+     */
+    icons?: Icon[];
+    view?: ViewConfig;
+    /** ChatGPT-only options. See {@link OpenAIToolConfig}. */
+    openai?: OpenAIToolConfig;
+    _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
+     * 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[];
+};
+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
+ * absence.
+ * @see https://developers.openai.com/apps-sdk/reference#_meta-fields-the-client-provides
+ */
+export interface ClientHintsMeta {
+    /** Requested locale (BCP-47, e.g. `"en-US"`). */
+    "openai/locale"?: string;
+    /** Browser user-agent */
+    "openai/userAgent"?: string;
+    /** Coarse user location. May be partially populated. */
+    "openai/userLocation"?: {
+        city?: string;
+        region?: string;
+        country?: string;
+        timezone?: string;
+        longitude?: number;
+        latitude?: number;
+    };
+    /** Anonymized user id. */
+    "openai/subject"?: string;
+    /** Anonymized conversation id, stable within a ChatGPT session. */
+    "openai/session"?: string;
+    /** Anonymized organization id, when the user account is part of an organization. */
+    "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<TAuthExtra extends ExtraClaims = ExtraClaims> = Omit<McpExtra<TAuthExtra>, "mcpReq"> & {
+    mcpReq: Omit<McpExtra<TAuthExtra>["mcpReq"], "_meta"> & {
+        _meta?: RequestMeta & ClientHintsMeta;
+    };
+};
+type ToolHandler<TInput extends Record<string, StandardSchemaWithJSON>, TReturn extends {
+    content?: HandlerContent;
+} = {
+    content?: HandlerContent;
+}, 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;
+ * `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;
+/**
+ * Prime the build-time Vite manifest before user code constructs its
+ * `McpServer`. Called from the generated `dist/__entry.js`; not part of the
+ * user-facing API.
+ *
+ * @internal
+ */
+export declare function __setBuildManifest(manifest: Record<string, {
+    file: string;
+}>): void;
+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 `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>;
+    private claimedViews;
+    private viewMetaBuilders;
+    /**
+     * Maps a view resource's query-less path to its canonical registered URI
+     * (the one carrying the `?v=` cache key). Lets `resources/read` resolve the
+     * underlying view no matter which version param the consumer sends, since
+     * the param is only a cache key, not part of the resource's identity.
+     */
+    private viewUriByPath;
+    private viteManifest;
+    private oauthEnabled;
+    private resolveResourceMetadataUrl?;
+    private readonly toolSecuritySchemes;
+    private readonly userMiddlewareEntries;
+    constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions);
+    /**
+     * 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`.
+     *
+     * @internal
+     */
+    get securitySchemesByTool(): ReadonlyMap<string, SecurityScheme[] | undefined>;
+    /**
+     * Inject the resolver the app uses to build the protected-resource metadata
+     * URL, so tool handlers can emit in-band auth challenges.
+     *
+     * @internal
+     */
+    setResourceMetadataUrlResolver(resolve: ResourceMetadataUrlResolver): this;
+    private setupSkills;
+    /** Register MCP protocol-level middleware (catch-all). */
+    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<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;
+        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.
+     */
+    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.
+     */
+    mcpMiddleware<W extends McpWildcard>(filter: W, handler: (request: {
+        method: string;
+        params: Record<string, unknown>;
+    }, 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<TAuthExtra>): this;
+    /**
+     * 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}.
+     *
+     * @internal
+     */
+    protocolMiddlewareEntries(): McpMiddlewareEntry[];
+    private enforceOneToolPerView;
+    private resolveViewRequestContext;
+    private registerViewResources;
+    private registerViewResource;
+    private serveLegacyAppsSdkUrl;
+    private decorateToolHandler;
+    private computeViewVersionParam;
+    private lookupViewFile;
+    private lookupDistFile;
+    /**
+     * Inject the Vite manifest as a value rather than letting `readManifest()`
+     * load it from disk. Required for runtimes without a usable filesystem
+     * (Cloudflare Workers, etc.) — the user's `skybridge build` emits the
+     * manifest as a JS module which the entry imports and passes here.
+     */
+    setViteManifest(manifest: Record<string, {
+        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 Record<string, StandardSchemaWithJSON>, TReturn extends {
+        content?: HandlerContent;
+    }>(config: ToolConfig<InputArgs> & {
+        name: TName;
+    }, 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 {};