MCP.pm

filter: Statementstmt 100% 26 / 26 Branchbran 50.0% 2 / 4 Conditioncond 66.6% 4 / 6 MC/DCmcdc 33.3% 1 / 3 Subroutinesub 100% 5 / 5 Podpod 100% 2 / 2 totaltotal 86.9% 40 / 46 CC 9 SCAR 17.5
CC
9
Cov
89%
mcp_dispatch
8.5
mcp_register_provider
2.0
BEGIN
1.0
CRAP 5.8
↑ Summary MCP/Server.pm »
1 package Catalyst::Plugin::MCP;
2 4 ▶use v5.36;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 4 ▶use Catalyst::Plugin::MCP::Server;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 4 ▶use Catalyst::Plugin::JSONRPC::Server::Dispatcher;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 4 our $VERSION = '0.003';
7  
8 4 my $PROVIDER_SLOT = 'Catalyst::Plugin::MCP/providers';
9  
10 18 ▶sub mcp_register_provider ( $c, $obj ) {
Subroutine mcp_register_provider: called CC=2 SCAR=6.9
Pod documented
11 18 ▶ my $list = $c->stash->{$PROVIDER_SLOT} //= [];
Condition100%2/2
$c->stash->{$PROVIDER_SLOT} //= []
l!l
711
MC/DC100%1/1
$c->stash->{$PROVIDER_SLOT} //= []
$c->stash->{$PROVIDER_SLOT}
Truth table100%2/2
A
A= $c->stash->{$PROVIDER_SLOT}
Aresult
11
00
12 18 push @$list, $obj;
13 18 return $c;
14 }
15  
16 11 ▶sub mcp_dispatch ( $c, $body = undef ) {
Subroutine mcp_dispatch: called CC=8 SCAR=21.4
Pod documented
17 11 ▶ my $providers = $c->stash->{$PROVIDER_SLOT} // [];
Condition50%1/2
$c->stash->{$PROVIDER_SLOT} // []
l!l
110
MC/DC0%0/1
$c->stash->{$PROVIDER_SLOT} // []
$c->stash->{$PROVIDER_SLOT}
Truth table50%1/2
A
A= $c->stash->{$PROVIDER_SLOT}
Aresult
11
00
18 11 ▶ my $cfg = $c->config->{'Catalyst::Plugin::MCP'} // {};
Condition50%1/2
$c->config->{"Catalyst::Plugin::MCP"} // {}
l!l
011
MC/DC0%0/1
$c->config->{"Catalyst::Plugin::MCP"} // {}
$c->config->{"Catalyst::Plugin::MCP"}
Truth table50%1/2
A
A= $c->config->{"Catalyst::Plugin::MCP"}
Aresult
11
00
19  
20 11 my %args;
21 $args{protocol_versions} = $cfg->{protocol_versions}
22 11 ▶ if $cfg->{protocol_versions};
Branch: 1 branch
BranchTrueFalseTotal
if $cfg->{"protocol_versions"} 0 11 11
23 11 ▶ $args{server_info} = $cfg->{server_info} if $cfg->{server_info};
Branch: 1 branch
BranchTrueFalseTotal
if $cfg->{"server_info"} 0 11 11
24  
25 11 my $engine = Catalyst::Plugin::MCP::Server->new(%args);
26 11 $engine->register_provider($_) for @$providers;
27  
28 11 my $handlers = $engine->handlers;
29  
30 # Build a fresh per-request dispatcher so each request's verb set is
31 # isolated: no stale verbs from prior requests leak across, and there
32 # are no cross-thread races on the shared per-application dispatcher.
33 11 my $dispatcher = Catalyst::Plugin::JSONRPC::Server::Dispatcher->new;
34 11 $dispatcher->register( $_ => $handlers->{$_} ) for keys %$handlers;
35  
36 # MCP's Streamable HTTP transport requires HTTP 202 Accepted (not the
37 # generic JSON-RPC 204) for a POST that carries only responses/notifications,
38 # i.e. when the dispatcher has nothing to send back.
39 11 return $c->jsonrpc_dispatch_with( $dispatcher, $body, 202 );
40 }
41  
42 =head1 NAME
43  
44 Catalyst::Plugin::MCP - Model Context Protocol server plugin for Catalyst
45  
46 =head1 SYNOPSIS
47  
48 package MyApp;
49 use Catalyst qw/
50 +Catalyst::Plugin::JSONRPC::Server
51 +Catalyst::Plugin::MCP
52 /;
53 __PACKAGE__->setup;
54  
55 # in a controller action mounted at your MCP endpoint
56 sub mcp :Path('/mcp') :Args(0) {
57 my ( $self, $c ) = @_;
58 $c->mcp_register_provider( $c->model('MCP::Resources') );
59 $c->mcp_register_provider( $c->model('MCP::Tools') );
60 $c->mcp_dispatch;
61 }
62  
63 =head1 REQUIRED PLUGINS
64  
65 This plugin builds on L<Catalyst::Plugin::JSONRPC::Server> and calls its
66 C<jsonrpc_dispatch_with> method. The consuming application B<must> load
67 C<Catalyst::Plugin::JSONRPC::Server> in its plugin list, B<before>
68 C<Catalyst::Plugin::MCP> (as in the SYNOPSIS). Declaring the distribution as a
69 prerequisite installs it but does not load it into the application class: a
70 Catalyst plugin is only mixed into C<$c> when listed in C<use Catalyst
71 qw/+.../>. Omitting it yields a runtime C<< Can't locate object method
72 "jsonrpc_dispatch_with" >> at the first MCP request.
73  
74 =head1 DESCRIPTION
75  
76 Adds a Model Context Protocol (revision 2025-06-18) server to a Catalyst
77 application, layered on L<Catalyst::Plugin::JSONRPC::Server>. The protocol
78 engine lives in L<Catalyst::Plugin::MCP::Server>; this module is the thin
79 Catalyst seam.
80  
81 Each call to C<mcp_dispatch> builds a fresh
82 L<Catalyst::Plugin::JSONRPC::Server::Dispatcher> containing only the handlers
83 registered by the providers in the current request's stash. The shared
84 per-application dispatcher provided by C<Catalyst::Plugin::JSONRPC::Server>
85 is never written to by this plugin, so there is no cross-request verb leakage
86 and no concurrency hazard between simultaneous requests.
87  
88 =head1 METHODS
89  
90 =head2 mcp_register_provider( $obj )
91  
92 Add a provider object to the current request's provider set. C<$obj> must be
93 blessed and must consume at least one of the provider roles
94 (L<Catalyst::Plugin::MCP::Role::ResourceProvider>,
95 L<Catalyst::Plugin::MCP::Role::PromptProvider>,
96 L<Catalyst::Plugin::MCP::Role::ToolProvider>); one provider per kind. Returns
97 C<$c>, so calls chain.
98  
99 Providers are validated when C<mcp_dispatch> builds the engine, not here, so a
100 bad provider dies at dispatch. Registration is per-request (it lives in the
101 stash), so each request must register its own providers.
102  
103 =head2 mcp_dispatch( $body )
104  
105 Run the MCP request: build an engine from the registered providers and config,
106 route the verb, and write the response. Call it last in the action.
107  
108 C<$body> is optional. Omit it and the request body is read and size-checked for
109 you, which is what you want. Pass a raw (still-encoded) JSON string only if you
110 have already consumed the body yourself. A supplied C<$body> bypasses
111 L<Catalyst::Plugin::JSONRPC::Server>'s oversize check, which makes the size
112 limit your problem.
113  
114 A POST carrying only notifications or responses has no reply to send, and gets
115 HTTP 202 with an empty body as the Streamable HTTP transport requires.
116  
117 =head1 CONFIGURATION
118  
119 Under the C<Catalyst::Plugin::MCP> key; both are optional and are passed to
120 L<Catalyst::Plugin::MCP::Server/new>:
121  
122 __PACKAGE__->config(
123 'Catalyst::Plugin::MCP' => {
124 protocol_versions => ['2025-06-18'],
125 server_info => { name => 'myapp', version => '1.0' },
126 },
127 );
128  
129 =over
130  
131 =item protocol_versions
132  
133 Supported MCP revisions, newest-first. The first is preferred, and is what a
134 client gets when it asks for a version you do not support.
135  
136 =item server_info
137  
138 Advertised at C<initialize>. Defaults to a generic name and this plugin's
139 version, so set it to your own.
140  
141 =back
142  
143 =head1 SECURITY
144  
145 B<This plugin ships no authentication and no C<Origin> validation, and
146 C<mcp_dispatch> does not add any.> A C<tools/call> runs your provider's code,
147 so an endpoint mounted as in the SYNOPSIS executes tools for anyone who can
148 POST to it. Guarding it is the application's job, and both of these are on you:
149  
150 =over
151  
152 =item Authenticate the endpoint
153  
154 The MCP Streamable HTTP transport says servers SHOULD authenticate connections.
155 Put your own authentication (a Catalyst authentication plugin, an C<auto>
156 action, or middleware) in front of C<mcp_dispatch>, and let the request reach it
157 only once it is authorised. Consider also what a provider is allowed to reach:
158 the engine does not scope tools or resources to a user.
159  
160 =item Validate the C<Origin> header
161  
162 The transport says servers MUST validate C<Origin> on incoming connections, to
163 stop a browser on another site from driving your endpoint via DNS rebinding.
164 Check it against an allow-list and reject anything else before dispatching.
165  
166 =back
167  
168 Binding to localhost rather than C<0.0.0.0> is worth it for a local server, but
169 it is not a substitute for either of the above.
170  
171 =head1 EXAMPLES
172  
173 A runnable example lives in F<examples/>: a small Catalyst app loading
174 C<Catalyst::Plugin::JSONRPC::Server> then C<Catalyst::Plugin::MCP>, mounting
175 an C<echo> tool and a static resource at C</mcp>, plus a core-Perl client that
176 replays the C<initialize> / C<tools/list> / C<tools/call> / C<resources/read>
177 handshake. Start it with C<plackup examples/app.psgi> and run C<perl
178 examples/client.pl>. See F<examples/README.md>.
179  
180 =head1 AUTHOR
181  
182 Mike Whitaker <mike@altrion.org>
183  
184 Built with tool assistance from Claude Code/(mostly) Opus 4.8 to accelerate
185 code generation and maximise test coverage (and reduce typing :D).
186  
187 With thanks to
188  
189 =over
190  
191 =item *
192  
193 Jesse Vincent for C</superpowers> (L<https://github.com/obra/superpowers>) and
194 the C<AGENTS.md> boilerplate
195  
196 =item *
197  
198 Curtis "Ovid" Poe for C</paad> (L<https://github.com/Ovid/paad>)
199  
200 =back
201  
202 for providing an agentic development framework that keeps code authority
203 firmly where it belongs.
204  
205 Iteratively reviewed by Finn Kempers <finn@shadow.cat> with analysis from
206 ZCode/GLM-5.2.
207  
208 =head1 LICENSE
209  
210 This library is free software; you can redistribute it and/or modify it
211 under the terms of the Artistic License, as distributed with Perl.
212  
213 =cut
214  
215 4 1;
↑ Summary MCP/Server.pm »