Pyjo.MCP.Test - Testing servers of MCP

from Pyjo.File import curfile
from Pyjo.MCP.Test import Test
from Pyjo.Test import *

t = Test(curfile().dirname().sibling('calculator.py'))

t.discover_ok().status_is(200).result_is('/capabilities', {'tools': {}})
t.list_tools_ok().status_is(200).tool_exists('divide')
t.call_ok('divide', a=7, b=2).status_is(200).structured_content_is(3.5).is_error_is(False)
t.call_ok('divide', {'a': 1, 'b': 0}).is_error_is(True).text_content_is('Division by zero')
t.call_ok('power').error_code_is(-32602).error_message_is('Unknown tool: power')

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

import Pyjo.MCP.Test

t = Pyjo.MCP.Test.new(curfile().dirname().sibling('calculator.py'))

# A request without its header Mcp-Name
params = {'name': 'add', 'arguments': {'a': 1, 'b': 2}}
t.mcp_ok('tools/call', params, headers={'Mcp-Name': None}).status_is(400)
t.error_message_is('Header mismatch: Missing Mcp-Name header')

done_testing()

Pyjo.MCP.Test is Pyjo.Test.Pyjo for the servers of the Model Context Protocol, with the requests of Pyjo.MCP.Client: the envelope of JSON-RPC, the _meta of the client and the headers of MCP made from the body, as a client sends them, and assertions of the response of JSON-RPC, which the client reads from JSON or from a stream of events.

The arguments of a tool go as a dict or as keyword arguments of call_ok(), after the name of the tool, which is only positional, so that no argument of a tool clashes with it.

See also

Pyjo.MCP.Client, Pyjo.MCP.Server, Pyjo.Test.Pyjo, Pyjo.MCP.

Classes

class Pyjo.MCP.Test.Pyjo_MCP_Test(app: Any = None, config: dict[str, Any] | None = None, /)[source]

Pyjo.MCP.Test inherits all attributes and methods from Pyjo.Test.Pyjo and implements the following new ones.

__init__(app: Any = None, config: dict[str, Any] | None = None, /) → None[source]
t = Pyjo.MCP.Test.new()
t = Pyjo.MCP.Test.new(Pyjo.File.new('/path/to/server.py'))
t = Pyjo.MCP.Test.new(app, {'foo': 'bar'})

Construct a new Pyjo.MCP.Test object, with the application of Pyjo.Test.Pyjo.Pyjo_Test_Pyjo.__init__().

call_ok(tool: str, arguments: dict[str, Any] | None = None, /, **kwargs: Any) → Self[source]
t = t.call_ok('greet')
t = t.call_ok('greet', name='Pyjo')
t = t.call_ok('greet', {'name': 'Pyjo'})

Call a tool with tools/call, with its arguments as a dict or as keyword arguments, and check for transport errors. The headers Mcp-Param-{name} of the x-mcp-header of a tool come from the tools of the last list_tools_ok(), as a client knows them from its definition.

t.list_tools_ok().call_ok('execute_sql', region='eu', query='SELECT 1').status_is(200)
property client: Pyjo_MCP_Client[source]
client = t.client
t.client = Pyjo.MCP.Client.new('/api/mcp')

The Pyjo.MCP.Client of the requests, of the endpoint /mcp by default, which sends them with ua.

# Another endpoint, client and capabilities
t.client.url = '/api/mcp'
t.client.name = 'ExampleClient'
t.client.capabilities = {'elicitation': {}}
complete_ok(ref: dict[str, Any], argument: str, value: str, arguments: dict[str, str] | None = None, /, *, headers: dict[str, Any] | None = None, meta: dict[str, Any] | None = None) → Self[source]
t = t.complete_ok({'type': 'ref/prompt', 'name': 'review'}, 'language', 'Py')
t = t.complete_ok({'type': 'ref/resource', 'uri': 'notes://{number}'}, 'number', '1')

Complete the value of an argument of a prompt, or of a variable of a resource template, with completion/complete, with the values of the other arguments, and check for transport errors, with the headers and the _meta of mcp_ok().

t.complete_ok({'type': 'ref/prompt', 'name': 'review'}, 'language', 'P')
t.result_is('/completion/values', ['Perl', 'Python'])
discover_ok(*, headers: dict[str, Any] | None = None, meta: dict[str, Any] | None = None) → Self[source]
t = t.discover_ok()
t = t.discover_ok(headers={'MCP-Protocol-Version': '2025-11-25'})

