mcp-use 2.0.0-beta.2 → 2.0.0-beta.21

package/dist/react/runtime/view-runtime.d.ts

@@ -1,6 +1,7 @@
 import { App, type McpUiHostContext, type RegisteredAppTool } from "@modelcontextprotocol/ext-apps";
 import type { CallToolResult, ContentBlock } from "@modelcontextprotocol/server";
 import type { DisplayMode } from "../types/host-types.js";
+import type { FileMetadata } from "../types/file-types.js";
 import { type ToolContextError } from "../types/result-types.js";
 import { ModelContextStore } from "./model-context-store.js";
 import type { NormalizedViewConfig } from "./view-config.js";
@@ -64,6 +65,18 @@ export interface DisplaySnapshot {
      */
     availableDisplayModes: readonly DisplayMode[];
 }
+/**
+ * ChatGPT file-extension channel snapshot.
+ *
+ * This channel deliberately represents only the optional file APIs used by
+ * `useFiles`; the runtime does not mirror other `window.openai` globals.
+ *
+ * @internal
+ */
+export interface FilesSnapshot {
+    /** Whether both upload and temporary-download-url helpers are available. */
+    isSupported: boolean;
+}
 /**
  * Parameters for {@link McpAppRuntime.callServerTool}.
  *
@@ -157,6 +170,10 @@ export interface McpAppRuntime {
      * negotiated `availableDisplayModes` change).
      */
     getDisplaySnapshot(): DisplaySnapshot;
+    /** Subscribe to ChatGPT file-extension availability changes. */
+    subscribeFiles(listener: Listener): () => void;
+    /** Current ChatGPT file-extension snapshot. */
+    getFilesSnapshot(): FilesSnapshot;
     /** Runtime-owned guest {@link App}, or `null` after disposal. */
     getApp(): App | null;
     /** Call a server tool through the host. */
