MCP/Server/Toolset.pm

=head1 NAME

AnyEvent::MCP::Server::Toolset - MCP tool declarations and callbacks

=head1 DESCRIPTION

A Toolset answers two questions: which tools exist, and what code should run
when one is called? It holds tool declarations and their callbacks, but no
transport or client state. You can therefore give the same Toolset to
several servers without copying or re-registering the tools.

If your program only needs one standalone server, the function interface in
L<AnyEvent::MCP::Server::Simple> manages a default Toolset for you.

=head1 EXAMPLE

   use AnyEvent::MCP::Server::Toolset;
   use AnyEvent::MCP::Server::HTTP;

   my $tools = AnyEvent::MCP::Server::Toolset->new;
   $tools->tool (echo => "Echo the supplied text",
      {
         type => "object", required => ["text"],
         properties => { text => { type => "string" } },
      },
      sub {
         my ($req, $args) = @_;
         $req->result ({ text => $args->{text} });
      },
   );

   my $server = AnyEvent::MCP::Server::HTTP->new (
      toolsets => [$tools], tokens => [$secret],
   );

Here C<$secret> is an application-provided HTTP token. The server still
needs C<< $server->listen >> and an event loop; see
L<AnyEvent::MCP::Server::HTTP>. The Toolset does not create connections.
For a complete standalone script, use
L<AnyEvent::MCP::Server::Simple/TUTORIAL> instead.

=head1 REQUEST AND TOOL WORKFLOW

Register tools with C<tool>, then pass the Toolset to a server through its
C<toolsets> option. The server handles the protocol and transport; the Toolset
supplies declarations for C<tools/list> and callbacks for C<tools/call>.

For a tool call, the server creates an L<AnyEvent::MCP::Server::Request>,
sets C<< $req->{tool} >> and C<< $req->{args} >>, and calls its C<on_request>
hook. It then finds the first Toolset containing that tool and invokes its
callback as C<$callback->($req, $args)>. C<$args> is the same hash reference
as C<< $req->{args} >>; C<< $req->{toolset} >> identifies the invoking Toolset.

The input schema describes the arguments to the client; the server does not
validate arguments against it. The handler must validate the arguments it
uses and complete the request with one reply.

=head2 Permission checks and retries

Configure the server's C<permissions> option with an
L<AnyEvent::MCP::Server::Permissions> object. The handler can check several
paths or operations in sequence:

   sub {
      my ($req, $args) = @_;

      my $source_grant = $req->require_permission ({
         tool => $req->{tool},
         dimensions => { subject => {
            label => "Source file", value => $args->{source},
            choices => [{ label => "source file", match => $args->{source} }],
         } },
         action => "read", sandbox_grants => ["workdir-read"],
         reason => "read the source file",
      });

      my $destination_grant = $req->require_permission ({
         tool => $req->{tool},
         dimensions => { subject => {
            label => "Destination file", value => $args->{destination},
            choices => [{ label => "destination file", match => $args->{destination} }],
         } },
         action => "write", sandbox_grants => ["workdir-write"],
         reason => "write the destination file",
      });

      ... # read using $source_grant, write using $destination_grant
      $req->result ({ ... });
   }

This example assumes both paths are inside the selected workdir and that
the application enforces the returned grants. C<action> chooses the kind
of operation to authorize; C<sandbox_grants> chooses the worker's authority.
Grant names and their implications belong to the application.
C<require_permission> returns the granted sandbox-grant array reference,
which may be smaller than the requested set. Execute using those grants
rather than assuming that everything requested was allowed.

Grants are separate; Server does not combine them. When reading the source
and writing the destination separately, use each grant for its corresponding
operation.

Combining authority is needed when one operation spans several subjects,
such as renaming a file. Request the required action and sandbox grants for
every affected path: a rename needs write authority for both source and
destination, unlike the read/write example above. Check that every grant
still permits the operation after any reductions. For an application using
C<workdir-write> for a rename within one workdir, after requesting that grant
for both paths:

   my $permissions = $req->{server}{permissions};
   my $source = $permissions->closure ($source_grant);
   my $destination = $permissions->closure ($destination_grant);

   $source->{"workdir-write"} && $destination->{"workdir-write"}
      or die "Rename needs write permission for both paths\n";

C<closure> includes implied sandbox grants. If the operation needs one
combined grant set, use the intersection of these closures, rather than their
union: authority granted for one path must not authorize the other.
Do this before starting the operation.

A denial dies and becomes a tool error. The first missing permission throws
a special exception: Server catches it and asks. Modern MCP asking replies
with C<input_required>; the client supplies the answer in a repeated call.
Local asking, including the legacy fallback, retries the handler internally.
An explicit local asking configuration also applies to modern callers.

