ExMCP.Client.Response (ex_mcp v0.10.0)

View Source

Response normalization and transformation utilities for MCP.

This module provides consistent, developer-friendly response formats by normalizing raw MCP protocol responses into standardized structures.

Features

  • Standardized field names (snake_case instead of mixed case)
  • Type coercion and validation
  • Automatic content parsing (JSON, text, etc.)
  • Error context enrichment
  • Missing field defaults

Response Types

All normalized responses follow consistent patterns:

  • Tools: %{name, description, input_schema, metadata}
  • Resources: %{uri, name, description, mime_type, metadata}
  • Prompts: %{name, description, arguments, metadata}
  • Content: Automatic parsing based on type detection

Summary

Types

normalized_prompt()
normalized_resource()
normalized_tool()

Functions

from_protocol(response)

Converts a raw protocol response to a normalized format.

normalize_prompt(raw_prompt)

Normalizes a prompt definition from MCP protocol format.

normalize_prompt_result(result)

Normalizes a prompt result (messages) from MCP protocol format.

normalize_resource(raw_resource)

Normalizes a resource definition from MCP protocol format.

normalize_resource_content(result, opts \\ [])

Normalizes resource content with automatic parsing.

normalize_server_info(server_info)

Normalizes server information response.

normalize_tool(raw_tool)

Normalizes a tool definition from MCP protocol format.

normalize_tool_result(result)

Normalizes a tool call result from MCP protocol format.

Types

normalized_prompt()

@type normalized_prompt() :: %{
  name: String.t(),
  description: String.t() | nil,
  arguments: [map()] | nil,
  metadata: map()
}

normalized_resource()

@type normalized_resource() :: %{
  uri: String.t(),
  name: String.t() | nil,
  description: String.t() | nil,
  mime_type: String.t() | nil,
  metadata: map()
}

normalized_tool()

@type normalized_tool() :: %{
  name: String.t(),
  description: String.t() | nil,
  input_schema: map() | nil,
  metadata: map()
}

Functions

from_protocol(response)

@spec from_protocol(map()) :: {:ok, any()} | {:error, any()}

Converts a raw protocol response to a normalized format.

This is a convenience function that handles the most common response types and provides a unified interface for response normalization.

normalize_prompt(raw_prompt)

@spec normalize_prompt(map()) :: normalized_prompt()

Normalizes a prompt definition from MCP protocol format.

normalize_prompt_result(result)

@spec normalize_prompt_result(map()) :: map()

Normalizes a prompt result (messages) from MCP protocol format.

normalize_resource(raw_resource)

@spec normalize_resource(map()) :: normalized_resource()

Normalizes a resource definition from MCP protocol format.

normalize_resource_content(result, opts \\ [])

@spec normalize_resource_content(
  map(),
  keyword()
) :: any()

Normalizes resource content with automatic parsing.

Options

  • :parse_json - Parse JSON content automatically (default: true)
  • :encoding - Text encoding to use (default: "utf-8")
  • :max_size - Maximum content size to parse (default: 10MB)

normalize_server_info(server_info)

@spec normalize_server_info(map()) :: map()

Normalizes server information response.

normalize_tool(raw_tool)

@spec normalize_tool(map()) :: normalized_tool()

Normalizes a tool definition from MCP protocol format.

Examples

# Raw MCP response
raw = %{
  "name" => "calculator",
  "description" => "Performs calculations",
  "inputSchema" => %{"type" => "object", "properties" => %{...}}
}

# Normalized response
tool = Response.normalize_tool(raw)
# => %{
#   name: "calculator",
#   description: "Performs calculations",
#   input_schema: %{type: "object", properties: %{...}},
#   metadata: %{}
# }

normalize_tool_result(result)

@spec normalize_tool_result(map()) :: any()

Normalizes a tool call result from MCP protocol format.

Handles content parsing, error detection, and metadata extraction.