@roxybrowser/openapi 1.0.9 → 1.0.10-beta.1

package/README.md

@@ -54,6 +54,108 @@ Add both RoxyBrowser OpenAPI and RoxyBrowser Playwright MCP to your MCP client c
 
 **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
@@ -156,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"}