@usercase/mcp 0.2.11-next.1 → 0.2.11-next.3

package/agents/fix.md

@@ -0,0 +1,36 @@
+# Fix a problem found by a Usercase research
+
+Research: {{research}}
+Finding: {{finding}}
+Report: {{audience}}
+
+A Usercase research watched people (or virtual users) do tasks on this site. Its report lists findings — problems on the site, each backed by what people did, what the screen showed in the recordings, and what they wrote. You fix one finding in this repository's code.
+
+## 1. Read the finding
+
+Call `report_finding` with the research id, the finding key and the report. If no finding key is given above, call `report_findings` first, show the user the list (key, severity, title, and whether someone is already fixing it), and ask which one to fix.
+
+Read all of it: the title and why, who it hit, the screen checks (what the page really showed — these come from the recordings, not from opinions), the paths people took, the groups of what they wrote, and the suggested changes. The suggested changes were written without seeing the code; treat them as a direction, not a spec.
+
+## 2. Find the code
+
+From the pages, buttons and texts in the evidence, find the code behind them: routes, the page components, the button and its click handler, the text shown. Confirm you found the right place by matching the exact text on screen (a button label, a heading) to the code.
+
+## 3. Propose the change — before changing anything
+
+Tell the user, briefly:
+- what in the code causes the problem, with file paths,
+- the change you propose and why it addresses what people did and said, and
+- anything the finding suggests that you would not do, and why (it would break something, it needs a product decision, the code already does it).
+
+Keep the change as small as solves the problem. Do not redesign unrelated parts. Wait for the user's approval or corrections.
+
+## 4. Change the code
+
+When the user approves, call `report_fix` with `status` `fixing` and the files you will change. Then make the change. Follow the repository's own conventions, and run its checks (type check, lint, tests) if it has them.
+
+## 5. Record the fix
+
+When the change is done, call `report_fix` with `status` `fixed`, the files changed, a one-sentence summary written for the team (what a visitor now sees differently), and the pull request link if you opened one. Do not commit, push or open a pull request unless the user asks.
+
+Then tell the user that the finding shows as fixed in the report, and how to check it worked: {{check}}

package/mcp/hub.js

