meta

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 27, 2026 License: Apache-2.0 Imports: 1 Imported by: 0

Documentation

Overview

Package meta provides typed manipulation of tool and resource `_meta` payloads for the MCP UI extension proposed by SEP-1865 (MCP Apps).

All `_meta` key spellings are sourced byte-for-byte from the upstream MCP Apps spec commit pinned in the module README. Helpers in this package perform exact identity reads/writes only; there is no fallback guessing.

Index

Constants

View Source
const (
	// FieldResourceUri is the leaf key under `_meta.ui` advertising the
	// `ui://...` URI that a tool's result can be rendered through.
	// Full path: `_meta.ui.resourceUri`.
	FieldResourceUri = "resourceUri"

	// FieldAllowedTools is the leaf key under `_meta.ui` carrying the per-
	// resource tool allowlist that guest-originated `tools/call` requests
	// must satisfy. Full path: `_meta.ui.allowedTools`.
	FieldAllowedTools = "allowedTools"

	// FieldAllowedToolBundles is the leaf key under `_meta.ui` carrying the
	// exact tool bundle ids the host must use when executing guest-originated
	// `tools/call` requests through an approval-aware server path.
	// Full path: `_meta.ui.allowedToolBundles`.
	FieldAllowedToolBundles = "allowedToolBundles"

	// FieldContentHash is the leaf key under `_meta.ui` carrying the
	// canonical content hash of a UI resource payload.
	// Full path: `_meta.ui.contentHash`.
	FieldContentHash = "contentHash"

	// FieldProtocolVersion is the leaf key under `_meta.ui` carrying the
	// `viant/mcp-ui` semantic version that produced the resource. Full
	// path: `_meta.ui.protocolVersion`.
	FieldProtocolVersion = "protocolVersion"

	// FieldRendererURL is the leaf key under `_meta.ui` carrying an explicit
	// same-origin renderer page URL the host may load instead of raw srcdoc when
	// the resource requires a richer authenticated runtime.
	FieldRendererURL = "rendererUrl"

	// FieldSandbox is the leaf key under `_meta.ui` carrying an explicit iframe
	// sandbox policy string for this resource. Empty means host default.
	FieldSandbox = "sandbox"

	// FieldCSP is the leaf key under `_meta.ui` carrying an explicit srcdoc CSP
	// policy override for browser hosts that assemble HTML via iframe.srcdoc.
	// Empty means host default deny-by-default CSP.
	FieldCSP = "csp"

	// FieldCSPPolicy is the leaf key under `_meta.ui` carrying a structured CSP
	// relaxation policy for browser hosts that assemble HTML via iframe.srcdoc.
	// Empty means host default deny-by-default CSP with no relaxations.
	FieldCSPPolicy = "cspPolicy"

	// FieldFallback is the leaf key under `_meta.ui` opting a resource or
	// tool in to embedded-resource compatibility behavior. Full path:
	// `_meta.ui.fallback`. The only currently meaningful value is the
	// constant FallbackEmbedded.
	FieldFallback = "fallback"
)

Tool-level `_meta.ui.*` keys (joined dotted paths are documented for readers; the constants below are bare leaf names because the helpers operate on the nested map under NamespaceUI).

View Source
const FallbackEmbedded = "embedded"

FallbackEmbedded is the only fallback value documented by the plan today.

View Source
const (
	// NamespaceUI is the parent key under which all UI extension metadata
	// lives in a `_meta` map.
	NamespaceUI = "ui"
)

Top-level `_meta` namespace for the MCP UI extension.

Variables

This section is empty.

Functions

func SetEmbeddedResourceUI

func SetEmbeddedResourceUI(resource *schema.EmbeddedResource, ui ResourceUI)

SetEmbeddedResourceUI writes ui under both the top-level embedded resource metadata and the embedded resource payload metadata.

func SetReadResultContentsUI

func SetReadResultContentsUI(contents *schema.ReadResourceResultContentsElem, ui ResourceUI)

SetReadResultContentsUI writes ui under contents.Meta[NamespaceUI].

func SetResourceContentsUI

func SetResourceContentsUI(contents *schema.ResourceContents, ui ResourceUI)

SetResourceContentsUI writes ui under contents.Meta[NamespaceUI].

contents must be non-nil.

func SetResourceUI

func SetResourceUI(resource *schema.Resource, ui ResourceUI)

SetResourceUI writes ui under resource.Meta[NamespaceUI]. It preserves any other `_meta.*` entries already on the resource. Passing the zero ResourceUI removes the `_meta.ui` entry.

resource must be non-nil.

func SetTextResourceContentsUI

func SetTextResourceContentsUI(contents *schema.TextResourceContents, ui ResourceUI)

SetTextResourceContentsUI writes ui under contents.Meta[NamespaceUI].

func SetToolUI

