flutter_mcp_ui_runtime library

Classes

AccessibleFormField
Form field with live validation announcements
AccessibleProgressIndicator
Progress indicator with live region announcements
ActionExecutor
Base class for action executors
ActionHandler
ActionResult
Result of an action execution
AppDensity
VisualDensity and scrollbar hover policy for the active FormFactor.
AppIconSizes
Icon-size scale. Logical pixels.
AppIconSizesScale
FormFactor-resolved icon sizes. Returned from AppIconSizes.of.
ApplicationDefinition
Application definition according to spec
AppSpacing
Spacing / padding / gap scale (8-point grid). Logical pixels.
AppSpacingScale
Design-token sets resolved against the active FormFactor.
AppTypography
AppTypographyScale
TextTheme resolved against the active FormFactor.
AssetRef
A parsed asset reference.
AssetResolver
Resolves an AssetRef to bytes or to an ImageProvider.
AsyncValidator
Async validator base class
BackgroundServiceDefinition
Background service definition
BackgroundServiceManager
Manages background services for the runtime
BackgroundServiceRunner
Runs a single background service
BackpressureController
Controls backpressure for channel streams (CH-07)
BaseService
Base implementation of Service
BatchResourceLoader
Loads multiple client resources in a single operation.
BatchResourceResult
Result of a batch resource load operation
BatchResourceSource
A single source entry in a batch resource declaration
Binding
Binding definition
BindingEngine
Engine for handling data bindings
BundleAssetProvider
Resolves bundle:// URIs to consumable asset references.
BundlePageAdapter
Internal helper that converts UiSection pages into route mappings and page content for ApplicationDefinition consumption.
BundleUiReadAdapter
Read adapter that implements UiPort from mcp_bundle.
CachedApp
Represents a cached app
CacheManager
Cache manager for MCP UI Runtime
CachePolicy
Cache policy configuration
CacheStats
Cache statistics
Channel
Base class for channels
ChannelActionExecutor
Executes v1.1 channel actions (start, stop, toggle)
ChannelConfig
v1.1: Channel configuration for bidirectional communication
ChannelManager
Manages channel lifecycle and data flow
ChannelMessage
Structured channel message with protocol metadata
ChannelRateLimiter
Sliding window rate limiter
ChannelTypes
Channel types for bidirectional communication
ClientActionHandler
Handles client-side action execution
ClientActionTypes
Client action type constants
ClientPermissions
Permission types for client actions Uses dot-namespaced format per spec standard
ClientResourceResolver
Resolves client:// resource URIs
ClientResourceSchemes
Client resource URI schemes
ClientResourceUri
Parsed client resource URI
ComponentLifecycleHandler
Handles lifecycle events for individual components
CompositeAsyncValidator
Composite async validator that combines multiple validators
ComputedProperty
Represents a computed property that derives its value from other state according to MCP UI DSL v1.0 specification.
ConformanceChecker
Checker for determining conformance level support.
CustomResourceProvider
A registered custom resource provider
CustomResourceProviderRegistry
Registry for custom client:// resource providers.
CustomValidator
Custom validator that uses expressions for validation according to MCP UI DSL v1.0 specification
Debouncer
Debouncer utility for performance optimization according to MCP UI DSL v1.0 specification
DependencyResolveResult
Result of resolving all resources in a dependency graph
DialogAction
Represents an action in a dialog
DialogService
Service for managing dialogs, bottom sheets, and overlays
DslAppMetadata
Top-level application metadata — spec §11.1.
EntryContext
How a definition was entered.
EntryIssuer
Who stands behind the scanned medium.
EntryNotice
A disclosure the host wants rendered before or alongside the document.
EntrySession
Per-runtime holder for entry.* and identity.*.
EntryStateKeys
Reserved state keys the session publishes under. Documents read them through entry.* / identity.* bindings and MUST NOT write them — the state action executor rejects writes to these roots.
ErrorBoundary
Error boundary widget for catching and handling errors according to MCP UI DSL v1.0 specification
ErrorRecovery
Error recovery widget with multiple strategies
ExamplePlugin
Example plugin implementation
ExampleWidgetFactory
Example widget factory for the plugin
ExpressionSandbox
Configuration for expression evaluation sandboxing.
FilePermissionConfig
File permission configuration
FlowControlConfig
Flow control configuration combining inbound and outbound rate limits
FocusGroup
Focus group for managing related focus nodes
FocusRestore
Focus restore widget for preserving focus state
FormFactorScope
InheritedWidget that pins a FormFactor for a subtree.
GlobalErrorHandler
Global error handler registration
HttpPermissionConfig
HTTP permission configuration
I18nLoader
Loader for i18n translations
I18nManager
Manager for internationalization support according to MCP UI DSL v1.0
IdentityContext
The principal a session currently acts as.
IdentityPromotion
The result of an PromotionOutcome.promoted attempt and nothing else — identity is set only when the principal actually changed.
JsonPath
Utility for accessing nested data using path notation
LifecycleDefinition
Lifecycle definition Definition-level lifecycle hooks (spec §1.5, §6.8).
LifecycleManager
Manages component and runtime lifecycle events
LifecycleRunner
Runs a definition's lifecycle hooks in the order the spec fixes (§1.5.2, §6.8.3), for every place a definition can be mounted.
LiveRegion
Live region widget for dynamic content announcements
LiveRegionBuilder
Live region builder for dynamic content
LiveRegionManager
Live region manager for accessibility announcements
MCPFocusManager
Focus manager for accessibility improvements according to MCP UI DSL v1.0 specification
MCPFocusTraversalPolicy
Focus traversal policy for custom navigation
MCPLogger
Logger for MCP UI Runtime that outputs debug messages.
MCPLogRecord
One line of runtime diagnostics.
MCPNotification
Represents a notification in the MCP UI Runtime
MCPPageScopeWrapper
Widget that provides page state scope wrapper
MCPPageWidget
Widget that renders a single page
MCPPlugin
Base class for MCP plugins according to MCP UI DSL v1.0
McpStreamChannel
A channel whose data is pushed by a host-registered MCP stream source.
MCPUIRuntime
Main MCP UI Runtime class that provides the entry point for using the runtime
MCPUIRuntimeHelper
Convenience functions for quick runtime usage
MediaPort
Opens media. Throws to report that this source cannot be played — the widget turns that into onError, never into a rendered message (§6.13.2).
MediaRegistry
The players currently mounted, addressed by the id their document gave them (spec §4.9b).
MediaSession
A media playback the runtime drives from the transport UI.
MessageOrderer
Ensures message ordering for channel streams (CH-08)
Executes navigation actions
Navigation definition
Navigation item
Navigation service for managing app navigation
NotificationAction
Represents an action that can be performed on a notification
NotificationChannel
Represents a notification channel for organizing notifications
NotificationManager
Manages local and system notifications for the MCP UI Runtime
NotificationService
Service for managing notifications within the runtime
PageDefinition
Page definition according to spec
PageStateNotifier
Notifier for page state changes
PageStateScope
Provides a page-specific state scope for multi-page applications
PathSegment
Represents a segment in a path (e.g., "items" or "0")
PermissionCheckResult
Result of a permission check with prompt
PermissionManager
Manages permissions for client actions
PermissionsConfig
v1.1: Permission configuration for client actions
PluginContext
Plugin context provided to plugins during initialization
PluginInfo
Plugin information
PluginManager
Plugin manager for loading and managing plugins
PublisherInfo
Publisher identity information.
RateLimitConfig
Configuration for a single direction (inbound or outbound) rate limit
RateLimiter
Rate limiter utility for controlling action frequency
RemoteValidator
Remote validator for server-side validation
RenderContext
Render context that provides access to runtime services during widget rendering
Renderer
Core rendering engine for MCP UI DSL
ResolverCachedEntry
A simple cached resource entry for the resolver's internal cache. For the richer lifecycle-aware version, see CachedResource in core/client_resource_manager.dart.
ResourceCacheManager
Caching strategies for client resources
ResourceContentType
Content type information derived from a file extension or explicit encoding
ResourceDeclaration
Declaration of a single resource with optional dependency info
ResourceDependencyResolver
Resolves a set of resource declarations respecting dependency order.
ResourceEntry
Tracks a resource through its lifecycle
ResourceResult
Result of a resource resolution
ResourceSizeLimits
Size limit constants matching spec §Binary Resource Handling table
ResourceTransformer
Resource transformation pipeline
RouteInfo
Route information
RouteManager
Manages application routing based on MCP UI DSL spec
RuntimeCapabilities
The set of behaviours this runtime can actually perform, and the objects that perform them.
RuntimeEngine
The main runtime engine that manages the MCP UI Runtime lifecycle and coordinates all runtime services.
RuntimeService
Abstract base class for all runtime services
Service
Service interface for common service operations
ServiceLocator
Service locator for dependency injection according to MCP UI DSL v1.0 specification
ServiceProvider
Service provider widget for Flutter
ServiceRegistry
Registry for managing runtime services
ServicesDefinition
Services definition
ShellPermissionConfig
Shell execution permission configuration
SkipToContent
Skip to content widget for accessibility
SoundPort
Plays short sounds. Overlapping is required by §4.9a: a click during an alarm is both sounds, not the last one.
SoundRequest
One sound playback requested by sound.play.
SplashConfig
Splash screen configuration.
StateChangeEvent
State change event
StateManager
Manages application state with change notifications Supports computed properties according to MCP UI DSL v1.0
StateWatcher
Watches for changes to a specific state path
StateWatcherGroup
A group of watchers that can be managed together
StatusLiveRegion
Status live region for form validation and status updates
SurfaceAssets
What a hosted surface is given besides its properties: the way to read an asset it cannot fetch by URI.
SurfaceEvents
How a host surface reports back into the document. A hosted web view still has to fire the onPageFinished the author wrote, and a hosted PDF still has to report a page change — without this the host draws content the document cannot react to, which is a different way of being disconnected from the truth.
ThemeManager
Theme manager for MCP UI DSL 1.3 — specs/mcp_ui_dsl/05_Theme.md.
Throttler
Throttler utility for performance optimization
TimestampInfo
Creation / update timestamps — spec §11.3.
TouchTargetSize
Minimum touch target sizes per WCAG 2.5.8
TrustLevelManager
Manages the current trust level and validates permission requirements
UIDefinition
Main UI definition that can be either an application or a page
UpdatePolicy
Update policy for checking app updates
ValidationEngine
Validation engine for MCP UI DSL v1.0
ValidationRule
Validation rule
ValidationState
Validation state for managing async validation
Validator
Base validator class
ViewModeResolver
Resolves the effective FormFactor by walking the priority chain defined in the responsive-rendering plan §4:
VirtualizedGridWidget
Virtualized grid widget for performance optimization
VirtualizedListWidget
Virtualized list widget for performance optimization according to MCP UI DSL v1.0 specification
WidgetFactory
Base class for widget factories
WidgetRegistry
Registry for widget factories

