@usercase/mcp 0.2.1 → 0.2.2-next.0

package/agents/focus.md

@@ -0,0 +1,26 @@
+## This run has a focus: {{focus}}
+
+The user wants this run to be about one part of the site — "{{focus}}" (it may name more than one feature). Everything below still applies, with these changes:
+
+**Step 2 — pin down what the focus means.** After you build the feature map, find which features, pages and routes "{{focus}}" covers. Before casting anyone, tell the user in one or two lines what you understood (e.g. "the calendar = /calendar and the event detail popup") and wait for them to confirm. If you cannot find it on the map, or it could mean several things, ask — do not guess from the word alone.
+
+Then check what the focus needs before anyone is cast:
+- If it is only reachable when signed in, demo account sign-in is required, not optional — say so, and if signed-in visits turn out to be impossible, tell the user the focus cannot really be reached and ask whether to go on.
+- If it is mostly writing to the site (comments, posting, saving, sign-up) and writes are not sent, tell the user when you ask about writes: with "not sent", visitors reach it but it is never really tried.
+
+**Step 3 — cast for the focus instead of spreading over the whole map.** Every person comes with a reason that makes the focus a natural part of their visit, and their `feature` is the focused feature they are about (if the focus names several, spread people over them). Everything else in the casting rules stays: varied people, their own words, a main reason that can lead on — never "test the calendar".
+
+Split how they arrive, about half and half:
+- **Straight in:** they land on a page of the focus itself (a bookmark, a shared link, a search result that opened it). This shows how the feature works for someone already there.
+- **Find it:** they land on the front page or a related page — wherever their arrival really takes them — and the focus is something they would need to get to. This shows whether people can find it.
+
+Do not add people who have nothing to do with the focus. In later rounds, cast new people for the same focus.
+
+**Step 4 — unchanged.** The visitors are never told about the focus.
+
+**Step 5 — open the report with the focus.** Before the usual report, using each visit's `Pages` line from `results` and the focus routes you confirmed:
+- how many people reached the focus — of those who landed straight in, and of those who had to find it
+- for those who had to find it and did not: where they went instead and where they stopped
+- what happened inside the focus: how far people got, and what they said or did there
+
+Then give the usual report for the rest of what visitors did.

package/agents/research.md

@@ -5,6 +5,8 @@ How many people: {{count_line}}
 
 You are the coordinator. Virtual users will visit the site in a real browser, one sub-agent per person, and answer the Usercase survey cards they happen to meet. Their answers become findings in the Usercase dashboard.
 
+{{focus}}
+
 ## 0. Setup (once)
 
 Call `setup` first. If it says it installed or updated the agent, ask the user to restart Claude Code and run this again — until then the visitors would use the old one, or none.

package/mcp/hub.js

