skybridge 0.0.0-dev.d2586b1 → 0.0.0-dev.d26b118

package/dist/server/server.d.ts

@@ -1,43 +1,68 @@
-import type { McpUiResourceMeta } from "@modelcontextprotocol/ext-apps";
+import type { McpUiToolMeta } 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 { 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 {
+    resourceDomains?: string[];
+    connectDomains?: string[];
+    frameDomains?: string[];
+    redirectDomains?: string[];
+    baseUriDomains?: string[];
+}
+export 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[];
+/** @see https://developers.openai.com/apps-sdk/reference#tool-descriptor-parameters */
+type OpenaiToolMeta = {
+    "openai/outputTemplate": string;
+    "openai/widgetAccessible"?: boolean;
+    "openai/toolInvocation/invoking"?: string;
+    "openai/toolInvocation/invoked"?: string;
+};
+/** @see https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#resource-discovery */
+type McpAppsToolMeta = {
+    ui: McpUiToolMeta;
 };
-type McpServerOriginalToolConfig = Omit<Parameters<typeof McpServerBase.prototype.registerTool<ZodRawShapeCompat, ZodRawShapeCompat>>[1], "inputSchema" | "outputSchema">;
+type InternalToolMeta = Partial<OpenaiToolMeta & McpAppsToolMeta>;
+/**
+ * Type-level marker interface for cross-package type inference.
+ */
+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;
@@ -48,52 +73,75 @@ 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>;
 }>;
-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;
+    mcpMiddleware(handler: McpMiddlewareFn): this;
+    mcpMiddleware(filter: "request", handler: (request: {
+        method: string;
+        params: Record<string, unknown>;
+    }, extra: McpExtra, next: () => Promise<ServerResult>) => Promise<unknown> | unknown): this;
+    mcpMiddleware(filter: "notification", handler: (request: {
+        method: string;
+        params: Record<string, unknown>;
+    }, extra: undefined, next: () => Promise<undefined>) => Promise<unknown> | unknown): this;
+    mcpMiddleware<M extends McpMethodString>(filter: M, handler: McpTypedMiddlewareFn<M>): this;
+    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;
+    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 */
+    wrapHandlerWithViewUUID<InputArgs extends ZodRawShapeCompat>(cb: ToolHandler<InputArgs>): ToolHandler<InputArgs>;
+    /** @internal */
+    wrapHandlerWithContentNormalization<InputArgs extends ZodRawShapeCompat>(cb: ToolHandler<InputArgs>): 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>): RegisteredTool;
 }
 export {};

package/dist/server/server.js

@@ -1,7 +1,12 @@
+import crypto from "node:crypto";
 import { readFileSync } from "node:fs";
+import http from "node:http";
 import path from "node:path";
 import { McpServer as McpServerBase, } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { mergeWith, union } from "es-toolkit";
+import { createApp } from "./express.js";
+import { createMiddlewareEntry } from "./metric.js";
+import { buildMiddlewareChain, getHandlerMaps } from "./middleware.js";
 import { templateHelper } from "./templateHelper.js";
 const mergeWithUnion = (target, source) => {
     return mergeWith(target, source, (targetVal, sourceVal) => {
@@ -10,111 +15,309 @@ const mergeWithUnion = (target, source) => {
         }
     });
 };
