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

package/README.md

@@ -109,7 +109,7 @@ Claude suggests the moment, the question and its answers, and saves it only afte
 /mcp__usercase__new-research
 ```
 
-Claude asks whether you already know what you want to learn. If you don't, it reads your project's findings and where visitors left, and suggests two or three researches, saying which evidence comes from real visitors and which from virtual users. With no data yet, it offers to send a few virtual users first. It then reads your code to write the tasks and their success conditions (the page that means done, or the exact button), and saves the research only after you approve it — as a draft in your Inbox, where you create it. It then offers to walk each task in a browser and record its expected path; the paths stay with the draft and move into the research when you create it. A draft you discard, or don't create within 30 days, loses its recorded paths and their screenshots.
+Claude asks whether you already know what you want to learn. If you don't, it reads your project's findings and where visitors left, and suggests two or three researches, saying which evidence comes from real visitors and which from virtual users. With no data yet, it offers to send a few virtual users first. It then reads your code to write the tasks, their success conditions (the page that means done, or the exact button) and the route each task is meant to take, and shows you all of it at once. On your approval it walks each route in a browser, checks it, and saves the research with the routes — as a draft in your Inbox, where you create it. The routes move into the research when you create it. A draft you discard, or don't create within 30 days, loses its recorded paths and their screenshots.
 
 ## What the visitors will and won't do
 

package/agents/new-research.md

@@ -54,33 +54,46 @@ 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.
 
 **Language**: English, unless the user asks for another language.
 
-## 6. Show the user, then save
+## 6. Plan each task's route
 
-Show the whole research compactly: the purpose and its evidence, each task with how it counts as done (in plain words, no paths or XPath), the questions, and the invite. Change whatever they ask for.
+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 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.
+- 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).
 
-On their approval, call `research_save` with `basis` (`real` if the evidence came from real visitors, `virtual` if only from virtual users, `none` otherwise) and the ids of the findings it answers. Give them the Inbox link it returns and tell them it stays a draft until they create it in the Inbox, where they also set when the invite appears.
+## 7. Show the user everything at once
 
-## 7. Record each task's expected path
+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.
 
-The results tell who went straight from who took a detour only when a task has an expected path, and walking it in a browser confirms the success condition you wrote from the code. Ask the user whether to record the paths now. If they say no, tell them `{{path_cmd}}` with the research id does it after the research is created, and stop.
+## 8. On approval: record the routes, then save
 
-For each task with a page or click to reach (skip tasks that are done by staying on a page), use the task id `research_save` listed for it, `draft:<draft>:<number>`:
+Do not ask again between these steps. For each task with a route, in order, use the task id `plan-<n>` (n = the task's position in the research, from 1):
 
 {{path_walk}}
 
-### Show the user, then save
+### Save each route
+
+When `path_check` passes and the route ends where the plan said, call `path_save` (`page` or `click` when the route's end is the task's success condition, otherwise `keep`). It is kept until the draft is saved. Stop and ask the user only when a route cannot be walked as planned — the site differs from the code, a check keeps failing, or the route needs a write or a sign-in you do not have; leave that task without a route if they say so.
+
+### Save the draft
 
-Show the user the steps and the screenshots `path_check` lists. Ask whether this is the route they intend, and whether the task should be done on reaching the last page (`page`), on the last recorded click (`click`), or keep the condition you wrote (`keep`). With page or click the path ends at that point — say so when the route goes on after it.
+Then call `research_save` with `basis` (`real` if the evidence came from real visitors, `virtual` if only from virtual users, `none` otherwise) and the ids of the findings it answers. It uploads the routes you saved with the draft. Tell the user:
+- the Inbox link, and that it stays a draft until they create it there, where they also set when the invite appears;
+- which tasks have a route and the screenshots `path_check` listed for them, and any task left without one and why;
+- a draft that is discarded, or not created within 30 days, loses its routes.
 
-On their approval, call `path_save`. The path stays in the draft and moves into the research when it is created; a draft that is discarded, or not created within 30 days, loses its paths. When all tasks are done, tell the user which have a path and any you could not record and why.
+To redo a route later: `path_start` with `draft:<draft>:<index>` while the draft exists, or `{{path_cmd}}` with the research id once it is created.
 
 Do not change any code.

package/mcp/path.js

@@ -124,9 +124,24 @@ class PathRecorder {
     this.hub = hub;
     /** taskId → { research, task } — path_tasks 로 받아 둔다 */
     this.known = new Map();
+    /** 아직 저장 안 한 리서치의 과제 경로(plan-<번호>) — 번호 → { body, steps, how }. research_save 가 가져간다 */
+    this.planned = new Map();
     this.cur = null;
   }
 
+  /** 녹화해 둔 계획 과제 경로를 넘기고 비운다 */
+  takePlanned() {
+    const out = new Map(this.planned);
+    this.planned.clear();
+    return out;
+  }
+
+  /** 상대 주소를 풀 사이트 — 연결된 프로젝트의 주소. 못 읽으면 빈 값(전체 주소를 받는다) */
+  async projectSite() {
+    if (this.site === undefined) this.site = await report.getInstall().then((m) => m.website || "").catch(() => "");
+    return this.site;
+  }
+
   /** 리서치의 과제들 */
   async tasks(researchId) {
     const r = await report.getResearchTasks(researchId);
@@ -169,20 +184,24 @@ class PathRecorder {
 
   /** 새로 기록을 시작한다. 같은 과제를 다시 하면 처음부터 */
   async start({ task, url, device = "desktop", account = null }) {
-    const k = this.known.get(String(task));
+    // 아직 저장 안 한 리서치의 과제(new-research, plan-<번호>) — 녹화해 두었다가 research_save 가 초안과 함께 올린다
+    const plan = String(task).match(/^plan-(\d+)$/i);
+    const k = plan ? { research: { website: await this.projectSite() }, task: { title: `Planned task ${plan[1]}` } } : this.known.get(String(task));
     if (!k)
       throw new Error(
         String(task).startsWith("draft:")
           ? `Draft task ${task} is not known in this session. Draft tasks are known right after research_save; once the research is created, use path_tasks with its id instead.`
           : `Task ${task} is not known yet. Call path_tasks with the research id first.`,
       );
-    const full = /^https?:\/\//i.test(url) ? url : new URL(url, k.research.website || undefined).toString();
+    if (!/^https?:\/\//i.test(url) && !k.research.website) throw new Error("Give the full URL where the route starts — the project has no site address to resolve a path against.");
+    const full = /^https?:\/\//i.test(url) ? url : new URL(url, k.research.website).toString();
     await this.stop();
     const s = this.hub.site(full);
     const ctx = await this.open(s, { device, account });
     const page = await ctx.newPage();
     ws.ensure();
-    const dir = path.join(ws.DIR, "paths", String(task));
+    // 폴더 이름에 : 를 못 쓰는 OS 가 있다(Windows) — draft:<초안>:<번호> 같은 id 를 바꿔 쓴다
+    const dir = path.join(ws.DIR, "paths", String(task).replace(/[^\w.-]+/g, "_"));
     fs.rmSync(dir, { recursive: true, force: true });
     fs.mkdirSync(dir, { recursive: true });
     this.cur = { taskId: String(task), title: k.task.title, s, ctx, page, net: watchNet(page), dir, startUrl: full, device, account, steps: [], actions: [], view: null, checked: null };
@@ -419,15 +438,25 @@ class PathRecorder {
     };
     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, label: last.label || "" };
-    // 초안 과제(new-research, draft:<초안>:<번호>)는 초안에 둔다 — 리서치로 만들 때 옮겨진다
+    const cutLine = 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.`
+      : "";
+    // 아직 저장 안 한 리서치의 과제 — 올리지 않고 들고 있다가 research_save 가 초안과 함께 올린다
+    const plan = c.taskId.match(/^plan-(\d+)$/i);
+    if (plan) {
+      const n = Number(plan[1]);
+      const how = success === "page" ? `done on reaching ${last.url}` : success === "click" ? `done on clicking "${last.label || last.tag}" on ${last.url}` : "success condition as written";
+      this.planned.set(n, { body, steps: steps.length, how });
+      await this.stop();
+      return [`Kept the checked path for planned task ${n}: ${steps.length} steps, ${how}. research_save uploads it with the draft.`, cutLine].filter(Boolean).join("\n");
+    }
+    // 초안 과제(draft:<초안>:<번호>)는 초안에 둔다 — 리서치로 만들 때 옮겨진다
     const draft = c.taskId.match(/^draft:([^:]+):(\d+)$/);
     const r = draft ? await report.saveDraftPath(draft[1], Number(draft[2]), body) : await report.savePath(c.taskId, body);
     const where = draft ? "The path is kept in the draft and moves into the research when it is created." : "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}"`}` : ""}. ${where}`,
-      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.`
-        : "",
+      cutLine,
     ]
       .filter(Boolean)
       .join("\n");

