OzMcp.Config.Tool behaviour (OzMcp v0.9.0)

Copy Markdown View Source

Behaviour for MCP tool modules.

Two ways to declare the tools

WayuseWhat you writeWhat the framework generates
DSLuse OzMcp.Config.Toolone tool "name" do ... end block for each tool and call/2list/0. The DSL checks the schemas at compile time.
Datause OzMcp.Config.Tool, dsl?: falselist/0 that returns %OzMcp.Structs.Tool{} structs or maps with the wire keys (name, inputSchema, ...) and call/2nothing

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 Tools shows an example of each way.

Static schemas and schema validation

The server reads a module one time, at the boot of the instance and answers a lookup from a map in the catalog. A change of a module needs a stop and a start of the instance.

A dsl?: true tool (the default) that declares an invalid inputSchema or outputSchema fails at compile time; the root of each schema must have the type "object". A tool with dsl?: false is checked at the boot of the instance. The guide Tools gives the details of each check.

Output schema

When a tool declares an outputSchema, the server checks each result of the tool before it sends the result:

  • A result with isError: true is not checked.
  • Each other result must have a structuredContent that is an object and that agrees with the outputSchema.
  • The check uses the JSON form of structuredContent: atom keys and atom values are strings, as on the wire.

A result that does not obey these rules gives the JSON-RPC error -32603 "tool output does not match outputSchema". The data of the error holds the messages. A task-augmented call gets the same check: the task becomes failed and tasks/result gives the same error.

Required scopes

Declare required_scopes [...] in a tool block: a tools/call without all the scopes gets 403 and tools/list hides the tool from a principal that lacks them. A tool 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 tool is unique in the module: two tools with the same name raise at compile time. The name is unique in the server too: the runtime refuses to boot when two tool modules of one server declare the same name. The boot check reads list/0 of each module.

Summary

Callbacks

Runs the tool params["name"] with the arguments params["arguments"].

Returns the tools of the module: %OzMcp.Structs.Tool{} structs, or maps with the wire keys.

Types

call_result()

@type call_result() ::
  {:ok,
   %OzMcp.Structs.CallToolResult{
     _meta: term(),
     content: term(),
     extras: term(),
     isError: term(),
     structuredContent: term()
   }}
  | {:ok, map()}
  | {:error, %OzMcp.Utils.Error{code: term(), data: term(), message: term()}}

name()

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

rpc_params()

@type rpc_params() :: map()

Callbacks

call(ctx, rpc_params)

@callback call(OzMcp.Context.ctx(), rpc_params()) :: call_result()

Runs the tool params["name"] with the arguments params["arguments"].

params is the full params object of tools/call. The input schema of the tool checked the arguments and gave the default values, before the call.

Return:

  • {:ok, %CallToolResult{}} or {:ok, map}: the result of the tool. Set isError: true for an error that the model can correct.
  • {:error, %OzMcp.Utils.Error{}}: a protocol error, for example an unknown tool (-32602).

Each other return value gives the client a -32603 error. The callback runs in a supervised process of its own, after the request process.

Example

@impl true
def call(_ctx, %{"name" => "echo", "arguments" => %{"text" => text}}) do
  {:ok, %{content: [%{type: "text", text: text}]}}
end

list()

@callback list() ::
  [
    %OzMcp.Structs.Tool{
      _meta: term(),
      annotations: term(),
      description: term(),
      execution: term(),
      extras: term(),
      icons: term(),
      inputSchema: term(),
      name: term(),
      outputSchema: term(),
      required_scopes: term(),
      title: term()
    }
  ]
  | [map()]

Returns the tools of the module: %OzMcp.Structs.Tool{} structs, or maps with the wire keys.

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