ExMCP.Server.Tools.Helpers (ex_mcp v0.10.0)

View Source

Helper functions for building tool responses and working with schemas.

This module provides utilities to simplify common patterns when implementing MCP tools, including response builders, schema validators, and type converters.

Summary

Functions

Generates an array schema.

Creates an error response with text content.

Creates a multi-content response with mixed content types.

Generates a number schema with constraints.

Generates an object schema.

Creates a resource response.

Generates a string schema with constraints.

Creates a response with both text and structured content.

Creates a simple text response.

Validates arguments against a JSON schema.

Functions

array_schema(item_type, opts \\ [])

Generates an array schema.

error_response(message)

Creates an error response with text content.

Examples

iex> error_response("Something went wrong")
%{content: [%{type: "text", text: "Something went wrong"}], isError: true}

image_response(data, description, mime_type \\ nil)

Creates an image response.

Examples

iex> image_response("https://example.com/image.png", "An example image")
[%{
  type: "image",
  data: "https://example.com/image.png",
  mimeType: "image/png",
  description: "An example image"
}]

multi_content_response(contents)

Creates a multi-content response with mixed content types.

Examples

iex> multi_content_response([
...>   {:text, "Here is some text"},
...>   {:image, "data:image/png;base64,abc123", "A diagram"},
...>   {:resource, "file:///doc.pdf", "application/pdf"}
...> ])

number_schema(opts \\ [])

Generates a number schema with constraints.

object_schema(properties, opts \\ [])

Generates an object schema.

resource_response(uri, mime_type)

Creates a resource response.

Examples

iex> resource_response("file:///path/to/file.txt", "text/plain")
[%{
  type: "resource",
  uri: "file:///path/to/file.txt",
  mimeType: "text/plain"
}]

string_schema(opts \\ [])

Generates a string schema with constraints.

structured_response(text, data)

Creates a response with both text and structured content.

Examples

iex> structured_response("Operation completed", %{status: "success", count: 42})
%{
  content: [%{type: "text", text: "Operation completed"}],
  structuredContent: %{status: "success", count: 42}
}

text_response(text)

Creates a simple text response.

Examples

iex> text_response("Hello, World!")
[%{type: "text", text: "Hello, World!"}]

validate_arguments(arguments, schema)

Validates arguments against a JSON schema.

Returns {:ok, validated_args} with defaults applied, or {:error, reason}.

Examples

iex> schema = %{
...>   type: "object",
...>   properties: %{
...>     name: %{type: "string"},
...>     age: %{type: "integer"}
...>   },
...>   required: ["name"]
...> }
iex> validate_arguments(%{name: "Alice", age: 30}, schema)
{:ok, %{name: "Alice", age: 30}}