# `Hermolaos.Client.NotificationHandler`
[🔗](https://github.com/nyo16/hermolaos/blob/v0.5.0/lib/hermolaos/client/notification_handler.ex#L1)

Behaviour for handling MCP server notifications and requests.

When a server sends notifications (like list_changed events) or requests
(like ping or sampling), they are dispatched to a notification handler
if one is configured.

## Implementing a Handler

    defmodule MyApp.MCPHandler do
      @behaviour Hermolaos.Client.NotificationHandler

      @impl true
      def handle_notification({:notification, "notifications/tools/list_changed", _params}, state) do
        IO.puts("Tools list changed!")
        {:ok, state}
      end

      def handle_notification({:notification, method, params}, state) do
        IO.puts("Got notification: #{method}")
        {:ok, state}
      end

      def handle_notification({:request, "ping", _params}, state) do
        # ping is handled automatically, but you can observe it
        {:ok, state}
      end

      def handle_notification(_event, state) do
        {:ok, state}
      end
    end

## Using the Handler

    {:ok, conn} = Hermolaos.Client.Connection.start_link(
      transport: :stdio,
      command: "my-server",
      notification_handler: {MyApp.MCPHandler, %{}}
    )

## Event Types

Events are tuples with one of these formats:

- `{:notification, method, params}` - Server notification
- `{:request, method, params}` - Server request (ping, sampling, etc.)

## Common Notifications

- `notifications/tools/list_changed` - Available tools changed
- `notifications/resources/list_changed` - Available resources changed
- `notifications/resources/updated` - A specific resource was updated
- `notifications/prompts/list_changed` - Available prompts changed
- `notifications/progress` - Progress update for long operation
- `notifications/message` - Log message from server

# `event`

```elixir
@type event() ::
  {:notification, String.t(), map() | nil} | {:request, String.t(), map() | nil}
```

# `handler_state`

```elixir
@type handler_state() :: term()
```

# `handle_notification`

```elixir
@callback handle_notification(event :: event(), state :: handler_state()) ::
  {:ok, handler_state()} | :ok
```

Called when a server notification or request is received.

## Parameters

- `event` - The event tuple
- `state` - Handler state (or nil if no state was provided)

## Returns

- `{:ok, new_state}` - Continue with updated state
- `:ok` - Continue with unchanged state (convenience for stateless handlers)

---

*Consult [api-reference.md](api-reference.md) for complete listing*