Enums

AssetForm
The shape an AssetRef takes, which selects the loader.
BackpressureStrategy
Backpressure strategy for channel data flow control (CH-07)
BindingSource
Binding source types
CacheStrategy
Cache strategy for deciding between cache and network
ChannelMessageDirection
Direction of a channel message
ChannelMessageType
Type of channel message
ChannelState
Channel lifecycle state enum (CH-05)
ConformanceLevel
Conformance level definitions for MCP UI DSL v1.0
DialogType
Types of dialogs
ErrorRecoveryStrategy
Error recovery strategies
EvictionPolicy
Eviction policy for removing cache entries
FormFactor
Device form factor class per Material 3 window-size taxonomy.
IdentityState
Who the current session acts as (§8.9.2).
IdentitySubjectKind
The kind of party a principal is.
LifecycleEvent
Enumeration of lifecycle events supported by the runtime
LiveRegionType
Live region types for accessibility announcements according to MCP UI DSL v1.0 specification
NotificationEvent
Events that can occur with notifications
NotificationImportance
Importance levels for notifications
NotificationType
Types of notifications supported by the runtime
OfflineMode
Offline mode options
PromotionOutcome
Why a promotion attempt ended the way it did (§8.9.3).
RuntimeCapability
Behaviours a document can ask for that the runtime cannot perform on its own: sound comes out, media decodes, a page loads, a document paginates, tiles are fetched, a vector animation plays.
ServiceStatus
Service status
SnackbarType
Types of snackbars
TrustLevel
Represents the trust level granted to a UI context
UIDefinitionType
Core models for MCP UI DSL.
ValidationRuleType
Validation rule types
ViewMode
User-selected view-mode pin.

