@roxybrowser/openapi 1.0.8 → 1.0.10-beta.0

package/README.md

@@ -1,13 +1,7 @@
-# RoxyBrowser MCP Server [Beta]
+# RoxyBrowser MCP Server
 
 [English](README.md) | [中文](README_CN.md)
 
-> **⚠️ BETA VERSION NOTICE**
->
-> This project is currently in **beta testing and active development**. While we strive for stability, please exercise caution when using this tool in production environments or with critical assets. We recommend closely monitoring software and browser operations when using it with MCP clients to avoid unnecessary losses.
->
->For more details, please refer to: [RoxyBrowser Now Supports MCP — AI Can Finally Do the Work for You](https://roxybrowser.com/blog/roxybrowser-mcp-integration)
-
 A Model Context Protocol (MCP) server for [RoxyBrowser](https://www.roxybrowser.com/) that provides AI assistants with the ability to manage browser instances and obtain Chrome DevTools Protocol (CDP) WebSocket endpoints for automation.
 
 ## Features
@@ -15,7 +9,7 @@ A Model Context Protocol (MCP) server for [RoxyBrowser](https://www.roxybrowser.
 - 🚀 **Browser Management**: Open and close RoxyBrowser instances programmatically
 - 🔗 **CDP Integration**: Get WebSocket endpoints for Chrome DevTools Protocol automation
 - 🤖 **AI-Friendly**: Seamlessly integrates with AI assistants through MCP
-- 🎯 **Playwright Ready**: Works with [PlayRoxy MCP](https://github.com/roxybrowserlabs/playroxy-mcp) (RoxyBrowser's customized Playwright MCP)
+- 🎯 **Playwright Ready**: Works with [RoxyBrowser Playwright MCP](https://github.com/roxybrowserlabs/roxybrowser-playwright-mcp) (RoxyBrowser's customized Playwright MCP)
 - 📊 **Workspace Support**: Manage browsers across different workspaces and projects
 - 🛠️ **Browser Creation**: Create browsers (single or batch) with full configuration
 - 🌐 **Proxy Management**: List, create, detect, and manage proxy configurations
@@ -36,7 +30,7 @@ A Model Context Protocol (MCP) server for [RoxyBrowser](https://www.roxybrowser.
 
 ### MCP Client Configuration
 
-Add both RoxyBrowser OpenAPI and PlayRoxy MCP to your MCP client configuration:
+Add both RoxyBrowser OpenAPI and RoxyBrowser Playwright MCP to your MCP client configuration:
 
 **Claude Desktop / VS Code / Cursor:**
 ```json
@@ -60,6 +54,108 @@ Add both RoxyBrowser OpenAPI and PlayRoxy MCP to your MCP client configuration:
 
 **Note:** Replace `YOUR API KEY` and `YOUR API HOST` with your actual RoxyBrowser credentials.
 
+## Usage
+
+This package supports three ways to run: **CLI**, **in-process (programmatic)**, and **as a library** for custom integration.
+
+### 1. CLI (direct start)
+
+Start the MCP server from the command line. Ideal for MCP clients that spawn the server as a subprocess.
+
+```bash
+# After npm install -g @roxybrowser/openapi
+roxy-browser-mcp
+
+# Or with npx (no global install)
+npx @roxybrowser/openapi
+
+# After cloning and building
+npm run build && node lib/index.js
+```
+
+CLI options (config: **CLI args > environment variables > defaults**):
+
+- `-V, --version` — Show version
+- `-h, --help` — Show usage
+- `-H, --api-host <url>` — RoxyBrowser API base URL (default: `http://127.0.0.1:50000`)
+- `-k, --api-key <key>` — API key (required unless set via env)
+- `-t, --timeout <ms>` — Request timeout in milliseconds (default: `30000`)
+
+Environment variables (used when an option is not passed): `ROXY_API_HOST`, `ROXY_API_KEY`, `ROXY_TIMEOUT`.
+
+Examples:
+
+```bash
+roxy-browser-mcp --api-key "your-key"
+roxy-browser-mcp -k "your-key" -H http://127.0.0.1:50000
+ROXY_API_KEY=your-key roxy-browser-mcp
+```
+
+### 2. In-process (programmatic start)
+
+Run the MCP server inside your own Node process (same process, stdio transport). Useful when you want to start the server from code instead of a separate CLI process.
+
+```ts
+import { runServer } from '@roxybrowser/openapi'
+
+// Starts MCP server on stdio; runs until process exits
+await runServer()
+```
+
+Or use the server class for more control:
+
+```ts
+import { RoxyBrowserMCPServer } from '@roxybrowser/openapi'
+
+const server = new RoxyBrowserMCPServer()
+await server.run()
+```
+
+Set env vars (`ROXY_API_KEY`, `ROXY_API_HOST`) before calling `runServer()`; config is read at process start and cannot be changed at runtime.
+
+### 3. Library (secondary development)
+
+Use the exported tools and API helpers in your own app: call RoxyBrowser APIs without running the MCP server.
+
+```ts
+import {
+  listBrowsers,
+  openBrowser,
+  createBrowser,
+  listWorkspaces,
+  healthCheck,
+} from '@roxybrowser/openapi'
+
+// Set ROXY_API_KEY and ROXY_API_HOST (env) before any request; config is fixed at process start
+// Use tool handlers directly (same as MCP tool calls)
+const listResult = await listBrowsers.handle({ workspaceId: 1 })
+const openResult = await openBrowser.handle({
+  workspaceId: 1,
+  dirIds: ['browser-dir-id'],
+})
+const createResult = await createBrowser.handle({
+  workspaceId: 1,
+  windowName: 'My Browser',
+})
+```
+
+Each tool exports:
+
+- `.name` — Tool name (e.g. `roxy_list_browsers`)
+- `.schema` — MCP tool schema (`name`, `description`, `inputSchema`)
+- `.handle(args)` — Async handler; pass the same arguments as the MCP tool
+
+You can also use the low-level `request()` helper and types:
+
+```ts
+import { request, resolveConfig } from '@roxybrowser/openapi'
+import type { RoxyClientConfig, BrowserListItem, Workspace } from '@roxybrowser/openapi'
+
+const res = await request('/browser/list_v3?workspaceId=1', { method: 'GET' })
+```
+
+This allows you to build custom UIs, scripts, or other MCP servers that reuse RoxyBrowser logic.
+
 ## Available Tools
 
 ### Workspace
@@ -113,8 +209,8 @@ Add both RoxyBrowser OpenAPI and PlayRoxy MCP to your MCP client configuration:
    → Returns CDP WebSocket URL like: ws://127.0.0.1:52314/devtools/browser/xxx
 
 3. AI: "Navigate to gmail.com, login, and send emails"
-   → Uses PlayRoxy MCP tools (browser_navigate, browser_type, browser_click, etc.)
-   → PlayRoxy MCP connects to the opened browser via CDP endpoint
+   → Uses RoxyBrowser Playwright MCP tools (browser_navigate, browser_type, browser_click, etc.)
+   → RoxyBrowser Playwright MCP connects to the opened browser via CDP endpoint
 
 4. AI: "Close the browser when done"
    → Uses roxy_close_browsers
@@ -133,20 +229,20 @@ Add both RoxyBrowser OpenAPI and PlayRoxy MCP to your MCP client configuration:
 
 3. AI: "Open the browser and start automation"
    → Uses roxy_open_browsers → gets CDP endpoint
-   → PlayRoxy MCP connects and begins automation
+   → RoxyBrowser Playwright MCP connects and begins automation
 ```
 
 ## Integration with Playwright MCP
 
-RoxyBrowser MCP is designed to work seamlessly with [PlayRoxy MCP](https://github.com/roxybrowserlabs/playroxy-mcp), our customized Playwright MCP server built specifically for RoxyBrowser compatibility.
+RoxyBrowser MCP is designed to work seamlessly with [RoxyBrowser Playwright MCP](https://github.com/roxybrowserlabs/roxybrowser-playwright-mcp), our customized Playwright MCP server built specifically for RoxyBrowser compatibility.
 
-**PlayRoxy MCP** is based on [Microsoft's Playwright MCP](https://github.com/microsoft/playwright-mcp) with enhancements for RoxyBrowser's fingerprint browser features.
+**RoxyBrowser Playwright MCP** is based on [Microsoft's Playwright MCP](https://github.com/microsoft/playwright-mcp) with enhancements for RoxyBrowser's fingerprint browser features.
 
 ### Workflow
 
 1. Use RoxyBrowser OpenAPI MCP to create and open browsers
 2. Get CDP WebSocket endpoints from opened browsers
-3. Use PlayRoxy MCP to automate browser tasks with full Playwright capabilities
+3. Use RoxyBrowser Playwright MCP to automate browser tasks with full Playwright capabilities
 
 Both servers work together seamlessly when configured in your MCP client (see configuration above).
 
@@ -162,13 +258,17 @@ npm run build
 
 ## API Reference
 
-### Environment Variables
+### Configuration
+
+Config is resolved in this order: **CLI arguments > environment variables > defaults**.
+
+| Source | Options / Variables | Description |
+|--------|----------------------|-------------|
+| CLI | `-H, --api-host`, `-k, --api-key`, `-t, --timeout` | Pass when starting the server |
+| Env | `ROXY_API_HOST`, `ROXY_API_KEY`, `ROXY_TIMEOUT` | Used when CLI option not passed |
+| Defaults | `apiHost: http://127.0.0.1:50000`, `timeout: 30000` | Built-in defaults |
 
-| Variable | Required | Default | Description |
-|----------|----------|---------|-------------|
-| `ROXY_API_KEY` | ✅ Yes | - | API key from RoxyBrowser settings |
-| `ROXY_API_HOST` | ✅ Yes | `http://127.0.0.1:50000` | RoxyBrowser API endpoint |
-| `ROXY_TIMEOUT` | No | `30000` | Request timeout in milliseconds |
+Config is read from env only; use `resolveConfig()` to read current effective config (env + defaults).
 
 ## Troubleshooting
 

package/lib/cli.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * CLI entry: parse args (Commander), apply config (CLI > env > defaults), then run MCP server.
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/lib/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;GAEG"}

package/lib/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * CLI entry: parse args (Commander), apply config (CLI > env > defaults), then run MCP server.
+ */
+import { Command } from 'commander';
+import { runServer } from './index.js';
+import { ConfigError } from './utils/index.js';
+const PKG_VERSION = '1.0.9';
+const program = new Command();
+program
+    .name('roxy-browser-mcp')
+    .description('RoxyBrowser MCP Server - Model Context Protocol server for RoxyBrowser automation')
+    .version(PKG_VERSION, '-V, --version', 'Show version')
+    .option('-H, --api-host <url>', 'RoxyBrowser API base URL', process.env.ROXY_API_HOST ?? 'http://127.0.0.1:50000')
+    .option('-k, --api-key <key>', 'API key (or set ROXY_API_KEY)', process.env.ROXY_API_KEY ?? '')
+    .option('-t, --timeout <ms>', 'Request timeout in milliseconds', (v) => (v != null && v !== '' ? Number.parseInt(v, 10) : 30_000), process.env.ROXY_TIMEOUT != null ? Number(process.env.ROXY_TIMEOUT) : 30_000)
+    .addHelpText('after', `
+Environment (used when option not passed):
+  ROXY_API_HOST   API base URL (default: http://127.0.0.1:50000)
+  ROXY_API_KEY    API key (required)
+  ROXY_TIMEOUT    Timeout in ms (default: 30000)
+
+Examples:
+  roxy-browser-mcp --api-key "your-key"
+  roxy-browser-mcp -k "your-key" -H http://127.0.0.1:50000
+  ROXY_API_KEY=your-key roxy-browser-mcp
+`);
+async function main() {
+    program.parse();
+    const opts = program.opts();
+    // Apply CLI args to env so request() sees them (env is the only config source)
+    if (opts.apiHost != null && opts.apiHost !== '')
+        process.env.ROXY_API_HOST = opts.apiHost;
+    if (opts.apiKey != null && opts.apiKey !== '')
+        process.env.ROXY_API_KEY = opts.apiKey;
+    if (opts.timeout != null)
+        process.env.ROXY_TIMEOUT = String(opts.timeout);
+    try {
+        await runServer();
+    }
+    catch (error) {
+        if (error instanceof ConfigError) {
+            console.error(`❌ Configuration Error: ${error.message}`);
+            process.exit(1);
+        }
+        console.error('❌ Unexpected error:', error);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=cli.js.map

package/lib/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,MAAM,WAAW,GAAG,OAAO,CAAA;AAE3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAA;AAE7B,OAAO;KACJ,IAAI,CAAC,kBAAkB,CAAC;KACxB,WAAW,CAAC,mFAAmF,CAAC;KAChG,OAAO,CAAC,WAAW,EAAE,eAAe,EAAE,cAAc,CAAC;KACrD,MAAM,CACL,sBAAsB,EACtB,0BAA0B,EAC1B,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,wBAAwB,CACtD;KACA,MAAM,CACL,qBAAqB,EACrB,+BAA+B,EAC/B,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,EAAE,CAC/B;KACA,MAAM,CACL,oBAAoB,EACpB,iCAAiC,EACjC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,EACxE,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAC7E;KACA,WAAW,CACV,OAAO,EACP;;;;;;;;;;CAUH,CACE,CAAA;AAEH,KAAK,UAAU,IAAI;IACjB,OAAO,CAAC,KAAK,EAAE,CAAA;IAEf,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAwD,CAAA;IAEjF,+EAA+E;IAC/E,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,IAAI,IAAI,CAAC,OAAO,KAAK,EAAE;QAAE,OAAO,CAAC,GAAG,CAAC,aAAa,GAAG,IAAI,CAAC,OAAO,CAAA;IACzF,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,CAAC,GAAG,CAAC,YAAY,GAAG,IAAI,CAAC,MAAM,CAAA;IACrF,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI;QAAE,OAAO,CAAC,GAAG,CAAC,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;IAEzE,IAAI,CAAC;QACH,MAAM,SAAS,EAAE,CAAA;IACnB,CAAC;IACD,OAAO,KAAK,EAAE,CAAC;QACb,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,OAAO,CAAC,KAAK,CAAC,0BAA0B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAA;YACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QACjB,CAAC;QACD,OAAO,CAAC,KAAK,CAAC,qBAAqB,EAAE,KAAK,CAAC,CAAA;QAC3C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAA"}