Discover the server with server/discover, and check for transport errors, with the headers and the _meta of mcp_ok().

error_code_is(code: int, desc: str | None = None) → Self[source]
t = t.error_code_is(-32602)
t = t.error_code_is(-32602, 'invalid params')

Check the code of the error of JSON-RPC of the response.

error_is(*args: Any) → Self[source]
t = t.error_is({'code': -32601, 'message': 'Method not found'})
t = t.error_is('/data/supported', ['2026-07-28'])
t = t.error_is('/code', -32601, 'right code')

Check the value of the error of JSON-RPC of the response, at a JSON Pointer of Pyjo.JSON.Pointer, which defaults to the whole error.

error_message_is(message: str, desc: str | None = None) → Self[source]
t = t.error_message_is('Unknown tool: power')
t = t.error_message_is('Unknown tool: power', 'right message')

Check the message of the error of JSON-RPC of the response.

error_message_like(regex: Any, desc: str | None = None) → Self[source]
t = t.error_message_like(re.compile(r'^Unknown tool'))
t = t.error_message_like(re.compile(r'^Unknown tool'), 'right message')

Check the message of the error of JSON-RPC of the response for a similar match.

get_prompt_ok(name: str, arguments: dict[str, Any] | None = None, /, **kwargs: Any) → Self[source]
t = t.get_prompt_ok('review')
t = t.get_prompt_ok('review', code='x = 1')
t = t.get_prompt_ok('review', {'code': 'x = 1'})

Get the messages of a prompt with prompts/get, with its arguments as a dict or as keyword arguments, and check for transport errors.

t.get_prompt_ok('review', code='x = 1').status_is(200).text_content_like(r'x = 1')
input_ok(responses: dict[str, Any] | None = None, /, *, headers: dict[str, Any] | None = None, meta: dict[str, Any] | None = None) → Self[source]
t = t.input_ok({'confirm': {'action': 'accept'}})

Send the last request again, as the next round of a request whose result is input_required, with the responses to its inputRequests, by their keys, and its requestState, and check for transport errors, with the headers and the _meta of mcp_ok().

t.call_ok('delete', path='a.txt').result_is('/resultType', 'input_required')
t.result_is('/inputRequests/confirm/method', 'elicitation/create')
t.input_ok({'confirm': {'action': 'accept'}}).text_content_is('Deleted a.txt')
is_error_is(value: bool, desc: str | None = None) → Self[source]
t = t.is_error_is(False)
t = t.is_error_is(True, 'error of the tool')

Check isError of the result of a tool, which is true for an error of the execution of the tool, as its arguments that the inputSchema does not validate.

list_prompts_ok(*, headers: dict[str, Any] | None = None, meta: dict[str, Any] | None = None) → Self[source]
t = t.list_prompts_ok()

List the prompts with prompts/list, and check for transport errors, with the headers and the _meta of mcp_ok().

list_resource_templates_ok(*, headers: dict[str, Any] | None = None, meta: dict[str, Any] | None = None) → Self[source]
t = t.list_resource_templates_ok()

List the resource templates with resources/templates/list, and check for transport errors, with the headers and the _meta of mcp_ok().

list_resources_ok(*, headers: dict[str, Any] | None = None, meta: dict[str, Any] | None = None) → Self[source]
t = t.list_resources_ok()

List the resources with resources/list, and check for transport errors, with the headers and the _meta of mcp_ok().

list_tools_ok(*, headers: dict[str, Any] | None = None, meta: dict[str, Any] | None = None) → Self[source]
t = t.list_tools_ok()

List the tools with tools/list, and check for transport errors, with the headers and the _meta of mcp_ok(). The client keeps the tools, whose x-mcp-header give the headers of the arguments of call_ok().

listen_ok(notifications: dict[str, Any] | None = None, /, *, headers: dict[str, Any] | None = None, meta: dict[str, Any] | None = None) → Self[source]
t = t.listen_ok({'toolsListChanged': True})
t = t.listen_ok({'resourceSubscriptions': ['file:///project/README.md']})

Open a subscription with subscriptions/listen, for the notifications that the filter asks for, with the headers and the _meta of mcp_ok(), and check that its stream of events is established, as post_sse_ok() does. Its messages are the events of the stream, which notification_ok() waits for, and sse_finish_ok() closes it.

