| 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} //= []
MC/DC100%1/1
$c->stash->{$PROVIDER_SLOT} //= []
$c->stash->{$PROVIDER_SLOT}
Truth table100%2/2
A
A= $c->stash->{$PROVIDER_SLOT}
| |||||||||||||
| 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} // []
MC/DC0%0/1
$c->stash->{$PROVIDER_SLOT} // []
$c->stash->{$PROVIDER_SLOT}
Truth table50%1/2
A
A= $c->stash->{$PROVIDER_SLOT}
| |||||||||||||
| 18 | 11 | ▶ | my $cfg = $c->config->{'Catalyst::Plugin::MCP'} // {}; | ||||||||||
|
Condition50%1/2
$c->config->{"Catalyst::Plugin::MCP"} // {}
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"}
| |||||||||||||
| 19 | |||||||||||||
| 20 | 11 | my %args; | |||||||||||
| 21 | $args{protocol_versions} = $cfg->{protocol_versions} | ||||||||||||
| 22 | 11 | ▶ | if $cfg->{protocol_versions}; | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 23 | 11 | ▶ | $args{server_info} = $cfg->{server_info} if $cfg->{server_info}; | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 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; | |||||||||||