MCP/Server.pm

filter: Statementstmt 100% 95 / 95 Branchbran 84.0% 42 / 50 Conditioncond 79.1% 19 / 24 MC/DCmcdc 66.6% 10 / 15 Subroutinesub 100% 31 / 31 Podpod 75.0% 3 / 4 totaltotal 91.3% 200 / 219 CC 37 SCAR 16.0
CC
37
Cov
92%
_tools_call
11.4
_prompts_get
9.1
register_provider
6.0
CRAP 4.9
« MCP.pm ↑ Summary MCP/Role/PromptProvider.pm »
1 package Catalyst::Plugin::MCP::Server;
2 6 ▶use v5.36;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 6 ▶use Moo;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 6 ▶use Scalar::Util qw/blessed/;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 6 ▶use namespace::clean;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 6 our $VERSION = '0.003';
8  
9 has protocol_versions => (
10 is => 'ro',
11 15 ▶ default => sub { ['2025-06-18'] },
Subroutine __ANON__: called CC=1 SCAR=0.0
12 6 );
13  
14 has server_info => (
15 is => 'ro',
16 16 ▶ default => sub { { name => 'mcp-server', version => __PACKAGE__->VERSION } },
Subroutine __ANON__: called CC=1 SCAR=0.0
17 6 );
18  
19 16 ▶has _providers => ( is => 'ro', default => sub { {} } );
Subroutine __ANON__: called CC=1 SCAR=0.0
20  
21 16 ▶sub BUILD ( $self, $args ) {
Subroutine BUILD: called CC=2 SCAR=6.9
Pod undocumented
22 die "protocol_versions must be a non-empty arrayref\n"
23 16 ▶ unless @{ $self->protocol_versions };
Branch: 1 branch
BranchTrueFalseTotal
unless @{$self->protocol_versions;} 1 15 16
24 }
25  
26 6 my %ROLE_FOR_KIND = (
27 resources => 'Catalyst::Plugin::MCP::Role::ResourceProvider',
28 prompts => 'Catalyst::Plugin::MCP::Role::PromptProvider',
29 tools => 'Catalyst::Plugin::MCP::Role::ToolProvider',
30 );
31  
32 27 ▶sub register_provider ( $self, $obj ) {
Subroutine register_provider: called CC=6 SCAR=17.9
Pod documented
33 27 ▶ die "MCP provider must be a blessed object\n" unless blessed $obj;
Branch: 1 branch
BranchTrueFalseTotal
unless builtin::blessed($obj) 1 26 27
34 26 my $matched = 0;
35 26 for my $kind ( sort keys %ROLE_FOR_KIND ) {
36 78 ▶ next unless $obj->DOES( $ROLE_FOR_KIND{$kind} );
Branch: 1 branch
BranchTrueFalseTotal
unless $obj->DOES($ROLE_FOR_KIND{$kind}) 53 25 78
37 die "MCP provider of kind '$kind' already registered\n"
38 25 ▶ if $self->_providers->{$kind};
Branch: 1 branch
BranchTrueFalseTotal
if $self->_providers->{$kind} 1 24 25
39 24 $self->_providers->{$kind} = $obj;
40 24 $matched++;
41 }
42 25 ▶ die "MCP provider consumes none of the provider roles\n" unless $matched;
Branch: 1 branch
BranchTrueFalseTotal
unless $matched 1 24 25
43 24 return $self;
44 }
45  
46 8 ▶sub capabilities ( $self ) {
Subroutine capabilities: called CC=2 SCAR=6.9
Pod documented
47 8 my %caps;
48 8 $caps{$_} = {} for keys %{ $self->_providers };
49 8 return \%caps;
50 }
51  
52 6 ▶sub _negotiate_version ( $self, $requested ) {
Subroutine _negotiate_version: called CC=3 SCAR=11.0
53 6 my @supported = @{ $self->protocol_versions };
54 6 ▶ if ( defined $requested ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $requested) 5 1 6
55 5 ▶ return $requested if grep { $_ eq $requested } @supported;
Branch: 1 branch
BranchTrueFalseTotal
if grep {$_ eq $requested;} @supported 4 1 5
56 }
57 2 return $supported[0];
58 }
59  
60 6 ▶sub _initialize ( $self, $params ) {
Subroutine _initialize: called CC=2 SCAR=7.2
61 6 ▶ my $requested = ref $params eq 'HASH' ? $params->{protocolVersion} : undef;
Branch: 1 branch
BranchTrueFalseTotal
ref $params eq 'HASH' ? : 6 0 6
62 return {
63 6 protocolVersion => $self->_negotiate_version($requested),
64 capabilities => $self->capabilities,
65 serverInfo => $self->server_info,
66 };
67 }
68  
69 13 ▶sub handlers ( $self ) {
Subroutine handlers: called CC=4 SCAR=13.9
Pod documented
70 my %h = (
71 6 ▶ 'initialize' => sub ($params) { $self->_initialize($params) },
Subroutine __ANON__: called CC=1 SCAR=0.0
72 1 ▶ 'ping' => sub ($params) { return {} },
Subroutine __ANON__: called CC=1 SCAR=0.0
73 1 ▶ 'notifications/initialized' => sub ($params) { return undef },
Subroutine __ANON__: called CC=1 SCAR=0.0
74 13 );
75  
76 13 ▶ if ( $self->_providers->{resources} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_providers->{"resources"}) 9 4 13
77 $h{'resources/list'} =
78 9 ▶ sub ($params) { $self->_resources_list($params) };
Subroutine __ANON__: called CC=1 SCAR=0.0
79 $h{'resources/templates/list'} =
80 9 ▶ sub ($params) { $self->_resources_templates($params) };
Subroutine __ANON__: called CC=1 SCAR=0.0
81 $h{'resources/read'} =
82 9 ▶ sub ($params) { $self->_resources_read($params) };
Subroutine __ANON__: called CC=1 SCAR=0.0
83 }
84 13 ▶ if ( $self->_providers->{prompts} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_providers->{"prompts"}) 1 12 13
85 1 ▶ $h{'prompts/list'} = sub ($params) { $self->_prompts_list($params) };
Subroutine __ANON__: called CC=1 SCAR=0.0
86 1 ▶ $h{'prompts/get'} = sub ($params) { $self->_prompts_get($params) };
Subroutine __ANON__: called CC=1 SCAR=0.0
87 }
88 13 ▶ if ( $self->_providers->{tools} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->_providers->{"tools"}) 13 0 13
89 13 ▶ $h{'tools/list'} = sub ($params) { $self->_tools_list($params) };
Subroutine __ANON__: called CC=1 SCAR=0.0
90 13 ▶ $h{'tools/call'} = sub ($params) { $self->_tools_call($params) };
Subroutine __ANON__: called CC=1 SCAR=0.0
91 }
92  
93 13 return \%h;
94 }
95  
96 3 ▶sub _cursor ( $self, $params ) {
Subroutine _cursor: called CC=2 SCAR=7.6
97 3 ▶ return ref $params eq 'HASH' ? $params->{cursor} : undef;
Branch: 1 branch
BranchTrueFalseTotal
ref $params eq 'HASH' ? : 3 0 3
98 }
99  
100 1 ▶sub _resources_list ( $self, $params ) {
Subroutine _resources_list: called CC=1 SCAR=0.0
101 1 return $self->_providers->{resources}->list( $self->_cursor($params) );
102 }
103  
104 1 ▶sub _resources_templates ( $self, $params ) {
Subroutine _resources_templates: called CC=1 SCAR=0.0
105 1 return $self->_providers->{resources}->templates;
106 }
107  
108 4 ▶sub _resources_read ( $self, $params ) {
Subroutine _resources_read: called CC=5 SCAR=16.2
109 4 ▶ my $uri = ref $params eq 'HASH' ? $params->{uri} : undef;
Branch: 1 branch
BranchTrueFalseTotal
ref $params eq 'HASH' ? : 4 0 4
110 4 ▶ die { code => -32602, message => 'Invalid params: uri is required' }
Branch: 1 branch
BranchTrueFalseTotal
unless defined $uri and length $uri 1 3 4
Condition66%2/3
defined $uri and length $uri
!ll&&!rl&&r
103
MC/DC50%1/2
defined $uri and length $uri
defined $uri length $uri
Truth table66%2/3
A and B
A= defined $uriB= length $uri
ABresult
0X0
100
111
111 unless defined $uri && length $uri;
112 3 my $out = $self->_providers->{resources}->read($uri);
113 3 ▶ die { code => -32002, message => 'Resource not found', data => { uri => $uri } }
Branch: 1 branch
BranchTrueFalseTotal
unless defined $out 2 1 3
114 unless defined $out;
115 1 return $out;
116 }
117  
118 1 ▶sub _prompts_list ( $self, $params ) {
Subroutine _prompts_list: called CC=1 SCAR=0.0
119 1 return $self->_providers->{prompts}->list( $self->_cursor($params) );
120 }
121  
122 5 ▶sub _prompts_get ( $self, $params ) {
Subroutine _prompts_get: called CC=9 SCAR=22.1
123 5 ▶ my $name = ref $params eq 'HASH' ? $params->{name} : undef;
Branch: 1 branch
BranchTrueFalseTotal
ref $params eq 'HASH' ? : 5 0 5
124 5 ▶ die { code => -32602, message => 'Invalid params: name is required' }
Branch: 1 branch
BranchTrueFalseTotal
unless defined $name and length $name 1 4 5
Condition66%2/3
defined $name and length $name
!ll&&!rl&&r
104
MC/DC50%1/2
defined $name and length $name
defined $name length $name
Truth table66%2/3
A and B
A= defined $nameB= length $name
ABresult
0X0
100
111
125 unless defined $name && length $name;
126 4 ▶ my $raw_args = ref $params eq 'HASH' ? $params->{arguments} : undef;
Branch: 1 branch
BranchTrueFalseTotal
ref $params eq 'HASH' ? : 4 0 4
127 4 ▶ die { code => -32602, message => 'Invalid params: arguments must be an object' }
Branch: 1 branch
BranchTrueFalseTotal
if defined $raw_args and ref $raw_args ne "HASH" 2 2 4
Condition100%3/3
defined $raw_args and ref $raw_args ne "HASH"
!ll&&!rl&&r
112
MC/DC100%2/2
defined $raw_args and ref $raw_args ne "HASH"
defined $raw_args ref $raw_args ne "HASH"
Truth table100%3/3
A and B
A= defined $raw_argsB= ref $raw_args ne "HASH"
ABresult
0X0
100
111
128 if defined $raw_args && ref $raw_args ne 'HASH';
129 2 ▶ my $args = $raw_args // {};
Condition100%2/2
$raw_args // {}
l!l
11
MC/DC100%1/1
$raw_args // {}
$raw_args
Truth table100%2/2
A
A= $raw_args
Aresult
11
00
130 2 my $out = $self->_providers->{prompts}->get( $name, $args );
131 2 ▶ die { code => -32602, message => 'Unknown prompt', data => { name => $name } }
Branch: 1 branch
BranchTrueFalseTotal
unless defined $out 1 1 2
132 unless defined $out;
133 1 return $out;
134 }
135  
136 1 ▶sub _tools_list ( $self, $params ) {
Subroutine _tools_list: called CC=1 SCAR=0.0
137 1 return $self->_providers->{tools}->list( $self->_cursor($params) );
138 }
139  
140 10 ▶sub _tools_call ( $self, $params ) {
Subroutine _tools_call: called CC=11 SCAR=24.3
141 10 ▶ my $name = ref $params eq 'HASH' ? $params->{name} : undef;
Branch: 1 branch
BranchTrueFalseTotal
ref $params eq 'HASH' ? : 10 0 10
142 10 ▶ die { code => -32602, message => 'Invalid params: name is required' }
Branch: 1 branch
BranchTrueFalseTotal
unless defined $name and length $name 1 9 10
Condition66%2/3
defined $name and length $name
!ll&&!rl&&r
109
MC/DC50%1/2
defined $name and length $name
defined $name length $name
Truth table66%2/3
A and B
A= defined $nameB= length $name
ABresult
0X0
100
111
143 unless defined $name && length $name;
144 9 ▶ my $raw_args = ref $params eq 'HASH' ? $params->{arguments} : undef;
Branch: 1 branch
BranchTrueFalseTotal
ref $params eq 'HASH' ? : 9 0 9
145 9 ▶ die { code => -32602, message => 'Invalid params: arguments must be an object' }
Branch: 1 branch
BranchTrueFalseTotal
if defined $raw_args and ref $raw_args ne "HASH" 2 7 9
Condition100%3/3
defined $raw_args and ref $raw_args ne "HASH"
!ll&&!rl&&r
342
MC/DC100%2/2
defined $raw_args and ref $raw_args ne "HASH"
defined $raw_args ref $raw_args ne "HASH"
Truth table100%3/3
A and B
A= defined $raw_argsB= ref $raw_args ne "HASH"
ABresult
0X0
100
111
146 if defined $raw_args && ref $raw_args ne 'HASH';
147 7 ▶ my $args = $raw_args // {};
Condition100%2/2
$raw_args // {}
l!l
43
MC/DC100%1/1
$raw_args // {}
$raw_args
Truth table100%2/2
A
A= $raw_args
Aresult
11
00
148  
149 # Protocol error if the tool is not advertised. The unpaginated list must
150 # enumerate every tool (see the ToolProvider POD).
151 7 my $list = $self->_providers->{tools}->list(undef);
152 7 ▶ my @names = map { $_->{name} } @{ $list->{tools} // [] };
Condition50%1/2
$list->{"tools"} // []
l!l
70
MC/DC0%0/1
$list->{"tools"} // []
$list->{"tools"}
Truth table50%1/2
A
A= $list->{"tools"}
Aresult
11
00
153 die { code => -32602, message => 'Unknown tool', data => { name => $name } }
154 7 ▶ unless grep { defined $_ && $_ eq $name } @names;
Branch: 1 branch
BranchTrueFalseTotal
unless grep {defined $_ and $_ eq $name;} @names 2 5 7
Condition66%2/3
defined $_ && $_ eq $name
!ll&&!rl&&r
025
MC/DC50%1/2
defined $_ && $_ eq $name
defined $_ $_ eq $name
Truth table66%2/3
A && B
A= defined $_B= $_ eq $name
ABresult
0X0
100
111
155  
156 # Execution failures are normal results carrying isError, not exceptions.
157 5 return $self->_providers->{tools}->call( $name, $args );
158 }
159  
160 =head1 NAME
161  
162 Catalyst::Plugin::MCP::Server - Model Context Protocol engine
163  
164 =head1 SYNOPSIS
165  
166 my $engine = Catalyst::Plugin::MCP::Server->new(
167 server_info => { name => 'myapp', version => '1.0' },
168 );
169 $engine->register_provider( $tools );
170 my $handlers = $engine->handlers; # verb name => sub ($params)
171  
172 =head1 DESCRIPTION
173  
174 The protocol engine behind L<Catalyst::Plugin::MCP>: it owns the MCP (revision
175 2025-06-18) lifecycle, capability advertisement, and verb routing, and knows
176 nothing about your domain: you supply providers.
177  
178 It also knows nothing about Catalyst or HTTP. The engine maps verb names to
179 plain coderefs; binding those to a transport is the caller's job.
180 L<Catalyst::Plugin::MCP> is that binding, and constructs a fresh engine per
181 request so no state leaks between requests.
182  
183 =head1 METHODS
184  
185 =head2 new( %args )
186  
187 =over
188  
189 =item protocol_versions
190  
191 Arrayref of supported MCP revisions, newest-first; defaults to
192 C<['2025-06-18']>. The first entry is the preferred version, returned when a
193 client asks for one that is not supported. Dies if empty.
194  
195 =item server_info
196  
197 Hashref advertised as C<serverInfo> at C<initialize>; defaults to
198 C<< { name => 'mcp-server', version => $VERSION } >>. Applications should set
199 their own name and version.
200  
201 =back
202  
203 =head2 register_provider( $obj )
204  
205 Register a blessed object consuming one or more of the provider roles
206 (L<Catalyst::Plugin::MCP::Role::ResourceProvider>,
207 L<Catalyst::Plugin::MCP::Role::PromptProvider>,
208 L<Catalyst::Plugin::MCP::Role::ToolProvider>). An object consuming several
209 roles is registered once per kind. Returns the engine, so calls chain.
210  
211 Dies if C<$obj> is not blessed, consumes none of the roles, or is of a kind
212 already registered: one provider per kind.
213  
214 =head2 capabilities
215  
216 Return the C<capabilities> hashref for C<initialize>: a key per registered
217 provider kind. Kinds with no registered provider are not advertised, and their
218 verbs are not routed.
219  
220 =head2 handlers
221  
222 Return a hashref of MCP verb name to C<< sub ($params) >>. C<initialize>,
223 C<ping>, and C<notifications/initialized> are always present; the resource,
224 prompt, and tool verbs appear only for registered kinds.
225  
226 A handler returns its result, or C<undef> for a notification (nothing to send
227 back). To signal a JSON-RPC error it dies with a hashref of C<code>, C<message>,
228 and optional C<data>, using C<-32602> for bad params and unknown tool or prompt
229 names, C<-32002> for a resource that does not exist. Note that a tool that runs
230 and B<fails> is not an error here: that is a normal result carrying
231 C<< isError => 1 >>, per L<Catalyst::Plugin::MCP::Role::ToolProvider>.
232  
233 =head1 AUTHOR
234  
235 Mike Whitaker <mike@altrion.org>
236  
237 =head1 LICENSE
238  
239 This library is free software; you can redistribute it and/or modify it
240 under the terms of the Artistic License, as distributed with Perl.
241  
242 =cut
243  
244 6 1;
« MCP.pm ↑ Summary MCP/Role/PromptProvider.pm »