mcp-use 2.0.0-beta.4 → 2.0.0-beta.41

package/dist/server.d.ts

@@ -1,11 +1,20 @@
 import { type ServerEventBus } from "@modelcontextprotocol/server";
+import { Hono, type Env, type MiddlewareHandler } from "hono";
+import { type ServerBranding } from "./branding.js";
 import { type ServerConfig } from "./config.js";
+import { type McpEventListenerFnFor, type McpEventPattern, type McpMiddlewareFnFor, type McpMiddlewarePattern } from "./middleware/mcp-middleware.js";
 import type { FromOpenAPIOptions } from "./openapi/types.js";
 import type { InferPromptInput, PromptCallback, PromptDefinition } from "./prompts.js";
 import type { InferTemplateParams, ResourceCallback, ResourceDefinition, ResourceTemplateCallback, ResourceTemplateDefinition } from "./resources.js";
+import type { ProxyConnection, ProxyServerConfig } from "./mcp-proxy.js";
 import type { InferToolInput, InferToolName, InferToolOutput, ToolCallback, ToolDefinition, ToolRef } from "./tools.js";
 import { registerViews, type ViewsManifest } from "./views/index.js";
 type HasOAuth<TUser> = [TUser] extends [never] ? false : true;
+/** Options accepted by {@link MCPServer.listen}. */
+export interface ListenOptions {
+    /** Explicit bind host; takes precedence over `HOST` and configured `host`. */
+    host?: string;
+}
 /**
  * MCP server with declarative tool/resource/prompt registration, served
  * statelessly over a composed fetch handler.
@@ -27,8 +36,32 @@ type HasOAuth<TUser> = [TUser] extends [never] ? false : true;
  * await server.listen(3000);
  * ```
  */
