ExMCP.Server behaviour (ex_mcp v0.9.0)

High-level server implementation with DSL support.

This module provides the use ExMCP.Server macro that enables the developer-friendly DSL for defining tools, resources, and prompts. It automatically handles capability registration and provides sensible defaults for MCP server behavior.

Usage

defmodule MyServer do
  use ExMCP.Server

  deftool "hello" do
    meta do
      name "Hello Tool"
      description "Says hello to someone"
    end

    input_schema %{
      type: "object",
      properties: %{name: %{type: "string"}},
      required: ["name"]
    }
  end

  defresource "config://app" do
    meta do
      name "App Config"
      description "Application configuration"
    end

    mime_type "application/json"
  end

  defprompt "greeting" do
    meta do
      name "Greeting Template"
      description "A greeting template"
    end

    arguments do
      arg :style, description: "Greeting style"
    end
  end

  # Handler callbacks
  @impl true
  def handle_tool_call("hello", %{"name" => name}, state) do
    {:ok, %{content: [text("Hello, #{name}!")]}, state}
  end

  @impl true
  def handle_resource_read("config://app", _uri, state) do
    content = json(%{debug: true, port: 8080})
    {:ok, content, state}
  end

  @impl true
  def handle_prompt_get("greeting", args, state) do
    style = Map.get(args, "style", "friendly")
    messages = [
      user("Please greet me in a #{style} way")
    ]
    {:ok, %{messages: messages}, state}
  end
end

Summary

Types

content()

state()

tool_result()

Callbacks

handle_initialize(params, state)

Callback for handling initialization requests.

handle_prompt_get(prompt_name, arguments, state)

Callback for handling prompt requests.

handle_prompt_list(state)

Callback for listing prompts.

handle_request(method, params, state)

Callback for custom request handling.

handle_resource_list(state)

Callback for listing resources.

handle_resource_read(uri, full_uri, state)

Callback for handling resource reads.

handle_resource_subscribe(uri, state)

Callback for resource subscriptions.

handle_resource_unsubscribe(uri, state)

Callback for resource unsubscriptions.

handle_tool_call(tool_name, arguments, state)

Callback for handling tool calls.

Functions

cancel_request(server, request_id, reason \\ nil)

Sends a cancellation notification to the server.

create_message(server, params)

Sends a createMessage request to the connected client.

get_pending_requests(server)

Gets the list of pending request IDs on the server.

list_roots(server, timeout \\ 5000)

Lists the roots available from the connected client.

notify_progress(server, progress_token, progress)

Sends a progress notification to the client.

notify_progress(server, progress_token, progress, total)

notify_prompts_changed(server)

Notifies subscribed clients that the prompts list has changed.

notify_resource_update(server, uri)

Sends a resource update notification for subscribed clients.

notify_resource_updated(server, uri)

Alias for notify_resource_update/2 for backward compatibility.

notify_resources_changed(server)

Notifies subscribed clients that the resource list has changed.

notify_roots_changed(server)

Notifies the client that the server's available roots have changed.

notify_tools_changed(server)

Notifies subscribed clients that the tools list has changed.

ping(server, timeout \\ 5000)

Sends a ping request to the client.

send_log_message(server, level, message, data)

Sends a log message through the server.

start_link(opts)

Starts an MCP server with the given options.

Types

content()

@type content() :: map()

state()

@type state() :: term()

tool_result()

@type tool_result() :: %{content: [content()], is_error?: boolean()}

Callbacks

handle_initialize(params, state)

(optional)

@callback handle_initialize(params :: map(), state()) ::
  {:ok, map(), state()} | {:error, term(), state()}

Callback for handling initialization requests.

Called when a client sends an initialize request. Allows custom version negotiation and capability setup.

handle_prompt_get(prompt_name, arguments, state)

(optional)

@callback handle_prompt_get(prompt_name :: String.t(), arguments :: map(), state()) ::
  {:ok, %{messages: [map()]}, state()} | {:error, term(), state()}

Callback for handling prompt requests.

Called when a client requests a prompt defined with defprompt.

handle_prompt_list(state)

(optional)

@callback handle_prompt_list(state()) ::
  {:ok, [map()], state()} | {:error, term(), state()}

Callback for listing prompts.

Called when a client requests a list of available prompts.

handle_request(method, params, state)

(optional)

@callback handle_request(method :: String.t(), params :: map(), state()) ::
  {:reply, map(), state()} | {:error, term(), state()} | {:noreply, state()}

Callback for custom request handling.

Called for any requests not handled by the standard callbacks. Can be used for experimental features.

handle_resource_list(state)

(optional)

@callback handle_resource_list(state()) ::
  {:ok, [map()], state()} | {:error, term(), state()}

Callback for listing resources.

Called when a client requests a list of available resources.

handle_resource_read(uri, full_uri, state)

(optional)

@callback handle_resource_read(uri :: String.t(), full_uri :: String.t(), state()) ::
  {:ok, [content()], state()} | {:error, term(), state()}

Callback for handling resource reads.

Called when a client reads a resource defined with defresource.

handle_resource_subscribe(uri, state)

(optional)

@callback handle_resource_subscribe(uri :: String.t(), state()) ::
  {:ok, state()} | {:error, term(), state()}

Callback for resource subscriptions.

Called when a client subscribes to resource change notifications.

