@olib-ai/owl-browser-mcp 1.0.0 → 1.0.2

package/README.md

@@ -39,18 +39,39 @@ npm install
 npm run build
 ```
 
+## Architecture: Understanding Ports
+
+The Owl Browser exposes two ports with different purposes:
+
+| Port | Service | Description |
+|------|---------|-------------|
+| **80** | Nginx Proxy | Web control panel + API gateway. **Recommended for Docker deployments.** Routes `/api/*`, `/execute/*`, `/ws` to the HTTP server. |
+| **8080** | HTTP Server | Direct REST API access. Use for standalone (non-Docker) deployments or debugging. |
+
+**Important:** When using Docker, connect to **port 80** (nginx), not port 8080. The nginx proxy handles routing, authentication, and serves the web control panel.
+
+```
+┌─────────────────┐         ┌─────────────────────────────────────┐
+│   MCP Server    │         │           Docker Container          │
+│                 │  HTTP   │  ┌─────────┐      ┌──────────────┐  │
+│ OWL_API_ENDPOINT├────────►│  │  Nginx  │─────►│ HTTP Server  │  │
+│ = localhost:80  │         │  │ (port 80)│      │ (port 8080)  │  │
+└─────────────────┘         │  └─────────┘      └──────────────┘  │
+                            └─────────────────────────────────────┘
+```
+
 ## Configuration
 
 Set environment variables before running:
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `OWL_API_ENDPOINT` | HTTP API endpoint URL | `http://127.0.0.1:8080` |
-| `OWL_API_TOKEN` | Bearer token for authentication | (none) |
+| `OWL_API_ENDPOINT` | HTTP API endpoint URL | `http://127.0.0.1:80` |
+| `OWL_API_TOKEN` | Bearer token for authentication (same as `OWL_HTTP_TOKEN` in Docker) | (none) |
 
-## Usage with Claude Desktop
+## Usage with Docker (Recommended)
 
-Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+When using the Owl Browser Docker image, connect to **port 80** (nginx proxy):
 
 ```json
 {
@@ -59,7 +80,24 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
       "command": "npx",
       "args": ["-y", "@olib-ai/owl-browser-mcp"],
       "env": {
-        "OWL_API_ENDPOINT": "http://127.0.0.1:8080",
+        "OWL_API_ENDPOINT": "http://localhost:80",
+        "OWL_API_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+Or if Docker is running on a remote host:
+
+```json
+{
+  "mcpServers": {
+    "owl-browser": {
+      "command": "npx",
+      "args": ["-y", "@olib-ai/owl-browser-mcp"],
+      "env": {
+        "OWL_API_ENDPOINT": "http://your-docker-host:80",
         "OWL_API_TOKEN": "your-api-token"
       }
     }
@@ -67,9 +105,13 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
 }
 ```
 
-## Usage with Docker
+**Note:** The `OWL_API_TOKEN` must match the `OWL_HTTP_TOKEN` environment variable set when starting the Docker container.
+
+## Usage with Standalone HTTP Server
 
-When using the Owl Browser Docker image:
+If running the HTTP server directly (without Docker/nginx), connect to **port 8080**:
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
 ```json
 {
@@ -78,8 +120,8 @@ When using the Owl Browser Docker image:
       "command": "npx",
       "args": ["-y", "@olib-ai/owl-browser-mcp"],
       "env": {
-        "OWL_API_ENDPOINT": "http://your-docker-host",
-        "OWL_API_TOKEN": "your-docker-token"
+        "OWL_API_ENDPOINT": "http://127.0.0.1:8080",
+        "OWL_API_TOKEN": "your-api-token"
       }
     }
   }
@@ -97,7 +139,7 @@ If running from source instead of npm:
       "command": "node",
       "args": ["/path/to/mcp-server/dist/index.js"],
       "env": {
-        "OWL_API_ENDPOINT": "http://127.0.0.1:8080",
+        "OWL_API_ENDPOINT": "http://127.0.0.1:80",
         "OWL_API_TOKEN": "your-api-token"
       }
     }
@@ -151,21 +193,21 @@ Use the official MCP Inspector to test the server interactively.
 ```bash
 cd mcp-server
 
-# Basic usage (default endpoint http://127.0.0.1:8080)
+# With Docker container (connect to nginx on port 80)
 npx @modelcontextprotocol/inspector \
-  -e OWL_API_ENDPOINT=http://127.0.0.1:8080 \
-  -e OWL_API_TOKEN=your-token \
+  -e OWL_API_ENDPOINT=http://localhost:80 \
+  -e OWL_API_TOKEN=your-docker-token \
   node dist/index.js
 
-# With Docker container endpoint
+# With standalone HTTP server (connect directly to port 8080)
 npx @modelcontextprotocol/inspector \
-  -e OWL_API_ENDPOINT=http://localhost:8080 \
-  -e OWL_API_TOKEN=your-docker-token \
+  -e OWL_API_ENDPOINT=http://127.0.0.1:8080 \
+  -e OWL_API_TOKEN=your-token \
   node dist/index.js
 
-# With remote server
+# With remote Docker server
 npx @modelcontextprotocol/inspector \
-  -e OWL_API_ENDPOINT=https://your-server.com \
+  -e OWL_API_ENDPOINT=http://your-server.com:80 \
   -e OWL_API_TOKEN=your-api-token \
   node dist/index.js
 ```

package/dist/index.js

@@ -22297,6 +22297,10 @@ var openapi_default = {
                   selector: {
                     type: "string",
                     description: "CSS selector or natural language description for the element to capture. Required when mode is 'element'. Examples: 'div.profile', '#submit-btn', 'the login form'"
+                  },
+                  scale: {
+                    type: "integer",
+                    description: "Scale percentage for the output image (1-100). Default is 100 (no scaling). Example: 50 will return an image at 50% of the original size (half width and height)."
                   }
                 },
                 required: [
@@ -26917,6 +26921,35 @@ function formatResponse(toolName, result) {
     };
   }
   const data = result.data;
+  const isImageTool = toolName === "browser_screenshot" || toolName === "browser_get_live_frame";
+  if (isImageTool) {
+    let base64Data = null;
+    if (typeof data === "object" && data !== null) {
+      const dataObj = data;
+      if (typeof dataObj.result === "string") {
+        base64Data = dataObj.result;
+      } else if (typeof dataObj.success === "boolean" && typeof dataObj.result === "string") {
+        base64Data = dataObj.result;
+      }
+    } else if (typeof data === "string") {
+      base64Data = data;
+    }
+    if (base64Data) {
+      if (base64Data.startsWith("data:image/")) {
+        const [, actualBase64] = base64Data.split(",");
+        base64Data = actualBase64;
+      }
+      return {
+        content: [
+          {
+            type: "image",
+            data: base64Data,
+            mimeType: "image/png"
+          }
+        ]
+      };
+    }
+  }
   if (typeof data === "object" && data !== null && "image" in data) {
     const imageData = data.image;
     if (imageData.startsWith("data:image/")) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olib-ai/owl-browser-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "MCP server for Owl Browser HTTP API - 144 browser automation tools with anti-detection",
   "type": "module",
   "main": "dist/index.js",