package/mcp/server.js

@@ -566,7 +566,7 @@ server.registerTool(
     description:
       "Open a fresh browser on the page where the task's intended route begins and start recording its expected path. The page itself is step 1. Starting again discards the recording in progress.",
     inputSchema: {
-      task: z.string().describe("Task id from path_tasks"),
+      task: z.string().describe("Task id from path_tasks · plan-<n> for task n of a research not saved yet (new-research) · draft:<draft>:<index> for a saved draft"),
       url: z.string().describe("Full URL where the route starts — the local dev server is fine; only paths are saved"),
       device: z.enum(["desktop", "mobile"]).optional(),
       account: z.string().optional().describe("Demo account saved by login (a1 …) if the route needs a signed-in user"),
@@ -685,7 +685,7 @@ server.registerTool(
   "research_save",
   {
     description:
-      "Save the research as a DRAFT in the dashboard Inbox, after the user approved it. It becomes a research only when someone creates it there. Paths are page paths starting with / (no host), with :name for the parts that change.",
+      "Save the research as a DRAFT in the dashboard Inbox, after the user approved it. It becomes a research only when someone creates it there. Paths are page paths starting with / (no host), with :name for the parts that change. Expected paths recorded and saved beforehand as plan-<n> (n = the task's position in tasks, from 1) are uploaded with it.",
     inputSchema: {
       title: z.string().describe("Short, for the team"),
       purpose: z.string().describe("What the team wants to learn and why — the evidence it came from"),
@@ -706,26 +706,51 @@ 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 는 다른 데로 데려가지 않는다).
+    // 첫 과제 경로가 다른 페이지에서 시작하면 첫 단계를 아무도 못 지난다 — 저장 전에 막는다. :이름 은 이름과 상관없이 같은 칸
+    const first = recorder.planned.get(1);
+    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);
-    // 과제 경로 녹화(path_start)에 쓸 번호 — 옛 서버는 tasks 를 안 준다
     const tasks = r.tasks || [];
     if (tasks.length) recorder.addDraft(r.draftId, { title: args.title, website: r.website || "", tasks });
+    // 저장 전에 녹화해 둔 경로(plan-<번호>, 번호는 tasks 순서 1부터)를 초안의 그 과제에 올린다
+    const planned = recorder.takePlanned();
+    const lines = [];
+    for (const [n, p] of [...planned.entries()].sort((a, b) => a[0] - b[0])) {
+      const t = tasks[n - 1];
+      if (!t) {
+        lines.push(`- planned task ${n}: not uploaded — the research has ${tasks.length} task(s)`);
+        continue;
+      }
+      try {
+        await report.saveDraftPath(r.draftId, t.index, p.body);
+        lines.push(`- task ${n} "${t.title}": ${p.steps} steps, ${p.how}`);
+      } catch (e) {
+        lines.push(`- task ${n} "${t.title}": not uploaded (${e.message}) — record it again with path_start draft:${r.draftId}:${t.index}`);
+      }
+    }
+    const missing = tasks.filter((t, i) => !planned.has(i + 1) && t.condition !== "time_on_page");
     return text(
       [
         `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)}`,
-        ...(tasks.length
-          ? [
-              "",
-              `Task ids for recording their expected paths with path_start${r.website ? ` (relative URLs resolve against ${r.website})` : ""}:`,
-              ...tasks.map((t) => `- draft:${r.draftId}:${t.index} — ${t.title}`),
-            ]
+        ...(lines.length ? ["", "Expected paths saved with it:", ...lines] : []),
+        ...(missing.length
+          ? ["", "Tasks without an expected path:", ...missing.map((t) => `- ${t.title} (record later with path_start draft:${r.draftId}:${t.index})`)]
           : []),
       ].join("\n"),
     );

package/package.json

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