skybridge 0.0.0-dev.f7aded3 → 0.0.0-dev.f7e85aa

package/dist/server/server.d.ts

@@ -1,99 +1,174 @@
-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 { 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 { ContentBlock, ServerNotification, ServerRequest, ServerResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { ErrorRequestHandler, RequestHandler } from "express";
+import type { McpExtra, McpExtraFor, McpMethodString, McpMiddlewareFilter, McpMiddlewareFn, McpResultFor, McpTypedMiddlewareFn, McpWildcard } from "./middleware.js";
 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
- */
-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
-     */
-    redirectDomains?: 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 */
+export interface ViewCsp {
+    /** Origins for static assets (images, fonts, scripts, styles). */
+    resourceDomains?: string[];
+    /** Origins the widget 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[];
+}
+interface WidgetNameRegistry {
+}
+export type WidgetName = keyof WidgetNameRegistry extends never ? string : keyof WidgetNameRegistry & string;
+export interface ViewConfig {
+    component: WidgetName;
+    description?: string;
     hosts?: WidgetHostType[];
+    prefersBorder?: boolean;
+    domain?: string;
+    csp?: ViewCsp;
+    _meta?: Record<string, unknown>;
+}
+export interface KnownToolMeta {
+    "openai/widgetAccessible"?: boolean;
+    "openai/toolInvocation/invoking"?: string;
+    "openai/toolInvocation/invoked"?: string;
+}
+export type ToolMeta = KnownToolMeta & Record<string, unknown>;
+export type HandlerContent = string | ContentBlock | ContentBlock[];
+type OpenaiToolMeta = {
+    "openai/outputTemplate": string;
+    "openai/widgetAccessible"?: boolean;
+    "openai/toolInvocation/invoking"?: string;
+    "openai/toolInvocation/invoked"?: string;
 };
-type McpServerOriginalToolConfig = Omit<Parameters<typeof McpServerBase.prototype.registerTool<ZodRawShapeCompat, ZodRawShapeCompat>>[1], "inputSchema" | "outputSchema">;
-type Simplify<T> = {
-    [K in keyof T]: T[K];
+/** @see https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#resource-discovery */
+type McpAppsToolMeta = {
+    ui: McpUiToolMeta;
 };
-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 InternalToolMeta = Partial<OpenaiToolMeta & McpAppsToolMeta>;
 /**
  * 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.
+ * 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;
+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 ZodRawShapeCompat, TOutput, TResponseMetadata = unknown> = McpServer<TTools & {
     [K in TName]: ToolDef<ShapeOutput<TInput>, TOutput, TResponseMetadata>;
 }>;
-type ToolConfig<TInput extends ZodRawShapeCompat | AnySchema> = {
+interface UnifiedToolConfig<TInput extends ZodRawShapeCompat | AnySchema> {
+    name: string;
     title?: string;
     description?: string;
     inputSchema?: TInput;
     outputSchema?: ZodRawShapeCompat | AnySchema;
     annotations?: ToolAnnotations;
-    _meta?: Record<string, unknown>;
-};
+    view?: ViewConfig;
+    _meta?: ToolMeta;
+}
 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: RequestHandlerExtra<ServerRequest, ServerNotification>) => TReturn | Promise<TReturn>;
+export declare function normalizeContent(content: HandlerContent): ContentBlock[];
+interface McpServerBaseOmitted extends Omit<McpServerBase, "registerTool" | "connect"> {
+}
+declare const McpServerBaseOmitted: new (...args: ConstructorParameters<typeof McpServerBase>) => McpServerBaseOmitted;
+export declare class McpServer<TTools extends Record<string, ToolDef> = Record<never, ToolDef>> 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 express?;
+    private customMiddleware;
+    private customErrorMiddleware;
+    private mcpMiddlewareEntries;
+    private mcpMiddlewareApplied;
+    private claimedWidgets;
+    use(...handlers: RequestHandler[]): this;
+    use(path: string, ...handlers: RequestHandler[]): this;
+    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(transport: Parameters<typeof McpServerBase.prototype.connect>[0]): Promise<void>;
+    run(): Promise<void>;
+    /** @internal */
+    enforceOneToolPerWidget(component: string, toolName: string): void;
+    /** @internal */
+    registerViewResources(toolName: string, view: ViewConfig, toolMeta: InternalToolMeta): void;
     private registerWidgetResource;
+    /** @internal */
+    wrapHandler<InputArgs extends ZodRawShapeCompat>(cb: ToolHandler<InputArgs>, { attachViewUUID }: {
+        attachViewUUID: boolean;
+    }): ToolHandler<InputArgs>;
+    private lookupWidgetFile;
     private lookupDistFile;
-    private lookupDistFileWithIndexFallback;
     private readManifest;
+    registerTool<TName extends string, InputArgs extends ZodRawShapeCompat, TReturn extends {
+        content: HandlerContent;
+    }>(config: UnifiedToolConfig<InputArgs> & {
+        name: TName;
+    }, cb: ToolHandler<InputArgs, TReturn>): AddTool<TTools, TName, InputArgs, ExtractStructuredContent<TReturn>, ExtractMeta<TReturn>>;
+    registerTool<InputArgs extends ZodRawShapeCompat>(config: UnifiedToolConfig<InputArgs>, cb: ToolHandler<InputArgs>): this;
 }
 export {};