compat

Documentation

Overview

Package compat provides compatibility helpers for the MCP UI extension proposed by SEP-1865 (MCP Apps).

The package owns the exact, doc-defined switching rule between:

• the negotiated UI extension path — server emits `_meta.ui.resourceUri` and the host calls `resources/read` to fetch the canonical payload; and
• the embedded-resource fallback path — server appends a UI EmbeddedResource directly to the tool result, used only when the peer does NOT advertise UI extension capability AND the tool/resource has explicitly opted in via `_meta.ui.fallback = "embedded"`.

There are no heuristics: a tool/resource that does not advertise both `_meta.ui.resourceUri` and `_meta.ui.fallback = "embedded"` cannot receive an embedded-resource fallback through these helpers, even if the peer is UI-incapable.

Index

• func BuildEmbeddedFallback(ctx context.Context, reader ResourceReader, uri string) (*schema.EmbeddedResource, error)
• func ClientUICapable(caps *schema.ClientCapabilities) bool
• func ResourceOptsInToEmbeddedFallback(ui meta.ResourceUI) bool
• func ServerUICapable(caps *schema.ServerCapabilities) bool
• func ToolOptsInToEmbeddedFallback(ui meta.ToolUI) bool
• type Mode
  • func SelectResourceMode(clientCaps *schema.ClientCapabilities, resourceUI meta.ResourceUI) Mode
  • func SelectToolMode(clientCaps *schema.ClientCapabilities, toolUI meta.ToolUI) Mode
  • func (m Mode) String() string
• type ResourceReader

Functions

func BuildEmbeddedFallback

func BuildEmbeddedFallback(ctx context.Context, reader ResourceReader, uri string) (*schema.EmbeddedResource, error)

BuildEmbeddedFallback fetches the canonical resource by uri via reader and wraps the first text contents entry as a UI EmbeddedResource suitable for appending to CallToolResult.Content.

The helper preserves the canonical `_meta.ui` (contentHash, protocolVersion, etc.) of the resource read result rather than re-assembling HTML. The MIME type is taken from the resource contents when present; otherwise it defaults to capabilities.ResourceMimeType.

Returns an error if reader is nil, the read returns no text contents, or the read itself fails.

func ClientUICapable

func ClientUICapable(caps *schema.ClientCapabilities) bool

ClientUICapable reports whether the supplied client capabilities advertise the UI extension under Experimental[capabilities.ExtensionName]. nil caps are treated as not capable.

func ResourceOptsInToEmbeddedFallback

func ResourceOptsInToEmbeddedFallback(ui meta.ResourceUI) bool

ResourceOptsInToEmbeddedFallback reports whether the resource's `_meta.ui.fallback` equals `"embedded"`.

func ServerUICapable

func ServerUICapable(caps *schema.ServerCapabilities) bool

ServerUICapable reports whether the supplied server capabilities advertise the UI extension under Experimental[capabilities.ExtensionName].

func ToolOptsInToEmbeddedFallback

func ToolOptsInToEmbeddedFallback(ui meta.ToolUI) bool

ToolOptsInToEmbeddedFallback reports whether the tool's `_meta.ui.fallback` equals `"embedded"`. No other values are recognized.

Types

type Mode

type Mode int

Mode is the rendering mode a server should apply to a UI-bearing tool result, given the negotiated UI extension capability and the tool's or resource's explicit fallback opt-in.

const (
	// ModeNone means no UI rendering applies. Either the tool advertises no
	// UI resource at all, or UI capability is absent and the tool/resource
	// has not opted in to embedded-resource fallback.
	ModeNone Mode = iota

	// ModeCapability means UI extension capability is negotiated and the
	// host follows the `_meta.ui.resourceUri` + `resources/read` flow on its
	// own. The server should NOT emit an embedded UI resource.
	ModeCapability

	// ModeEmbeddedFallback means UI extension capability is NOT negotiated
	// but the tool or resource has explicitly opted in via
	// `_meta.ui.fallback = "embedded"`. The server MUST emit a UI
	// EmbeddedResource in the tool result so a non-UI-capable host can still
	// render it.
	ModeEmbeddedFallback
)

func SelectResourceMode

func SelectResourceMode(clientCaps *schema.ClientCapabilities, resourceUI meta.ResourceUI) Mode

SelectResourceMode is the resource-side analogue used when the opt-in is declared on the resource itself rather than on the tool that advertises it. The decision is exact in the same way as SelectToolMode.

func SelectToolMode

func SelectToolMode(clientCaps *schema.ClientCapabilities, toolUI meta.ToolUI) Mode

SelectToolMode returns the rendering mode a server should apply to a tool result. The decision is exact:

• if the tool advertises no `_meta.ui.resourceUri` => ModeNone.
• if UI extension capability is negotiated => ModeCapability.
• else if the tool opts in via `_meta.ui.fallback = "embedded"` => ModeEmbeddedFallback.
• otherwise => ModeNone.

func (Mode) String

func (m Mode) String() string

String reports a stable identifier for the mode, useful in logs and tests.

type ResourceReader

type ResourceReader interface {
	ReadResource(ctx context.Context, uri string) (*schema.ReadResourceResult, error)
}

ResourceReader is the narrow interface a host runtime implements so the compat helpers can fetch the canonical `ui://...` payload without coupling this package to any specific server implementation.

Implementations should resolve uri exactly; partial matches are not permitted.