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

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/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.2",
   "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",