mcp-use 2.0.0-beta.9 → 2.0.0

package/dist/config.d.ts

@@ -1,34 +1,6 @@
 import type { Icon, ServerOptions } from "@modelcontextprotocol/server";
 import type { LoggingOptions } from "./logging.js";
 import type { OAuthProvider } from "./oauth/index.js";
-/**
- * Options for the inspector shell route — the shape of
- * {@link ServerConfig.inspector}.
- */
-export interface InspectorOptions {
-    /**
-     * Whether the inspector shell route is mounted.
-     *
-     * @defaultValue `true`
-     */
-    enabled?: boolean;
-    /**
-     * Full replacement URL for the inspector bundle script (FastAPI's
-     * `swagger_js_url` analog). The shell's `<script type="module">` loads
-     * exactly this URL, so it must point at a complete copy of the
-     * `@mcp-use/inspector` CDN bundle (`dist/cdn/inspector.js`) — self-host it
-     * for air-gapped environments where the public CDN is unreachable.
-     *
-     * @defaultValue The mcp-use CDN URL for the `@mcp-use/inspector` bundle,
-     * pinned to the current version.
-     */
-    assetsUrl?: string;
-    /**
-     * Hosted managed-chat backend URL (injected as `window.__MANUFACT_CHAT_URL__`).
-     * Defaults to `process.env.MANUFACT_CHAT_URL` when the shell is mounted.
-     */
-    manufactChatUrl?: string;
-}
 /**
  * Common server identity and behavior, passed to `new MCPServer(...)`.
  *
@@ -52,9 +24,9 @@ interface BaseServerConfig {
      *
      * Accepts a safe path relative to the project `public/` directory, an
      * absolute HTTP(S) URL, or an image data URL. The selected image is served
-     * at the root-level `/favicon.ico` route. When omitted, the `icons` field
-     * selects the favicon using ICO, small PNG, any PNG, then first-icon order.
-     * An explicit value always wins; an empty string is invalid.
+     * at the root-level `/favicon.ico` route. When omitted, the first entry in
+     * `icons` selects the favicon. An explicit value always wins; an empty
+     * string is invalid.
      *
      * @defaultValue Inferred from `icons`, or no favicon when `icons` is absent
      * or empty.
@@ -78,8 +50,8 @@ interface BaseServerConfig {
      * relative to `public/`, an absolute HTTP(S) URL, or an image data URL.
      * Local paths become request-scoped absolute URLs under
      * `${basePath}/_mcp-use/public/`; author order is preserved on the wire.
-     * When `favicon` is omitted, these icons also select `/favicon.ico`.
-     * An empty array is valid and selects no favicon.
+     * When `favicon` is omitted, the first icon in this array also selects
+     * `/favicon.ico`. An empty array is valid and selects no favicon.
      *
      * @defaultValue `undefined`
      * @throws TypeError When an icon has an invalid source, MIME type, sizes,
@@ -130,28 +102,36 @@ interface BaseServerConfig {
      */
     basePath?: string;
     /**
-     * Hostname `listen()` binds. Defaults to `127.0.0.1`; localhost-class
+     * Hostname `listen()` binds when neither an explicit listener host nor
+     * `HOST` is set. Defaults to `127.0.0.1`; localhost-class
      * binds get DNS-rebinding protection (`Host` on every request; `Origin`
      * only on non-GET/HEAD) automatically. Set `"0.0.0.0"` to serve publicly — behind a platform
      * edge (Railway, Fly, …) nothing more is needed, since the edge only
-     * routes hostnames assigned to the deployment. Ignored by `getHandler()`,
-     * which never binds.
+     * routes hostnames assigned to the deployment. Ignored by `server.fetch`,
+     * which never binds a socket.
      */
     host?: string;
