mcp-use 2.0.0-beta.63 → 2.0.0-beta.64

package/dist/oauth/keycloak.d.ts

@@ -1,20 +1,37 @@
+/**
+ * Verify Keycloak access tokens for an mcp-use resource server.
+ *
+ * @packageDocumentation
+ */
 import { type OAuthProvider, type OAuthResourceOptions } from "./provider.js";
 /** Verified Keycloak user and role claims exposed to authenticated MCP callbacks. */
 export interface KeycloakOAuthUser {
+    /** Keycloak subject identifier. */
     id: string;
+    /** Primary email address, when included in the access token. */
     email?: string;
+    /** Display name, when included in the access token. */
     name?: string;
+    /** Preferred username, when included in the access token. */
     preferredUsername?: string;
+    /** Given name, when included in the access token. */
     givenName?: string;
+    /** Family name, when included in the access token. */
     familyName?: string;
+    /** Whether Keycloak has verified {@link KeycloakOAuthUser.email}. */
     emailVerified?: boolean;
+    /** Realm roles from `realm_access.roles`. */
     roles: string[];
+    /** Unmodified `realm_access` claim, when present. */
     realmAccess?: Record<string, unknown>;
+    /** Unmodified `resource_access` claim, when present. */
     resourceAccess?: Record<string, unknown>;
 }
 /** Configures Keycloak JWT verification and protected-resource metadata. */
 export interface KeycloakOAuthProviderOptions extends OAuthResourceOptions {
+    /** Base URL of the Keycloak server. */
     serverUrl: URL | string;
+    /** Keycloak realm that issues accepted access tokens. */
     realm: string;
 }
 /**
@@ -22,5 +39,16 @@ export interface KeycloakOAuthProviderOptions extends OAuthResourceOptions {
  *
  * @param options - Keycloak server URL, realm, and resource-server settings.
  * @returns A provider that rejects tokens not issued for the resolved MCP resource.
+ * @throws A `TypeError` if `serverUrl` or `realm` is invalid.
+ *
+ * @example
+ * ```ts
+ * import { oauthKeycloakProvider } from "mcp-use/oauth/keycloak";
+ *
+ * const oauth = oauthKeycloakProvider({
+ *   serverUrl: "https://keycloak.example.com",
+ *   realm: "production",
+ * });
+ * ```
  */
 export declare function oauthKeycloakProvider(options: KeycloakOAuthProviderOptions): OAuthProvider<KeycloakOAuthUser>;

package/dist/oauth/provider.d.ts

@@ -30,7 +30,7 @@ export interface CustomOAuthProviderOptions<TUser> extends OAuthResourceOptions
     /** Maps verified SDK auth information into mcp-use callback identity data. */
     mapAuthInfo: (authInfo: OAuthAuthInfo) => OAuthExtra<TUser>;
 }
-/** OAuth resource-server provider accepted by {@link MCPServer}. */
+/** OAuth resource-server provider accepted by the mcp-use server constructor. */
 export type OAuthProvider<TUser> = CustomOAuthProviderOptions<TUser>;
 /**
  * Creates an OAuth provider backed by an external authorization server.
@@ -38,5 +38,21 @@ export type OAuthProvider<TUser> = CustomOAuthProviderOptions<TUser>;
  * @typeParam TUser - Application user type exposed to authenticated callbacks.
  * @param options - Token verification, discovery metadata, and identity mapping.
  * @returns A provider for an OAuth-enabled MCP server.
+ * @throws A `TypeError` if provider metadata or resource settings are invalid.
+ *
+ * @example
+ * ```ts
+ * import { oauthCustomProvider } from "mcp-use/oauth";
+ *
+ * const oauth = oauthCustomProvider({
+ *   createTokenVerifier: (resource) => tokenVerifierFor(resource),
+ *   oauthMetadata,
+ *   mapAuthInfo: (authInfo) => ({
+ *     user: { id: authInfo.clientId },
+ *     payload: {},
+ *     permissions: [],
+ *   }),
+ * });
+ * ```
  */
 export declare function oauthCustomProvider<TUser>(options: CustomOAuthProviderOptions<TUser>): OAuthProvider<TUser>;

