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

package/dist/inspector-shell.d.ts

@@ -34,6 +34,12 @@ export declare const DEFAULT_INSPECTOR_ASSETS_URL = "https://cdn.jsdelivr.net/np
  * strings and fragments are preserved.
  */
 export declare function inspectorStylesUrl(assetsUrl: string): string;
+/** True for the default jsDelivr `@mcp-use/inspector@*` CDN bundle URL. */
+export declare function isDefaultJsdelivrInspectorUrl(url: string): boolean;
+/** Append a per-request cache-bust query param for the default jsDelivr CDN URL. */
+export declare function withInspectorCacheBust(assetsUrl: string): string;
+/** True for inspector UI shell routes (SPA), excluding `/inspector/api/*`. */
+export declare function matchesInspectorShellPath(pathname: string, basePath: string): boolean;
 /** Inputs for {@link renderInspectorShell}. */
 export interface InspectorShellOptions {
     /** Server display name, used in the page title. */

package/dist/inspector-shell.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"inspector-shell.d.ts","sourceRoot":"","sources":["../src/inspector-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,+EAA2F,CAAC;AAErI;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAgE3E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,GAAG,SAAS,EACvC,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChD,YAAY,GAAG,SAAS,CAgC1B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAI1C"}
+{"version":3,"file":"inspector-shell.d.ts","sourceRoot":"","sources":["../src/inspector-shell.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,SAAS,CAAC;AAEpC;;;;;GAKG;AACH,eAAO,MAAM,4BAA4B,+EAA2F,CAAC;AAErI;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,2EAA2E;AAC3E,wBAAgB,6BAA6B,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAElE;AAED,oFAAoF;AACpF,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIhE;AAED,8EAA8E;AAC9E,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAOT;AAED,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,gEAAgE;IAChE,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAuBD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,MAAM,CAiE3E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,gBAAgB,GAAG,SAAS,EACvC,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAChD,YAAY,GAAG,SAAS,CA+B1B;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,IAAI,CAI1C"}

package/dist/middleware/cors.d.ts

@@ -0,0 +1,11 @@
+import type { CorsOptions } from "../config.js";
+import type { FetchMiddleware } from "../fetch-app.js";
+/**
+ * Fetch middleware that adds CORS headers to every response.
+ *
+ * @internal Wired from {@link MCPServer} when `ServerConfig.cors` is set.
+ */
+export declare function corsFetchMiddleware(options: CorsOptions): FetchMiddleware;
+/** Whether global CORS middleware owns response headers for view assets. */
+export declare function isGlobalCorsEnabled(cors: CorsOptions | undefined): boolean;
+//# sourceMappingURL=cors.d.ts.map

package/dist/middleware/cors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../../src/middleware/cors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAgFvD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,eAAe,CA0BzE;AAED,4EAA4E;AAC5E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,GAAG,SAAS,GAAG,OAAO,CAE1E"}

package/dist/middleware/mcp-middleware.d.ts

@@ -0,0 +1,135 @@
+import type { AuthInfo } from "@modelcontextprotocol/server";
+/**
+ * Context passed to every MCP middleware handler.
+ *
+ * `params` is mutable — middleware can modify params before calling `next()`
+ * and those changes will be visible to downstream middleware and the handler.
+ *
+ * `state` is a shared Map for passing arbitrary data across middleware in
+ * the same chain.
+ */
+export interface MiddlewareContext {
+    /** MCP method name, e.g. "tools/call", "tools/list", "resources/read" */
+    method: string;
+    /** JSON-RPC request params (mutable — mutations are passed downstream) */
+    params: Record<string, unknown>;
+    /** OAuth info extracted from JWT, present when OAuth is configured */
+    auth?: AuthInfo;
+    /** Shared state Map for passing data across middleware in the same request */
+    state: Map<string, unknown>;
+}
+/** Params shape for `tools/call` method */
+interface ToolsCallParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+    _meta?: Record<string, unknown>;
+}
+/** Params shape for `resources/read` method */
+interface ResourcesReadParams {
+    uri: string;
+    _meta?: Record<string, unknown>;
+}
+/** Params shape for `prompts/get` method */
+interface PromptsGetParams {
+    name: string;
+    arguments?: Record<string, string>;
+    _meta?: Record<string, unknown>;
+}
+/** Context with narrowed `params` for `tools/call` */
+export interface ToolsCallMiddlewareContext extends MiddlewareContext {
+    method: "tools/call";
+    params: ToolsCallParams & Record<string, unknown>;
+}
+/** Context with narrowed `params` for `resources/read` */
+export interface ResourcesReadMiddlewareContext extends MiddlewareContext {
+    method: "resources/read";
+    params: ResourcesReadParams & Record<string, unknown>;
+}
+/** Context with narrowed `params` for `prompts/get` */
+export interface PromptsGetMiddlewareContext extends MiddlewareContext {
+    method: "prompts/get";
+    params: PromptsGetParams & Record<string, unknown>;
+}
+/**
+ * Map from MCP middleware pattern strings to their narrowed context type.
+ * Used by `McpMiddlewareFnFor<P>` to infer the correct `ctx` parameter.
+ */
+export interface McpMiddlewarePatternMap {
+    "tools/call": ToolsCallMiddlewareContext;
+    "resources/read": ResourcesReadMiddlewareContext;
+    "prompts/get": PromptsGetMiddlewareContext;
+}
+/**
+ * A typed MCP middleware function whose `ctx` is narrowed based on the
+ * pattern string `P`. Falls back to the base `MiddlewareContext` for
+ * wildcard or unrecognized patterns.
+ */
+export type McpMiddlewareFnFor<P extends string> = P extends keyof McpMiddlewarePatternMap ? (ctx: McpMiddlewarePatternMap[P], next: () => Promise<unknown>) => Promise<unknown> : McpMiddlewareFn;
+/**
+ * A single MCP middleware function.
+ *
+ * Call `next()` to pass control to the next middleware (or handler).
+ * Return its result, or return a different value to override the response.
+ * Throw an error to reject the request.
+ */
+export type McpMiddlewareFn = (ctx: MiddlewareContext, next: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * Internal storage entry for a registered MCP middleware.
+ * The pattern is stored with the `mcp:` prefix already stripped.
+ * @internal
+ */
+export interface McpMiddlewareEntry {
+    /** Pattern after stripping "mcp:" — e.g. "tools/call", "tools/*", "*" */
+    pattern: string;
+    handler: McpMiddlewareFn;
+}
+/** Phase for MCP observer event listeners registered via `server.on()`. */
+export type McpEventPhase = "before" | "complete";
+/**
+ * Internal storage entry for a registered MCP observer event listener.
+ * @internal
+ */
+export interface McpEventListenerEntry {
+    pattern: string;
+    phase: McpEventPhase;
+    handler: McpEventListenerFn | McpCompleteEventListenerFn;
+}
+/** Read-only observer invoked before the MCP handler runs. */
+export type McpEventListenerFn = (ctx: Readonly<MiddlewareContext>) => void;
+/** Read-only observer invoked after the MCP handler completes. */
+export type McpCompleteEventListenerFn = (ctx: Readonly<MiddlewareContext>, result: unknown) => void;
+/**
+ * Test whether a registered middleware pattern matches a given MCP method.
+ *
+ * Matching rules:
+ * - `"*"` matches any method
+ * - `"tools/*"` prefix-matches any method starting with `"tools/"`
+ * - `"tools/call"` exact-matches only `"tools/call"`
+ */
+export declare function matchesPattern(pattern: string, method: string): boolean;
+/**
+ * Compose a middleware chain for a given MCP method invocation.
+ *
+ * Filters `entries` to those matching `method`, then builds a `next()` chain
+ * with `innerFn` at the center. Returns the outermost callable.
+ *
+ * Middleware executes in FIFO registration order (first registered = outermost).
+ */
+export declare function composeMiddleware(entries: McpMiddlewareEntry[], method: string, innerFn: () => Promise<unknown>): (ctx: MiddlewareContext) => Promise<unknown>;
+/** Build a read-only snapshot of middleware context for observer events. */
+export declare function freezeMiddlewareContext(ctx: MiddlewareContext): Readonly<MiddlewareContext>;
+/**
+ * Run before/complete observer listeners around a middleware chain.
+ *
+ * Listener throws are logged and do not fail the MCP request.
+ */
+export declare function runMcpOperation(middlewares: McpMiddlewareEntry[], events: McpEventListenerEntry[], method: string, ctx: MiddlewareContext, innerFn: () => Promise<unknown>): Promise<unknown>;
+/** Strip `mcp:` prefix and optional `:complete` suffix from observer patterns. */
+export declare function parseMcpPattern(raw: string): {
+    pattern: string;
+    phase: McpEventPhase;
+};
+/** Normalize middleware pattern strings (strip `mcp:` prefix). */
+export declare function normalizeMcpMiddlewarePattern(raw: string): string;
+export {};
+//# sourceMappingURL=mcp-middleware.d.ts.map

package/dist/middleware/mcp-middleware.d.ts.map

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

package/dist/mount-mcp.d.ts

@@ -44,8 +44,4 @@ export interface McpMount {
  * ```
  */
 export declare function createMcpMount(factory: McpServerFactory, options?: MountMcpOptions): McpMount;
-/**
- * @deprecated Use {@link createMcpMount} — returns the same mount without Hono.
- */
-export declare function mountMcp(factory: McpServerFactory, options?: MountMcpOptions): McpMount;
 //# sourceMappingURL=mount-mcp.d.ts.map

package/dist/mount-mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mount-mcp.d.ts","sourceRoot":"","sources":["../src/mount-mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACtB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAA8B,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAM/E,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,SAAS,CAAC;CACvD;AAED,wCAAwC;AACxC,MAAM,WAAW,QAAQ;IACvB,yDAAyD;IACzD,OAAO,EAAE,cAAc,CAAC;IACxB,uEAAuE;IACvE,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,eAAoB,GAC5B,QAAQ,CAiDV;AAED;;GAEG;AACH,wBAAgB,QAAQ,CACtB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,eAAoB,GAC5B,QAAQ,CAEV"}
+{"version":3,"file":"mount-mcp.d.ts","sourceRoot":"","sources":["../src/mount-mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,QAAQ,EACb,KAAK,uBAAuB,EAC5B,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACtB,MAAM,8BAA8B,CAAC;AAEtC,OAAO,EAA8B,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAM/E,0CAA0C;AAC1C,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,uBAAuB,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,QAAQ,GAAG,SAAS,CAAC;CACvD;AAED,wCAAwC;AACxC,MAAM,WAAW,QAAQ;IACvB,yDAAyD;IACzD,OAAO,EAAE,cAAc,CAAC;IACxB,uEAAuE;IACvE,KAAK,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,eAAoB,GAC5B,QAAQ,CAiDV"}

package/dist/oauth/index.js

@@ -8,7 +8,7 @@ import {
   oauthMetadataResponse,
   requireBearerAuth,
   verifyBearerToken
-} from "../chunk-SFI2T6TE.js";
+} from "../chunk-PMPGMSYA.js";
 import {
   oauthCustomProvider
 } from "../chunk-DPL7OEXC.js";

package/dist/{public-route-7IK5D7V7.js → public-route-26FUVRO5.js}

@@ -36,7 +36,7 @@ async function resolvePublicFilePath(publicRoot, subpath) {
   }
   return abs;
 }
-async function servePublicFile(diskPath) {
+async function servePublicFile(diskPath, options = {}) {
   const { createReadStream } = await import("fs");
   const { extname } = await import("path");
   const { Readable } = await import("stream");
@@ -49,7 +49,9 @@ async function servePublicFile(diskPath) {
     headers: {
       "Content-Type": contentType,
       "Cache-Control": "public, max-age=0, must-revalidate",
-      "Access-Control-Allow-Origin": "*"
+      ...options.deferCors !== true && {
+        "Access-Control-Allow-Origin": "*"
+      }
     }
   });
 }
@@ -57,4 +59,4 @@ export {
   resolvePublicFilePath,
   servePublicFile
 };
-//# sourceMappingURL=public-route-7IK5D7V7.js.map
+//# sourceMappingURL=public-route-26FUVRO5.js.map

package/dist/public-route-26FUVRO5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/views/public-route.ts"],"sourcesContent":["const PUBLIC_CONTENT_TYPES: Record<string, string> = {\n  \".css\": \"text/css\",\n  \".gif\": \"image/gif\",\n  \".html\": \"text/html\",\n  \".ico\": \"image/x-icon\",\n  \".jpeg\": \"image/jpeg\",\n  \".jpg\": \"image/jpeg\",\n  \".js\": \"application/javascript\",\n  \".json\": \"application/json\",\n  \".map\": \"application/json\",\n  \".png\": \"image/png\",\n  \".svg\": \"image/svg+xml\",\n  \".txt\": \"text/plain\",\n  \".webp\": \"image/webp\",\n  \".woff\": \"font/woff\",\n  \".woff2\": \"font/woff2\",\n};\n\n/**\n * Resolve a request subpath to an on-disk file under `publicRoot`, rejecting\n * path traversal.\n *\n * @param publicRoot - Absolute path to the `public/` directory on disk.\n * @param subpath - Request path after the `/public/` route prefix.\n * @returns Absolute file path when safe and present, otherwise `null`.\n *\n * @internal\n */\nexport async function resolvePublicFilePath(\n  publicRoot: string,\n  subpath: string\n): Promise<string | null> {\n  const { existsSync } = await import(\"node:fs\");\n  const { resolve, sep } = await import(\"node:path\");\n\n  if (subpath === \"\" || subpath.includes(\"..\") || subpath.includes(\"\\\\\")) {\n    return null;\n  }\n  const clean = subpath.replace(/^\\/+/, \"\");\n  if (clean === \"\" || clean.endsWith(\"/\")) {\n    return null;\n  }\n  const root = resolve(publicRoot);\n  const abs = resolve(root, clean);\n  if (abs !== root && !abs.startsWith(root + sep)) {\n    return null;\n  }\n  if (!existsSync(abs)) {\n    return null;\n  }\n  return abs;\n}\n\n/**\n * Serve one file from the project's `public/` directory.\n *\n * @param diskPath - Absolute path resolved by {@link resolvePublicFilePath}.\n * @param options - When `deferCors` is true, omit hardcoded `ACAO: *` so global\n *   {@link ServerConfig.cors} middleware owns CORS headers.\n * @returns A `Response` with `Cache-Control: public, max-age=0, must-revalidate`\n * and optionally `Access-Control-Allow-Origin: *` so cross-origin sandboxed\n * view iframes can load public files (module scripts and fetches use CORS mode).\n *\n * @internal\n */\nexport async function servePublicFile(\n  diskPath: string,\n  options: { deferCors?: boolean } = {}\n): Promise<Response> {\n  const { createReadStream } = await import(\"node:fs\");\n  const { extname } = await import(\"node:path\");\n  const { Readable } = await import(\"node:stream\");\n\n  const ext = extname(diskPath);\n  const contentType = PUBLIC_CONTENT_TYPES[ext] ?? \"application/octet-stream\";\n  const nodeStream = createReadStream(diskPath);\n  const webStream = Readable.toWeb(nodeStream) as ReadableStream;\n  return new Response(webStream, {\n    status: 200,\n    headers: {\n      \"Content-Type\": contentType,\n      \"Cache-Control\": \"public, max-age=0, must-revalidate\",\n      ...(options.deferCors !== true && {\n        \"Access-Control-Allow-Origin\": \"*\",\n      }),\n    },\n  });\n}\n"],"mappings":";AAAA,IAAM,uBAA+C;AAAA,EACnD,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,SAAS;AAAA,EACT,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,SAAS;AAAA,EACT,UAAU;AACZ;AAYA,eAAsB,sBACpB,YACA,SACwB;AACxB,QAAM,EAAE,WAAW,IAAI,MAAM,OAAO,IAAS;AAC7C,QAAM,EAAE,SAAS,IAAI,IAAI,MAAM,OAAO,MAAW;AAEjD,MAAI,YAAY,MAAM,QAAQ,SAAS,IAAI,KAAK,QAAQ,SAAS,IAAI,GAAG;AACtE,WAAO;AAAA,EACT;AACA,QAAM,QAAQ,QAAQ,QAAQ,QAAQ,EAAE;AACxC,MAAI,UAAU,MAAM,MAAM,SAAS,GAAG,GAAG;AACvC,WAAO;AAAA,EACT;AACA,QAAM,OAAO,QAAQ,UAAU;AAC/B,QAAM,MAAM,QAAQ,MAAM,KAAK;AAC/B,MAAI,QAAQ,QAAQ,CAAC,IAAI,WAAW,OAAO,GAAG,GAAG;AAC/C,WAAO;AAAA,EACT;AACA,MAAI,CAAC,WAAW,GAAG,GAAG;AACpB,WAAO;AAAA,EACT;AACA,SAAO;AACT;AAcA,eAAsB,gBACpB,UACA,UAAmC,CAAC,GACjB;AACnB,QAAM,EAAE,iBAAiB,IAAI,MAAM,OAAO,IAAS;AACnD,QAAM,EAAE,QAAQ,IAAI,MAAM,OAAO,MAAW;AAC5C,QAAM,EAAE,SAAS,IAAI,MAAM,OAAO,QAAa;AAE/C,QAAM,MAAM,QAAQ,QAAQ;AAC5B,QAAM,cAAc,qBAAqB,GAAG,KAAK;AACjD,QAAM,aAAa,iBAAiB,QAAQ;AAC5C,QAAM,YAAY,SAAS,MAAM,UAAU;AAC3C,SAAO,IAAI,SAAS,WAAW;AAAA,IAC7B,QAAQ;AAAA,IACR,SAAS;AAAA,MACP,gBAAgB;AAAA,MAChB,iBAAiB;AAAA,MACjB,GAAI,QAAQ,cAAc,QAAQ;AAAA,QAChC,+BAA+B;AAAA,MACjC;AAAA,IACF;AAAA,EACF,CAAC;AACH;","names":[]}

package/dist/react/hooks/use-files.d.ts

@@ -0,0 +1,25 @@
+import type { UseFilesResult } from "../types/file-types.js";
+/**
+ * Upload and download files through ChatGPT's optional `window.openai`
+ * extension.
+ *
+ * File handling is not part of the MCP Apps bridge. Always check
+ * `isSupported` before calling either action; unsupported calls reject with a
+ * descriptive error. The hook does not read or update ChatGPT widget state and
+ * does not make uploaded files model-visible as a side effect.
+ *
+ * The returned actions are referentially stable for the lifetime of the
+ * mounted runtime.
+ *
+ * @example
+ * ```tsx
+ * const { isSupported, upload, getDownloadUrl } = useFiles();
+ *
+ * if (!isSupported) return <p>File handling requires ChatGPT.</p>;
+ *
+ * const { fileId } = await upload(file);
+ * const { downloadUrl } = await getDownloadUrl({ fileId });
+ * ```
+ */
+export declare function useFiles(): UseFilesResult;
+//# sourceMappingURL=use-files.d.ts.map

package/dist/react/hooks/use-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-files.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-files.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,IAAI,cAAc,CAezC"}

package/dist/react/index.d.ts

@@ -16,6 +16,7 @@ export { ThemeProvider } from "./components/theme-provider.js";
 export { ViewControls } from "./components/view-controls.js";
 export { useCallTool, type CallToolHandle } from "./hooks/use-call-tool.js";
 export { useDisplayMode } from "./hooks/use-display-mode.js";
+export { useFiles } from "./hooks/use-files.js";
 export { useHostContext, type HostContextHandle, } from "./hooks/use-host-context.js";
 export { useOpenExternal } from "./hooks/use-open-external.js";
 export { useSendFollowUp } from "./hooks/use-send-follow-up.js";
@@ -24,6 +25,7 @@ export { useViewTheme } from "./hooks/use-view-theme.js";
 export { useToolContext, type ToolContextHandle, } from "./hooks/use-tool-context.js";
 export { useViewTool, type ViewToolDefinition } from "./hooks/use-view-tool.js";
 export { type DeepPartial, type Register, type RegisteredTools, } from "./types/register.js";
+export type { FileMetadata, UseFilesResult } from "./types/file-types.js";
 export type { DisplayMode, HostCapabilities, HostContext, HostInfo, SafeAreaInsets, } from "./types/host-types.js";
 export { ToolError, toolResultText, type CallToolResult, type CallToolSuccess, type ToolContextError, } from "./types/result-types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,aAAa,EACb,WAAW,EACX,KAAK,UAAU,GAChB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EACL,cAAc,EACd,KAAK,iBAAiB,GACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EACL,cAAc,EACd,KAAK,iBAAiB,GACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAChF,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,SAAS,EACT,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,aAAa,EACb,WAAW,EACX,KAAK,UAAU,GAChB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAC/D,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EACL,cAAc,EACd,KAAK,iBAAiB,GACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AACzD,OAAO,EACL,cAAc,EACd,KAAK,iBAAiB,GACvB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAChF,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAC;AAC7B,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC1E,YAAY,EACV,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,QAAQ,EACR,cAAc,GACf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,SAAS,EACT,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,GACtB,MAAM,yBAAyB,CAAC"}

package/dist/react/index.js

@@ -365,6 +365,19 @@ var defaultHostSnapshot = {
   isConnected: false,
   connectionError: void 0
 };
+var defaultFilesSnapshot = {
+  isSupported: false
+};
+function getChatGptFilesApi() {
+  if (typeof window === "undefined") return void 0;
+  return window.openai;
+}
+function resolveFilesSnapshot() {
+  const api = getChatGptFilesApi();
+  return {
+    isSupported: typeof api?.uploadFile === "function" && typeof api.getFileDownloadUrl === "function"
+  };
+}
 function resolveDisplayMode(hostContext) {
   return hostContext?.displayMode === "fullscreen" || hostContext?.displayMode === "pip" ? hostContext.displayMode : "inline";
 }
@@ -434,10 +447,12 @@ function createMcpAppRuntime(config, options) {
     displayMode: "inline",
     availableDisplayModes: ["inline"]
   };
+  let filesSnapshot = resolveFilesSnapshot();
   const toolChannel = createChannelStore();
   const hostChannel = createChannelStore();
   const themeChannel = createChannelStore();
   const displayChannel = createChannelStore();
+  const filesChannel = createChannelStore();
   function patchTool(patch) {
     if (!toolSnapshotChanged(toolSnapshot, patch)) {
       return;
@@ -613,6 +628,7 @@ function createMcpAppRuntime(config, options) {
     hostChannel.clear();
     themeChannel.clear();
     displayChannel.clear();
+    filesChannel.clear();
     toolSnapshot = { ...defaultToolSnapshot };
     hostSnapshot = { ...defaultHostSnapshot };
     themeSnapshot = "light";
@@ -620,6 +636,7 @@ function createMcpAppRuntime(config, options) {
       displayMode: "inline",
       availableDisplayModes: ["inline"]
     };
+    filesSnapshot = { ...defaultFilesSnapshot };
     if (activeRuntime === runtime) {
       activeRuntime = null;
     }
@@ -669,6 +686,30 @@ function createMcpAppRuntime(config, options) {
     const app2 = await connect();
     await app2.sendSizeChanged(params);
   }
+  async function uploadFile(file) {
+    if (disposed) {
+      throw new Error("View runtime has been disposed");
+    }
+    const api = getChatGptFilesApi();
+    if (!filesSnapshot.isSupported || typeof api?.uploadFile !== "function") {
+      throw new Error(
+        "[useFiles] File upload is not supported in this host. Check `isSupported` before calling `upload`. File operations are only available in the ChatGPT Apps SDK environment."
+      );
+    }
+    return api.uploadFile(file);
+  }
+  async function getFileDownloadUrl(file) {
+    if (disposed) {
+      throw new Error("View runtime has been disposed");
+    }
+    const api = getChatGptFilesApi();
+    if (!filesSnapshot.isSupported || typeof api?.getFileDownloadUrl !== "function") {
+      throw new Error(
+        "[useFiles] File download is not supported in this host. Check `isSupported` before calling `getDownloadUrl`. File operations are only available in the ChatGPT Apps SDK environment."
+      );
+    }
+    return api.getFileDownloadUrl(file);
+  }
   const runtime = {
     config,
     modelContextStore,
@@ -682,12 +723,16 @@ function createMcpAppRuntime(config, options) {
     getThemeSnapshot: () => themeSnapshot,
     subscribeDisplay: displayChannel.subscribe,
     getDisplaySnapshot: () => displaySnapshot,
+    subscribeFiles: filesChannel.subscribe,
+    getFilesSnapshot: () => filesSnapshot,
     getApp: () => disposed ? null : app,
     callServerTool,
     sendMessage,
     openLink,
     requestDisplayMode,
     sendSizeChanged,
+    uploadFile,
+    getFileDownloadUrl,
     registerViewTool
   };
   return runtime;
@@ -1257,6 +1302,24 @@ function useCallTool(nameOrRef) {
   return { callTool, data, error, isPending };
 }
 
+// src/react/hooks/use-files.ts
+import { useMemo, useSyncExternalStore as useSyncExternalStore5 } from "react";
+function useFiles() {
+  const runtime = useViewRuntime();
+  const { isSupported } = useSyncExternalStore5(
+    runtime.subscribeFiles,
+    runtime.getFilesSnapshot
+  );
+  return useMemo(
+    () => ({
+      isSupported,
+      upload: runtime.uploadFile,
+      getDownloadUrl: runtime.getFileDownloadUrl
+    }),
+    [runtime, isSupported]
+  );
+}
+
 // src/react/hooks/use-open-external.ts
 import { useCallback as useCallback2 } from "react";
 function useOpenExternal() {
@@ -1291,10 +1354,10 @@ function useSendSizeChanged() {
 }
 
 // src/react/hooks/use-view-theme.ts
-import { useSyncExternalStore as useSyncExternalStore5 } from "react";
+import { useSyncExternalStore as useSyncExternalStore6 } from "react";
 function useViewTheme() {
   const runtime = useViewRuntime();
-  return useSyncExternalStore5(runtime.subscribeTheme, runtime.getThemeSnapshot);
+  return useSyncExternalStore6(runtime.subscribeTheme, runtime.getThemeSnapshot);
 }
 
 // src/react/hooks/use-view-tool.ts
@@ -1406,6 +1469,7 @@ export {
   toolResultText,
   useCallTool,
   useDisplayMode,
+  useFiles,
   useHostContext,
   useOpenExternal,
   useSendFollowUp,