Pyjo.MCP.Tool - Tool of a server of MCP

from Pyjo.MCP.Tool import Tool

def add(a: int, b: int) -> int:
    """Add two numbers.

    :param a: The first number.
    :param b: The second number.
    """
    return a + b

tool = Tool(add)
print(tool.name, tool.description, tool.input_schema)

# Or import the module, as in Google Python Style Guide

import Pyjo.MCP.Tool

tool = Pyjo.MCP.Tool.new(add, name='math.add', title='Addition')
tool.call_p({'a': 1, 'b': 2}).then(print).wait()

Pyjo.MCP.Tool is a tool of Pyjo.MCP.Server, a function that a language model calls with the arguments of its inputSchema. The name, the description and the schemas of the tool are those of the function by default: its name, the first paragraph of its docstring, the schema of its parameters, with the descriptions of its docstring, and the one of what it returns, of Pyjo.JSON.Schema.

The function returns the result of the tool, as a value, a Pyjo.Promise of it or a coroutine, of an async def:

  • a value of the outputSchema of the tool, as of the annotation of what the function returns, is the structuredContent of the result, and its JSON the text of its content;

  • a string, without an outputSchema, is the text of the content;

  • a dict with content, without an outputSchema, is the result as it is, for the content of another type, as an image;

  • None is a result without content, and another value is its JSON.

Arguments that the inputSchema does not validate, and a function that raises Error, give a result with isError, whose text the language model reads to call the tool again, as a tool reports the errors of its execution. Another exception is an error of the server, which the result does not tell.

See also

Pyjo.MCP.Server, Pyjo.JSON.Schema, Pyjo.MCP.

Classes

exception Pyjo.MCP.Tool.Error(message: Anything = None)[source]

An error of the execution of a tool, which the result of the call tells with isError, so that the language model can correct the arguments.

raise Pyjo.MCP.Tool.Error.new('Invalid departure date: must be in the future')
class Pyjo.MCP.Tool.Pyjo_MCP_Tool(cb: Callable[[...], Any], *, name: str | None = None, title: str | None = None, description: str | None = None, input_schema: Mapping[str, Any] | Pyjo_JSON_Schema | None = None, output_schema: Mapping[str, Any] | Pyjo_JSON_Schema | bool | None = None, annotations: Mapping[str, Any] | None = None, context: bool = False)[source]

Pyjo.MCP.Tool inherits all methods from Pyjo.Base and implements the following new ones.

__init__(cb: Callable[[...], Any], *, name: str | None = None, title: str | None = None, description: str | None = None, input_schema: Mapping[str, Any] | Pyjo_JSON_Schema | None = None, output_schema: Mapping[str, Any] | Pyjo_JSON_Schema | bool | None = None, annotations: Mapping[str, Any] | None = None, context: bool = False) → None[source]
tool = Pyjo.MCP.Tool.new(add)
tool = Pyjo.MCP.Tool.new(add, name='math.add', title='Addition')
tool = Pyjo.MCP.Tool.new(lambda c, **args: ..., input_schema={'type': 'object'}, context=True)
tool = Pyjo.MCP.Tool.new(report, output_schema=False)

Construct a new Pyjo.MCP.Tool object of a function. With context, the function gets the Context of the request before its arguments. output_schema of False gives the tool no outputSchema, also when the function has the annotation of what it returns.

__json__() → dict[str, Any][source]
definition = tool.__json__()

The definition of the tool, as tools/list gives it, with its name, title, description, inputSchema, outputSchema and annotations, where it has them.

__weakref__

list of weak references to the object

annotations: dict[str, Any]
annotations = tool.annotations

The properties of the behaviour of the tool, as readOnlyHint, which a client takes as hints, for the annotations of the tool.

call_p(arguments: Mapping[str, Any], context: Any = None) → Pyjo_Promise[source]
promise = tool.call_p({'a': 1, 'b': 2})
promise = tool.call_p({'a': 1, 'b': 2}, context)

Call the function with the arguments, and return a Pyjo.Promise of the result of the tool, as tools/call gives it, without its resultType, or rejected with an exception of the function that is not an Error, an error of the server. A promise or a coroutine of the function is cancelled with the Pyjo.MCP.Server.Context of the request, as Pyjo.MCP.Server.Context.cancellable() does.

# {'content': [{'type': 'text', 'text': '3'}], 'structuredContent': 3, 'isError': False}
tool.call_p({'a': 1, 'b': 2}).then(print).wait()
cb
cb = tool.cb

The function of the tool.

context
boolean = tool.context

Whether the function gets the context of the request before its arguments.

description
description = tool.description

What the tool does, for the language model, the first paragraph of the docstring of the function by default.

property header_params: list[tuple[str, list[str], str]][source]
params = tool.header_params

The arguments of the x-mcp-header of the inputSchema, which a client of HTTP sends as the headers Mcp-Param-{name} too, each with the name, the path of the properties and the type. A header that the specification does not allow, as of a property of an array or of a number, fails with a Pyjo.Exception when the tool is made.

input_schema: Pyjo_JSON_Schema
schema = tool.input_schema

The Pyjo.JSON.Schema of the arguments, the inputSchema of the tool, the one of the parameters of the function by default.

name
name = tool.name

The name of the tool, the one of the function by default.

output_schema
schema = tool.output_schema

The Pyjo.JSON.Schema of the structuredContent of the result, the outputSchema of the tool, the one of what the function returns by default, or None.

result(value: Any = None) → dict[str, Any][source]
result = tool.result(3)
result = tool.result('Three')

The result of the tool of what the function returns. A value that the outputSchema does not validate fails with a Pyjo.Exception, as an error of the server.

title
title = tool.title

The name of the tool for people, or None.

Pyjo.MCP.Tool.error_result(text: str) → dict[str, Any][source]
result = Pyjo.MCP.Tool.error_result('Invalid departure date')

A result of a tool with the text of an error of its execution and isError.

Pyjo.MCP.Tool.text_result(text: str) → dict[str, Any][source]
result = Pyjo.MCP.Tool.text_result('Sunny')

A result of a tool with a text.