func SetToolUI(tool *schema.Tool, ui ToolUI)

SetToolUI writes ui under tool.Meta[NamespaceUI]. It preserves any other `_meta.*` entries already on the tool and any other keys under `_meta.ui.*` that are not modeled by ToolUI. Passing the zero ToolUI is equivalent to ClearToolUI and removes the `_meta.ui` entry.

tool must be non-nil.

Types

type CSPPolicy

type CSPPolicy struct {
	ScriptSrc           []string `json:"scriptSrc,omitempty" yaml:"scriptSrc,omitempty"`
	StyleSrc            []string `json:"styleSrc,omitempty" yaml:"styleSrc,omitempty"`
	ConnectSrc          []string `json:"connectSrc,omitempty" yaml:"connectSrc,omitempty"`
	ImgSrc              []string `json:"imgSrc,omitempty" yaml:"imgSrc,omitempty"`
	FontSrc             []string `json:"fontSrc,omitempty" yaml:"fontSrc,omitempty"`
	ScriptStrictDynamic bool     `json:"scriptStrictDynamic,omitempty" yaml:"scriptStrictDynamic,omitempty"`
}

CSPPolicy is the explicit, bounded per-resource CSP relaxation contract for srcdoc-rendered widgets. It is intentionally narrow: only the allowlists and strict-dynamic toggle the plan currently calls out are modeled here.

type ResourceUI

type ResourceUI struct {
	// AllowedTools is the authoritative per-resource tool allowlist that
	// guest-originated `tools/call` requests are validated against.
	AllowedTools []string

	// AllowedToolBundles is the exact bundle selection the host must apply
	// when executing guest-originated `tools/call` requests so approval and
	// other tool-surface metadata comes from the canonical bundle layer.
	AllowedToolBundles []string

	// ContentHash is the canonical content hash of the resource payload.
	ContentHash string

	// ProtocolVersion is the `viant/mcp-ui` semantic version that produced
	// the resource.
	ProtocolVersion string

	// RendererURL is an optional same-origin page URL that the host may load
	// instead of srcdoc when the resource needs a richer authenticated runtime.
	RendererURL string

	// Sandbox is an optional iframe sandbox string for this resource.
	Sandbox string

	// CSP is an optional explicit srcdoc CSP policy override. Empty means host
	// default deny-by-default nonce-based policy.
	CSP string

	// CSPPolicy is the preferred structured srcdoc CSP relaxation contract for
	// explicitly approved advanced widgets. Empty means no relaxation.
	CSPPolicy *CSPPolicy

	// Fallback opts the resource in to embedded-resource fallback. Empty
	// means no fallback.
	Fallback string
}

ResourceUI is the typed representation of `_meta.ui` as it appears on a schema.Resource or on a schema.ResourceContents entry.

func GetEmbeddedResourceUI

func GetEmbeddedResourceUI(resource *schema.EmbeddedResource) (ResourceUI, bool)

GetEmbeddedResourceUI reads `_meta.ui` from the embedded resource payload metadata, falling back to the top-level embedded resource metadata only if the payload metadata is absent.

func GetReadResultContentsUI

func GetReadResultContentsUI(contents *schema.ReadResourceResultContentsElem) (ResourceUI, bool)

GetReadResultContentsUI reads `_meta.ui` from a resources/read contents entry.

func GetResourceContentsUI

func GetResourceContentsUI(contents *schema.ResourceContents) (ResourceUI, bool)

GetResourceContentsUI reads `_meta.ui` from the resource contents entry.

func GetResourceUI

func GetResourceUI(resource *schema.Resource) (ResourceUI, bool)

GetResourceUI reads `_meta.ui` from the resource.

func GetTextResourceContentsUI

func GetTextResourceContentsUI(contents *schema.TextResourceContents) (ResourceUI, bool)

GetTextResourceContentsUI reads `_meta.ui` from a text resource contents entry.

type ToolUI

type ToolUI struct {
	// ResourceUri is the canonical `ui://...` resource advertised by the
	// tool. Required when emitting UI metadata.
	ResourceUri string

	// AllowedTools is the per-resource tool allowlist mirror that may be
	// advertised on a tool for discovery purposes. The authoritative copy
	// lives on the resource itself.
	AllowedTools []string

	// Fallback opts the tool in to embedded-resource fallback when peers
	// do not negotiate UI extension capability. Empty means no fallback.
	Fallback string
}

ToolUI is the typed representation of `_meta.ui` as it appears on a schema.Tool. Fields with their zero values are omitted on write.

func GetToolUI

func GetToolUI(tool *schema.Tool) (ToolUI, bool)

GetToolUI reads `_meta.ui` from the tool and returns the typed view plus true if `_meta.ui` is present. A present-but-empty `_meta.ui` returns ToolUI{}, true.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL