poke-browser 0.2.9 → 0.3.0

package/README.md

@@ -1,60 +1,92 @@
-# poke-browser-mcp
+# poke-browser
 
-Node process that implements an **MCP server** (stdio) and a **WebSocket server** (localhost) used by the **poke-browser** Chrome extension.
+Control Chrome from MCP clients with one command.
 
-## Role in the stack
+`poke-browser` runs an MCP server and bridges commands to the `poke-browser` Chrome extension over localhost WebSocket. It supports stdio MCP, HTTP MCP, and optional Poke tunnel mode for remote access.
 
-1. **WebSocket (extension → this process)**  
-   The extension connects to `ws://127.0.0.1:<port>`. This package listens on that port (default **9009**). When a new client connects, any previous client is closed so only one browser session is attached at a time.
+## Fast start
 
-2. **JSON commands**  
-   The server sends messages shaped like:
+Use without install:
 
-   ```json
-   { "type": "command", "id": "<uuid>", "command": "navigate", "payload": { "url": "https://example.com" } }
-   ```
-
-   The extension replies with:
-
-   ```json
-   { "type": "response", "id": "<uuid>", "ok": true, "result": { } }
-   ```
-
-   or `ok: false` and an `error` string.
+```bash
+npx poke-browser@latest
+```
 
-   On connect, the extension may send `{ "type": "hello", "client": "poke-browser-extension", "version": "..." }` for logging only.
+Or install as a dependency:
 
-3. **MCP (AI client → this process)**  
-   The official `@modelcontextprotocol/sdk` exposes tools (`list_tabs`, `get_active_tab`, `navigate`, `click`, `screenshot`, `evaluate_js`, `new_tab`, `close_tab`). Each tool forwards to the extension over the WebSocket and returns JSON text in the MCP result.
+```bash
+npm install poke-browser
+```
 
-## Configuration
+## Extension setup
+
+1. Start the launcher: `npx poke-browser@latest`
+2. Open `chrome://extensions`
+3. Enable Developer mode
+4. Click **Load unpacked**
+5. Select this repo's `extension` folder
+6. Confirm the extension popup is connected
+
+## How it works
+
+```mermaid
+flowchart LR
+  A[AI client<br/>Cursor / Claude Desktop / Inspector] -->|MCP stdio or HTTP| B[poke-browser process]
+  B -->|MCP tool calls| C[Tool router]
+  C -->|JSON command| D[WebSocket bridge<br/>ws://127.0.0.1:POKE_BROWSER_WS_PORT]
+  D -->|command payload| E[Chrome extension]
+  E -->|browser action + result| D
+  D -->|tool result| C
+  C -->|MCP response| A
+  B -->|optional --tunnel| F[npx poke@latest tunnel]
+  F -->|public MCP endpoint| A
+```
 
-| Variable | Default | Meaning |
-|----------|---------|---------|
-| `POKE_BROWSER_WS_PORT` | `9009` | WebSocket listen port (`WS_PORT` is also read as a fallback) |
+MCP JSON-RPC stays on stdout, while operational logs are written to stderr.
 
-The Chrome extension stores its target port in `chrome.storage.local` (`wsPort`); keep it aligned with this value.
+## Usage
 
-## Scripts
+```bash
+poke-browser                 # auto mode: tunnel in interactive terminals, stdio when piped
+poke-browser --stdio         # force stdio MCP mode
+poke-browser --http 8755     # MCP over HTTP at 127.0.0.1:8755/mcp
+poke-browser --tunnel 8755   # HTTP MCP + npx poke@latest tunnel
+poke-browser -n my-agent     # custom tunnel label + MCP server name
+poke-browser --name my-agent # same as -n
+poke-browser -y              # compatibility no-op for shared launcher contract
+poke-browser --debug         # verbose logs
+```
 
-| Command | Description |
-|---------|-------------|
-| `npm start` | Run `index.ts` with `tsx` (stdio MCP + WebSocket) |
-| `npm run build` | Emit JavaScript to `dist/` |
-| `npm run serve` | Run `node dist/index.js` |
+## Configuration
 
-## Dependencies
+| Variable | Default | Description |
+| --- | --- | --- |
+| `POKE_BROWSER_WS_PORT` | `9009` | Extension WebSocket port |
+| `POKE_BROWSER_MCP_PORT` | `8755` | HTTP MCP port (`--http` / `--tunnel`) |
+| `POKE_BROWSER_PORT` | `8755` | Alias for `POKE_BROWSER_MCP_PORT` |
+| `POKE_BROWSER_TUNNEL_NAME` | `poke-browser` | Label for `poke tunnel -n` |
+| `POKE_BROWSER_MCP_SERVER_NAME` | `poke-browser-mcp` | MCP initialize server name |
+| `POKE_BROWSER_SKIP_POKE_LOGIN` | unset | Set to `1` to skip `poke whoami/login` preflight |
+| `POKE_BROWSER_YES` | unset | Set when `-y/--yes` is passed (compatibility marker) |
 
