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_scopeslike 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/0of a module one time at boot.
The guide Prompts 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.
Summary
Callbacks
Gives the values for one argument of completion/complete. Optional.
Gives the messages of the prompt params["name"].
Returns the prompts of the module: %OzMcp.Structs.Prompt{}
structs, or maps with the wire keys.
Types
Callbacks
@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}.prefixis the text that the user typed.context: thecontext.argumentsof the request (a map of strings), ornil.
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.
@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
@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.