@usercase/mcp 0.2.8-next.4 → 0.2.8-next.6

package/agents/new-research.md

@@ -54,10 +54,12 @@ One research is **one flow a participant can walk in one sitting**: 1–4 tasks,
 - Neutral wording that does not suggest the answer. One thing per question.
 - Choice answers do not overlap and cover the likely cases; add a free-text question when you cannot guess the answers. `likert_scale` always gets labels for both ends.
 
-**Invite**: the page glob where visitors should be invited (where the flow begins, or the moment the evidence points to), and one short line asking them to take part.
+**Invite**: the page where visitors are invited, and one short line asking them to take part. Participants start the first task on the page where they accepted the invite — nothing takes them elsewhere. So the invite page is where the first task begins, and the first task is something to do from there, never a trip to where they already are. Write it as one kind of page: an exact path, or a path with `:name` for the one part that changes. A `*` covers pages the first route cannot start from.
+
+**Time**: estimate the minutes the whole session takes — every task plus every question — and pass it as `minutes`. The invite card and the start screen show it next to your words.
 
 **Wording people read** (the start screen, the invite line):
-- Say plainly what they will do and roughly how long it takes.
+- Say plainly what they will do. Never state a duration or mention recording: the card and the start screen already show both from the research settings, and a second number can disagree.
 - The participant is the subject. Never ask for help, never make the team or the site the subject, never thank in advance.
 - Do not mention the problem you suspect or what others said.
 
@@ -66,14 +68,14 @@ One research is **one flow a participant can walk in one sitting**: 1–4 tasks,
 ## 6. Plan each task's route
 
 The results tell who went straight from who took a detour only when a task has an expected path: the route the site was built for. Work it out now, from the code, for every task with a page or click to reach (tasks done by staying on a page have none):
-- **where it starts**: the page a participant is on when the task begins;
+- **where it starts**: the first task starts on the invite page; every later task starts where the previous one ended;
 - **the clicks a participant must make**, in order — the main route the UI offers, not a shortcut only you know;
-- **where it ends**: the page or the click that counts as done. It must agree with the task's success condition.
+- **where it ends**: the page or the click that counts as done. It must agree with the task's success condition. When participants could reach any item of a kind (a project, a post, a product), the task's page is the route's pattern with `:name` for that part — never the item you happened to open — and while recording, `path_pattern` turns that page into the same pattern.
 - what the route needs: a signed-in demo account, or a write the safety guard does not send (the last click is then recorded without pressing it).
 
 ## 7. Show the user everything at once
 
-Show the whole research compactly: the purpose and its evidence, each task with how it counts as done (in plain words, no XPath) and its route in one line, the questions, and the invite. Say that on their approval you will walk each route in a browser and save the draft with the routes. Change whatever they ask for.
+Show the whole research compactly: the purpose and its evidence, each task with how it counts as done (in plain words, no XPath) and its route in one line, the questions, the invite, and the minutes. Say that on their approval you will walk each route in a browser and save the draft with the routes. Change whatever they ask for.
 
 ## 8. On approval: record the routes, then save
 

package/mcp/server.js

@@ -23,7 +23,7 @@ const ws = require("./workspace.js");
 const persona = require("../src/persona/persona.js");
 const report = require("./report.js");
 const peopleRules = require("../src/persona/people.js");
-const { PathRecorder } = require("./path.js");
+const { PathRecorder, patternOf } = require("./path.js");
 
 const hub = new Hub();
 const server = new McpServer({ name: "usercase", version: require("../package.json").version });
@@ -706,12 +706,44 @@ server.registerTool(
         )
         .optional(),
       questions: z.array(RQuestion).optional().describe("Asked after all tasks"),
