real-browser-cli 0.16.3__tar.gz → 0.16.8__tar.gz

{real_browser_cli-0.16.3 → real_browser_cli-0.16.8}/.gitea/workflows/testing.yml

@@ -28,8 +28,8 @@ jobs:
       fail-fast: false
       matrix:
         browser-cli-client-version:
-          - "0.9.3"
-          - "0.9.5"
+          - "0.15.0"
+          - "0.16.0"
 
     steps:
       - name: Checkout

{real_browser_cli-0.16.3 → real_browser_cli-0.16.8}/CLAUDE.md

@@ -3,7 +3,7 @@
 ## Memory laden
 Beim Start dieser Session: Memory-Datei lesen für vollständigen Codebase-Kontext:
 ```
-/home/daniel156161/Dokumente/Nodes - Obsidian/AI-Worker/03 Bereiche/Open Source & Side Projects/browser-cli.md
+03 Bereiche/Open Source & Side Projects/browser-cli.md
 ```
 
 Memory nach Änderungen aktualisieren (neue Commands, Architektur-Änderungen, neue Patterns, Version-Bumps).

{real_browser_cli-0.16.3 → real_browser_cli-0.16.8}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: real-browser-cli
-Version: 0.16.3
+Version: 0.16.8
 Summary: Control your real running browser from the terminal or Python SDK
 Project-URL: Homepage, https://git.yiprawr.dev/Automatisation/browser-cli
 Project-URL: Repository, https://git.yiprawr.dev/Automatisation/browser-cli
@@ -90,6 +90,8 @@ Requires-Dist: questionary>=2
 Requires-Dist: rich>=13
 Provides-Extra: fast
 Requires-Dist: zstandard>=0.22; extra == 'fast'
+Provides-Extra: mcp
+Requires-Dist: mcp<3,>=2; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # browser-cli
@@ -164,6 +166,11 @@ For better remote-response compression, install the optional `fast` extra:
 uv tool install "real-browser-cli[fast]"
 ```
 
+To expose the conservative MCP tool surface, install the optional `mcp` extra:
+```sh
+uv tool install "real-browser-cli[mcp]"
+```
+
 To upgrade later:
 
 ```sh
@@ -235,6 +242,89 @@ browser-cli/
 
 ---
 
+## Stateless MCP server
+The optional MCP adapter exposes a small, typed subset of the Python SDK for
+MCP hosts such as Claude Desktop, Claude Code, Cursor, or VS Code. It controls
+the same real browser; it does not launch a headless browser or duplicate the
+browser command implementation.
+
+Install and run the local stdio server:
+```sh
+uv tool install "real-browser-cli[mcp]"
+browser-cli-mcp
+```
+
+Example MCP host configuration:
+```json
+{
+  "mcpServers": {
+    "browser-cli": {
+      "command": "browser-cli-mcp"
+    }
+  }
+}
+```
+
+The server is stateless at the MCP layer. Every tool call creates a fresh
+`BrowserCLI` SDK client, and browser state remains in the real browser. Pass
+`browser`, `remote`, and `key` on a tool call when a specific local profile or
+authenticated browser-cli remote is required.
+
+`browser_navigate`, `browser_tabs_close`, and `browser_screenshot` take an
+optional `tab_id` and act on the active tab when it is omitted, so a caller
+does not need a preceding `browser_tabs_list` round trip. `browser_tabs_close`
+reports the tab it closed.
+
+Available tools:
+- `browser_tabs_list`, `browser_tabs_open`, `browser_tabs_close`
+- `browser_navigate`, `browser_page_info`
+- `browser_extract_text`, `browser_extract_markdown`
+- `browser_dom_query`, `browser_dom_click`, `browser_dom_type`
+- `browser_screenshot`
+
+Generic JavaScript evaluation, raw browser commands, storage writes, and
+session import are intentionally not exposed.
+
+### Pinning one browser and naming tools
+Set `BROWSER_CLI_PROFILE` to pin every call from an MCP server to one browser,
+so tools do not have to pass `browser` and listing tools do not fan out across
+all connected browsers:
+```json
+{
+  "mcpServers": {
+    "browser-cli-testing": {
+      "command": "browser-cli-mcp",
+      "env": {
+        "BROWSER_CLI_PROFILE": "testing",
+        "BROWSER_CLI_MCP_TOOL_PREFIX": ""
+      }
+    }
+  }
+}
+```
+`BROWSER_CLI_REMOTE` and `BROWSER_CLI_KEY` pin an authenticated remote the same
+way. Explicit `browser`, `remote`, and `key` tool arguments still win.
+
+Tool names carry a `browser_` prefix by default so they stay unambiguous in
+hosts that expose raw MCP tool names. Hosts that already prefix tools with the
+server name produce stutter such as `browser_cli_testing_browser_tabs_list`;
+setting `BROWSER_CLI_MCP_TOOL_PREFIX` to an empty string drops the built-in
+prefix and yields `browser_cli_testing_tabs_list`. Any other value replaces the
+prefix.
+
+For local development and testing, Streamable HTTP is also available:
+```sh
+browser-cli-mcp --transport streamable-http --port 8000
+# endpoint: http://127.0.0.1:8000/mcp
+```
+
+HTTP uses stateless JSON responses and intentionally refuses non-loopback bind
+addresses because this MCP endpoint has no independent authentication. For a
+browser on another machine, keep MCP local and pass an authenticated
+browser-cli `remote` target to each tool call.
+
+---
+
 ## CLI reference
 During source development, commands are usually run as `uv run browser-cli [--browser ALIAS] <command>`. After tool installation, use `browser-cli ...` directly. Add `--remote HOST[:PORT]` and optionally `--key PATH` to target a browser exposed by `browser-cli serve`.
 
