MCP/Server/Request.pm

=head1 NAME

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

=head1 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
C<reply>, C<result> or C<error> does.

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

=head1 PUBLIC FIELDS

Request fields are accessed directly through the hash.

=over

=item $req->{server}

The server handling this request.

=item $req->{id}

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

=item $req->{method}

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

=item $req->{protocol_version}

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

=item $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 C<_meta>.

=item $req->{params}

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

=item $req->{tool}

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

=item $req->{args}

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

=item $req->{toolset}

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

=item $req->{finished}

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

=item $req->{cancelled}

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

=back

=head1 METHODS

=over

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

Synchronously checks a permission request using the server's C<permissions>
object. C<%request> has the fields described by
L<AnyEvent::MCP::Server::Permissions/check>. 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.

=item $req->reply ($result)

Completes the request with the MCP result hash reference C<$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.

=item $req->error ($message)

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

=item $req->result ($data)

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

This deliberately duplicates the data. Use C<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.

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

Sends a notification associated with this request. C<$method> is the
notification method name and C<$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.

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

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

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

=item $req->cancel ($reason)

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

Cancellation does not send a reply.

=back

=head1 EVENTS

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

=over

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

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

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

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

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

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

=back

=cut

package AnyEvent::MCP::Server::Request;

use common::sense;
use AnyEvent::MCP ();
use JSON::XS ();

our @ISA = qw(AnyEvent::MCP::Base);

sub require_permission {
   my ($self, $request) = @_;

   my $permissions = $self->{server}{permissions}
      or die "Server has no permission configuration\n";

   $permissions->require_permission ($self, $request)
}

sub reply {
   my ($self, $result) = @_;

   die "MCP request already finished\n"
      if $self->{finished};

   $self->{finished} = 1;

   my $reply = delete $self->{on_reply};
   delete @$self{qw(on_notify on_cancel _reply)};

   $reply->($self, $result) if $reply
}

sub error {
   my ($self, $message) = @_;

   $self->reply ({
      isError => JSON::XS::true,
      content => [{ type => "text", text => $message }],
   })
}

sub result {
   my ($self, $data) = @_;

   ref $data eq "HASH"
      or die "MCP structured result must be an object\n";

   $self->reply ({
      structuredContent => $data,
      content           => [{ type => "text", text => JSON::XS->new->encode ($data) }],
   })
}

sub notify {
   my ($self, $method, $params) = @_;

   return if $self->{finished};

   $self->event (notify => $method, $params)
}

sub progress {
   my ($self, $progress, $total, $message) = @_;

   return unless $self->{on_notify} && !$self->{finished};

   my $meta = $self->{params}{_meta}
      or return;

   return unless exists $meta->{progressToken};

   my $params = {
      progressToken => $meta->{progressToken},
      progress      => $progress,
   };

   $params->{total}   = $total   if defined $total;
   $params->{message} = $message if defined $message;

   $self->notify ("notifications/progress", $params)
}

sub cancel {
   my ($self, $reason) = @_;

   return if $self->{finished};
   $self->{finished} = $self->{cancelled} = 1;

   delete $self->{peer}{requests}{$self->{id}}
      if $self->{peer};

   my $cancel = delete $self->{on_cancel};
   delete @$self{qw(on_reply on_notify _reply)};

   $cancel->($self, $reason) if $cancel
}