The handler starts again from the beginning, including the server's
C<on_request> hook. Earlier one-time grants survive these retries but do not
authorize another tool invocation. Current rules are rechecked, so a new
denial can supersede an earlier approval.

Complete all checks before side effects or asynchronous work. Do not catch
the permission-needed exception as an ordinary tool failure; it must reach
the server's synchronous dispatch boundary. A deferred callback cannot use
that boundary to restart the handler.

=head2 Replies and failures

=over

=item $req->reply ($result)

Sends the MCP result hash reference as supplied. Use this for arbitrary
content, structured errors or large results. The server adds the JSON-RPC
envelope.

=item $req->result ($data)

Sends the hash reference C<$data> as C<structuredContent> and also as JSON in
one text content item. This duplicates the data for clients that consume
only text; use C<reply> when that representation is unsuitable.

=item $req->error ($message)

Sends a tool result with C<isError> set and C<$message> as one text item.

=back

A synchronous handler exception becomes a tool error. Tool failures do not
become JSON-RPC errors; malformed protocol requests and unknown tools are
handled by Server.

Reply exactly once. Replying after completion is a bug and dies. A reply
finishes the request, but returning from the callback does not.

=head2 Asynchronous work and cancellation

The callback may keep C<$req> and return without replying. Reply when the
operation completes. The callback runs in the event loop; use asynchronous
operations rather than blocking it.

Set C<< $req->{on_cancel} >> to stop an outstanding operation. Cancellation
sets C<< $req->{cancelled} >> and C<< $req->{finished} >> and sends no reply.
A late completion callback must check C<< $req->{finished} >> before replying.

Server catches exceptions during synchronous dispatch, not exceptions in
later application callbacks. Such callbacks must handle their own failures.

C<< $req->progress ($progress, $total, $message) >> reports progress when
the client supplied a progress token. Delivery is best effort and may be
dropped by the transport; it does not complete the request.

=head1 METHODS

=over

=item $toolset = AnyEvent::MCP::Server::Toolset->new

Creates an empty tool registry.

=item $toolset->tool ($name, $description, $input_schema, $callback->($req, $args))

Registers a tool named C<$name>. Underscores are converted to hyphens and
duplicate names are rejected.

C<$description> is stripped of surrounding whitespace and common indentation.
C<$input_schema> is a JSON Schema hash reference describing the arguments.

C<$callback> receives an L<AnyEvent::MCP::Server::Request> object C<$req>
and its C<< $req->{args} >> hash reference as C<$args>, for convenience:

   sub {
      my ($req, $args) = @_;

      $req->reply ({
         content => [{ type => "text", text => $args->{text} }],
      });
   }

Registered tools are callbacks, not methods of the Toolset.

=item $definitions = $toolset->list

Returns the array reference of MCP tool definitions in registration order.
C<$definitions> contains no callbacks.

=item $toolset->call ($req)

Invokes the tool named by C<< $req->{tool} >> with C<$req> and
C<< $req->{args} >>. Sets C<< $req->{toolset} >> to this Toolset.

Unknown names and exceptions from the callback are left for the server to
handle.

=back

=cut

package AnyEvent::MCP::Server::Toolset;

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

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

sub new {
   my $class = shift;

   $class->SUPER::new (tool => {}, list => [], @_)
}

sub tool {
   my ($self, $name, $description, $input_schema, $callback) = @_;

   $name =~ y/_/-/;

   !exists $self->{tool}{$name}
      or die "duplicate MCP tool '$name'\n";

   my $definition = {
      name        => $name,
      description => AnyEvent::MCP::_clean_text $description,
      inputSchema => $input_schema,
   };

   $self->{tool}{$name} = {
      definition => $definition,
      callback   => $callback,
   };

   push @{$self->{list}}, $definition;
}

sub list {
   $_[0]{list}
}

sub call {
   my ($self, $req) = @_;

   my $name = $req->{tool};

   my $tool = $self->{tool}{$name}
      or die "unknown MCP tool '$name'\n";

   $req->{toolset} = $self;
   $tool->{callback}->($req, $req->{args})
}

