view release on metacpan or  search on metacpan

bin/mcp-multibroker  view on Meta::CPAN

fails pending calls, removes the registration and starts a new connection
period. Refused TCP connections are retried every second, up to sixty times.
Other TCP setup failures and TLS verification failures log an error and stop;
there is no automatic downgrade to plaintext. No interrupted operation is
replayed. Plain HTTP endpoint URLs do not provide transport encryption;
use a trusted connection or tunnel as needed.

=head2 Process lifetime

Each downstream connection advertises C<anyevent-mcp/multibroker> version 1
in its client capabilities. A spawned stdio child can request managed idle
shutdown with C<anyevent-mcp/idle-exit>. When no calls are outstanding, the
broker may send C<anyevent-mcp/shutdown>; the child acknowledges before
exiting. This is optional and never makes HTTP children exit. Unexpected
disconnects are logged, not proactively restarted. A later use reconnects.

=head1 PERMISSION PROMPTS

C<--ask helper> (the default) answers downstream form challenges locally.
Ordinary forms use C<anyevent-mcp-form-elicitation>; permission requests keep their
specialised permission dialogs. C<--ask mcp> forwards modern challenges to
the upstream client. C<--ask auto> uses upstream form support when advertised,
otherwise the local helper. Both modes deliberately trust the upstream
client's user assertion when permission authority has been delegated to it.
The multibroker forwards the original authenticated user with every tool call,
even when a downstream saved permission rule resolves that request without
another prompt. A decline or cancel is never retried through another
interface. If a client advertises forms but silently declines them,
select C<helper> explicitly.

C<--ask tty> and C<--ask yad> select only the built-in terminal or YAD
interface for both ordinary forms and permission dialogs. These modes
ignore custom helper variables and do not fall back to another interface.

The broker advertises its local form support to downstream calls when it
will handle their forms itself. In C<mcp> mode it forwards the upstream
caller's capabilities instead. Local forms work for HTTP and stdio children,
including when the upstream caller cannot handle native input challenges.
Continuation tokens remain opaque; the broker sends the human response back
to the same downstream operation and returns its eventual result.

Spawned stdio children default to C<--ask mcp>, delegating permissions to
the multibroker, which handles them according to its own C<--ask> mode.
An explicit child C<--ask> overrides this default. Independently running
servers keep their own configuration.
Spawned C<mcp-ask-user> instances normally delegate presentation to this broker.
Use C<--ask mcp> on a separately started C<mcp-ask-user> to delegate to its
connecting client, including a multibroker.

Local permission and question dialogs share one queue. Set
C<PERL_ANYEVENT_MCP_ELICITATION_HELPER> to replace the form helper and
C<PERL_ANYEVENT_MCP_PERMISSION_HELPER> to replace the permission helper.
Cancelling a tool call cancels its downstream operation and pending local
prompt.

=head1 CLIENT CONNECTION

The upstream listener uses L<AnyEvent::MCP::Server::Simple/mcp_start>: HTTP
without stdout output by default, or stdio when run by another broker.
The service instance name defaults to C<default>. Repeated
C<--token TOKEN> options before the broker pairs configure credentials
accepted by the upstream HTTP listener. They are separate from C<--bearer>
after a downstream broker URL, which authenticates the client connection.
C<--name NAME>
selects C<[instance NAME]> in the global configuration, including its
credentials and optional C<bind> address. C<--bind ADDRESS[:PORT]> overrides
that address. The default is IPv4 loopback with a stable name-derived port
in 16384..32767. Port zero requests an ephemeral port.
C<--print-url> prints the credential-bearing URL without opening a listener
or starting children; it requires a nonzero port. Upstream stdio startup
skips HTTP listener configuration unless C<--listen> is specified; named HTTP
children still load their client defaults. Browser origins are unrestricted by default; HTTP requests
still require an accepted token. See L<AnyEvent::MCP::Intro> for examples.

=head1 OPTIONS

Shared upstream switches are documented in
L<AnyEvent::MCP::Server::Simple/COMMON COMMAND-LINE OPTIONS>.
Put broker-wide options before the first PREFIX/URL pair. Downstream
options must immediately follow the server they configure.

=head2 Broker options

=over

=item --listen

Keep the upstream HTTP/extension listener active alongside C<--stdio>
or C<--connect>. Without those, HTTP is already the default.
Applies to the broker, not its downstream servers.

=item --ask MODE

Select how downstream permission prompts are presented:
C<helper> (default), C<tty>, C<yad>, C<mcp>, or C<auto>.
This also supplies the default asking mode to spawned stdio children.
See L</PERMISSION PROMPTS>.

=back

=head2 Downstream options

=over

=item --bearer TOKEN

Authenticate the preceding HTTP(S) child with a bearer token, not
the broker's upstream listener. Supply after the child URL;
invalid for stdio children.

=item --hidden

Omit the preceding child's tools from ordinary tool discovery,
including unfiltered C<list-tools>. Discover its definitions with
C<list-tools> specifying its C<broker> prefix. Its tools remain
callable by name. Applies to HTTP and stdio children.

=item --eager

Start the preceding stdio child at broker startup instead of on
first use. Not available for HTTP children.

=item --required

Require the preceding stdio child to initialize and remain connected.
Implies C<--eager>; an unexpected disconnect causes the broker to exit.