package/dist/oauth/supabase.d.ts

@@ -1,28 +1,52 @@
+/**
+ * Verify Supabase access tokens for an mcp-use resource server.
+ *
+ * @packageDocumentation
+ */
 import { type OAuthProvider, type OAuthResourceOptions } from "./provider.js";
 /** Verified Supabase user claims exposed to authenticated MCP callbacks. */
 export interface SupabaseOAuthUser {
+    /** Supabase user identifier. */
     id: string;
+    /** Primary email address, when included in the access token. */
     email?: string;
+    /** Display name from `user_metadata.name`. */
     name?: string;
+    /** Full name from `user_metadata.full_name`. */
     fullName?: string;
+    /** Username from `user_metadata.username`. */
     username?: string;
+    /** Profile image URL from `user_metadata.avatar_url`. */
     avatarUrl?: string;
+    /** Supabase Postgres role from the access token. */
     role?: string;
+    /** Authenticator assurance level for the session. */
     aal?: string;
+    /** Authentication methods used for the session. */
     amr: SupabaseAmr[];
+    /** Supabase session identifier. */
     sessionId?: string;
 }
 /** A verified Supabase authentication-method reference. */
 export interface SupabaseAmr {
+    /** Authentication method name, such as `password` or `totp`. */
     method: string;
+    /** Unix timestamp at which the authentication method was completed. */
     timestamp?: number;
 }
 /** Configures Supabase JWT verification and protected-resource metadata. */
 export interface SupabaseOAuthProviderOptions extends OAuthResourceOptions {
+    /** Supabase project identifier used to derive `supabaseUrl`. */
     projectId?: string;
+    /** Full Supabase project URL. Takes precedence over `projectId`. */
     supabaseUrl?: URL | string;
+    /** Legacy HS256 JWT secret. Omit to verify ES256 tokens against project JWKS. */
     jwtSecret?: string;
-    /** Expected access-token audience. Defaults to Supabase's `authenticated`. */
+    /**
+     * Expected access-token audience.
+     *
+     * @defaultValue `"authenticated"`
+     */
     audience?: string;
 }
 /**
@@ -30,5 +54,16 @@ export interface SupabaseOAuthProviderOptions extends OAuthResourceOptions {
  *
  * @param options - Supabase project or URL, optional JWT secret/audience, and resource-server settings.
  * @returns A provider that rejects tokens without a valid configured Supabase signature and issuer.
+ * @throws A `TypeError` if project settings are invalid, `audience` is empty,
+ * or `jwtSecret` is shorter than 32 bytes.
+ *
+ * @example
+ * ```ts
+ * import { oauthSupabaseProvider } from "mcp-use/oauth/supabase";
+ *
+ * const oauth = oauthSupabaseProvider({
+ *   projectId: "example-project",
+ * });
+ * ```
  */
 export declare function oauthSupabaseProvider(options: SupabaseOAuthProviderOptions): OAuthProvider<SupabaseOAuthUser>;

package/dist/oauth/workos.d.ts

