effing-use 0.1.0

package/src/browser/output.ts

@@ -0,0 +1,31 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Config } from "../config.js";
+
+export async function saveText(
+  config: Config,
+  filename: string,
+  text: string,
+): Promise<string> {
+  await mkdir(config.outputDir, { recursive: true });
+  const path = join(config.outputDir, filename);
+  await writeFile(path, text, "utf-8");
+  return path;
+}
+
+export function cap(
+  text: string,
+  maxChars: number,
+): { text: string; truncated: boolean } {
+  if (text.length <= maxChars) return { text, truncated: false };
+  return {
+    text:
+      text.slice(0, maxChars) +
+      `\n…[truncated ${text.length - maxChars} chars, see file]`,
+    truncated: true,
+  };
+}
+
+export function stamp(prefix: string, ext: string): string {
+  return `${prefix}-${new Date().toISOString().replace(/[:.]/g, "-")}.${ext}`;
+}

package/src/browser/refs.ts

@@ -0,0 +1,75 @@
+import type { Page, Locator } from "playwright";
+
+export class EngineError extends Error {
+  code: string;
+  hint: string;
+  data?: Record<string, unknown>;
+  constructor(
+    code: string,
+    message: string,
+    hint: string,
+    data?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.code = code;
+    this.hint = hint;
+    this.data = data;
+  }
+}
+
+const INTERACTIVE_SELECTOR =
+  "button, a, input, select, textarea, [role=button], [tabindex]";
+
+/** Resolve `eNN` snapshot refs via nth-match on interactive elements. */
+export function resolveRef(page: Page, ref: string): Locator {
+  const m = /^e(\d+)$/i.exec(ref.trim());
+  if (!m) throw new Error("not an e-ref");
+  return page.locator(INTERACTIVE_SELECTOR).nth(Number(m[1]));
+}
+
+export async function resolveLocator(
+  page: Page,
+  target: string,
+): Promise<Locator> {
+  const t = target.trim();
+  // 0. eNN ref
+  if (/^e\d+$/i.test(t)) {
+    const loc = resolveRef(page, t);
+    if ((await loc.count()) > 0) return loc;
+    throw new EngineError(
+      "E_NOT_FOUND",
+      `No element matches "${t}".`,
+      "Call browser_observe kind=snapshot first to refresh refs, then use a fresh e-ref.",
+    );
+  }
+  // 1. role= selector passes through
+  if (t.startsWith("role=")) return page.locator(t);
+  // 2. CSS-ish (starts with #, ., [, //, or tag)
+  if (/^[#.\[/a-zA-Z]/.test(t) && !t.includes(" ")) {
+    try {
+      const css = page.locator(`css=${t}`);
+      if ((await css.count()) > 0) return css.first();
+    } catch {
+      /* fall through */
+    }
+  }
+  // try as generic CSS anyway
+  try {
+    const any = page.locator(t);
+    if ((await any.count()) > 0) return any.first();
+  } catch {
+    /* fall through to fuzzy */
+  }
+  // 3. fuzzy label on interactive roles
+  const fuzzy = page
+    .getByRole("button", { name: t })
+    .or(page.getByRole("link", { name: t }))
+    .or(page.getByRole("textbox", { name: t }))
+    .or(page.getByText(t));
+  if ((await fuzzy.count()) > 0) return fuzzy.first();
+  throw new EngineError(
+    "E_NOT_FOUND",
+    `No element matches "${t}".`,
+    "Call browser_observe kind=snapshot first, then use an e-ref, role= selector, or CSS selector.",
+  );
+}

package/src/browser/session.ts

@@ -0,0 +1,100 @@
+import {
+  chromium,
+  type Browser,
+  type BrowserContext,
+  type Page,
+} from "playwright";
+import type { Config } from "../config.js";
+
+let browser: Browser | null = null;
+
+interface SessionEntry {
+  context: BrowserContext;
+  page: Page;
+  consoleLogs: Array<{ type: string; text: string; at: string }>;
+  networkLogs: Array<{ method: string; url: string; status: number }>;
+}
+
+const sessions = new Map<string, SessionEntry>();
+
+async function getBrowser(config: Config): Promise<Browser> {
+  if (!browser) {
+    browser = await chromium.launch({ headless: config.headless });
+  }
+  return browser;
+}
+
+export async function getPage(
+  config: Config,
+  sessionId = "default",
+): Promise<Page> {
+  const existing = sessions.get(sessionId);
+  if (existing) return existing.page;
+  const b = await getBrowser(config);
+  const context = await b.newContext({
+    viewport: { width: config.viewportW, height: config.viewportH },
+  });
+  const page = await context.newPage();
+  const entry: SessionEntry = {
+    context,
+    page,
+    consoleLogs: [],
+    networkLogs: [],
+  };
+  page.on("console", (msg) => {
+    entry.consoleLogs.push({
+      type: msg.type(),
+      text: msg.text(),
+      at: new Date().toISOString(),
+    });
+    if (entry.consoleLogs.length > 50) entry.consoleLogs.shift();
+  });
+  page.on("response", (res) => {
+    entry.networkLogs.push({
+      method: res.request().method(),
+      url: res.url(),
+      status: res.status(),
+    });
+    if (entry.networkLogs.length > 50) entry.networkLogs.shift();
+  });
+  sessions.set(sessionId, entry);
+  return page;
+}
+
+export async function getContext(
+  config: Config,
+  sessionId = "default",
+): Promise<BrowserContext> {
+  const existing = sessions.get(sessionId);
+  if (existing) return existing.context;
+  await getPage(config, sessionId);
+  return sessions.get(sessionId)!.context;
+}
+
+export function getConsoleLogs(
+  sessionId = "default",
+): SessionEntry["consoleLogs"] {
+  return sessions.get(sessionId)?.consoleLogs ?? [];
+}
+
+export function getNetworkLogs(
+  sessionId = "default",
+): SessionEntry["networkLogs"] {
+  return sessions.get(sessionId)?.networkLogs ?? [];
+}
+
+export async function closeSession(sessionId = "default"): Promise<void> {
+  const s = sessions.get(sessionId);
+  if (s) {
+    await s.context.close();
+    sessions.delete(sessionId);
+  }
+}
+
+export async function closeAll(): Promise<void> {
+  for (const id of [...sessions.keys()]) await closeSession(id);
+  if (browser) {
+    await browser.close();
+    browser = null;
+  }
+}

package/src/config.ts

@@ -0,0 +1,25 @@
+import * as v from "valibot";
+
+const ConfigSchema = v.object({
+  headless: v.optional(v.boolean(), true),
+  viewportW: v.optional(v.number(), 1280),
+  viewportH: v.optional(v.number(), 800),
+  timeoutMs: v.optional(v.number(), 15000),
+  outputDir: v.optional(v.string(), ".browser-use"),
+  outputMaxChars: v.optional(v.number(), 4000),
+  allowEval: v.optional(v.boolean(), false),
+});
+
+export type Config = v.InferOutput<typeof ConfigSchema>;
+
+export function loadConfig(): Config {
+  return v.parse(ConfigSchema, {
+    headless: process.env.BROWSER_HEADLESS !== "false",
+    viewportW: Number(process.env.BROWSER_VIEWPORT_W ?? 1280),
+    viewportH: Number(process.env.BROWSER_VIEWPORT_H ?? 800),
+    timeoutMs: Number(process.env.BROWSER_TIMEOUT_MS ?? 15000),
+    outputDir: process.env.OUTPUT_DIR ?? ".browser-use",
+    outputMaxChars: Number(process.env.OUTPUT_MAX_CHARS ?? 4000),
+    allowEval: process.env.ALLOW_EVAL === "true",
+  });
+}

package/src/http.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env bun
+import { HttpTransport } from "@tmcp/transport-http";
+import { server } from "./server.js";
+
+const port = Number(process.env.PORT ?? 3000);
+
+// 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.
+// Bun-only: Bun.serve keeps this file dependency-free (no node:http shim).
+const transport = new HttpTransport(server, { path: "/mcp" });
+
+Bun.serve({
+  port,
+  async fetch(req) {
+    const url = new URL(req.url);
+    if (url.pathname === "/healthz") {
+      return Response.json({ ok: true, name: "effing-use" });
+    }
+    const response = await transport.respond(req);
+    if (response === null) {
+      return new Response("Not Found", { status: 404 });
+    }
+    return response;
+  },
+});
+
+// eslint-disable-next-line no-console
+console.log(`effing-use listening on :${port} (MCP at /mcp)`);

package/src/index.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env bun
+import { StdioTransport } from "@tmcp/transport-stdio";
+import { server } from "./server.js";
+
+const transport = new StdioTransport(server);
+transport.listen();

package/src/server.ts

@@ -0,0 +1,19 @@
+import { McpServer } from "tmcp";
+import { ValibotJsonSchemaAdapter } from "@tmcp/adapter-valibot";
+import { actTool } from "./tools/act.js";
+import { observeTool } from "./tools/observe.js";
+import { extractTool } from "./tools/extract.js";
+
+const adapter = new ValibotJsonSchemaAdapter();
+
+export const server = new McpServer(
+  {
+    name: "effing-use",
+    version: "0.1.0",
+    description:
+      "Token-efficient browser control: 3 tools (act, observe, extract).",
+  },
+  { adapter, capabilities: { tools: { listChanged: true } } },
+);
+
+server.tools([actTool, observeTool, extractTool]);

package/src/tools/act.ts

@@ -0,0 +1,131 @@
+import { defineTool } from "tmcp/tool";
+import { tool } from "tmcp/utils";
+import * as v from "valibot";
+import { loadConfig } from "../config.js";
+import { getPage, getContext } from "../browser/session.js";
+import { doAct, doBatch, doGoal, type ActAction } from "../browser/engine.js";
+import { EngineError } from "../browser/refs.js";
+
+export const ACT_ACTIONS = [
+  "open",
+  "goto",
+  "click",
+  "dblclick",
+  "fill",
+  "type",
+  "press",
+  "select",
+  "check",
+  "uncheck",
+  "hover",
+  "drag",
+  "upload",
+  "scroll",
+  "back",
+  "forward",
+  "reload",
+  "wait",
+  "dialog_accept",
+  "dialog_dismiss",
+  "close",
+  "goal",
+  "batch",
+  "tab_new",
+  "tab_select",
+  "tab_close",
+  "resize",
+] as const;
+
+const StepSchema = v.object({
+  action: v.picklist(ACT_ACTIONS),
+  target: v.optional(v.string()),
+  value: v.optional(v.string()),
+});
+
+export const actTool = defineTool(
+  {
+    name: "browser_act",
+    description:
+      "Drive the browser: open/goto URLs, click, fill, type, press keys, select, check, hover, drag, upload, scroll, back/forward/reload, wait, dialogs, tabs, resize, or run a high-level goal or batch of steps. Targets accept snapshot e-refs (e12), role= selectors, or CSS. Returns a capped JSON summary; large state goes to a file path.",
+    schema: v.object({
+      action: v.picklist(ACT_ACTIONS),
+      target: v.optional(v.string()),
+      value: v.optional(v.string()),
+      sessionId: v.optional(v.string()),
+      steps: v.optional(v.array(StepSchema)),
+    }),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: false,
+      openWorldHint: true,
+    },
+  },
+  async ({ action, target, value, sessionId, steps }) => {
+    const config = loadConfig();
+    const sid = sessionId ?? "default";
+    try {
+      const page = await getPage(config, sid);
+      const context = await getContext(config, sid);
+      const opts = { context, sessionId: sid };
+      if (action === "batch") {
+        if (!steps || steps.length === 0)
+          return tool.text(
+            JSON.stringify({
+              ok: false,
+              code: "E_BAD_INPUT",
+              message: "Missing steps[].",
+              hint: "Pass steps[] with up to 20 {action,target,value} entries.",
+            }),
+          );
+        const result = await doBatch(
+          page,
+          config,
+          steps as Array<{
+            action: ActAction;
+            target?: string;
+            value?: string;
+          }>,
+          opts,
+        );
+        const url = page.url();
+        const title = await page.title().catch(() => "");
+        return tool.text(
+          JSON.stringify({ ok: true, action, url, title, ...result }),
+        );
+      }
+      if (action === "goal") {
+        const result = await doGoal(page, config, value ?? target ?? "", opts);
+        return tool.text(JSON.stringify({ ok: true, action, ...result }));
+      }
+      const result = await doAct(
+        page,
+        config,
+        action as ActAction,
+        target,
+        value,
+        opts,
+      );
+      return tool.text(JSON.stringify({ ok: true, action, ...result }));
+    } catch (e) {
+      if (e instanceof EngineError)
+        return tool.text(
+          JSON.stringify({
+            ok: false,
+            code: e.code,
+            message: e.message,
+            hint: e.hint,
+            ...(e.data ?? {}),
+          }),
+        );
+      return tool.text(
+        JSON.stringify({
+          ok: false,
+          code: "E_BAD_INPUT",
+          message: e instanceof Error ? e.message : String(e),
+          hint: "Retry with fresh snapshot refs.",
+        }),
+      );
+    }
+  },
+);

