@usercase/mcp 0.2.4-next.6 → 0.2.4-next.8

package/agents/path.md

@@ -1,6 +1,7 @@
 # Record the expected path for a Usercase research
 
 Research: {{research}}
+{{task}}
 
 A Usercase research asks real participants to do tasks on this site. For each task, the dashboard splits results into **went straight**, **took a detour** and **failed** — but only if the task has an **expected path**: the route the team intends people to take. Without one, every success counts as "went straight", so the results cannot show where people wander.
 
@@ -8,7 +9,7 @@ You record that path by walking it yourself in a browser. Unlike the virtual vis
 
 ## 1. See the tasks
 
-Call `path_tasks` with the research id. For each task you get what the participant is told, how it counts as done, and whether a path exists. Record paths for the tasks that have none. If every task already has one, ask the user which to redo.
+Call `path_tasks` with the research id. For each task you get what the participant is told, how it counts as done, and whether a path exists. If a task is named above, record only that one, even if it already has a path. Otherwise record paths for the tasks that have none, and if every task already has one, ask the user which to redo.
 
 ## 2. Work out the intended route — before opening the browser
 

package/mcp/fingerprint.js

@@ -0,0 +1,117 @@
+"use strict";
+/**
+ * 경로 클릭 단계의 요소 특징 — SDK core/elementFingerprint.ts 의 clickableOf·fingerprintOf 와 **같아야 한다**.
+ * 위치(XPath)가 안 맞을 때 SDK 가 같은 요소인지 보조로 판정하는 데 쓴다(지금은 그림자 모드 — 진단만).
+ * 내용에 따라 블록 수가 다른 상세 페이지에서 같은 버튼이 div[5]/div[6] 으로 갈렸다(10/27 bluetags).
+ *
+ * 브라우저 안에서 도는 함수 하나다(page.evaluate 에 그대로 넘긴다) — 바깥 변수를 쓰면 안 된다.
+ */
+function fingerprintInPage(el) {
+  const PICK_SEL = 'a[href],button,[role="button"],[role="link"],[role="tab"],[role="menuitem"],summary,label,input,select,textarea';
+  const ATTRS = ["aria-label", "title", "alt", "name", "type", "placeholder", "data-testid", "data-test", "data-cy", "data-action"];
+  const ZONES = [
+    ["dialog", 'dialog,[role="dialog"],[role="alertdialog"],[aria-modal="true"]'],
+    ["header", 'header,[role="banner"]'],
+    ["nav", 'nav,[role="navigation"]'],
+    ["aside", 'aside,[role="complementary"]'],
+    ["footer", 'footer,[role="contentinfo"]'],
+    ["main", 'main,[role="main"]'],
+  ];
+  const mask = (s, max) =>
+    (s || "")
+      .replace(/\s+/g, " ")
+      .trim()
+      .toLowerCase()
+      .replace(/\d+/g, "#")
+      .slice(0, max);
+  const textOf = (e) => mask(e.textContent || "", 80);
+  const zoneRoot = (e) => {
+    for (const [zone, sel] of ZONES) {
+      const r = e.closest(sel);
+      if (r) return { zone, root: r };
+    }
+    return { zone: "body", root: e.ownerDocument.body };
+  };
+  const shapeOf = (e, root) => {
+    const parts = [];
+    for (let x = e; x && x !== root; x = x.parentElement) parts.unshift(x.tagName.toLowerCase());
+    return parts.join(">");
+  };
+  const hrefPattern = (e) => {
+    const a = e.closest("a[href]") || e.querySelector("a[href]");
+    const raw = a && a.getAttribute("href");
+    if (!raw) return "";
+    try {
+      const u = new URL(raw, e.ownerDocument.location && e.ownerDocument.location.href);
+      const same = u.origin === (e.ownerDocument.location && e.ownerDocument.location.origin);
+      const p = u.pathname
+        .split("/")
+        .map((seg) => (/^\d+$/.test(seg) || /^[0-9a-f]{8,}$/i.test(seg) || /^[0-9a-f-]{32,36}$/i.test(seg) ? ":id" : seg))
+        .join("/");
+      return (same ? "" : u.host) + p;
+    } catch (err) {
+      return "";
+    }
+  };
+  const iconOf = (e) => {
+    const svg = e.tagName.toLowerCase() === "svg" ? e : e.querySelector("svg");
+    if (!svg) return "";
+    const d = Array.from(svg.querySelectorAll("path"))
+      .slice(0, 3)
+      .map((p) => p.getAttribute("d") || "")
+      .join("|");
+    const src = (svg.getAttribute("viewBox") || "") + "|" + d;
+    if (src === "|") return "";
+    let h = 5381;
+    for (let i = 0; i < src.length; i++) h = ((h << 5) + h + src.charCodeAt(i)) | 0;
+    return (h >>> 0).toString(36);
+  };
+  const attrsOf = (e) => {
+    const out = {};
+    for (const k of ATTRS) {
+      const v = e.getAttribute(k);
+      if (v && v.trim()) out[k] = mask(v, 60);
+    }
+    return out;
+  };
+  const reactClick = (x) => {
+    for (const k in x) if (k.startsWith("__reactProps") && x[k] && typeof x[k].onClick === "function") return true;
+    return false;
+  };
+  // 올라가며 처음 만나는 링크·버튼 또는 React onClick — 카드 링크 안의 저장 버튼은 저장 버튼이다
+  const clickableOf = (n) => {
+    const win = n.ownerDocument.defaultView;
+    const body = n.ownerDocument.body;
+    const area = (x) => {
+      const r = x.getBoundingClientRect();
+      return r.width * r.height;
+    };
+    const base = Math.max(area(n), 1);
+    const fits = (x) => area(x) <= base * 6 && !Array.from(x.querySelectorAll(PICK_SEL)).some((c) => !c.contains(n) && !n.contains(c));
+    for (let x = n; x && x !== body; x = x.parentElement) {
+      if (x.matches(PICK_SEL)) return x;
+      if (reactClick(x)) return fits(x) ? x : n;
+    }
+    let top = n;
+    for (let x = n.parentElement; x && x !== body && win && win.getComputedStyle(x).cursor === "pointer" && fits(x); x = x.parentElement) top = x;
+    return top;
+  };
+
+  const e = clickableOf(el);
+  const { zone, root } = zoneRoot(e);
+  return {
+    v: 1,
+    zone,
+    tag: e.tagName.toLowerCase(),
+    role: e.getAttribute("role") || "",
+    shape: shapeOf(e, root),
+    text: textOf(e),
+    attrs: attrsOf(e),
+    href: hrefPattern(e),
+    icon: iconOf(e),
+    before: e.previousElementSibling ? mask(e.previousElementSibling.textContent || "", 30) : "",
+    after: e.nextElementSibling ? mask(e.nextElementSibling.textContent || "", 30) : "",
+  };
+}
+
+module.exports = { fingerprintInPage };