t.listen_ok({'toolsListChanged': True})
t.notification_ok().notification_is('/method', 'notifications/subscriptions/acknowledged')
server.notify_list_changed('tools')
t.notification_ok().notification_is('/method', 'notifications/tools/list_changed')
t.sse_finish_ok()
mcp_ok(method: str, params: dict[str, Any] | None = None, /, *, headers: dict[str, Any] | None = None, id: Any = None, meta: dict[str, Any] | None = None) → Self[source]
t = t.mcp_ok('tools/list')
t = t.mcp_ok('tools/call', {'name': 'add', 'arguments': {'a': 1, 'b': 2}})
t = t.mcp_ok('tools/call', {'name': 'add', 'arguments': {}}, headers={'Mcp-Name': 'foo'})
t = t.mcp_ok('server/discover', id='discover-1', meta={'io.modelcontextprotocol/clientInfo': None})

Send a request of MCP with the method and its parameters, as Pyjo.MCP.Client builds it, and check for transport errors. The id replaces the one of the client, a value of meta replaces the one of its key in the _meta of the request, before the headers are made from the body, and a value of headers replaces the header of its name after it, None dropping either, so that a test sends what a client must not.

# A revision of the specification that the server does not support
t.mcp_ok('tools/list', meta={'io.modelcontextprotocol/protocolVersion': '1900-01-01'}).status_is(400)
t.error_code_is(-32022)
notification_is(*args: Any) → Self[source]
t = t.notification_is({'jsonrpc': '2.0', 'method': 'notifications/tools/list_changed', 'params': {}})
t = t.notification_is('/method', 'notifications/resources/updated')
t = t.notification_is('/params/uri', 'file:///project/README.md', 'right resource')

Check the value of the message of JSON-RPC of the last event of the subscription of listen_ok(), a notification, or the response at its end, at a JSON Pointer of Pyjo.JSON.Pointer, which defaults to the whole message.

notification_ok(desc: str | None = None) → Self[source]
t = t.notification_ok()
t = t.notification_ok('got a notification')

Wait for the next message of the subscription of listen_ok(), as sse_ok() waits for the next event.

notifications: list[dict[str, Any]]
notifications = t.notifications

The notifications of JSON-RPC that the server sent before the response of the last request, in its stream of events, as the progress of a tool.

params = {'name': 'count', 'arguments': {'to': 3}}
t.mcp_ok('tools/call', params, meta={'progressToken': 'count-1'}).status_is(200)
is_ok(t.notifications[0]['method'], 'notifications/progress', 'progress')
prompt_exists(name: str, desc: str | None = None) → Self[source]
t = t.prompt_exists('review')
t = t.prompt_exists('review', 'has a review')

Check if the result of prompts/list has a prompt of the name.

prompt_exists_not(name: str, desc: str | None = None) → Self[source]
t = t.prompt_exists_not('summary')
t = t.prompt_exists_not('summary', 'no summary')

Opposite of prompt_exists().

prompt_is(name: str, *args: Any) → Self[source]
t = t.prompt_is('review', {'name': 'review', 'arguments': []})
t = t.prompt_is('review', '/arguments/0/name', 'code')
t = t.prompt_is('review', '/arguments/0/required', True, 'code required')

Check the value of the definition of a prompt of the result of prompts/list, at a JSON Pointer of Pyjo.JSON.Pointer, which defaults to the whole definition.

read_resource_ok(uri: str, *, headers: dict[str, Any] | None = None, meta: dict[str, Any] | None = None) → Self[source]
t = t.read_resource_ok('file:///project/README.md')

Read the contents of a resource with resources/read, and check for transport errors, with the headers and the _meta of mcp_ok().

t.read_resource_ok('file:///project/README.md').status_is(200).text_content_like(r'^# ')
resource_exists(uri: str, desc: str | None = None) → Self[source]
t = t.resource_exists('file:///project/README.md')
t = t.resource_exists('file:///project/README.md', 'has a README')

Check if the result of resources/list has a resource of the URI.

resource_exists_not(uri: str, desc: str | None = None) → Self[source]
t = t.resource_exists_not('file:///etc/passwd')
t = t.resource_exists_not('file:///etc/passwd', 'no secrets')

Opposite of resource_exists().