@@ -169,6 +186,12 @@ export interface McpAppRuntime {
     requestDisplayMode(params: RequestDisplayModeParams): Promise<void>;
     /** Notify the host of a size change. */
     sendSizeChanged(params: SizeChangedParams): Promise<void>;
+    /** Upload a file through ChatGPT's optional file extension. */
+    uploadFile(file: File): Promise<FileMetadata>;
+    /** Request a temporary download URL through ChatGPT's file extension. */
+    getFileDownloadUrl(file: FileMetadata): Promise<{
+        downloadUrl: string;
+    }>;
     /**
      * Register a view tool, performing the empty-handler → registry handoff on
      * the first call. Must remain synchronous relative to the handoff.

package/dist/react/runtime/view-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"view-runtime.d.ts","sourceRoot":"","sources":["../../../src/react/runtime/view-runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"view-runtime.d.ts","sourceRoot":"","sources":["../../../src/react/runtime/view-runtime.ts"],"names":[],"mappings":"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"}

package/dist/react/types/file-types.d.ts

@@ -0,0 +1,16 @@
+/** Opaque file reference returned by {@link useFiles}. */
+export type FileMetadata = {
+    fileId: string;
+};
+/** Value returned by {@link useFiles}. */
+export interface UseFilesResult {
+    /** Whether the ChatGPT file upload and download extensions are available. */
+    isSupported: boolean;
+    /** Upload a file through ChatGPT. */
+    upload(file: File): Promise<FileMetadata>;
+    /** Request a temporary download URL for an uploaded file. */
+    getDownloadUrl(file: FileMetadata): Promise<{
+        downloadUrl: string;
+    }>;
+}
+//# sourceMappingURL=file-types.d.ts.map

package/dist/react/types/file-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-types.d.ts","sourceRoot":"","sources":["../../../src/react/types/file-types.ts"],"names":[],"mappings":"AAAA,0DAA0D;AAC1D,MAAM,MAAM,YAAY,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE9C,0CAA0C;AAC1C,MAAM,WAAW,cAAc;IAC7B,6EAA6E;IAC7E,WAAW,EAAE,OAAO,CAAC;IACrB,qCAAqC;IACrC,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC1C,6DAA6D;IAC7D,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACtE"}

package/dist/react/types/register.d.ts

@@ -1,5 +1,5 @@
 import type { ToolRef } from "../../tools.js";
-/** Augmented by the project's `register.d.ts`; empty by default. */
+/** Augmented by the project's `mcp-env.d.ts`; empty by default. */
 export interface Register {
 }
 type RegisteredToolsModule = Register extends {

package/dist/react/types/register.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/react/types/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,oEAAoE;AAEpE,MAAM,WAAW,QAAQ;CAAG;AAE5B,KAAK,qBAAqB,GAAG,QAAQ,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC,CAAA;CAAE,GAC5D,CAAC,GACD,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAEzB,KAAK,eAAe,CAAC,CAAC,IAAI;KAEvB,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GACpD,CAAC,GACD,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAE9B,GAAG,EACH,MAAM,CAAC,EACP,MAAM,CAAC,CACR,GACG;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,MAAM,EAAE,CAAC,CAAA;KAAE,GACvB,KAAK;CACV,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,eAAe,CAAC,qBAAqB,CAAC,CAAC;AAErE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAC9C,WAAW,CAAC,CAAC,CAAC,EAAE,GAChB,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACtC,CAAC,CAAC"}
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/react/types/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AAE9C,mEAAmE;AAEnE,MAAM,WAAW,QAAQ;CAAG;AAE5B,KAAK,qBAAqB,GAAG,QAAQ,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC,CAAA;CAAE,GAC5D,CAAC,GACD,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAEzB,KAAK,eAAe,CAAC,CAAC,IAAI;KAEvB,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GACpD,CAAC,GACD,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAE9B,GAAG,EACH,MAAM,CAAC,EACP,MAAM,CAAC,CACR,GACG;QAAE,KAAK,EAAE,CAAC,CAAC;QAAC,MAAM,EAAE,CAAC,CAAA;KAAE,GACvB,KAAK;CACV,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,eAAe,CAAC,qBAAqB,CAAC,CAAC;AAErE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,GAC9C,WAAW,CAAC,CAAC,CAAC,EAAE,GAChB,CAAC,SAAS,MAAM,GACd;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,GACtC,CAAC,CAAC"}

package/dist/resource-completion.d.ts

@@ -0,0 +1,12 @@
+import type { CompleteResourceTemplateCallback } from "@modelcontextprotocol/server";
+import type { ResourceTemplateCompleter } from "./resources.js";
+/**
+ * Convert public static and callback completions to the SDK callback map.
+ *
+ * @param completions - Public completion providers keyed by template variable.
+ * @returns The callback-only map required by the official SDK.
+ *
+ * @internal
+ */
+export declare function normalizeCompletions(completions: Readonly<Record<string, ResourceTemplateCompleter | undefined>>): Record<string, CompleteResourceTemplateCallback>;
+//# sourceMappingURL=resource-completion.d.ts.map

package/dist/resource-completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-completion.d.ts","sourceRoot":"","sources":["../src/resource-completion.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,8BAA8B,CAAC;AAGrF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAEhE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC,CAAC,GAC3E,MAAM,CAAC,MAAM,EAAE,gCAAgC,CAAC,CAYlD"}

package/dist/resources.d.ts

@@ -1,4 +1,4 @@
-import type { ReadResourceResult } from "@modelcontextprotocol/server";
+import type { Annotations, CompleteResourceTemplateCallback, MetaObject, ReadResourceResult } from "@modelcontextprotocol/server";
 import type { RequestContext } from "./context.js";
 /** Declares a static resource at a fixed URI. First argument to {@link MCPServer.resource}. */
 export interface ResourceDefinition {
@@ -15,6 +15,16 @@ export interface ResourceDefinition {
      * own `mimeType` on the wire — set it in the callback's result.
      */
     mimeType?: string;
+    /** Standard MCP hints describing the resource's audience and presentation. */
+    annotations?: Annotations;
+    /**
+     * Extension metadata advertised on this resource's `resources/list`
+     * descriptor. Use vendor-namespaced keys for custom data.
+     *
+     * This value is not copied into `resources/read` content entries; content
+     * metadata must be returned by the callback on each entry's own `_meta`.
+     */
+    _meta?: MetaObject;
 }
 /**
  * Resource read callback. Returns the SDK's raw {@link ReadResourceResult};
@@ -28,18 +38,63 @@ export interface ResourceDefinition {
  * ```
  */
 export type ResourceCallback<TUser = never, HasOAuth extends boolean = false> = (uri: URL, ctx: RequestContext<TUser, HasOAuth>) => ReadResourceResult | Promise<ReadResourceResult>;
-/** Declares a parameterized resource matched by URI template. First argument to {@link MCPServer.resourceTemplate}. */
-export interface ResourceTemplateDefinition {
+/**
+ * A resource-template variable completer accepted by
+ * {@link MCPServer.resourceTemplate}.
+ *
+ * Static values are matched case-insensitively against the beginning of the
+ * current value. Callback completions use the official SDK callback shape and
+ * may inspect the other resolved string arguments in its optional context.
+ * The SDK limits wire results to 100 values and derives `total` and `hasMore`
+ * from the returned array.
+ */
+export type ResourceTemplateCompleter = readonly string[] | CompleteResourceTemplateCallback;
+/**
+ * Per-variable completion map inferred from an RFC 6570 URI template.
+ *
+ * Literal templates accept only variables declared by the template. A
+ * widened `string` template accepts arbitrary string keys because its
+ * variables cannot be known at compile time.
+ *
+ * @typeParam TUriTemplate - URI template whose variables become map keys.
+ */
+export type ResourceTemplateCompletions<TUriTemplate extends string> = string extends TUriTemplate ? Partial<Record<string, ResourceTemplateCompleter>> : Partial<Record<ExtractTemplateVariables<TUriTemplate>, ResourceTemplateCompleter>>;
+/**
+ * Declares a parameterized resource matched by URI template.
+ *
+ * @typeParam TUriTemplate - Literal URI template used to infer read variables
+ * and completion keys.
+ */
+export interface ResourceTemplateDefinition<TUriTemplate extends string = string> {
     /** Template display name. */
     name: string;
     /** RFC 6570 URI template with variables, e.g. `"db://users/{id}"`. */
-    uriTemplate: string;
+    uriTemplate: TUriTemplate;
     /** Human-readable title (falls back to `name`). */
     title?: string;
     /** Human-readable description. */
     description?: string;
     /** MIME type of the content. */
     mimeType?: string;
+    /** Standard MCP hints describing resources produced by this template. */
+    annotations?: Annotations;
+    /**
+     * Extension metadata advertised on this template's
+     * `resources/templates/list` descriptor. Use vendor-namespaced keys for
+     * custom data.
+     *
+     * This value is not copied into `resources/read` content entries; content
+     * metadata must be returned by the callback on each entry's own `_meta`.
+     */
+    _meta?: MetaObject;
+    /**
+     * Optional completion providers keyed by URI-template variable.
+     *
+     * Static arrays use case-insensitive prefix matching. Dynamic callbacks may
+     * be synchronous or asynchronous and receive the current value plus the
+     * official completion context containing already-resolved arguments.
+     */
+    complete?: ResourceTemplateCompletions<TUriTemplate>;
 }
 /** Strip a leading RFC 6570 operator (`+`, `#`, `.`, `/`, `;`, `?`, `&`) from a template expression. */
 type StripOperator<E extends string> = E extends `${"+" | "#" | "." | "/" | ";" | "?" | "&"}${infer Rest}` ? Rest : E;

package/dist/resources.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../src/resources.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,gCAAgC,EAChC,UAAU,EACV,kBAAkB,EACnB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,+FAA+F;AAC/F,MAAM,WAAW,kBAAkB;IACjC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,CAC1B,KAAK,GAAG,KAAK,EACb,QAAQ,SAAS,OAAO,GAAG,KAAK,IAC9B,CACF,GAAG,EAAE,GAAG,EACR,GAAG,EAAE,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,KACjC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,MAAM,yBAAyB,GACjC,SAAS,MAAM,EAAE,GACjB,gCAAgC,CAAC;AAErC;;;;;;;;GAQG;AACH,MAAM,MAAM,2BAA2B,CAAC,YAAY,SAAS,MAAM,IACjE,MAAM,SAAS,YAAY,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAAC,GAClD,OAAO,CACL,MAAM,CACJ,wBAAwB,CAAC,YAAY,CAAC,EACtC,yBAAyB,CAC1B,CACF,CAAC;AAER;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B,CACzC,YAAY,SAAS,MAAM,GAAG,MAAM;IAEpC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,WAAW,EAAE,YAAY,CAAC;IAC1B,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gCAAgC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yEAAyE;IACzE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;OAOG;IACH,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,2BAA2B,CAAC,YAAY,CAAC,CAAC;CACtD;AAED,wGAAwG;AACxG,KAAK,aAAa,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAC7C,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GACH,GAAG,GAAG,MAAM,IAAI,EAAE,GAClB,IAAI,GACJ,CAAC,CAAC;AAEN,0FAA0F;AAC1F,KAAK,aAAa,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,IAAI,GAAG,GAC7D,IAAI,GACJ,CAAC,SAAS,GAAG,MAAM,IAAI,IAAI,MAAM,EAAE,GACjC,IAAI,GACJ,CAAC,CAAC;AAER,uFAAuF;AACvF,KAAK,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI,CAAC,SAAS,GAAG,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,GAC3E,aAAa,CAAC,IAAI,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,GAC1C,aAAa,CAAC,CAAC,CAAC,CAAC;AAErB,sGAAsG;AACtG,KAAK,wBAAwB,CAAC,CAAC,SAAS,MAAM,IAC5C,CAAC,SAAS,GAAG,MAAM,IAAI,MAAM,IAAI,IAAI,MAAM,IAAI,EAAE,GAC7C,cAAc,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,GAAG,wBAAwB,CAAC,IAAI,CAAC,GACpE,KAAK,CAAC;AAEZ,uDAAuD;AACvD,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,SAAS;IAC7C,WAAW,EAAE,MAAM,CAAC,SAAS,MAAM,CAAC;CACrC,GACG,MAAM,SAAS,CAAC,GACd,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,GACrC;KAAG,CAAC,IAAI,wBAAwB,CAAC,CAAC,CAAC,GAAG,qBAAqB;CAAE,GAC/D,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAC;AAE1C,+EAA+E;AAC/E,MAAM,MAAM,wBAAwB,CAClC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,EAC/C,KAAK,GAAG,KAAK,EACb,QAAQ,SAAS,OAAO,GAAG,KAAK,IAC9B,CACF,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,OAAO,EACf,GAAG,EAAE,cAAc,CAAC,KAAK,EAAE,QAAQ,CAAC,KACjC,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC"}

package/dist/server.d.ts

@@ -1,8 +1,13 @@
 import { type ServerEventBus } from "@modelcontextprotocol/server";
+import { type ServerBranding } from "./branding.js";
 import { type ServerConfig } from "./config.js";
+import { type FrameworkHandler } from "./fetch-app.js";
+import { type McpEventListenerFnFor, type McpEventPattern, type McpMiddlewareFnFor, type McpMiddlewarePattern } from "./middleware/mcp-middleware.js";
+import type { NodeRequestHandler } from "./node-bridge.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;
@@ -67,6 +72,22 @@ export declare class MCPServer<TUser = never> {
      * can build the endpoint and inspector URLs without assuming the default.
      */
     get basePath(): string;
+    /**
+     * 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 inspector/view layers.
+     *
+     * @example
+     * ```ts
+     * if (server.branding.favicon) {
+     *   console.log("Browser favicon: /favicon.ico");
+     * }
+     * ```
+     */
+    get branding(): ServerBranding;
     /**
      * Register a tool. Input is validated against `inputSchema` before the callback
      * runs; results carrying `structuredContent` are type-checked against
@@ -77,9 +98,9 @@ export declare class MCPServer<TUser = never> {
      */
     tool<const T extends ToolDefinition>(definition: T, callback: ToolCallback<InferToolInput<T>, InferToolOutput<T>, TUser, HasOAuth<TUser>>): 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
@@ -119,12 +140,58 @@ 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>>): 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;
+    /**
+     * 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.
@@ -149,7 +216,54 @@ export declare class MCPServer<TUser = never> {
      */
     getHandler(options?: {
         bus?: ServerEventBus;
-    }): (request: Request) => Promise<Response>;
+    }): FrameworkHandler;
+    /**
+     * Node `(req, res) => void` handler for composing with an existing
+     * `http.Server`. Uses the same internal `toNodeHandler` bridge as
+     * {@link MCPServer.listen}; MCPServer users do not need to import
+     * `mcp-use/node`.
+     *
+     * @example
+     * ```ts
+     * import { createServer } from "node:http";
+     * const httpServer = createServer(await server.getNodeHandler());
+     * httpServer.listen(3000);
+     * ```
+     */
+    getNodeHandler(): Promise<NodeRequestHandler>;
+    /**
+     * Register MCP operation middleware that intercepts JSON-RPC dispatch.
+     *
+     * Patterns use an `mcp:` prefix (for example `mcp:tools/call`, `mcp:*`).
+     * 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.
+     *
+     * @example
+     * ```ts
+     * 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>): 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
+     * server.on("mcp:tools/call", (ctx) => {
+     *   metrics.increment("tools.call", { tool: ctx.params.name });
+     * });
+     * ```
+     */
+    on<P extends McpEventPattern>(pattern: P, handler: McpEventListenerFnFor<P>): this;
     /**
      * Publish a tools-list change to v2 clients with active subscriptions.
      *
@@ -192,9 +306,8 @@ export declare class MCPServer<TUser = never> {
      * Serve over HTTP on Node. Pass port `0` for an ephemeral port.
      *
      * 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"`;
+     * 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).
      *

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/tools.d.ts

@@ -1,19 +1,18 @@
-import type { CallToolResult, InputRequiredResult, StandardSchemaWithJSON, ToolAnnotations } from "@modelcontextprotocol/server";
+import type { CallToolResult, InputRequiredResult, MetaObject, StandardSchemaWithJSON, ToolAnnotations } from "@modelcontextprotocol/server";
 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 +21,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 +69,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

package/dist/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/dist/views/constants.d.ts

@@ -11,7 +11,7 @@ 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

@@ -0,0 +1,37 @@
+import type { McpUiResourceCsp } from "@modelcontextprotocol/ext-apps";
+import type { ViewResourceFacts } from "./types.js";
+type CspCategory = "connectDomains" | "resourceDomains" | "frameDomains" | "baseUriDomains";
+/** Parse a comma-separated env var into trimmed non-empty domain strings. */
+export declare function parseDomainList(raw: string | undefined): string[];
+/** Domains from `CSP_URLS` (shortcut for all categories). */
+export declare function readCspUrlsShortcut(): string[];
+/** Per-category env override, or `CSP_URLS` when the category var is unset. */
+export declare function readEnvDomainsForCategory(category: CspCategory): string[];
+/**
+ * Merge domain lists: earlier segments win on duplicate (higher priority).
+ */
+export declare function mergeDomainLists(...segments: string[][]): string[];
+/**
+ * Resolved origins and flags used when merging author, env, and MCP CSP domains.
+ *
+ * @internal
+ */
+export interface BuildCspOptions {
+    /** Public server origin from `MCP_URL` or forwarded request headers. */
+    serverOrigin: string;
+    /** Assets origin derived from `MCP_ASSETS_URL` or the server origin. */
+    assetsOrigin: string;
+    /** When false, server origin is appended to resourceDomains (same-origin assets). */
+    explicitAssetsBase: boolean;
+    /** When true, append the server origin's websocket variant for Vite HMR. */
+    hmrWs?: boolean;
+}
+/**
+ * Build final `_meta.ui.csp` from author facts, env vars, and MCP auto-append.
+ *
+ * Precedence (high → low): author → env (`CSP_*_DOMAINS` or `CSP_URLS`) →
+ * MCP auto-append (lowest).
+ */
+export declare function buildMergedResourceCsp(authorFacts: ViewResourceFacts | undefined, options: BuildCspOptions): McpUiResourceCsp;
+export {};
+//# sourceMappingURL=csp-env.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"csp-env.d.ts","sourceRoot":"","sources":["../../src/views/csp-env.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAEvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,KAAK,WAAW,GACZ,gBAAgB,GAChB,iBAAiB,GACjB,cAAc,GACd,gBAAgB,CAAC;AASrB,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,EAAE,CAQjE;AAaD,6DAA6D;AAC7D,wBAAgB,mBAAmB,IAAI,MAAM,EAAE,CAE9C;AAED,+EAA+E;AAC/E,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,EAAE,CAMzE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,CAYlE;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,YAAY,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,kBAAkB,EAAE,OAAO,CAAC;IAC5B,4EAA4E;IAC5E,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAYD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,iBAAiB,GAAG,SAAS,EAC1C,OAAO,EAAE,eAAe,GACvB,gBAAgB,CAgDlB"}

package/dist/views/document.d.ts

@@ -1,35 +1,52 @@
 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 `/`.
  */
 export declare function resolveAssetUrl(assetPath: string, origin: string): string;
+/**
+ * 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 / registry key.
+ */
+export declare function viewAssetsBasePath(basePath: string, viewName: string): string;
+/**
+ * Resolve a production or dev external asset path to an absolute URL.
+ *
+ * @param assetPath - Full CDN URL, origin-absolute dev path (`/…`), or
+ *   view-relative production path (`assets/…`).
+ * @param assetsBase - Assets URL prefix (origin + optional path).
+ * @param basePath - MCP mount prefix.
+ * @param viewName - View directory / registry key (required for view-relative paths).
+ */
+export declare function resolveExternalAssetUrl(assetPath: string, assetsBase: string, basePath: string, viewName: string): string;
 /**
  * Resolve the absolute URL prefix for the project's `public/` directory.
  *
- * @param origin - Request-resolved public origin.
+ * @param assetsBase - Assets URL prefix (origin + optional path).
  * @param basePath - MCP mount prefix (e.g. `/mcp`).
  * @returns Absolute prefix with trailing slash.
  */
-export declare function resolvePublicBase(origin: string, basePath: string): string;
+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: "inline"`) embeds JS and CSS directly so a srcdoc iframe
- * boots with zero network fetches for the view bundle. Dev
- * (`kind: "external"`) loads Vite module URLs for HMR.
+ * Production (`kind: "external"`) loads built assets over HTTP with absolute
+ * URLs. Legacy `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 origin - Request-resolved public origin for absolute asset URLs.
+ * @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 / registry key (required for production external paths).
  */
-export declare function synthesizeViewDocument(entry: ViewManifestEntry, origin: string, basePath: string): string;
+export declare function synthesizeViewDocument(entry: ViewManifestEntry, assetsBase: string, basePath: string, viewName?: string): string;
 //# sourceMappingURL=document.d.ts.map

package/dist/views/document.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/views/document.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAOzE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE1E;AAgCD;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GACf,MAAM,CAuDR"}
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../../src/views/document.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAOzE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAE7E;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,MAAM,CAYR;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,MAAM,CAER;AAoCD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,iBAAiB,EACxB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,GAChB,MAAM,CAoER"}