effing-use 0.1.0 → 0.1.1

package/README.md

@@ -1,20 +1,37 @@
 # effing-use — stop paying 19.5 KB every session for browser control
 
+[![npm version](https://img.shields.io/npm/v/effing-use)](https://www.npmjs.com/package/effing-use) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) [![Bun](https://img.shields.io/badge/runtime-Bun%201.4%2B-black?logo=bun)](https://bun.sh)
+
 Full Chromium automation in **3 tools, 3.9 KB**. Same pages, same clicks, same scrapes — without the 24-tool handshake eating your context window before you load a page.
 
 **Measured, not marketed:** `tools/list` is **3,913 bytes** here vs **19,517 bytes** for `@playwright/mcp@latest` (~5x smaller, ~15.6 KB saved every session). Local ops stay in milliseconds — snapshot ~15 ms, extract ~50 ms, batch ~65 ms, screenshot ~60–190 ms. Page loads still cost seconds (network, not us). Full numbers in [`docs/COMPARISON.md`](docs/COMPARISON.md).
 
 ## Install (Bun-only)
 
-Requires [Bun](https://bun.sh) 1.4+. The `playwright` npm package ships the driver, **not** the browser — every user needs Playwright's version-pinned Chromium (~150 MB) once:
+Requires [Bun](https://bun.sh) 1.4+. Installs from npm in seconds — the tarball is ~16 kB ([`effing-use` v0.1.1](https://www.npmjs.com/package/effing-use)):
+
+```bash
+# No install needed — bunx fetches from npm on first run
+bunx effing-use               # STDIO (single editor) — runs src/index.ts via bin
+bunx effing-use-http          # HTTP on :3123 (/mcp) — shared across editors
+bunx playwright install chromium --only-shell   # one-time Chromium download (~150 MB)
+```
+
+Optional — install globally so `effing-use` is on your PATH:
+
+```bash
+bun install -g effing-use
+effing-use                    # STDIO
+effing-use-http               # HTTP on :3123 (/mcp)
+```
+
+The `playwright` npm package ships the driver, **not** the browser — every user needs Playwright's version-pinned Chromium once. From source instead:
 
 ```bash
-bunx effing-use --help        # after: bun publish (runs src/index.ts via bin)
-# or from source:
 bun install
-bunx playwright install chromium --only-shell   # one-time Chromium download
-bun src/index.ts              # STDIO (single editor)
-bun src/http.ts               # HTTP on :3000 (/mcp) — shared across editors
+bunx playwright install chromium --only-shell
+bun src/index.ts              # STDIO
+bun src/http.ts               # HTTP on :3123 (/mcp)
 ```
 
 Re-run `bunx playwright install chromium --only-shell` whenever you bump the `playwright` dependency (each Playwright version pins its own browser build). Verify with `bunx playwright install --dry-run chromium` or check `~/.cache/ms-playwright/`.
@@ -29,25 +46,25 @@ Re-run `bunx playwright install chromium --only-shell` whenever you bump the `pl
 bun install
 bunx playwright install chromium --only-shell
 docker compose up --build -d
-curl http://localhost:3000/healthz
+curl http://localhost:3123/healthz
 ```
 
-Point any VS Code instance at `http://localhost:3000/mcp` (see `.vscode/mcp.json` → `effing-use (http)`). Plain HTTP on loopback is intentional — add TLS at the edge for remote use.
+Point any VS Code instance at `http://localhost:3123/mcp` (see `.vscode/mcp.json` → `effing-use (http)`). Plain HTTP on loopback is intentional — add TLS at the edge for remote use.
 
 **Step 2/3 — Connect.** STDIO for one editor, HTTP for all of them:
 
 ```json
 {
   "mcpServers": {
-    "computer-use": {
-      "command": "bun",
-      "args": ["/path/to/litepilot/src/index.ts"]
+    "effing-use": {
+      "command": "bunx",
+      "args": ["effing-use"]
     }
   }
 }
 ```
 
-Or HTTP: `http://localhost:3000/mcp`.
+Or HTTP: `http://localhost:3123/mcp` (via `bunx effing-use-http` or Docker). From source instead: `command: "bun"`, `args: ["/path/to/effing-use/src/index.ts"]`.
 
 **Step 3/3 — Drive.** Search Wikipedia in one call instead of two round-trips:
 
@@ -62,7 +79,7 @@ Or HTTP: `http://localhost:3000/mcp`.
 }
 ```
 
-No Docker? `bun src/index.ts` (STDIO) or `bun src/http.ts` (`:3000` `/mcp`) works directly.
+No Docker? `bun src/index.ts` (STDIO) or `bun src/http.ts` (`:3123` `/mcp`) works directly.
 
 ## Why agents prefer 3 tools
 

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "effing-use",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Token-efficient browser control: 3 tools (act, observe, extract) built with tmcp + Bun + Playwright",
   "license": "MIT",
   "author": "Michael Obubelebra Amachree",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Michael-Obele/litepilot.git"
+    "url": "git+https://github.com/Michael-Obele/effing-use.git"
   },
-  "homepage": "https://github.com/Michael-Obele/litepilot#readme",
+  "homepage": "https://github.com/Michael-Obele/effing-use#readme",
   "type": "module",
   "main": "src/index.ts",
   "bin": {
@@ -21,6 +21,10 @@
     "README.md",
     "LICENSE"
   ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "scripts": {
     "start": "bun src/index.ts",
     "start:http": "bun src/http.ts",

package/skills/effing-use/SKILL.md

@@ -4,7 +4,7 @@ description: Drive a headless Chromium browser through 3 token-efficient MCP too
 license: MIT
 compatibility: Requires the effing-use MCP server (Bun + Playwright Chromium). Works over stdio or Streamable HTTP at /mcp.
 metadata:
-  repo: Michael-Obele/litepilot
+  repo: Michael-Obele/effing-use
   tools: browser_act,browser_observe,browser_extract
 ---
 
@@ -53,6 +53,6 @@ Errors always come back as `{ ok: false, code, message, hint }` with codes
 ## Setup
 
 See [references/setup.md](references/setup.md) for install (local Bun,
-Docker, VS Code `mcp.json` entries), port config (`ECU_PORT`), and the
+Docker, VS Code `mcp.json` entries), port config (`EFFING_PORT`), and the
 `.browser-use/` gitignore contract. See [references/troubleshooting.md](references/troubleshooting.md)
 for port conflicts, Chromium sandbox notes, and the `doQuery` arity lesson.

package/skills/effing-use/references/setup.md

@@ -14,7 +14,7 @@
 bun install
 bunx playwright install chromium --only-shell
 bun src/index.ts          # STDIO transport
-bun src/http.ts           # Streamable HTTP on $PORT (default 3000), MCP at /mcp
+bun src/http.ts           # Streamable HTTP on $PORT (default 3123), MCP at /mcp
 ```
 
 VS Code `.vscode/mcp.json`:
@@ -40,12 +40,12 @@ VS Code `.vscode/mcp.json`:
 ## Option B — Docker (shared across VS Code instances)
 
 ```bash
-ECU_PORT=3123 docker compose up --build -d
+EFFING_PORT=3123 docker compose up --build -d
 curl http://localhost:3123/healthz   # {"ok":true,"name":"effing-use"}
 ```
 
-Then point any local client at `http://localhost:<ECU_PORT>/mcp`.
-The container listens on 3000 internally; only the host-side port moves.
+Then point any local client at `http://localhost:<EFFING_PORT>/mcp`.
+The container listens on 3123 internally; only the host-side port moves.
 
 - `restart: unless-stopped` — survives daemon restarts and host reboots
   once started with `up -d`.
@@ -62,8 +62,8 @@ All optional; defaults shown (see `.env.example`):
 
 | Var                    | Default        | Notes                                          |
 | ---------------------- | -------------- | ---------------------------------------------- |
-| `PORT`                 | `3000`         | `src/http.ts` listen port (container-internal) |
-| `ECU_PORT`             | `3000`         | compose host-side port override                |
+| `PORT`                 | `3123`         | `src/http.ts` listen port (container-internal) |
+| `EFFING_PORT`          | `3123`         | compose host-side port override                |
 | `BROWSER_HEADLESS`     | `true`         | Docker supports headless Chromium only         |
 | `BROWSER_VIEWPORT_W/H` | `1280/800`     |                                                |
 | `BROWSER_TIMEOUT_MS`   | `15000`        | per-action Playwright timeout                  |

package/skills/effing-use/references/troubleshooting.md

@@ -12,7 +12,7 @@ docker ps --format "{{.Names}} {{.Ports}}"
 Fix — move our host port, never the container's:
 
 ```bash
-ECU_PORT=3123 docker compose up -d   # client → http://localhost:3123/mcp
+EFFING_PORT=3123 docker compose up -d   # client → http://localhost:3123/mcp
 PORT=3123 bun src/http.ts            # local Bun route
 ```
 

package/src/browser/session.ts

@@ -18,8 +18,15 @@ interface SessionEntry {
 const sessions = new Map<string, SessionEntry>();
 
 async function getBrowser(config: Config): Promise<Browser> {
+  if (browser && !browser.isConnected()) {
+    sessions.clear();
+    browser = null;
+  }
   if (!browser) {
-    browser = await chromium.launch({ headless: config.headless });
+    browser = await chromium.launch({
+      headless: config.headless,
+      args: ["--no-sandbox", "--disable-dev-shm-usage"],
+    });
   }
   return browser;
 }
@@ -29,7 +36,8 @@ export async function getPage(
   sessionId = "default",
 ): Promise<Page> {
   const existing = sessions.get(sessionId);
-  if (existing) return existing.page;
+  if (existing && !existing.page.isClosed()) return existing.page;
+  if (existing) sessions.delete(sessionId);
   const b = await getBrowser(config);
   const context = await b.newContext({
     viewport: { width: config.viewportW, height: config.viewportH },
@@ -66,7 +74,7 @@ export async function getContext(
   sessionId = "default",
 ): Promise<BrowserContext> {
   const existing = sessions.get(sessionId);
-  if (existing) return existing.context;
+  if (existing && !existing.page.isClosed()) return existing.context;
   await getPage(config, sessionId);
   return sessions.get(sessionId)!.context;
 }
@@ -86,7 +94,7 @@ export function getNetworkLogs(
 export async function closeSession(sessionId = "default"): Promise<void> {
   const s = sessions.get(sessionId);
   if (s) {
-    await s.context.close();
+    await s.context.close().catch(() => undefined);
     sessions.delete(sessionId);
   }
 }

package/src/config.ts

@@ -1,5 +1,12 @@
 import * as v from "valibot";
 
+// The npm package version — single source of truth is package.json, so the MCP
+// server's reported version (serverInfo.version) never drifts from the
+// published release.
+export const VERSION = (
+  await Bun.file(new URL("../package.json", import.meta.url)).json()
+).version as string;
+
 const ConfigSchema = v.object({
   headless: v.optional(v.boolean(), true),
   viewportW: v.optional(v.number(), 1280),

package/src/http.ts

@@ -2,7 +2,7 @@
 import { HttpTransport } from "@tmcp/transport-http";
 import { server } from "./server.js";
 
-const port = Number(process.env.PORT ?? 3000);
+const port = Number(process.env.PORT ?? 3123);
 
 // Streamable HTTP transport (MCP spec). Serves the MCP endpoint at /mcp.
 // No auth on local loopback; put a reverse proxy / tunnel in front for remote use.
@@ -11,6 +11,14 @@ const transport = new HttpTransport(server, { path: "/mcp" });
 
 Bun.serve({
   port,
+  // Bun closes idle connections after 10s by default (idleTimeout), and the
+  // timer applies even while a response is being streamed. The MCP
+  // Streamable-HTTP SSE notification stream sits idle between server->client
+  // messages, so Bun was killing it every ~10s and clients logged
+  // "Error reading from async stream: terminated" on a loop until the
+  // connection hard-failed. idleTimeout: 0 disables the idle close entirely
+  // (safe: this server is meant for local loopback / private networks).
+  idleTimeout: 0,
   async fetch(req) {
     const url = new URL(req.url);
     if (url.pathname === "/healthz") {

package/src/server.ts

@@ -1,5 +1,6 @@
 import { McpServer } from "tmcp";
 import { ValibotJsonSchemaAdapter } from "@tmcp/adapter-valibot";
+import { VERSION } from "./config.js";
 import { actTool } from "./tools/act.js";
 import { observeTool } from "./tools/observe.js";
 import { extractTool } from "./tools/extract.js";
@@ -9,7 +10,7 @@ const adapter = new ValibotJsonSchemaAdapter();
 export const server = new McpServer(
   {
     name: "effing-use",
-    version: "0.1.0",
+    version: VERSION,
     description:
       "Token-efficient browser control: 3 tools (act, observe, extract).",
   },