package/mcp/path.js

@@ -17,6 +17,7 @@ const fs = require("fs");
 const path = require("path");
 const ws = require("./workspace.js");
 const report = require("./report.js");
+const { fingerprintInPage } = require("./fingerprint.js");
 const { listControls, visibleText, handleAt, clickBlocked } = require("../src/browser/page.js");
 const { renderScreen, settle, watchNet } = require("../src/run/visit.js");
 
@@ -37,8 +38,34 @@ const pathOnly = (u) => {
  * 요소 하나를 SDK 가 맞출 수 있는 모양으로. 브라우저 안에서 돈다.
  * XPath 는 SDK main/utils.ts getElementXPath 와 같은 방식(같은 이름 형제 사이 순번, svg 는 name())
  */
-function describeInPage(n, pickSel) {
-  const pick = (n.closest && n.closest(pickSel)) || n;
+function describeInPage(n, { sel: pickSel, lift = false }) {
+  /**
+   * onClick 달린 div 로 만든 버튼은 태그로 안 잡힌다. 그러면 누른 조각(글자 span)만 기록돼, 같은 버튼의 아이콘을
+   * 누른 참여자는 다른 길로 갔다고 나왔다(10/27 bluetags: "Save" 글자 대 북마크 아이콘). 클릭을 받는 요소까지 올린다:
+   * React 가 onClick 을 붙인 가장 가까운 것, 없으면 손가락 커서가 이어지는 데까지. 둘 다 조작을 하나 더 품거나
+   * 처음 것보다 훨씬 크면(카드 전체) 멈춘다 — 아무 데나 눌러도 맞게 되면 안 된다
+   */
+  const liftInPage = (e) => {
+    const area = (x) => {
+      const r = x.getBoundingClientRect();
+      return r.width * r.height;
+    };
+    const base = Math.max(area(e), 1);
+    const fits = (x) => area(x) <= base * 6 && !Array.from(x.querySelectorAll(pickSel)).some((c) => !c.contains(e) && !e.contains(c));
+    const reactClick = (x) => {
+      for (const k in x) if (k.startsWith("__reactProps") && x[k] && typeof x[k].onClick === "function") return true;
+      return false;
+    };
+    for (let x = e; x && x !== document.body; x = x.parentElement) {
+      if (x.matches(pickSel)) return x;
+      if (reactClick(x)) return fits(x) ? x : e;
+    }
+    let top = e;
+    for (let x = e.parentElement; x && x !== document.body && getComputedStyle(x).cursor === "pointer" && fits(x); x = x.parentElement) top = x;
+    return top;
+  };
+  // 카드 전체가 링크이고 안에 onClick 저장 버튼이 있으면 저장 버튼을 기록한다 — 링크부터 찾으면 카드 전체가 잡혔다(10/27 홈 목록)
+  const pick = lift ? liftInPage(n) : (n.closest && n.closest(pickSel)) || n;
   const xp = (e) => {
     const parts = [];
     while (e && e.nodeType === 1) {
@@ -215,16 +242,19 @@ class PathRecorder {
       return this.screen(
         `Not pressed — ${blocked}. If this is where the participant's task ends (e.g. the final "Pay" or "Submit" button), call path_click again with press=false: it is recorded as the final click without pressing it.`,
       );
-    const pickH = await el.evaluateHandle((n, sel) => (n.closest && n.closest(sel)) || n, PICK_SEL);
-    const info = await el.evaluate(describeInPage, PICK_SEL);
+    const info = await el.evaluate(describeInPage, { sel: PICK_SEL, lift: true });
     if (!info.xpath) return this.screen(`Could not work out where [${index}] is in the page. Try another element.`);
+    // 기록한 XPath 로 다시 찾은 것을 찍고 누른다 — SDK 가 참여자 화면에서 찾을 바로 그 요소다
+    const pickH = (await c.page.evaluateHandle(byXPathInPage, info.xpath)).asElement() || el;
     const at = pathOnly(c.page.url());
     let step = null;
     if (record) {
       const file = path.join(c.dir, `${String(c.steps.length + 1).padStart(2, "0")}-click.jpg`);
-      await pickH.asElement().scrollIntoViewIfNeeded({ timeout: 5000 }).catch(() => {});
-      await this.shot(file, pickH.asElement());
-      step = { type: "XPATH", url: at, concrete: at, xpath: info.xpath, classes: info.classes, ids: info.ids, label: info.label, tag: info.tag, image: file, pressed: press };
+      await pickH.scrollIntoViewIfNeeded({ timeout: 5000 }).catch(() => {});
+      await this.shot(file, pickH);
+      // 위치가 안 맞을 때(내용에 따라 칸이 밀리는 상세 페이지) SDK 가 보조로 맞춰 보는 요소 특징. 못 구하면 위치로만
+      const fingerprint = await pickH.evaluate(fingerprintInPage).catch(() => null);
+      step = { type: "XPATH", url: at, concrete: at, xpath: info.xpath, classes: info.classes, ids: info.ids, fingerprint, label: info.label, tag: info.tag, image: file, pressed: press };
       c.steps.push(step);
     }
     c.actions.push({ do: "click", xpath: info.xpath, label: info.label, press, step: step ? c.steps.length - 1 : null });
@@ -232,7 +262,7 @@ class PathRecorder {
     if (!press) return this.screen(`Recorded "${info.label || info.tag}" as the final click, without pressing it. The path ends here — call path_check next.`);
     const before = c.page.url();
     try {
-      await pickH.asElement().click({ timeout: 10000 });
+      await pickH.click({ timeout: 10000 });
     } catch (e) {
       if (step) c.steps.pop();
       c.actions.pop();
@@ -251,7 +281,7 @@ class PathRecorder {
     const c = this.need();
     const el = c.view && c.view.items[index] ? await handleAt(c.page, index) : null;
     if (!el) return this.screen(`[${index}] is not on the screen any more.`);
-    const info = await el.evaluate(describeInPage, "input,textarea,select,[contenteditable]");
+    const info = await el.evaluate(describeInPage, { sel: "input,textarea,select,[contenteditable]" });
     await el.fill(text, { timeout: 10000 });
     c.actions.push({ do: "type", xpath: info.xpath, text });
     c.checked = null;
@@ -374,7 +404,7 @@ class PathRecorder {
     const steps = c.steps.slice(0, end + 1);
     const cut = c.steps.slice(end + 1);
     const body = {
-      steps: steps.map((s) => ({ type: s.type, url: s.url, xpath: s.xpath || "", classes: s.classes || [], ids: s.ids || [], image: fs.readFileSync(s.image).toString("base64") })),
+      steps: steps.map((s) => ({ type: s.type, url: s.url, xpath: s.xpath || "", classes: s.classes || [], ids: s.ids || [], fingerprint: s.fingerprint || null, image: fs.readFileSync(s.image).toString("base64") })),
     };
     if (success === "page") body.success = { condition: "url_entry", targetUrl: last.url };
     else if (success === "click") body.success = { condition: "element_click", xpath: last.xpath, xpathUrl: last.url, classes: last.classes, ids: last.ids };

package/mcp/server.js

@@ -711,12 +711,17 @@ server.registerPrompt(
 
 server.registerPrompt(
   "path",
-  { description: "Record the expected path of a Usercase research's tasks", argsSchema: { research: z.string().optional() } },
-  ({ research }) => {
+  {
+    description: "Record the expected path of a Usercase research's tasks",
+    // 대시보드 과제 화면의 명령은 과제 id 를 붙인다 — 그 과제만, 경로가 있어도 다시
+    argsSchema: { research: z.string().optional(), task: z.string().optional() },
+  },
+  ({ research, task }) => {
     const body = fs
       .readFileSync(path.join(__dirname, "..", "agents", "path.md"), "utf8")
       .replace(/\r\n/g, "\n")
-      .replace("{{research}}", research || "(ask the user — the dashboard shows it)");
+      .replace("{{research}}", research || "(ask the user — the dashboard shows it)")
+      .replace("{{task}}", task ? `Task: ${task} — record this task only, and record it again even if it already has a path.` : "Task: all tasks of the research");
     return { messages: [{ role: "user", content: { type: "text", text: body } }] };
   },
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.2.4-next.6",
+  "version": "0.2.4-next.8",
   "description": "Virtual users that browse your website and tell you what they thought — an MCP server for Claude Code",
   "license": "UNLICENSED",
   "homepage": "https://usercase.io",