+    /**
+     * TCP port `listen()` binds when neither an explicit port nor `PORT` is set.
+     * Use `0` to request an ephemeral port.
+     *
+     * @defaultValue `3000`
+     */
+    port?: number;
     /**
      * Extra allowed hostnames for Host-header validation (DNS-rebinding
      * protection), e.g. `["api.example.com"]`. Port-agnostic and additive:
      * localhost-class hostnames stay allowed, so local runs keep working
      * unmodified. Setting this also turns Host validation on for
-     * `getHandler()`, which otherwise applies none.
+     * `server.fetch`, which otherwise applies none.
      */
     allowedHosts?: string[];
     /**
      * Extra allowed origin hostnames for Origin-header validation
      * (port-agnostic, additive to the localhost-class origins). When unset,
-     * mirrors the effective Host allowlist. Origin is validated only on
-     * non-GET/HEAD requests (sandboxed view iframes send `Origin: null` on
-     * asset GETs; the MCP wire is POST). Requests without an `Origin` header
+     * Origin validation is off (SDK-aligned). When set, Origin is validated
+     * only on non-GET/HEAD requests (sandboxed view iframes send `Origin: null`
+     * on asset GETs; the MCP wire is POST). Requests without an `Origin` header
      * always pass (non-browser MCP clients don't send one).
      */
     allowedOrigins?: string[];
