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

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 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.
 
 ## What the visitors will and won't do
 

package/agents/new-research.md

@@ -56,14 +56,31 @@ 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
 
-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.
+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.
+
+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. Record each task's expected path
+
+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.
+
+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>`:
+
+{{path_walk}}
+
+### Show the user, then save
+
+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.
 
-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.
+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.
 
 Do not change any code.

package/mcp/path.js

@@ -150,6 +150,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) {
@@ -164,7 +170,12 @@ 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.`);
+    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();
     await this.stop();
     const s = this.hub.site(full);
@@ -407,10 +418,13 @@ 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 || "" };
+    // 초안 과제(new-research, 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.`,
+      `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.`
         : "",

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

@@ -713,10 +713,20 @@ server.registerTool(
   },
   wrap(async (args) => {
     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 });
     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}`),
+            ]
+          : []),
       ].join("\n"),
     );
   }),
@@ -843,6 +853,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 +933,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.3",
   "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",