resource_is(uri: str, *args: Any) → Self[source]
t = t.resource_is('file:///project/README.md', {'uri': 'file:///project/README.md', 'name': 'readme'})
t = t.resource_is('file:///project/README.md', '/mimeType', 'text/markdown')
t = t.resource_is('file:///project/README.md', '/name', 'readme', 'right name')

Check the value of the definition of a resource of the result of resources/list, at a JSON Pointer of Pyjo.JSON.Pointer, which defaults to the whole definition.

resource_template_exists(uri: str, desc: str | None = None) → Self[source]
t = t.resource_template_exists('notes://{number}')
t = t.resource_template_exists('notes://{number}', 'has notes')

Check if the result of resources/templates/list has a resource template of the URI Template.

resource_template_exists_not(uri: str, desc: str | None = None) → Self[source]
t = t.resource_template_exists_not('file:///{+path}')
t = t.resource_template_exists_not('file:///{+path}', 'no files')

Opposite of resource_template_exists().

resource_template_is(uri: str, *args: Any) → Self[source]
t = t.resource_template_is('notes://{number}', {'uriTemplate': 'notes://{number}', 'name': 'note'})
t = t.resource_template_is('notes://{number}', '/mimeType', 'text/plain')
t = t.resource_template_is('notes://{number}', '/name', 'note', 'right name')

Check the value of the definition of a resource template of the result of resources/templates/list, at a JSON Pointer of Pyjo.JSON.Pointer, which defaults to the whole definition.

response: dict[str, Any] | None
response = t.response
t.response = {'jsonrpc': '2.0', 'id': 1, 'result': {}}

The response of JSON-RPC of the last request, from JSON or from a stream of events, which the assertions of the response test, or None for none.

# More specific tests
is_ok(t.response['result']['content'][0]['type'], 'text', 'right type')
response_is(*args: Any) → Self[source]
t = t.response_is({'jsonrpc': '2.0', 'id': 1, 'result': {}})
t = t.response_is('/id', 1)
t = t.response_is('/id', 1, 'right id')

Check the value of the response of JSON-RPC, at a JSON Pointer of Pyjo.JSON.Pointer, which defaults to the whole response.

result_is(*args: Any) → Self[source]
t = t.result_is({'resultType': 'complete', 'tools': []})
t = t.result_is('/content/0/text', 'Hello, Pyjo!')
t = t.result_is('/content/0/text', 'Hello, Pyjo!', 'right text')

Check the value of the result of the response, at a JSON Pointer of Pyjo.JSON.Pointer, which defaults to the whole result.

structured_content_is(*args: Any) → Self[source]
t = t.structured_content_is(3.5)
t = t.structured_content_is('/temperature', 21.5)
t = t.structured_content_is('/temperature', 21.5, 'right temperature')

Check the value of the structuredContent of the result of a tool, at a JSON Pointer of Pyjo.JSON.Pointer, which defaults to the whole value.

text_content_is(text: str, desc: str | None = None) → Self[source]
t = t.text_content_is('Hello, Pyjo!')
t = t.text_content_is('Hello, Pyjo!', 'right text')

Check the text of the result: of the content of a tool, of the content of the messages of a prompt, or of the contents of a resource, its items of the type text joined.

t.get_prompt_ok('review', code='x = 1').text_content_is('Review this Python code:\nx = 1')
t.read_resource_ok('file:///project/README.md').text_content_is('# Project')
text_content_like(regex: Any, desc: str | None = None) → Self[source]
t = t.text_content_like(re.compile(r'/name: Missing property'))
t = t.text_content_like(re.compile(r'/name: Missing property'), 'right error')

Check the text of the result, as text_content_is() takes it, for a similar match.

tool_exists(name: str, desc: str | None = None) → Self[source]
t = t.tool_exists('greet')
t = t.tool_exists('greet', 'has a greeting')

Check if the result of tools/list has a tool of the name.

tool_exists_not(name: str, desc: str | None = None) → Self[source]
t = t.tool_exists_not('power')
t = t.tool_exists_not('power', 'no power')

Opposite of tool_exists().

tool_is(name: str, *args: Any) → Self[source]
t = t.tool_is('greet', {'name': 'greet', 'inputSchema': {'type': 'object'}})
t = t.tool_is('greet', '/description', 'Greet somebody by name.')
t = t.tool_is('greet', '/inputSchema/required', ['name'], 'right required arguments')

Check the value of the definition of a tool of the result of tools/list, at a JSON Pointer of Pyjo.JSON.Pointer, which defaults to the whole definition.