-export class McpServer extends McpServerBase {
-    registerWidget(name, resourceConfig, toolConfig, toolCallback) {
-        const userMeta = resourceConfig._meta;
-        const toolMeta = {
-            ...toolConfig._meta,
+// ---------------------------------------------------------------------------
+// Content normalization
+// ---------------------------------------------------------------------------
+export function normalizeContent(content) {
+    if (typeof content === "string") {
+        return [{ type: "text", text: content }];
+    }
+    if (Array.isArray(content)) {
+        return content;
+    }
+    return [content];
+}
+const McpServerBaseOmitted = McpServerBase;
+export class McpServer extends McpServerBaseOmitted {
+    express;
+    customMiddleware = [];
+    customErrorMiddleware = [];
+    mcpMiddlewareEntries = [];
+    mcpMiddlewareApplied = false;
+    claimedWidgets = new Map();
+    use(pathOrHandler, ...handlers) {
+        if (typeof pathOrHandler === "string") {
+            this.customMiddleware.push({
+                path: pathOrHandler,
+                handlers,
+            });
+        }
+        else {
+            this.customMiddleware.push({
+                handlers: [pathOrHandler, ...handlers],
+            });
+        }
+        return this;
+    }
+    useOnError(pathOrHandler, ...handlers) {
+        if (typeof pathOrHandler === "string") {
+            this.customErrorMiddleware.push({ path: pathOrHandler, handlers });
+        }
+        else {
+            this.customErrorMiddleware.push({
+                handlers: [pathOrHandler, ...handlers],
+            });
+        }
+        return this;
+    }
+    mcpMiddleware(filterOrHandler, 
+    // biome-ignore lint/suspicious/noExplicitAny: overloads narrow the handler type at call sites; implementation must accept all variants
+    maybeHandler) {
+        if (this.mcpMiddlewareApplied) {
+            throw new Error("Cannot register MCP middleware after run() or connect() has been called");
+        }
+        const handler = maybeHandler;
+        if (typeof filterOrHandler === "function") {
+            this.mcpMiddlewareEntries.push({
+                filter: null,
+                handler: filterOrHandler,
+            });
+        }
+        else if (handler) {
+            this.mcpMiddlewareEntries.push({
+                filter: filterOrHandler,
+                handler,
+            });
+        }
+        else {
+            throw new Error("mcpMiddleware requires a handler function when a filter is provided");
+        }
+        return this;
+    }
+    applyMcpMiddleware() {
+        if (this.mcpMiddlewareApplied) {
+            return;
+        }
+        this.mcpMiddlewareApplied = true;
+        const monitoringEntry = createMiddlewareEntry();
+        const entries = monitoringEntry
+            ? [monitoringEntry, ...this.mcpMiddlewareEntries]
+            : this.mcpMiddlewareEntries;
+        if (entries.length === 0) {
+            return;
+        }
+        const { requestHandlers, notificationHandlers } = getHandlerMaps(this.server);
+        const instrumentMap = (map, isNotification) => {
+            for (const [method, handler] of map) {
+                map.set(method, buildMiddlewareChain(method, isNotification, handler, entries));
+            }
+            const originalSet = map.set.bind(map);
+            map.set = (method, handler) => originalSet(method, buildMiddlewareChain(method, isNotification, handler, entries));
         };
-        if (!resourceConfig.hosts || resourceConfig.hosts.includes("apps-sdk")) {
+        instrumentMap(requestHandlers, false);
+        instrumentMap(notificationHandlers, true);
+    }
+    async connect(transport) {
+        this.applyMcpMiddleware();
+        return McpServerBase.prototype.connect.call(this, transport);
+    }
+    async run() {
+        this.applyMcpMiddleware();
+        const httpServer = http.createServer();
+        if (!this.express) {
+            this.express = await createApp({
+                mcpServer: this,
+                httpServer,
+                customMiddleware: this.customMiddleware,
+                errorMiddleware: this.customErrorMiddleware,
+            });
+        }
+        httpServer.on("request", this.express);
+        return new Promise((resolve, reject) => {
+            httpServer.on("error", (error) => {
+                console.error("Failed to start server:", error);
+                reject(error);
+            });
+            const port = parseInt(process.env.__PORT ?? "3000", 10);
+            httpServer.listen(port, () => {
+                resolve();
+            });
+        });
+    }
+    // registerTool is defined via interface merging + prototype assignment below
+    // to avoid TypeScript override signature incompatibility with the base class.
+    // -------------------------------------------------------------------------
+    // View (widget) resource registration
+    // -------------------------------------------------------------------------
+    /** @internal */
+    enforceOneToolPerWidget(component, toolName) {
+        const existingTool = this.claimedWidgets.get(component);
+        if (existingTool) {
+            throw new Error(`skybridge: widget "${component}" is already used by tool "${existingTool}". Tool "${toolName}" cannot also reference it — each widget backs exactly one tool.`);
+        }
+        this.claimedWidgets.set(component, toolName);
+    }
+    /** @internal */
+    registerViewResources(toolName, view, toolMeta) {
+        const hosts = view.hosts ?? ["apps-sdk", "mcp-app"];
+        if (hosts.includes("apps-sdk")) {
             const widgetConfig = {
                 hostType: "apps-sdk",
-                uri: `ui://widgets/apps-sdk/${name}.html`,
+                uri: `ui://widgets/apps-sdk/${view.component}.html`,
                 mimeType: "text/html+skybridge",
-                buildContentMeta: ({ resourceDomains, connectDomains, domain }) => {
-                    const userUi = userMeta?.ui;
-                    const userCsp = userUi?.csp;
+                buildContentMeta: ({ resourceDomains, connectDomains, domain }, overrides) => {
                     const defaults = {
                         "openai/widgetCSP": {
                             resource_domains: resourceDomains,
                             connect_domains: connectDomains,
                         },
                         "openai/widgetDomain": domain,
-                        "openai/widgetDescription": toolConfig.description,
+                        "openai/widgetDescription": view.description,
                     };
-                    const fromUi = {
+                    const fromView = {
                         "openai/widgetCSP": {
-                            resource_domains: userCsp?.resourceDomains,
-                            connect_domains: userCsp?.connectDomains,
-                            frame_domains: userCsp?.frameDomains,
-                            redirect_domains: userCsp?.redirectDomains,
+                            resource_domains: view.csp?.resourceDomains,
+                            connect_domains: view.csp?.connectDomains,
+                            frame_domains: view.csp?.frameDomains,
+                            redirect_domains: view.csp?.redirectDomains,
                         },
-                        "openai/widgetDomain": userUi?.domain,
-                        "openai/widgetPrefersBorder": userUi?.prefersBorder,
+                        "openai/widgetDomain": view.domain,
+                        "openai/widgetPrefersBorder": view.prefersBorder,
                     };
-                    const directOpenaiKeys = Object.fromEntries(Object.entries(userMeta ?? {}).filter(([key]) => key.startsWith("openai/")));
-                    return mergeWithUnion(mergeWithUnion(defaults, fromUi), directOpenaiKeys);
+                    const base = mergeWithUnion(mergeWithUnion(defaults, fromView), {
+                        "openai/widgetDomain": overrides.domain,
+                    });
+                    if (view._meta) {
+                        return { ...base, ...view._meta };
+                    }
+                    return base;
                 },
             };
             this.registerWidgetResource({
-                name,
+                name: toolName,
                 widgetConfig,
-                resourceConfig,
+                view,
             });
             toolMeta["openai/outputTemplate"] = widgetConfig.uri;
         }
-        if (!resourceConfig.hosts || resourceConfig.hosts.includes("mcp-app")) {
+        if (hosts.includes("mcp-app")) {
             const widgetConfig = {
                 hostType: "mcp-app",
-                uri: `ui://widgets/ext-apps/${name}.html`,
+                uri: `ui://widgets/ext-apps/${view.component}.html`,
                 mimeType: "text/html;profile=mcp-app",
-                buildContentMeta: ({ resourceDomains, connectDomains, domain }) => {
+                buildContentMeta: ({ resourceDomains, connectDomains, domain, baseUriDomains }, overrides) => {
                     const defaults = {
                         ui: {
                             csp: {
                                 resourceDomains,
                                 connectDomains,
+                                baseUriDomains,
                             },
                             domain,
                         },
                     };
-                    return mergeWithUnion(defaults, { ui: userMeta?.ui });
+                    const fromView = {
+                        ui: {
+                            ...(view.description && { description: view.description }),
+                            ...(view.prefersBorder !== undefined && {
+                                prefersBorder: view.prefersBorder,
+                            }),
+                            ...(view.domain && { domain: view.domain }),
+                            csp: {
+                                ...(view.csp?.resourceDomains && {
+                                    resourceDomains: view.csp.resourceDomains,
+                                }),
+                                ...(view.csp?.connectDomains && {
+                                    connectDomains: view.csp.connectDomains,
+                                }),
+                                ...(view.csp?.frameDomains && {
+                                    frameDomains: view.csp.frameDomains,
+                                }),
+                                ...(view.csp?.baseUriDomains && {
+                                    baseUriDomains: view.csp.baseUriDomains,
+                                }),
+                                ...(view.csp?.redirectDomains && {
+                                    redirectDomains: view.csp.redirectDomains,
+                                }),
+                            },
+                        },
+                    };
+                    const base = mergeWithUnion(mergeWithUnion(defaults, fromView), {
+                        ui: overrides,
+                    });
+                    if (view._meta) {
+                        return { ...base, ...view._meta };
+                    }
+                    return base;
                 },
             };
             this.registerWidgetResource({
-                name,
+                name: toolName,
                 widgetConfig,
-                resourceConfig,
+                view,
             });
+            // @ts-expect-error - For backwards compatibility with Claude current implementation of the specs
+            toolMeta["ui/resourceUri"] = widgetConfig.uri;
             toolMeta.ui = { resourceUri: widgetConfig.uri };
         }
-        this.registerTool(name, {
-            ...toolConfig,
-            _meta: toolMeta,
-        }, toolCallback);
-        return this;
-    }
-    registerTool(name, config, cb) {
-        super.registerTool(name, config, cb);
-        return this;
     }
-    registerWidgetResource({ name, widgetConfig, resourceConfig, }) {
+    registerWidgetResource({ name, widgetConfig, view, }) {
         const { hostType, uri: widgetUri, mimeType, buildContentMeta, } = widgetConfig;
-        this.registerResource(name, widgetUri, { ...resourceConfig, _meta: resourceConfig._meta }, async (uri, extra) => {
+        this.registerResource(name, widgetUri, { description: view.description }, async (uri, extra) => {
             const isProduction = process.env.NODE_ENV === "production";
-            const useForwardedHost = process.env.SKYBRIDGE_USE_FORWARDED_HOST === "true";
-            const serverUrl = isProduction || useForwardedHost
-                ? `https://${extra?.requestInfo?.headers?.["x-forwarded-host"] ?? extra?.requestInfo?.headers?.host}`
-                : "http://localhost:3000";
+            const isClaude = extra?.requestInfo?.headers?.["user-agent"] === "Claude-User";
+            const headers = extra?.requestInfo?.headers || {};
+            const header = (key) => {
+                const val = headers[key];
+                return Array.isArray(val) ? val[0] : val;
+            };
+            let serverUrl;
+            const forwardedHost = header("x-forwarded-host");
+            const origin = header("origin");
+            const host = header("host");
+            if (forwardedHost) {
+                const proto = header("x-forwarded-proto") || "https";
+                serverUrl = `${proto}://${forwardedHost}`;
+            }
+            else if (origin) {
+                serverUrl = origin;
+            }
+            else if (host) {
+                const proto = ["127.0.0.1:", "localhost:"].some((p) => host.startsWith(p))
+                    ? "http"
+                    : "https";
+                serverUrl = `${proto}://${host}`;
+            }
+            else {
+                const devPort = process.env.__PORT || "3000";
+                serverUrl = `http://localhost:${devPort}`;
+            }
             const html = isProduction
                 ? templateHelper.renderProduction({
                     hostType,
                     serverUrl,
-                    widgetFile: this.lookupDistFileWithIndexFallback(`src/widgets/${name}`),
+                    widgetFile: this.lookupWidgetFile(view.component),
                     styleFile: this.lookupDistFile("style.css"),
                 })
                 : templateHelper.renderDevelopment({
                     hostType,
                     serverUrl,
-                    widgetName: name,
+                    widgetName: view.component,
                 });
-            const VITE_HMR_WEBSOCKET_DEFAULT_URL = "ws://localhost:24678";
+            const connectDomains = [serverUrl];
+            if (!isProduction) {
+                const wsUrl = new URL(serverUrl);
+                wsUrl.protocol = wsUrl.protocol === "https:" ? "wss:" : "ws:";
+                connectDomains.push(wsUrl.origin);
+            }
+            let contentMetaOverrides = {};
+            if (isClaude) {
+                const pathname = extra?.requestInfo?.url?.pathname ?? "";
+                const rawUrl = header("x-alpic-forwarded-url") ?? `${serverUrl}${pathname}`;
+                const url = rawUrl.endsWith("/") ? rawUrl.slice(0, -1) : rawUrl;
+                const hash = crypto
+                    .createHash("sha256")
+                    .update(url)
+                    .digest("hex")
+                    .slice(0, 32);
+                contentMetaOverrides = { domain: `${hash}.claudemcpcontent.com` };
+            }
             const contentMeta = buildContentMeta({
                 resourceDomains: [serverUrl],
-                connectDomains: !isProduction ? [VITE_HMR_WEBSOCKET_DEFAULT_URL] : [],
+                connectDomains,
                 domain: serverUrl,
                 baseUriDomains: [serverUrl],
-            });
+            }, contentMetaOverrides);
             return {
                 contents: [
                     { uri: uri.href, mimeType, text: html, _meta: contentMeta },
@@ -122,18 +325,70 @@ export class McpServer extends McpServerBase {
             };
         });
     }
-    lookupDistFile(key) {
+    // -------------------------------------------------------------------------
+    // Handler wrapping
+    // -------------------------------------------------------------------------
+    /** @internal */
+    wrapHandlerWithViewUUID(cb) {
+        return async (args, extra) => {
+            const result = await cb(args, extra);
+            return {
+                ...result,
+                content: normalizeContent(result.content),
+                _meta: {
+                    ...result._meta,
+                    viewUUID: crypto.randomUUID(),
+                },
+            };
+        };
+    }
+    /** @internal */
+    wrapHandlerWithContentNormalization(cb) {
+        return async (args, extra) => {
+            const result = await cb(args, extra);
+            return {
+                ...result,
+                content: normalizeContent(result.content),
+            };
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Manifest helpers
+    // -------------------------------------------------------------------------
+    lookupWidgetFile(widgetName) {
         const manifest = this.readManifest();
-        return manifest[key]?.file;
+        const file = manifest[widgetName]?.file;
+        if (!file) {
+            throw new Error(`Widget "${widgetName}" not found in Vite manifest. Did the build complete successfully? Expected key "${widgetName}" in dist/assets/.vite/manifest.json.`);
+        }
+        return file;
     }
-    lookupDistFileWithIndexFallback(basePath) {
+    lookupDistFile(key) {
         const manifest = this.readManifest();
-        const flatFileKey = `${basePath}.tsx`;
-        const indexFileKey = `${basePath}/index.tsx`;
-        return manifest[flatFileKey]?.file ?? manifest[indexFileKey]?.file;
+        return manifest[key]?.file;
     }
     readManifest() {
         return JSON.parse(readFileSync(path.join(process.cwd(), "dist", "assets", ".vite", "manifest.json"), "utf-8"));
     }
+    registerTool(...args) {
+        const baseFn = McpServerBase.prototype.registerTool;
+        if (typeof args[0] === "string") {
+            baseFn.call(this, args[0], args[1], args[2]);
+            return this;
+        }
+        const config = args[0];
+        const cb = args[1];
+        const { name, view, _meta: userToolMeta, ...toolFields } = config;
+        const toolMeta = { ...userToolMeta };
+        if (view) {
+            this.enforceOneToolPerWidget(view.component, name);
+            this.registerViewResources(name, view, toolMeta);
+        }
+        const wrappedCb = view
+            ? this.wrapHandlerWithViewUUID(cb)
+            : this.wrapHandlerWithContentNormalization(cb);
+        baseFn.call(this, name, { ...toolFields, _meta: toolMeta }, wrappedCb);
+        return this;
+    }
 }
 //# sourceMappingURL=server.js.map