# `ExMCP.Content`
[🔗](https://github.com/azmaveth/ex_mcp/blob/v1.0.0/lib/ex_mcp/content.ex#L1)

Content handling utilities for MCP messages.

Builds and validates **protocol content blocks** used in tool results, prompts,
sampling, and resources:

- **text** — plain text
- **image** — base64 payload + MIME type (MCP content type, not image processing)
- **audio** — base64 payload + MIME type
- **resource** — embedded resource reference
- **tool_use** / **tool_result** — sampling content (2025-11-25)

MCP and ACP specify how to *carry* images (and icons with URLs). They do **not**
require compress/resize/thumbnail APIs. Those stubs live under experimental
modules (`ExMCP.Content.Transformer`, `Builders`) and are deprecated for 2.0.0.

# `audio`

```elixir
@spec audio(String.t(), String.t(), map() | nil) :: ExMCP.Types.audio_content()
```

Creates an audio content object.

## Parameters
  - data: Base64-encoded audio data
  - mime_type: MIME type of the audio (e.g., "audio/mp3", "audio/wav", "audio/ogg")
  - annotations: Optional annotations

## Examples

    iex> ExMCP.Content.audio(base64_data, "audio/mp3")
    %{type: :audio, data: base64_data, mimeType: "audio/mp3"}

# `get_type`

```elixir
@spec get_type(ExMCP.Types.content()) :: ExMCP.Types.content_type()
```

Extracts the type of a content object.

# `image`

```elixir
@spec image(String.t(), String.t(), map() | nil) :: ExMCP.Types.image_content()
```

Creates an image content object.

## Parameters
  - data: Base64-encoded image data
  - mime_type: MIME type of the image (e.g., "image/png", "image/jpeg")
  - annotations: Optional annotations

## Examples

    iex> ExMCP.Content.image(base64_data, "image/png")
    %{type: :image, data: base64_data, mimeType: "image/png"}

# `resource`

```elixir
@spec resource(map(), map() | nil) :: ExMCP.Types.embedded_resource()
```

Creates a resource content object.

## Parameters
  - resource: Resource object with uri, name, description, etc.
  - annotations: Optional annotations

## Examples

    iex> resource = %{uri: "file:///example.txt", name: "Example"}
    iex> ExMCP.Content.resource(resource)
    %{type: :resource, resource: %{uri: "file:///example.txt", name: "Example"}}

# `text`

```elixir
@spec text(String.t(), map() | nil) :: ExMCP.Types.text_content()
```

Creates a text content object.

## Examples

    iex> ExMCP.Content.text("Hello, world!")
    %{type: :text, text: "Hello, world!"}

# `tool_result`

```elixir
@spec tool_result(String.t(), [map()], keyword()) :: ExMCP.Types.tool_result_content()
```

Creates a tool result content object (new in 2025-11-25).

Used in sampling/createMessage to provide the result of a tool call.

## Parameters
  - tool_use_id: The ID of the tool_use this is a result for
  - content: List of content items (the tool's output)
  - opts: Optional keyword list with `:is_error` boolean

# `tool_use`

```elixir
@spec tool_use(String.t(), String.t(), map()) :: ExMCP.Types.tool_use_content()
```

Creates a tool use content object (new in 2025-11-25).

Used in sampling/createMessage responses when the model wants to call a tool.

## Parameters
  - id: Unique identifier for this tool use
  - name: Name of the tool to call
  - input: Arguments to pass to the tool

# `type?`

```elixir
@spec type?(ExMCP.Types.content(), ExMCP.Types.content_type()) :: boolean()
```

Checks if content is of a specific type.

# `validate`

```elixir
@spec validate(map()) :: {:ok, ExMCP.Types.content()} | {:error, String.t()}
```

Validates content object structure.

Returns {:ok, content} if valid, {:error, reason} otherwise.

---

*Consult [api-reference.md](api-reference.md) for complete listing*