@humanjs/mcp 0.2.0 → 0.4.0

package/README.md

@@ -71,6 +71,7 @@ The `config` payload is base64 of `{"command":"npx","args":["-y","@humanjs/mcp"]
 | `HUMANJS_SPEED` | `human` \| `fast` \| `instant` | `human` | Humanization pace. `human` = full realistic motion; `fast` = humanized but quick; `instant` = no humanized motion. Changes how long each action *executes*, not the wait between actions. |
 | `HUMANJS_HEADLESS` | `true` \| `false` | `false` | Headless browser. Default is visible — the point of the MCP. |
 | `HUMANJS_OUTPUT_DIR` | path | server's CWD | Where screenshots and recordings are written. |
+| `HUMANJS_UPLOAD_DIR` | path | server's CWD | Folder `human_upload` reads files from (basename only — can't escape it). |
 | `HUMANJS_VIEWPORT` | `WIDTHxHEIGHT` | `1440x900` | Default viewport for new sessions. Bump to `1920x1080` for crisper recordings. |
 | `HUMANJS_AUTO_INSTALL` | `true` \| `false` | `true` | Auto-download the Chromium binary on first launch if missing. Set `false` to require a manual `npx playwright install chromium`. |
 | `HUMANJS_PERSIST` | `true` \| `false` | `false` | Persist a profile across runs (logins/cookies survive). Uses `~/.humanjs/profile` unless `HUMANJS_USER_DATA_DIR` is set. See [Browser modes](#browser-modes). |
@@ -232,6 +233,7 @@ The server ships **built-in guidance** (sent to the agent on connect via MCP `in
 
 - **No arbitrary-JS `evaluate` tool.** Executing page-supplied JavaScript is a prompt-injection cliff — a malicious page could trick the agent into running code that exfiltrates data. The read-only inspection tools cover the legitimate "what's on the page" need.
 - **File-path safety.** Tools that write files accept a basename only; path components (`../`, absolute paths) are rejected, so a prompt-injected filename can't escape `HUMANJS_OUTPUT_DIR`.