-      invite: z.object({ page: z.string().describe("Page glob where visitors are invited"), copy: z.string().describe("The invite line, short") }).optional(),
+      invite: z.object({ page: z.string().describe("Page glob where visitors are invited"), copy: z.string().describe("The invite line, short. No duration — the card shows minutes") }).optional(),
+      minutes: z.number().int().min(1).max(60).optional().describe("Minutes the whole session takes (tasks and questions). Shown on the invite card and the start screen"),
       basis: z.enum(["real", "virtual", "none"]).describe("What the research came from: real visitor data, virtual user data, or neither (the user's question or the code)"),
       findingIds: z.array(z.string()).optional().describe("Ids of the findings it answers, from research_context"),
     },
   },
   wrap(async (args) => {
+    // 참여자는 초대를 수락한 페이지에서 첫 과제를 시작한다(SDK 는 다른 데로 데려가지 않는다).
+    // 첫 과제 경로가 다른 페이지에서 시작하면 첫 단계를 아무도 못 지난다 — 저장 전에 막는다. :이름 은 이름과 상관없이 같은 칸
+    // 녹화는 걸은 주소 그대로(/project/zksync)다. 과제에 적은 패턴(/project/:slug)에 맞는 주소는 그 패턴으로 —
+    // 안 그러면 그 항목을 고른 사람만 성공·바로 감으로 잡힌다(10/29 bluetags). 에이전트가 path_pattern 을 빠뜨려도 여기서 맞춘다
+    const toPattern = (body, pat) => {
+      if (!pat || !pat.includes(":")) return false;
+      const re = patternOf(pat);
+      const fit = (u) => u && u !== pat && !u.includes(":") && re.test(u);
+      let hit = false;
+      for (const s of body.steps) if (fit(s.url)) (s.url = pat), (hit = true);
+      const sc = body.success;
+      if (sc && fit(sc.targetUrl)) (sc.targetUrl = pat), (hit = true);
+      if (sc && fit(sc.xpathUrl)) (sc.xpathUrl = pat), (hit = true);
+      return hit;
+    };
+    const patternNotes = [];
+    for (const [n, p] of recorder.planned) {
+      const t = (args.tasks || [])[n - 1];
+      const pat = t && (t.success_condition === "element_click" ? t.xpath_url : t.target_url);
+      if (t && toPattern(p.body, pat)) patternNotes.push(`- task ${n}: recorded pages matching ${pat} now use that pattern`);
+    }
+    const first = recorder.planned.get(1);
+    if (args.invite && first && toPattern(first.body, args.invite.page)) patternNotes.push(`- task 1: its start page now uses the invite's pattern ${args.invite.page}`);
+    if (args.invite && first) {
+      const kind = (p) => String(p || "").trim().replace(/:[A-Za-z_]\w*/g, ":x").replace(/\/+$/, "") || "/";
+      const start = first.body.steps[0].url;
+      if (kind(args.invite.page) !== kind(start))
+        throw new Error(
+          `Nothing was saved. The invite is on ${args.invite.page}, but the first task's recorded route starts on ${start}. Participants start the first task where they accepted the invite, so these must be the same page: put the invite on ${start}, or record the first route again from the invite page (path_start plan-1). Tell the user which you change.`,
+        );
+    }
     const r = await report.saveResearchDraft(args);
     const tasks = r.tasks || [];
     if (tasks.length) recorder.addDraft(r.draftId, { title: args.title, website: r.website || "", tasks });
@@ -737,6 +769,7 @@ server.registerTool(
         `Saved as a draft${r.findings ? `, linked to ${r.findings} finding${r.findings > 1 ? "s" : ""}` : ""}.`,
         `Open it in the Inbox to review and create it: ${report.dashboardUrl(r.inboxPath)}`,
         ...(lines.length ? ["", "Expected paths saved with it:", ...lines] : []),
+        ...(patternNotes.length ? ["", "Item pages were recorded with the item you opened; they now match any item of that kind:", ...patternNotes] : []),
         ...(missing.length
           ? ["", "Tasks without an expected path:", ...missing.map((t) => `- ${t.title} (record later with path_start draft:${r.draftId}:${t.index})`)]
           : []),

package/package.json

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