package/src/tools/extract.ts

@@ -0,0 +1,86 @@
+import { defineTool } from "tmcp/tool";
+import { tool } from "tmcp/utils";
+import * as v from "valibot";
+import { loadConfig } from "../config.js";
+import { getPage, getContext } from "../browser/session.js";
+import { doExtract, doQuery } from "../browser/engine.js";
+import { EngineError } from "../browser/refs.js";
+
+export const extractTool = defineTool(
+  {
+    name: "browser_extract",
+    description:
+      "Pull structured data out of the page: rendered text, HTML, table rows as JSON, CSS query as JSON, PDF file, or Playwright trace. Large results go to a file path with a capped preview. Prefer over snapshot for scraping.",
+    schema: v.object({
+      kind: v.picklist([
+        "text",
+        "html",
+        "table",
+        "query",
+        "pdf",
+        "trace_start",
+        "trace_stop",
+      ]),
+      selector: v.optional(v.string()),
+      mode: v.optional(v.string()),
+      limit: v.optional(v.number()),
+      sessionId: v.optional(v.string()),
+    }),
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ kind, selector, mode, limit, sessionId }) => {
+    const config = loadConfig();
+    const sid = sessionId ?? "default";
+    try {
+      const page = await getPage(config, sid);
+      const context = await getContext(config, sid);
+      if (kind === "query") {
+        if (!selector)
+          return tool.text(
+            JSON.stringify({
+              ok: false,
+              code: "E_BAD_INPUT",
+              message: "Missing selector.",
+              hint: "Pass a CSS selector in selector and mode text|href|json.",
+            }),
+          );
+        const result = await doQuery(
+          page,
+          config,
+          selector,
+          mode ?? "text",
+          limit ?? 50,
+        );
+        return tool.text(JSON.stringify({ ok: true, kind, ...result }));
+      }
+      const result = await doExtract(page, config, kind, selector, limit, {
+        context,
+        sessionId: sid,
+      });
+      return tool.text(JSON.stringify({ ok: true, kind, ...result }));
+    } catch (e) {
+      if (e instanceof EngineError)
+        return tool.text(
+          JSON.stringify({
+            ok: false,
+            code: e.code,
+            message: e.message,
+            hint: e.hint,
+          }),
+        );
+      return tool.text(
+        JSON.stringify({
+          ok: false,
+          code: "E_BAD_INPUT",
+          message: e instanceof Error ? e.message : String(e),
+          hint: "Retry the extract call.",
+        }),
+      );
+    }
+  },
+);

