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

{real_browser_cli-0.16.4 → 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.4 → 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.4
+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`.
 

{real_browser_cli-0.16.4 → 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`.
 

{real_browser_cli-0.16.4 → 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 = []
@@ -249,18 +253,17 @@ def collect_browser_clients(
     if targets:
       uncached = []
       for target in targets:
-        cached = _cached_client_row(target)
+        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.display_name,
+          t.profile,
           profile=t.profile,
           remote=remote,
           key=key,
-          profile_group=t.display_group,
         ))
         for t in uncached
       ])

{real_browser_cli-0.16.4 → 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.4 → 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.4 → 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")

real_browser_cli-0.16.8/browser_cli/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""Stateless Model Context Protocol adapter for browser-cli."""
+
+from browser_cli.mcp.server import create_server, main
+
+__all__ = ["create_server", "main"]

real_browser_cli-0.16.8/browser_cli/mcp/naming.py

@@ -0,0 +1,39 @@
+"""Tool-name prefixing for the MCP surface.
+
+Hosts differ in how they namespace MCP tools. Hosts that already prefix tool
+names with the server name turn the built-in ``browser_`` prefix into stutter
+(``browser_cli_testing_browser_tabs_list``), while hosts that expose raw names
+need the prefix to keep ``navigate`` or ``screenshot`` unambiguous. The prefix
+is therefore configurable per MCP server process.
+"""
+from __future__ import annotations
+
+import os
+import re
+
+TOOL_PREFIX_ENV = "BROWSER_CLI_MCP_TOOL_PREFIX"
+DEFAULT_TOOL_PREFIX = "browser_"
+
+_VALID_PREFIX = re.compile(r"\A[a-z][a-z0-9_]*\Z")
+
+def resolve_tool_prefix(environ: dict[str, str] | None = None) -> str:
+  """Return the configured tool-name prefix, defaulting to ``browser_``.
+
+  An empty value disables prefixing for hosts that namespace tools themselves.
+  """
+  configured = (environ if environ is not None else os.environ).get(TOOL_PREFIX_ENV)
+  if configured is None:
+    return DEFAULT_TOOL_PREFIX
+  prefix = configured.strip()
+  if not prefix:
+    return ""
+  if not _VALID_PREFIX.match(prefix):
+    raise ValueError(
+      f"{TOOL_PREFIX_ENV} must be lowercase letters, digits, and underscores starting "
+      f"with a letter, or empty to disable prefixing; got {configured!r}"
+    )
+  return prefix if prefix.endswith("_") else f"{prefix}_"
+
+def tool_name(base: str, prefix: str) -> str:
+  """Apply *prefix* to a bare tool name such as ``tabs_list``."""
+  return f"{prefix}{base}"

real_browser_cli-0.16.8/browser_cli/mcp/serialization.py

@@ -0,0 +1,19 @@
+"""Convert browser-cli SDK models into MCP structured-output values."""
+from __future__ import annotations
+
+from dataclasses import fields, is_dataclass
+from typing import Any
+
+def structured(value: Any) -> Any:
+  """Return JSON-compatible data without private SDK binding fields."""
+  if is_dataclass(value) and not isinstance(value, type):
+    return {
+      field.name: structured(getattr(value, field.name))
+      for field in fields(value)
+      if not field.name.startswith("_")
+    }
+  if isinstance(value, dict):
+    return {str(key): structured(item) for key, item in value.items()}
+  if isinstance(value, (list, tuple, set)):
+    return [structured(item) for item in value]
+  return value