OzMcp.Utils.Error (OzMcp v0.9.0)

Copy Markdown View Source

A JSON-RPC error that a callback returns.

The struct has three fields: code (an integer), message (a string) and data (a map or a list, or nil). The framework puts the fields in the error object of the JSON-RPC response. The client receives the code, the message and the data as they are.

When to return an error struct

Return {:error, %OzMcp.Utils.Error{}} for a protocol error: the entity does not exist, or the request does not agree with the protocol. The framework answers an unknown entity itself.

HelperCodeUse
invalid_params/2-32602an invalid argument
resource_not_found/1-32002a resource uri whose data does not exist
internal_error/2-32603a failure of the callback that has no better code
new/3anyanother code

A tool callback that returns the error struct sends the failure as a JSON-RPC error: the model does not read it. A task-augmented call that gets an error struct makes the task failed.

When to return a tool error result

In a tool callback, return {:ok, result} with isError: true when the work of the tool failed and the model can correct the input. The model reads the content of the result:

{:ok,
 %CallToolResult{}
 |> CallToolResult.content([
   %TextContent{} |> TextContent.text("The city is unknown")
 ])
 |> CallToolResult.is_error(true)
 |> CallToolResult.build()}

The read/2, read/4 and get/2 callbacks have no tool error result: they return the error struct for each failure.

Summary

Functions

Builds the error -32603. The client reads the message: keep the details out.

Builds the error -32602: the message names the invalid argument.

Builds an error struct with a code, a message and an optional data. The data is a map or a list of JSON terms, or nil.

Builds the error -32002 with the data %{"uri" => uri}.

Types

t()

@type t() :: %OzMcp.Utils.Error{
  code: integer(),
  data: map() | list() | nil,
  message: String.t()
}

Functions

internal_error(message \\ "internal error", data \\ nil)

@spec internal_error(String.t(), map() | list() | nil) :: %OzMcp.Utils.Error{
  code: term(),
  data: term(),
  message: term()
}

Builds the error -32603. The client reads the message: keep the details out.

invalid_params(message, data \\ nil)

@spec invalid_params(String.t(), map() | list() | nil) :: %OzMcp.Utils.Error{
  code: term(),
  data: term(),
  message: term()
}

Builds the error -32602: the message names the invalid argument.

new(code, message, data \\ nil)

@spec new(integer(), String.t(), map() | list() | nil) :: %OzMcp.Utils.Error{
  code: term(),
  data: term(),
  message: term()
}

Builds an error struct with a code, a message and an optional data. The data is a map or a list of JSON terms, or nil.

resource_not_found(uri)

@spec resource_not_found(String.t()) :: %OzMcp.Utils.Error{
  code: term(),
  data: term(),
  message: term()
}

Builds the error -32002 with the data %{"uri" => uri}.