+- **Upload path safety.** `human_upload` can attach a local file to a web form — a potential exfiltration path if a page prompt-injects the agent. So it reads files by **basename only** from `HUMANJS_UPLOAD_DIR` (default: the server's working dir); subdirectories, `../`, and absolute paths are rejected, so the agent can't reach (and send) files outside that folder. Point `HUMANJS_UPLOAD_DIR` at where your upload fixtures live.
 - **No credentials handling.** The server drives the browser; it doesn't manage logins, payment details, or secrets on your behalf.
 - **Attaching to your real browser (CDP) is opt-in and env-only.** When you point `HUMANJS_CDP_URL` at your running browser, the agent acts with *your* live sessions — a bigger blast radius if a page tries to manipulate it. That's why it's a deliberate config choice you make up front, never something a tool can switch on.
 

package/dist/index.cjs

@@ -23,6 +23,7 @@ function readEnv() {
     speed: parseSpeed(process.env.HUMANJS_SPEED),
     headless: parseBool(process.env.HUMANJS_HEADLESS, false),
     outputDir: process.env.HUMANJS_OUTPUT_DIR ?? process.cwd(),
+    uploadDir: process.env.HUMANJS_UPLOAD_DIR ?? process.cwd(),
     viewport: parseViewport(process.env.HUMANJS_VIEWPORT),
     autoInstall: parseBool(process.env.HUMANJS_AUTO_INSTALL, true),
     browser: resolveBrowserConfig(),
@@ -592,6 +593,15 @@ function resolveOutputPath(outputDir, filename) {
   }
   return path.join(outputDir, base);
 }
+function resolveUploadPath(uploadDir, filename) {
+  const base = path.basename(filename);
+  if (base !== filename || base.length === 0) {
+    throw new Error(
+      `upload filename must be a plain name with no path components, got "${filename}". Files are read from HUMANJS_UPLOAD_DIR \u2014 place the file there (or point HUMANJS_UPLOAD_DIR at its folder) and pass just the name.`
+    );
+  }
+  return path.join(uploadDir, base);
+}
 function resolveRecordingFormat(filename) {
   const lower = filename.toLowerCase();
   if (lower.endsWith(".mp4") || lower.endsWith(".webm")) return "video";
@@ -646,6 +656,22 @@ function registerInspectionTools(server, ctx) {
       return { content: [{ type: "text", text }] };
     }
   );
+  server.registerTool(
+    "human_outline",
+    {
+      title: "Page outline (accessibility tree)",
+      description: 'Returns a compact accessibility-tree outline of the page (or a region) \u2014 every interactive element and landmark by its ARIA role + accessible name, as YAML (e.g. `- button "Sign in"`, `- textbox "Email"`). The most token-efficient way to see what is actionable and pick a selector: the names map directly to getByRole / accessible-name selectors. Prefer this over human_get_html for "what can I click or fill"; use human_screenshot when you need the visual layout.',
+      inputSchema: {
+        selector: zod.z.string().optional().describe("Optional region selector to scope the outline. Omit for the whole page."),
+        session: sessionArg
+      }
+    },
+    async ({ selector, session }) => {
+      const { human } = await ctx.sessions.get(session);
+      const text = await human.outline(selector);
+      return { content: [{ type: "text", text }] };
+    }
+  );
   server.registerTool(
     "human_get_text",
     {
@@ -724,7 +750,7 @@ function resolveTarget(input) {
 var sessionArg2 = zod.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 }) {
+function registerPrimitiveTools(server, { sessions, env }) {
   server.registerTool(
     "human_goto",
     {
@@ -771,6 +797,22 @@ function registerPrimitiveTools(server, { sessions }) {
       };
     }
   );
+  server.registerTool(
+    "human_doubleClick",
+    {
+      title: "Double-click (humanized)",
+      description: "Double-clicks the target \u2014 same humanized motion as human_click, but two presses within the OS double-click window. Use for things that open/activate on double-click (list rows, file items, editable cells). 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.doubleClick(target);
+      return {
+        content: [{ type: "text", text: `double-clicked ${describeTarget(selector, x, y)}` }]
+      };
+    }
+  );
   server.registerTool(
     "human_hover",
     {
@@ -865,6 +907,112 @@ function registerPrimitiveTools(server, { sessions }) {
       return { content: [{ type: "text", text: `pasted ${value.length} chars into ${selector}` }] };
     }
   );
+  server.registerTool(
+    "human_clear",
+    {
+      title: "Clear a field (humanized)",
+      description: "Clears a text field (input/textarea/contenteditable) with a real keyboard gesture \u2014 click to focus, select-all, then delete \u2014 firing the input events the page expects. Use before human_type when you need to replace an existing value rather than append to it.",
+      inputSchema: {
+        selector: zod.z.string().describe("Selector of the field to clear."),
+        session: sessionArg2
+      }
+    },
+    async ({ selector, session }) => {
+      const { human } = await sessions.get(session);
+      await human.clear(selector);
+      return { content: [{ type: "text", text: `cleared ${selector}` }] };
+    }
+  );
+  server.registerTool(
+    "human_selectText",
+    {
+      title: "Select an element\u2019s text (humanized)",
+      description: "Selects (highlights) text inside an element \u2014 moves the cursor to it, then selects. By default selects all of the element\u2019s text; pass `text` to select just that substring (found inside the element, whitespace-tolerant, first match; falls back to the whole element if not found). Use before copying, replacing, or triggering a highlight menu.",
+      inputSchema: {
+        selector: zod.z.string().describe("Selector of the element whose text to select."),
+        text: zod.z.string().optional().describe("Optional substring to select instead of the element\u2019s whole text."),
+        session: sessionArg2
+      }
+    },
+    async ({ selector, text, session }) => {
+      const { human } = await sessions.get(session);
+      await human.selectText(selector, text === void 0 ? void 0 : { text });
+      const what = text === void 0 ? "text" : `"${text}"`;
+      return { content: [{ type: "text", text: `selected ${what} in ${selector}` }] };
+    }
+  );
+  server.registerTool(
+    "human_check",
+    {
+      title: "Check a box (humanized)",
+      description: "Ticks a checkbox or radio \u2014 moves the cursor to it and clicks, but only if it is not already checked (a real user does not re-click a ticked box). Verifies the resulting state. Pass the checkbox/radio input itself (or a [role=checkbox]) \u2014 not a wrapping <label> \u2014 so the current state can be read and the click stays idempotent.",
+      inputSchema: {
+        selector: zod.z.string().describe("Selector of the checkbox/radio input."),
+        session: sessionArg2
+      }
+    },
+    async ({ selector, session }) => {
+      const { human } = await sessions.get(session);
+      await human.check(selector);
+      return { content: [{ type: "text", text: `checked ${selector}` }] };
+    }
+  );
+  server.registerTool(
+    "human_uncheck",
+    {
+      title: "Uncheck a box (humanized)",
+      description: "Unticks a checkbox \u2014 humanized click only if currently checked. Radios cannot be unchecked by clicking (select a different option instead). Pass the checkbox input itself (or a [role=checkbox]) \u2014 not a wrapping <label> \u2014 so its state can be read and the click stays idempotent.",
+      inputSchema: {
+        selector: zod.z.string().describe("Selector of the checkbox input."),
+        session: sessionArg2
+      }
+    },
+    async ({ selector, session }) => {
+      const { human } = await sessions.get(session);
+      await human.uncheck(selector);
+      return { content: [{ type: "text", text: `unchecked ${selector}` }] };
+    }
+  );
+  server.registerTool(
+    "human_selectOption",
+    {
+      title: "Select dropdown option (humanized)",
+      description: "Chooses option(s) in a native <select> \u2014 moves the cursor to the dropdown, then sets the value (native selects open an OS menu automation can't drive, so the value is set programmatically, firing change/input). For custom DOM dropdowns, use human_click on the rendered options instead. Match by value(s); pass one string or an array for multi-selects.",
+      inputSchema: {
+        selector: zod.z.string().describe("Selector of the <select> element."),
+        values: zod.z.union([zod.z.string(), zod.z.array(zod.z.string())]).describe("Option value, or array of values for a multi-select."),
+        session: sessionArg2
+      }
+    },
+    async ({ selector, values, session }) => {
+      const { human } = await sessions.get(session);
+      const selected = await human.selectOption(selector, values);
+      return {
+        content: [{ type: "text", text: `selected ${selected.join(", ")} in ${selector}` }]
+      };
+    }
+  );
+  server.registerTool(
+    "human_upload",
+    {
+      title: "Upload file(s) (humanized)",
+      description: `Attaches file(s) to a file input \u2014 moves the cursor to the control, then sets the files (never opens the OS dialog, which would hang). For safety, files are read by basename from HUMANJS_UPLOAD_DIR (default: the server working dir) \u2014 subdirectories, "../", and absolute paths are rejected, so the agent can't read and exfiltrate arbitrary local files. Pass the <input type="file"> selector and the filename(s).`,
+      inputSchema: {
+        selector: zod.z.string().describe("Selector of the file input."),
+        files: zod.z.union([zod.z.string(), zod.z.array(zod.z.string())]).describe("Filename(s) inside HUMANJS_UPLOAD_DIR \u2014 a basename only, no path components."),
+        session: sessionArg2
+      }
+    },
+    async ({ selector, files, session }) => {
+      const { human } = await sessions.get(session);
+      const names = Array.isArray(files) ? files : [files];
+      const paths = names.map((name) => resolveUploadPath(env.uploadDir, name));
+      await human.upload(selector, paths);
+      return {
+        content: [{ type: "text", text: `uploaded ${paths.length} file(s) to ${selector}` }]
+      };
+    }
+  );
   server.registerTool(
     "human_press",
     {