@humanjs/mcp 0.1.0 → 0.2.0

package/README.md

@@ -48,10 +48,15 @@ Some clients can register the server for you, no manual JSON:
 **Claude Code:**
 
 ```bash
+# this project only (default scope: local)
 claude mcp add humanjs --env HUMANJS_PERSONALITY=careful -- npx -y @humanjs/mcp
-# add --scope user to install it globally (all projects)
+
+# all your projects (global): add --scope user (-s user)
+claude mcp add humanjs --scope user --env HUMANJS_PERSONALITY=careful -- npx -y @humanjs/mcp
 ```
 
+`--scope` is `local` (default, this project only), `user` (you, across all projects), or `project` (shared via a checked-in `.mcp.json`). Use `user` for a one-time global install.
+
 **Cursor** — one click:
 
 [![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=humanjs&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBodW1hbmpzL21jcCJdfQ==)
@@ -128,7 +133,7 @@ Click / rightClick / move / drag take a **selector or raw x/y coordinates** —
 | Tool | What it does |
 |---|---|
 | `human_start_recording` | Begin capturing (frames + action timeline) |
-| `human_stop_recording` | Finalize and write one or more files — `.mp4` / `.webm` / `.gif` / `.json` (e.g. video + timeline from one recording) |
+| `human_stop_recording` | Finalize and write one or more files — `.mp4` / `.webm` (video), `.gif`, `.json` (timeline), `.ts` (HumanJS script), `.spec.ts` / `.test.ts` (Playwright test). Pass several to export multiple ways, e.g. a video + a ready-to-commit test |
 
 **Sessions** — only needed for parallel browsers; the default session is implicit:
 

package/dist/index.cjs

@@ -192,7 +192,10 @@ var SessionManager = class {
       stop = resolve;
     });
     const video = options.video ?? true;
-    const done = session.human.record({ video, quality: options.quality ?? "high" }, () => signal);
+    const done = session.human.record(
+      { name: options.name, video, quality: options.quality ?? "high" },
+      () => signal
+    );
     session.recording = {
       name: options.name ?? "recording",
       startedAt: Date.now(),
@@ -589,6 +592,15 @@ function resolveOutputPath(outputDir, filename) {
   }
   return path.join(outputDir, base);
 }
+function resolveRecordingFormat(filename) {
+  const lower = filename.toLowerCase();
+  if (lower.endsWith(".mp4") || lower.endsWith(".webm")) return "video";
+  if (lower.endsWith(".gif")) return "gif";
+  if (lower.endsWith(".json")) return "timeline";
+  if (lower.endsWith(".spec.ts") || lower.endsWith(".test.ts")) return "playwright";
+  if (lower.endsWith(".ts")) return "humanjs";
+  return null;
+}
 
 // src/tools/inspection.ts
 var sessionArg = zod.z.string().optional().describe("Session ID to act on. Omit to use the default session.");
@@ -955,32 +967,32 @@ function registerRecordingTools(server, { sessions, env }) {
     "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.`,
+      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, .ts = runnable HumanJS script, .spec.ts/.test.ts = @playwright/test spec (humanized, with derived assertions). Pass several to export the same recording multiple ways, e.g. ["demo.mp4", "checkout.spec.ts"] for a video plus a ready-to-commit test. Path components are rejected for safety.`,
       inputSchema: {
         filenames: zod.z.array(zod.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"].'
+          'One or more output filenames. The recording is saved to each, format chosen by extension. e.g. ["demo.mp4"], ["checkout.spec.ts"], or ["demo.mp4", "demo.json", "demo.ts"].'
         ),
         session: zod.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: path.extname(filename).toLowerCase()
-      }));
-      for (const { ext } of targets) {
-        if (ext !== ".mp4" && ext !== ".webm" && ext !== ".gif" && ext !== ".json") {
+      const targets = filenames.map((filename) => {
+        const format = resolveRecordingFormat(filename);
+        if (format === null) {
           throw new Error(
-            `Unsupported output extension "${ext}". Use .mp4, .webm, .gif, or .json.`
+            `Unsupported output extension for "${filename}". Use .mp4/.webm (video), .gif, .json (timeline), .ts (HumanJS script), or .spec.ts/.test.ts (Playwright test).`
           );
         }
-      }
+        return { path: resolveOutputPath(env.outputDir, filename), format };
+      });
       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));
+        for (const { path, format } of targets) {
+          if (format === "gif") saved.push(await recording.toGif(path));
+          else if (format === "timeline") saved.push(await recording.toTimeline(path));
+          else if (format === "humanjs") saved.push(await recording.toHumanJS(path));
+          else if (format === "playwright") saved.push(await recording.toPlaywright(path));
           else saved.push(await recording.toVideo(path));
         }
         return { content: [{ type: "text", text: `saved recording to:
@@ -1065,6 +1077,10 @@ 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.
 
+Export as a test: human_stop_recording picks format by extension. A .spec.ts (or .test.ts) filename writes a ready-to-commit @playwright/test with derived assertions; a .ts writes a standalone HumanJS script; .mp4/.webm/.gif/.json are video/timeline. So "record this flow and save it as a test" = run the clean pass, then stop into e.g. "checkout.spec.ts".
+
+Captured input + passwords: typed/pasted text IS recorded into the timeline and code exports, so generated scripts/tests are runnable \u2014 EXCEPT password fields, which are always masked (emitted as an empty string with a "fill in" comment). This is intentional, not a bug; don't work around it by hand-editing the secret back in. If the user explicitly wants the flow to log in, edit the exported file to read the credential from an env var (e.g. process.env.APP_PASSWORD) and tell them to set it \u2014 never hardcode a real password into a file that may be committed.
+
 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.`;