mcp-use 2.0.0-beta.31 → 2.0.0-beta.32

package/dist/context.d.ts

@@ -1,17 +1,127 @@
-import { type InputRequiredResult, type RequestStateAccessor, type ServerContext, type StandardSchemaWithJSON } from "@modelcontextprotocol/server";
+import { type ClientCapabilities, type Implementation, type InputRequiredResult, type RequestStateAccessor, type ServerContext, type StandardSchemaWithJSON } 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;
 }

package/dist/index.d.ts

@@ -53,7 +53,7 @@ export type { MiddlewareContext, McpMiddlewareContext, McpCompleteEventListenerF
 export { composeMiddleware, createMcpEventListenerEntry, createMcpMiddlewareEntry, matchesPattern, } from "./middleware/mcp-middleware.js";
 export type { NodeRequestHandler } from "./node-bridge.js";
 export type { FromOpenAPIOptions, OpenAPIAuth, OpenAPIDocument, OpenAPIExcludeRule, } from "./openapi/index.js";
-export type { Elicit, ElicitationResult, OAuthAuth, RequestClientContext, RequestContext, } from "./context.js";
+export type { Elicit, ElicitationResult, OAuthAuth, RequestClientContext, RequestContext, UserContext, } from "./context.js";
 export type { InferToolInput, InferToolName, InferToolOutput, ToolCallback, ToolDefinition, ToolRef, ToolResult, ToolViewConfig, } from "./tools.js";
 export type { ExternalViewManifestEntry, InlineViewManifestEntry, UiPermissions, ViewManifestEntry, ViewsManifest, } from "./views/index.js";
 export type { InferTemplateParams, ResourceCallback, ResourceDefinition, ResourceTemplateCallback, ResourceTemplateCompleter, ResourceTemplateCompletions, ResourceTemplateDefinition, TemplateVariableValue, } from "./resources.js";

package/dist/index.js

@@ -319,6 +319,7 @@ function parsePort(value) {
 // src/context.ts
 import {
   CLIENT_CAPABILITIES_META_KEY as CLIENT_CAPABILITIES_META_KEY2,
+  CLIENT_INFO_META_KEY,
   inputRequired,
   inputResponse
 } from "@modelcontextprotocol/server";
@@ -384,11 +385,84 @@ function requireOAuthAuthInfo(authInfo) {
     throw new Error("OAuth callback did not receive mapped AuthInfo.extra");
   }
 }
+function stringValue(value) {
+  return typeof value === "string" ? value : void 0;
+}
+function coordinateValue(value) {
+  if (typeof value === "string") return value;
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function normalizeUserContext(meta) {
+  if (meta === void 0) return void 0;
+  const locale = stringValue(meta["openai/locale"]) ?? stringValue(meta["webplus/i18n"]);
+  const userAgent = stringValue(meta["openai/userAgent"]);
+  const subject = stringValue(meta["openai/subject"]);
+  const conversationId = stringValue(meta["openai/session"]);
+  const organizationId = stringValue(meta["openai/organization"]);
+  const rawLocation = meta["openai/userLocation"];
+  let location;
+  if (typeof rawLocation === "object" && rawLocation !== null && !Array.isArray(rawLocation)) {
+    const values = rawLocation;
+    const normalized = {
+      city: stringValue(values.city),
+      region: stringValue(values.region),
+      country: stringValue(values.country),
+      timezone: stringValue(values.timezone),
+      latitude: coordinateValue(values.latitude),
+      longitude: coordinateValue(values.longitude)
+    };
+    const entries = Object.entries(normalized).filter(
+      (entry) => entry[1] !== void 0
+    );
+    if (entries.length > 0) {
+      location = Object.fromEntries(entries);
+    }
+  }
+  if (locale === void 0 && userAgent === void 0 && location === void 0 && subject === void 0 && conversationId === void 0 && organizationId === void 0) {
+    return void 0;
+  }
+  return {
+    ...locale !== void 0 && { locale },
+    ...userAgent !== void 0 && { userAgent },
+    ...location !== void 0 && { location },
+    ...subject !== void 0 && { subject },
+    ...conversationId !== void 0 && { conversationId },
+    ...organizationId !== void 0 && { organizationId }
+  };
+}
 function toClientContext(ctx) {
-  const envelopeCaps = ctx.mcpReq.envelope?.[CLIENT_CAPABILITIES_META_KEY2];
+  const envelope = ctx.mcpReq.envelope;
+  const capabilities = {
+    ...envelope?.[CLIENT_CAPABILITIES_META_KEY2] ?? {}
+  };
+  const info = {
+    ...envelope?.[CLIENT_INFO_META_KEY] ?? {}
+  };
+  const user = normalizeUserContext(ctx.mcpReq._meta);
   return {
+    can(capability) {
+      return Object.hasOwn(capabilities, capability);
+    },
+    capabilities() {
+      return { ...capabilities };
+    },
+    extension(id) {
+      const settings = capabilities.extensions?.[id];
+      return settings === void 0 ? void 0 : { ...settings };
+    },
+    info() {
+      return { ...info };
+    },
+    user() {
+      return user === void 0 ? void 0 : {
+        ...user,
+        ...user.location !== void 0 && {
+          location: { ...user.location }
+        }
+      };
+    },
     supportsViews() {
-      return supportsViews(envelopeCaps);
+      return supportsViews(capabilities);
     }
   };
 }
@@ -871,7 +945,7 @@ function normalizeMcpMiddlewarePattern(raw) {
 
 // src/logging.ts
 import {
-  CLIENT_INFO_META_KEY,
+  CLIENT_INFO_META_KEY as CLIENT_INFO_META_KEY2,
   isJSONRPCRequest
 } from "@modelcontextprotocol/server";
 function colorsEnabled() {
@@ -949,7 +1023,7 @@ function inlineJson(value) {
 function formatClientIdentity(message) {
   const meta = message.params?._meta;
   if (meta === void 0) return void 0;
-  const info = meta[CLIENT_INFO_META_KEY];
+  const info = meta[CLIENT_INFO_META_KEY2];
   if (typeof info !== "object" || info === null || typeof info.name !== "string") {
     return void 0;
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mcp-use",
   "type": "module",
-  "version": "2.0.0-beta.31",
+  "version": "2.0.0-beta.32",
   "description": "MCP framework and CLI built on the official v2 SDK",
   "author": "mcp-use, Inc.",
   "license": "MIT",
@@ -89,7 +89,7 @@
     "@modelcontextprotocol/server": "2.0.0-beta.5",
     "hono": "^4.12.27",
     "jose": "^6.1.3",
-    "@mcp-use/inspector": "20.0.0-beta.23",
+    "@mcp-use/inspector": "20.0.0-beta.24",
     "@mcp-use/cli": "4.0.0-beta.6"
   },
   "peerDependencies": {
@@ -123,8 +123,8 @@
     "vite": "^8.0.16",
     "vitest": "^4.1.9",
     "zod": "^4.4.3",
-    "mcp-use": "2.0.0-beta.31",
-    "@mcp-use/client": "2.0.0-beta.12"
+    "@mcp-use/client": "2.0.0-beta.12",
+    "mcp-use": "2.0.0-beta.32"
   },
   "publishConfig": {
     "access": "public"