@@ -450,7 +450,12 @@ class Hub {
       external,
       study: research
         ? {
-            press: (k) => study.press(page, k),
+            // 패널 옮기기는 막혔던 자리에서 비키게 끈다. 옮기고 나면 그 항목은 목록에서 내린다
+            press: async (k) => {
+              if (k !== "move") return study.press(page, k);
+              await study.movePanel(page, rec.panelInWay);
+              rec.panelInWay = null;
+            },
             // 과제 질문·시간 초과 창이 페이지를 덮고 있나 — 그 사이 조작은 페이지에 닿지 않는다
             blocking: async () => {
               const w = study.isSurveyUrl(page.url()) ? null : await study.readStudy(page);
@@ -505,6 +510,9 @@ class Hub {
     if (look.ended) return "This visit has ended.";
     if (look.card) return renderCard(look.card);
     // 과제 건너뛰기는 위젯 단추다. 화면 목록 끝에 붙인다 — 누르면 Visit 이 위젯을 누른다
+    // 우리 패널이 누르려던 것을 덮었다 — 사람은 패널을 끌어 비킨다(11/04 실험실 covered_by_panel 3건: 캘린더 Week·Month)
+    if (st && rec.panelInWay && !look.view.dialog)
+      look.view.items.push({ i: look.view.items.length, label: "Drag the study panel aside (it is covering the page)", where: "study panel, by its top bar", study: "move" });
     if (st && st.skip && !look.view.dialog) look.view.items.push({ i: look.view.items.length, label: `${st.skip} (in the study panel — gives up on this task)`, where: "study panel, corner of the screen", study: "skip" });
     // 아직 건너뛸 수 없는 과제 — 예전엔 "패널 기다리기" 를 줘서 막히면 몇 분씩 아무것도 안 했다(라이브 11번 × 약 5분).
     // 사람은 막히면 계속 찾아본다. 그러다 실패 시간이 지나면 SDK 가 묻는 창을 띄우고, 다음 화면에서 그 창이 먼저 보인다
@@ -780,6 +788,7 @@ class Hub {
     if (TRACE) trace(rec, { ev: "act", action: decision.action, study: r && r.study, actMs: Date.now() - a0, waitTurnMs: v.lastWaitMs || 0, sdk: await sdkSnap(rec.page) });
     // 패널의 건너뛰기를 눌렀다 — 그 과제를 건너뛴 것으로 남긴다
     if (r && r.study === "skip" && !r.skipped && rec.study) rec.study.skipped.push(rec.study.lastTask);
+    if (r && r.panelAt && rec.study) rec.panelInWay = r.panelAt;
     if (r.interrupted && r.study) {
       rec.cutOff = true;
       return ["Before you could do that, the study asked you something.", "", await this.screen(rec)].join("\n");

package/mcp/report.js

@@ -292,6 +292,11 @@ const sendSteps = (session, body) => keyed("PUT", `/agent/questions/steps/${enco
 /** 리서치 초안(new-research) — 무엇을 리서치할지 고를 근거와, Inbox 초안으로 저장 */
 const getResearchContext = () => keyed("GET", "/agent/researches/context", null, 30000);
 const saveResearchDraft = (body) => keyed("POST", "/agent/researches/drafts", body, 30000);
+/** 리서치 Report(fix) — 발견 목록, 발견 하나와 근거, 고친 기록 */
+const rq = (audience) => (audience === "real" ? "?audience=real" : "?audience=virtual");
+const getReport = (researchId, audience) => keyed("GET", `/agent/researches/${encodeURIComponent(researchId)}/report${rq(audience)}`);
+const getFinding = (researchId, key, audience) => keyed("GET", `/agent/researches/${encodeURIComponent(researchId)}/report/findings/${encodeURIComponent(key)}${rq(audience)}`);
+const saveFix = (researchId, key, body) => keyed("PUT", `/agent/researches/${encodeURIComponent(researchId)}/report/findings/${encodeURIComponent(key)}/fix`, body);
 /** 대시보드 주소. API 주소에서 /koa 를 뗀다 */
 const dashboardUrl = (p) => apiBase().replace(/\/koa$/, "") + p;
 
@@ -315,5 +320,8 @@ module.exports = {
   sendSteps,
   getResearchContext,
   saveResearchDraft,
+  getReport,
+  getFinding,
+  saveFix,
   dashboardUrl,
 };

package/mcp/server.js

@@ -556,6 +556,87 @@ server.registerTool(
 
 const recorder = new PathRecorder(hub);
 
+// ── 리서치 Report 의 발견 고치기(fix) ──
+const audienceArg = z.enum(["virtual", "real"]).optional().describe("Which report: virtual users (default) or real people");
+const fixLine = (f) => (f ? ` — ${f.status === "fixed" ? "fixed" : "being fixed"}${f.agent ? ` by ${f.agent}` : ""}` : "");
+const whoWord = (audience) => (audience === "real" ? "people" : "virtual users");
+
+server.registerTool(
+  "report_findings",
+  {
+    description:
+      "List the findings of a Usercase research's latest report (key, severity, title, who, and whether one is being fixed). Use when the fix command has no finding key.",
+    inputSchema: { research: z.string().describe("The research id"), audience: audienceArg },
+  },
+  wrap(async ({ research, audience }) => {
+    const r = await report.getReport(research, audience);
+    if (!r.findings)
+      return text(r.making ? "The report is being written right now. Try again in a minute." : `This research has no ${whoWord(r.audience)} report yet. It is written once 5 have finished.`);
+    return text(
+      [
+        `${r.research.title} — report of ${r.people} ${whoWord(r.audience)}`,
+        `Summary: ${r.summary}`,
+        "",
+        ...r.findings.map((f) => `${f.key} [${f.severity}] ${f.title} — ${f.who}${fixLine(f.fix)}`),
+        "",
+        `Report: ${r.url}`,
+      ].join("\n"),
+    );
+  }),
+);
+
+server.registerTool(
+  "report_finding",
+  {
+    description:
+      "Read one finding of a Usercase research report with all its evidence: why, who, the screen checks from the recordings, the paths people took, what they wrote, and the suggested changes. Read it before looking for the code.",
+    inputSchema: { research: z.string().describe("The research id"), finding: z.string().describe("Finding key, e.g. F1"), audience: audienceArg },
+  },
+  wrap(async ({ research, finding, audience }) => {
+    const r = await report.getFinding(research, finding, audience);
+    const f = r.finding;
+    const e = r.evidence;
+    const L = [
+      `${f.key} [${f.severity}] ${f.title}${fixLine(f.fix)}`,
+      `Research: ${r.research.title} (report of ${r.people} ${whoWord(r.audience)})`,
+      "",
+      `Why: ${f.why}`,
+      `Who: ${f.who}`,
+      `Where: ${f.where}`,
+    ];
+    if (e.screen.length) L.push("", "What the screen showed (from the recordings):", ...e.screen.map((x) => `- ${x.replace(/^Screen check:\s*/, "")}`));
+    if (e.paths.length) L.push("", "Paths people took:", ...e.paths.map((p) => `- ${(p.steps || []).join(" → ")} (${p.people} people)`));
+    if (e.words.length) L.push("", "What people wrote (grouped by meaning, with examples):", ...e.words.map((w) => `- ${w.text}`));
+    if (e.numbers.length) L.push("", "Numbers:", ...e.numbers.map((x) => `- ${x}`));
+    L.push("", "Suggested changes (written without seeing the code):", ...f.changes.map((c, i) => `${i + 1}. ${c}`), `Check after the fix: ${f.measure}`);
+    if (r.sessionsUrl) L.push("", `Watch these sessions: ${r.sessionsUrl}`);
+    L.push(`Report: ${r.reportUrl}`);
+    return text(L.join("\n"));
+  }),
+);
+
+server.registerTool(
+  "report_fix",
+  {
+    description:
+      "Record on the research report that you are fixing a finding (status fixing, once the user approved the change) or have fixed it (status fixed, with the files, a one-sentence summary for the team, and the pull request link if any). The report shows it on that finding.",
+    inputSchema: {
+      research: z.string().describe("The research id"),
+      finding: z.string().describe("Finding key, e.g. F1"),
+      audience: audienceArg,
+      status: z.enum(["fixing", "fixed"]),
+      files: z.array(z.string()).optional().describe("Repository paths of the files changed (or to be changed)"),
+      summary: z.string().optional().describe("One sentence for the team: what visitors now see differently"),
+      prUrl: z.string().optional().describe("Pull request link, if one was opened"),
+    },
+  },
+  wrap(async ({ research, finding, audience, status, files, summary, prUrl }) => {
+    const agent = CODEX ? "Codex" : OTHER ? null : "Claude Code";
+    const r = await report.saveFix(research, finding, { audience: audience || "virtual", status, agent, files, summary, prUrl });
+    return text(`${r.key} is marked ${r.status} on the report: ${r.reportUrl}`);
+  }),
+);
+
 server.registerTool(
   "path_tasks",
   {
@@ -1047,6 +1128,21 @@ const COMMANDS = {
         "Only this repository's folder changes. Other repositories keep their own project. Until the new project is approved, the current connection stays.",
       ].join("\n"),
   },
+  // 리서치 Report 의 발견 하나를 고친다 — 대시보드 Report 의 "Fix with your agent" 명령
+  fix: {
+    description: "Fix a finding from a Usercase research report in this repository's code",
+    argsSchema: { research: z.string().optional(), finding: z.string().optional(), audience: z.string().optional() },
+    body: ({ research, finding, audience }) =>
+      agentDoc("fix.md", {
+        research: research || "(ask the user — the dashboard Report shows the command)",
+        finding: finding ? String(finding).toUpperCase() : "(not given — list the findings and ask)",
+        audience: audience === "real" ? "real (the report of real people)" : "virtual (the report of virtual users)",
+        check:
+          audience === "real"
+            ? "the next report, made as more people take part, shows whether people still hit it."
+            : `run the same tasks with virtual users again (${cmd("research")} <site> 5 research=${research || "<research id>"}). The next report shows whether they still hit it.`,
+      }),
+  },
   steps: {
     description: "Write the steps for the question open in your dashboard (New question → Several steps)",
     argsSchema: { session: z.string().optional().describe("The window id shown in the dashboard command") },
@@ -1059,12 +1155,13 @@ if (PLUGIN || CODEX || OTHER) {
     "instructions",
     {
       description:
-        "The step-by-step instructions for a Usercase command (research, install, path, question, new-research, steps, connect). The plugin's /usercase:* commands call this; follow what it returns as the user's request.",
+        "The step-by-step instructions for a Usercase command (research, install, path, question, new-research, steps, connect, fix). The plugin's /usercase:* commands call this; follow what it returns as the user's request.",
       inputSchema: {
         command: z.enum(Object.keys(COMMANDS)),
         ...COMMANDS.research.argsSchema,
         ...COMMANDS.path.argsSchema,
         ...COMMANDS.steps.argsSchema,
+        ...COMMANDS.fix.argsSchema,
       },
     },
     wrap(async ({ command, ...args }) => text(COMMANDS[command].body(byName(args, COMMANDS[command].argsSchema)))),

package/package.json

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

package/src/browser/hand.js

@@ -133,7 +133,8 @@ async function coveredBy(page, el) {
     )
     .catch(() => null);
   if (!hit) return null;
-  if (hit.own === "panel") return { say: "the study panel is on top of it — scroll or move so it is not under the panel" };
+  // 패널은 끌어 옮길 수 있다(core Widget 알약 드래그). 막힌 자리를 같이 넘겨 hub 가 "패널 옮기기" 를 화면 목록에 붙인다
+  if (hit.own === "panel") return { say: "the study panel is on top of it — drag the panel aside (it is in the list), or scroll so it is not under the panel", panelAt: { x: cx, y: cy } };
   if (hit.own) return { say: "the survey card is on top of it" };
   if (hit.text) return { say: `something else on the screen is on top of it ("${hit.text}") — you cannot reach it until that is out of the way` };
   return { invisible: true, x: cx, y: cy };
@@ -387,6 +388,7 @@ async function clickLikePerson(page, state, el) {
       if (startY !== null) await page.evaluate((y) => window.scrollTo({ top: y, behavior: "instant" }), startY).catch(() => {});
       const e = new Error(cover.say);
       e.human = cover.say;
+      if (cover.panelAt) e.panelAt = cover.panelAt;
       throw e;
     }
     // 화면 가장자리 밖으로 잘려 나간 것. 굴려도 옆으로는 안 온다 — 사람은 "잘려 있다" 를 본다.

package/src/browser/study.js

@@ -180,6 +180,52 @@ const PRESS = {
   submit: "#eb-plugin #eb-survey-action-btn",
 };
 
+/**
+ * 리서치 패널을 끌어 비킨다 — 알약(#eb-pill)을 잡고 끌면 패널이 같이 움직인다(core components/widget/Widget.ts setupDrag).
+ * 막혔던 자리(away)의 반대쪽 가장자리로. 그래도 덮으면 위아래도 바꾼다. 고객이 끌기를 껐으면(draggable 0) 안 움직인다
+ */
+async function movePanel(page, away) {
+  const vp = page.viewportSize() || { width: 1280, height: 860 };
+  const pill = page.locator("#eb-plugin #eb-pill").first();
+  const covers = (pt) =>
+    pt
+      ? page
+          .evaluate(([x, y]) => {
+            const h = document.elementFromPoint(x, y);
+            return !!(h && h.closest("#eb-plugin"));
+          }, [pt.x, pt.y])
+          .catch(() => false)
+      : Promise.resolve(false);
+  const drag = async (tx, ty) => {
+    const b = await pill.boundingBox();
+    if (!b) throw new Error("the study panel is not on the screen");
+    const sx = b.x + b.width / 2;
+    const sy = b.y + b.height / 2;
+    await page.mouse.move(sx, sy, { steps: 6 });
+    await sleep(120 + Math.random() * 200);
+    await page.mouse.down();
+    await page.mouse.move(sx + (tx - sx) * 0.5 + (Math.random() - 0.5) * 30, sy + (ty - sy) * 0.5 + (Math.random() - 0.5) * 30, { steps: 10 });
+    await page.mouse.move(tx, ty, { steps: 8 });
+    await sleep(80 + Math.random() * 150);
+    await page.mouse.up();
+    await sleep(300);
+    const a = await pill.boundingBox();
+    return a && Math.hypot(a.x - b.x, a.y - b.y) > 20;
+  };
+  const b = await pill.boundingBox();
+  if (!b) throw new Error("the study panel is not on the screen");
+  const half = b.width / 2;
+  const ax = away ? away.x : b.x + half;
+  const ay = away ? away.y : b.y;
+  // 옆으로 — 막힌 자리의 반대쪽 끝
+  const tx = ax < vp.width / 2 ? vp.width - half - 24 : half + 24;
+  if (!(await drag(tx, b.y + b.height / 2))) throw new Error("the panel did not move — it stays where it is");
+  if (!(await covers(away))) return;
+  // 패널이 길어 아직 덮는다 — 위아래도 반대쪽으로
+  const ty = ay < vp.height / 2 ? vp.height - b.height - 24 : 24 + b.height / 2;
+  await drag(tx, ty);
+}
+
 /** 위젯 단추를 누른다 */
 async function press(page, key) {
   const sel = PRESS[key];
@@ -211,4 +257,4 @@ async function answerQuestion(page, q, answer) {
   return null;
 }
 
-module.exports = { readStudy, waitState, join, press, answerQuestion, isSurveyUrl };
+module.exports = { readStudy, waitState, join, press, movePanel, answerQuestion, isSurveyUrl };

package/src/run/visit.js

@@ -727,7 +727,7 @@ class Visit {
     // 리서치 위젯의 단추(과제 건너뛰기). 페이지 조작이 아니라 위젯을 누른다 — 화면 목록에 hub 가 붙여 둔 것이다
     if (decision.action === "click" && item && item.study && this.study) {
       record.study = item.study;
-      await this.study.press(item.study).catch(() => (record.skipped = "it did not respond"));
+      await this.study.press(item.study).catch((e) => (record.skipped = item.study === "move" && e && e.message ? e.message : "it did not respond"));
       await sleep(1500);
       this.steps.push(record);
       this.history.push(`click "${item.label}" — ${decision.why}${record.skipped ? ` (${record.skipped})` : ""}`);
@@ -892,7 +892,7 @@ class Visit {
           let ours = false;
           const clicked = await hand
             .clickLikePerson(page, this.handState, el)
-            .catch((e) => ((record.skipped = e.human || humanClickError(e)), (ours = /eb-insight|eb-plugin/.test(String(e.message))), { missed: false }));
+            .catch((e) => ((record.skipped = e.human || humanClickError(e)), (record.panelAt = e.panelAt || undefined), (ours = /eb-insight|eb-plugin/.test(String(e.message))), { missed: false }));
           // 사이트의 무언가가 덮어 못 눌렀다. 우리 카드·위젯이 덮은 것은 사이트 탓이 아니다
           if (record.skipped && /on top of it/.test(record.skipped) && !/survey card|study panel/.test(record.skipped) && !ours)
             await this.shoot(record, "covered", await boxOf(page, el));