NAME

AnyEvent::MCP::Server::Request - one MCP request

DESCRIPTION

Each incoming request gets a Request object. The handler can reply immediately, or keep the object and reply when asynchronous work finishes. Returning from the handler does not complete the request; calling reply, result or error does.

There is one important consequence: do not reply after cancellation or after another callback has already completed the request. Check finished in late asynchronous callbacks. A second reply is a programming error.

You normally receive this object as the first argument to a AnyEvent::MCP::Server::Toolset callback. See "TUTORIAL" in AnyEvent::MCP::Server::Simple for complete synchronous and asynchronous examples rather than constructing requests yourself.

PUBLIC FIELDS

Request fields are accessed directly through the hash.

$req->{server}

The server handling this request.

$req->{id}

The JSON-RPC request id, used to associate the response with the request.

$req->{method}

The JSON-RPC method name, such as tools/call.

$req->{protocol_version}

The protocol revision used for this request. Modern requests supply it in _meta; legacy requests use the initialized peer or HTTP version.

$req->{peer}

The connection's peer hash reference, supplied by the transport or embedder. It holds transport context and legacy state, rather than a user identity. Modern client identity and capabilities come from this request's _meta.

$req->{params}

The original decoded JSON-RPC parameters. For a tool call, this hash contains name, arguments and any _meta supplied by the client. These are the protocol parameters, rather than just the tool arguments.

$req->{tool}

The tool name from $req->{params}{name}. Present for tool calls.

$req->{args}

The tool argument hash reference from $req->{params}{arguments}. Present for tool calls. The tool callback also receives this same reference as its second parameter, for convenience.

$req->{toolset}

The Toolset invoking the tool callback. Set by the Toolset when it dispatches the call; absent for requests dispatched without a Toolset.

$req->{finished}

True after a reply or cancellation. Replying to a finished request is an error. Notifications and progress after completion are ignored.

$req->{cancelled}

True if the request was cancelled. An asynchronous handler can check this before attempting to reply.

METHODS

$grant = $req->require_permission ({ %request })

Synchronously checks a permission request using the server's permissions object. %request has the fields described by "check" in AnyEvent::MCP::Server::Permissions. Returns the granted sandbox-grant array reference; it can be reduced from the requested set.

A denial dies. A missing permission throws a special exception handled by Server, which asks and retries the handler. Multiple checks are supported: one-time grants belong to this tool invocation and survive permission retries. They do not authorize later calls. Current rules are checked on every retry.

Complete all checks before side effects or asynchronous work starts. The handler can run more than once. Do not catch the permission exception as an ordinary tool error; let it reach Server's dispatch boundary.

$req->reply ($result)

Completes the request with the MCP result hash reference $result. The server adds the JSON-RPC envelope. Tools do not construct JSON-RPC errors. Dies if the request has already finished.

Use this method for arbitrary MCP results, including structured errors, large results and results requiring a particular content representation.

$req->error ($message)

Replies with isError set to true and $message as one text content item. Use reply for errors with structured content or other content types.

$req->result ($data)

Replies with the hash reference $data as structuredContent, and its JSON encoding as one text content item for clients that consume only text.

This deliberately duplicates the data. Use reply for large results or when JSON text is unsuitable, including clients that encode text as JSON again. Arrays and scalars must be wrapped in an object explicitly.

$req->notify ($method, $params)

Sends a notification associated with this request. $method is the notification method name and $params its parameter hash reference.

A notification does not complete the request. Delivery is best effort: notifications can be dropped if the transport does not implement delivery. Calls after completion are ignored.

$req->progress ($progress, $total, $message)

Sends a progress notification if the client supplied a progress token in $req->{params}{_meta}{progressToken}. $progress is the amount completed; $total and $message can be omitted or undefined.

Uses notify, with the same best-effort delivery. Calls after completion are ignored.

$req->cancel ($reason)

Marks the request as cancelled and calls on_cancel, allowing the handler to stop work and release resources. $reason is an optional explanation.

Cancellation completes the transport's request bookkeeping without sending a JSON-RPC response.

EVENTS

These callbacks are stored in the request hash like other MCP events.

on_reply => $callback->($req, $result)

Called once when the request is completed with reply. The server installs $callback to deliver the result.

on_notify => $callback->($req, $method, $params)

Called for each notification while the request is active. The server installs $callback to deliver notifications through the transport.

on_cancel => $callback->($req, $reason)

Called once when the request is cancelled. A handler can set $callback to cancel its asynchronous operation.