McpServer.Tool.Content (HTTP MCP Server v0.9.0)

View Source

Structs and helper functions for representing tool result content items.

This module provides typed structs and convenience functions for different types of content that can be returned from tool functions, following the MCP protocol specification.

Content Types

  • Text - Text content
  • Image - Image content with base64-encoded data
  • Audio - Audio content with base64-encoded data
  • Resource - Embedded resource content

Usage

You can alias this module and use the helper functions to build tool results:

alias McpServer.Tool.Content, as: ToolContent

def search_tool(_conn, %{"query" => query}) do
  [
    ToolContent.text("Found 5 results for: #{query}"),
    ToolContent.text("Result 1: ..."),
    ToolContent.text("Result 2: ...")
  ]
end

def generate_chart(_conn, %{"data" => data}) do
  chart_image = create_chart(data)
  [
    ToolContent.text("Chart generated successfully"),
    ToolContent.image(chart_image, "image/png")
  ]
end

def read_file(_conn, %{"path" => path}) do
  [ToolContent.resource("file://#{path}", text: File.read!(path), mimeType: "text/plain")]
end

Low-level Struct API

iex> alias McpServer.Tool.Content
iex> text = Content.Text.new(text: "Hello, World!")
iex> text.text
"Hello, World!"

iex> image_data = <<137, 80, 78, 71, 13, 10, 26, 10>>
iex> image = Content.Image.new(data: image_data, mime_type: "image/png")
iex> image.mime_type
"image/png"

iex> resource = Content.Resource.new(uri: "file:///path/to/file.txt")
iex> resource.uri
"file:///path/to/file.txt"

Summary

Functions

audio(data, mime_type)

Creates an audio content item for tool responses.

audio_base64(base64_string, mime_type)

Creates an audio content item from a pre-encoded base64 string.

image(data, mime_type)

Creates an image content item for tool responses.

resource(uri, opts \\ [])

Creates an embedded resource content item for tool responses.

text(text)

Creates a text content item for tool responses.

Functions

audio(data, mime_type)

@spec audio(binary(), String.t()) :: McpServer.Tool.Content.Audio.t()

Creates an audio content item for tool responses.

Returns a McpServer.Tool.Content.Audio struct. The audio data will be automatically base64-encoded during JSON serialization.

Parameters

  • data (binary): the raw audio data
  • mime_type (string): the MIME type of the audio (e.g., "audio/wav", "audio/mpeg", "audio/ogg")

Examples

iex> audio_data = <<0, 1, 2, 3>>
iex> McpServer.Tool.Content.audio(audio_data, "audio/wav")
%McpServer.Tool.Content.Audio{data: <<0, 1, 2, 3>>, mime_type: "audio/wav"}

audio_base64(base64_string, mime_type)

@spec audio_base64(String.t(), String.t()) :: McpServer.Tool.Content.Audio.t()

Creates an audio content item from a pre-encoded base64 string.

Returns a McpServer.Tool.Content.Audio struct. The base64 string is decoded to binary internally so that serialization is consistent with audio/2.

Parameters

  • base64_string (string): the base64-encoded audio data
  • mime_type (string): the MIME type of the audio (e.g., "audio/wav", "audio/mpeg")

Examples

iex> McpServer.Tool.Content.audio_base64("AQID", "audio/wav")
%McpServer.Tool.Content.Audio{data: <<1, 2, 3>>, mime_type: "audio/wav"}

image(data, mime_type)

@spec image(binary(), String.t()) :: McpServer.Tool.Content.Image.t()

Creates an image content item for tool responses.

Returns a McpServer.Tool.Content.Image struct. The image data will be automatically base64-encoded during JSON serialization.

Parameters

  • data (binary): the raw image data
  • mime_type (string): the MIME type of the image (e.g., "image/png", "image/jpeg")

Examples

iex> image_data = <<137, 80, 78, 71, 13, 10, 26, 10>>
iex> McpServer.Tool.Content.image(image_data, "image/png")
%McpServer.Tool.Content.Image{data: <<137, 80, 78, 71, 13, 10, 26, 10>>, mime_type: "image/png"}

resource(uri, opts \\ [])

@spec resource(
  String.t(),
  keyword()
) :: McpServer.Tool.Content.Resource.t()

Creates an embedded resource content item for tool responses.

Returns a McpServer.Tool.Content.Resource struct.

Parameters

  • uri (string): the URI of the resource
  • opts (keyword list): optional keys include:
    • :mimeType - MIME type of the resource
    • :text - textual content of the resource
    • :blob - binary content; base64-encoded during JSON serialization

Examples

iex> McpServer.Tool.Content.resource("file:///path/to/file.txt")
%McpServer.Tool.Content.Resource{uri: "file:///path/to/file.txt", text: nil, blob: nil, mime_type: nil}

iex> McpServer.Tool.Content.resource("file:///data.json", mimeType: "application/json", text: ~s({"key": "value"}))
%McpServer.Tool.Content.Resource{
  uri: "file:///data.json",
  mime_type: "application/json",
  text: ~s({"key": "value"}),
  blob: nil
}

iex> McpServer.Tool.Content.resource("file:///image.png", mimeType: "image/png", blob: <<255, 216, 255>>)
%McpServer.Tool.Content.Resource{
  uri: "file:///image.png",
  mime_type: "image/png",
  text: nil,
  blob: <<255, 216, 255>>
}

text(text)

@spec text(String.t()) :: McpServer.Tool.Content.Text.t()

Creates a text content item for tool responses.

Returns a McpServer.Tool.Content.Text struct.

Parameters

  • text (string): the text content to return

Examples

iex> McpServer.Tool.Content.text("Hello, World!")
%McpServer.Tool.Content.Text{text: "Hello, World!"}

iex> McpServer.Tool.Content.text("Operation completed successfully")
%McpServer.Tool.Content.Text{text: "Operation completed successfully"}