-export declare class MCPServer<TUser = never> {
+export declare class MCPServer<TUser = never, TEnv extends Env = Env> {
     #private;
+    /** Hono application that owns HTTP middleware and routes. */
+    readonly app: Hono<TEnv>;
+    /** Register a typed `GET` route on {@link MCPServer.app}. */
+    readonly get: Hono<TEnv>["get"];
+    /** Register a typed `POST` route on {@link MCPServer.app}. */
+    readonly post: Hono<TEnv>["post"];
+    /** Register a typed `PUT` route on {@link MCPServer.app}. */
+    readonly put: Hono<TEnv>["put"];
+    /** Register a typed `PATCH` route on {@link MCPServer.app}. */
+    readonly patch: Hono<TEnv>["patch"];
+    /** Register a typed `DELETE` route on {@link MCPServer.app}. */
+    readonly delete: Hono<TEnv>["delete"];
+    /** Register a typed route for every HTTP method on {@link MCPServer.app}. */
+    readonly all: Hono<TEnv>["all"];
+    /**
+     * Canonical Web-standard handler for edge runtimes and framework mounting.
+     *
+     * @example
+     * ```ts
+     * export default server;
+     * // or: export const POST = server.fetch;
+     * ```
+     */
+    readonly fetch: (...args: Parameters<Hono<TEnv>["fetch"]>) => Promise<Response>;
     /**
      * Create an MCP server from a parsed, bundled OpenAPI document.
      *
@@ -56,7 +89,7 @@ export declare class MCPServer<TUser = never> {
      * is both the MCP route and the path of the OAuth protected-resource
      * identity, so any explicit OAuth resource URL must use that exact path.
      * Nothing binds or listens until {@link MCPServer.listen} or
-     * {@link MCPServer.getHandler} is called.
+     * the first request reaches {@link MCPServer.fetch}.
      */
     constructor(config: ServerConfig<TUser>);
     /**
@@ -64,22 +97,48 @@ export declare class MCPServer<TUser = never> {
      *
      * Reflects `config.basePath` (default `"/mcp"`). Exposed so tooling that
      * imports the entry module — `mcp-use dev`'s startup log, for example —
-     * can build the endpoint and inspector URLs without assuming the default.
+     * can build endpoint and development-tool URLs without assuming the default.
      */
     get basePath(): string;
+    /** Configured bind host, before CLI and environment overrides. */
+    get host(): string | undefined;
+    /** Configured bind port, before CLI and environment overrides. */
+    get port(): number | undefined;
+    /**
+     * Immutable normalized branding shared by MCP identity and browser pages.
+     *
+     * `favicon` is the final source after explicit-favicon and icon-selection
+     * precedence. Landing-page integrations can use this accessor and link to
+     * the server's root-level `/favicon.ico` route without reading private
+     * configuration or depending on the landing/view layers.
+     *
+     * @example
+     * ```ts
+     * if (server.branding.favicon) {
+     *   console.log("Browser favicon: /favicon.ico");
+     * }
+     * ```
+     */
+    get branding(): ServerBranding;
+    /** @deprecated Use {@link MCPServer.fetch} directly. */
+    getHandler(): typeof this.fetch;
     /**
      * Register a tool. Input is validated against `inputSchema` before the callback
      * runs; results carrying `structuredContent` are type-checked against
      * `outputSchema` at the callback's return position.
      *
+     * Assign static registrations to exported constants so `mcp-env.d.ts` can
+     * expose their {@link ToolRef} types to views:
+     * `export const search = server.tool(...)`.
+     *
      * @returns A {@link ToolRef} carrying the tool name and phantom types for
      * inference-based view typing.
      */
-    tool<const T extends ToolDefinition>(definition: T, callback: ToolCallback<InferToolInput<T>, InferToolOutput<T>, TUser, HasOAuth<TUser>>): ToolRef<InferToolName<T>, InferToolInput<T>, InferToolOutput<T>>;
+    tool<const T extends ToolDefinition>(definition: T, callback: ToolCallback<InferToolInput<T>, InferToolOutput<T>, TUser, HasOAuth<TUser>, TEnv>): ToolRef<InferToolName<T>, InferToolInput<T>, InferToolOutput<T>>;
     /**
-     * Prime the views registry from a build/dev manifest.
+     * Prime the views registry from build/dev registry data.
      *
-     * @param views - Manifest map keyed by view directory name.
+     * @param views - Registry map keyed by view directory name.
      * @param options - Priming options. When `dev` is true, resource CSP
      * emission appends the serving origin's websocket variant to
      * `connectDomains` so Vite HMR passes host-enforced CSP. Pass
@@ -109,7 +168,7 @@ export declare class MCPServer<TUser = never> {
         projectRoot?: string;
     }): void;
     /** Register a static resource readable at `definition.uri`. */
-    resource(definition: ResourceDefinition, callback: ResourceCallback<TUser, HasOAuth<TUser>>): this;
+    resource(definition: ResourceDefinition, callback: ResourceCallback<TUser, HasOAuth<TUser>, TEnv>): this;
     /**
      * Register a parameterized resource. Reads matching `uriTemplate` invoke
      * the callback with the extracted variables.
@@ -119,37 +178,110 @@ export declare class MCPServer<TUser = never> {
      * `string`), which is what lets `InferTemplateParams` type the callback's
      * `params` from the template's variables.
      */
-    resourceTemplate<const T extends ResourceTemplateDefinition>(definition: T, callback: ResourceTemplateCallback<InferTemplateParams<T>, TUser, HasOAuth<TUser>>): this;
+    resourceTemplate<const TUriTemplate extends string>(definition: ResourceTemplateDefinition<TUriTemplate>, callback: ResourceTemplateCallback<InferTemplateParams<{
+        uriTemplate: TUriTemplate;
+    }>, TUser, HasOAuth<TUser>, TEnv>): this;
     /**
      * Register a prompt template. Schema fields wrapped with `completable()`
      * gain autocomplete via `completion/complete`.
      */
-    prompt<T extends PromptDefinition>(definition: T, callback: PromptCallback<InferPromptInput<T>, TUser, HasOAuth<TUser>>): this;
+    prompt<T extends PromptDefinition>(definition: T, callback: PromptCallback<InferPromptInput<T>, TUser, HasOAuth<TUser>, TEnv>): this;
+    /**
+     * Compose upstream MCP servers into this server.
+     *
+     * A name-keyed HTTP config creates upstream connections through the optional
+     * `@mcp-use/client` v2 peer. Each key automatically namespaces its mounted
+     * tools, resources, and prompts. You may instead pass an existing ready
+     * {@link ProxyConnection}; its negotiated server name becomes the namespace
+     * and the connection remains caller-owned.
+     *
+     * Connection, introspection, and collision failures are diagnosed and
+     * skipped without discarding capabilities that can be mounted.
+     *
+     * @param servers - Namespace-keyed upstream HTTP connection settings.
+     * @throws If `@mcp-use/client` is not installed or the server already started
+     * or closed.
+     *
+     * @example
+     * ```ts
+     * await server.proxy({
+     *   weather: {
+     *     url: "https://weather.example.com/mcp",
+     *     authToken: process.env.WEATHER_MCP_TOKEN,
+     *   },
+     * });
+     * ```
+     */
+    proxy(servers: Record<string, ProxyServerConfig>): Promise<void>;
+    /**
+     * Mount an existing ready `@mcp-use/client` v2 connection.
+     *
+     * @param connection - Ready connection to introspect and forward through.
+     * The connection's negotiated server name automatically namespaces every
+     * mounted capability. Introspection and collision failures are diagnosed and
+     * skipped without discarding capabilities that can be mounted.
+     *
+     * @throws If the server already started or closed.
+     *
+     * @example
+     * ```ts
+     * const connection = await client.connect("database");
+     * await server.proxy(connection);
+     * ```
+     */
+    proxy(connection: ProxyConnection): Promise<void>;
     /**
-     * Web-standard request handler for the whole app (MCP endpoint included) —
-     * usable directly on serverless/edge runtimes or in tests.
+     * Register HTTP middleware or typed MCP operation middleware.
      *
-     * The handler never binds a socket, so no Host/Origin validation applies
-     * by default: DNS rebinding targets locally bound servers, and platform
-     * edges (Vercel, Cloudflare, …) only route hostnames assigned to the
-     * deployment. Set `allowedHosts`/`allowedOrigins` to opt into validation
-     * (additive — localhost-class values stay allowed).
+     * MCP patterns always use an `mcp:` prefix (for example
+     * `mcp:tools/call`, `mcp:*`). Every other overload is Hono middleware and
+     * may target all routes or a path pattern.
      *
-     * Pass the same `bus` to multiple server instances when their handlers
-     * replace one another while existing `subscriptions/listen` streams remain
-     * open. The bus is fixed when this instance first mounts.
+     * Exact methods may transform their typed result. The global `mcp:*` pattern
+     * is pass-through middleware. Middleware runs in registration order; call
+     * `next()` to continue the chain.
      *
-     * @param options - Optional handler wiring.
+     * @example
+     * ```ts
+     * server.use("/api/*", async (c, next) => {
+     *   c.set("requestId", crypto.randomUUID());
+     *   await next();
+     * });
+     *
+     * server.use("mcp:tools/call", async (ctx, next) => {
+     *   console.log(`Calling tool: ${ctx.params.name}`);
+     *   return next();
+     * });
+     * ```
+     */
+    use<P extends McpMiddlewarePattern>(pattern: P, handler: McpMiddlewareFnFor<P, TEnv>): this;
+    use(handler: MiddlewareHandler<TEnv>): this;
+    use(path: `/${string}` | "*", ...handlers: MiddlewareHandler<TEnv>[]): this;
+    /**
+     * Register a read-only MCP observer. Unlike {@link MCPServer.use}, listeners
+     * cannot block, override, or mutate params. Throwing is logged and does not
+     * fail the request.
+     *
+     * Append `:complete` to run after the handler (for example
+     * `mcp:tools/call:complete`).
      *
      * @example
      * ```ts
-     * const handler = server.getHandler();
-     * export default { fetch: handler };
+     * server.on("mcp:tools/call", (ctx) => {
+     *   metrics.increment("tools.call", { tool: ctx.params.name });
+     * });
      * ```
      */
-    getHandler(options?: {
-        bus?: ServerEventBus;
-    }): (request: Request) => Promise<Response>;
+    on<P extends McpEventPattern>(pattern: P, handler: McpEventListenerFnFor<P, TEnv>): this;
+    /**
+     * Attach the shared development event bus before the first request.
+     *
+     * @param bus - Bus retained across hot-reloaded server instances.
+     * @internal
+     */
+    __setEventBus(bus: ServerEventBus): void;
+    /** Mount and validate the Hono/MCP application without serving a request. @internal */
+    __mount(): void;
     /**
      * Publish a tools-list change to v2 clients with active subscriptions.
      *
@@ -189,12 +321,13 @@ export declare class MCPServer<TUser = never> {
      */
     notifyResourceUpdated(uri: string): Promise<void>;
     /**
-     * Serve over HTTP on Node. Pass port `0` for an ephemeral port.
+     * Serve over HTTP on Node. Pass port `0` for an ephemeral port. Port
+     * precedence is the argument, `PORT`, `config.port`, then `3000`; host
+     * precedence is `options.host`, `HOST`, `config.host`, then `127.0.0.1`.
      *
-     * Binds `config.host` (default `127.0.0.1`). Localhost-class binds get
-     * DNS-rebinding protection automatically: `Host` on every request,
-     * `Origin` only on non-GET/HEAD (sandboxed view iframes send
-     * `Origin: null` on asset GETs). To serve publicly set `host: "0.0.0.0"`;
+     * Localhost-class binds get
+     * DNS-rebinding Host protection automatically. Origin validation is off
+     * unless `allowedOrigins` is set. To serve publicly set `host: "0.0.0.0"`;
      * behind a platform edge that is all that's needed, and `allowedHosts`
      * restricts direct exposure (additive — localhost-class values stay allowed).
      *
@@ -204,10 +337,10 @@ export declare class MCPServer<TUser = never> {
      * requests accepted before then are queued. Public/wildcard listeners must
      * configure the resource before calling this method.
      *
-     * @throws If called on a localhost-class bind after {@link MCPServer.getHandler}
+     * @throws If called on a localhost-class bind after {@link MCPServer.fetch}
      * already mounted the app without Host validation.
      */
-    listen(port?: number): Promise<{
+    listen(port?: number | undefined, options?: ListenOptions): Promise<{
         port: number;
         url: string;
     }>;
@@ -215,10 +348,9 @@ export declare class MCPServer<TUser = never> {
      * Abort in-flight MCP exchanges and stop the HTTP listener.
      *
      * A closed server is done for good — the underlying MCP handler stays
-     * closed, so `listen()`/`getHandler()` cannot revive it. Create a new
+     * closed, so `listen()`/`fetch()` cannot revive it. Create a new
      * instance to serve again.
      */
     close(): Promise<void>;
 }
 export {};
-//# sourceMappingURL=server.d.ts.map

package/dist/tools.d.ts

@@ -1,19 +1,19 @@
-import type { CallToolResult, InputRequiredResult, StandardSchemaWithJSON, ToolAnnotations } from "@modelcontextprotocol/server";
+import type { CallToolResult, InputRequiredResult, MetaObject, StandardSchemaWithJSON, ToolAnnotations } from "@modelcontextprotocol/server";
+import type { Env } from "hono";
 import type { McpUiResourceCsp } from "@modelcontextprotocol/ext-apps";
 import type { RequestContext } from "./context.js";
 import type { UiPermissions } from "./views/types.js";
 /**
  * Binds a tool to a view directory for MCP Apps rendering.
  *
- * Any number of tools may share the same `name`. Resource facts
- * (`description`, `csp`, `permissions`, `domain`, `prefersBorder`) have one
- * authoring point — at most one binder may declare them; others pass only
- * `{ name }`. The view file exports only the component; the framework reads
- * these fields at registration and emits them on the bound view's MCP
- * resource (hosts read resource `_meta.ui`, not tool-level copies).
+ * A view may have at most one bound tool. That tool owns the resource facts
+ * (`description`, `csp`, `permissions`, `domain`, `prefersBorder`); a second
+ * tool that names the same view is rejected. The view file exports the
+ * component, while the framework emits these fields on the view's MCP
+ * resource, where hosts read `_meta.ui`.
  */
 export interface ToolViewConfig {
-    /** View directory / manifest name, e.g. `"product-search-result"`. */
+    /** View directory / registry name, e.g. `"product-search-result"`. */
     name: string;
     /**
      * Human-readable description of the view resource → the resource's
@@ -22,8 +22,9 @@ export interface ToolViewConfig {
     description?: string;
     /**
      * CSP domains the host must allow → resource `_meta.ui.csp`. The framework
-     * auto-appends its serving origin to `resourceDomains` at emission time;
-     * other author-set fields (`frameDomains`, `baseUriDomains`, …) pass through.
+     * appends the server origin to `connectDomains` and the configured assets
+     * origin (or server origin) to `resourceDomains` at emission time. Other
+     * author-set fields (`frameDomains`, `baseUriDomains`, …) pass through.
      */
     csp?: McpUiResourceCsp;
     /** Sandbox permissions the view needs → resource `_meta.ui.permissions`. */
@@ -69,6 +70,17 @@ export interface ToolDefinition {
     outputSchema?: StandardSchemaWithJSON;
     /** Behavioral hints for clients (readOnlyHint, destructiveHint, …). */
     annotations?: ToolAnnotations;
+    /**
+     * Extension metadata advertised on this tool's `tools/list` descriptor.
+     *
+     * Use vendor-namespaced keys for custom data. This definition metadata is
+     * distinct from a tool callback result's `_meta`: it describes the tool,
+     * while result `_meta` belongs to one invocation. For view-bound or
+     * visibility-restricted tools, framework-owned MCP Apps keys are derived
+     * from {@link ToolDefinition.view} and {@link ToolDefinition.visibility};
+     * those derived values take precedence over colliding entries here.
+     */
+    _meta?: MetaObject;
     /**
      * Declares who may call or see the tool. Emitted as `_meta.ui.visibility`
      * on `tools/list`. Omitted = host default (callable by the model, visible
@@ -105,9 +117,9 @@ export interface ToolRef<Name extends string = string, Input = Record<string, un
 }
 /**
  * Result a tool callback may return, keyed by the tool's inferred output
- * type. Completed calls use the SDK's raw {@link CallToolResult}; interactive
- * calls may return an {@link InputRequiredResult}. There is no
- * framework-specific result layer.
+ * type. Prefer the SDK's raw {@link CallToolResult}; interactive calls may
+ * return an {@link InputRequiredResult}. Deprecated response helpers
+ * (`text`, `object`, …) return the same envelope and remain accepted.
  *
  * Without an `outputSchema` (`TOutput = never`) any `CallToolResult` is
  * accepted. With one, the result must carry `structuredContent` matching the
@@ -162,5 +174,4 @@ export type InferToolName<T> = T extends {
  * an `outputSchema` must return matching `structuredContent` or an `isError`
  * result; tools without one accept any {@link CallToolResult}.
  */
-export type ToolCallback<TInput = Record<string, unknown>, TOutput = never, TUser = never, HasOAuth extends boolean = false> = (params: TInput, ctx: RequestContext<TUser, HasOAuth>) => ToolResult<TOutput> | Promise<ToolResult<TOutput>>;
-//# sourceMappingURL=tools.d.ts.map
+export type ToolCallback<TInput = Record<string, unknown>, TOutput = never, TUser = never, HasOAuth extends boolean = false, TEnv extends Env = Env> = (params: TInput, ctx: RequestContext<TUser, HasOAuth, TEnv>) => ToolResult<TOutput> | Promise<ToolResult<TOutput>>;

package/dist/usage.d.ts

@@ -0,0 +1,11 @@
+type Value = string | number | boolean;
+type Properties = Record<string, Value | undefined>;
+/** Capture one anonymous, flat SDK usage event. @internal */
+export declare function recordUsage(feature: string, action: string, properties?: Properties, options?: {
+    onceKey?: string;
+    sampleRate?: number;
+    serverRoot?: string;
+}): void;
+/** Wait for in-flight usage events in validation fixtures. @internal */
+export declare function flushUsage(): Promise<void>;
+export {};

package/dist/views/capabilities.d.ts

@@ -31,4 +31,3 @@ export declare function extractClientCapabilitiesFromBody(body: unknown): Client
  * of this result.
  */
 export declare function supportsViews(capabilities: ClientCapabilities | undefined): boolean;
-//# sourceMappingURL=capabilities.d.ts.map

package/dist/views/constants.d.ts

@@ -11,7 +11,6 @@ export declare const UI_RESOURCE_URI_META_KEY: "ui/resourceUri";
 /**
  * Build the stable `ui://` resource URI for a view name.
  *
- * @param viewName - View directory / manifest key.
+ * @param viewName - View directory / registry key.
  */
 export declare function viewResourceUri(viewName: string): string;
-//# sourceMappingURL=constants.d.ts.map

package/dist/views/csp-env.d.ts

@@ -34,4 +34,3 @@ export interface BuildCspOptions {
  */
 export declare function buildMergedResourceCsp(authorFacts: ViewResourceFacts | undefined, options: BuildCspOptions): McpUiResourceCsp;
 export {};
-//# sourceMappingURL=csp-env.d.ts.map

package/dist/views/document.d.ts

@@ -1,12 +1,11 @@
 import type { ViewManifestEntry } from "./types.js";
 /**
- * Resolve a manifest asset path to an absolute URL for embedding in the
+ * Resolve a registry asset path to an absolute URL for embedding in the
  * synthesized view document.
  *
- * External manifest entries are origin-absolute `/`-prefixed paths by
- * contract ({@link ExternalViewManifestEntry}).
+ * Dev external registry paths are origin-absolute and `/`-prefixed.
  *
- * @param assetPath - Origin-absolute path starting with `/`.
+ * @param assetPath - Origin-absolute dev path starting with `/`.
  * @param origin - Request-resolved public origin.
  * @returns Absolute URL `${origin}${assetPath}`.
  * @throws When `assetPath` does not start with `/`.
@@ -16,7 +15,7 @@ export declare function resolveAssetUrl(assetPath: string, origin: string): stri
  * Build the HTTP path prefix for a view's built assets (no origin).
  *
  * @param basePath - MCP mount prefix (e.g. `/mcp`).
- * @param viewName - View directory / manifest key.
+ * @param viewName - View directory / registry key.
  */
 export declare function viewAssetsBasePath(basePath: string, viewName: string): string;
 /**
@@ -26,7 +25,7 @@ export declare function viewAssetsBasePath(basePath: string, viewName: string):
  *   view-relative production path (`assets/…`).
  * @param assetsBase - Assets URL prefix (origin + optional path).
  * @param basePath - MCP mount prefix.
- * @param viewName - View directory / manifest key (required for view-relative paths).
+ * @param viewName - View directory / registry key (required for view-relative paths).
  */
 export declare function resolveExternalAssetUrl(assetPath: string, assetsBase: string, basePath: string, viewName: string): string;
 /**
@@ -38,16 +37,15 @@ export declare function resolveExternalAssetUrl(assetPath: string, assetsBase: s
  */
 export declare function resolvePublicBase(assetsBase: string, basePath: string): string;
 /**
- * Synthesize a complete HTML document for a view from manifest data.
+ * Synthesize a complete HTML document for a view from registry data.
  *
  * Production (`kind: "external"`) loads built assets over HTTP with absolute
- * URLs. Legacy `kind: "inline"` embeds JS/CSS directly. Dev uses Vite module
+ * URLs. Production `kind: "inline"` embeds JS/CSS directly. Dev uses Vite module
  * URLs (`kind: "external"` with origin-absolute paths).
  *
- * @param entry - Primed manifest entry for the view.
+ * @param entry - Primed registry entry for the view.
  * @param assetsBase - Request-resolved assets URL prefix for absolute asset URLs.
  * @param basePath - MCP mount prefix (e.g. `/mcp`).
- * @param viewName - View directory / manifest key (required for production external paths).
+ * @param viewName - View directory / registry key (required for production external paths).
  */
 export declare function synthesizeViewDocument(entry: ViewManifestEntry, assetsBase: string, basePath: string, viewName?: string): string;
-//# sourceMappingURL=document.d.ts.map

package/dist/views/index.d.ts

@@ -8,4 +8,3 @@ export { parseDomainList, buildMergedResourceCsp } from "./csp-env.js";
 export { createViewPublicHandler, createViewAssetsHandler } from "./routes.js";
 export { extractClientCapabilitiesFromBody, getStashedClientCapabilities, stashClientCapabilities, supportsViews, } from "./capabilities.js";
 export { buildResourceUiMeta, buildToolResultUiMeta, buildToolUiMeta, viewResourceConfig, type BuildResourceUiMetaOptions, } from "./wire.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/views/origin.d.ts

@@ -40,4 +40,3 @@ export declare function resolveRequestOrigin(request: Request): string;
  * Whether `MCP_ASSETS_URL` is explicitly configured (distinct from server).
  */
 export declare function hasExplicitAssetsBase(): boolean;
-//# sourceMappingURL=origin.d.ts.map

package/dist/views/public-route.d.ts

@@ -10,14 +10,19 @@
  */
 export declare function resolvePublicFilePath(publicRoot: string, subpath: string): Promise<string | null>;
 /**
- * Serve one file from the project's `public/` directory.
+ * Serve one static view-bundle or project-public file.
  *
  * @param diskPath - Absolute path resolved by {@link resolvePublicFilePath}.
+ * @param options - `head` returns headers without opening a file stream.
+ *   When `deferCors` is true, omit hardcoded `ACAO: *` so global
+ *   {@link ServerConfig.cors} middleware owns CORS headers.
  * @returns A `Response` with `Cache-Control: public, max-age=0, must-revalidate`
- * and `Access-Control-Allow-Origin: *` so cross-origin sandboxed view iframes
- * can load public files (module scripts and fetches use CORS mode).
+ * and optionally `Access-Control-Allow-Origin: *` so cross-origin sandboxed
+ * view iframes can load static files (module scripts and fetches use CORS mode).
  *
  * @internal
  */
-export declare function servePublicFile(diskPath: string): Promise<Response>;
-//# sourceMappingURL=public-route.d.ts.map
+export declare function servePublicFile(diskPath: string, options?: {
+    deferCors?: boolean;
+    head?: boolean;
+}): Promise<Response>;

package/dist/views/register.d.ts

@@ -1,7 +1,7 @@
 import type { ViewsManifest } from "./types.js";
 /**
  * Symbol-keyed method on {@link MCPServer} that primes the views registry
- * from a build/dev manifest.
+ * from build/dev registry data.
  *
  * @internal
  */
@@ -25,4 +25,3 @@ export interface RegisterViewsOptions {
 }
 /** Type of the {@link registerViews} method on {@link MCPServer}. */
 export type RegisterViews = (views: ViewsManifest, options?: RegisterViewsOptions) => void;
-//# sourceMappingURL=register.d.ts.map

package/dist/views/routes.d.ts

@@ -14,6 +14,7 @@ import type { ViewManifestEntry } from "./types.js";
  */
 export declare function createViewAssetsHandler(basePath: string, views: ReadonlyMap<string, ViewManifestEntry>, options?: {
     projectRoot?: string;
+    deferCors?: boolean;
 }): FetchHandler | undefined;
 /**
  * Fetch handler for public view assets under `${basePath}/_mcp-use/public/`.
@@ -22,19 +23,22 @@ export declare function createViewAssetsHandler(basePath: string, views: Readonl
  * cross-origin sandboxed view iframes.
  *
  * Node filesystem modules load only on the first public-asset request so the
- * library entry stays edge-safe for `getHandler()`-only deployments.
+ * library entry stays edge-safe for `server.fetch` deployments.
  *
  * @param basePath - MCP mount prefix (e.g. `/mcp`).
  * @param views - Primed view registry; empty skips mounting.
  * @param options - When `dev` is true, the public route reads from
  *   `<projectRoot>/public` instead of `.mcp-use/build/views/public/`.
- *   `projectRoot` defaults to `process.cwd()`.
+ *   `projectRoot` defaults to `process.cwd()`. `enabled` mounts the shared
+ *   public route for local server branding even when no views are registered.
  *
  * @internal
  */
 export declare function createViewPublicHandler(basePath: string, views: ReadonlyMap<string, ViewManifestEntry>, options?: {
     dev?: boolean;
     projectRoot?: string;
+    deferCors?: boolean;
+    enabled?: boolean;
 }): FetchHandler | undefined;
 /**
  * @deprecated Use {@link createViewPublicHandler}.
@@ -42,4 +46,3 @@ export declare function createViewPublicHandler(basePath: string, views: Readonl
  * @internal
  */
 export declare function mountViewRoutes(): void;
-//# sourceMappingURL=routes.d.ts.map

package/dist/views/types.d.ts

@@ -16,8 +16,9 @@ export interface ViewResourceFacts {
     description?: string;
     /**
      * CSP domains the host must allow → resource `_meta.ui.csp`. The framework
-     * auto-appends its serving origin to `resourceDomains` at emission time;
-     * other author-set fields (`frameDomains`, `baseUriDomains`, …) pass through.
+     * appends the server origin to `connectDomains` and the configured assets
+     * origin (or server origin) to `resourceDomains` at emission time. Other
+     * author-set fields (`frameDomains`, `baseUriDomains`, …) pass through.
      */
     csp?: McpUiResourceCsp;
     /** Sandbox permissions the view needs → `_meta.ui.permissions`. */
@@ -31,11 +32,13 @@ export interface ViewResourceFacts {
     prefersBorder?: boolean;
 }
 /**
- * Production manifest entry: a self-contained view bundle whose JS and CSS are
- * inlined into the synthesized HTML document (zero asset fetches at srcdoc boot).
+ * Manifest entry whose JS and CSS are embedded in the synthesized HTML
+ * document.
+ *
+ * The production CLI emits this shape for `mcp-use build --inline`.
  */
 export interface InlineViewManifestEntry {
-    /** Discriminant for the production self-contained bundle shape. */
+    /** Discriminant for the embedded bundle shape. */
     kind: "inline";
     /**
      * Minified ES module source embedded in a `<script type="module">` by
@@ -49,14 +52,15 @@ export interface InlineViewManifestEntry {
     css: string;
 }
 /**
- * Dev manifest entry: Vite client-environment module URLs loaded by the
- * synthesized document (HMR / Fast Refresh).
+ * External view entry loaded through stylesheet and module URLs.
  *
- * Production builds emit the same shape with view-relative asset paths
- * (`assets/…`) served from `${basePath}/_mcp-use/views/<name>/`.
+ * Production builds use view-relative asset paths (`assets/…`) served from
+ * `${basePath}/_mcp-use/views/<name>/`, or full URLs after an
+ * `MCP_ASSETS_URL` rewrite. Dev uses origin-absolute Vite paths for HMR and
+ * Fast Refresh.
  */
 export interface ExternalViewManifestEntry {
-    /** Discriminant for the dev external-module shape. */
+    /** Discriminant for the external-module shape. */
     kind: "external";
     /**
      * Module entry path. Dev: origin-absolute Vite URL (`/…`). Production:
@@ -77,14 +81,14 @@ export interface ExternalViewManifestEntry {
     scripts?: string[];
 }
 /**
- * One entry in the primed views manifest.
+ * One entry in the primed views registry.
  *
- * Production builds emit {@link ExternalViewManifestEntry} with view-relative
- * asset paths; `mcp-use dev` emits origin-absolute Vite URLs.
+ * Production builds emit {@link ExternalViewManifestEntry} by default and
+ * {@link InlineViewManifestEntry} with `mcp-use build --inline`; `mcp-use dev`
+ * emits origin-absolute Vite URLs.
  */
 export type ViewManifestEntry = InlineViewManifestEntry | ExternalViewManifestEntry;
-/** Map of view name → manifest entry, primed via {@link registerViews}. */
+/** Map of view name → registry entry, primed via {@link registerViews}. */
 export interface ViewsManifest {
     [viewName: string]: ViewManifestEntry;
 }
-//# sourceMappingURL=types.d.ts.map