@@ -179,46 +159,6 @@ interface BaseServerConfig {
      * @defaultValue `false`
      */
     publicLandingPage?: boolean;
-    /**
-     * Inspector shell route at `${basePath}/inspector` — a browser UI for
-     * exploring and calling the server's tools, resources, and prompts.
-     *
-     * @remarks
-     * Follows the FastAPI `/docs` model: the server itself ships only a tiny
-     * dependency-free HTML page whose `<script type="module">` loads the
-     * `@mcp-use/inspector` bundle from a CDN (pinned to the current inspector
-     * version), so the UI updates independently of SDK releases and adds
-     * nothing to the install. The page tells the inspector to connect to this
-     * server's MCP endpoint at `basePath`, deriving the URL from the browser's
-     * own origin.
-     *
-     * Enabled by default; set `{ enabled: false }` to disable the route, or
-     * pass `{ assetsUrl }` to load the bundle from a self-hosted copy instead
-     * of the public CDN (air-gapped environments). For local development,
-     * `MCP_USE_INSPECTOR_ASSETS_URL` provides the same override without changing
-     * application code; an explicit `assetsUrl` takes precedence.
-     *
-     * @example
-     * ```ts
-     * // Default: inspector served at /mcp/inspector from the public CDN.
-     * new MCPServer({ name: "my-server", version: "1.0.0" });
-     *
-     * // Disabled:
-     * new MCPServer({
-     *   name: "my-server",
-     *   version: "1.0.0",
-     *   inspector: { enabled: false },
-     * });
-     *
-     * // Air-gapped: load a self-hosted copy of the inspector bundle.
-     * new MCPServer({
-     *   name: "my-server",
-     *   version: "1.0.0",
-     *   inspector: { assetsUrl: "https://intranet.example.com/inspector.js" },
-     * });
-     * ```
-     */
-    inspector?: InspectorOptions;
     /**
      * HTTP/MCP request logging: one summary line per request plus an indented
      * detail line naming the MCP method, its subject (tool name, resource URI,
@@ -246,8 +186,8 @@ interface BaseServerConfig {
      */
     requestState?: ServerOptions["requestState"];
     /**
-     * Optional CORS headers on every route served by `getHandler()` / `listen()`
-     * (MCP endpoint, view assets, inspector, OAuth metadata). Off when omitted.
+     * Optional CORS headers on every route served by `server.fetch` / `listen()`
+     * (MCP endpoint, view assets, landing page, OAuth metadata). Off when omitted.
      *
      * Pair with {@link BaseServerConfig.allowedOrigins | allowedOrigins} for
      * browser clients: CORS tells the browser it may read the response; Origin
@@ -269,7 +209,7 @@ interface BaseServerConfig {
     cors?: CorsOptions;
 }
 /**
- * CORS configuration for routes owned by mcp-use (`getHandler()` / `listen()`).
+ * CORS configuration for routes owned by the Hono application.
  *
  * Omit `cors` entirely for the current no-CORS behavior. Pass `cors: {}` to
  * enable with defaults (reflects the request `Origin` when present; wildcard
@@ -297,6 +237,7 @@ export interface CorsOptions {
  */
 export declare function assertServerConfig(config: {
     basePath?: unknown;
+    port?: unknown;
 }): void;
 /**
  * Server identity and behavior, passed to `new MCPServer(...)`.
@@ -316,4 +257,3 @@ export type ServerConfig<TUser = never> = BaseServerConfig & ([TUser] extends [n
     oauth: OAuthProvider<TUser>;
 });
 export {};
-//# sourceMappingURL=config.d.ts.map

package/dist/context.d.ts

@@ -1,74 +1,143 @@
-import { type InputRequiredResult, type RequestStateAccessor, type ServerContext, type StandardSchemaWithJSON } from "@modelcontextprotocol/server";
+import { type ClientCapabilities, type Implementation, type RequestStateAccessor, type ServerContext } from "@modelcontextprotocol/server";
+import type { Context, Env, HonoRequest as HonoRequestType } from "hono";
 /**
- * Per-request client capability queries.
+ * OpenAI-specific end-user hints declared in request metadata.
  *
- * Reads the modern per-request envelope only — never session state.
+ * All fields are optional, client-reported, and unverified. Use
+ * {@link OAuthAuth.user} for an authenticated identity.
+ */
+export interface UserContext {
+    /** Requested BCP 47 locale from `openai/locale` or legacy `webplus/i18n`. */
+    locale?: string;
+    /** Best-effort browser or host identifier from `openai/userAgent`. */
+    userAgent?: string;
+    /** Coarse end-user location from `openai/userLocation`. */
+    location?: {
+        /** City name, when supplied. */
+        city?: string;
+        /** Region or state name, when supplied. */
+        region?: string;
+        /** Country identifier, when supplied. */
+        country?: string;
+        /** IANA timezone identifier, when supplied. */
+        timezone?: string;
+        /** Approximate latitude; clients may encode coordinates as strings or numbers. */
+        latitude?: string | number;
+        /** Approximate longitude; clients may encode coordinates as strings or numbers. */
+        longitude?: string | number;
+    };
+    /** Client-reported subject hint from `openai/subject`. */
+    subject?: string;
+    /** Client-reported conversation hint from `openai/session`. */
+    conversationId?: string;
+    /** Client-reported organization hint from `openai/organization`. */
+    organizationId?: string;
+}
+/**
+ * Per-request client metadata and capability queries.
+ *
+ * Reads only the current request's metadata — never session state.
  */
 export interface RequestClientContext {
+    /**
+     * Checks whether this request declares a top-level client capability.
+     *
+     * @param capability - Capability name such as `sampling`, `elicitation`,
+     * `roots`, or `extensions`.
+     * @returns `true` when the current request advertises the capability.
+     *
+     * @example
+     * ```ts
+     * if (ctx.client.can("elicitation")) {
+     *   // Shape the result for an elicitation-capable client.
+     * }
+     * ```
+     */
+    can(capability: string): boolean;
+    /**
+     * Returns the capabilities declared by the client for this request.
+     *
+     * The returned object is a shallow copy. Requests without the modern
+     * metadata envelope return an empty object.
+     *
+     * @example
+     * ```ts
+     * const capabilities = ctx.client.capabilities();
+     * const supportsFormElicitation = capabilities.elicitation?.form !== undefined;
+     * ```
+     */
+    capabilities(): ClientCapabilities;
+    /**
+     * Returns one extension settings object declared for this request.
+     *
+     * @param id - Namespaced extension identifier, such as
+     * `io.modelcontextprotocol/ui`.
+     * @returns A shallow copy of the extension settings, or `undefined` when the
+     * current request does not advertise the extension.
+     *
+     * @example
+     * ```ts
+     * const ui = ctx.client.extension("io.modelcontextprotocol/ui");
+     * ```
+     */
+    extension(id: string): NonNullable<ClientCapabilities["extensions"]>[string] | undefined;
+    /**
+     * Returns the client implementation metadata declared for this request.
+     *
+     * Valid modern requests include `name` and `version`. The partial return
+     * type preserves v1 ergonomics for legacy requests without an envelope.
+     * The returned object is a shallow copy.
+     *
+     * @example
+     * ```ts
+     * const { name, version } = ctx.client.info();
+     * ```
+     */
+    info(): Partial<Implementation>;
+    /**
+     * Returns normalized OpenAI-specific end-user hints for this request.
+     *
+     * The data comes from ordinary request `_meta`, not the MCP client-info
+     * envelope. It is client-reported and must not be used for authentication
+     * or authorization. Each call returns a fresh object, including a fresh
+     * location object. Requests without recognized metadata return `undefined`.
+     *
+     * @example
+     * ```ts
+     * const caller = ctx.client.user();
+     * const locale = caller?.locale ?? "en";
+     * ```
+     */
+    user(): UserContext | undefined;
     /**
      * Whether this request's client advertises MCP Apps / UI support.
      *
      * True when the client declares the `io.modelcontextprotocol/ui` extension
      * with `text/html;profile=mcp-app` in `mimeTypes`. Legacy (non-envelope)
      * requests always return `false`.
+     *
+     * @example
+     * ```ts
+     * if (ctx.client.supportsViews()) {
+     *   // Return a view-optimized result.
+     * }
+     * ```
      */
     supportsViews(): boolean;
 }
-/**
- * Result of a {@link Elicit} call.
- *
- * `required` means the callback must return `result`; the client then gathers
- * input and retries the tool. Accepted form results carry schema-validated,
- * inferred `data`. URL acceptances and declined/cancelled results carry no
- * data.
- */
-export type ElicitationResult<T = never> = {
-    status: "required";
-    result: InputRequiredResult;
-} | {
-    status: "decline" | "cancel";
-} | ([T] extends [never] ? {
-    status: "accept";
-} : {
-    status: "accept";
-    data: T;
-});
-/**
- * Requests or reads one keyed elicitation in a multi-round-trip tool callback.
- *
- * The explicit key correlates the request with the client's response on
- * re-entry. On the first entry, or after an invalid form response, this returns
- * `{ status: "required", result }`; return that result from the tool. On
- * re-entry it returns `accept`, `decline`, or `cancel` and validates accepted
- * Standard Schema form data before exposing it. Validation may be synchronous
- * or asynchronous.
- *
- * @example
- * ```ts
- * const confirmation = await ctx.elicit(
- *   "confirm",
- *   "Deploy to production?",
- *   schema,
- * );
- * if (confirmation.status === "required") {
- *   return confirmation.result;
- * }
- * ```
- */
-export interface Elicit {
-    /** Request or read a typed form-mode elicitation. */
-    <S extends StandardSchemaWithJSON>(key: string, message: string, schema: S): Promise<ElicitationResult<StandardSchemaWithJSON.InferOutput<S>>>;
-    /** Request or read a URL-mode elicitation. */
-    (key: string, message: string, url: string): Promise<ElicitationResult>;
-}
 /**
  * Per-request context passed to tool/resource/prompt callbacks.
  */
 export type OAuthAuth<TUser> = {
+    /** Authenticated application user mapped by the OAuth provider. */
     user: TUser;
+    /** Verified access-token claims or introspection data. */
     payload: Record<string, unknown>;
+    /** Raw bearer token for authenticated downstream requests. */
     accessToken: string;
+    /** OAuth scopes granted to the access token. */
     scopes: string[];
+    /** Provider-normalized permissions granted to the user. */
     permissions: string[];
     /**
      * The OAuth client identifier from the token's `client_id` or `azp` claim;
@@ -76,18 +145,24 @@ export type OAuthAuth<TUser> = {
      * (e.g. WorkOS AuthKit, Supabase).
      */
     clientId?: string;
+    /** Access-token expiration as Unix time in seconds. */
     expiresAt: number;
+    /** Resource audience the access token authorizes, when supplied. */
     resource?: URL;
 };
-type RequestContextBase = {
+type RequestContextBase<TEnv extends Env> = Omit<Context<TEnv>, "req"> & {
     /** Aborted when the client cancels the request or the connection drops. */
     signal: AbortSignal;
-    /** The originating HTTP request, when served over HTTP. */
-    request?: Request;
+    /** Hono request for the originating HTTP exchange. Its raw Web Request is available as `request.raw`. */
+    request?: HonoRequestType;
+    /**
+     * Deprecated v1-compatible alias for {@link RequestContext.request}.
+     *
+     * @deprecated Use `request` instead.
+     */
+    req?: HonoRequestType;
     /** Per-request client capability queries. */
     client: RequestClientContext;
-    /** Request or read a keyed form- or URL-mode elicitation. */
-    elicit: Elicit;
     /**
      * Bare responses supplied when the client retries an `input_required`
      * round. Values are client input; validate them before use.
@@ -99,6 +174,26 @@ type RequestContextBase = {
      * when state affects authorization or business logic.
      */
     requestState: RequestStateAccessor;
+    /**
+     * Sends a one-way notification related to the current MCP request.
+     *
+     * The notification is delivered on the originating request's response
+     * stream and must be sent before the callback returns. Use the
+     * `server.notifyToolsChanged()` and related server helpers for
+     * cross-request list or resource invalidations.
+     *
+     * @param method - Application-defined notification method.
+     * @param params - Optional JSON-serializable notification parameters.
+     * @returns A promise that resolves after the notification is sent.
+     *
+     * @example
+     * ```ts
+     * await ctx.sendNotification("com.example/import-status", {
+     *   status: "started",
+     * });
+     * ```
+     */
+    sendNotification(method: string, params?: Record<string, unknown>): Promise<void>;
     /**
      * Report request-scoped progress when the caller supplied a progress token.
      *
@@ -112,9 +207,9 @@ type RequestContextBase = {
 /**
  * Per-request callback context, authenticated when OAuth is configured.
  */
-export type RequestContext<TUser = never, HasOAuth extends boolean = false> = HasOAuth extends true ? RequestContextBase & {
+export type RequestContext<TUser = never, HasOAuth extends boolean = false, TEnv extends Env = Env> = HasOAuth extends true ? RequestContextBase<TEnv> & {
     auth: OAuthAuth<TUser>;
-} : RequestContextBase & {
+} : RequestContextBase<TEnv> & {
     auth?: never;
 };
 /**
@@ -123,8 +218,7 @@ export type RequestContext<TUser = never, HasOAuth extends boolean = false> = Ha
  *
  * @internal
  */
-export declare function toRequestContext(ctx: ServerContext): RequestContext<never, false>;
+export declare function toRequestContext<TEnv extends Env = Env>(ctx: ServerContext): RequestContext<never, false, TEnv>;
 /** @internal Projects mapped OAuth auth information into callback context. */
-export declare function toAuthenticatedRequestContext<TUser>(ctx: ServerContext): RequestContext<TUser, true>;
+export declare function toAuthenticatedRequestContext<TUser, TEnv extends Env = Env>(ctx: ServerContext): RequestContext<TUser, true, TEnv>;
 export {};
-//# sourceMappingURL=context.d.ts.map

package/dist/fetch-app.d.ts

@@ -1,23 +1,7 @@
 import { type AuthInfo } from "@modelcontextprotocol/server";
+import type { Context, Env } from "hono";
 /** Web-standard request handler. */
 export type FetchHandler = (request: Request) => Promise<Response>;
-/** Request shapes accepted by {@link toFrameworkHandler}. */
-export type FrameworkRequestLike = Request | {
-    req: {
-        raw: Request;
-    };
-};
-/**
- * Universal web handler mountable in Vercel, Hono, TanStack, and other
- * fetch-native frameworks without `c.req.raw` boilerplate.
- */
-export type FrameworkHandler = (input: FrameworkRequestLike) => Promise<Response>;
-/**
- * Wrap a {@link FetchHandler} for framework duck-typing (Hono `Context`, etc.).
- *
- * @param fetch - Inner fetch handler produced by {@link MCPServer.getHandler}.
- */
-export declare function toFrameworkHandler(fetch: FetchHandler): FrameworkHandler;
 /** Onion middleware over a {@link FetchHandler} terminal. */
 export type FetchMiddleware = (request: Request, next: () => Promise<Response>) => Promise<Response>;
 /** Per-request values stashed before the MCP handler runs. */
@@ -26,6 +10,8 @@ export interface RequestBag {
     parsedBody?: unknown;
     /** Verified OAuth identity forwarded to the SDK handler. */
     authInfo?: AuthInfo;
+    /** Hono context associated with this request while it traverses the app. */
+    honoContext?: Context<Env>;
 }
 /**
  * Mutable per-request bag; created on first access.
@@ -86,16 +72,6 @@ export declare function pathUnderBase(basePath: string, childPath: string): stri
  * @internal
  */
 export declare function isHtmlNavigationRequest(request: Request): boolean;
-/**
- * Dispatch to the first matching route handler.
- *
- * @param routes - Ordered route table; first match wins.
- * @param fallback - Handler when nothing matches.
- */
-export declare function routeFetch(routes: Array<{
-    match: (request: Request) => boolean;
-    handler: FetchHandler;
-}>, fallback?: FetchHandler): FetchHandler;
 /**
  * Parse JSON bodies once and stash them in the request bag.
  */
@@ -113,4 +89,3 @@ export declare function hostValidationMiddleware(hosts: string[]): FetchMiddlewa
  * @param skipSafeMethods - When true, skip GET/HEAD (view asset GETs).
  */
 export declare function originValidationMiddleware(origins: string[], skipSafeMethods?: boolean): FetchMiddleware;
-//# sourceMappingURL=fetch-app.d.ts.map