1
Revision:	1.4
Committed:	Tue Oct 13 22:54:22 2026 UTC (4 weeks ago) by root
Branch:	MAIN
Changes since 1.3:	+19 -11 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			AnyEvent::MCP::Server::Request - one MCP request
4
5			=head1 DESCRIPTION
6
7	root	1.2	Each incoming request gets a Request object. The handler can reply
8			immediately, or keep the object and reply when asynchronous work finishes.
9			Returning from the handler does not complete the request; calling
10			C<reply>, C<result> or C<error> does.
11
12			There is one important consequence: do not reply after cancellation or after
13			another callback has already completed the request. Check C<finished> in
14			late asynchronous callbacks. A second reply is a programming error.
15	root	1.1
16			=head1 PUBLIC FIELDS
17
18			Request fields are accessed directly through the hash.
19
20	root	1.2	=over
21	root	1.1
22			=item $req->{server}
23
24			The server handling this request.
25
26			=item $req->{id}
27
28			The JSON-RPC request id, used to associate the response with the request.
29
30			=item $req->{method}
31
32			The JSON-RPC method name, such as C<tools/call>.
33
34			=item $req->{protocol_version}
35
36			The protocol revision used for this request. Modern requests supply it in
37			C<_meta>; legacy requests use the initialized peer or HTTP version.
38
39			=item $req->{peer}
40
41			The connection's peer hash reference, supplied by the transport or embedder.
42			It holds transport context and legacy state, rather than a user identity.
43			Modern client identity and capabilities come from this request's C<_meta>.
44
45			=item $req->{params}
46
47			The original decoded JSON-RPC parameters. For a tool call, this hash contains
48			C<name>, C<arguments> and any C<_meta> supplied by the client. These are the
49			protocol parameters, rather than just the tool arguments.
50
51			=item $req->{tool}
52
53			The tool name from C<< $req->{params}{name} >>. Present for tool calls.
54
55			=item $req->{args}
56
57			The tool argument hash reference from C<< $req->{params}{arguments} >>.
58			Present for tool calls. The tool callback also receives this same reference
59			as its second parameter, for convenience.
60
61			=item $req->{toolset}
62
63			The Toolset invoking the tool callback. Set by the Toolset when it dispatches
64			the call; absent for requests dispatched without a Toolset.
65
66			=item $req->{finished}
67
68			True after a reply or cancellation. Replying to a finished request is an
69			error. Notifications and progress after completion are ignored.
70
71			=item $req->{cancelled}
72
73			True if the request was cancelled. An asynchronous handler can check this
74			before attempting to reply.
75
76			=back
77
78			=head1 METHODS
79
80	root	1.4	=over
81
82			=item $grant = $req->require_permission ({ %request })
83	root	1.1
84			Synchronously checks a permission request using the server's C<permissions>
85			object. C<%request> has the fields described by
86	root	1.4	L<AnyEvent::MCP::Server::Permissions/check>. Returns the granted sandbox-grant
87	root	1.1	array reference; it can be reduced from the requested set.
88
89			A denial dies. A missing permission throws a special exception handled by
90			Server, which asks and retries the handler. Multiple checks are supported:
91			one-time grants belong to this tool invocation and survive permission retries.
92			They do not authorize later calls. Current rules are checked on every retry.
93
94			Complete all checks before side effects or asynchronous work starts.
95			The handler can run more than once. Do not catch the permission exception
96			as an ordinary tool error; let it reach Server's dispatch boundary.
97
98	root	1.4	=item $req->reply ($result)
99	root	1.1
100			Completes the request with the MCP result hash reference C<$result>. The
101			server adds the JSON-RPC envelope. Tools do not construct JSON-RPC errors.
102			Dies if the request has already finished.
103
104			Use this method for arbitrary MCP results, including structured errors,
105			large results and results requiring a particular content representation.
106
107	root	1.4	=item $req->error ($message)
108	root	1.1
109			Replies with C<isError> set to true and C<$message> as one text content item.
110			Use C<reply> for errors with structured content or other content types.
111
112	root	1.4	=item $req->result ($data)
113	root	1.1
114			Replies with the hash reference C<$data> as C<structuredContent>, and its
115			JSON encoding as one text content item for clients that consume only text.
116
117			This deliberately duplicates the data. Use C<reply> for large results or
118			when JSON text is unsuitable, including clients that encode text as JSON
119			again. Arrays and scalars must be wrapped in an object explicitly.
120
121	root	1.4	=item $req->notify ($method, $params)
122	root	1.1
123			Sends a notification associated with this request. C<$method> is the
124			notification method name and C<$params> its parameter hash reference.
125
126			A notification does not complete the request. Delivery is best effort:
127			notifications can be dropped if the transport does not implement delivery.
128			Calls after completion are ignored.
129
130	root	1.4	=item $req->progress ($progress, $total, $message)
131	root	1.1
132			Sends a progress notification if the client supplied a progress token in
133			C<< $req->{params}{_meta}{progressToken} >>. C<$progress> is the amount
134			completed; C<$total> and C<$message> can be omitted or undefined.
135
136			Uses C<notify>, with the same best-effort delivery. Calls after completion
137			are ignored.
138
139	root	1.4	=item $req->cancel ($reason)
140	root	1.1
141			Marks the request as cancelled and calls C<on_cancel>, allowing the handler
142			to stop work and release resources. C<$reason> is an optional explanation.
143
144			Cancellation does not send a reply.
145
146	root	1.4	=back
147
148	root	1.1	=head1 EVENTS
149
150			These callbacks are stored in the request hash like other MCP events.
151
152	root	1.4	=over
153
154			=item on_reply => $callback->($req, $result)
155	root	1.1
156			Called once when the request is completed with C<reply>. The server installs
157			C<$callback> to deliver the result.
158
159	root	1.4	=item on_notify => $callback->($req, $method, $params)
160	root	1.1
161			Called for each notification while the request is active. The server installs
162			C<$callback> to deliver notifications through the transport.
163
164	root	1.4	=item on_cancel => $callback->($req, $reason)
165	root	1.1
166			Called once when the request is cancelled. A handler can set C<$callback>
167			to cancel its asynchronous operation.
168
169	root	1.4	=back
170
171	root	1.1	=cut
172
173			package AnyEvent::MCP::Server::Request;
174
175			use common::sense;
176			use AnyEvent::MCP ();
177			use JSON::XS ();
178
179			our @ISA = qw(AnyEvent::MCP::Base);
180
181			sub require_permission {
182			my ($self, $request) = @_;
183
184			my $permissions = $self->{server}{permissions}
185			or die "Server has no permission configuration\n";
186
187			$permissions->require_permission ($self, $request)
188			}
189
190			sub reply {
191			my ($self, $result) = @_;
192
193			die "MCP request already finished\n"
194			if $self->{finished};
195
196			$self->{finished} = 1;
197
198			my $reply = delete $self->{on_reply};
199			delete @$self{qw(on_notify on_cancel _reply)};
200
201			$reply->($self, $result) if $reply
202			}
203
204			sub error {
205			my ($self, $message) = @_;
206
207			$self->reply ({
208			isError => JSON::XS::true,
209			content => [{ type => "text", text => $message }],
210			})
211			}
212
213			sub result {
214			my ($self, $data) = @_;
215
216	root	1.3	ref $data eq "HASH"
217			or die "MCP structured result must be an object\n";
218	root	1.1
219			$self->reply ({
220			structuredContent => $data,
221			content => [{ type => "text", text => JSON::XS->new->encode ($data) }],
222			})
223			}
224
225			sub notify {
226			my ($self, $method, $params) = @_;
227
228			return if $self->{finished};
229
230			$self->event (notify => $method, $params)
231			}
232
233			sub progress {
234			my ($self, $progress, $total, $message) = @_;
235
236			return unless $self->{on_notify} && !$self->{finished};
237
238			my $meta = $self->{params}{_meta}
239			or return;
240
241			return unless exists $meta->{progressToken};
242
243			my $params = {
244			progressToken => $meta->{progressToken},
245			progress => $progress,
246			};
247
248			$params->{total} = $total if defined $total;
249			$params->{message} = $message if defined $message;
250
251			$self->notify ("notifications/progress", $params)
252			}
253
254			sub cancel {
255			my ($self, $reason) = @_;
256
257			return if $self->{finished};
258			$self->{finished} = $self->{cancelled} = 1;
259
260			delete $self->{peer}{requests}{$self->{id}}
261			if $self->{peer};
262
263			my $cancel = delete $self->{on_cancel};
264			delete @$self{qw(on_reply on_notify _reply)};
265
266			$cancel->($self, $reason) if $cancel
267			}
268
269			1