NAME

MCP::Client::Exceptions - the typed failures thrown by MCP::Client

DESCRIPTION

Every failure this distribution raises on its own behalf is an X::MCP::Client, so one CATCH clause separates "the MCP conversation went wrong" from "the code around it went wrong". The subclasses carry the context you would otherwise have to scrape back out of a message string: the exit code and last words of a server process that died, the version list a server said it would accept, the JSON-RPC error code and data payload the server sent.

The failures

• X::MCP::Client::Timeout — a request outlived its budget. Carries seconds, and method/id when the caller registered them.

• X::MCP::Client::ServerGone — the server process exited (or the HTTP connection died) with requests in flight. Carries exit-code, signal, command and stderr-tail, the tail of the child's stderr ring buffer — which is usually the only place the real reason is written.

• X::MCP::Client::Protocol — the peer said something the protocol does not allow, or answered with a JSON-RPC error. Carries code and the verbatim data payload when it came off the wire.

• X::MCP::Client::UnsupportedVersion — no overlap between the versions we speak and the versions the server speaks. Carries requested and supported.

• X::MCP::Client::Cancelled — a request was abandoned by the caller.

• X::MCP::Client::InputLoopExceeded — a multi round-trip request kept asking for input past max-input-rounds.

• X::MCP::Client::TransportClosed — the transport was closed, either by close or by a failure that took the connection with it.

• X::MCP::Client::SpawnFailed — the server command could not be started.

EXAMPLES

Distinguish "this server is broken" from "this call is slow":

use MCP::Client::Exceptions;

{
	CATCH {
		when X::MCP::Client::Timeout {
			note "gave up on {.method // 'request'} after {.seconds}s";
		}
		when X::MCP::Client::ServerGone {
			note "server died (exit {.exit-code // '?'})";
			note "  last words: {.stderr-tail}" if .stderr-tail.chars;
		}
		when X::MCP::Client {
			note "MCP failure: {.^name}: {.message}";
		}
	}
	# ... an MCP::Client call ...
}

Read the machine-readable half of a protocol error rather than its message:

CATCH {
	when X::MCP::Client::Protocol {
		if .code == -32022 {   # UNSUPPORTED_PROTOCOL_VERSION
			note "server offers: " ~ (.data<supported> // []).join(', ');
		}
	}
}