Merge pull request #29 from co-browser/fix/Logging

Fix/logging

Author: michiosw

.env.example

@@ -5,4 +5,7 @@ CHROME_PATH=
 OPENAI_API_KEY=your-api-key-here
 
 # Set to true if you want api calls to wait for tasks to complete (default is false)
-PATIENT=false
+PATIENT=false
+
+# Set to true if you want to disable anonymous telemetry (default is false)
+ANONYMIZED_TELEMETRY=false

README.md

@@ -1,102 +1,71 @@
-# ➡️ browser-use mcp server
+# browser-use-mcp-server
+
+<div align="center">
 
 [![Twitter URL](https://img.shields.io/twitter/url/https/twitter.com/cobrowser.svg?style=social&label=Follow%20%40cobrowser)](https://x.com/cobrowser)
 [![PyPI version](https://badge.fury.io/py/browser-use-mcp-server.svg)](https://pypi.org/project/browser-use-mcp-server/)
 
-[browser-use](https://github.com/browser-use/browser-use) MCP Server with SSE +
-stdio transport
+**An MCP server that enables AI agents to control web browsers using
+[browser-use](https://github.com/browser-use/browser-use).**
 
-### Requirements
+</div>
 
-- [uv](https://github.com/astral-sh/uv)
-- [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) (for stdio)
+## Prerequisites
 
-```
-# 1. Install uv
+- [uv](https://github.com/astral-sh/uv) - Fast Python package manager
+- [Playwright](https://playwright.dev/) - Browser automation
+- [mcp-proxy](https://github.com/sparfenyuk/mcp-proxy) - Required for stdio mode
+
+```bash
+# Install prerequisites
 curl -LsSf https://astral.sh/uv/install.sh | sh
-# 2. Install mcp-proxy pypi package via uv
 uv tool install mcp-proxy
+uv tool update-shell
 ```
 
-### Quickstart
+## Environment
 
-Starting in SSE mode:
+Create a `.env` file:
 
-```bash
-uv sync
-uv pip install playwright
-uv run playwright install --with-deps --no-shell chromium
-uv run server --port 8000
+```
+OPENAI_API_KEY=your-api-key
+CHROME_PATH=optional/path/to/chrome
+PATIENT=false  # Set to true if API calls should wait for task completion
 ```
 
-With stdio mode:
+## Installation
 
 ```bash
-# Run with stdio mode and specify a proxy port
-uv run server --stdio --proxy-port 8001
-
-# Or just stdio mode (random proxy port)
-uv run server --stdio
+# Install dependencies
+uv sync
+uv pip install playwright
+uv run playwright install --with-deps --no-shell chromium
 ```
 
-- the .env requires the following:
-
-```
-OPENAI_API_KEY=[your api key]
-CHROME_PATH=[only change this if you have a custom chrome build]
-PATIENT=false # Set to true if you want api calls to wait for tasks to complete (default is false)
-```
+## Usage
 
-When building the docker image, you can use Docker secrets for VNC password:
+### SSE Mode
 
 ```bash
-# With Docker secrets (recommended for production)
-echo "your-secure-password" > vnc_password.txt
-docker run -v $(pwd)/vnc_password.txt:/run/secrets/vnc_password your-image-name
-
-# Or during development with the default password
-docker build .
+# Run directly from source
+uv run server --port 8000
 ```
 
-### Tools
+### stdio Mode
 
-- [x] SSE transport
-- [x] stdio transport (via mcp-proxy)
-- [x] browser_use - Initiates browser tasks with URL and action
-- [x] browser_get_result - Retrieves results of async browser tasks
-- [x] VNC server - stream the dockerized browser to your client
-
-### VNC
-
-the dockerfile has a vnc server with a default password of browser-use. connect
-to it:
+```bash
+# 1. Build and install globally
+uv build
+uv tool uninstall browser-use-mcp-server 2>/dev/null || true
+uv tool install dist/browser_use_mcp_server-*.whl
 
+# 2. Run with stdio transport
+browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000
 ```
-docker build -t  browser-use-mcp-server .
-docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server
-git clone https://github.com/novnc/noVNC
-cd noVNC
-./utils/novnc_proxy --vnc localhost:5900
-```
-
-<p align="center">
-<img width="428" alt="Screenshot 2025-03-24 at 12 03 15 PM" src="https://github.com/user-attachments/assets/45bc5bee-418d-4182-94f5-db84b4fc0b3a" />
-<br>
-<img width="428" alt="Screenshot 2025-03-24 at 12 11 42 PM" src="https://github.com/user-attachments/assets/7db53f41-fc00-4e48-8892-f7108096f9c4" />
-</p>
-
-### Supported Clients
-
-- cursor.ai
-- claude desktop
-- claude code
-- windsurf ([windsurf](https://codeium.com/windsurf) doesn't support SSE, only
-  stdio)
 
-#### SSE Mode
+## Client Configuration
 
-After running the server in SSE mode, add http://localhost:8000/sse to your
-client UI, or in a mcp.json file:
+### SSE Mode
 
 ```json
 {
@@ -108,20 +77,7 @@ client UI, or in a mcp.json file:
 }
 ```
 
-#### stdio Mode
-
-When running in stdio mode, the server will automatically start both the SSE
-server and mcp-proxy. The proxy handles the conversion between stdio and SSE
-protocols. No additional configuration is needed - just start your client and it
-will communicate with the server through stdin/stdout.
-
-Install the cli
-
-```bash
-uv pip install -e .
-```
-
-And then e.g., in Windsurf, paste:
+### stdio Mode
 
 ```json
 {
@@ -136,41 +92,115 @@ And then e.g., in Windsurf, paste:
         "--stdio",
         "--proxy-port",
         "9000"
-      ]
+      ],
+      "env": {
+        "OPENAI_API_KEY": "your-api-key"
+      }
     }
   }
 }
 ```
 
-### Client Configuration Paths
+### Config Locations
+
+| Client           | Configuration Path                                                |
+| ---------------- | ----------------------------------------------------------------- |
+| Cursor           | `./.cursor/mcp.json`                                              |
+| Windsurf         | `~/.codeium/windsurf/mcp_config.json`                             |
+| Claude (Mac)     | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude (Windows) | `%APPDATA%\Claude\claude_desktop_config.json`                     |
+
+## Features
+
+- [x] **Browser Automation**: Control browsers through AI agents
+- [x] **Dual Transport**: Support for both SSE and stdio protocols
+- [x] **VNC Streaming**: Watch browser automation in real-time
+- [x] **Async Tasks**: Execute browser operations asynchronously
+
+## Local Development
+
+To develop and test the package locally:
+
+1. Build a distributable wheel:
+
+   ```bash
+   # From the project root directory
+   uv build
+   ```
+
+2. Install it as a global tool:
+
+   ```bash
+   uv tool uninstall browser-use-mcp-server 2>/dev/null || true
+   uv tool install dist/browser_use_mcp_server-*.whl
+   ```
 
-#### Cursor
+3. Run from any directory:
 
-- `./.cursor/mcp.json`
+   ```bash
+   # Set your OpenAI API key for the current session
+   export OPENAI_API_KEY=your-api-key-here
 
-#### Windsurf
+   # Or provide it inline for a one-time run
+   OPENAI_API_KEY=your-api-key-here browser-use-mcp-server run server --port 8000 --stdio --proxy-port 9000
+   ```
 
-- `~/.codeium/windsurf/mcp_config.json`
+4. After making changes, rebuild and reinstall:
+   ```bash
+   uv build
+   uv tool uninstall browser-use-mcp-server
+   uv tool install dist/browser_use_mcp_server-*.whl
+   ```
 
-#### Claude
+## Docker
 
-- `~/Library/Application Support/Claude/claude_desktop_config.json`
-- `%APPDATA%\Claude\claude_desktop_config.json`
+```bash
+# Run with default VNC password
+docker build -t browser-use-mcp-server .
+docker run --rm -p8000:8000 -p5900:5900 browser-use-mcp-server
 
-### Example Usage
+# Use custom VNC password
+echo "your-password" > vnc_password.txt
+docker run --rm -p8000:8000 -p5900:5900 \
+  -v $(pwd)/vnc_password.txt:/run/secrets/vnc_password \
+  browser-use-mcp-server
+```
 
-Try asking your LLM the following:
+### VNC Viewer
 
-`open https://news.ycombinator.com and return the top ranked article`
+```bash
+# Browser-based viewer
+git clone https://github.com/novnc/noVNC
+cd noVNC
+./utils/novnc_proxy --vnc localhost:5900
+```
+
+Default password: `browser-use`
+
+<div align="center">
+  <img width="428" alt="VNC Screenshot" src="https://github.com/user-attachments/assets/45bc5bee-418d-4182-94f5-db84b4fc0b3a" />
+  <br><br>
+  <img width="428" alt="VNC Screenshot" src="https://github.com/user-attachments/assets/7db53f41-fc00-4e48-8892-f7108096f9c4" />
+</div>
+
+## Example
+
+Try asking your AI:
+
+```
+open https://news.ycombinator.com and return the top ranked article
+```
 
-### Help
+## Support
 
-for issues or interest reach out @ https://cobrowser.xyz
+For issues or inquiries: [cobrowser.xyz](https://cobrowser.xyz)
 
-# Stars
+## Star History
 
-<picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date&theme=dark" />
-  <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
-  <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
-</picture>
+<div align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date&theme=dark" />
+    <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
+    <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=co-browser/browser-use-mcp-server&type=Date" />
+  </picture>
+</div>

pyproject.toml

@@ -25,6 +25,7 @@ dependencies = [
     "pydantic>=2.10.6",
     "anyio",
     "python-dotenv",
+    "python-json-logger>=2.0.7",
     "starlette",
     "uvicorn",
     "playwright>=1.50.0",
@@ -72,7 +73,8 @@ disallow_incomplete_defs = true
 browser-use-mcp-server = "browser_use_mcp_server.cli:cli"
 
 [tool.hatch.build]
-packages = ["src/browser_use_mcp_server"]
+packages = ["src", "server"]
+include = ["server"]
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/browser_use_mcp_server"]
+packages = ["src/browser_use_mcp_server", "server"]