@@ -431,6 +431,7 @@ class Hub {
     // 개인정보 칸. 사이트가 막은 게 아니라 이 사람이 안 친 것이다 — 그렇게 알린다
     if (r.personalField !== undefined) said.push(`You don't type personal details such as your email, phone number or real name into this site on this visit, so you left that field empty. Carry on as you would without filling it in — skip it, or go elsewhere.`);
     if (r.closedOverlay) said.push("Something was open on top of the page; your click landed outside it and closed it, so it did not reach what you clicked.");
+    if (r.cappedTimes) said.push(`You did that ${r.cappedTimes} times in a row — that is the most in one go. What you see is after ${r.cappedTimes}; to go on, do it again.`);
     if (r.missed) said.push("Your click landed just outside it and nothing happened.");
     if (r.typos) said.push(`(You made ${r.typos} typo(s) and fixed them.)`);
     if (v.ended) {
@@ -750,6 +751,7 @@ function summarize(row) {
   const card = row.card ? `Card "${row.card.question}" → ${row.card.result === "close" ? "closed" : row.card.answer}` : "No card";
   return [
     `${row.person} (${row.device}) · ${row.entry?.how ?? "?"} → ${row.entry?.path ?? "/"} · ${row.steps.length} steps · ${Math.round(row.ms / 1000)}s`,
+    row.pages?.length ? `Pages: ${row.pages.join(" → ")}` : "",
     card,
     last ? `Last: ${last.action} — ${last.why}` : row.blocked ? "Stopped at a block page" : "",
   ]

package/mcp/server.js

@@ -655,9 +655,13 @@ server.registerPrompt(
   "research",
   {
     description: "Research this site with Usercase virtual users",
-    argsSchema: { url: z.string().optional(), count: z.string().optional().describe('How many people (default 5), or "unlimited" to keep going until you stop it') },
+    argsSchema: {
+      url: z.string().optional(),
+      count: z.string().optional().describe('How many people (default 5), or "unlimited" to keep going until you stop it'),
+      focus: z.string().optional().describe("Only people who come for this part of the site, e.g. calendar, or comments and sharing"),
+    },
   },
-  ({ url, count }) => {
+  ({ url, count, focus }) => {
     const plan = researchPlan(count);
     run = { total: plan.total, since: Date.now() };
     // 사람 만드는 규칙은 우리 AI 로 만들 때와 같은 원본(people.md)에서 가져온다 — 두 벌로 두지 않는다.
@@ -669,8 +673,14 @@ server.registerPrompt(
         .replace(/\r\n/g, "\n")
         .replace(/^# Role:.*\n+/, "")
         .replace(/^#/gm, "###");
+    // focus 가 있으면 그 기능에 올 사람만 — 바뀌는 단계만 따로 적은 글을 앞에 붙인다. 방문자는 모른다
+    const f = (focus || "").trim();
+    const focusPart = f
+      ? fs.readFileSync(path.join(__dirname, "..", "agents", "focus.md"), "utf8").replace(/\r\n/g, "\n").replaceAll("{{focus}}", f).trim() + "\n\n"
+      : "";
     const body = fs
       .readFileSync(path.join(__dirname, "..", "agents", "research.md"), "utf8")
+      .replace("{{focus}}\n", focusPart)
       .replace("{{url}}", url || "(ask the user)")
       .replace("{{count_line}}", plan.line)
       .replace("{{rounds}}", plan.rounds)

package/package.json

@@ -1,43 +1,43 @@
-{
-  "name": "@usercase/mcp",
-  "version": "0.2.1",
-  "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",
-  "type": "commonjs",
-  "main": "mcp/server.js",
-  "bin": {
-    "usercase-mcp": "mcp/server.js"
-  },
-  "files": [
-    "mcp/",
-    "src/browser/",
-    "src/persona/",
-    "src/run/",
-    "src/prompts/",
-    "agents/",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "check": "node --check mcp/server.js && node scripts/onboarding.js --check && node scripts/agents.js --check",
-    "docs": "node scripts/onboarding.js && node scripts/agents.js",
-    "release:next": "node scripts/release.js next",
-    "release:promote": "node scripts/release.js promote",
-    "release:rollback": "node scripts/release.js rollback",
-    "release:status": "node scripts/release.js status"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
-    "playwright": "^1.58.2",
-    "zod": "^4.6.5"
-  },
-  "devDependencies": {
-    "@google/genai": "^2.23.0"
-  }
-}
+{
+  "name": "@usercase/mcp",
+  "version": "0.2.2-next.0",
+  "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",
+  "type": "commonjs",
+  "main": "mcp/server.js",
+  "bin": {
+    "usercase-mcp": "mcp/server.js"
+  },
+  "files": [
+    "mcp/",
+    "src/browser/",
+    "src/persona/",
+    "src/run/",
+    "src/prompts/",
+    "agents/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "node --check mcp/server.js && node scripts/onboarding.js --check && node scripts/agents.js --check",
+    "docs": "node scripts/onboarding.js && node scripts/agents.js",
+    "release:next": "node scripts/release.js next",
+    "release:promote": "node scripts/release.js promote",
+    "release:rollback": "node scripts/release.js rollback",
+    "release:status": "node scripts/release.js status"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "playwright": "^1.58.2",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@google/genai": "^2.23.0"
+  }
+}

package/src/browser/page.js

@@ -188,14 +188,16 @@ async function listControls(page, max = 60) {
         // 같은 크기로 여럿 되풀이되는 아이콘(달력 칸마다의 표시)부터 뺀다. 한두 개뿐인 것(이전·다음 화살표)은 남긴다
         const bySize = {};
         for (const c of inView) if (isIcon(c)) bySize[c.size] = (bySize[c.size] || 0) + 1;
-        const keep = new Set(
-          inView
-            .filter(isIcon)
-            .map((c, k) => ({ c, k, rep: bySize[c.size] }))
-            .sort((a, b) => a.rep - b.rep || a.k - b.k)
-            .slice(0, Math.max(0, max - named))
-            .map((x) => x.c),
-        );
+        const ranked = inView
+          .filter(isIcon)
+          .map((c, k) => ({ c, k, rep: bySize[c.size] }))
+          .sort((a, b) => a.rep - b.rep || a.k - b.k);
+        // 한두 개뿐인 아이콘(이전·다음 화살표, 닫기)은 이름 있는 것만으로 넘쳐도 남긴다 — 일정이 꽉 찬 달에서
+        // 이름 있는 칸만 100개가 넘어 화살표가 빠지고, 달을 못 넘겼다(10/20 실험실 p11, bluetags 2023년 9월)
+        const keep = new Set([
+          ...ranked.filter((x) => x.rep <= 2).slice(0, 4).map((x) => x.c),
+          ...ranked.slice(0, Math.max(0, max - named)).map((x) => x.c),
+        ]);
         pool = pool.filter((c) => c.where !== "in view" || !isIcon(c) || keep.has(c));
         iconsLeft = shown.length - pool.length;
       }

package/src/run/visit.js

@@ -436,6 +436,8 @@ class Visit {
     const record = { step: this.steps.length + 1, t: Date.now() - this.t0, path: view.path, action: decision.action, why: decision.why, label: item?.label ?? null };
     const times = Math.max(1, Math.min(MAX_TIMES[decision.action] || 1, Math.round(Number(decision.times) || 1)));
     if (times > 1) record.times = times;
+    // 한 번에 할 수 있는 수보다 많이 달라고 했다. 말없이 줄이면 "사이트가 클릭을 삼킨다" 로 읽었다(10/20 실험실 p7: 15·20·30번이 다 4번)
+    if (Math.round(Number(decision.times) || 1) > times) record.cappedTimes = times;
     const before = page.url();
     const offsiteBefore = this.offsite.length;
     const notSentBefore = this.notSent.length;
@@ -615,7 +617,7 @@ class Visit {
 
     this.steps.push(record);
     this.history.push(
-      `${decision.action}${times > 1 ? ` ×${times}` : ""}${item ? ` "${item.label}"` : ""} — ${decision.why}${record.skipped ? ` (${record.skipped})` : ""}${record.offsite ? ` (it leads to another website, ${record.offsite})` : ""}${record.notSent ? " (it would have sent something to the site; it was not sent)" : ""}${record.fileWindow ? " (a window to choose a file opened; you closed it without choosing)" : ""}${record.personalField !== undefined ? " (you chose not to enter personal details there)" : ""}${record.openedApp ? " (it tried to open another app; nothing opened)" : ""}`,
+      `${decision.action}${times > 1 ? ` ×${times}` : ""}${item ? ` "${item.label}"` : ""} — ${decision.why}${record.skipped ? ` (${record.skipped})` : ""}${record.cappedTimes ? " (that is the most in one go)" : ""}${record.offsite ? ` (it leads to another website, ${record.offsite})` : ""}${record.notSent ? " (it would have sent something to the site; it was not sent)" : ""}${record.fileWindow ? " (a window to choose a file opened; you closed it without choosing)" : ""}${record.personalField !== undefined ? " (you chose not to enter personal details there)" : ""}${record.openedApp ? " (it tried to open another app; nothing opened)" : ""}`,
     );
     this.log(`${record.step}. ${decision.action}${item ? ` "${String(item.label).slice(0, 30)}"` : ""}${record.skipped ? ` · ${record.skipped}` : ""} — ${decision.why}`);
     this.lastView = null;