@usercase/mcp 0.2.4-next.3 → 0.2.4-next.5

package/agents/path.md

@@ -1,49 +1,49 @@
-# Record the expected path for a Usercase research
-
-Research: {{research}}
-
-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.
-
-You record that path by walking it yourself in a browser. Unlike the virtual visitors, **you may read the code** — the expected path is the route the site was built for, and the code is where that intent lives.
-
-## 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.
-
-## 2. Work out the intended route — before opening the browser
-
-For each task, from the task text and the code (routes, pages, the components on them):
-- **where it starts**: the page a participant is on when the task begins. If the task text names a situation ("you are on a jacket's product page"), start there; otherwise the front page.
-- **the clicks a participant must make**, in order — the main route the UI offers (the menu, the primary button), not a shortcut only you know (a typed URL, a hidden link).
-- **where it ends**: the page or the click that means the task is done. Compare it with the task's success condition from `path_tasks`. If they disagree, or the task has none that fits, note it — the user decides in step 5.
-
-Tell the user the route in one line per task (e.g. "Front page → Pricing → 'Start free trial' → sign-up form") and go on. Stop and ask only when the code leaves the route genuinely unclear.
-
-## 3. Walk it
-
-- `path_start` with the task and the URL where the route starts. A local dev server is fine (only paths are saved, not the host). Use `account` if the route is for signed-in users (demo accounts from `login`).
-- `path_click` each click of the route. Choose the element a participant would use — the visible button or menu item.
-- Things that are not part of the route (closing a cookie banner or a pop-up): `path_click` with `record: false`. Search terms or quantities: `path_type`.
-- **Picking one of many** (a product, an announcement, a project from a list): participants will pick a different one, and a recorded click points at the exact item you picked — everyone else would count as taking a detour. So click it with `record: false`, and turn the page it opens into a pattern with `path_pattern` (`/notice/6553c3ba` → `/notice/:id`, parameter names from the route definitions in the code). The page step is what matches them.
-- Record a click as a step only when every participant must press that same control (a menu item, the main button).
-- **The safety guard does not send writes** (sign-ups, posts, orders) unless the user chose so with `set_writes`, and never presses pay or delete buttons. If the route's last step is such a button, record it with `press: false` — it becomes the final click. If the route needs a write *in the middle* (an item must be in the cart first), stop and tell the user: the path can only go as far as the guard allows, unless they let writes through on a test site.
-
-Do not change any code.
-
-## 4. Check it
-
-Call `path_check`. It walks the path again in a fresh browser. If it fails:
-- "not found" or "now holds …": the element sits at a position that changes between visits (list order, a rotating banner). Record again with a more stable element — a menu link, a heading link — or use a pattern for the page.
-- "landed on … instead": the page address changes; use `path_pattern`.
-
-Record again with `path_start` when needed. Only a passing check can be saved.
-
-## 5. Show the user, then save
-
-Show the user the steps and the screenshots `path_check` lists (open them so they can see each step). Ask:
-- whether this is the route they intend participants to take, and
-- if the task's success condition did not match the route's end (step 2), whether to change it: **page** = done on reaching the last page of the path, **click** = done on the last recorded click, **keep** = leave it.
-
-On their approval, call `path_save` (with `success` if they chose to change it). Then go on to the next task.
-
-When all are done, tell the user which tasks now have a path, and any you could not record and why.
+# Record the expected path for a Usercase research
+
+Research: {{research}}
+
+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.
+
+You record that path by walking it yourself in a browser. Unlike the virtual visitors, **you may read the code** — the expected path is the route the site was built for, and the code is where that intent lives.
+
+## 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.
+
+## 2. Work out the intended route — before opening the browser
+
+For each task, from the task text and the code (routes, pages, the components on them):
+- **where it starts**: the page a participant is on when the task begins. If the task text names a situation ("you are on a jacket's product page"), start there; otherwise the front page.
+- **the clicks a participant must make**, in order — the main route the UI offers (the menu, the primary button), not a shortcut only you know (a typed URL, a hidden link).
+- **where it ends**: the page or the click that means the task is done. Compare it with the task's success condition from `path_tasks`. If they disagree, or the task has none that fits, note it — the user decides in step 5.
+
+Tell the user the route in one line per task (e.g. "Front page → Pricing → 'Start free trial' → sign-up form") and go on. Stop and ask only when the code leaves the route genuinely unclear.
+
+## 3. Walk it
+
+- `path_start` with the task and the URL where the route starts. A local dev server is fine (only paths are saved, not the host). Use `account` if the route is for signed-in users (demo accounts from `login`).
+- `path_click` each click of the route. Choose the element a participant would use — the visible button or menu item.
+- Things that are not part of the route (closing a cookie banner or a pop-up): `path_click` with `record: false`. Search terms or quantities: `path_type`.
+- **Picking one of many** (a product, an announcement, a project from a list): participants will pick a different one, and a recorded click points at the exact item you picked — everyone else would count as taking a detour. So click it with `record: false`, and turn the page it opens into a pattern with `path_pattern` (`/notice/6553c3ba` → `/notice/:id`, parameter names from the route definitions in the code). The page step is what matches them.
+- Record a click as a step only when every participant must press that same control (a menu item, the main button).
+- **The safety guard does not send writes** (sign-ups, posts, orders) unless the user chose so with `set_writes`, and never presses pay or delete buttons. If the route's last step is such a button, record it with `press: false` — it becomes the final click. If the route needs a write *in the middle* (an item must be in the cart first), stop and tell the user: the path can only go as far as the guard allows, unless they let writes through on a test site.
+
+Do not change any code.
+
+## 4. Check it
+
+Call `path_check`. It walks the path again in a fresh browser. If it fails:
+- "not found" or "now holds …": the element sits at a position that changes between visits (list order, a rotating banner). Record again with a more stable element — a menu link, a heading link — or use a pattern for the page.
+- "landed on … instead": the page address changes; use `path_pattern`.
+
+Record again with `path_start` when needed. Only a passing check can be saved.
+
+## 5. Show the user, then save
+
+Show the user the steps and the screenshots `path_check` lists (open them so they can see each step). Ask:
+- whether this is the route they intend participants to take, and
+- if the task's success condition did not match the route's end (step 2), whether to change it: **page** = done on reaching the last page of the path, **click** = done on the last recorded click, **keep** = leave it. With page or click the path is saved only up to that point — say so when the route goes on after it (e.g. a page that opens after the last click).
+
+On their approval, call `path_save` (with `success` if they chose to change it). Then go on to the next task.
+
+When all are done, tell the user which tasks now have a path, and any you could not record and why.

