@humanjs/mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,1099 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { homedir } from 'os';
+import { join, extname, basename, dirname } from 'path';
+import { spawn } from 'child_process';
+import { readFileSync } from 'fs';
+import { createRequire } from 'module';
+import { createHuman, installMouseHelper } from '@humanjs/playwright';
+import { chromium } from 'playwright';
+import { z } from 'zod';
+import { blend } from '@humanjs/core';
+import { writeFile } from 'fs/promises';
+
+var VALID_PRESETS = ["careful", "fast", "distracted", "precise"];
+var VALID_SPEEDS = ["human", "fast", "instant"];
+function readEnv() {
+  return {
+    personality: parsePersonality(process.env.HUMANJS_PERSONALITY),
+    speed: parseSpeed(process.env.HUMANJS_SPEED),
+    headless: parseBool(process.env.HUMANJS_HEADLESS, false),
+    outputDir: process.env.HUMANJS_OUTPUT_DIR ?? process.cwd(),
+    viewport: parseViewport(process.env.HUMANJS_VIEWPORT),
+    autoInstall: parseBool(process.env.HUMANJS_AUTO_INSTALL, true),
+    browser: resolveBrowserConfig(),
+    channel: process.env.HUMANJS_CHANNEL?.trim() || void 0
+  };
+}
+var DEFAULT_PERSIST_DIR = join(homedir(), ".humanjs", "profile");
+function resolveBrowserConfig() {
+  const cdpUrl = process.env.HUMANJS_CDP_URL?.trim() || void 0;
+  if (cdpUrl) return { mode: "cdp", cdpUrl };
+  const explicitDir = process.env.HUMANJS_USER_DATA_DIR?.trim() || void 0;
+  if (explicitDir) return { mode: "persistent", userDataDir: explicitDir };
+  if (parseBool(process.env.HUMANJS_PERSIST, false)) {
+    return { mode: "persistent", userDataDir: DEFAULT_PERSIST_DIR };
+  }
+  return { mode: "ephemeral" };
+}
+function parsePersonality(raw) {
+  if (!raw) return "careful";
+  const lower = raw.toLowerCase();
+  if (VALID_PRESETS.includes(lower)) return lower;
+  throw new Error(
+    `HUMANJS_PERSONALITY="${raw}" is not a known preset. Expected one of: ${VALID_PRESETS.join(", ")}.`
+  );
+}
+function parseSpeed(raw) {
+  if (!raw) return "human";
+  const lower = raw.toLowerCase();
+  if (VALID_SPEEDS.includes(lower)) return lower;
+  throw new Error(
+    `HUMANJS_SPEED="${raw}" is not valid. Expected one of: ${VALID_SPEEDS.join(", ")}.`
+  );
+}
+function parseBool(raw, fallback) {
+  if (raw === void 0) return fallback;
+  const lower = raw.toLowerCase();
+  if (lower === "true" || lower === "1" || lower === "yes") return true;
+  if (lower === "false" || lower === "0" || lower === "no") return false;
+  throw new Error(`Expected a boolean ("true"/"false"), got "${raw}".`);
+}
+function parseViewport(raw) {
+  if (!raw) return { width: 1440, height: 900 };
+  const match = /^\s*(\d+)\s*[x×]\s*(\d+)\s*$/i.exec(raw);
+  if (!match) {
+    throw new Error(
+      `HUMANJS_VIEWPORT="${raw}" is invalid. Expected "WIDTHxHEIGHT", e.g. "1920x1080".`
+    );
+  }
+  return { width: Number(match[1]), height: Number(match[2]) };
+}
+var DEFAULT_SESSION_ID = "default";
+var SessionManager = class {
+  /** Backing browser for `ephemeral` and `cdp` modes. */
+  browser = null;
+  /** Backing context for `persistent` mode (launchPersistentContext returns a context, no Browser). */
+  persistentContext = null;
+  /** True when `browser` was obtained via connectOverCDP — must NOT be closed on teardown. */
+  cdpConnected = false;
+  /** Runtime persistence toggle (from human_enable_persistence); overrides env mode on next launch. */
+  persistOverride = null;
+  sessions = /* @__PURE__ */ new Map();
+  env;
+  constructor(env) {
+    this.env = env;
+  }
+  /** Effective browser config, honoring the runtime persistence override. */
+  effectiveConfig() {
+    if (this.persistOverride) {
+      return { mode: "persistent", userDataDir: this.persistOverride.userDataDir };
+    }
+    return this.env.browser;
+  }
+  /**
+   * Resolves the session named by `id`, creating the default session
+   * lazily if `id` is omitted or `'default'` and the session doesn't
+   * exist yet. Throws if an explicit non-default session ID hasn't been
+   * created — that case is a caller bug, not a missing-default UX
+   * problem, and a clear error helps the AI agent recover.
+   */
+  async get(id = DEFAULT_SESSION_ID) {
+    const existing = this.sessions.get(id);
+    if (existing) return existing;
+    if (id === DEFAULT_SESSION_ID) return this.create(DEFAULT_SESSION_ID, {});
+    throw new Error(
+      `Session "${id}" does not exist. Use human_create_session to create it first, or omit the session argument to use the default session.`
+    );
+  }
+  /**
+   * Creates a new named session. Throws if the ID is already in use —
+   * the caller (an AI agent) should close the old one first if they
+   * want to recreate.
+   */
+  async create(id, options) {
+    if (this.sessions.has(id)) {
+      throw new Error(
+        `Session "${id}" already exists. Close it first with human_close_session if you want to recreate it.`
+      );
+    }
+    const config = this.effectiveConfig();
+    if (config.mode !== "ephemeral" && id !== DEFAULT_SESSION_ID) {
+      throw new Error(
+        `In ${config.mode} mode HumanJS drives a single shared browser, so named/parallel sessions aren't available. Omit the session argument to use the default session.`
+      );
+    }
+    const viewport = options.viewport ?? this.env.viewport;
+    const { context, page } = await this.acquireContext(config, viewport);
+    const personality = options.personality ?? this.env.personality;
+    const speed = options.speed ?? this.env.speed;
+    const human = await createHuman(page, { personality, speed });
+    const session = {
+      id,
+      context,
+      page,
+      human,
+      personality,
+      speed,
+      mode: config.mode,
+      recording: null,
+      createdAt: Date.now()
+    };
+    this.sessions.set(id, session);
+    return session;
+  }
+  /**
+   * Obtains a `{ context, page }` for the given mode:
+   *
+   * - `cdp` — reuse the attached browser's existing context + page (the
+   *   user's real session); only make a new one if there's none.
+   * - `persistent` — the single persistent context; reuse its page.
+   * - `ephemeral` — a fresh isolated context + page per session.
+   *
+   * The visible cursor overlay is installed on the context in every mode.
+   */
+  async acquireContext(config, viewport) {
+    if (config.mode === "cdp") {
+      const browser2 = await this.ensureCdpBrowser(config.cdpUrl);
+      const context2 = browser2.contexts()[0] ?? await browser2.newContext();
+      await installMouseHelper(context2);
+      const page2 = context2.pages()[0] ?? await context2.newPage();
+      return { context: context2, page: page2 };
+    }
+    if (config.mode === "persistent") {
+      const context2 = await this.ensurePersistentContext(config.userDataDir, viewport);
+      const page2 = context2.pages()[0] ?? await context2.newPage();
+      return { context: context2, page: page2 };
+    }
+    const browser = await this.ensureEphemeralBrowser();
+    const context = await browser.newContext({ viewport });
+    await installMouseHelper(context);
+    const page = await context.newPage();
+    return { context, page };
+  }
+  /**
+   * Starts a recording on a session. Holds `human.record()` open across
+   * tool calls by awaiting an internal stop-signal — capture (frames +
+   * action timeline) runs until {@link stopRecording} fires it.
+   */
+  async startRecording(id, options) {
+    const session = await this.get(id);
+    if (session.recording) {
+      throw new Error(
+        `Session "${session.id}" is already recording. Stop it first with human_stop_recording.`
+      );
+    }
+    let stop;
+    const signal = new Promise((resolve) => {
+      stop = resolve;
+    });
+    const video = options.video ?? true;
+    const done = session.human.record({ video, quality: options.quality ?? "high" }, () => signal);
+    session.recording = {
+      name: options.name ?? "recording",
+      startedAt: Date.now(),
+      video,
+      stop,
+      done
+    };
+  }
+  /**
+   * Stops the active recording, returns the finished {@link Recording} for
+   * export, and recreates the session's `Human` so it can record again
+   * (`human.record()` is single-use per instance; page/context/cookies are
+   * preserved).
+   */
+  async stopRecording(id) {
+    const session = await this.get(id);
+    const rec = session.recording;
+    if (!rec) {
+      throw new Error(
+        `Session "${session.id}" is not recording. Start one with human_start_recording first.`
+      );
+    }
+    rec.stop();
+    const recording = await rec.done;
+    session.recording = null;
+    session.human = await createHuman(session.page, {
+      personality: session.personality,
+      speed: session.speed
+    });
+    return recording;
+  }
+  /**
+   * Replaces the `Human` instance on an existing session with one bound
+   * to a new personality. Browser context, page, cookies, and scroll
+   * position are preserved — only the humanization profile changes.
+   */
+  async setPersonality(id = DEFAULT_SESSION_ID, personality) {
+    const session = await this.get(id);
+    assertNotRecording(session, "change personality");
+    session.human = await createHuman(session.page, { personality, speed: session.speed });
+    session.personality = session.human.personality.name ?? "careful";
+    return toSessionInfo(session);
+  }
+  /**
+   * Changes the humanization pace for a session at runtime. Recreates the
+   * `Human` (speed is fixed at creation); browser context, page, cookies,
+   * and scroll position are preserved.
+   */
+  async setSpeed(id = DEFAULT_SESSION_ID, speed) {
+    const session = await this.get(id);
+    assertNotRecording(session, "change speed");
+    session.speed = speed;
+    session.human = await createHuman(session.page, {
+      personality: session.personality,
+      speed
+    });
+    return toSessionInfo(session);
+  }
+  /** Lists all currently-open sessions, including the default if active. */
+  list() {
+    return [...this.sessions.values()].map(toSessionInfo);
+  }
+  /** Closes a single session and frees its browser context. */
+  async close(id) {
+    const session = this.sessions.get(id);
+    if (!session) return;
+    if (session.recording) {
+      const rec = session.recording;
+      session.recording = null;
+      try {
+        rec.stop();
+        const recording = await rec.done;
+        const ext = rec.video ? ".mp4" : ".json";
+        const path = join(this.env.outputDir, basename(`${rec.name}-${rec.startedAt}${ext}`));
+        if (rec.video) await recording.toVideo(path);
+        else await recording.toTimeline(path);
+      } catch {
+      }
+    }
+    this.sessions.delete(id);
+    if (session.mode === "ephemeral") {
+      await session.context.close();
+    } else if (session.mode === "persistent") {
+      await this.persistentContext?.close();
+      this.persistentContext = null;
+    }
+  }
+  /**
+   * Tears down every session and the backing browser. Called from the bin
+   * entry's shutdown handlers (SIGINT / SIGTERM) so we don't leak chrome
+   * processes — and by {@link restartBrowser}. A CDP-attached browser is
+   * never closed (it's the user's), only disconnected by dropping the ref.
+   */
+  async closeAll() {
+    for (const id of [...this.sessions.keys()]) {
+      await this.close(id);
+    }
+    if (this.browser && !this.cdpConnected) {
+      await this.browser.close();
+    }
+    this.browser = null;
+    this.cdpConnected = false;
+    this.persistentContext = null;
+  }
+  /**
+   * Tears the browser down so the next action relaunches it in the current
+   * (possibly newly-toggled) mode. Backs `human_restart_browser` — the way
+   * to apply a persistence change without restarting the whole MCP server.
+   * Discards open pages/tabs.
+   */
+  async restartBrowser() {
+    await this.closeAll();
+  }
+  /**
+   * Turns on a persistent profile for subsequent browser starts (backs
+   * `human_enable_persistence`). Takes effect on the next browser launch —
+   * call {@link restartBrowser} to apply it to an already-running browser.
+   */
+  setPersistOverride(userDataDir) {
+    this.persistOverride = { userDataDir: userDataDir ?? DEFAULT_PERSIST_DIR };
+  }
+  /** Read-only snapshot of the browser configuration (backs `human_browser_info`). */
+  browserInfo() {
+    const config = this.effectiveConfig();
+    const running = this.browserRunning();
+    return {
+      mode: config.mode,
+      userDataDir: config.mode === "persistent" ? config.userDataDir : null,
+      cdpUrl: config.mode === "cdp" ? config.cdpUrl : null,
+      channel: this.env.channel ?? null,
+      // A toggle is "pending restart" only when a browser is already up:
+      // before any browser exists, the new mode just applies on next start.
+      persistPendingRestart: this.persistOverride !== null && running,
+      browserRunning: running
+    };
+  }
+  browserRunning() {
+    return this.browser !== null || this.persistentContext !== null;
+  }
+  async ensureEphemeralBrowser() {
+    if (this.browser) return this.browser;
+    this.browser = await this.withBrowserInstall(
+      () => chromium.launch({ headless: this.env.headless, channel: this.env.channel })
+    );
+    return this.browser;
+  }
+  async ensureCdpBrowser(url) {
+    if (this.browser) return this.browser;
+    try {
+      this.browser = await chromium.connectOverCDP(url);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(
+        `Could not attach to a browser at ${url} (HUMANJS_CDP_URL). Start your browser with --remote-debugging-port and a matching URL, then retry. (${message})`
+      );
+    }
+    this.cdpConnected = true;
+    return this.browser;
+  }
+  async ensurePersistentContext(userDataDir, viewport) {
+    if (this.persistentContext) return this.persistentContext;
+    this.persistentContext = await this.withBrowserInstall(
+      () => chromium.launchPersistentContext(userDataDir, {
+        headless: this.env.headless,
+        channel: this.env.channel,
+        viewport
+      })
+    );
+    await installMouseHelper(this.persistentContext);
+    return this.persistentContext;
+  }
+  /**
+   * Runs a browser-launch thunk, auto-installing Chromium once and retrying
+   * if the binary is missing (the common first-run failure — binaries can't
+   * ship via npm). Honors `HUMANJS_AUTO_INSTALL=false`. CDP attach doesn't
+   * need a local binary, so it doesn't go through here.
+   */
+  async withBrowserInstall(launch) {
+    try {
+      return await launch();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (!/executable doesn't exist|playwright install/i.test(message)) throw error;
+      if (!this.env.autoInstall) {
+        throw new Error(
+          "Chromium isn't installed and HUMANJS_AUTO_INSTALL is off. Run `npx playwright install chromium` once, then retry."
+        );
+      }
+      await installChromium();
+      try {
+        return await launch();
+      } catch (retryError) {
+        const retryMessage = retryError instanceof Error ? retryError.message : String(retryError);
+        throw new Error(
+          `Auto-install of Chromium ran but the browser still failed to launch. Try \`npx playwright install chromium\` manually. (Original error: ${retryMessage})`
+        );
+      }
+    }
+  }
+};
+async function installChromium() {
+  process.stderr.write(
+    "[humanjs-mcp] Chromium not found \u2014 installing once (~150MB, may take a minute)\u2026\n"
+  );
+  const require2 = createRequire(import.meta.url);
+  const pkgPath = require2.resolve("playwright/package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const binRel = pkg.bin?.playwright;
+  if (!binRel) {
+    throw new Error("Could not locate Playwright's CLI to install Chromium.");
+  }
+  const cli = join(dirname(pkgPath), binRel);
+  await new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [cli, "install", "chromium"], {
+      stdio: ["ignore", 2, 2]
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`playwright install exited with code ${code}.`));
+    });
+  });
+  process.stderr.write("[humanjs-mcp] Chromium installed.\n");
+}
+function toSessionInfo(session) {
+  return {
+    id: session.id,
+    personality: session.personality,
+    speed: session.speed,
+    createdAt: session.createdAt
+  };
+}
+function assertNotRecording(session, action) {
+  if (session.recording) {
+    throw new Error(
+      `Cannot ${action} while session "${session.id}" is recording. Stop the recording first with human_stop_recording.`
+    );
+  }
+}
+function registerBrowserTools(server, { sessions }) {
+  server.registerTool(
+    "human_browser_info",
+    {
+      title: "Browser configuration",
+      description: "Reports how the browser is obtained (ephemeral fresh profile, persistent profile, or attached over CDP), the channel, and whether logins persist. Use it to explain to the user why they are or are not signed in, and how to change it.",
+      inputSchema: {}
+    },
+    async () => {
+      const info = sessions.browserInfo();
+      const lines = [];
+      if (info.mode === "cdp") {
+        lines.push(`Mode: attached to your running browser over CDP (${info.cdpUrl}).`);
+        lines.push("Uses that browser's existing logins, tabs, and extensions.");
+      } else if (info.mode === "persistent") {
+        lines.push(`Mode: persistent profile at ${info.userDataDir}.`);
+        lines.push("Logins persist across runs (sign in once; it sticks).");
+      } else {
+        lines.push("Mode: ephemeral \u2014 a fresh, empty profile each run (no saved logins).");
+        lines.push(
+          "To keep logins across runs: call human_enable_persistence, or set HUMANJS_PERSIST=true in the MCP config for a permanent default."
+        );
+      }
+      lines.push(`Channel: ${info.channel ?? "bundled Chromium"}.`);
+      lines.push(`Browser running: ${info.browserRunning ? "yes" : "no"}.`);
+      if (info.persistPendingRestart) {
+        lines.push(
+          "A persistence change is set but not yet applied \u2014 call human_restart_browser to apply it now."
+        );
+      }
+      return { content: [{ type: "text", text: lines.join("\n") }] };
+    }
+  );
+  server.registerTool(
+    "human_enable_persistence",
+    {
+      title: "Enable a persistent profile",
+      description: "Switches HumanJS to a persistent browser profile so logins/cookies survive across runs. Takes effect on the next browser start; pass restartNow:true to apply immediately (restarting discards the current page \u2014 re-navigate after). For a permanent default, set HUMANJS_PERSIST=true in the MCP config instead. Note: this does NOT use your real Chrome profile (that stays an env-only, opt-in setting).",
+      inputSchema: {
+        userDataDir: z.string().optional().describe("Optional profile directory. Defaults to ~/.humanjs/profile."),
+        restartNow: z.boolean().optional().describe(
+          "Restart the browser immediately to apply (discards the current page). Default false."
+        )
+      }
+    },
+    async ({ userDataDir, restartNow }) => {
+      sessions.setPersistOverride(userDataDir);
+      const info = sessions.browserInfo();
+      let text = `Persistence enabled (profile: ${info.userDataDir}).`;
+      if (info.persistPendingRestart) {
+        if (restartNow) {
+          await sessions.restartBrowser();
+          text += " Browser restarted \u2014 re-navigate to your page; logins will now persist.";
+        } else {
+          text += " Active on the next browser start. Call human_restart_browser to apply now (discards the current page).";
+        }
+      } else {
+        text += " It will apply on the next action.";
+      }
+      text += " For a permanent default, set HUMANJS_PERSIST=true in your MCP config.";
+      return { content: [{ type: "text", text }] };
+    }
+  );
+  server.registerTool(
+    "human_restart_browser",
+    {
+      title: "Restart the browser",
+      description: "Closes the browser and all sessions; the next action launches a fresh one in the current mode. Use to apply a persistence change, or to recover a wedged browser. Discards open pages/tabs \u2014 re-navigate afterward. (Does not affect a CDP-attached browser beyond disconnecting.)",
+      inputSchema: {}
+    },
+    async () => {
+      await sessions.restartBrowser();
+      return {
+        content: [
+          {
+            type: "text",
+            text: "Browser restarted. The next action launches a fresh browser in the current mode \u2014 re-navigate to your page."
+          }
+        ]
+      };
+    }
+  );
+}
+var preset = z.enum(["careful", "fast", "distracted", "precise"]);
+function registerConfigTools(server, { sessions }) {
+  server.registerTool(
+    "human_set_personality",
+    {
+      title: "Set session personality",
+      description: "Changes the humanization personality for a session at runtime. Pass a preset, or a blend of two presets (e.g. mostly careful with a touch of distracted). The browser, cookies, and scroll position are preserved \u2014 only the motion/typing/reading profile changes.",
+      inputSchema: {
+        personality: preset.optional().describe("A preset to apply. Provide this OR `blend`, not both."),
+        blend: z.object({
+          a: preset.describe("First personality."),
+          b: preset.describe("Second personality."),
+          ratio: z.number().min(0).max(1).describe("Weight toward `b` (0 = all a, 1 = all b). e.g. 0.3 = mostly a.")
+        }).optional().describe("Blend two presets. Provide this OR `personality`, not both."),
+        session: z.string().optional().describe("Session ID. Omit for the default session.")
+      }
+    },
+    async ({ personality, blend: blendArg, session }) => {
+      if (personality && blendArg) {
+        throw new Error("Provide either `personality` or `blend`, not both.");
+      }
+      if (!personality && !blendArg) {
+        throw new Error("Provide a `personality` preset or a `blend`.");
+      }
+      const config = blendArg ? blend(blendArg.a, blendArg.b, blendArg.ratio) : personality;
+      const info = await sessions.setPersonality(session, config);
+      const label = blendArg ? `blend(${blendArg.a}, ${blendArg.b}, ${blendArg.ratio})` : personality;
+      return {
+        content: [{ type: "text", text: `set "${info.id}" personality to ${label}` }]
+      };
+    }
+  );
+  server.registerTool(
+    "human_set_speed",
+    {
+      title: "Set humanization speed",
+      description: `Changes a session's humanization pace at runtime. "human" = full realistic motion (best for recordings); "fast" = humanized but quicker; "instant" = no humanized motion (straight Playwright). Note: this changes how long each action takes to execute, not the wait between actions. Cannot change while recording.`,
+      inputSchema: {
+        speed: z.enum(["human", "fast", "instant"]).describe("The pace to switch to."),
+        session: z.string().optional().describe("Session ID. Omit for the default session.")
+      }
+    },
+    async ({ speed, session }) => {
+      const info = await sessions.setSpeed(session, speed);
+      return { content: [{ type: "text", text: `set "${info.id}" speed to ${speed}` }] };
+    }
+  );
+  server.registerTool(
+    "human_set_viewport",
+    {
+      title: "Resize the viewport",
+      description: "Resizes a session's browser viewport at runtime. Use for a bigger/crisper recording or to test responsive layouts. The default size for new sessions is set by HUMANJS_VIEWPORT (default 1440\xD7900).",
+      inputSchema: {
+        width: z.number().int().positive().describe("Viewport width in CSS px."),
+        height: z.number().int().positive().describe("Viewport height in CSS px."),
+        session: z.string().optional().describe("Session ID. Omit for the default session.")
+      }
+    },
+    async ({ width, height, session }) => {
+      const { human } = await sessions.get(session);
+      await human.setViewportSize({ width, height });
+      return { content: [{ type: "text", text: `viewport set to ${width}\xD7${height}` }] };
+    }
+  );
+}
+function resolveOutputPath(outputDir, filename) {
+  const base = basename(filename);
+  if (base !== filename || base.length === 0) {
+    throw new Error(
+      `filename must be a plain name with no path components, got "${filename}". Files are always written to HUMANJS_OUTPUT_DIR.`
+    );
+  }
+  return join(outputDir, base);
+}
+
+// src/tools/inspection.ts
+var sessionArg = z.string().optional().describe("Session ID to act on. Omit to use the default session.");
+function registerInspectionTools(server, ctx) {
+  server.registerTool(
+    "human_screenshot",
+    {
+      title: "Screenshot the current page",
+      description: "Captures the current page (or a specific element if `selector` is given) as a PNG and returns it as image content the AI can view directly. Pass `filename` to also save it to disk (HUMANJS_OUTPUT_DIR); omit it for an ephemeral look-at-the-page capture.",
+      inputSchema: {
+        selector: z.string().optional().describe("Optional selector. If omitted, captures the entire viewport."),
+        fullPage: z.boolean().optional().describe(
+          "Capture the full scrollable page instead of just the viewport. Ignored if `selector` is set."
+        ),
+        filename: z.string().optional().describe(
+          'Optional plain filename (e.g. "homepage.png"). When set, the screenshot is saved to HUMANJS_OUTPUT_DIR. Path components are rejected for safety.'
+        ),
+        session: sessionArg
+      }
+    },
+    async ({ selector, fullPage, filename, session }) => {
+      const { human, page } = await ctx.sessions.get(session);
+      const buffer = selector ? await page.locator(selector).screenshot() : await human.screenshot({ fullPage: fullPage ?? false });
+      const content = [{ type: "image", data: buffer.toString("base64"), mimeType: "image/png" }];
+      if (filename) {
+        const path = resolveOutputPath(ctx.env.outputDir, filename);
+        await writeFile(path, buffer);
+        content.push({ type: "text", text: `saved screenshot to ${path}` });
+      }
+      return { content };
+    }
+  );
+  server.registerTool(
+    "human_page_text",
+    {
+      title: "Get visible page text",
+      description: "Returns the page's visible text (document.body.innerText). The fastest way to understand what's on screen without parsing HTML \u2014 prefer this over human_get_html unless you need element structure or attributes.",
+      inputSchema: { session: sessionArg }
+    },
+    async ({ session }) => {
+      const { human } = await ctx.sessions.get(session);
+      const text = await human.pageText();
+      return { content: [{ type: "text", text }] };
+    }
+  );
+  server.registerTool(
+    "human_get_text",
+    {
+      title: "Get an element's text",
+      description: "Returns the visible innerText of the first element matching `selector`. Use to read a specific label, price, status, or message.",
+      inputSchema: {
+        selector: z.string().describe("Selector of the element to read."),
+        session: sessionArg
+      }
+    },
+    async ({ selector, session }) => {
+      const { page } = await ctx.sessions.get(session);
+      const text = await page.locator(selector).innerText();
+      return { content: [{ type: "text", text }] };
+    }
+  );
+  server.registerTool(
+    "human_get_attribute",
+    {
+      title: "Get an element's attribute",
+      description: "Returns the value of an attribute on the first element matching `selector` (or reports it is absent). Handy for reading aria-label, data-*, href, value, disabled state, etc. \u2014 often how you confirm an icon-only button's purpose.",
+      inputSchema: {
+        selector: z.string().describe("Selector of the element."),
+        attribute: z.string().describe('Attribute name, e.g. "aria-label", "href", "data-state".'),
+        session: sessionArg
+      }
+    },
+    async ({ selector, attribute, session }) => {
+      const { page } = await ctx.sessions.get(session);
+      const value = await page.locator(selector).getAttribute(attribute);
+      const text = value === null ? `${selector} has no attribute "${attribute}"` : `${attribute}="${value}"`;
+      return { content: [{ type: "text", text }] };
+    }
+  );
+  server.registerTool(
+    "human_get_html",
+    {
+      title: "Get an element's HTML",
+      description: "Returns the outerHTML of the first element matching `selector` \u2014 the element plus its children, including its own attributes (class, aria-label, etc.). The go-to tool for discovering the real selector of a control with no obvious text. Target a specific region; full-page HTML is large.",
+      inputSchema: {
+        selector: z.string().describe("Selector of the region to dump. Target narrowly."),
+        session: sessionArg
+      }
+    },
+    async ({ selector, session }) => {
+      const { page } = await ctx.sessions.get(session);
+      const html = await page.locator(selector).evaluate((el) => el.outerHTML);
+      return { content: [{ type: "text", text: html }] };
+    }
+  );
+}
+var targetFields = {
+  selector: z.string().optional().describe(
+    "Playwright-compatible selector. Provide this OR x/y \u2014 not both. Prefer role/text selectors over brittle CSS."
+  ),
+  x: z.number().optional().describe(
+    "X coordinate (CSS px from viewport left). Use x+y when there is no clean selector \u2014 e.g. an icon-only button you can see in a screenshot. Requires y."
+  ),
+  y: z.number().optional().describe("Y coordinate (CSS px from viewport top). Requires x.")
+};
+function resolveTarget(input) {
+  const hasSelector = input.selector !== void 0;
+  const hasPoint = input.x !== void 0 && input.y !== void 0;
+  if (hasSelector && hasPoint) {
+    throw new Error("Provide either a selector or x/y coordinates, not both.");
+  }
+  if (hasSelector) return input.selector;
+  if (hasPoint) return { x: input.x, y: input.y };
+  if (input.x !== void 0 || input.y !== void 0) {
+    throw new Error("Coordinate targets need both x and y.");
+  }
+  throw new Error("Provide a selector or x/y coordinates.");
+}
+
+// src/tools/primitives.ts
+var sessionArg2 = z.string().optional().describe(
+  "Session ID to act on. Omit to use the default session (created lazily on first call). Use human_create_session for parallel browsers."
+);
+function registerPrimitiveTools(server, { sessions }) {
+  server.registerTool(
+    "human_goto",
+    {
+      title: "Navigate to URL",
+      description: `Navigates the session's page to a URL. Plugins observe a "goto" action. Equivalent to a user typing a URL in the address bar.`,
+      inputSchema: {
+        url: z.string().url().describe("Absolute URL to navigate to."),
+        session: sessionArg2
+      }
+    },
+    async ({ url, session }) => {
+      const { human } = await sessions.get(session);
+      await human.goto(url);
+      return { content: [{ type: "text", text: `navigated to ${url}` }] };
+    }
+  );
+  server.registerTool(
+    "human_click",
+    {
+      title: "Click (humanized)",
+      description: "Moves the cursor to the target along a humanized Bezier path and clicks. Target is a selector OR x/y coordinates \u2014 use coordinates for icon-only buttons or anything with no clean selector that you can see in a screenshot.",
+      inputSchema: { ...targetFields, session: sessionArg2 }
+    },
+    async ({ selector, x, y, session }) => {
+      const { human } = await sessions.get(session);
+      const target = resolveTarget({ selector, x, y });
+      await human.click(target);
+      return { content: [{ type: "text", text: `clicked ${describeTarget(selector, x, y)}` }] };
+    }
+  );
+  server.registerTool(
+    "human_rightClick",
+    {
+      title: "Right-click (humanized)",
+      description: "Right-clicks the target to open a context menu. Same motion as human_click; only the dispatched button differs. Target is a selector OR x/y coordinates.",
+      inputSchema: { ...targetFields, session: sessionArg2 }
+    },
+    async ({ selector, x, y, session }) => {
+      const { human } = await sessions.get(session);
+      const target = resolveTarget({ selector, x, y });
+      await human.rightClick(target);
+      return {
+        content: [{ type: "text", text: `right-clicked ${describeTarget(selector, x, y)}` }]
+      };
+    }
+  );
+  server.registerTool(
+    "human_hover",
+    {
+      title: "Hover an element (humanized)",
+      description: "Moves the cursor to an element and settles on it (no click), letting hover-triggered UI fire \u2014 tooltips, dropdowns. Element-bound only; for positioning the cursor at coordinates without an element, use human_move.",
+      inputSchema: {
+        selector: z.string().describe("Selector of the element to hover."),
+        session: sessionArg2
+      }
+    },
+    async ({ selector, session }) => {
+      const { human } = await sessions.get(session);
+      await human.hover(selector);
+      return { content: [{ type: "text", text: `hovered ${selector}` }] };
+    }
+  );
+  server.registerTool(
+    "human_move",
+    {
+      title: "Move the cursor (humanized)",
+      description: "Moves the cursor to a target along a Bezier path with no click and no settle dwell \u2014 pure positioning. Useful before a keyboard action, for canvas work, or cinematic beats. Target is a selector OR x/y coordinates.",
+      inputSchema: { ...targetFields, session: sessionArg2 }
+    },
+    async ({ selector, x, y, session }) => {
+      const { human } = await sessions.get(session);
+      const target = resolveTarget({ selector, x, y });
+      await human.move(target);
+      return { content: [{ type: "text", text: `moved to ${describeTarget(selector, x, y)}` }] };
+    }
+  );
+  server.registerTool(
+    "human_drag",
+    {
+      title: "Drag (humanized)",
+      description: "Drags from one location to another \u2014 cursor \u2192 source, mousedown, source \u2192 destination, mouseup, all humanized. Each endpoint is a selector OR x/y coordinates (use coordinates for sliders, canvas, SVG handles).",
+      inputSchema: {
+        fromSelector: z.string().optional().describe("Source selector. Provide this OR fromX/fromY."),
+        fromX: z.number().optional().describe("Source X coordinate. Requires fromY."),
+        fromY: z.number().optional().describe("Source Y coordinate. Requires fromX."),
+        toSelector: z.string().optional().describe("Destination selector. Provide this OR toX/toY."),
+        toX: z.number().optional().describe("Destination X coordinate. Requires toY."),
+        toY: z.number().optional().describe("Destination Y coordinate. Requires toX."),
+        session: sessionArg2
+      }
+    },
+    async ({ fromSelector, fromX, fromY, toSelector, toX, toY, session }) => {
+      const { human } = await sessions.get(session);
+      const from = resolveTarget({ selector: fromSelector, x: fromX, y: fromY });
+      const to = resolveTarget({ selector: toSelector, x: toX, y: toY });
+      await human.drag(from, to);
+      return {
+        content: [
+          {
+            type: "text",
+            text: `dragged ${describeTarget(fromSelector, fromX, fromY)} \u2192 ${describeTarget(toSelector, toX, toY)}`
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "human_type",
+    {
+      title: "Type text (humanized)",
+      description: "Clicks the element to focus it, then types with humanized per-key rhythm. The current personality controls speed, typo probability, and corrections (HUMANJS_PERSONALITY / human_set_personality). If this types into a search/filter, the results re-render (often debounced) \u2014 use a specific selector for the result, as the list shifts as it filters.",
+      inputSchema: {
+        selector: z.string().describe("Selector of the input/textarea/contenteditable."),
+        value: z.string().describe("Text to type. May contain newlines."),
+        session: sessionArg2
+      }
+    },
+    async ({ selector, value, session }) => {
+      const { human } = await sessions.get(session);
+      await human.type(selector, value);
+      return { content: [{ type: "text", text: `typed ${value.length} chars into ${selector}` }] };
+    }
+  );
+  server.registerTool(
+    "human_paste",
+    {
+      title: "Paste text (one shot)",
+      description: "Inserts text in one shot (the Cmd-V semantic) \u2014 focuses the field, then sets the whole value via insertText with no per-key timing. Use for long strings where humanized typing would be slow. Does not fire the page paste event.",
+      inputSchema: {
+        selector: z.string().describe("Selector of the field to paste into."),
+        value: z.string().describe("Text to insert."),
+        session: sessionArg2
+      }
+    },
+    async ({ selector, value, session }) => {
+      const { human } = await sessions.get(session);
+      await human.paste(selector, value);
+      return { content: [{ type: "text", text: `pasted ${value.length} chars into ${selector}` }] };
+    }
+  );
+  server.registerTool(
+    "human_press",
+    {
+      title: "Press a key or chord",
+      description: 'Presses a single key (Enter, Tab, Escape, ArrowDown, \u2026) or a chord (Mod+S, Cmd+Shift+P, Ctrl+C). "Mod" maps to Meta on Mac and Control elsewhere. Dispatches against focus \u2014 does not move the cursor; compose with human_click/human_move when you need both.',
+      inputSchema: {
+        key: z.string().describe('Key or chord, e.g. "Enter", "Tab", "Mod+S", "Ctrl+Shift+K".'),
+        session: sessionArg2
+      }
+    },
+    async ({ key, session }) => {
+      const { human } = await sessions.get(session);
+      await human.press(key);
+      return { content: [{ type: "text", text: `pressed ${key}` }] };
+    }
+  );
+  server.registerTool(
+    "human_scroll",
+    {
+      title: "Scroll (humanized)",
+      description: 'Scrolls the page or a container with a natural velocity profile. Default scrolls one viewport down. Use `target` for presets ("natural"/"end"/"top") or an element selector to scroll into view; `by` for a relative pixel delta; `to` for an absolute position.',
+      inputSchema: {
+        target: z.string().optional().describe(
+          'One of "natural" (one viewport), "end", "top", or an element selector to scroll until visible. Defaults to "natural". Ignored if `by` or `to` is set.'
+        ),
+        by: z.number().optional().describe("Relative pixel delta (negative = up/left)."),
+        to: z.number().optional().describe("Absolute scroll position on the chosen axis."),
+        axis: z.enum(["x", "y"]).optional().describe('Axis to scroll. Defaults to "y".'),
+        within: z.string().optional().describe("Selector of a scrollable container to scope the scroll to."),
+        session: sessionArg2
+      }
+    },
+    async ({ target, by, to, axis, within, session }) => {
+      const { human } = await sessions.get(session);
+      const scrollTarget = by !== void 0 ? { by } : to !== void 0 ? { to } : target ?? "natural";
+      const result = await human.scroll(scrollTarget, { axis, within });
+      return {
+        content: [
+          { type: "text", text: `scrolled ${result.from} \u2192 ${result.to} (${result.distance}px)` }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "human_read",
+    {
+      title: "Read dwell (humanized)",
+      description: `Dwells as if reading the target \u2014 pause time derived from word count and the personality's reading speed, with a visible cursor scan across the text. Models the "user pauses to read" beat. Provide a selector OR literal text.`,
+      inputSchema: {
+        selector: z.string().optional().describe("Selector of the text to read. Provide this OR text."),
+        text: z.string().optional().describe('Literal text to "read" (no DOM lookup). Provide this OR selector.'),
+        kind: z.enum(["prose", "code", "scan"]).optional().describe('Reading style. Auto-detected as "code" for <pre>/<code> when omitted.'),
+        session: sessionArg2
+      }
+    },
+    async ({ selector, text, kind, session }) => {
+      const { human } = await sessions.get(session);
+      if (selector === void 0 && text === void 0) {
+        throw new Error("Provide a selector or text to read.");
+      }
+      const readTarget = text !== void 0 ? { text } : selector;
+      const result = await human.read(readTarget, { kind });
+      return {
+        content: [
+          {
+            type: "text",
+            text: `read ${result.words} words (${result.kind}) over ${result.durationMs}ms`
+          }
+        ]
+      };
+    }
+  );
+}
+function describeTarget(selector, x, y) {
+  if (selector !== void 0) return selector;
+  if (x !== void 0 && y !== void 0) return `(${x}, ${y})`;
+  return "target";
+}
+function registerRecordingTools(server, { sessions, env }) {
+  server.registerTool(
+    "human_start_recording",
+    {
+      title: "Start recording",
+      description: "Begins recording the session. Every humanized action until human_stop_recording is captured (frames + action timeline). The visible cursor is in the video. One recording per session at a time. For a natural-looking take: explore the flow first to find correct selectors, then dispatch the whole run \u2014 start_recording + every action + stop_recording \u2014 in a SINGLE turn (one batch of tool calls), so there are no model-thinking pauses between actions to leave dead air in the video.",
+      inputSchema: {
+        name: z.string().optional().describe("Label for the recording (used in the timeline + the fallback filename)."),
+        video: z.boolean().optional().describe("Capture video frames. Default true. Set false for a timeline-only recording."),
+        quality: z.enum(["fast", "standard", "high", "lossless"]).optional().describe('Capture/encode quality. Default "high" (1080p, visually lossless).'),
+        session: z.string().optional().describe("Session ID. Omit for the default session.")
+      }
+    },
+    async ({ name, video, quality, session }) => {
+      await sessions.startRecording(session, { name, video, quality });
+      return {
+        content: [{ type: "text", text: `recording started${name ? ` ("${name}")` : ""}` }]
+      };
+    }
+  );
+  server.registerTool(
+    "human_stop_recording",
+    {
+      title: "Stop recording and save",
+      description: `Stops the active recording and writes it to one or more files in HUMANJS_OUTPUT_DIR. Each filename's extension picks its format: .mp4/.webm = video, .gif = animated gif, .json = action timeline. Pass several to export the same recording multiple ways, e.g. ["demo.mp4", "demo.json"] for video + timeline. Path components are rejected for safety.`,
+      inputSchema: {
+        filenames: z.array(z.string()).min(1).describe(
+          'One or more output filenames. The recording is saved to each, format chosen by extension. e.g. ["demo.mp4"] or ["demo.mp4", "demo.gif", "demo.json"].'
+        ),
+        session: z.string().optional().describe("Session ID. Omit for the default session.")
+      }
+    },
+    async ({ filenames, session }) => {
+      const targets = filenames.map((filename) => ({
+        path: resolveOutputPath(env.outputDir, filename),
+        ext: extname(filename).toLowerCase()
+      }));
+      for (const { ext } of targets) {
+        if (ext !== ".mp4" && ext !== ".webm" && ext !== ".gif" && ext !== ".json") {
+          throw new Error(
+            `Unsupported output extension "${ext}". Use .mp4, .webm, .gif, or .json.`
+          );
+        }
+      }
+      const recording = await sessions.stopRecording(session);
+      try {
+        const saved = [];
+        for (const { path, ext } of targets) {
+          if (ext === ".gif") saved.push(await recording.toGif(path));
+          else if (ext === ".json") saved.push(await recording.toTimeline(path));
+          else saved.push(await recording.toVideo(path));
+        }
+        return { content: [{ type: "text", text: `saved recording to:
+${saved.join("\n")}` }] };
+      } finally {
+        await recording.dispose();
+      }
+    }
+  );
+}
+var personalityArg = z.enum(["careful", "fast", "distracted", "precise"]).optional().describe("Personality preset for this session. Defaults to HUMANJS_PERSONALITY.");
+var speedArg = z.enum(["human", "fast", "instant"]).optional().describe(
+  'Humanization pace. "human" (default) = full realistic motion; "fast" = humanized but quick; "instant" = no humanized motion. Defaults to HUMANJS_SPEED.'
+);
+function registerSessionTools(server, { sessions }) {
+  server.registerTool(
+    "human_create_session",
+    {
+      title: "Create a browser session",
+      description: "Opens a new isolated session (its own browser context, cookies, viewport) under the given ID. Only needed for parallel browsers \u2014 for a single browser, just omit the session arg on other tools and the default session is used.",
+      inputSchema: {
+        id: z.string().describe('Unique session ID, e.g. "buyer", "seller".'),
+        personality: personalityArg,
+        speed: speedArg,
+        width: z.number().int().positive().optional().describe("Viewport width in CSS px. Defaults to HUMANJS_VIEWPORT. Requires height."),
+        height: z.number().int().positive().optional().describe("Viewport height in CSS px. Requires width.")
+      }
+    },
+    async ({ id, personality, speed, width, height }) => {
+      if (width === void 0 !== (height === void 0)) {
+        throw new Error("Provide both width and height, or neither.");
+      }
+      const viewport = width !== void 0 && height !== void 0 ? { width, height } : void 0;
+      const session = await sessions.create(id, { personality, speed, viewport });
+      return {
+        content: [
+          {
+            type: "text",
+            text: `created session "${session.id}" (personality: ${session.personality}, speed: ${session.speed})`
+          }
+        ]
+      };
+    }
+  );
+  server.registerTool(
+    "human_close_session",
+    {
+      title: "Close a browser session",
+      description: "Closes a session and frees its browser context. Closing the default session is allowed \u2014 it will be recreated lazily on the next call.",
+      inputSchema: {
+        id: z.string().describe("Session ID to close.")
+      }
+    },
+    async ({ id }) => {
+      await sessions.close(id);
+      return { content: [{ type: "text", text: `closed session "${id}"` }] };
+    }
+  );
+  server.registerTool(
+    "human_list_sessions",
+    {
+      title: "List open sessions",
+      description: "Lists every currently-open session with its personality. Use to orient before acting on a specific session.",
+      inputSchema: {}
+    },
+    async () => {
+      const list = sessions.list();
+      const text = list.length === 0 ? "no open sessions (the default session is created on first action)" : list.map((s) => `${s.id} (personality: ${s.personality}, speed: ${s.speed})`).join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+}
+
+// src/index.ts
+var SERVER_NAME = "humanjs-mcp";
+var SERVER_VERSION = "0.1.0";
+var SERVER_INSTRUCTIONS = `HumanJS drives a real browser with humanized motion, typing, and reading dwell. Motion is already realistic at the default speed \u2014 do NOT switch to 'fast'/'instant' or change personality to make a flow "look natural"; it already does.
+
+DISPATCH KNOWN STEPS TOGETHER. When you already know the full sequence (a recording, or any flow you've mapped out), emit ALL the tool calls in a SINGLE turn, back-to-back, WITHOUT pausing to reason between them. This matters a lot: each model turn between actions is a multi-second gap, which is slow in general and shows up as dead air in a recording. The humanized motion paces the actions on its own \u2014 don't add thinking gaps on top. Only go one tool at a time when a step genuinely needs the previous step's result (exploring, or reacting to something you can't predict).
+
+Recording a flow (the natural-looking way):
+1. EXPLORE FIRST (un-recorded). Navigate the flow once to discover correct, unambiguous selectors (human_screenshot / human_get_html / human_get_attribute). Do this by default whenever the selectors aren't already known \u2014 no need for the user to ask. Skip it only if the selectors are already known or the user tells you not to explore.
+2. THEN RECORD ONE CLEAN RUN AS A SINGLE BATCH: human_start_recording + every action + human_stop_recording, all emitted in one turn. Keep selector-guessing and fumbles out of the take.
+
+Dynamic UI: prefer specific selectors (role, aria-label) over text \u2014 the same visible text often matches several cards before a filter, or the wrong one after. If a click reports multiple matches, narrow the selector.
+
+Browser state: by default each run is a fresh, signed-out browser. If a flow needs a login, tell the user to enable persistence (human_enable_persistence or HUMANJS_PERSIST) or CDP attach \u2014 see human_browser_info.`;
+async function main() {
+  const env = readEnv();
+  const sessions = new SessionManager(env);
+  const ctx = { sessions, env };
+  const server = new McpServer(
+    { name: SERVER_NAME, version: SERVER_VERSION },
+    { instructions: SERVER_INSTRUCTIONS }
+  );
+  registerPrimitiveTools(server, ctx);
+  registerInspectionTools(server, ctx);
+  registerRecordingTools(server, ctx);
+  registerSessionTools(server, ctx);
+  registerConfigTools(server, ctx);
+  registerBrowserTools(server, ctx);
+  const shutdown = async () => {
+    try {
+      await sessions.closeAll();
+    } finally {
+      process.exit(0);
+    }
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((error) => {
+  console.error("[humanjs-mcp] fatal:", error);
+  process.exit(1);
+});
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map