@@ -1,20 +1,37 @@
+/**
+ * Verify WorkOS AuthKit access tokens for an mcp-use resource server.
+ *
+ * @packageDocumentation
+ */
 import { type OAuthProvider, type OAuthResourceOptions } from "./provider.js";
 /** Verified WorkOS user and organization claims exposed to authenticated MCP callbacks. */
 export interface WorkOSOAuthUser {
+    /** WorkOS subject identifier. */
     id: string;
+    /** Primary email address, when included in the access token. */
     email?: string;
+    /** Whether WorkOS has verified {@link WorkOSOAuthUser.email}. */
     emailVerified?: boolean;
+    /** Display name, when included in the access token. */
     name?: string;
+    /** Preferred username, when included in the access token. */
     preferredUsername?: string;
+    /** Given name, when included in the access token. */
     firstName?: string;
+    /** Family name, when included in the access token. */
     lastName?: string;
+    /** Profile image URL, when included in the access token. */
     picture?: string;
+    /** Roles from the access token's `roles` claim. */
     roles: string[];
+    /** Active WorkOS organization identifier. */
     organizationId?: string;
+    /** WorkOS session identifier. */
     sessionId?: string;
 }
 /** Configures WorkOS JWT verification and protected-resource metadata. */
 export interface WorkOSOAuthProviderOptions extends OAuthResourceOptions {
+    /** AuthKit subdomain, with or without the `https://` scheme. */
     subdomain: string;
 }
 /**
@@ -22,5 +39,15 @@ export interface WorkOSOAuthProviderOptions extends OAuthResourceOptions {
  *
  * @param options - WorkOS AuthKit origin and resource-server settings.
  * @returns A provider that rejects tokens not issued for the resolved MCP resource.
+ * @throws A `TypeError` if `subdomain` is empty or uses a non-HTTPS URL.
+ *
+ * @example
+ * ```ts
+ * import { oauthWorkOSProvider } from "mcp-use/oauth/workos";
+ *
+ * const oauth = oauthWorkOSProvider({
+ *   subdomain: "example.authkit.app",
+ * });
+ * ```
  */
 export declare function oauthWorkOSProvider(options: WorkOSOAuthProviderOptions): OAuthProvider<WorkOSOAuthUser>;

package/dist/react/components/error-boundary.d.ts

