AnyEvent-MCP
view release on metacpan or search on metacpan
lib/AnyEvent/MCP/Server/Simple.pm view on Meta::CPAN
C<< without => ["ask"] >>. The parser rejects excluded switches, and
C<--help> omits them. All common options are enabled by default.
=item print_url_extra => $callback
Append application-specific URLs to C<--print-url> output. Called once with
the resolved HTTP settings after the normal MCP URLs have been printed.
=item default_port => $port
Choose an application-specific fallback port for C<--print-url>, without
replacing the bind address or overriding ports explicitly specified by
C<--bind> or configuration. The application must also pass it to
C<http_settings> when starting its listener.
=back
See L</COMMON COMMAND-LINE OPTIONS> for the full reference to shared
server switches. Application-specific Getopt::Long options are parsed alongside them.
These switches also appear in C<--help>; application options are passed
through to L<Getopt::Long>. Other leading hash settings (e.g. C<path>,
C<auth>, C<url_scheme>) go to C<mcp_start>. Parse positional C<@ARGV>
in the application; C<mcp_getoptions> deliberately does not require them
for help or URL discovery. Default activity logging includes asynchronous
tool failures and formats time, program, instance and PID. Environment
C<PERL_ANYEVENT_LOG> can select destinations and verbosity.
=item mcp_tool_help ($enabled, @toolsets)
If C<$enabled> is true, print the definitions registered in the supplied
L<AnyEvent::MCP::Server::Toolset> objects and exit. Otherwise do nothing.
Call after registering tools but before starting listeners for executables
which manage their own toolsets. Only registered tools appear.
=item mcp_log $message
Emit operator-facing activity to the configured AnyEvent::Log destination,
bypassing its diagnostic verbosity filter. C<--quiet> suppresses this log.
=item mcp_log_request ($server, $req, %extra)
C<on_request> callback to report tool invocations once across permission
retries, and log tool-error replies, including asynchronous ones. It logs
selected arguments rather than entire request or reply payloads. This includes
JSON-quoted previews of command arguments and VCS filenames (up to four,
80 characters each), and Vim C<ex> commands (up to 200 characters).
These can contain sensitive text. The Simple starters install it by default;
custom servers can use it too.
C<%extra> appends application-specific C<key=value> fields in key order.
Sanitize sensitive arguments before passing them.
=item mcp_start %config
Starts and runs the usual server. When C<stdio> is true or
C<PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL> is C<stdio>, uses C<mcp_stdio>.
Otherwise starts HTTP without printing its URL. HTTP-capable executables
provide C<--print-url> to retrieve the URL explicitly.
The HTTP defaults are IPv4 loopback, a stable name-derived port in
16384..32767, and C</> as the endpoint path.
Without explicit C<tokens>, one server-specific token is derived from
the private global secret. The selected token authenticates either its URL
path or an
C<Authorization: Bearer TOKEN> header at the clean URL returned by
C<< $server->url (0) >>. The corresponding executable's C<--print-url>
option prints the first accepted token in its URL.
C<name> selects the C<[instance NAME]> configuration section and credential.
It defaults to C<default>.
Named settings C<bind>, C<path>, C<url_host>, C<url_scheme>, C<tokens>,
C<tls_cert> and C<tls_key> are loaded from the global configuration.
Explicit C<tokens> (an ordered,
nonempty array reference of URL-safe strings) replaces the configured list
and the derived default. Every token works in the URL and bearer header.
An explicit C<bind> overrides the configured bind address. Other arguments
override these settings.
The global secret is generated automatically when needed; see
L<AnyEvent::MCP/GLOBAL CONFIGURATION>. No configuration is loaded for stdio.
Unless explicitly disabled using C<mcp_permissions undef>, Simple constructs
a default permission engine. C<--ask> and automatic permission rules configure
it along with any application-supplied permission object.
HTTP startup neither prints to stdout nor changes its buffering.
C<mcp_start> does not parse C<@ARGV>; applications parse their own options.
The bundled executables use C<mcp_getoptions>, which handles shared
options and URL discovery before starting the event loop.
=item mcp_connect %config
Run a reverse-connecting JSONL server using C<connect =E<gt>
"http[s]://host:port/token/alias">. HTTPS verifies the server certificate
and hostname. It sends the authenticated extension hello only after the
transport is established, then serves MCP over the socket. Refused TCP
connections retry every second for at most sixty attempts, and unexpected
established disconnects start a new retry period. Other TCP setup and TLS
handshake errors are reported and stop the server.
Calls are cancelled rather than replayed.
This connection has no spawned-child lifecycle authority.
=item mcp_stdio %config
Creates and runs a server over stdin/stdout. Arguments override the collected
configuration. Stdout buffering is disabled. On stdin EOF, pending replies
finish and stdout drains before
this function returns. Stream errors close the connection and cancel pending
requests.
=item mcp_http %config
Creates and runs an HTTP server. For example:
mcp_http
host => "127.0.0.1",
port => 31740,
path => "/mcp/",
tokens => ["your-long-random-secret"];
Arguments override the collected configuration. Unlike C<mcp_start>, this
function does not derive or supply authentication. B<Always> pass C<tokens>,
or explicitly pass C<auth =E<gt> "none"> when a trusted embedding layer
( run in 0.891 second using v1.01-cache-2.11-cpan-1bcd28dbaf1 )