1
Revision:	1.6
Committed:	Wed Oct 28 10:39:53 2026 UTC (12 days, 23 hours ago) by root
Branch:	MAIN
CVS Tags:	rel-0_81, rel-0_82, rel-0_71, rel-0_7, rel-0_8, HEAD
Changes since 1.5:	+10 -4 lines
Log Message:	* empty log message *
#	Content
1	=head1 NAME
2
3	AnyEvent::MCP::Server::Toolset - MCP tool declarations and callbacks
4
5	=head1 DESCRIPTION
6
7	A Toolset answers two questions: which tools exist, and what code should run
8	when one is called? It holds tool declarations and their callbacks, but no
9	transport or client state. You can therefore give the same Toolset to
10	several servers without copying or re-registering the tools.
11
12	If your program only needs one standalone server, the function interface in
13	L<AnyEvent::MCP::Server::Simple> manages a default Toolset for you.
14
15	=head1 EXAMPLE
16
17	use AnyEvent::MCP::Server::Toolset;
18	use AnyEvent::MCP::Server::HTTP;
19
20	my $tools = AnyEvent::MCP::Server::Toolset->new;
21	$tools->tool (echo => "Echo the supplied text",
22	{
23	type => "object", required => ["text"],
24	properties => { text => { type => "string" } },
25	},
26	sub {
27	my ($req, $args) = @_;
28	$req->result ({ text => $args->{text} });
29	},
30	);
31
32	my $server = AnyEvent::MCP::Server::HTTP->new (
33	toolsets => [$tools], tokens => [$secret],
34	);
35
36	Here C<$secret> is an application-provided HTTP token. The server still
37	needs C<< $server->listen >> and an event loop; see
38	L<AnyEvent::MCP::Server::HTTP>. The Toolset does not create connections.
39	For a complete standalone script, use
40	L<AnyEvent::MCP::Server::Simple/TUTORIAL> instead.
41
42	=head1 REQUEST AND TOOL WORKFLOW
43
44	Register tools with C<tool>, then pass the Toolset to a server through its
45	C<toolsets> option. The server handles the protocol and transport; the Toolset
46	supplies declarations for C<tools/list> and callbacks for C<tools/call>.
47
48	For a tool call, the server creates an L<AnyEvent::MCP::Server::Request>,
49	sets C<< $req->{tool} >> and C<< $req->{args} >>, and calls its C<on_request>
50	hook. It then finds the first Toolset containing that tool and invokes its
51	callback as C<$callback->($req, $args)>. C<$args> is the same hash reference
52	as C<< $req->{args} >>; C<< $req->{toolset} >> identifies the invoking Toolset.
53
54	The input schema describes the arguments to the client; the server does not
55	validate arguments against it. The handler must validate the arguments it
56	uses and complete the request with one reply.
57
58	=head2 Permission checks and retries
59
60	Configure the server's C<permissions> option with an
61	L<AnyEvent::MCP::Server::Permissions> object. The handler can check several
62	paths or operations in sequence:
63
64	sub {
65	my ($req, $args) = @_;
66
67	my $source_grant = $req->require_permission ({
68	tool => $req->{tool},
69	dimensions => { subject => {
70	label => "Source file", value => $args->{source},
71	choices => [{ label => "source file", match => $args->{source} }],
72	} },
73	action => "read", sandbox_grants => ["workdir-read"],
74	reason => "read the source file",
75	});
76
77	my $destination_grant = $req->require_permission ({
78	tool => $req->{tool},
79	dimensions => { subject => {
80	label => "Destination file", value => $args->{destination},
81	choices => [{ label => "destination file", match => $args->{destination} }],
82	} },
83	action => "write", sandbox_grants => ["workdir-write"],
84	reason => "write the destination file",
85	});
86
87	... # read using $source_grant, write using $destination_grant
88	$req->result ({ ... });
89	}
90
91	This example assumes both paths are inside the selected workdir and that
92	the application enforces the returned grants. C<action> chooses the kind
93	of operation to authorize; C<sandbox_grants> chooses the worker's authority.
94	Grant names and their implications belong to the application.
95	C<require_permission> returns the granted sandbox-grant array reference,
96	which may be smaller than the requested set. Execute using those grants
97	rather than assuming that everything requested was allowed.
98
99	Grants are separate; Server does not combine them. When reading the source
100	and writing the destination separately, use each grant for its corresponding
101	operation.
102
103	Combining authority is needed when one operation spans several subjects,
104	such as renaming a file. Request the required action and sandbox grants for
105	every affected path: a rename needs write authority for both source and
106	destination, unlike the read/write example above. Check that every grant
107	still permits the operation after any reductions. For an application using
108	C<workdir-write> for a rename within one workdir, after requesting that grant
109	for both paths:
110
111	my $permissions = $req->{server}{permissions};
112	my $source = $permissions->closure ($source_grant);
113	my $destination = $permissions->closure ($destination_grant);
114
115	$source->{"workdir-write"} && $destination->{"workdir-write"}
116	or die "Rename needs write permission for both paths\n";
117
118	C<closure> includes implied sandbox grants. If the operation needs one
119	combined grant set, use the intersection of these closures, rather than their
120	union: authority granted for one path must not authorize the other.
121	Do this before starting the operation.
122
123	A denial dies and becomes a tool error. The first missing permission throws
124	a special exception: Server catches it and asks. Modern MCP asking replies
125	with C<input_required>; the client supplies the answer in a repeated call.
126	Local asking, including the legacy fallback, retries the handler internally.
127	An explicit local asking configuration also applies to modern callers.
128
129	The handler starts again from the beginning, including the server's
130	C<on_request> hook. Earlier one-time grants survive these retries but do not
131	authorize another tool invocation. Current rules are rechecked, so a new
132	denial can supersede an earlier approval.
133
134	Complete all checks before side effects or asynchronous work. Do not catch
135	the permission-needed exception as an ordinary tool failure; it must reach
136	the server's synchronous dispatch boundary. A deferred callback cannot use
137	that boundary to restart the handler.
138
139	=head2 Replies and failures
140
141	=over
142
143	=item $req->reply ($result)
144
145	Sends the MCP result hash reference as supplied. Use this for arbitrary
146	content, structured errors or large results. The server adds the JSON-RPC
147	envelope.
148
149	=item $req->result ($data)
150
151	Sends the hash reference C<$data> as C<structuredContent> and also as JSON in
152	one text content item. This duplicates the data for clients that consume
153	only text; use C<reply> when that representation is unsuitable.
154
155	=item $req->error ($message)
156
157	Sends a tool result with C<isError> set and C<$message> as one text item.
158
159	=back
160
161	A synchronous handler exception becomes a tool error. Tool failures do not
162	become JSON-RPC errors; malformed protocol requests and unknown tools are
163	handled by Server.
164
165	Reply exactly once. Replying after completion is a bug and dies. A reply
166	finishes the request, but returning from the callback does not.
167
168	=head2 Asynchronous work and cancellation
169
170	The callback may keep C<$req> and return without replying. Reply when the
171	operation completes. The callback runs in the event loop; use asynchronous
172	operations rather than blocking it.
173
174	Set C<< $req->{on_cancel} >> to stop an outstanding operation. Cancellation
175	sets C<< $req->{cancelled} >> and C<< $req->{finished} >> and sends no reply.
176	A late completion callback must check C<< $req->{finished} >> before replying.
177
178	Server catches exceptions during synchronous dispatch, not exceptions in
179	later application callbacks. Such callbacks must handle their own failures.
180
181	C<< $req->progress ($progress, $total, $message) >> reports progress when
182	the client supplied a progress token. Delivery is best effort and may be
183	dropped by the transport; it does not complete the request.
184
185	=head1 METHODS
186
187	=over
188
189	=item $toolset = AnyEvent::MCP::Server::Toolset->new
190
191	Creates an empty tool registry.
192
193	=item $toolset->tool ($name, $description, $input_schema, $callback->($req, $args))
194
195	Registers a tool named C<$name>. Underscores are converted to hyphens and
196	duplicate names are rejected.
197
198	C<$description> is stripped of surrounding whitespace and common indentation.
199	C<$input_schema> is a JSON Schema hash reference describing the arguments.
200
201	C<$callback> receives an L<AnyEvent::MCP::Server::Request> object C<$req>
202	and its C<< $req->{args} >> hash reference as C<$args>, for convenience:
203
204	sub {
205	my ($req, $args) = @_;
206
207	$req->reply ({
208	content => [{ type => "text", text => $args->{text} }],
209	});
210	}
211
212	Registered tools are callbacks, not methods of the Toolset.
213
214	=item $definitions = $toolset->list
215
216	Returns the array reference of MCP tool definitions in registration order.
217	C<$definitions> contains no callbacks.
218
219	=item $toolset->call ($req)
220
221	Invokes the tool named by C<< $req->{tool} >> with C<$req> and
222	C<< $req->{args} >>. Sets C<< $req->{toolset} >> to this Toolset.
223
224	Unknown names and exceptions from the callback are left for the server to
225	handle.
226
227	=back
228
229	=cut
230
231	package AnyEvent::MCP::Server::Toolset;
232
233	use common::sense;
234	use AnyEvent::MCP ();
235
236	our @ISA = qw(AnyEvent::MCP::Base);
237
238	sub new {
239	my $class = shift;
240
241	$class->SUPER::new (tool => {}, list => [], @_)
242	}
243
244	sub tool {
245	my ($self, $name, $description, $input_schema, $callback) = @_;
246
247	$name =~ y/_/-/;
248
249	!exists $self->{tool}{$name}
250	or die "duplicate MCP tool '$name'\n";
251
252	my $definition = {
253	name => $name,
254	description => AnyEvent::MCP::_clean_text $description,
255	inputSchema => $input_schema,
256	};
257
258	$self->{tool}{$name} = {
259	definition => $definition,
260	callback => $callback,
261	};
262
263	push @{$self->{list}}, $definition;
264	}
265
266	sub list {
267	$_[0]{list}
268	}
269
270	sub call {
271	my ($self, $req) = @_;
272
273	my $name = $req->{tool};
274
275	my $tool = $self->{tool}{$name}
276	or die "unknown MCP tool '$name'\n";
277
278	$req->{toolset} = $self;
279	$tool->{callback}->($req, $req->{args})
280	}
281
282	1