@@ -290,8 +380,9 @@ browser-cli search so click choices
 ```sh
 browser-cli tabs list                        # list all open tabs (all windows)
 browser-cli tabs count                       # count all tabs
-browser-cli tabs count youtube               # count tabs matching URL pattern
-browser-cli tabs filter youtube              # list tabs matching URL pattern
+browser-cli tabs count youtube               # count tabs whose URL contains "youtube"
+browser-cli tabs filter youtube              # list tabs whose URL contains "youtube"
+browser-cli tabs filter 'twitch.tv/*'        # glob: list every twitch.tv tab
 browser-cli tabs query "pull request"        # search tabs by URL or title
 
 browser-cli tabs active 1234                 # switch browser focus to tab
@@ -313,6 +404,10 @@ browser-cli tabs sort --by time
 browser-cli tabs merge-windows               # pull all tabs into the current window
 ```
 
+> URL patterns for `tabs filter` / `tabs count` match against the full tab URL.
+> A plain string is a case-sensitive substring (`youtube`); a pattern containing
+> `*` or `?` is treated as a glob (`twitch.tv/*`, `*.twitch.tv`).
+
 ### Tab groups
 ```sh
 browser-cli groups list                      # list all tab groups

{real_browser_cli-0.16.3 → real_browser_cli-0.16.8}/README.md

@@ -70,6 +70,11 @@ For better remote-response compression, install the optional `fast` extra:
 uv tool install "real-browser-cli[fast]"
 ```
 
