McpServer.Controller (HTTP MCP Server v0.6.0)

View Source

Helper functions for declaring data in controllers.

Usually you would import this module in your controller modules:

defmodule MyApp.MyController do
  import McpServer.Controller

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

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

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

  # Resource content helpers
  def read_resource(params) do
    McpServer.Resource.ReadResult.new(
      contents: [
        content("file.txt", "file:///path/to/file.txt", mimeType: "text/plain", text: "File content")
      ]
    )
  end

  # Prompt helpers
  def get_prompt(_conn, _args) do
    [
      message("user", "text", "Hello!"),
      message("assistant", "text", "Hi there!")
    ]
  end

  def complete_prompt(_conn, _arg, _prefix) do
    completion(["Alice", "Bob"], total: 10, has_more: true)
  end
end

Summary

Functions

Creates a completion response for prompt argument or resource URI completion.

Creates a resource content item.

Creates an image content item for tool responses.

Creates a message for a prompt response.

Creates an embedded resource content item for tool responses.

Creates a text content item for tool responses.

Functions

completion(values, opts \\ [])

@spec completion(
  [String.t()],
  keyword()
) :: McpServer.Completion.t()

Creates a completion response for prompt argument or resource URI completion.

Returns a McpServer.Completion struct that can be used in completion responses.

Parameters

  • values - A list of completion values
  • opts - Optional parameters:
    • :total - Total number of possible completions
    • :has_more - Whether there are more completions available

Examples

iex> completion(["Alice", "Bob", "Charlie"])
%McpServer.Completion{
    values: ["Alice", "Bob", "Charlie"]
}

iex> completion(["Alice", "Bob"], total: 10, has_more: true)
%McpServer.Completion{
    values: ["Alice", "Bob"],
    total: 10,
    has_more: true
}

iex> completion(["Alice", "Bob"], total: 10, has_more: false)
%McpServer.Completion{
    values: ["Alice", "Bob"],
    total: 10,
    has_more: false
}

content(name, uri, opts \\ [])

Creates a resource content item.

Returns a McpServer.Resource.Content struct that can be used in read_resource responses.

Parameters

  • name (string): the display name of the content (e.g. filename)
  • uri (string): the canonical URI of the content
  • opts (keyword list): optional keys include:
    • :mimeType - mime type string
    • :text - textual content
    • :title - title for the content
    • :blob - binary content; when present it's base64-encoded

Examples

iex> content("main.rs", "file:///project/src/main.rs", mimeType: "plain/text", text: "<actual content of the file>...", title: "Main file of the code base")
%McpServer.Resource.Content{
  name: "main.rs",
  uri: "file:///project/src/main.rs",
  mime_type: "plain/text",
  text: "<actual content of the file>...",
  title: "Main file of the code base"
}

iex> content("image.png", "file:///tmp/image.png", mimeType: "image/png", blob: <<255, 216, 255>>)
%McpServer.Resource.Content{
  name: "image.png",
  uri: "file:///tmp/image.png",
  mime_type: "image/png",
  blob: "/9j/"  # base64-encoded
}

image_content(data, mime_type)

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

Creates an image content item for tool responses.

Returns a McpServer.Tool.Content.Image struct that can be returned from tool functions. 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> image_content(image_data, "image/png")
%McpServer.Tool.Content.Image{data: <<137, 80, 78, 71, 13, 10, 26, 10>>, mime_type: "image/png"}

message(role, type, content)

Creates a message for a prompt response.

Returns a McpServer.Prompt.Message struct that can be used in get_prompt responses.

Parameters

  • role - The role of the message sender ("user", "assistant", "system")
  • type - The type of content ("text", "image", etc.)
  • content - The actual content of the message

Examples

iex> message("user", "text", "Hello world!")
%McpServer.Prompt.Message{
  role: "user",
  content: %McpServer.Prompt.MessageContent{
    type: "text",
    text: "Hello world!"
  }
}

resource_content(uri, opts \\ [])

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

Creates an embedded resource content item for tool responses.

Returns a McpServer.Tool.Content.Resource struct that can be returned from tool functions.

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> resource_content("file:///path/to/file.txt")
%McpServer.Tool.Content.Resource{uri: "file:///path/to/file.txt", text: nil, blob: nil, mime_type: nil}

iex> resource_content("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> resource_content("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_content(text)

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

Creates a text content item for tool responses.

Returns a McpServer.Tool.Content.Text struct that can be returned from tool functions.

Parameters

  • text (string): the text content to return

Examples

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

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