Make it styles.variables instead of styles

examples/customer-segmentation-server/src/mcp-app.ts

@@ -453,11 +453,11 @@ app.onhostcontextchanged = (params) => {
   if (params.theme) {
     applyDocumentTheme(params.theme);
   }
-  if (params.styles) {
-    applyHostStyles(params.styles);
+  if (params.styles?.variables) {
+    applyHostStyles(params.styles.variables);
   }
   // Recreate chart to pick up new colors
-  if (state.chart && (params.theme || params.styles)) {
+  if (state.chart && (params.theme || params.styles?.variables)) {
     state.chart.destroy();
     state.chart = initChart();
   }
@@ -469,8 +469,8 @@ app.connect(new PostMessageTransport(window.parent)).then(() => {
   if (ctx?.theme) {
     applyDocumentTheme(ctx.theme);
   }
-  if (ctx?.styles) {
-    applyHostStyles(ctx.styles);
+  if (ctx?.styles?.variables) {
+    applyHostStyles(ctx.styles.variables);
   }
 });
 

specification/draft/apps.mdx

@@ -404,8 +404,11 @@ interface HostContext {
   };
   /** Current color theme preference */
   theme?: "light" | "dark";
-  /** CSS variables for theming. See Theming section for standardized variable names. */
-  styles?: Record<McpUiStyleVariableKey, string | undefined>;
+  /** Style configuration for theming. See Theming section for standardized variable names. */
+  styles?: {
+    /** CSS variables for theming */
+    variables?: Record<McpUiStyleVariableKey, string | undefined>;
+  };
   /** How the UI is currently displayed */
   displayMode?: "inline" | "fullscreen" | "pip";
   /** Display modes the host supports */
@@ -454,10 +457,12 @@ Example:
     "hostContext": {
       "theme": "dark",
       "styles": {
-        "--color-background-primary": "light-dark(#ffffff, #171717)",
-        "--color-text-primary": "light-dark(#171717, #fafafa)",
-        "--font-family-sans": "system-ui, sans-serif",
-        ...
+        "variables": {
+          "--color-background-primary": "light-dark(#ffffff, #171717)",
+          "--color-text-primary": "light-dark(#171717, #fafafa)",
+          "--font-family-sans": "system-ui, sans-serif",
+          ...
+        }
       },
       "displayMode": "inline",
       "viewport": { "width": 400, "height": 300 }
@@ -468,7 +473,7 @@ Example:
 
 ### Theming
 
-Hosts can optionally pass CSS custom properties via `HostContext.styles` for visual cohesion with the host environment.
+Hosts can optionally pass CSS custom properties via `HostContext.styles.variables` for visual cohesion with the host environment.
 
 #### Current Standardized Variables
 

src/generated/schema.test.ts

@@ -63,6 +63,10 @@ export type McpUiToolCancelledNotificationSchemaInferredType = z.infer<
   typeof generated.McpUiToolCancelledNotificationSchema
 >;
 
+export type McpUiHostStylesSchemaInferredType = z.infer<
+  typeof generated.McpUiHostStylesSchema
+>;
+
 export type McpUiResourceTeardownRequestSchemaInferredType = z.infer<
   typeof generated.McpUiResourceTeardownRequestSchema
 >;
@@ -177,6 +181,8 @@ expectType<spec.McpUiToolCancelledNotification>(
 expectType<McpUiToolCancelledNotificationSchemaInferredType>(
   {} as spec.McpUiToolCancelledNotification,
 );
+expectType<spec.McpUiHostStyles>({} as McpUiHostStylesSchemaInferredType);
+expectType<McpUiHostStylesSchemaInferredType>({} as spec.McpUiHostStyles);
 expectType<spec.McpUiResourceTeardownRequest>(
   {} as McpUiResourceTeardownRequestSchemaInferredType,
 );

src/generated/schema.ts

@@ -246,6 +246,16 @@ export const McpUiToolCancelledNotificationSchema = z.object({
   }),
 });
 
+/**
+ * @description Style configuration for theming MCP apps.
+ */
+export const McpUiHostStylesSchema = z.object({
+  /** @description CSS variables for theming the app. */
+  variables: McpUiStylesSchema.optional().describe(
+    "CSS variables for theming the app.",
+  ),
+});
+
 /**
  * @description Request for graceful shutdown of the Guest UI (Host -> Guest UI).
  * @see {@link app-bridge.AppBridge.sendResourceTeardown} for the host method that sends this
@@ -422,9 +432,9 @@ export const McpUiHostContextSchema = z.looseObject({
   theme: McpUiThemeSchema.optional().describe(
     "Current color theme preference.",
   ),
-  /** @description CSS variables for theming the app. */
-  styles: McpUiStylesSchema.optional().describe(
-    "CSS variables for theming the app.",
+  /** @description Style configuration for theming the app. */
+  styles: McpUiHostStylesSchema.optional().describe(
+    "Style configuration for theming the app.",
   ),
   /** @description How the UI is currently displayed. */
   displayMode: McpUiDisplayModeSchema.optional().describe(

src/react/useHostStyles.ts

@@ -7,7 +7,7 @@ import { McpUiHostContext } from "../types";
  * React hook that applies host styles and theme as CSS custom properties.
  *
  * This hook listens to host context changes and automatically applies:
- * - `styles` CSS variables to `document.documentElement` (e.g., `--color-background-primary`)
+ * - `styles.variables` CSS variables to `document.documentElement` (e.g., `--color-background-primary`)
  * - `theme` via `color-scheme` CSS property, enabling `light-dark()` CSS function support
  *
  * The hook also applies styles and theme from the initial host context when
@@ -70,10 +70,10 @@ export function useHostStyles(
     if (initialContext?.theme) {
       applyDocumentTheme(initialContext.theme);
     }
-    if (initialContext?.styles) {
-      applyHostStyles(initialContext.styles);
+    if (initialContext?.styles?.variables) {
+      applyHostStyles(initialContext.styles.variables);
     }
-    if (initialContext?.theme || initialContext?.styles) {
+    if (initialContext?.theme || initialContext?.styles?.variables) {
       initialApplied.current = true;
     }
   }, [initialContext]);
@@ -88,8 +88,8 @@ export function useHostStyles(
       if (params.theme) {
         applyDocumentTheme(params.theme);
       }
-      if (params.styles) {
-        applyHostStyles(params.styles);
+      if (params.styles?.variables) {
+        applyHostStyles(params.styles.variables);
       }
     };
   }, [app]);

src/spec.types.ts

@@ -244,6 +244,14 @@ export interface McpUiToolCancelledNotification {
   };
 }
 
+/**
+ * @description Style configuration for theming MCP apps.
+ */
+export interface McpUiHostStyles {
+  /** @description CSS variables for theming the app. */
+  variables?: McpUiStyles;
+}
+
 /**
  * @description Rich context about the host environment provided to Guest UIs.
  */
@@ -259,8 +267,8 @@ export interface McpUiHostContext {
   };
   /** @description Current color theme preference. */
   theme?: McpUiTheme;
-  /** @description CSS variables for theming the app. */
-  styles?: McpUiStyles;
+  /** @description Style configuration for theming the app. */
+  styles?: McpUiHostStyles;
   /** @description How the UI is currently displayed. */
   displayMode?: McpUiDisplayMode;
   /** @description Display modes the host supports. */

src/styles.ts

@@ -76,12 +76,12 @@ export function applyDocumentTheme(theme: McpUiTheme): void {
 /**
  * Apply host styles as CSS custom properties on an element.
  *
- * This function takes the `styles` object from `McpUiHostContext` and sets
+ * This function takes the `variables` object from `McpUiHostContext.styles` and sets
  * each CSS variable on the specified root element (defaults to `document.documentElement`).
  * This allows apps to use the host's theming values via CSS variables like
  * `var(--color-background-primary)`.
  *
- * @param styles - The styles object from `McpUiHostContext.styles`
+ * @param styles - The styles object from `McpUiHostContext.styles.variables`
  * @param root - The element to apply styles to (defaults to `document.documentElement`)
  *
  * @example Apply styles from host context
@@ -89,8 +89,8 @@ export function applyDocumentTheme(theme: McpUiTheme): void {
  * import { applyHostStyles } from '@modelcontextprotocol/ext-apps';
  *
  * app.onhostcontextchanged = (params) => {
- *   if (params.styles) {
- *     applyHostStyles(params.styles);
+ *   if (params.styles?.variables) {
+ *     applyHostStyles(params.styles.variables);
  *   }
  * };
  * ```
@@ -98,7 +98,7 @@ export function applyDocumentTheme(theme: McpUiTheme): void {
  * @example Apply to a specific element
  * ```typescript
  * const container = document.getElementById('app-root');
- * applyHostStyles(hostContext.styles, container);
+ * applyHostStyles(hostContext.styles?.variables, container);
  * ```
  *
  * @see {@link McpUiStyles} for the available CSS variables

src/types.ts

@@ -16,6 +16,7 @@ export {
   type McpUiDisplayMode,
   type McpUiStyleVariableKey,
   type McpUiStyles,
+  type McpUiHostStyles,
   type McpUiOpenLinkRequest,
   type McpUiOpenLinkResult,
   type McpUiMessageRequest,
@@ -65,6 +66,7 @@ import type {
 export {
   McpUiThemeSchema,
   McpUiDisplayModeSchema,
+  McpUiHostStylesSchema,
   McpUiOpenLinkRequestSchema,
   McpUiOpenLinkResultSchema,
   McpUiMessageRequestSchema,