# `Hermolaos.Protocol.Messages`
[🔗](https://github.com/nyo16/hermolaos/blob/v0.5.0/lib/hermolaos/protocol/messages.ex#L1)

MCP message builders for all protocol methods.

This module provides functions to build properly formatted MCP request
and notification messages. Each function returns a map that can be
sent through a transport.

## Protocol Version

The default protocol version is `2025-03-26`.
This can be overridden in the `initialize/3` function.

## Message Categories

### Lifecycle Messages
- `initialize/3` - Initialize connection
- `initialized_notification/0` - Confirm initialization complete
- `ping/0` - Liveness check

### Tool Messages
- `tools_list/1` - List available tools
- `tools_call/2` - Invoke a tool

### Resource Messages
- `resources_list/1` - List resources
- `resources_read/1` - Read a resource
- `resources_subscribe/1` - Subscribe to changes
- `resources_unsubscribe/1` - Unsubscribe

### Prompt Messages
- `prompts_list/1` - List prompts
- `prompts_get/2` - Get a prompt

### Other Messages
- `logging_set_level/1` - Set logging level
- `completion_complete/2` - Request completions

# `cancelled_notification`

```elixir
@spec cancelled_notification(integer() | String.t(), String.t() | nil) :: map()
```

Builds a cancellation notification.

Sent to cancel a pending request.

## Parameters

- `request_id` - ID of the request to cancel
- `reason` - Optional cancellation reason

## Examples

    msg = Hermolaos.Protocol.Messages.cancelled_notification(123)
    msg = Hermolaos.Protocol.Messages.cancelled_notification(123, "User cancelled")

# `completion_complete`

```elixir
@spec completion_complete(map(), map(), map() | nil) :: map()
```

Builds a completion/complete request.

Requests argument completion suggestions.

## Parameters

- `ref` - Reference object (prompt or resource)
- `argument` - Argument to complete
- `context` - Optional context map with `"arguments"` for multi-argument completion

## Examples

    msg = Hermolaos.Protocol.Messages.completion_complete(
      %{"type" => "ref/prompt", "name" => "code_review"},
      %{"name" => "language", "value" => "eli"}
    )

    # With context arguments
    msg = Hermolaos.Protocol.Messages.completion_complete(
      %{"type" => "ref/prompt", "name" => "code_review"},
      %{"name" => "language", "value" => "eli"},
      %{"arguments" => %{"repo" => "myapp"}}
    )

# `default_protocol_version`

```elixir
@spec default_protocol_version() :: String.t()
```

Returns the default MCP protocol version.

# `initialize`

```elixir
@spec initialize(String.t(), map(), map()) :: map()
```

Builds an initialize request message.

This is the first message sent by the client to establish the connection
and negotiate capabilities.

## Parameters

- `protocol_version` - The protocol version to request
- `capabilities` - Client capabilities map
- `client_info` - Client identification info

## Examples

    msg = Hermolaos.Protocol.Messages.initialize(
      "2025-03-26",
      %{roots: %{listChanged: true}},
      %{name: "MyClient", version: "1.0.0"}
    )

# `initialized_notification`

```elixir
@spec initialized_notification() :: map()
```

Builds the initialized notification.

Sent by the client after receiving a successful initialize response
to indicate the handshake is complete.

## Examples

    msg = Hermolaos.Protocol.Messages.initialized_notification()
    # => %{"method" => "notifications/initialized"}

# `logging_set_level`

```elixir
@spec logging_set_level(String.t()) :: map()
```

Builds a logging/setLevel request.

Sets the server's logging level.

## Parameters

- `level` - Log level (debug, info, notice, warning, error, critical, alert, emergency)

## Examples

    msg = Hermolaos.Protocol.Messages.logging_set_level("debug")

# `ping`

```elixir
@spec ping() :: map()
```

Builds a ping request.

Used to check if the connection is alive.

## Examples

    msg = Hermolaos.Protocol.Messages.ping()
    # => %{"method" => "ping"}

# `ping_response`

```elixir
@spec ping_response() :: map()
```

Builds a response to a ping request.

# `progress_notification`

```elixir
@spec progress_notification(String.t() | integer(), number(), keyword()) :: map()
```

Builds a progress notification.

Sent to report progress on a long-running operation.

## Parameters

- `progress_token` - Token identifying the operation
- `progress` - Current progress value
- `opts` - Optional keyword list:
  - `:total` - Total progress value
  - `:message` - Human-readable progress message

## Examples

    msg = Hermolaos.Protocol.Messages.progress_notification("op123", 50, total: 100)
    msg = Hermolaos.Protocol.Messages.progress_notification("op123", 50, total: 100, message: "Processing files...")

# `prompts_get`

```elixir
@spec prompts_get(String.t(), map()) :: map()
```

Builds a prompts/get request.

Gets a specific prompt, optionally with argument values.

## Parameters

- `name` - Prompt name
- `arguments` - Optional argument values

## Examples

    msg = Hermolaos.Protocol.Messages.prompts_get("code_review")
    msg = Hermolaos.Protocol.Messages.prompts_get("summarize", %{"language" => "elixir"})

# `prompts_list`

```elixir
@spec prompts_list(String.t() | nil) :: map()
```

Builds a prompts/list request.

Lists all prompts available on the server.

## Parameters

- `cursor` - Optional pagination cursor

## Examples

    msg = Hermolaos.Protocol.Messages.prompts_list()

# `resources_list`

```elixir
@spec resources_list(String.t() | nil) :: map()
```

Builds a resources/list request.

Lists all resources available on the server.

## Parameters

- `cursor` - Optional pagination cursor

## Examples

    msg = Hermolaos.Protocol.Messages.resources_list()

# `resources_read`

```elixir
@spec resources_read(String.t()) :: map()
```

Builds a resources/read request.

Reads the content of a specific resource.

## Parameters

- `uri` - Resource URI

## Examples

    msg = Hermolaos.Protocol.Messages.resources_read("file:///project/README.md")

# `resources_subscribe`

```elixir
@spec resources_subscribe(String.t()) :: map()
```

Builds a resources/subscribe request.

Subscribes to updates for a specific resource.

## Parameters

- `uri` - Resource URI

## Examples

    msg = Hermolaos.Protocol.Messages.resources_subscribe("file:///project/src/main.rs")

# `resources_templates_list`

```elixir
@spec resources_templates_list(String.t() | nil) :: map()
```

Builds a resources/templates/list request.

Lists resource templates available on the server.

## Parameters

- `cursor` - Optional pagination cursor

# `resources_unsubscribe`

```elixir
@spec resources_unsubscribe(String.t()) :: map()
```

Builds a resources/unsubscribe request.

Unsubscribes from updates for a specific resource.

## Parameters

- `uri` - Resource URI

# `roots_list_changed_notification`

```elixir
@spec roots_list_changed_notification() :: map()
```

Builds a roots/list_changed notification.

Sent when the client's root list changes.

# `roots_list_response`

```elixir
@spec roots_list_response([map()]) :: map()
```

Builds a response to a roots/list request.

## Parameters

- `roots` - List of root objects

## Examples

    msg = Hermolaos.Protocol.Messages.roots_list_response([
      %{"uri" => "file:///project", "name" => "Project Root"}
    ])

# `sampling_not_supported_error`

```elixir
@spec sampling_not_supported_error() :: map()
```

Builds an error response to a sampling/createMessage request.

Used when the client doesn't support sampling.

# `tools_call`

```elixir
@spec tools_call(String.t(), map()) :: map()
```

Builds a tools/call request.

Invokes a tool with the given arguments.

## Parameters

- `name` - Tool name
- `arguments` - Tool arguments map

## Examples

    msg = Hermolaos.Protocol.Messages.tools_call("read_file", %{"path" => "/tmp/test.txt"})

# `tools_list`

```elixir
@spec tools_list(String.t() | nil) :: map()
```

Builds a tools/list request.

Lists all tools available on the server.

## Parameters

- `cursor` - Optional pagination cursor

## Examples

    msg = Hermolaos.Protocol.Messages.tools_list()
    msg = Hermolaos.Protocol.Messages.tools_list("cursor123")

---

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