apps

Documentation

Overview

Package apps provides the MCP Apps UI resource registry and embedded HTML apps. It manages registration and retrieval of interactive HTML resources that MCP clients (like Claude Desktop) can render alongside tool results.

Index

• Constants
• func ExtractAppName(uri string) string
• func RegisterEmbeddedApps(registry *UIResourceRegistry) error
• type AppInfo
• type Compiler
  • func NewCompiler() (*Compiler, error)
  • func (c *Compiler) Catalog() *ComponentCatalog
  • func (c *Compiler) Compile(spec *loomv1.UIAppSpec) ([]byte, error)
  • func (c *Compiler) ListComponentTypes() []*loomv1.ComponentType
  • func (c *Compiler) Validate(spec *loomv1.UIAppSpec) error
• type ComponentCatalog
  • func NewComponentCatalog() *ComponentCatalog
  • func (c *ComponentCatalog) HasChildren(typ string) bool
  • func (c *ComponentCatalog) IsValidType(typ string) bool
  • func (c *ComponentCatalog) ToProto() []*loomv1.ComponentType
  • func (c *ComponentCatalog) ValidTypes() []string
• type UIResource
• type UIResourceRegistry
  • func NewUIResourceRegistry() *UIResourceRegistry
  • func (r *UIResourceRegistry) AppHTML(name string) ([]byte, error)
  • func (r *UIResourceRegistry) AppNames() []string
  • func (r *UIResourceRegistry) Count() int
  • func (r *UIResourceRegistry) CreateApp(name, displayName, description string, html []byte, overwrite bool) (*AppInfo, bool, error)
  • func (r *UIResourceRegistry) Delete(uri string) error
  • func (r *UIResourceRegistry) DeleteApp(name string) error
  • func (r *UIResourceRegistry) Get(uri string) (*UIResource, error)
  • func (r *UIResourceRegistry) GetAppHTML(name string) ([]byte, *AppInfo, error)
  • func (r *UIResourceRegistry) List() []protocol.Resource
  • func (r *UIResourceRegistry) ListAppInfo() []AppInfo
  • func (r *UIResourceRegistry) Read(uri string) (*protocol.ReadResourceResult, error)
  • func (r *UIResourceRegistry) Register(res *UIResource) error
  • func (r *UIResourceRegistry) SetOnChange(fn func())
  • func (r *UIResourceRegistry) UpdateApp(name, displayName, description string, html []byte) (*AppInfo, error)
  • func (r *UIResourceRegistry) Upsert(res *UIResource) (created bool, err error)

Constants

const (
	MaxComponents          = 50
	MaxNestingDepth        = 10
	MaxComponentPropsBytes = 64 * 1024  // 64 KB per component props
	MaxSpecBytes           = 512 * 1024 // 512 KB total spec
)

Structural limits for spec validation.

const (
	// DefaultMaxDynamic is the maximum number of dynamic (agent-created) apps.
	DefaultMaxDynamic = 100

	// DefaultMaxTotalBytes is the maximum total HTML bytes for dynamic apps (50 MB).
	DefaultMaxTotalBytes int64 = 50 * 1024 * 1024
)

Functions

func ExtractAppName

func ExtractAppName(uri string) string

ExtractAppName extracts the short app name from a ui:// URI. For example, "ui://loom/data-chart" returns "data-chart".

func RegisterEmbeddedApps

func RegisterEmbeddedApps(registry *UIResourceRegistry) error

RegisterEmbeddedApps registers all built-in MCP App HTML resources. Returns an error if any registration fails (e.g., duplicate URI on second call).

Types

type AppInfo

type AppInfo struct {
	Name          string
	URI           string
	DisplayName   string
	Description   string
	MimeType      string
	PrefersBorder bool
	Dynamic       bool
}

AppInfo holds metadata about a UI app for use by the gRPC server. This avoids the server importing the apps package directly.

type Compiler

type Compiler struct {
	// contains filtered or unexported fields
}

Compiler validates UIAppSpec and compiles it to standalone HTML.

func NewCompiler

func NewCompiler() (*Compiler, error)

NewCompiler creates a new compiler with the embedded template and runtime.

func (*Compiler) Catalog

func (c *Compiler) Catalog() *ComponentCatalog

Catalog returns the compiler's component catalog.

func (*Compiler) Compile

func (c *Compiler) Compile(spec *loomv1.UIAppSpec) ([]byte, error)

Compile validates the spec and compiles it to a standalone HTML document.

func (*Compiler) ListComponentTypes

func (c *Compiler) ListComponentTypes() []*loomv1.ComponentType

ListComponentTypes returns proto ComponentType messages for the discovery RPC.

func (*Compiler) Validate

func (c *Compiler) Validate(spec *loomv1.UIAppSpec) error

Validate checks a spec against structural limits, component type validity, and security constraints (dangerous keys/values).

type ComponentCatalog

type ComponentCatalog struct {
	// contains filtered or unexported fields
}

ComponentCatalog holds the definitions for all supported component types. It is used for validation and for the ListComponentTypes discovery RPC.