handle_resource_unsubscribe(uri, state)

(optional)

@callback handle_resource_unsubscribe(uri :: String.t(), state()) ::
  {:ok, state()} | {:error, term(), state()}

Callback for resource unsubscriptions.

Called when a client unsubscribes from resource change notifications.

handle_tool_call(tool_name, arguments, state)

(optional)

@callback handle_tool_call(tool_name :: String.t(), arguments :: map(), state()) ::
  {:ok, tool_result(), state()} | {:error, term(), state()}

Callback for handling tool calls.

Called when a client invokes a tool defined with deftool.

Functions

cancel_request(server, request_id, reason \\ nil)

@spec cancel_request(GenServer.server(), ExMCP.Types.request_id(), String.t() | nil) ::
  :ok

Sends a cancellation notification to the server.

This function allows external processes to notify the server that a request should be cancelled. The server will attempt to cancel the request if it's still pending.

Parameters

server - Server process reference
request_id - The ID of the request to cancel
reason - Optional human-readable reason for cancellation

Returns

:ok - Cancellation notification sent

Examples

:ok = ExMCP.Server.cancel_request(server, "req_123", "User cancelled")
:ok = ExMCP.Server.cancel_request(server, 12345, nil)

create_message(server, params)

@spec create_message(GenServer.server(), map()) :: {:ok, map()} | {:error, term()}

Sends a createMessage request to the connected client.

This function allows the server to request message creation from the client using the sampling/createMessage method. This is part of the MCP sampling feature where servers can ask clients to generate LLM responses.

Parameters

server - Server process reference
params - Parameters for message creation including messages, modelPreferences, etc.

Returns

{:ok, result} - The created message response from the client
{:error, reason} - If the request fails

Examples

params = %{
  "messages" => [
    %{"role" => "user", "content" => %{"type" => "text", "text" => "Hello"}}
  ],
  "modelPreferences" => %{
    "hints" => [%{"name" => "gpt-4"}]
  }
}

{:ok, response} = ExMCP.Server.create_message(server, params)

get_pending_requests(server)

@spec get_pending_requests(GenServer.server()) :: [ExMCP.Types.request_id()]

Gets the list of pending request IDs on the server.

Returns a list of request IDs for requests that are currently being processed by the server. This can be used to monitor server load and track long-running operations.

Examples

{:ok, server} = MyServer.start_link()

# Get pending requests
pending = ExMCP.Server.get_pending_requests(server)
# => ["req_123", "req_456"]

list_roots(server, timeout \\ 5000)

@spec list_roots(GenServer.server(), timeout()) ::
  {:ok, %{roots: [map()]}} | {:error, any()}

Lists the roots available from the connected client.

Sends a roots/list request to the client to discover what filesystem or conceptual roots the client has access to. This allows the server to understand what the client can provide access to.

Parameters

server - Server process reference
timeout - Request timeout in milliseconds (default: 5000)

Returns

{:ok, %{roots: [root()]}} - List of roots from client
{:error, reason} - Request failed

Root Format

Each root contains:

uri - URI identifying the root location (required)
name - Human-readable name for the root (optional)

Examples

{:ok, %{roots: roots}} = ExMCP.Server.list_roots(server)

# Example roots format:
[
  %{uri: "file:///home/user", name: "Home Directory"},
  %{uri: "file:///projects", name: "Projects"},
  %{uri: "config://app", name: "App Configuration"}
]

notify_progress(server, progress_token, progress)

Sends a progress notification to the client.

Used for long-running operations to report progress updates.

notify_progress(server, progress_token, progress, total)

notify_prompts_changed(server)

@spec notify_prompts_changed(GenServer.server()) :: :ok

Notifies subscribed clients that the prompts list has changed.

notify_resource_update(server, uri)

Sends a resource update notification for subscribed clients.

This function should be called by the server when a subscribed resource changes.

notify_resource_updated(server, uri)

@spec notify_resource_updated(GenServer.server(), String.t()) :: :ok

Alias for notify_resource_update/2 for backward compatibility.

notify_resources_changed(server)

@spec notify_resources_changed(GenServer.server()) :: :ok

Notifies subscribed clients that the resource list has changed.

notify_roots_changed(server)

@spec notify_roots_changed(GenServer.server()) :: :ok

Notifies the client that the server's available roots have changed.

Sends a notification to inform the client that the list of roots the server can access has been updated. This allows clients to refresh their understanding of what the server can provide.

Parameters

server - Server process reference

Returns

:ok - Notification sent successfully

Example

:ok = ExMCP.Server.notify_roots_changed(server)

notify_tools_changed(server)

@spec notify_tools_changed(GenServer.server()) :: :ok

Notifies subscribed clients that the tools list has changed.

ping(server, timeout \\ 5000)

@spec ping(GenServer.server(), timeout()) :: {:ok, map()} | {:error, any()}

Sends a ping request to the client.

The client must respond promptly or may be disconnected.

send_log_message(server, level, message, data)

Sends a log message through the server.

Compatibility function for the logging system.

start_link(opts)

Starts an MCP server with the given options.

This function provides compatibility with the legacy server API and delegates to the appropriate server implementation.

Options

:handler - Handler module implementing ExMCP.Server.Handler
:transport - Transport type (:stdio, :http, :test, etc.)
Other options are passed to the underlying implementation