@humanjs/mcp 0.2.0 → 0.4.0

package/dist/index.js

@@ -20,6 +20,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(),
@@ -589,6 +590,15 @@ function resolveOutputPath(outputDir, filename) {
   }
   return join(outputDir, base);
 }
+function resolveUploadPath(uploadDir, filename) {
+  const base = 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 join(uploadDir, base);
+}
 function resolveRecordingFormat(filename) {
   const lower = filename.toLowerCase();
   if (lower.endsWith(".mp4") || lower.endsWith(".webm")) return "video";
@@ -643,6 +653,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: 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",
     {
@@ -721,7 +747,7 @@ function resolveTarget(input) {
 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 }) {
+function registerPrimitiveTools(server, { sessions, env }) {
   server.registerTool(
     "human_goto",
     {
@@ -768,6 +794,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",
     {
@@ -862,6 +904,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: 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: z.string().describe("Selector of the element whose text to select."),
+        text: 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: 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: 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: z.string().describe("Selector of the <select> element."),
+        values: z.union([z.string(), z.array(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: z.string().describe("Selector of the file input."),
+        files: z.union([z.string(), z.array(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",
     {