skybridge 0.0.0-dev.db8be9c → 0.0.0-dev.dbab7df

package/dist/server/server.d.ts

@@ -1,43 +1,172 @@
-import type { McpUiResourceMeta } from "@modelcontextprotocol/ext-apps";
-import { McpServer as McpServerBase, type RegisteredTool } 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 { CallToolResult, Resource, ServerNotification, ServerRequest, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { McpUiToolMeta } from "@modelcontextprotocol/ext-apps";
+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 { 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`.
+ *
+ * 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;
 };
 /**
- * Extended MCP Apps CSP with upcoming fields from ext-apps PR #158
- * and Skybridge-specific fields for OpenAI compatibility
- * @see https://github.com/modelcontextprotocol/ext-apps/pull/158
+ * 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.
  */
-type ExtendedMcpUiResourceCsp = McpUiResourceMeta["csp"] & {
-    /**
-     * Origins that can receive openExternal redirects without safe-link modal (OpenAI-specific)
-     * @see https://developers.openai.com/apps-sdk/reference#component-resource-_meta-fields
-     */
+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
+ * 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[];
 };
-/** Extended MCP Apps resource metadata with upcoming CSP fields */
-type ExtendedMcpUiResourceMeta = Omit<McpUiResourceMeta, "csp"> & {
-    csp?: ExtendedMcpUiResourceCsp;
-};
-/** User-provided resource configuration with optional CSP override */
-export type WidgetResourceMeta = {
-    ui?: ExtendedMcpUiResourceMeta;
-} & Resource["_meta"];
-export type WidgetHostType = "apps-sdk" | "mcp-app";
-type McpServerOriginalResourceConfig = Omit<Resource, "uri" | "name" | "mimeType" | "_meta"> & {
-    _meta?: WidgetResourceMeta;
-    /** Restrict host types to a specific subset */
-    hosts?: WidgetHostType[];
+/**
+ * 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[];
 };
-type McpServerOriginalToolConfig = Omit<Parameters<typeof McpServerBase.prototype.registerTool<ZodRawShapeCompat, ZodRawShapeCompat>>[1], "inputSchema" | "outputSchema">;
+/**
+ * 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 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<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`.
+ * 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 RawInputShape> = Simplify<{
+    [K in keyof Shape as undefined extends InferSchemaOutput<Shape[K]> ? never : K]: InferSchemaOutput<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;
 } ? Simplify<SC> : never;
@@ -48,52 +177,245 @@ type ExtractMeta<T> = [Extract<T, {
 }> extends {
     _meta: infer M;
 } ? Simplify<M> : unknown;
-/**
- * Type-level marker interface for cross-package type inference.
- * This enables TypeScript to infer tool types across package boundaries
- * using structural typing on the $types property, rather than relying on
- * class generic inference which fails when McpServer comes from different
- * package installations.
- *
- * Inspired by tRPC's _def pattern and Hono's type markers.
- */
-export interface McpServerTypes<TTools extends Record<string, ToolDef>> {
-    readonly tools: TTools;
-}
-type ShapeOutput<Shape extends ZodRawShapeCompat> = Simplify<{
-    [K in keyof Shape as undefined extends SchemaOutput<Shape[K]> ? never : K]: SchemaOutput<Shape[K]>;
-} & {
-    [K in keyof Shape as undefined extends SchemaOutput<Shape[K]> ? K : never]?: SchemaOutput<Shape[K]>;
-}>;
-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>;
-}>;
-type 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;
-    _meta?: Record<string, unknown>;
+    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
+     * 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 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
+ * 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;
+}
+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 {
-    content: CallToolResult["content"];
-} = CallToolResult> = (args: ShapeOutput<TInput>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => TReturn | Promise<TReturn>;
-export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>> extends McpServerBase {
+type ToolHandler<TInput extends RawInputShape, 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" | "registerResource" | "registerPrompt" | "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 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>;
-    registerWidget<TName extends string, TInput extends ZodRawShapeCompat, TReturn extends {
-        content: CallToolResult["content"];
-    }>(name: TName, resourceConfig: McpServerOriginalResourceConfig, toolConfig: McpServerOriginalToolConfig & {
-        inputSchema?: TInput;
-        outputSchema?: ZodRawShapeCompat | AnySchema;
-    }, toolCallback: ToolHandler<TInput, TReturn>): AddTool<TTools, TName, TInput, ExtractStructuredContent<TReturn>, ExtractMeta<TReturn>>;
-    registerTool<TName extends string, InputArgs extends ZodRawShapeCompat, TReturn extends {
-        content: CallToolResult["content"];
-    }>(name: TName, config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs, TReturn>): AddTool<TTools, TName, InputArgs, ExtractStructuredContent<TReturn>, ExtractMeta<TReturn>>;
-    registerTool<InputArgs extends ZodRawShapeCompat>(name: string, config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs>): RegisteredTool;
-    private registerWidgetResource;
+    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 diskManifest;
+    private oauthEnabled;
+    private resolveResourceMetadataUrl?;
+    private readonly toolSecuritySchemes;
+    constructor(serverInfo: Implementation, options?: ServerOptions, skybridgeOptions?: SkybridgeServerOptions<TAuthExtra>);
+    /**
+     * 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;
+    /**
+     * Register a resource. 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. 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 applyInherited;
+    private skillRegistrar;
+    private setupSkills;
+    /**
+     * 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.
+     *
+     * @internal
+     */
+    protocolMiddlewareEntries(): McpMiddlewareEntry[];
+    private enforceOneToolPerView;
+    private resolveViewRequestContext;
+    private registerViewResources;
+    private registerViewResource;
+    private serveLegacyAppsSdkUrl;
+    private decorateToolHandler;
+    private computeViewVersionParam;
+    private lookupViewFile;
     private lookupDistFile;
-    private lookupDistFileWithIndexFallback;
+    /**
+     * 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 RawInputShape, 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 RawInputShape>(config: ToolConfig<InputArgs>, cb: ToolHandler<InputArgs, {
+        content?: HandlerContent;
+    }, TAuthExtra>): this;
 }
 export {};