Mixins

DebounceMixin
Mixin to add debouncing capabilities to widgets
FormValidationMixin<T extends StatefulWidget>
Form validation mixin for widgets
ServiceLocatorMixin<T extends StatefulWidget>
Mixin to add service locator access to widgets
ThrottleMixin
Mixin to add throttling capabilities to widgets

Extensions

NotificationActionJson on NotificationAction
Extension methods for NotificationAction
VirtualizationExtension on RenderContext
Extension to integrate virtualized lists with existing list widgets

Functions

decodeDataUri(String uri) → Uint8List?
Decodes a data: URI payload, base64 or percent-encoded.
readAction(dynamic raw, RenderContext context) → Map<String, dynamic>?
The single-action view of an Action slot. A list collapses to a sequence, which is what running them in order means (§4.6) — not to its first entry, which would silently drop the rest.
readActions(dynamic raw, RenderContext context) → List<Map<String, dynamic>>
An Action slot as the list of actions to run. The slot accepts one action, a list of them, or a binding resolving to either; casting it to Map<String, dynamic>? renders an error for the list form.
readBool(dynamic raw, RenderContext context) → bool?
A boolean slot, read the way §3 says every value may be written.
readDimension(dynamic raw, RenderContext context) → double?
A Dimension slot, read the way the registry declares it — a number, the v1.0 {value, unit} object, or a binding resolving to either. A factory that writes numberOf(properties['width'], context) throws on two of the three forms the same document is told it may use.
readEnum(dynamic raw, RenderContext context) → String?
An enum-valued slot: resolve the binding, then take the value only if it resolved to a string. context.resolve<String?> throws when the document legitimately carries another shape in the same slot (a button.style object, for instance), which turns a widened schema into a render error.
readInt(dynamic raw, RenderContext context) → int?
An integer slot — a count of columns, a page index, a maximum length.
readList(dynamic raw, RenderContext context) → List?
A list slot — rows, items, tabs, options, nodes.
readNumber(dynamic raw, RenderContext context) → double?
A number slot. Same reason as readBool; ?.toDouble() on a binding string throws rather than reverting, which is worse.
readString(dynamic raw, RenderContext context) → String?
A string slot, resolved. as String? answers null for a bound value the binding engine would have produced from a number.

