Attach rich content¶

Use the six content constructors to keep text, binary media and resource identity separate:

Constructor	Owned value	Accessors
`Text(text)`	UTF-8 text	`Text`
`Image(bytes, mime)`	Image bytes and MIME declaration	`Bytes`, `MIMEType`
`Audio(bytes, mime)`	Audio bytes and MIME declaration	`Bytes`, `MIMEType`
`ResourceLink(ref)`	Resource reference	`ResourceRef`
`EmbeddedText(ref, text)`	Reference and text	`ResourceRef`, `Text`
`EmbeddedBlob(ref, bytes)`	Reference and blob	`ResourceRef`, `Bytes`

Create a reference with NewResourceRef(ResourceRefSpec{URI: "asset://project/preview", Name: "preview"}). Its description may also contain a title, description, MIME declaration, metadata and annotations. Description returns detached annotation storage. A URI must be absolute and contain no credentials; the module reserves the mcp-warning scheme for later resource diagnostics. Creating a reference never fetches it.

NewResult validates content when assembling it. Image/audio MIME declarations must match their category; the module does not decode media to certify its bytes. Empty embedded text and blobs are valid.

Create application metadata with NewMetadata("example.com", map[string]json.RawMessage{...}). Keys in the input map are local names; Values returns fully qualified keys such as example.com/selection. Use WithContentMetadata and WithResultMetadata to attach it. Duplicate keys fail rather than replacing earlier data. Resource reference metadata describes the reference; content metadata describes its containing block. They remain separate locations and are not automatically merged.

Use WithContentAnnotations for audience, priority and last-modified hints. Audiences are user and assistant, priority is finite and between zero and one, and timestamps normalize to UTC. ContentMetadata and ContentAnnotations work across content kinds and return detached mutable storage. Hints do not confer permission to discover or read a resource.

For an Apps presentation, construct a typed value and keep useful fallback content:

presentation, err := mcp.NewPresentation(mcp.PresentationSpec{
    View: "candidate-gallery",
    Data: json.RawMessage(`{"selected":3}`),
})
if err != nil {
    return err
}
result, err := mcp.NewResult(
    []mcp.Content{mcp.Text("Selected candidate 3")},
    mcp.WithPresentation(presentation),
)

Data must contain a JSON value; use explicit null when there is no view data. The helper writes the reserved go.phpboyscout.uk/mcp.presentation metadata. Generic metadata cannot override that key. The upcoming adapter will check configured view IDs and map the static Apps shell. This constructor provides owned presentation data only; it does not host a UI. See ExampleNewPresentation for a runnable example.