+To expose the conservative MCP tool surface, install the optional `mcp` extra:
+```sh
+uv tool install "real-browser-cli[mcp]"
+```
+
 To upgrade later:
 
 ```sh
@@ -141,6 +146,89 @@ browser-cli/
 
 ---
 
+## Stateless MCP server
+The optional MCP adapter exposes a small, typed subset of the Python SDK for
+MCP hosts such as Claude Desktop, Claude Code, Cursor, or VS Code. It controls
+the same real browser; it does not launch a headless browser or duplicate the
+browser command implementation.
+
+Install and run the local stdio server:
+```sh
+uv tool install "real-browser-cli[mcp]"
+browser-cli-mcp
+```
+
+Example MCP host configuration:
+```json
+{
+  "mcpServers": {
+    "browser-cli": {
+      "command": "browser-cli-mcp"
+    }
+  }
+}
+```
+
+The server is stateless at the MCP layer. Every tool call creates a fresh
+`BrowserCLI` SDK client, and browser state remains in the real browser. Pass
+`browser`, `remote`, and `key` on a tool call when a specific local profile or
+authenticated browser-cli remote is required.
+
+`browser_navigate`, `browser_tabs_close`, and `browser_screenshot` take an
+optional `tab_id` and act on the active tab when it is omitted, so a caller
+does not need a preceding `browser_tabs_list` round trip. `browser_tabs_close`
+reports the tab it closed.
+
+Available tools:
+- `browser_tabs_list`, `browser_tabs_open`, `browser_tabs_close`
+- `browser_navigate`, `browser_page_info`
+- `browser_extract_text`, `browser_extract_markdown`
+- `browser_dom_query`, `browser_dom_click`, `browser_dom_type`
+- `browser_screenshot`
+
+Generic JavaScript evaluation, raw browser commands, storage writes, and
+session import are intentionally not exposed.
+
+### Pinning one browser and naming tools
+Set `BROWSER_CLI_PROFILE` to pin every call from an MCP server to one browser,
+so tools do not have to pass `browser` and listing tools do not fan out across
+all connected browsers:
+```json
+{
+  "mcpServers": {
+    "browser-cli-testing": {
+      "command": "browser-cli-mcp",
+      "env": {
+        "BROWSER_CLI_PROFILE": "testing",
+        "BROWSER_CLI_MCP_TOOL_PREFIX": ""
+      }
+    }
+  }
+}
+```
+`BROWSER_CLI_REMOTE` and `BROWSER_CLI_KEY` pin an authenticated remote the same
+way. Explicit `browser`, `remote`, and `key` tool arguments still win.
+
+Tool names carry a `browser_` prefix by default so they stay unambiguous in
+hosts that expose raw MCP tool names. Hosts that already prefix tools with the
+server name produce stutter such as `browser_cli_testing_browser_tabs_list`;
+setting `BROWSER_CLI_MCP_TOOL_PREFIX` to an empty string drops the built-in
+prefix and yields `browser_cli_testing_tabs_list`. Any other value replaces the
+prefix.
+
+For local development and testing, Streamable HTTP is also available:
+```sh
+browser-cli-mcp --transport streamable-http --port 8000
+# endpoint: http://127.0.0.1:8000/mcp
+```
+
+HTTP uses stateless JSON responses and intentionally refuses non-loopback bind
+addresses because this MCP endpoint has no independent authentication. For a
+browser on another machine, keep MCP local and pass an authenticated
+browser-cli `remote` target to each tool call.
+
+---
+
 ## CLI reference
 During source development, commands are usually run as `uv run browser-cli [--browser ALIAS] <command>`. After tool installation, use `browser-cli ...` directly. Add `--remote HOST[:PORT]` and optionally `--key PATH` to target a browser exposed by `browser-cli serve`.
 
@@ -196,8 +284,9 @@ browser-cli search so click choices
 ```sh
 browser-cli tabs list                        # list all open tabs (all windows)
 browser-cli tabs count                       # count all tabs
-browser-cli tabs count youtube               # count tabs matching URL pattern
-browser-cli tabs filter youtube              # list tabs matching URL pattern
+browser-cli tabs count youtube               # count tabs whose URL contains "youtube"
+browser-cli tabs filter youtube              # list tabs whose URL contains "youtube"
+browser-cli tabs filter 'twitch.tv/*'        # glob: list every twitch.tv tab
 browser-cli tabs query "pull request"        # search tabs by URL or title
 
 browser-cli tabs active 1234                 # switch browser focus to tab
