Make it styles.variables instead of styles

This commit is contained in:
martinalong 2025-12-14 12:28:42 -08:00
commit 445a5836cf
No known key found for this signature in database
9 changed files with 717 additions and 496 deletions

View file

@ -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);
}
});

View file

@ -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": {
"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

View file

@ -265,6 +265,10 @@
]
},
"styles": {
"description": "Style configuration for theming the app.",
"type": "object",
"properties": {
"variables": {
"description": "CSS variables for theming the app.",
"type": "object",
"propertyNames": {
@ -425,6 +429,9 @@
{}
]
}
}
},
"additionalProperties": false
},
"displayMode": {
"description": "How the UI is currently displayed.",
@ -713,6 +720,10 @@
]
},
"styles": {
"description": "Style configuration for theming the app.",
"type": "object",
"properties": {
"variables": {
"description": "CSS variables for theming the app.",
"type": "object",
"propertyNames": {
@ -873,6 +884,9 @@
{}
]
}
}
},
"additionalProperties": false
},
"displayMode": {
"description": "How the UI is currently displayed.",
@ -991,6 +1005,175 @@
"additionalProperties": false
}
},
"additionalProperties": false
},
"McpUiHostStyles": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"variables": {
"description": "CSS variables for theming the app.",
"type": "object",
"propertyNames": {
"description": "Style variables for theming MCP apps.\n\nIndividual style keys are optional - hosts may provide any subset of these values.\nValues are strings containing CSS values (colors, sizes, font stacks, etc.).\n\nNote: This type uses `Record<K, string | undefined>` rather than `Partial<Record<K, string>>`\nfor compatibility with Zod schema generation. Both are functionally equivalent for validation.",
"anyOf": [
{
"type": "string",
"const": "--color-background-primary"
},
{
"type": "string",
"const": "--color-background-secondary"
},
{
"type": "string",
"const": "--color-background-tertiary"
},
{
"type": "string",
"const": "--color-background-inverted"
},
{
"type": "string",
"const": "--color-text-primary"
},
{
"type": "string",
"const": "--color-text-secondary"
},
{
"type": "string",
"const": "--color-text-tertiary"
},
{
"type": "string",
"const": "--color-text-inverted"
},
{
"type": "string",
"const": "--color-icon-primary"
},
{
"type": "string",
"const": "--color-icon-secondary"
},
{
"type": "string",
"const": "--color-icon-tertiary"
},
{
"type": "string",
"const": "--color-icon-inverted"
},
{
"type": "string",
"const": "--color-border-primary"
},
{
"type": "string",
"const": "--color-border-secondary"
},
{
"type": "string",
"const": "--color-accent-info"
},
{
"type": "string",
"const": "--color-accent-danger"
},
{
"type": "string",
"const": "--color-accent-success"
},
{
"type": "string",
"const": "--color-accent-warning"
},
{
"type": "string",
"const": "--font-family-sans"
},
{
"type": "string",
"const": "--font-size-heading"
},
{
"type": "string",
"const": "--font-size-body"
},
{
"type": "string",
"const": "--font-size-caption"
},
{
"type": "string",
"const": "--font-weight-regular"
},
{
"type": "string",
"const": "--font-weight-emphasized"
},
{
"type": "string",
"const": "--font-leading-regular"
},
{
"type": "string",
"const": "--font-leading-tight"
},
{
"type": "string",
"const": "--font-style-heading"
},
{
"type": "string",
"const": "--font-style-body"
},
{
"type": "string",
"const": "--font-style-body-emphasized"
},
{
"type": "string",
"const": "--font-style-caption"
},
{
"type": "string",
"const": "--font-style-caption-emphasized"
},
{
"type": "string",
"const": "--border-radius-small"
},
{
"type": "string",
"const": "--border-radius-medium"
},
{
"type": "string",
"const": "--border-radius-large"
},
{
"type": "string",
"const": "--border-radius-full"
},
{
"type": "string",
"const": "--border-width-regular"
}
]
},
"additionalProperties": {
"description": "Style variables for theming MCP apps.\n\nIndividual style keys are optional - hosts may provide any subset of these values.\nValues are strings containing CSS values (colors, sizes, font stacks, etc.).\n\nNote: This type uses `Record<K, string | undefined>` rather than `Partial<Record<K, string>>`\nfor compatibility with Zod schema generation. Both are functionally equivalent for validation.",
"anyOf": [
{
"type": "string"
},
{}
]
}
}
},
"additionalProperties": {}
},
"McpUiInitializeRequest": {
@ -1343,6 +1526,10 @@
]
},
"styles": {
"description": "Style configuration for theming the app.",
"type": "object",
"properties": {
"variables": {
"description": "CSS variables for theming the app.",
"type": "object",
"propertyNames": {
@ -1503,6 +1690,9 @@
{}
]
}
}
},
"additionalProperties": false
},
"displayMode": {
"description": "How the UI is currently displayed.",

View file

@ -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,
);

View file

@ -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(

View file

@ -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]);

View file

@ -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. */

View file

@ -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

View file

@ -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,