package/src/tools/observe.ts

@@ -0,0 +1,68 @@
+import { defineTool } from "tmcp/tool";
+import { tool } from "tmcp/utils";
+import * as v from "valibot";
+import { loadConfig } from "../config.js";
+import { getPage, getContext } from "../browser/session.js";
+import { doObserve } from "../browser/engine.js";
+import { EngineError } from "../browser/refs.js";
+
+export const observeTool = defineTool(
+  {
+    name: "browser_observe",
+    description:
+      "Read browser state without changing it: snapshot (element refs), screenshot (file path), url, title, console logs, network requests, tab list, focused element. Snapshots are capped; full content is saved to a file path. Call snapshot before act to get refs.",
+    schema: v.object({
+      kind: v.picklist([
+        "snapshot",
+        "screenshot",
+        "url",
+        "title",
+        "console",
+        "network",
+        "tabs",
+        "focused",
+      ]),
+      target: v.optional(v.string()),
+      limit: v.optional(v.number()),
+      sessionId: v.optional(v.string()),
+      inline: v.optional(v.boolean()),
+    }),
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  async ({ kind, target, limit, sessionId }) => {
+    const config = loadConfig();
+    const sid = sessionId ?? "default";
+    try {
+      const page = await getPage(config, sid);
+      const context = await getContext(config, sid);
+      const result = await doObserve(page, config, kind, target, limit, {
+        context,
+        sessionId: sid,
+      });
+      return tool.text(JSON.stringify({ ok: true, kind, ...result }));
+    } catch (e) {
+      if (e instanceof EngineError)
+        return tool.text(
+          JSON.stringify({
+            ok: false,
+            code: e.code,
+            message: e.message,
+            hint: e.hint,
+          }),
+        );
+      return tool.text(
+        JSON.stringify({
+          ok: false,
+          code: "E_BAD_INPUT",
+          message: e instanceof Error ? e.message : String(e),
+          hint: "Retry the observe call.",
+        }),
+      );
+    }
+  },
+);