# `OzMcp.Config.Prompt`
[🔗](https://github.com/oz-elixir/oz_mcp/blob/v0.9.0/lib/oz_mcp/config/prompt.ex#L1)

Behaviour for MCP prompt modules.

## Two ways to declare the prompts

| Way | `use` | What you write | What the framework generates |
|---|---|---|---|
| DSL | `use OzMcp.Config.Prompt` | one `prompt "name" do ... end` block for each prompt and `get/2` | `list/0` |
| Data | `use OzMcp.Config.Prompt, dsl?: false` | `list/0` that returns `%OzMcp.Structs.Prompt{}` structs or maps with the wire keys (`name`, `arguments`, ...) and `get/2` | nothing |

Rules for the way with `dsl?: false`:

  * A map carries `required_scopes` like a struct: the boot of the
    instance reads the key, checks it and it never reaches the
    client.
  * The boot check of duplicate names reads `list/0` of a module one
    time at boot.

The guide [Prompts](guides/entities/prompts.md) shows an example of
each way.

## Required scopes

Declare `required_scopes [...]` in a `prompt` block: a `prompts/get`
without all the scopes gets `403` and `prompts/list` hides the
prompt from a principal that lacks them. A prompt declared with
`dsl?: false` carries the scopes in the key `required_scopes` of
a map, or in the field of the struct. The guide about the
authorization gives the rules of the scopes and of the filter of the
lists.

## Unique key

The `name` of a prompt is unique in the module: two prompts with the
same `name` raise at compile time. The `name` is unique in the server
too: the runtime refuses to boot when two prompt modules of one
server declare the same `name`. The boot check reads `list/0` of each
module.

# `complete_result`

```elixir
@type complete_result() ::
  {:ok, %OzMcp.Structs.CompleteResult{_meta: term(), completion: term()}}
  | {:ok, map()}
  | {:error, %OzMcp.Utils.Error{code: term(), data: term(), message: term()}}
```

# `completion_argument`

```elixir
@type completion_argument() :: %{required(String.t()) =&gt; String.t()}
```

# `completion_context`

```elixir
@type completion_context() :: map() | nil
```

# `get_result`

```elixir
@type get_result() ::
  {:ok,
   %OzMcp.Structs.GetPromptResult{
     _meta: term(),
     description: term(),
     messages: term()
   }}
  | {:ok, map()}
  | {:error, %OzMcp.Utils.Error{code: term(), data: term(), message: term()}}
```

# `name`

```elixir
@type name() :: String.t()
```

# `rpc_params`

```elixir
@type rpc_params() :: map()
```

# `complete`
*optional* 

```elixir
@callback complete(
  OzMcp.Context.ctx(),
  name(),
  completion_argument(),
  completion_context()
) ::
  complete_result()
```

Gives the values for one argument of `completion/complete`. Optional.

The arguments:

  * `ctx`: the short context of the callbacks.
  * `name`: the name of the prompt of the reference.
  * `argument`: `%{"name" => argument, "value" => prefix}`.
    `prefix` is the text that the user typed.
  * `context`: the `context.arguments` of the request (a map of
    strings), or `nil`.

Return `{:ok, %CompleteResult{}}` or `{:ok, map}`: the `values`
hold at most 100 items. Without this callback, the client gets
`-32601` for a completion of this prompt.

# `get`

```elixir
@callback get(OzMcp.Context.ctx(), rpc_params()) :: get_result()
```

Gives the messages of the prompt `params["name"]`.

`params["arguments"]` is a map of strings, or absent. The server
checked the arguments before the call: an unknown argument, a
missing required argument, or a value that is not a string gives the
client a `-32602` error and `get/2` does not run.

Return `{:ok, %GetPromptResult{}}` or `{:ok, map}`: the `messages`
hold one message for each step. The `role` of a message is `"user"`
or `"assistant"`. The `content` of a message is one content block:
text, image, audio, `resource_link`, or an embedded resource.

Return `{:error, %OzMcp.Utils.Error{}}` for a protocol error.

## Example

    @impl true
    def get(_ctx, %{"name" => "review", "arguments" => %{"language" => language}}) do
      {:ok,
       %{
         messages: [
           %{role: "user",
             content: %{type: "text", text: "Review this #{language} code."}}
         ]
       }}
    end

# `list`

```elixir
@callback list() ::
  [
    %OzMcp.Structs.Prompt{
      _meta: term(),
      arguments: term(),
      description: term(),
      extras: term(),
      icons: term(),
      name: term(),
      required_scopes: term(),
      title: term()
    }
  ]
  | [map()]
```

Returns the prompts of the module: `%OzMcp.Structs.Prompt{}`
structs, or maps with the wire keys.

The DSL generates it. The boot of the instance calls it one time.

---

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