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

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. Afterwards, `/mcp__usercase__path <research id>` records each task's expected path.
+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

@@ -56,14 +56,42 @@ One research is **one flow a participant can walk in one sitting**: 1–4 tasks,
 
 **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.
 
+**Wording people read** (the start screen, the invite line):
+- Say plainly what they will do and roughly how long it takes.
+- 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
+
+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;
+- **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).
+
+## 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.
+
+## 8. On approval: record the routes, then save
+
+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}}
+
+### 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 whole research compactly: the purpose and its evidence, each task with how it counts as done (in plain words: "done when they reach the order page"), the questions, and the invite. Change whatever they ask for.
+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 `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;
-- after it is created, `{{path_cmd}}` with the research id records each task's expected path, so the results can tell who went straight from who took a detour.
+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);
@@ -150,6 +165,12 @@ class PathRecorder {
       .join("\n");
   }
 
+  /** 방금 저장한 리서치 초안의 과제들(new-research) — draft:<초안>:<번호> 로 path_start 에 쓴다 */
+  addDraft(draftId, { title, website, tasks }) {
+    const research = { title, status: "draft", website };
+    for (const t of tasks) this.known.set(`draft:${draftId}:${t.index}`, { research, task: { taskId: `draft:${draftId}:${t.index}`, title: t.title } });
+  }
+
   async open(s, { device, account }) {
     let storageState;
     if (account) {
@@ -163,15 +184,24 @@ class PathRecorder {
 
   /** 새로 기록을 시작한다. 같은 과제를 다시 하면 처음부터 */
   async start({ task, url, device = "desktop", account = null }) {
-    const k = this.known.get(String(task));
-    if (!k) throw new Error(`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();
+    // 아직 저장 안 한 리서치의 과제(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.`,
+      );
+    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 };
@@ -407,13 +437,26 @@ class PathRecorder {
       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 };
-    const r = await report.savePath(c.taskId, body);
+    else if (success === "click") body.success = { condition: "element_click", xpath: last.xpath, xpathUrl: last.url, classes: last.classes, ids: last.ids, label: last.label || "" };
+    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}"`}` : ""}. 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.`
-        : "",
+      `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}`,
+      cutLine,
     ]
       .filter(Boolean)
       .join("\n");

package/mcp/report.js

@@ -279,6 +279,8 @@ const getResearchTasks = (researchId) => keyed("GET", `/agent/researches/${encod
 
 /** 과제의 정상 경로를 통째로 바꾼다. 화면을 올리느라 오래 걸릴 수 있다 */
 const savePath = (taskId, body) => keyed("PUT", `/agent/tasks/${encodeURIComponent(taskId)}/path`, body, 90000);
+/** 아직 리서치가 안 된 초안 과제의 경로(new-research) — 초안에 둔다 */
+const saveDraftPath = (draftId, index, body) => keyed("PUT", `/agent/researches/drafts/${encodeURIComponent(draftId)}/tasks/${index}/path`, body, 90000);
 
 /** 질문 만들기(question) — 최근 방문을 읽어야 해서 조금 걸린다 */
 const getQuestionContext = () => keyed("GET", "/agent/questions/context", null, 60000);
@@ -305,6 +307,7 @@ module.exports = {
   sendDiagnostics,
   getResearchTasks,
   savePath,
+  saveDraftPath,
   getQuestionContext,
   checkQuestion,
   saveQuestion,

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"),
@@ -713,10 +713,33 @@ server.registerTool(
   },
   wrap(async (args) => {
     const r = await report.saveResearchDraft(args);
+    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)}`,
+        ...(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"),
     );
   }),
@@ -843,6 +866,19 @@ const agentDoc = (name, vars = {}) => {
   return body;
 };
 
+/** path.md 의 "## 3. Walk it" ~ "## 4. Check it" 끝까지 — 제목은 한 단계 낮추고 번호를 뗀다 */
+const pathWalkRules = () => {
+  const d = doc("path.md");
+  const from = d.indexOf("## 3. Walk it");
+  const to = d.indexOf("## 5.");
+  if (from < 0 || to < 0) throw new Error("agents/path.md lost its Walk it / Check it sections");
+  return d
+    .slice(from, to)
+    .replace(/^## \d+\. /gm, "### ")
+    .replace(/\n*Do not change any code\.\n*/g, "\n\n")
+    .trim();
+};
+
 /**
  * 명령 지시문. 따로 쓰면 MCP 프롬프트(/mcp__usercase__research), 플러그인이면 instructions 도구(/usercase:research 스킬이 부른다)로
  * 같은 글이 나간다
@@ -910,7 +946,8 @@ const COMMANDS = {
   // 리서치 초안 — 무엇을 알고 싶은지는 대화로 묻는다(인자 없음, question 과 같은 이유)
   "new-research": {
     description: "Plan a Usercase research from your data and code — your agent suggests what to research, writes the tasks and questions, and saves a draft",
-    body: () => agentDoc("new-research.md", { research_cmd: cmd("research"), path_cmd: cmd("path") }),
+    // 경로를 걷고 확인하는 규칙은 path 명령과 한 벌 — path.md 의 3·4 단계를 그대로 싣는다
+    body: () => agentDoc("new-research.md", { research_cmd: cmd("research"), path_cmd: cmd("path"), path_walk: pathWalkRules() }),
   },
   // 프로젝트 바꾸기 — 연결은 저장소 폴더마다라 이 저장소만 바뀐다
   connect: {

package/package.json

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