@@ -1,5 +1,6 @@
 import React from "react";
 interface ErrorBoundaryProps {
+    /** View subtree protected by the boundary. */
     children: React.ReactNode;
     /** Custom fallback when an error is caught. */
     fallback?: React.ReactNode | ((error: Error) => React.ReactNode);
@@ -15,11 +16,13 @@ export declare class ErrorBoundary extends React.Component<ErrorBoundaryProps, {
     error: Error | null;
 }> {
     constructor(props: ErrorBoundaryProps);
+    /** Records a render failure for the fallback render pass. */
     static getDerivedStateFromError(error: Error): {
         hasError: boolean;
         error: Error;
     };
     componentDidCatch(error: Error, errorInfo: React.ErrorInfo): void;
+    /** Renders the child tree or the configured error fallback. */
     render(): string | number | bigint | boolean | React.JSX.Element | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | Iterable<React.ReactNode> | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | React.ReactPortal | null | undefined> | null | undefined;
 }
 export {};

package/dist/react/components/theme-provider.d.ts

@@ -2,14 +2,15 @@ import React from "react";
 /**
  * Applies host theme, style variables, and fonts to the document root.
  *
- * Subscribes to the host channel (theme, `styles.variables`, `styles.css.fonts`)
- * via {@link useHostContextSubscription}. Theme-only consumers should use
- * {@link useViewTheme} instead so locale/dimension updates do not rerender them.
+ * Subscribes to the runtime's host-context channel for theme,
+ * `styles.variables`, and `styles.css.fonts`. Theme-only consumers should use
+ * {@link useViewTheme} so locale and dimension updates do not rerender them.
  *
  * MCP App views render in srcdoc iframes; the document canvas stays transparent
  * by default so rounded cards do not expose an opaque `color-scheme` backdrop.
  */
 export declare const ThemeProvider: React.FC<{
+    /** View subtree that receives the host theme. */
     children: React.ReactNode;
     /** Set `color-scheme` on the document root to match the active theme. */
     colorScheme?: boolean;

package/dist/react/hooks/use-view-tool.d.ts

@@ -20,9 +20,9 @@ export type ViewToolDefinition = Pick<ToolDefinition, "name" | "title" | "descri
  * the ext-apps handle's `update()`, passing explicit `undefined` so omitted
  * fields are cleared. Toggling `enabled` calls `enable()` / `disable()`
  * without re-registering. The handler is kept in a ref so calls always see
- * current React state. Registration goes through
- * {@link McpAppRuntime.registerViewTool} (never `app.registerTool` directly)
- * so the runtime can perform the empty-handler handoff on first registration.
+ * current React state. Registration goes through the document runtime rather
+ * than the guest App directly, allowing the runtime to perform the
+ * empty-handler handoff on first registration.
  *
  * Cleanup captures the registration handle inside the effect so an older
  * cleanup cannot remove a newer registration (e.g. after a rapid `name`

package/dist/react/index.d.ts

@@ -1,11 +1,10 @@
 /**
- * React view runtime for MCP Apps (`mcp-use/react`).
+ * Build MCP App views with React components and hooks.
  *
- * Browser-only — built on the ext-apps guest `App` class. Layout:
- * `types/` (the zero-codegen typing layer and vendored host types),
- * `runtime/` (per-document `McpAppRuntime`, snapshots, and iframe bootstrap),
- * `hooks/` (the user-facing hook surface), and `components/`
- * (provider/utility components).
+ * This browser-only entry point provides the view runtime, typed tool context,
+ * host integration hooks, and reusable view components.
+ *
+ * @packageDocumentation
  */
 export { bootstrapView, disposeView, type ViewModule, } from "./runtime/bootstrap-view.js";
 export { type ViewConfig } from "./runtime/view-config.js";

package/dist/react/index.js

@@ -9,6 +9,7 @@ var ErrorBoundary = class extends React.Component {
     super(props);
     this.state = { hasError: false, error: null };
   }
+  /** Records a render failure for the fallback render pass. */
   static getDerivedStateFromError(error) {
     return { hasError: true, error };
   }
@@ -16,6 +17,7 @@ var ErrorBoundary = class extends React.Component {
     console.error("[mcp-use] View error:", error, errorInfo);
     this.props.onError?.(error, errorInfo);
   }
+  /** Renders the child tree or the configured error fallback. */
   render() {
     if (this.state.hasError && this.state.error) {
       if (this.props.fallback !== void 0) {

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

@@ -57,12 +57,12 @@ export interface BootstrapViewOptions {
  */
 export declare function bootstrapView(module: ViewModule, options?: BootstrapViewOptions): void;
 /**
- * Unmount the document's view and dispose its {@link McpAppRuntime}.
+ * Unmount the document's view and dispose its guest MCP App runtime.
  *
  * React unmounts first so hook cleanup (e.g. {@link useViewTool} removal) can
  * run while the App connection still exists; then the runtime closes the App
- * and transport. After this resolves, {@link bootstrapView} may create a
- * fresh runtime.
+ * and transport. After this resolves, the view bootstrap can create a fresh
+ * runtime.
  *
  * No-ops when nothing is mounted.
  *

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

@@ -1,5 +1,6 @@
 /** Opaque file reference returned by {@link useFiles}. */
 export type FileMetadata = {
+    /** Host-assigned opaque file identifier. */
     fileId: string;
 };
 /** Value returned by {@link useFiles}. */
@@ -10,6 +11,7 @@ export interface UseFilesResult {
     upload(file: File): Promise<FileMetadata>;
     /** Request a temporary download URL for an uploaded file. */
     getDownloadUrl(file: FileMetadata): Promise<{
+        /** Temporary URL from which the file can be downloaded. */
         downloadUrl: string;
     }>;
 }

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

@@ -7,7 +7,9 @@ export type SafeAreaInsets = NonNullable<McpUiHostContext["safeAreaInsets"]>;
  * Host application identity from the initialization handshake.
  */
 export type HostInfo = {
+    /** Host product name. */
     name: string;
+    /** Host product version. */
     version: string;
 };
 /**

package/dist/response-helpers.d.ts

@@ -9,9 +9,13 @@ import type { CallToolResult } from "@modelcontextprotocol/server";
  */
 export interface TypedCallToolResult<T extends Record<string, unknown> = Record<string, unknown>> {
     [x: string]: unknown;
+    /** Model-visible content blocks. */
     content: CallToolResult["content"];
+    /** Whether the result represents a tool-domain error. */
     isError?: CallToolResult["isError"];
+    /** Protocol extension metadata. */
     _meta?: CallToolResult["_meta"];
+    /** Typed structured payload. */
     structuredContent?: T;
 }
 /**
@@ -22,9 +26,13 @@ export interface TypedCallToolResult<T extends Record<string, unknown> = Record<
  */
 export interface ToolContentResult {
     [x: string]: unknown;
+    /** Model-visible content blocks. */
     content: CallToolResult["content"];
+    /** Whether the result represents a tool-domain error. */
     isError?: CallToolResult["isError"];
+    /** Protocol extension metadata. */
     _meta?: CallToolResult["_meta"];
+    /** Content-only helpers never provide structured content. */
     structuredContent?: never;
 }
 /**

package/dist/server.d.ts

@@ -341,7 +341,9 @@ export declare class MCPServer<TUser = never, TEnv extends Env = Env> {
      * already mounted the app without Host validation.
      */
     listen(port?: number | undefined, options?: ListenOptions): Promise<{
+        /** Actual bound port, including an ephemeral port chosen for `0`. */
         port: number;
+        /** HTTP URL of the bound MCP endpoint. */
         url: string;
     }>;
     /**

package/dist/views/types.d.ts

@@ -41,8 +41,8 @@ export interface InlineViewManifestEntry {
     /** Discriminant for the embedded bundle shape. */
     kind: "inline";
     /**
-     * Minified ES module source embedded in a `<script type="module">` by
-     * {@link synthesizeViewDocument}.
+     * Minified ES module source embedded in the generated view document's
+     * `<script type="module">` element.
      */
     js: string;
     /**
@@ -88,7 +88,7 @@ export interface ExternalViewManifestEntry {
  * emits origin-absolute Vite URLs.
  */
 export type ViewManifestEntry = InlineViewManifestEntry | ExternalViewManifestEntry;
-/** Map of view name → registry entry, primed via {@link registerViews}. */
+/** Map of view name to registry entry, primed by `registerViews()`. */
 export interface ViewsManifest {
     [viewName: string]: ViewManifestEntry;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-use",
   "type": "module",
-  "version": "2.0.0-beta.63",
+  "version": "2.0.0-beta.64",
   "description": "MCP framework and CLI built on the official v2 SDK",
   "author": "mcp-use, Inc.",
   "license": "MIT",
@@ -101,14 +101,14 @@
     "node": ">=22.22.2"
   },
   "dependencies": {
-    "@modelcontextprotocol/client": "2.0.0-beta.5",
-    "@modelcontextprotocol/core": "2.0.0-beta.5",
-    "@modelcontextprotocol/ext-apps": "npm:@mcp-use/ext-apps@1.7.4-pr720.0",
-    "@modelcontextprotocol/server": "2.0.0-beta.5",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/core": "2.0.0",
+    "@modelcontextprotocol/ext-apps": "npm:@mcp-use/ext-apps@1.7.4-pr720.1",
+    "@modelcontextprotocol/server": "2.0.0",
     "hono": "^4.12.27",
     "jose": "^6.1.3",
     "@mcp-use/cli": "4.0.0-beta.15",
-    "@mcp-use/inspector": "20.0.0-beta.55"
+    "@mcp-use/inspector": "20.0.0-beta.56"
   },
   "peerDependencies": {
     "@mcp-use/client": "^2.0.0-alpha.0",
@@ -142,8 +142,8 @@
     "vite": "^8.0.16",
     "vitest": "^4.1.9",
     "zod": "^4.4.3",
-    "@mcp-use/client": "2.0.0-beta.16",
-    "mcp-use": "2.0.0-beta.63"
+    "@mcp-use/client": "2.0.0-beta.17",
+    "mcp-use": "2.0.0-beta.64"
   },
   "publishConfig": {
     "access": "public"