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
- type ResourceReader
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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 ¶
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.
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.
Source Files