-- `@modelcontextprotocol/sdk` — MCP server over stdio  
-- `ws` — WebSocket server for the extension  
-- `zod` — tool input schemas (peer-style dependency of the SDK)
+Keep the extension popup WebSocket target aligned with `POKE_BROWSER_WS_PORT`.
 
-## Development
+## Local development
 
-Typecheck:
+```bash
+npm install
+npm run build
+npm test
+npm start
+```
 
 ```bash
 npx tsc --noEmit
+npm run inspector
 ```
 
-The server logs WebSocket lifecycle messages on **stderr** so stdio **stdout** stays clean for MCP JSON-RPC.
+## Troubleshooting
+
+- **No browser connected:** verify the extension is loaded and uses the same WebSocket port.
+- **Port already in use:** change `POKE_BROWSER_WS_PORT` or `POKE_BROWSER_MCP_PORT`.
+- **Tunnel login fails:** run `npx poke@latest login` and retry.

package/cli.mjs

@@ -58,6 +58,7 @@ const entry = join(root, "dist", "index.js");
 const rawArgs = process.argv.slice(2);
 const verboseCli =
   rawArgs.includes("--debug") || rawArgs.includes("--verbose");
+const autoYes = rawArgs.includes("-y") || rawArgs.includes("--yes");
 
 /** Same shape as @leokok/poke-agents `argAfter` (used there for `--mcp-name`). */
 function argAfter(flag) {
@@ -78,8 +79,8 @@ function slugifyMcpServerName(s) {
   return t.length > 64 ? t.slice(0, 64) : t;
 }
 
-/** Custom Poke tunnel `-n` label + MCP `initialize` server name (when `--name` is passed). */
-const customMcpName = argAfter("--name");
+/** Custom Poke tunnel `-n` label + MCP `initialize` server name. */
+const customMcpName = argAfter("--name") ?? argAfter("-n");
 
 const color =
   output.isTTY && !process.env.NO_COLOR
@@ -169,29 +170,13 @@ function printQuietStartupBanner({
   console.error("");
   console.error(
     customMcpName
-      ? `  poke-browser v${VERSION} (as '${customMcpName}')`
-      : `  poke-browser v${VERSION}`,
+      ? `  Poke 🌴 / Browser v${VERSION} (as "${customMcpName}")`
+      : `  Poke 🌴 / Browser v${VERSION}`,
   );
+  console.error(`  ${color.dim("Quick start:")} keep this running, then use your MCP client.`);
+  console.error(`  ${color.dim("Guide: https://github.com/leoakok/poke-browser")}`);
+  console.error(`  ${color.dim("Load extension folder:")} ${extPath}`);
   console.error("");
-  console.error("  Load the Chrome extension:");
-  console.error("");
-  console.error("  1. Open chrome://extensions");
-  console.error("");
-  console.error("  2. Enable Developer Mode");
-  console.error("");
-  console.error("  3. Click Load unpacked \u2192 select the /extension folder");
-  console.error(
-    color.grey(
-      "     (NOT the root \u2014 open poke-browser/extension specifically)",
-    ),
-  );
-  console.error(color.dim(`     ${extPath}`));
-  console.error("");
-  console.error("  4. Extension auto-connects to this server");
-  console.error("");
-  console.error("  \u2605 Star us: https://github.com/leoakok/poke-browser");
-  console.error("");
-  console.error("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
   if (showMcpLine) {
     console.error(
       `  Local MCP:  http://127.0.0.1:${mcpPort}/mcp${mcpAuto}`,
@@ -212,38 +197,23 @@ function childEnv() {
 }
 
 if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
-  console.error(`poke-browser \u2014 MCP server for the poke-browser Chrome extension
+  console.error(`Poke 🌴 / Browser
 
 Usage:
-  poke-browser                    Poke tunnel mode when run in a terminal (default)
-  poke-browser --poke-tunnel      Same as above (explicit)
-  poke-browser --stdio            Force stdio MCP mode (Cursor, Claude Desktop, etc.)
-  poke-browser --http [port]      Streamable HTTP MCP on 127.0.0.1 (default: env POKE_BROWSER_MCP_PORT or 8755)
-  poke-browser --tunnel [port]    Same as --http, then: npx poke@latest tunnel \u2026/mcp
-  poke-browser --name <label>     Poke tunnel -n label and MCP server id
-  poke-browser --debug            Verbose stderr ([poke-browser], WebSocket port, MCP debug)
-  poke-browser --verbose          Same as --debug
-
-Mode selection (first match wins):
-  - stdin is NOT a TTY (piped)    \u2192 stdio mode  (Cursor / Claude Desktop auto-detection)
-  - --http or --stdio flag        \u2192 explicit HTTP / stdio mode
-  - interactive terminal          \u2192 poke-tunnel mode (shows public URL)
-
-Poke auth (tunnel flows):
-  Uses the global Poke CLI \u2014 same as @leokok/poke-apple-music:
-    npx poke@latest whoami    # must succeed before tunnel
-    npx poke@latest login     # browser login if needed
-  Optional: POKE_BROWSER_SKIP_POKE_LOGIN=1 to skip the whoami/login gate.
-
-Environment:
-  POKE_BROWSER_WS_PORT          WebSocket port for the extension (default 9009)
-  POKE_BROWSER_MCP_PORT       HTTP MCP listen port for --http / tunnel (default 8755)
-  POKE_BROWSER_PORT             Alias for HTTP MCP port (same as run.ts)
-  POKE_BROWSER_TUNNEL_NAME      poke tunnel -n label (default: poke-browser; --name overrides)
-  POKE_BROWSER_MCP_SERVER_NAME  MCP initialize server name slug (set from --name when passed)
-
-Build once (or pass --build):
-  npm run build
+  poke-browser [--stdio|--http PORT|--tunnel PORT] [-n NAME] [-y]
+
+Options:
+  -h, --help          show help
+  -v, --version       show version
+  -y, --yes           compatibility no-op
+  -n, --name NAME     tunnel label + MCP server name
+  --stdio             force stdio MCP mode
+  --http [port]       local HTTP MCP mode
+  --tunnel [port]     HTTP MCP + poke tunnel
+  --debug             verbose logs
+
+Guide:
+  https://github.com/leoakok/poke-browser
 `);
   process.exit(0);
 }
@@ -253,6 +223,11 @@ if (rawArgs.includes("--version") || rawArgs.includes("-v")) {
   process.exit(0);
 }
 
+if (autoYes) {
+  // Kept intentionally as a no-op to align launcher interfaces across poke CLIs.
+  process.env.POKE_BROWSER_YES = "1";
+}
+
 const wantBuild = rawArgs.includes("--build");
 
 /**
@@ -285,11 +260,14 @@ const childArgs = rawArgs.filter((a, i, arr) => {
     a === "--stdio" ||
     a === "--debug" ||
     a === "--verbose" ||
-    a === "--name"
+    a === "--name" ||
+    a === "-n" ||
+    a === "--yes" ||
+    a === "-y"
   ) {
     return false;
   }
-  if (i > 0 && arr[i - 1] === "--name") return false;
+  if (i > 0 && (arr[i - 1] === "--name" || arr[i - 1] === "-n")) return false;
   return true;
 });
 
@@ -405,16 +383,9 @@ if (!existsSync(entry)) {
       });
       const current = pkg.version;
       if (latest && latest !== current) {
-        console.log(
-          "\x1b[33m  \u26a1 Update available: v" +
-            latest +
-            " (you have v" +
-            current +
-            ")\x1b[0m",
-        );
-        console.log(
-          "\x1b[90m     npx poke-browser@latest\x1b[0m\n",
-        );
+        console.error(`  ${color.red("New version available:")} poke-browser@${latest}`);
+        console.error(`  ${color.dim("Run: npx poke-browser@latest")}`);
+        console.error("");
       }
     } catch {}
   })();

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "poke-browser",
-  "version": "0.2.9",
+  "version": "0.3.0",
   "description": "MCP server + WebSocket bridge for the poke-browser Chrome extension",
   "type": "module",
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "bin": {
     "poke-browser": "./cli.mjs"
@@ -32,8 +32,14 @@
   "keywords": [
     "poke",
     "mcp",
+    "cli",
+    "launcher",
+    "mcp-server",
+    "model-context-protocol",
     "browser",
     "chrome",
+    "chrome-extension",
+    "ai",
     "automation"
   ],
   "license": "MIT",
@@ -42,13 +48,21 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "poke": "^0.4.2",
     "ws": "^8.18.1",
     "zod": "^3.24.2"
   },
   "devDependencies": {
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.0",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.1",
     "@types/express": "^5.0.0",
     "@types/node": "^22.13.10",
     "@types/ws": "^8.18.1",
+    "semantic-release": "^24.2.0",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
     "vitest": "^3.0.9"