func NewComponentCatalog

func NewComponentCatalog() *ComponentCatalog

NewComponentCatalog creates a catalog with all 14 built-in component types.

func (*ComponentCatalog) HasChildren

func (c *ComponentCatalog) HasChildren(typ string) bool

HasChildren returns true if the component type supports children.

func (*ComponentCatalog) IsValidType

func (c *ComponentCatalog) IsValidType(typ string) bool

IsValidType checks whether a component type exists in the catalog.

func (*ComponentCatalog) ToProto

func (c *ComponentCatalog) ToProto() []*loomv1.ComponentType

ToProto converts the catalog to proto ComponentType messages for the ListComponentTypes RPC.

func (*ComponentCatalog) ValidTypes

func (c *ComponentCatalog) ValidTypes() []string

ValidTypes returns the sorted list of valid component type names.

type UIResource

type UIResource struct {
	URI         string                   // ui:// URI identifying this resource
	Name        string                   // Human-readable name
	Description string                   // Description of what this UI shows
	MIMEType    string                   // MIME type (typically protocol.ResourceMIME)
	HTML        []byte                   // Raw HTML content
	Meta        *protocol.UIResourceMeta // Security and display metadata
	Dynamic     bool                     // true = agent-created, false = embedded
}

UIResource represents an HTML app that can be rendered by an MCP client.

type UIResourceRegistry

type UIResourceRegistry struct {
	// contains filtered or unexported fields
}

UIResourceRegistry manages UI resources that the MCP server exposes. Thread-safe for concurrent access.

func NewUIResourceRegistry

func NewUIResourceRegistry() *UIResourceRegistry

NewUIResourceRegistry creates a new empty registry.

func (*UIResourceRegistry) AppHTML

func (r *UIResourceRegistry) AppHTML(name string) ([]byte, error)

AppHTML returns the raw HTML content for an app identified by short name. Returns an error if no app matches the given name.

func (*UIResourceRegistry) AppNames

func (r *UIResourceRegistry) AppNames() []string

AppNames returns sorted short names extracted from all registered URIs. For example, "ui://loom/data-chart" yields "data-chart".

func (*UIResourceRegistry) Count

func (r *UIResourceRegistry) Count() int

Count returns the number of registered resources.

func (*UIResourceRegistry) CreateApp

func (r *UIResourceRegistry) CreateApp(name, displayName, description string, html []byte, overwrite bool) (*AppInfo, bool, error)

CreateApp creates a dynamic app from compiled HTML. It builds the UIResource, checks existence atomically, and returns the app info. This implements the AppProvider interface for the gRPC server.

func (*UIResourceRegistry) Delete

func (r *UIResourceRegistry) Delete(uri string) error

Delete removes a dynamic UI resource by URI. Rejects deletion of embedded resources.

func (*UIResourceRegistry) DeleteApp

func (r *UIResourceRegistry) DeleteApp(name string) error

DeleteApp deletes a dynamic app by short name.

func (*UIResourceRegistry) Get

func (r *UIResourceRegistry) Get(uri string) (*UIResource, error)

Get returns a UIResource by its URI, or an error if not found.

func (*UIResourceRegistry) GetAppHTML

func (r *UIResourceRegistry) GetAppHTML(name string) ([]byte, *AppInfo, error)

GetAppHTML returns the HTML content and metadata for an app by short name. Returns an error if no app matches the given name.

func (*UIResourceRegistry) List

func (r *UIResourceRegistry) List() []protocol.Resource

List returns all registered resources as MCP Resource objects. Results are sorted by URI for deterministic ordering.

func (*UIResourceRegistry) ListAppInfo

func (r *UIResourceRegistry) ListAppInfo() []AppInfo

ListAppInfo returns metadata for all registered apps, sorted by name.

func (*UIResourceRegistry) Read

func (r *UIResourceRegistry) Read(uri string) (*protocol.ReadResourceResult, error)

Read returns the contents of a resource by URI. Returns an error if the resource is not found.

func (*UIResourceRegistry) Register

func (r *UIResourceRegistry) Register(res *UIResource) error

Register adds a UI resource to the registry. Returns an error if a resource with the same URI is already registered.

func (*UIResourceRegistry) SetOnChange

func (r *UIResourceRegistry) SetOnChange(fn func())

SetOnChange registers a callback that is invoked after any mutation (Upsert, Delete). The callback is called outside the lock to prevent deadlocks. Only one callback can be registered; a new call replaces the previous one.

func (*UIResourceRegistry) UpdateApp

func (r *UIResourceRegistry) UpdateApp(name, displayName, description string, html []byte) (*AppInfo, error)

UpdateApp updates an existing dynamic app with new HTML. Returns an error if the app doesn't exist or is embedded.

func (*UIResourceRegistry) Upsert

func (r *UIResourceRegistry) Upsert(res *UIResource) (created bool, err error)

Upsert creates or replaces a dynamic UI resource. It rejects overwrites of embedded (non-dynamic) resources. Returns true if a new resource was created, false if an existing dynamic resource was replaced.