MCPEx.Transport.TestServer (MCPEx v0.1.0)
Test server implementation to pair with MCPEx.Transport.Test.
This module simulates an MCP server for integration testing, allowing tests to verify client behavior without requiring an actual MCP server.
Features
- Simulate server responses and notifications
- Control message timing and failures
- Test specific scenarios and protocol flows
- Verify client requests match expectations
- Support all MCP protocol features (resources, tools, prompts, sampling)
Usage
# Create a test server with capabilities
server = MCPEx.Transport.TestServer.new(
capabilities: [:resources, :tools]
)
# Start a test transport connected to this server
{:ok, transport} = MCPEx.Transport.Test.start_link(server: server)
# Trigger server events
MCPEx.Transport.TestServer.send_notification(server, %{
jsonrpc: "2.0",
method: "notifications/resources/updated"
})
# Verify client messages
assert MCPEx.Transport.TestServer.last_message(server).method == "initialize"Summary
Functions
Adds a custom handler for a specific method or response.
Adds a prompt to the server.
Adds a resource to the server.
Adds a tool to the server.
Creates a standard error response for use in handlers.
Gets the current recording for later replay.
Gets the last message received by the server.
Creates a new test server instance.
Processes a message from a client.
Checks if the server received a message matching the given criteria.
Gets all messages received by the server.
Registers a client with the server.
Triggers a sampling request.
Sends a notification message to a client.
Sets a custom response handler for a specific method.
Unregisters a client from the server.
Types
@type client_ref() :: reference()
@type t() :: %MCPEx.Transport.TestServer{ capabilities: [atom()], clients: [{client_ref(), pid()}], delay: non_neg_integer(), error_rate: float(), log: list(), prompts: [map()], received_messages: [map()], recording: list() | nil, resources: [map()], responses: map(), scenario: atom() | nil, tools: [map()] }
Functions
Adds a custom handler for a specific method or response.
Parameters
server- The server structmethod- The method name to handlehandler_fn- A function that takes the params and returns the result or an error
Returns
- Updated server struct
Adds a prompt to the server.
Parameters
server- The server structprompt- The prompt to add
Returns
- Updated server struct
Adds a resource to the server.
Parameters
server- The server structresource- The resource to add
Returns
- Updated server struct
Adds a tool to the server.
Parameters
server- The server structtool- The tool to add
Returns
- Updated server struct
Creates a standard error response for use in handlers.
Parameters
error_type- The type of error (atom like :invalid_params, :parse_error)message- The error messagedata- Optional additional data about the error
Returns
{:error, code, message}- Error tuple that can be returned from handlers
Gets the current recording for later replay.
Parameters
server- The server struct
Returns
- The recording data or nil if not in recording mode
Gets the last message received by the server.
Parameters
server- The server struct
Returns
- The last message or nil if none
Creates a new test server instance.
Options
:capabilities- List of server capabilities (default: []):scenario- Name of the test scenario to run (default: nil):delay- Artificial delay in milliseconds for responses (default: 0):error_rate- Probability of simulated errors (0.0-1.0, default: 0.0):resources- Initial resources to serve (default: []):tools- Initial tools to serve (default: []):prompts- Initial prompts to serve (default: [])
Returns
- A new TestServer struct
Processes a message from a client.
Parameters
server- The server structclient_ref- Reference for the client sending the messagemessage- The message received from the client
Returns
{response, updated_server}- Response to send back and updated server
Checks if the server received a message matching the given criteria.
Parameters
server- The server structcriteria- Criteria to match (method, id, etc.)
Returns
trueorfalse
Gets all messages received by the server.
Parameters
server- The server struct
Returns
- List of messages in reverse chronological order
@spec register_client(t(), pid()) :: {client_ref(), t()}
Registers a client with the server.
Parameters
server- The server structclient_pid- PID of the client transport process
Returns
{ref, updated_server}- The client reference and updated server
@spec request_sampling(t(), keyword(), client_ref() | nil) :: t()
Triggers a sampling request.
Parameters
server- The server structoptions- Options for the sampling requestclient_ref- Optional client reference (first client if nil)
Returns
- Updated server struct
@spec send_notification(t(), map(), client_ref() | nil) :: t()
Sends a notification message to a client.
Parameters
server- The server structnotification- The notification message to sendclient_ref- Optional client reference (sends to all if nil)
Returns
- Updated server struct
Sets a custom response handler for a specific method.
Parameters
server- The server structmethod- The method to handlehandler- Function that takes (server, message) and returns response
Returns
- Updated server struct
@spec unregister_client(t(), client_ref()) :: t()
Unregisters a client from the server.
Parameters
server- The server structclient_ref- Reference for the client to unregister
Returns
- Updated server struct