skybridge 0.0.0-dev.fec1c58 → 0.0.0-dev.fef24cf

package/dist/server/server.d.ts

@@ -1,44 +1,125 @@
-import type { McpUiResourceMeta } from "@modelcontextprotocol/ext-apps";
-import { McpServer as McpServerBase, type RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
+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 { CallToolResult, Resource, ServerNotification, ServerRequest, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
-import type { RequestHandler } from "express";
+import type { ContentBlock, Implementation, RequestMeta, ServerNotification, ServerRequest, ServerResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { type ErrorRequestHandler, type Express, type RequestHandler } from "express";
+import type { McpExtra, McpExtraFor, McpMethodString, McpMiddlewareFilter, McpMiddlewareFn, McpResultFor, McpTypedMiddlewareFn, McpWildcard } from "./middleware.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;
 };
+/** Which host runtime a view targets — `"apps-sdk"` (ChatGPT) or `"mcp-app"` (MCP Apps spec). */
+export type ViewHostType = "apps-sdk" | "mcp-app";
 /**
- * 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
+ * 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.
  */
-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 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 {
+}
+/** Union of valid view component names. Narrowed by {@link ViewNameRegistry}. */
+export type ViewName = keyof ViewNameRegistry & string;
+/**
+ * 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;
+    /** Restrict where the view is rendered. Defaults to all known hosts. */
+    hosts?: ViewHostType[];
+    /** Apps SDK only: request a visible border around the widget. */
+    prefersBorder?: boolean;
+    /** Apps SDK only: override the iframe's served domain (advanced). */
+    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[];
-};
-type McpServerOriginalToolConfig = Omit<Parameters<typeof McpServerBase.prototype.registerTool<ZodRawShapeCompat, ZodRawShapeCompat>>[1], "inputSchema" | "outputSchema">;
+/**
+ * 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">;
+    securitySchemes?: SecurityScheme[];
+}
+/** {@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 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 ExtractStructuredContent<T> = T extends {
     structuredContent: infer SC;
 } ? Simplify<SC> : never;
@@ -49,61 +130,269 @@ 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 & {
     [K in TName]: ToolDef<ShapeOutput<TInput>, TOutput, TResponseMetadata>;
-}> & {
-    use(...handlers: RequestHandler[]): AddTool<TTools, TName, TInput, TOutput, TResponseMetadata>;
-    use(path: string, ...handlers: RequestHandler[]): AddTool<TTools, TName, TInput, TOutput, TResponseMetadata>;
-    run(): Promise<void>;
-};
-type ToolConfig<TInput extends ZodRawShapeCompat | AnySchema> = {
+}>;
+interface ToolConfig<TInput extends ZodRawShapeCompat | AnySchema> {
+    name: string;
     title?: string;
     description?: string;
     inputSchema?: TInput;
     outputSchema?: ZodRawShapeCompat | AnySchema;
     annotations?: ToolAnnotations;
-    _meta?: Record<string, unknown>;
+    view?: ViewConfig;
+    /**
+     * 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[];
+    _meta?: ToolMeta;
+}
+/**
+ * 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 = Omit<RequestHandlerExtra<ServerRequest, ServerNotification>, "_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 {
+    content?: HandlerContent;
+} = {
+    content?: HandlerContent;
+}> = (args: ShapeOutput<TInput>, extra: ToolHandlerExtra) => 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;
+/**
+ * The Skybridge server. Extends the MCP SDK's `McpServer` with a typed tool
+ * registry, view resources, an embedded Express app, and protocol-level
+ * middleware. Construct it with the same `Implementation` info you would pass
+ * to the SDK, chain {@link McpServer.registerTool} calls to declare tools,
+ * then call {@link McpServer.run} to start the HTTP server.
+ *
+ * The `TTools` generic accumulates each registered tool's input/output/meta
+ * shape, so `typeof server` 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
+ * const server = new McpServer({ name: "my-app", version: "1.0.0" }, {})
+ *   .registerTool({
+ *     name: "search",
+ *     inputSchema: { query: z.string() },
+ *     view: { component: "search" },
+ *   }, async ({ query }) => ({ content: `Results for ${query}` }));
+ *
+ * await server.run();
+ * export type AppType = typeof server;
+ * ```
+ *
+ * @see https://docs.skybridge.tech/api-reference/mcp-server
+ */
+export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>> extends McpServerBaseOmitted {
     readonly $types: McpServerTypes<TTools>;
-    private express?;
-    private customMiddleware;
+    /**
+     * 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. 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;
+    private viteManifest;
+    private readonly serverInfo;
+    private readonly serverOptions?;
+    constructor(serverInfo: Implementation, options?: ServerOptions);
+    /**
+     * 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.
+     *
+     * Note: Alpic Cloud only routes traffic to `/mcp`. Custom paths work
+     * locally and on self-hosted deployments.
+     */
     use(...handlers: RequestHandler[]): this;
     use(path: string, ...handlers: RequestHandler[]): this;
-    run(): Promise<void>;
-    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;
+    /**
+     * 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.
+     *
+     * @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.
+     */
+    mcpMiddleware<M extends McpMethodString>(filter: M, handler: McpTypedMiddlewareFn<M>): 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>, 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>;
+    /**
+     * 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}.
+     *
+     * On Cloudflare Workers / workerd, returns an object exposing `fetch` so
+     * the runtime can bridge incoming requests to the Node HTTP server. On
+     * Node, returns `undefined` once listening.
+     */
+    run(): Promise<{
+        fetch: (...args: unknown[]) => unknown;
+    } | undefined>;
+    private enforceOneToolPerView;
+    private resolveViewRequestContext;
+    private registerViewResources;
+    private registerViewResource;
+    private wrapHandler;
+    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 ZodRawShapeCompat, 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;
 }
 export {};