NAME
MCP::Tool - Tool container
SYNOPSIS
use MCP::Tool;
my $tool = MCP::Tool->new;DESCRIPTION
MCP::Tool is a container for tools to be called. Arguments and structured content are validated with JSON::Schema::Tiny, which covers JSON Schema 2020-12, 2019-09, and draft-07, but only partially implements $id, $dynamicRef, and $dynamicAnchor.
ATTRIBUTES
MCP::Tool implements the following attributes.
annotations
my $annotations = $tool->annotations;
$tool = $tool->annotations({title => '...'});Optional annotations for the tool which provide additional metadata about the tool behavior.
code
my $code = $tool->code;
$tool = $tool->code(sub { ... });Tool code.
description
my $description = $tool->description;
$tool = $tool->description('A brief description of the tool');Description of the tool.
input_schema
my $schema = $tool->input_schema;
$tool = $tool->input_schema({type => 'object', properties => {foo => {type => 'string'}}});JSON schema for validating input arguments. Schemas without a $schema keyword are interpreted as JSON Schema 2020-12, the default dialect of the Model Context Protocol; schemas with one are interpreted as the dialect it names, which has to be one of 2020-12, 2019-09, or draft-07. Any other dialect is an error.
Properties may carry an x-mcp-header keyword, naming the HTTP header a client has to mirror the argument in, for the benefit of gateways that route on headers alone. See "header_params".
max_schema_depth
my $depth = $tool->max_schema_depth;
$tool = $tool->max_schema_depth(10);How many levels deep validation may descend into a schema before it is aborted, which bounds the work a deeply nested or recursive schema can cause. Defaults to 50.
name
my $name = $tool->name;
$tool = $tool->name('my_tool');Name of the tool.
output_schema
my $schema = $tool->output_schema;
$tool = $tool->output_schema({type => 'object', properties => {foo => {type => 'string'}}});JSON schema for validating output results, interpreted with the same dialect rules as "input_schema".
METHODS
MCP::Tool inherits all methods from MCP::Primitive and implements the following new ones.
audio_result
my $result = $tool->audio_result($bytes, $options, $is_error);Returns an audio result in the expected format, optionally marking it as an error.
These options are currently available:
- mime_type
-
mime_type => 'audio/wav'Specifies the MIME type of the audio, defaults to
audio/wav.
call
my $result = $tool->call($args, $context);Calls the tool with the given arguments and context, returning a result. The result can be a promise or a direct value.
header_params
my $params = $tool->header_params;All properties of "input_schema" annotated with x-mcp-header, as an array reference of hash references with name, path and type keys. Only properties reachable from the schema root through a chain of properties keys are considered, since the protocol forbids x-mcp-header anywhere else. The result is cached after the first call.
image_result
my $result = $tool->image_result($bytes, $options, $is_error);Returns an image result in the expected format, optionally marking it as an error.
These options are currently available:
- annotations
-
annotations => {audience => ['user']}Annotations for the image.
- mime_type
-
mime_type => 'image/png'Specifies the MIME type of the image, defaults to
image/png.
resource_link_result
my $result = $tool->resource_link_result($uri, $options, $is_error);Returns a resource link result in the expected format, optionally marking it as an error.
These options are currently available:
- annotations
-
annotations => {audience => ['user']}Annotations for the resource link.
- description
-
description => 'A brief description of the resource'Description of the resource.
- mime_type
-
mime_type => 'text/x-perl'Specifies the MIME type of the resource, defaults to
text/plain. - name
-
name => 'Resource Name'Name of the resource.
structured_result
my $result = $tool->structured_result({foo => 'bar'}, $is_error);Returns a structured result in the format of "output_schema", optionally marking it as an error. Data that does not match "output_schema" is turned into an error result instead.
text_result
my $result = $tool->text_result('Some text', $is_error);Returns a text result in the expected format, optionally marking it as an error.
validate_input
my $bool = $tool->validate_input($args);Validates the input arguments against "input_schema". Returns true if validation failed. References are only resolved as JSON pointers into the schema itself, so a $ref to a remote schema is never fetched over the network and simply fails validation.
validate_output
my $bool = $tool->validate_output($data);Validates structured content against "output_schema". Returns true if validation failed, and false if the tool has no output schema.
SEE ALSO
MCP, https://mojolicious.org, https://modelcontextprotocol.io.