view release on metacpan or  search on metacpan

bin/mcp-webbrowser  view on Meta::CPAN

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

=head1 PERMISSIONS

The default rule file is C<~/.config/anyevent-mcp/rules/webbrowser-default.ini>,
under C<$XDG_CONFIG_HOME> when set. C<--name NAME> replaces C<default>.
C<read> covers tab and operation discovery; C<exec> covers arbitrary JavaScript
and tab-operation calls. A userscript or extension may apply additional
permissions for individual operations.

JavaScript exec prompts offer this exact code in this target, any code in
this target, or any code in all targets. Operation exec prompts offer
corresponding scopes for browser operations. Independently, each exec request
offers this origin, the same scheme and host on any port, or any origin.
Only HTTP(S) origins offer persistent scopes: opaque origins such as C<null>
cannot distinguish different documents, so they allow one-time decisions only.
Saved target grants also cover future tabs using the same target name.
Saved rules use C<match.subject> and C<match.origin> as independent fields.
Rules without C<match.origin> match all origins, as do broad C<--auto-allow>
overrides. The broker derives origins from the URL already reported by the
userscript on connect, state changes and navigation, including older clients.
For HTTP(S), credentials and the path/query/fragment are excluded.
Origin identity relies on the connected userscript's reported URL, not on
independently authenticating the page's location.
C<--ask> selects the same helper, tty, yad, mcp or auto modes as other servers.

=head1 OPTIONS

Shared switches are documented in
L<AnyEvent::MCP::Server::Simple/COMMON COMMAND-LINE OPTIONS>.
The following switch is specific to C<mcp-webbrowser>.

=over

=item --ask MODE

Permission prompts: C<helper> (default), C<tty>, C<yad>, C<mcp> or
C<auto>. tty/yad force local interface; mcp delegates to client,
auto prefers native elicitation when offered. See L</PERMISSIONS>.

=back

=head2 Shared-option behavior

=over

=item --stdio

The browser's auxiliary HTTP/WebSocket listener stays active while
MCP uses stdio.

=item --connect URL

The auxiliary browser HTTP/WebSocket listener stays active while
MCP connects to an upstream multibroker.

=item --auto-allow TOOL[,ACTION[,CAPABILITY]]

For example, C<--auto-allow '*,*'> allows discovery and JavaScript
execution in explicitly opted-in tabs. The executed page code then
has full authority within that page; use this only when intended.

=back

=head1 BROWSER PROTOCOL

WebSocket authentication happens at C</TOKEN/TARGET>. C<TARGET> is one
percent-encoded path component. Before ordinary messages, send:

   ["mcp-webbrowser", 1, 1, INSTANCE_ID, {"url": URL, "title": TITLE}]

C<INSTANCE_ID> identifies one loaded document. Keep it across reconnects of that
document and change it on navigation/reload. The private browser protocol is
1.1, independent of MCP and the old xpcse browser-transfer protocol. Compatible
older/newer minor versions can connect. Version 1.0 clients support page
execution but not additional tab operations; discovery returns an empty list
and unsupported calls fail without disconnecting the browser.
The broker answers C<["welcome", TARGET, INSTANCE_ID, REVISION]>.
The requested target represents a browser tab: a different document with the
same target replaces its previous connection and increments the revision.
Reconnecting the same document retains that revision. A disconnected tab's
identity expires after 30 seconds with no pending navigation. No page is