Hermes.Server (hermes_mcp v0.9.1)

High-level MCP server implementation.

This module provides the main API for implementing MCP (Model Context Protocol) servers. It includes macros and functions to simplify server creation with standardized capabilities, protocol version support, and supervision tree setup.

Usage

defmodule MyServer do
  use Hermes.Server,
    name: "My MCP Server",
    version: "1.0.0",
    capabilities: [:tools, :resources, :logging]

  @impl Hermes.Server.Behaviour
  def init(_arg, frame) do
    {:ok, frame}
  end

  @impl Hermes.Server.Behaviour
  def handle_request(%{"method" => "tools/list"}, frame) do
    {:reply, %{"tools" => []}, frame}
  end

  @impl Hermes.Server.Behaviour
  def handle_notification(_notification, frame) do
    {:noreply, frame}
  end
end

Server Capabilities

The following capabilities are supported:

  • :prompts - Server can provide prompt templates
  • :tools - Server can execute tools/functions
  • :resources - Server can provide resources (files, data, etc.)
  • :logging - Server supports log level configuration

Capabilities can be configured with options:

  • subscribe?: boolean - Whether the capability supports subscriptions (resources only)
  • list_changed?: boolean - Whether the capability emits list change notifications

Protocol Versions

By default, servers support the following protocol versions:

  • "2025-03-26" - Latest protocol version
  • "2024-10-07" - Previous stable version
  • "2024-05-11" - Legacy version for backward compatibility

Summary

Functions

component(module, opts \\ [])

Registers a component (tool, prompt, or resource) with the server.

is_server_capability(capability)

Guard to check if a capability is valid.

is_supported_capability(capabilities, capability)

Guard to check if a capability is supported by the server.

start_link(mod, init_arg, opts)

Starts a server with its supervision tree.

Functions

component(module, opts \\ [])

(macro)

Registers a component (tool, prompt, or resource) with the server.

Examples

# Register with auto-derived name
component MyServer.Tools.Calculator

# Register with custom name
component MyServer.Tools.FileManager, name: "files"

is_server_capability(capability)

(macro)

Guard to check if a capability is valid.

Examples

iex> is_server_capability(:tools)
true

iex> is_server_capability(:invalid)
false

is_supported_capability(capabilities, capability)

(macro)

Guard to check if a capability is supported by the server.

Examples

iex> capabilities = %{"tools" => %{}}
iex> is_supported_capability(capabilities, "tools")
true

start_link(mod, init_arg, opts)

Starts a server with its supervision tree.

Examples

# Start with default options
Hermes.Server.start_link(MyServer, :ok, transport: :stdio)

# Start with custom name
Hermes.Server.start_link(MyServer, %{}, 
  transport: :stdio,
  name: {:local, :my_server}
)