Typedefs

AssetBytesReader = Future<Uint8List?> Function()
Reads the bytes behind an asset the host cannot open by URI — a sound inside a bundle, one served by an origin, one the client holds.
BundleAssetReader = Future<Uint8List?> Function(String path)
Reads a path inside the ambient origin's bundle.
ClientAssetReader = Future<Uint8List?> Function(String path)
Reads a client:// resource held by the host process.
CustomResourceHandler = Future<ResourceResult> Function(String path, Map<String, dynamic>? config)
Handler function signature for custom resource providers.
IdentityPromoter = Future<IdentityPromotion> Function()
Asks the host to identify the current viewer, or to let go of that identity.
NotificationListener = void Function(NotificationEvent event, MCPNotification notification, String? actionId)
Callback type for notification events
OriginAssetReader = Future<Uint8List?> Function(String uri, Map<String, dynamic>? origin)
Reads a resource uri from a named origin via MCP resources/read.
RenderInspector = Widget Function(Widget child, Map<String, dynamic> node)
Wrap callback supplied by host tooling (e.g. the AppPlayer Builder / vibe editor) so each rendered widget can be paired with its source JSON node for hit-testing. The runtime invokes the wrapper exactly once per renderWidget call. When no wrapper is supplied the runtime follows the fast path with zero per-node overhead.
StateChangeCallback = Future<void> Function(dynamic newValue, dynamic oldValue)
Represents a function that is called when a watched state value changes
StreamSourceResolver = Stream? Function(String uri, Map<String, dynamic> params)
Resolves a stream-source uri (with subscribe params) to a live stream, or null when no source is registered for the uri's scheme.
SurfaceBuilder = Widget? Function(BuildContext context, Map<String, dynamic> properties, SurfaceEvents events, SurfaceAssets assets)
Builds a platform surface for a widget the runtime cannot draw itself. Returning null is the same statement as not being wired: the capability is absent, and the widget reports it.

Exceptions / Errors

CapabilityUnavailable
Raised when a document asks for a behaviour this runtime does not have. Carried to the widget's onError and the diagnostic channel — never rendered in place of the content (§6.13.2).
CircularDependencyException
Exception thrown when circular dependency is detected
PluginException
Plugin exception
ResourceCircularDependencyException
Exception thrown when a circular dependency is detected at parse time
ServiceException
Exception thrown when service operations fail
ServiceNotFoundException
Exception thrown when a service is not found