This module implements the standard MCP specification.

Behaviour for implementing MCP server handlers.

This behaviour defines callbacks for handling all MCP protocol operations including tools, resources, prompts, and the new sampling/LLM integration features.

The handler behaviour pattern is an implementation detail but all callbacks correspond to official MCP protocol methods.

Metadata (_meta) Support

Handlers receive metadata passed by clients through the _meta field:

• For handle_call_tool/3: The _meta field is included in the arguments map
• For list operations: The cursor parameter may be a map containing _meta
• For other operations: Check the params for _meta field

Example accessing progress token in a tool:

def handle_call_tool("my_tool", arguments, state) do
  {meta, args} = Map.pop(arguments, "_meta")
  progress_token = meta && meta["progressToken"]

  if progress_token do
    # Report progress via Server.notify_progress/5
  end

  # Process args without _meta...
end

Basic Example

defmodule MyServer do
  use ExMCP.Server.Handler

  @impl true
  def handle_initialize(params, state) do
    # Check client's protocol version
    client_version = params["protocolVersion"]

    # Accept 2025-03-26 or propose 2024-11-05 as fallback
    negotiated_version = case client_version do
      "2025-03-26" -> "2025-03-26"
      "2024-11-05" -> "2024-11-05"
      _ -> "2025-03-26"  # Propose latest as default
    end

    {:ok, %{
      protocolVersion: negotiated_version,
      serverInfo: %{
        name: "my-server",
        version: "1.0.0"
      },
      capabilities: %{
        tools: %{},
        resources: %{},
        prompts: %{},
        sampling: %{}  # Enable LLM features
      }
    }, state}
  end

  @impl true
  def handle_list_tools(state) do
    tools = [
      %{
        name: "calculate",
        description: "Perform calculations",
        inputSchema: %{
          type: "object",
          properties: %{
            expression: %{type: "string"}
          },
          required: ["expression"]
        }
      }
    ]
    {:ok, tools, state}
  end

  @impl true
  def handle_call_tool("calculate", params, state) do
    # Access progress token if provided
    progress_token = get_in(params, ["_meta", "progressToken"])

    # Your tool implementation
    case eval_expression(params["expression"]) do
      {:ok, result} ->
        # Send progress updates if token provided
        if progress_token do
          ExMCP.Server.notify_progress(self(), progress_token, 100, 100)
        end

        {:ok, [%{type: "text", text: "Result: #{result}"}], state}

      {:error, reason} ->
        # Return tool execution error with isError flag
        error_result = %{
          content: [%{type: "text", text: "Calculation failed: #{reason}"}],
          isError: true
        }
        {:ok, error_result, state}
    end
  end
end

Advanced Features

Structured Tool Output (Draft Feature)

Example implementation:

defmodule WeatherServer do
  use ExMCP.Server.Handler

  @impl true
  def handle_list_tools(_cursor, state) do
    tools = [
      %{
        name: "get_weather",
        description: "Get current weather data",
        inputSchema: %{
          type: "object",
          properties: %{
            location: %{type: "string", description: "City name"}
          },
          required: ["location"]
        },
        # Draft feature: declare expected output structure
        outputSchema: %{
          type: "object",
          properties: %{
            temperature: %{type: "number", description: "Temperature in Celsius"},
            conditions: %{type: "string", description: "Weather conditions"},
            humidity: %{type: "number", description: "Humidity percentage"}
          },
          required: ["temperature", "conditions"]
        }
      }
    ]
    {:ok, tools, nil, state}
  end

  @impl true
  def handle_call_tool("get_weather", %{"location" => location}, state) do
    # Fetch weather data (example implementation)
    # In real code, this would call an actual weather API
    temp = 22.5
    conditions = "Partly cloudy"
    humidity = 65

    # Return both unstructured and structured content
    result = %{
      content: [%{
        type: "text",
        text: "Current weather in #{location}: #{temp}°C, #{conditions}"
      }],
      # Draft feature: structured content matching outputSchema
      structuredContent: %{
        "temperature" => temp,
        "conditions" => conditions,
        "humidity" => humidity
      }
    }

    {:ok, result, state}
  end

  # ... other callbacks ...
end

Sampling/LLM Integration

@impl ExMCP.Server.Handler
def handle_create_message(params, state) do
  messages = params["messages"]
  model_prefs = params["modelPreferences"]

  # Integrate with your LLM provider
  response = call_llm_api(messages, model_prefs)

  result = %{
    content: %{type: "text", text: response.text},
    model: response.model,
    stopReason: "stop"
  }

  {:ok, result, state}
end

Progress Notifications

For long-running operations, use progress tokens:

@impl true
def handle_call_tool("process_file", params, state) do
  progress_token = get_in(params, ["_meta", "progressToken"])
  file_path = params["path"]

  # Start async processing with progress updates
  Task.start(fn ->
    process_with_progress(file_path, progress_token, self())
  end)

  {:ok, [%{type: "text", text: "Processing started"}], state}
end

defp process_with_progress(path, token, server) when token != nil do
  # Send progress updates
  ExMCP.Server.notify_progress(server, token, 0, 100)
  # ... processing ...
  ExMCP.Server.notify_progress(server, token, 50, 100)
  # ... more processing ...
  ExMCP.Server.notify_progress(server, token, 100, 100)
end

Dynamic Content Notifications

Notify clients when your server's content changes:

def add_new_tool(server, tool_def) do
  # Add tool to your server state
  # Then notify clients
  ExMCP.Server.notify_tools_changed(server)
end

def update_resource(server, uri) do
  # Update the resource
  # Then notify clients
  ExMCP.Server.notify_resource_updated(server, uri)
end

Callback Reference

The use macro provides default implementations for optional callbacks. You only need to implement the callbacks for features your server supports.