Phantom.Tool (phantom_mcp v0.2.0)

View Source

The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by language models. Tools enable models to interact with external systems, such as querying databases, calling APIs, or performing computations. Each tool is uniquely identified by a name and includes metadata describing its schema.

https://modelcontextprotocol.io/specification/2025-03-26/server/tools

Summary

Types

audio_response()
embedded_blob_resource()
embedded_resource_response()
embedded_text_resource()
error_response()
image_response()
json()
resource_link_response()
response()
structured_response()
t()
text_response()

Functions

audio(binary, attrs \\ [])

Tool response as audio content

build(attrs)

Build a tool spec

embedded_resource(uri, resource)

Embedded resource response.

error(message)
image(binary, attrs \\ [])

Tool response as image content

resource_link(uri, resource_template, resource_attrs \\ %{})

Resource link reponse.

response(results)

Formats the response from an MCP Router to the MCP specification

text(data)
to_json(tool)

Represent a Tool spec as json when listing the available tools to clients.

Types

audio_response()

@type audio_response() :: %{
  content: [type: :audio, data: base64_binary :: binary(), mimeType: String.t()]
}

embedded_blob_resource()

@type embedded_blob_resource() :: %{
  :uri => String.t(),
  :data => String.t(),
  optional(:mimeType) => String.t(),
  optional(:title) => String.t(),
  optional(:description) => String.t()
}

embedded_resource_response()

@type embedded_resource_response() :: %{
  content: [
    type: :resource,
    resource: embedded_text_resource() | embedded_blob_resource()
  ]
}

embedded_text_resource()

@type embedded_text_resource() :: %{
  :uri => String.t(),
  :text => String.t(),
  optional(:mimeType) => String.t(),
  optional(:title) => String.t(),
  optional(:description) => String.t()
}

error_response()

@type error_response() :: %{isError: true, content: [type: :text, text: String.t()]}

image_response()

@type image_response() :: %{
  content: [type: :image, data: base64_binary :: binary(), mimeType: String.t()]
}

json()

@type json() :: %{
  :name => String.t(),
  :description => String.t(),
  :inputSchema => InputSchema.json(),
  optional(:outputSchema) => OutputSchema.json(),
  optional(:annotations) => Phantom.Tool.Annotation.json()
}

response()

@type response() ::
  image_response()
  | audio_response()
  | text_response()
  | structured_response()
  | embedded_resource_response()
  | resource_link_response()

structured_response()

@type structured_response() :: %{
  structuredContent: map(),
  content: [type: :text, text: json_encoded :: String.t()]
}

t()

@type t() :: %Phantom.Tool{
  annotations: Phantom.Tool.Annotation.t(),
  description: String.t(),
  function: atom(),
  handler: module(),
  input_schema: Phantom.Tool.JSONSchema.t(),
  meta: map(),
  mime_type: String.t(),
  name: String.t(),
  output_schema: Phantom.Tool.JSONSchema.t()
}

text_response()

@type text_response() :: %{content: [type: :text, text: String.t()]}

Functions

audio(binary, attrs \\ [])

(macro)

Tool response as audio content

The :mime_type will be fetched from the current tool within the scope of the request if not provided, but you will need to provide the rest.

  • binary - Binary data.
  • :mime_type (optional) MIME type. Defaults to "application/octet-stream"

For example:

Phantom.Tool.audio(File.read!("game-over.wav"))

Phantom.Tool.audio(
  File.read!("game-over.wav"),
  mime_type: "audio/wav"
)

build(attrs)

Build a tool spec

The Phantom.Router.tool/3 macro will build these specs.

embedded_resource(uri, resource)

@spec embedded_resource(string_uri :: String.t(), map()) ::
  embedded_resource_response()

Embedded resource response.

Typically used with your router's read_resource/3 function. See Phantom.Router.read_resource/3 for more information

error(message)

@spec error(message :: String.t()) :: error_response()

image(binary, attrs \\ [])

(macro)

Tool response as image content

The :mime_type will be fetched from the current tool within the scope of the request if not provided, but you will need to provide the rest.

  • binary - Binary data.
  • :mime_type (optional) MIME type. Defaults to "application/octet-stream"

For example:

Phantom.Tool.image(File.read!("tower.png"))

Phantom.Tool.audio(
  File.read!("tower.png"),
  mime_type: "image/png"
)

resource_link(uri, resource_template, resource_attrs \\ %{})

@spec resource_link(string_uri :: String.t(), Phantom.ResourceTemplate.t(), map()) ::
  resource_link_response()

Resource link reponse.

Typically used with your router's resource_uri/3 function. See Phantom.Router.resource_uri/3 for more information.

response(results)

Formats the response from an MCP Router to the MCP specification

text(data)

@spec text(map()) :: structured_response()
@spec text(String.t()) :: text_response()

to_json(tool)

Represent a Tool spec as json when listing the available tools to clients.