AnyEvent-MCP

 view release on metacpan or  search on metacpan

bin/mcp-sctl  view on Meta::CPAN

#!/opt/bin/perl

=encoding utf8

=head1 NAME

mcp-sctl - ScriptCat and sctl Browser WebSocket bridge for MCP

=head1 SYNOPSIS

   mcp-sctl --stdio
   mcp-sctl
   mcp-sctl --bind 127.0.0.1:9000

=head1 DESCRIPTION

Speak the native sctl WebSocket protocol directly to ScriptCat and sctl
Browser. No sctl daemon or control proxy. Both extensions initiate their own
connections to the same listener used for authenticated MCP HTTP.
The listener defaults to C<127.0.0.1:8643>, matching ScriptCat's default URL.
Keep this server running with C<--eager> when started by mcp-multibroker.

Pair a browser once using the C<pair> MCP tool, then enter the displayed
eight-character code in that extension's External Access settings. The code
expires after two minutes. Long-term keys are stored in a private JSON file
under C<$XDG_CONFIG_HOME/anyevent-mcp/> (or C<~/.config/anyevent-mcp/>).
A pairing code grants the extension access to the bridge; the MCP permissions
independently control what an AI client may call.

C<list> discovers connected instances and their advertised methods;
C<search> looks up methods and, when available, parameter/result schemas;
C<call> invokes a method with uninterpreted JSON input. Method permission
is independent of instance permission. CDP uses the same C<call> tool with
C<debugger.send>; there is no Playwright/CDP endpoint or high-level page
automation here.

Protocol metadata is advisory, not an authorization source. It is cached
under C<$XDG_CACHE_HOME/anyevent-mcp/> and refreshed over HTTPS as needed.
Only methods advertised by the live extension can be invoked, even if a
downloaded description lists more.

=head1 FIRST USE

With C<mcp-multibroker>, add an eager child:

   sctl --- mcp-sctl --- --eager

Stop any running C<sctl serve> first; it normally owns that same port.
Print both connection URLs:

   mcp-sctl --print-urls

The output includes the ordinary authenticated C<http://> MCP URL and a
credential-free C<ws://127.0.0.1:8643/> URL for the browser extensions.
Only the latter goes into ScriptCat's External Access or sctl Browser.
The extension authenticates separately with the pairing HMAC.

Call C<sctl.pair> from your MCP client, then enable External Access in
ScriptCat's options and enter the returned code. The extension connects to
C<ws://127.0.0.1:8643/>. Call C<sctl.list> to confirm it is online, then
C<sctl.search> to find operations and C<sctl.call> to invoke them.

Pair C<sctl Browser> separately, using its popup, only when browser-wide
debugging/control is desired. ScriptCat userscript management does not
require C<sctl Browser>.

=head1 LOGGING

The normal MCP operator log reports listener startup, pairing windows,
authenticated instances, disconnects, tool requests and call outcomes.
Calls include abbreviated arguments and elapsed time; script listings,
source retrieval and searches report counts or ranges, never complete
source bodies. Pairing codes and authentication keys are not logged.
C<--quiet> suppresses operator activity logging; ordinary debug/trace
diagnostics use the configured AnyEvent::Log verbosity.

=head1 OPTIONS

Use the shared C<--bind> option for both the extension WebSocket and MCP HTTP
listener. C<--print-url> prints both the authenticated MCP endpoint and the
token-free extension WebSocket endpoint.
The shared switches are documented in
L<AnyEvent::MCP::Server::Simple/COMMON COMMAND-LINE OPTIONS>.

=cut

use common::sense;

use JSON::XS ();
use Time::HiRes qw(time);
use Digest::SHA qw(hmac_sha256 hmac_sha256_hex sha256_hex);
use MIME::Base64 ();
use Scalar::Util qw(weaken);
use File::Path ();

use AnyEvent ();
use AnyEvent::HTTP ();
use Socket ();
use AnyEvent::Socket ();
use AnyEvent::WebSocket::Server ();
use AnyEvent::WebSocket::Message ();
use Crypt::AuthEnc::GCM ();

use AnyEvent::MCP ();
use AnyEvent::MCP::Config ();
use AnyEvent::MCP::Server::HTTP ();
use AnyEvent::MCP::Server::JSONL ();
use AnyEvent::MCP::Server::Permissions ();
use AnyEvent::MCP::Server::Toolset ();
use AnyEvent::MCP::Server::Simple qw(mcp_getoptions mcp_tool_help mcp_log mcp_log_request);

my $options = mcp_getoptions
   {
      usage       => "Usage: mcp-sctl [OPTION]...\n",
      default_port => 8643,
      path        => "/",
      description => "Bridge ScriptCat/sctl Browser WebSockets directly to MCP.",
      examples    => "  mcp-sctl --stdio\n  mcp-sctl --print-urls",
      print_url_extra => sub {
         my $http = shift;
         my $url = AnyEvent::MCP::Server::HTTP->new (
            %$http, path => "/", url_scheme => "http",
         )->url (0);
         $url =~ s/\Ahttp:/ws:/;
         print "$url  # ScriptCat / sctl Browser\n";
      },
   };
@ARGV and die "Unexpected arguments\n";

my $name = $options->{name};
my $connect = $options->{connect};
my $stdio = $options->{stdio} || !defined $connect && $ENV{PERL_ANYEVENT_MCP_MULTIBROKER_PROTOCOL} eq "stdio";
!($stdio && defined $connect) or die "Cannot combine --stdio and --connect\n";

my $config = AnyEvent::MCP::Config::global_config ();
my %http = $config->http_settings ($name, $options->{bind}, $options->{default_port});
$http{tokens} = $options->{tokens} if $options->{tokens};

my $json = JSON::XS->new->utf8->max_depth (64);
my $log_json = JSON::XS->new->allow_nonref;
my $keys_file = ($ENV{XDG_CONFIG_HOME} || "$ENV{HOME}/.config") . "/anyevent-mcp/sctl-$name-keys.json";



( run in 1.813 second using v1.01-cache-2.11-cpan-1bcd28dbaf1 )