mcp-use 2.0.0-beta.9 → 2.0.1

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