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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +60 -18
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -39,18 +39,39 @@ npm install
39
39
  npm run build
40
40
  ```
41
41
 
42
+ ## Architecture: Understanding Ports
43
+
44
+ The Owl Browser exposes two ports with different purposes:
45
+
46
+ | Port | Service | Description |
47
+ |------|---------|-------------|
48
+ | **80** | Nginx Proxy | Web control panel + API gateway. **Recommended for Docker deployments.** Routes `/api/*`, `/execute/*`, `/ws` to the HTTP server. |
49
+ | **8080** | HTTP Server | Direct REST API access. Use for standalone (non-Docker) deployments or debugging. |
50
+
51
+ **Important:** When using Docker, connect to **port 80** (nginx), not port 8080. The nginx proxy handles routing, authentication, and serves the web control panel.
52
+
53
+ ```
54
+ ┌─────────────────┐ ┌─────────────────────────────────────┐
55
+ │ MCP Server │ │ Docker Container │
56
+ │ │ HTTP │ ┌─────────┐ ┌──────────────┐ │
57
+ │ OWL_API_ENDPOINT├────────►│ │ Nginx │─────►│ HTTP Server │ │
58
+ │ = localhost:80 │ │ │ (port 80)│ │ (port 8080) │ │
59
+ └─────────────────┘ │ └─────────┘ └──────────────┘ │
60
+ └─────────────────────────────────────┘
61
+ ```
62
+
42
63
  ## Configuration
43
64
 
44
65
  Set environment variables before running:
45
66
 
46
67
  | Variable | Description | Default |
47
68
  |----------|-------------|---------|
48
- | `OWL_API_ENDPOINT` | HTTP API endpoint URL | `http://127.0.0.1:8080` |
49
- | `OWL_API_TOKEN` | Bearer token for authentication | (none) |
69
+ | `OWL_API_ENDPOINT` | HTTP API endpoint URL | `http://127.0.0.1:80` |
70
+ | `OWL_API_TOKEN` | Bearer token for authentication (same as `OWL_HTTP_TOKEN` in Docker) | (none) |
50
71
 
51
- ## Usage with Claude Desktop
72
+ ## Usage with Docker (Recommended)
52
73
 
53
- Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
74
+ When using the Owl Browser Docker image, connect to **port 80** (nginx proxy):
54
75
 
55
76
  ```json
56
77
  {
@@ -59,7 +80,24 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
59
80
  "command": "npx",
60
81
  "args": ["-y", "@olib-ai/owl-browser-mcp"],
61
82
  "env": {
62
- "OWL_API_ENDPOINT": "http://127.0.0.1:8080",
83
+ "OWL_API_ENDPOINT": "http://localhost:80",
84
+ "OWL_API_TOKEN": "your-api-token"
85
+ }
86
+ }
87
+ }
88
+ }
89
+ ```
90
+
91
+ Or if Docker is running on a remote host:
92
+
93
+ ```json
94
+ {
95
+ "mcpServers": {
96
+ "owl-browser": {
97
+ "command": "npx",
98
+ "args": ["-y", "@olib-ai/owl-browser-mcp"],
99
+ "env": {
100
+ "OWL_API_ENDPOINT": "http://your-docker-host:80",
63
101
  "OWL_API_TOKEN": "your-api-token"
64
102
  }
65
103
  }
@@ -67,9 +105,13 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
67
105
  }
68
106
  ```
69
107
 
70
- ## Usage with Docker
108
+ **Note:** The `OWL_API_TOKEN` must match the `OWL_HTTP_TOKEN` environment variable set when starting the Docker container.
109
+
110
+ ## Usage with Standalone HTTP Server
71
111
 
72
- When using the Owl Browser Docker image:
112
+ If running the HTTP server directly (without Docker/nginx), connect to **port 8080**:
113
+
114
+ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
73
115
 
74
116
  ```json
75
117
  {
@@ -78,8 +120,8 @@ When using the Owl Browser Docker image:
78
120
  "command": "npx",
79
121
  "args": ["-y", "@olib-ai/owl-browser-mcp"],
80
122
  "env": {
81
- "OWL_API_ENDPOINT": "http://your-docker-host",
82
- "OWL_API_TOKEN": "your-docker-token"
123
+ "OWL_API_ENDPOINT": "http://127.0.0.1:8080",
124
+ "OWL_API_TOKEN": "your-api-token"
83
125
  }
84
126
  }
85
127
  }
@@ -97,7 +139,7 @@ If running from source instead of npm:
97
139
  "command": "node",
98
140
  "args": ["/path/to/mcp-server/dist/index.js"],
99
141
  "env": {
100
- "OWL_API_ENDPOINT": "http://127.0.0.1:8080",
142
+ "OWL_API_ENDPOINT": "http://127.0.0.1:80",
101
143
  "OWL_API_TOKEN": "your-api-token"
102
144
  }
103
145
  }
@@ -151,21 +193,21 @@ Use the official MCP Inspector to test the server interactively.
151
193
  ```bash
152
194
  cd mcp-server
153
195
 
154
- # Basic usage (default endpoint http://127.0.0.1:8080)
196
+ # With Docker container (connect to nginx on port 80)
155
197
  npx @modelcontextprotocol/inspector \
156
- -e OWL_API_ENDPOINT=http://127.0.0.1:8080 \
157
- -e OWL_API_TOKEN=your-token \
198
+ -e OWL_API_ENDPOINT=http://localhost:80 \
199
+ -e OWL_API_TOKEN=your-docker-token \
158
200
  node dist/index.js
159
201
 
160
- # With Docker container endpoint
202
+ # With standalone HTTP server (connect directly to port 8080)
161
203
  npx @modelcontextprotocol/inspector \
162
- -e OWL_API_ENDPOINT=http://localhost:8080 \
163
- -e OWL_API_TOKEN=your-docker-token \
204
+ -e OWL_API_ENDPOINT=http://127.0.0.1:8080 \
205
+ -e OWL_API_TOKEN=your-token \
164
206
  node dist/index.js
165
207
 
166
- # With remote server
208
+ # With remote Docker server
167
209
  npx @modelcontextprotocol/inspector \
168
- -e OWL_API_ENDPOINT=https://your-server.com \
210
+ -e OWL_API_ENDPOINT=http://your-server.com:80 \
169
211
  -e OWL_API_TOKEN=your-api-token \
170
212
  node dist/index.js
171
213
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@olib-ai/owl-browser-mcp",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "MCP server for Owl Browser HTTP API - 144 browser automation tools with anti-detection",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",