Phantom.UI (phantom_mcp v0.5.0)

Metadata for the MCP Apps extension (io.modelcontextprotocol/ui).

MCP Apps allow servers to deliver interactive HTML user interfaces that render inside MCP hosts as sandboxed iframes. This module encapsulates the UI metadata for both tools (linking to a UI resource) and resources (CSP, permissions, sandbox configuration).

See https://apps.extensions.modelcontextprotocol.io/

Summary

Types

t()

visibility()

Functions

build(attrs)

Build a %Phantom.UI{} from a keyword list or map.

model_visible?(tool)

Returns true if the tool should appear in tools/list (visible to the model).

to_resource_meta(ui)

Produce the _meta map for a resource's JSON representation.

to_tool_meta(ui)

Produce the _meta map for a tool's JSON representation.

Types

t()

@type t() :: %Phantom.UI{
  base_uri_domains: [String.t()] | nil,
  connect_domains: [String.t()] | nil,
  domain: String.t() | nil,
  frame_domains: [String.t()] | nil,
  permissions: [atom()] | nil,
  prefers_border: boolean() | nil,
  resource_domains: [String.t()] | nil,
  resource_uri: String.t() | nil,
  visibility: [visibility()]
}

visibility()

@type visibility() :: :model | :app

Functions

build(attrs)

@spec build(Keyword.t() | map()) :: t() | nil

Build a %Phantom.UI{} from a keyword list or map.

Returns nil if no UI-related attributes are present.

Raises ArgumentError if visibility contains unknown values. Valid visibility values are :model and :app.

model_visible?(tool)

@spec model_visible?(Phantom.Tool.t()) :: boolean()

Returns true if the tool should appear in tools/list (visible to the model).

Tools without UI metadata are always visible. Tools with UI are visible when their visibility list includes :model.

to_resource_meta(ui)

@spec to_resource_meta(t() | nil) :: %{ui: map()} | nil

Produce the _meta map for a resource's JSON representation.

Includes CSP domains, permissions, domain, and border preference. Returns nil when no resource-side metadata is present.

to_tool_meta(ui)

@spec to_tool_meta(t() | nil) :: %{ui: map()} | nil

Produce the _meta map for a tool's JSON representation.

Returns nil when no UI is configured, which gets stripped by remove_nils. Visibility atoms are serialized to strings for the JSON wire format.