Class: ActionModelContext::Tool

Inherits:
Object
  • Object
show all
Includes:
Primitive
Defined in:
lib/action_model_context/tool.rb

Overview

Base class of the tools. An application subclasses it through ApplicationTool, under app/mcp/tools.

Examples:

class EchoTool < ApplicationTool
  argument :message, :string, required: true
  argument :times, :integer

  def call(message:, times: 1) = message * times
end

Constant Summary collapse

ARGUMENT_TYPES =

The types argument accepts.

%i[string integer number boolean array object].freeze
SCHEMA_KEYWORDS =

JSON Schema 2020-12, the dialect MCP mandates (SEP-1613), minus type and required that argument sets itself.

%w[
  $id $schema $ref $anchor $dynamicRef $dynamicAnchor $vocabulary $comment $defs
  prefixItems items contains additionalProperties properties patternProperties dependentSchemas propertyNames
  if then else allOf anyOf oneOf not unevaluatedItems unevaluatedProperties
  const enum multipleOf maximum exclusiveMaximum minimum exclusiveMinimum maxLength minLength pattern
  maxItems minItems uniqueItems maxContains minContains maxProperties minProperties dependentRequired
  title description default deprecated readOnly writeOnly examples format contentEncoding contentMediaType contentSchema
].freeze

Instance Attribute Summary

Attributes included from Primitive

#context

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Primitive

description, title

Class Method Details

.annotations(**hints) ⇒ Hash?

Declares the annotations, or reads them.

Parameters:

  • hints (Hash) —

    the keywords of MCP::Tool::Annotations, such as read_only_hint: true

Returns:

  • (Hash, nil) —

    nil when none are declared

.argument(name, type, **keywords) ⇒ void

This method returns an undefined value.

Declares an argument of the input schema.

Examples:

argument :ids, :array, required: true, items: { type: 'integer' }, max_items: 50

Parameters:

  • name (Symbol, String) —

    the argument's name

  • type (Symbol) —

    one of ARGUMENT_TYPES

  • keywords (Hash) —

    any JSON Schema 2020-12 keyword, in snake_case or camelCase

Options Hash (**keywords):

  • :required (Boolean) — default: false —

    whether the client must send it

  • :null (Boolean) — default: false —

    whether it also accepts null

Raises:

  • (ArgumentError) —

    when the type or a keyword is unknown

.arguments_from(properties, required: []) ⇒ void

This method returns an undefined value.

Declares one argument per entry of a JSON Schema properties hash, type: [..., 'null'] becoming null: true.

Examples:

arguments_from({ title: { type: 'string' }, due_on: { type: %w[string null] } }, required: %i[title])

Parameters:

  • properties (Hash{Symbol, String => Hash}) —

    the schema of each argument

  • required (Array<Symbol, String>) (defaults to: []) —

    the names of the required arguments

Raises:

  • (ArgumentError) —

    when a property has no single type, lists its own required or takes an unknown keyword

.tool_name(name = nil) ⇒ String?

Declares the name, or reads it.

Parameters:

  • name (String, nil) (defaults to: nil) —

    the name to declare

Returns:

  • (String, nil) —

    the declared name, else the underscored class name without its Tool suffix

Instance Method Details

#call ⇒ String, ...

Runs the tool. A subclass defines it, with one keyword per argument it takes.

Returns:

  • (String, Hash, Array, MCP::Tool::Response) —

    the result, a Hash also going out as structured content

Raises:

  • (Error) —

    to answer an error result with its message

  • (NotImplementedError) —

    when no subclass defines it

#invoke(arguments) ⇒ Object

Wraps every call of the tool: override this private method and call super, as process_action in a controller. rescue_from covers it.

Parameters:

  • arguments (Hash) —

    the arguments as the client sent them, before they are sliced to the declared ones

Returns:

  • (Object) —

    the value of #call, before its conversion