@@ -219,6 +308,10 @@ browser-cli tabs sort --by time
 browser-cli tabs merge-windows               # pull all tabs into the current window
 ```
 
+> URL patterns for `tabs filter` / `tabs count` match against the full tab URL.
+> A plain string is a case-sensitive substring (`youtube`); a pattern containing
+> `*` or `?` is treated as a glob (`twitch.tv/*`, `*.twitch.tv`).
+
 ### Tab groups
 ```sh
 browser-cli groups list                      # list all tab groups

real_browser_cli-0.16.8/browser_cli/auth/server_identity.py

@@ -0,0 +1,57 @@
+"""Persistent server identity keys for SSH-style remote host pinning."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives.serialization import Encoding, NoEncryption, PrivateFormat, PublicFormat, load_pem_private_key
+
+from browser_cli.constants import CONFIG_DIR
+
+SERVER_IDENTITY_PATH = CONFIG_DIR / "server_identity.pem"
+
+def load_or_create_server_identity(path: Path = SERVER_IDENTITY_PATH) -> Ed25519PrivateKey:
+  """Load the persistent serve identity key, creating it on first start."""
+  if path.exists():
+    key = load_pem_private_key(path.read_bytes(), password=None)
+    if not isinstance(key, Ed25519PrivateKey):
+      raise ValueError(f"server identity key is not Ed25519: {path}")
+    return key
+
+  path.parent.mkdir(parents=True, exist_ok=True)
+  key = Ed25519PrivateKey.generate()
+  pem = key.private_bytes(Encoding.PEM, PrivateFormat.PKCS8, NoEncryption())
+  fd = path.open("xb")
+  try:
+    fd.write(pem)
+  finally:
+    fd.close()
+  path.chmod(0o600)
+  return key
+
+def public_key_hex(key: Ed25519PrivateKey) -> str:
+  return key.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw).hex()
+
+def _signed_challenge_fields(challenge: dict) -> dict:
+  return {key: value for key, value in challenge.items() if key != "server_sig"}
+
+def challenge_payload(challenge: dict) -> bytes:
+  """Canonical bytes signed by the server identity key."""
+  return json.dumps(_signed_challenge_fields(challenge), sort_keys=True, separators=(",", ":")).encode("utf-8")
+
+def sign_challenge(challenge: dict, key: Ed25519PrivateKey) -> str:
+  return key.sign(challenge_payload(challenge)).hex()
+
+def verify_challenge_signature(challenge: dict) -> bool:
+  pub_hex = challenge.get("server_pubkey")
+  sig_hex = challenge.get("server_sig")
+  if not isinstance(pub_hex, str) or not isinstance(sig_hex, str):
+    return False
+  try:
+    pub = Ed25519PublicKey.from_public_bytes(bytes.fromhex(pub_hex))
+    pub.verify(bytes.fromhex(sig_hex), challenge_payload(challenge))
+    return True
+  except (InvalidSignature, ValueError):
+    return False

{real_browser_cli-0.16.3 → real_browser_cli-0.16.8}/browser_cli/client/core.py

@@ -151,21 +151,25 @@ def active_browser_targets(*, include_remotes: bool = True, key=None, suppress_p
     targets.extend(_remote_browser_targets(key=key, suppress_pq_warning=suppress_pq_warning))
   return targets
 
-def _cached_client_row(target: BrowserTarget) -> dict | None:
+def _cached_client_row(target: BrowserTarget, *, scoped: bool = False) -> dict | None:
   """Build a clients row from a target's discovery data, skipping a roundtrip.
 
   Returns None when the remote didn't advertise its version (older serve), so
-  callers fall back to an explicit ``clients.list`` query.
+  callers fall back to an explicit ``clients.list`` query. When *scoped* is
+  true, the caller already selected one remote host, so render profile-only
+  labels instead of adding a host group header.
   """
   if target.version is None and target.extension_version is None:
     return None
-  return {
-    "profile": target.display_name,
-    "profileGroup": target.display_group,
+  row = {
+    "profile": target.profile if scoped else target.display_name,
     "name": target.browser_name or "",
     "version": target.version or "",
     "extensionVersion": target.extension_version or "",
   }
+  if target.display_group and not scoped:
+    row["profileGroup"] = target.display_group
+  return row
 
 def _rows_from_result(result, label: str, profile_group: str | None) -> list[dict]:
   rows = []
@@ -243,6 +247,34 @@ def collect_browser_clients(
     return rows
 
   if remote:
+    targets = remote_browser_targets(remote, key=key)
+    if browser_alias:
+      targets = [target for target in targets if target.profile == browser_alias or target.display_name == browser_alias]
+    if targets:
+      uncached = []
+      for target in targets:
+        cached = _cached_client_row(target, scoped=True)
+        if cached is not None:
+          rows.append(cached)
+        else:
+          uncached.append(target)
+      results = _run_concurrent([
+        (lambda t=t: _client_rows_async(
+          t.profile,
+          profile=t.profile,
+          remote=remote,
+          key=key,
+        ))
+        for t in uncached
+      ])
+      for result in results:
+        if isinstance(result, (BrowserNotConnected, RuntimeError)):
+          continue
+        if isinstance(result, BaseException):
+          raise result
+        rows.extend(result)
+      return rows
+
     result = send_command("clients.list", profile=browser_alias, remote=remote, key=key)
     for item in result or []:
       row = dict(item)

{real_browser_cli-0.16.3 → real_browser_cli-0.16.8}/browser_cli/client/messages.py

@@ -5,8 +5,8 @@ import uuid
 from typing import Any
 
 from browser_cli import transport
-from browser_cli.endpoints import _normalize_endpoint
 from browser_cli.errors import BrowserNotConnected
+from browser_cli.remote.registry import resolve_remote_endpoint
 
 def base_message(command: str, args: dict | None) -> dict:
   return {"id": str(uuid.uuid4()), "command": command, "args": args or {}}
@@ -14,7 +14,7 @@ def base_message(command: str, args: dict | None) -> dict:
 def requested_target(profile: str | None, remote: str | None) -> tuple[str | None, str | None]:
   requested_profile = profile or os.environ.get("BROWSER_CLI_PROFILE")
   remote_endpoint = remote or os.environ.get("BROWSER_CLI_REMOTE")
-  return requested_profile, _normalize_endpoint(remote_endpoint) if remote_endpoint else None
+  return requested_profile, resolve_remote_endpoint(remote_endpoint) if remote_endpoint else None
 
 def encode_payload(msg: dict) -> bytes:
   return json.dumps(msg).encode("utf-8")

{real_browser_cli-0.16.3 → real_browser_cli-0.16.8}/browser_cli/commands/extract.py

@@ -1,7 +1,7 @@
 import json
 
 import click
-from browser_cli.commands import client_from_ctx, handle_errors
+from browser_cli.commands import client_from_ctx, handle_errors, tab_option
 from rich.console import Console
 from rich.table import Table
 
@@ -12,10 +12,11 @@ def extract_group():
     """Extract content from the active tab."""
 
 @extract_group.command("links")
+@tab_option
 @handle_errors
-def extract_links():
-    """Extract all links from the active tab."""
-    links = client_from_ctx().extract.links()
+def extract_links(tab_id):
+    """Extract all links from the active tab or --tab."""
+    links = client_from_ctx().extract.links(tab_id)
     if not links:
         console.print("[yellow]No links found[/yellow]")
         return
@@ -27,10 +28,11 @@ def extract_links():
     console.print(table)
 
 @extract_group.command("images")
+@tab_option
 @handle_errors
-def extract_images():
-    """Extract all images from the active tab."""
-    images = client_from_ctx().extract.images()
+def extract_images(tab_id):
+    """Extract all images from the active tab or --tab."""
+    images = client_from_ctx().extract.images(tab_id)
     if not images:
         console.print("[yellow]No images found[/yellow]")
         return
@@ -42,29 +44,33 @@ def extract_images():
     console.print(table)
 
 @extract_group.command("text")
+@tab_option
 @handle_errors
-def extract_text():
-    """Extract all visible text from the active tab."""
-    console.print(client_from_ctx().extract.text())
+def extract_text(tab_id):
+    """Extract all visible text from the active tab or --tab."""
+    console.print(client_from_ctx().extract.text(tab_id))
 
 @extract_group.command("json")
 @click.argument("selector")
+@tab_option
 @handle_errors
-def extract_json(selector):
-    """Parse and pretty-print JSON content inside SELECTOR."""
-    data = client_from_ctx().extract.json(selector)
+def extract_json(selector, tab_id):
+    """Parse and pretty-print JSON content inside SELECTOR in the active tab or --tab."""
+    data = client_from_ctx().extract.json(selector, tab_id)
     console.print_json(json.dumps(data))
 
 @extract_group.command("html")
+@tab_option
 @handle_errors
-def extract_html():
-    """Print the full HTML of the active tab to stdout."""
-    click.echo(client_from_ctx().extract.html())
+def extract_html(tab_id):
+    """Print the full HTML of the active tab or --tab to stdout."""
+    click.echo(client_from_ctx().extract.html(tab_id))
 
 @extract_group.command("markdown")
 @click.option("--selector", help="Extract only the DOM subtree matching this CSS selector.")
+@tab_option
 @handle_errors
-def extract_markdown(selector):
-    """Extract the page's main content as Markdown."""
-    markdown = client_from_ctx().extract.markdown(selector)
+def extract_markdown(selector, tab_id):
+    """Extract the page's main content as Markdown from the active tab or --tab."""
+    markdown = client_from_ctx().extract.markdown(selector, tab_id)
     click.echo(markdown or "", nl=not (markdown or "").endswith("\n"))

{real_browser_cli-0.16.3 → real_browser_cli-0.16.8}/browser_cli/commands/page.py

@@ -1,5 +1,5 @@
 import click
-from browser_cli.commands import client_from_ctx, handle_errors
+from browser_cli.commands import client_from_ctx, handle_errors, tab_option
 from rich.console import Console
 from rich.table import Table
 
@@ -10,10 +10,11 @@ def page_group():
     """Inspect current page metadata."""
 
 @page_group.command("info")
+@tab_option
 @handle_errors
-def page_info():
-    """Show title, URL, readyState, language, and meta tags of the active tab."""
-    info = client_from_ctx().page.info()
+def page_info(tab_id):
+    """Show title, URL, readyState, language, and meta tags of the active tab or --tab."""
+    info = client_from_ctx().page.info(tab_id)
     table = Table(show_header=False)
     table.add_column("Field", style="bold cyan", no_wrap=True)
     table.add_column("Value")