AnyEvent-MCP
view release on metacpan or search on metacpan
bin/mcp-webbrowser view on Meta::CPAN
when Chromium replaced a discarded tab. After such a discard and restoration,
the user had to choose Allow again. This was reported in
L<https://github.com/scriptscat/scriptcat/issues/1791> and fixed in 1.5.0.
=head1 FIRST TOOL CALL
After allowing a tab, ask your assistant:
Call tabs and show the connected tabs. On one of them, execute
document.title and show its result.
Use a C<target> returned by C<tabs> for the C<execute> call. Listing
requires C<read> permission; even this simple JavaScript expression needs
C<exec> permission, because execution has full page authority. The
tool returns an object containing C<value>; there is no read-only mode.
With a multibroker prefix C<browser>, the tools are C<browser.tabs>
and C<browser.execute>. If no tab is listed, confirm that the userscript
was allowed B<on that tab> and that its indicator shows a connection.
Installing the userscript does not grant access to any tabs.
An execution error or timeout does not prove that nothing happened;
do not blindly retry JavaScript that changes page state.
=head1 TOOLS
=over
=item tabs
Return C<{tabs: [...]}> with each connected tab's C<target>, current document
C<instance_id>, integer C<revision>, and client-reported C<url> and C<title>.
Boolean C<last_allowed> identifies the most recent explicit Allow operation;
boolean C<marked> identifies the tab chosen with the Mark menu command.
Both selections are broker-local, survive ordinary reconnection, and are
cleared when their tab session retires. Neither grants execution permission.
The revision starts at 1 and advances on document replacement, not on an
ordinary WebSocket reconnect or a same-document navigation. Disconnected tab
identities are retained for up to 30 seconds. This is cached registration
metadata, not a fresh DOM inspection. Requires C<read> permission.
=item execute
Run C<code> on C<target>. Optional C<instance_id> and C<revision> from C<tabs>
reject a replaced document before dispatch. C<timeout> defaults to 30 seconds
and can be 1..300 seconds. With C<navigate> false (the default), the browser
awaits the evaluation result. Results are C<{value: JSON_VALUE}>; exceptions
become tool errors.
Replies default to a 16 KiB UTF-8 JSON limit; C<max_bytes> can raise the
limit to 2 MiB (minimum 1024 bytes). The size includes the JSON envelope.
Oversized results yield an error instead of truncating JSON or disconnecting
the browser. Code has already executed when the size error is returned;
do not blindly retry commands with side effects.
With C<navigate> true, the broker sends the command, awaits the browser's
C<ready> message, and sends C<proceed> before the browser evaluates it.
The broker then waits for either a new document registering on the same tab
or an observed same-document navigation. The result has C<navigation> equal
to C<document> or C<same-document>, the resulting C<revision>, and reported
URL/title. If neither completion is observed before the timeout, it returns
C<navigation: "timeout"> with a reason, current revision and available metadata.
Timeout does not imply that the command was not executed; no automatic retry
is attempted. One navigation operation at a time is allowed per tab.
The browser client injects C<code> as body of C<async () =E<gt> CODE>
in the page's JavaScript world. Supply only CODE, not the arrow-function
wrapper. For example, C<({title: document.title})> returns an object;
C<async () =E<gt> ({title: document.title})> returns a function and is
rejected as a non-JSON result. Single expression yields its value without
C<return>; braced function body needs explicit C<return> for multiple
statements.
C<await> works inside either form. Declarations in the body do not persist
between calls unless assigned to page globals. Results are awaited. This
does not use C<eval> or C<Function>. Syntax errors can prevent the injected
script from starting; a temporary page-world error listener tries to return
the native syntax-error message, otherwise the client reports an injection
failure. Source injection is serialized until each script acknowledges
successful compilation or fails; asynchronous execution thereafter may
overlap. Code has full page-context authority, with no read-only evaluation
mode or sandbox claim.
Cancellation and timeout send a best-effort cancel message. They cannot undo
already executed code or guarantee that JavaScript stops. Disconnect fails
ordinary pending calls without replaying them. A navigation request persists
across disconnects and may complete on the next document's registration.
Concurrent human navigation can satisfy a pending request; success reports
observation, not proof that the submitted code caused the navigation.
=item add-element
Insert an element through the userscript's C<GM_addElement> in the content
sandbox. This can bypass page CSP for stylesheets and scripts. Required
C<target> and C<tag>; optional C<parent> is a document CSS selector
(default: document root). C<attributes> contains HTML attribute strings,
while C<properties> contains DOM property values, such as C<textContent>
or C<innerHTML>. Properties are supplied during element creation; attributes
are set explicitly as well. An unsuccessful selector or insertion is an error.
The result is C<{value: {tag: TAG, id: ID_OR_NULL}}> and does not assert that
the caller's C<id> is unique. No automatic ID or registry is maintained: give
elements a distinctive C<id> or C<data-*> attribute when later page-context
C<execute> calls need to modify or remove them. Uses C<exec> permission and
supports the same optional C<instance_id> and C<revision> guards as C<execute>.
=item list-tab-operations
Ask the connected tab for additional operations it supports. Returns
C<{operations: [...]}> with operation descriptions and input schemas, or an
empty array if none are available. Unlike MCP tools, these are discovered
per tab and are not registered with the broker. Requires C<read> permission.
Supports optional C<instance_id> and C<revision> guards.
=item call-tab-operation
Call a tab-specific operation previously discovered with
C<list-tab-operations>. Supply C<target>, C<operation> and optional
C<arguments>. The browser implements and authorizes the operation; the
broker does not interpret its name or arguments. Returns C<{value: ...}> or
a tool error. Requires C<exec> permission, and supports the same document
guards, timeout and result-size options as C<execute>.
=back
( run in 0.761 second using v1.01-cache-2.11-cpan-234fa220139 )