package/mcp/path.js

@@ -366,19 +366,27 @@ class PathRecorder {
   async save({ success = "keep" }) {
     const c = this.need();
     if (!c.checked || c.checked !== this.signature()) throw new Error("Run path_check first — only a path that passed, unchanged since, can be saved.");
+    // 경로는 성공 지점에서 끝난다 — 성공하는 순간 과제가 끝나서 그 뒤 단계는 아무도 못 채운다(모두 "돌아감"이 된다)
+    const type = success === "page" ? "URL" : success === "click" ? "XPATH" : null;
+    const end = type ? c.steps.map((s) => s.type).lastIndexOf(type) : c.steps.length - 1;
+    if (end < 0) throw new Error("There is no recorded click to use as the success condition.");
+    const last = c.steps[end];
+    const steps = c.steps.slice(0, end + 1);
+    const cut = c.steps.slice(end + 1);
     const body = {
-      steps: c.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 || [], image: fs.readFileSync(s.image).toString("base64") })),
     };
-    if (success === "page") {
-      const last = [...c.steps].reverse().find((s) => s.type === "URL");
-      body.success = { condition: "url_entry", targetUrl: last.url };
-    } else if (success === "click") {
-      const last = [...c.steps].reverse().find((s) => s.type === "XPATH");
-      if (!last) throw new Error("There is no recorded click to use as the success condition.");
-      body.success = { condition: "element_click", xpath: last.xpath, xpathUrl: last.url, classes: last.classes, ids: last.ids };
-    }
+    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 };
     const r = await report.savePath(c.taskId, body);
-    const done = `Saved the expected path for task ${c.taskId} ("${c.title}"): ${r.steps} steps${r.success ? `, success condition set to ${r.success === "url_entry" ? `reaching ${body.success.targetUrl}` : `clicking "${[...c.steps].reverse().find((s) => s.type === "XPATH").label}"`}` : ""}. The dashboard's task results now separate going straight from detours.`;
+    const done = [
+      `Saved the expected path for task ${c.taskId} ("${c.title}"): ${r.steps} steps${r.success ? `, success condition set to ${r.success === "url_entry" ? `reaching ${last.url}` : `clicking "${last.label || last.tag}"`}` : ""}. The dashboard's task results now separate going straight from detours.`,
+      cut.length
+        ? `Left out the ${cut.length} step(s) after the success point (${cut.map((s) => (s.type === "URL" ? `page ${s.url}` : `click "${s.label || s.tag}"`)).join(", ")}) — the task ends at the success point, so no participant could ever reach them. Tell the user.`
+        : "",
+    ]
+      .filter(Boolean)
+      .join("\n");
     await this.stop();
     return done;
   }

package/mcp/server.js

@@ -553,7 +553,7 @@ server.registerTool(
   "path_save",
   {
     description:
-      "Upload the checked path to the dashboard, replacing the task's expected path. Only after the user approved it. success: keep (default) leaves the task's success condition; page = done on reaching the last page of the path; click = done on the last recorded click. Ask the user before changing it.",
+      "Upload the checked path to the dashboard, replacing the task's expected path. Only after the user approved it. success: keep (default) leaves the task's success condition; page = done on reaching the last page of the path; click = done on the last recorded click. With page or click the saved path ends at that point (later steps are left out: the task ends there, so nobody could reach them). Ask the user before changing it.",
     inputSchema: { success: z.enum(["keep", "page", "click"]).optional() },
   },
   wrap(async ({ success }) => text(await recorder.save({ success }))),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.2.4-next.3",
+  "version": "0.2.4-next.5",
   "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",