@usercase/mcp 0.0.0-stage → 0.2.1-next.0

package/mcp/server.js

@@ -0,0 +1,679 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * 어닝버드 MCP 서버(stdio). 고객의 AI 도구(Claude Code 등)가 저장소 폴더에서 띄운다.
+ *
+ * 역할이 둘로 갈린다(PLAN.md).
+ * - **메인 에이전트**: 저장소를 읽고 사이트를 이해해 가상 사용자를 만든다(save_people), 점검한다(check_site),
+ *   사람마다 서브에이전트를 띄우고 결과를 모은다(results)
+ * - **가상 사용자 서브에이전트**(`usercase-visitor`): 그 사람이 되어 open_visit → act → answer_card 로 한 걸음씩 걷는다.
+ *   **파일을 보지 않는다** — 도구가 이 서버의 것만 허용된 에이전트다. 코드를 알면 사람이 못 찾는 버튼을 바로 찾아 QA 값이 사라진다
+ *
+ * AI 비용은 고객 구독에서 나간다. 우리는 몸(브라우저·사람 손·막는 선)만 준다.
+ * **stdout 은 MCP 통신이다. 로그는 stderr 로만.**
+ */
+const { McpServer } = require("@modelcontextprotocol/sdk/server/mcp.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const { z } = require("zod");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { Hub } = require("./hub.js");
+const ws = require("./workspace.js");
+const persona = require("../src/persona/persona.js");
+const report = require("./report.js");
+const peopleRules = require("../src/persona/people.js");
+const { PathRecorder } = require("./path.js");
+
+const hub = new Hub();
+const server = new McpServer({ name: "usercase", version: require("../package.json").version });
+
+const text = (t) => ({ content: [{ type: "text", text: String(t) }] });
+const fail = (e) => ({ content: [{ type: "text", text: `Error: ${e.message}` }], isError: true });
+const wrap = (fn) => async (args) => {
+  try {
+    return await fn(args);
+  } catch (e) {
+    return fail(e);
+  }
+};
+
+// ── 메인 에이전트용 ──
+
+server.registerTool(
+  "check_site",
+  {
+    description:
+      "Open the site once as a virtual user and report: does it load, is the Usercase SDK running (which project), is a firewall/bot protection blocking us (and how to unblock, per vendor), is the secret key set. Always run this before starting visits. If it reports a block, stop and tell the user.",
+    inputSchema: { url: z.string().url().describe("The site to test, e.g. https://staging.example.com") },
+  },
+  wrap(async ({ url }) => text(await hub.checkSite(url))),
+);
+
+/** 설치 스크립트를 어디에 넣나 — 프레임워크별. 고객 저장소를 읽는 건 메인 에이전트다 */
+const PLACEMENT = [
+  "## Where to put it",
+  "Once, in the place every page goes through, inside <head> (or as early in <body> as the framework allows):",
+  "- Next.js App Router: app/layout.tsx — use next/script: <Script id=\"usercase\" strategy=\"afterInteractive\" dangerouslySetInnerHTML={{ __html: \"<the code inside the script tag>\" }} />",
+  "- Next.js Pages Router: pages/_document.tsx, inside <Head>, as a <script dangerouslySetInnerHTML={{ __html: ... }} />",
+  "- Plain HTML, Vite, Create React App: index.html (or every .html page), right before </head>",
+  "- Remix, Nuxt, SvelteKit, Astro, Gatsby: the root document or layout's head",
+  "- WordPress, Shopify and other themes: the header template (header.php, theme.liquid) before </head>",
+  "- Google Tag Manager only: tell the user to add it as a Custom HTML tag on All Pages instead of editing code",
+  "Do not change the code inside the tag: it carries this project's id. In JSX, keep it as a string, not parsed markup.",
+].join("\n");
+
+server.registerTool(
+  "install_snippet",
+  {
+    description:
+      "Get the Usercase script for the project this API key belongs to, with where to put it per framework. Use when check_site says the SDK is not running and you are in the site's repository: add the script once to the root layout/document, show the user the diff, then run check_site on the local site to confirm. Do not commit or deploy unless asked.",
+    inputSchema: {},
+  },
+  wrap(async () => {
+    const me = await report.getInstall();
+    return text(
+      [
+        `Project: "${me.title}" (${me.projectId})${me.website ? ` — ${me.website}` : ""}`,
+        "",
+        "## The script",
+        "```html",
+        me.snippet,
+        "```",
+        "",
+        PLACEMENT,
+        "",
+        `If the repository already contains "Usercase.project" or "Earningbirds.project": same id → already installed; a different id → ask the user which project is right.`,
+        "",
+        "## After adding it",
+        "1. Show the user the diff. Do not commit or deploy unless asked.",
+        "2. If the site runs locally (it may already be running — try its usual dev address), call check_site on it. Done when it says \"Usercase SDK is running\" with this project.",
+        "3. Tell the user real visitors are recorded once this is deployed, and offer to send a few virtual users now (the research prompt).",
+      ].join("\n"),
+    );
+  }),
+);
+
+/** 사람 한 줄: 기기 · 유입 → 착지 · 회원 · [기능] — 목적 */
+const personLine = (p) =>
+  `${p.device} · ${p.arrival}${p.landing ? ` → ${p.landing}` : ""}${p.member ? " · member" : ""}${p.feature ? ` · [${p.feature}]` : ""} — ${p.goal}`;
+
+/** 사람들이 어느 기능에 몰려 있나 — 다음 판에 빈 곳을 채우라고 보여 준다 */
+function coverageLine(people) {
+  const c = {};
+  for (const p of people) {
+    const k = p.feature || "(no feature)";
+    c[k] = (c[k] || 0) + 1;
+  }
+  return "Features so far: " + Object.entries(c).sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k} ${n}`).join(" · ");
+}
+
+const PERSON = z.object({
+  device: z.enum(["desktop", "mobile"]),
+  background: z.string().describe("Who they are, in one or two sentences"),
+  goal: z.string().describe("What they came to this site to do or find out, in their own terms"),
+  moment: z.string().describe("Their state right now: where they are, how much time, mood"),
+  attention: z.enum(["skims", "reads", "studies"]),
+  surveyHabit: z.enum(["ignores", "sometimes", "willing"]).describe("How they usually treat pop-up survey cards. Most people ignore them"),
+  writing: z.enum(["careless", "careful"]),
+  arrival: z.enum(["search", "social", "shared", "direct"]).describe("How they got here: search engine, a link in a feed or chat, a link someone sent, or typed the address / a bookmark"),
+  landing: z
+    .string()
+    .optional()
+    .describe(
+      "The page they land on, as a path on this site (e.g. /bluecard/6553c3ba5fae82d8976b6806, /watchlist, /calendar). The page their search result, link or bookmark would really open — for someone who searched for one announcement, that announcement. Take real paths from check_site's page list or the routes in the code. Leave out to land on the front page",
+    ),
+  feature: z
+    .string()
+    .optional()
+    .describe("Which part of the site this visit is about, from your feature map (e.g. calendar, comments, profile settings). For your coverage only — the visitor never sees it"),
+  member: z
+    .boolean()
+    .optional()
+    .describe("Already has an account and is signed in (uses a demo account saved by `login`). Mix members and non-members — all members hides what newcomers hit"),
+  account: z
+    .string()
+    .optional()
+    .describe("Members only: which demo account (a1, a2 …). Leave out — members are spread across the signed-in accounts and keep the same one"),
+  traits: z
+    .object({
+      readCps: z.number().describe("reading speed, chars/sec, 6–60"),
+      patience: z.number().describe("0.05–1"),
+      decisiveness: z.number().describe("0.05–1"),
+      distraction: z.number().describe("0–1"),
+      thoroughness: z.number().describe("0–1"),
+      mobileEase: z.number().describe("0–1"),
+    })
+    .partial()
+    .optional()
+    .describe("How they move. Omit to derive automatically"),
+});
+
+server.registerTool(
+  "save_people",
+  {
+    description:
+      "Save virtual users to .usercase/people.json (adds to what is there). People have no names — like real visitors; each gets a number (p1, p2…) to refer to them by. Make people who would really come to this site — varied goals, devices, arrival paths, and states of mind. Do not make everyone a perfect fit for one feature. Show the list to the user before running visits.",
+    inputSchema: {
+      site: z.string().url().describe("Site origin the visits go to"),
+      site_about: z.string().describe("One or two English sentences on what the site is, as a visitor would understand it"),
+      people: z.array(PERSON).min(1).max(50),
+    },
+  },
+  wrap(async ({ site, site_about, people }) => {
+    const doc = ws.loadPeople();
+    doc.site = new URL(site).origin;
+    doc.siteAbout = site_about;
+    const at = new Date().toISOString();
+    // 착지 화면은 이 사이트 경로만. 전체 주소로 줘도 경로로 바꾸고, 다른 사이트면 버린다(그 사람은 홈으로 들어온다)
+    const landingOf = (l) => {
+      if (!l) return undefined;
+      try {
+        const u = new URL(l, doc.site);
+        return u.origin === doc.site ? u.pathname + u.search : undefined;
+      } catch {
+        return undefined;
+      }
+    };
+    const ids = peopleRules.withIds(doc.people, people.map((p) => ({ ...p, landing: landingOf(p.landing), createdAt: at, usedAt: null })));
+    for (const p of ids.incoming) p.traits = persona.coerceTraits(p.traits, peopleRules.personKey(p)).traits;
+    doc.people = [...ids.existing, ...ids.incoming];
+    ws.savePeople(doc);
+    return text(
+      [
+        `Saved ${people.length} people → ${ws.PEOPLE}`,
+        ...ids.incoming.map((p) => `- ${p.id} · ${personLine(p)}`),
+        `${doc.people.length} in total (${doc.people.filter((x) => !x.usedAt).length} not visited yet)`,
+        coverageLine(doc.people),
+      ].join("\n"),
+    );
+  }),
+);
+
+server.registerTool(
+  "list_people",
+  { description: "List the virtual users in .usercase/people.json and whether each has visited yet.", inputSchema: {} },
+  wrap(async () => {
+    const doc = ws.loadPeople();
+    if (!doc.people.length) return text("No people yet. Create them with save_people.");
+    return text(
+      [`site: ${doc.site}`, ...doc.people.map((p) => `- ${p.id ?? "?"} · ${p.usedAt ? "visited" : "not visited"} · ${personLine(p)}`), coverageLine(doc.people)].join("\n"),
+    );
+  }),
+);
+
+server.registerTool(
+  "results",
+  {
+    description: "Recent visit results (one summary per visit) and what the safety guard blocked. Call after each round of visitor sub-agents finishes — it also says whether the research run goes on to another round.",
+    inputSchema: { limit: z.number().int().min(1).max(200).optional() },
+  },
+  wrap(async ({ limit = 30 }) => {
+    const rows = ws.recentRuns(limit);
+    const { summarize } = require("./hub.js");
+    const lines = rows.map((r) => summarize(r)).join("\n\n");
+    const st = hub.status();
+    const next = runStatus();
+    return text([lines || "No visits yet.", st ? `\n---\n${st}` : "", next ? `\n---\n${next}` : ""].join("\n"));
+  }),
+);
+
+server.registerTool(
+  "login",
+  {
+    description:
+      "Open a visible browser on the user's screen so THEY can sign in to the site with one demo account. Only the resulting session (cookies) is saved, under an account name in .usercase/sessions/ — the password never passes through you or us. Call it once per demo account, one at a time. Returns immediately; tell the user to sign in and close the window, then run check_site — it checks whether the sign-in really worked. If an account is not signed in or has expired, call login again with that same account name. Members (member=true) are spread across the signed-in accounts. Never ask the user for their password.",
+    inputSchema: {
+      url: z.string().url().describe("The sign-in page, or any page of the site"),
+      account: z.string().optional().describe('Account name to save it as (a1, a2 …). Leave out for a new account; give an existing name to sign in again'),
+      window: z
+        .enum(["chrome", "playwright"])
+        .optional()
+        .describe(
+          "Which window. chrome (default): the user's normal Chrome — Google and other sign-in buttons work, but a sign-in cookie that lasts only until the browser closes is lost. playwright: keeps such cookies, but Google sign-in is blocked there. Choose from the site's auth code; leave out if unsure",
+        ),
+      lifetimeHours: z
+        .number()
+        .positive()
+        .optional()
+        .describe("How long a sign-in lasts, if the auth code says (e.g. a session maxAge or ttl). Shown as time left, and the account is not used after it"),
+    },
+  },
+  wrap(async ({ url, account, window, lifetimeHours }) => text(await hub.login(url, account, { window, lifetimeH: lifetimeHours }))),
+);
+
+server.registerTool(
+  "set_writes",
+  {
+    description:
+      "Choose whether visitors' writes reach the site: signing up, posting, commenting, saving, liking. 'block' (the default) sends nothing to the site; 'send' lets those through for real. Only the user can decide this — ask them, and only call this with their answer. 'send' suits a test or staging site, or data that may be messed up; on a live site real users will see what visitors post. Payments, deleting, wallet connections and sign-out stay blocked either way. Saved in .usercase/settings.json.",
+    inputSchema: { mode: z.enum(["block", "send"]).describe("block = nothing is sent to the site; send = writes really reach the site") },
+  },
+  wrap(async ({ mode }) => text(hub.setWrites(mode))),
+);
+
+const AGENT_SRC = path.join(__dirname, "..", "agents", "usercase-visitor.md");
+// 사용자 전체(~/.claude/agents/)에 둔다 — 사용자 저장소에 파일을 늘리지 않는다
+const AGENT_DEST = path.join(os.homedir(), ".claude", "agents", "usercase-visitor.md");
+// 0.1.6 까지는 저장소에 깔았다. 같은 이름이면 저장소 것이 이겨서 옛 지시문이 남으니 치운다.
+// 0.1.x 까지는 이름이 earningbirds-visitor 였다 — 옛 도구 이름(mcp__earningbirds__*)을 가리키니 같이 치운다
+const AGENT_OLD = [
+  path.join(process.cwd(), ".claude", "agents", "earningbirds-visitor.md"),
+  path.join(os.homedir(), ".claude", "agents", "earningbirds-visitor.md"),
+];
+
+/** 예전에 깐 것을 지운다. 우리가 만든 파일(scripts/agents.js 표시)만 */
+function removeOldAgent() {
+  let removed = false;
+  for (const p of AGENT_OLD) {
+    try {
+      if (!fs.readFileSync(p, "utf8").includes("scripts/agents.js")) continue;
+      fs.unlinkSync(p);
+      if (p.startsWith(process.cwd())) try { fs.rmdirSync(path.dirname(p)); } catch {} // 비었을 때만 지워진다
+      removed = true;
+    } catch {}
+  }
+  return removed;
+}
+
+/** 방문자 에이전트를 ~/.claude/agents/ 에 둔다. "installed" | "updated" | "same" */
+function installAgent() {
+  const moved = removeOldAgent();
+  const had = fs.existsSync(AGENT_DEST);
+  if (had && fs.readFileSync(AGENT_DEST, "utf8") === fs.readFileSync(AGENT_SRC, "utf8")) return moved ? "updated" : "same";
+  fs.mkdirSync(path.dirname(AGENT_DEST), { recursive: true });
+  fs.copyFileSync(AGENT_SRC, AGENT_DEST);
+  return had || moved ? "updated" : "installed";
+}
+
+server.registerTool(
+  "setup",
+  {
+    description:
+      "Install the usercase-visitor sub-agent definition into ~/.claude/agents/ (user-wide, nothing is added to the repository) so visitors can be started. Run once if that agent type is not available. The user may need to restart Claude Code afterwards.",
+    inputSchema: {},
+  },
+  wrap(async () => {
+    const r = installAgent();
+    return text(
+      r === "same"
+        ? `Already up to date — ${AGENT_DEST}`
+        : `${r === "updated" ? "Updated" : "Installed"} → ${AGENT_DEST}\nThis agent can only use the three Usercase tools (open_visit, act, answer_card) and cannot read files.\nRestart Claude Code so it picks up the ${r === "updated" ? "new version" : "agent"}.`,
+    );
+  }),
+);
+
+// ── 질문 만들기 (메인 에이전트, question 절차) ──
+// 대시보드 New question 은 한 단계 조건만 고른다. 여러 단계 조건은 여기서 코드를 읽고 쓴다.
+// 서버가 최근 방문에 돌려 본 것만 초안으로 받는다 — 켜는 건 사람이 Inbox 에서 한다
+
+const QStep = z.object({
+  do: z.enum(["arrive", "click", "scroll", "input", "submit", "back", "hide", "error", "idle"]),
+  page: z.string().optional().describe("Path glob of the screen this happened on. * = anything, :name = one segment"),
+  from: z.string().optional().describe("arrive/back only: path glob of the screen they came from"),
+  target: z.string().optional().describe("click/input/submit: words in the element's text or field name, or class:name, or tag:BUTTON"),
+  atLeast: z.number().int().optional().describe("Happened at least this many times"),
+  percent: z.number().optional().describe("scroll: reached at least this % of the page"),
+  seconds: z.number().optional().describe("idle: a pause of at least this many seconds between two actions"),
+  cleared: z.boolean().optional().describe("input: typed and then deleted"),
+  absent: z.boolean().optional().describe("This did NOT happen between the previous step and the moment the question appears"),
+});
+const QCondition = z.object({
+  page: z.string().describe("Path glob of the screen the visitor is on when the question appears"),
+  steps: z.array(QStep).describe("What happened, in order. Other actions may happen in between"),
+  moment: z.object({
+    type: z.enum(["on_match", "idle", "leave"]).describe("on_match = as soon as the steps are met · idle = after that, N seconds with no action · leave = when about to leave"),
+    seconds: z.number().optional(),
+  }),
+});
+
+function describeCheck(r) {
+  const L = [`Checked against ${r.visits} visits from the last ${r.days} days: matched ${r.matched}.`];
+  if (!r.visits) L.push("There are no recent visits yet, so the condition could only be checked for shape, not against real behavior.");
+  if (r.issues.length) L.push("", "Problems — fix these before saving:", ...r.issues.map((s) => `- ${s}`));
+  else L.push("No problems found.");
+  if (r.overlaps.length)
+    L.push("", "Fires at the same moment as existing questions (only one card shows per visit, so one of them would rarely appear):", ...r.overlaps.map((o) => `- "${o.question}" (${o.status})`));
+  if (r.examples.length) L.push("", "What some matched visitors did, up to the moment the question would appear:", ...r.examples.map((e) => "```\n" + e + "\n```"));
+  L.push("", "Condition as it will be saved:", "```json", JSON.stringify(r.condition, null, 2), "```");
+  return L.join("\n");
+}
+
+server.registerTool(
+  "question_context",
+  {
+    description:
+      "Screens and element words from this project's recent real visits. Call first in the question procedure, before writing a condition — page globs and click targets must match what visitors actually saw.",
+    inputSchema: {},
+  },
+  wrap(async () => {
+    const c = await report.getQuestionContext();
+    if (!c.visits) return text(`No visits in the last ${c.days} days. Conditions can still be saved, but cannot be checked against behavior until visits come in.`);
+    return text(
+      [
+        `${c.visits} visits in the last ${c.days} days.`,
+        "",
+        "Screens (visits):",
+        c.pages,
+        "",
+        "Every path seen:",
+        "  " + c.paths.join("  "),
+        "",
+        "Words on clicked elements and field names, most common first:",
+        "  " + c.words.map((w) => JSON.stringify(w)).join("  "),
+      ].join("\n"),
+    );
+  }),
+);
+
+server.registerTool(
+  "question_check",
+  {
+    description:
+      "Run a condition over this project's recent visits: how many it matches, grammar problems, overlap with existing questions, and what matched visitors did. Repeat until there are no problems.",
+    inputSchema: { condition: QCondition },
+  },
+  wrap(async ({ condition }) => text(describeCheck(await report.checkQuestion(condition)))),
+);
+
+server.registerTool(
+  "question_save",
+  {
+    description:
+      "Save the question as a DRAFT in the dashboard Inbox, after the user approved it. The server checks the condition again and refuses it if there are problems. Nobody sees it until someone turns it on.",
+    inputSchema: {
+      condition: QCondition,
+      question: z.string().describe("English, under 15 words. Asks about this moment"),
+      answerType: z.enum(["choice", "yes_no", "text"]).optional(),
+      choices: z.array(z.object({ text: z.string(), noProblem: z.boolean().optional() })).optional().describe("For choice: 2–6 choices, exactly one with noProblem: true"),
+      allowOther: z.boolean().optional().describe("Let visitors write their own answer (choice only). Default true"),
+      title: z.string().optional().describe("English, a few words, for the Inbox"),
+      why: z.string().optional().describe("English. What the team wants to learn, shown in the Inbox"),
+      triggerEn: z.string().optional().describe("English. One plain sentence: when and in what situation it appears. No paths or class names"),
+    },
+  },
+  wrap(async (args) => {
+    let r;
+    try {
+      r = await report.saveQuestion(args);
+    } catch (e) {
+      if (e.status === 422) throw new Error("The condition did not pass the check. Run question_check, fix the problems, then save again");
+      throw e;
+    }
+    const L = [`Saved as a draft — matched ${r.matched} of ${r.visits} recent visits.`, `Open it in the Inbox to turn it on: ${report.dashboardUrl(r.inboxPath)}`];
+    if (r.overlaps.length) L.push("", "Note: it fires at the same moment as:", ...r.overlaps.map((o) => `- "${o.question}" (${o.status})`));
+    return text(L.join("\n"));
+  }),
+);
+
+// ── 과제의 정상 경로 (메인 에이전트, path 절차) ──
+
+const recorder = new PathRecorder(hub);
+
+server.registerTool(
+  "path_tasks",
+  {
+    description: "List the tasks of a Usercase research (from the dashboard) and whether each already has an expected path. Call first in the path procedure.",
+    inputSchema: { research: z.string().describe("The research id, as shown in the dashboard command") },
+  },
+  wrap(async ({ research }) => text(await recorder.tasks(research))),
+);
+
+server.registerTool(
+  "path_start",
+  {
+    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"),
+      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"),
+    },
+  },
+  wrap(async ({ task, url, device, account }) => text(await recorder.start({ task, url, device, account }))),
+);
+
+server.registerTool(
+  "path_click",
+  {
+    description:
+      "Click a numbered element from the latest screen. By default it becomes a step of the path (the element is recorded; a new page reached is recorded too). record=false for clicks that are not part of the route (closing a cookie banner) — they are still repeated by path_check. press=false records the element as the final click without pressing it (a Pay or Submit button the safety guard will not press).",
+    inputSchema: {
+      index: z.number().int(),
+      record: z.boolean().optional(),
+      press: z.boolean().optional(),
+    },
+  },
+  wrap(async ({ index, record, press }) => text(await recorder.click({ index, record, press }))),
+);
+
+server.registerTool(
+  "path_type",
+  {
+    description: "Type into a numbered field (a search box, a quantity). Not a path step, but repeated by path_check.",
+    inputSchema: { index: z.number().int(), text: z.string() },
+  },
+  wrap(async ({ index, text: t }) => text(await recorder.type({ index, text: t }))),
+);
+
+server.registerTool(
+  "path_scroll",
+  { description: "Scroll the recording page to see more.", inputSchema: { direction: z.enum(["down", "up"]).optional() } },
+  wrap(async ({ direction }) => text(await recorder.scroll({ up: direction === "up" }))),
+);
+
+server.registerTool(
+  "path_pattern",
+  {
+    description:
+      "Make a page step match any page of its kind: /notice/6553c3ba → /notice/:id. Use when participants would open a different item than the one you did (the route reads from the code). Applies to every step on that page.",
+    inputSchema: { step: z.number().int().min(1), url: z.string().describe("Path pattern with :name for the changing parts") },
+  },
+  wrap(async ({ step, url }) => text(await recorder.pattern({ step, url }))),
+);
+
+server.registerTool(
+  "path_check",
+  {
+    description:
+      "Walk the recorded path again in a fresh browser: every clicked element must still be found at its recorded position with the same text, and every page must be reached. Lists the screenshots to show the user. Required before path_save.",
+    inputSchema: {},
+  },
+  wrap(async () => text(await recorder.check())),
+);
+
+server.registerTool(
+  "path_save",
+  {
+    description:
+      "Upload the checked path to the dashboard, replacing the task's expected path. Only after the user approved it. success: keep (default) leaves the task's success condition; page = done on reaching the last page of the path; click = done on the last recorded click. Ask the user before changing it.",
+    inputSchema: { success: z.enum(["keep", "page", "click"]).optional() },
+  },
+  wrap(async ({ success }) => text(await recorder.save({ success }))),
+);
+
+// ── 가상 사용자 서브에이전트용 ──
+
+server.registerTool(
+  "open_visit",
+  {
+    description:
+      "Start a visit as one virtual user from people.json. Returns a visit_id and what you see first. You ARE this person from now on. If it says the site is blocking us, stop and report that.",
+    inputSchema: { person: z.string().describe("The person's number from people.json, e.g. p3") },
+  },
+  wrap(async ({ person }) => {
+    const r = await hub.open(person);
+    return text(r.text);
+  }),
+);
+
+server.registerTool(
+  "act",
+  {
+    description:
+      "Do one thing on the screen, as the person. Numbers refer to the latest screen you were shown — only what is in view; scroll to see more. It happens after the pause a real person would take on that screen, then you get the new screen — or a survey card, or the end of the visit.",
+    inputSchema: {
+      visit_id: z.string(),
+      action: z.enum(["click", "type", "scroll", "scroll_up", "read", "back", "leave"]),
+      index: z.number().int().describe("Number of the thing to click or type into; -1 otherwise"),
+      text: z.string().optional().describe("What you type, for action=type, in the language of the site"),
+      why: z.string().describe("One short sentence in English: what you are doing and why, as this person"),
+      done: z.boolean().optional().describe("For leave: true if you got what you came for"),
+      times: z.number().int().min(1).max(5).optional().describe("For scroll, scroll_up or click: how many times in a row, quickly (scrolling down while skimming, clicking again because nothing happened). Default 1"),
+    },
+  },
+  wrap(async ({ visit_id, action, index, text: typed = "", why, done = false, times = 1 }) => text(await hub.act(visit_id, { action, index, text: typed, why, done, times }))),
+);
+
+server.registerTool(
+  "answer_card",
+  {
+    description:
+      "Respond to the survey card on screen, as the person. Decide `bothered` FIRST — most people close these without reading. Only if bothered, pick an option, write your own words, or still close.",
+    inputSchema: {
+      visit_id: z.string(),
+      bothered: z.boolean().describe("Would this person, right now, bother to answer at all?"),
+      bothered_why: z.string().describe("English, one sentence"),
+      action: z.enum(["choose", "other", "close"]),
+      choice_index: z.number().int().describe("Option number for choose; -1 otherwise"),
+      other_text: z.string().optional().describe("Your own words for other, in the language of the card, the way this person writes"),
+      why: z.string().describe("English, one sentence: why this answer"),
+    },
+  },
+  wrap(async ({ visit_id, bothered, bothered_why, action, choice_index, other_text = "", why }) =>
+    text(await hub.answer(visit_id, { bothered, botheredWhy: bothered_why, action, choiceIndex: choice_index, otherText: other_text, why })),
+  ),
+);
+
+// ── 절차 ──
+
+/** 한 판에 만드는 사람 수 — 이보다 많거나 무제한이면 판을 나눠 이어 간다 */
+const ROUND = 5;
+
+/** research 의 인원 — 숫자면 그만큼(많으면 판을 나눠), "unlimited" 면 사용자가 멈출 때까지 */
+function researchPlan(count) {
+  const c = String(count ?? "").trim().toLowerCase();
+  const unlimited = /^(unlimited|nonstop|infinite|forever|0|∞|무제한)$/.test(c);
+  const n = unlimited ? null : Math.max(1, parseInt(c, 10) || ROUND);
+  if (n !== null && n <= ROUND) return { total: n, line: String(n), rounds: `Cast all ${n} people in one round, run them (step 4), then report (step 5).` };
+  const until = unlimited ? "until the user stops you (they press Esc) — there is no limit" : `until ${n} people have visited (the last round may be smaller)`;
+  return {
+    total: n,
+    line: unlimited ? `unlimited — rounds of ${ROUND} until the user stops` : `${n} in total, in rounds of ${ROUND}`,
+    rounds: [
+      `Work in rounds of ${ROUND} people, ${until}.`,
+      `- **Round 1:** cast ${ROUND}, show the user the list, and tell them you will keep casting new people like this ${unlimited ? "until they press Esc" : `until ${n} have visited`}, and that every visit uses their Claude usage. Wait for the go-ahead, then run the round (step 4).`,
+      "- **Next rounds:** do not ask again. Call `list_people` first and cast people unlike the ones already there — different goals, arrival paths, devices and states of mind, not variations of the same person. Run the round, then tell the user one short line (round number, who went, visits so far) and go on.",
+      "- After each round, `results` tells you whether the run is finished. Until it says so, start the next round — do not write the report.",
+      "- Stop early only if the site blocks us, or visits keep failing the same way before they start.",
+      "- Keep your notes between rounds short. Do the full report (step 5) once, at the end — or when the user stops you and asks for it.",
+    ].join("\n"),
+  };
+}
+
+/**
+ * 지금 돌고 있는 research 의 인원. 긴 지시문의 "다음 판" 은 기다리는 사이 잊힌다(10/13 bluetags 에서 한 판 만에 끝냈다) —
+ * 그래서 판이 끝날 때마다 부르는 results 가 이어 갈지 끝낼지를 말한다
+ */
+let run = null;
+
+function runStatus() {
+  if (!run) return "";
+  const done = ws.recentRuns(5000).filter((r) => r.at && Date.parse(r.at) >= run.since).length;
+  if (run.total !== null && done >= run.total) {
+    run = null;
+    return `■ The run is complete — ${done} people visited. Now write the report (step 5).`;
+  }
+  const left = run.total === null ? "unlimited, until the user presses Esc" : `${run.total - done} of ${run.total} still to go`;
+  const next = run.total === null ? ROUND : Math.min(ROUND, run.total - done);
+  return [
+    `▶ The run is not finished — ${done} visited so far (${left}).`,
+    `Do not write the report and do not look into the code. Tell the user one short line about this round, then: call list_people, cast ${next} new people unlike the ones already there with save_people, start one usercase-visitor for each, and call results again when they finish.`,
+  ].join("\n");
+}
+
+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') },
+  },
+  ({ url, count }) => {
+    const plan = researchPlan(count);
+    run = { total: plan.total, since: Date.now() };
+    // 사람 만드는 규칙은 우리 AI 로 만들 때와 같은 원본(people.md)에서 가져온다 — 두 벌로 두지 않는다.
+    // 자유 탐방이라 원본이 말하는 "path" 는 "자기 목적으로 왔다" 뿐이다
+    const rules =
+      "(Here the \"path\" is simply: came to the site with something of their own to find out.)\n\n" +
+      fs
+        .readFileSync(path.join(__dirname, "..", "src", "prompts", "people.md"), "utf8")
+        .replace(/\r\n/g, "\n")
+        .replace(/^# Role:.*\n+/, "")
+        .replace(/^#/gm, "###");
+    const body = fs
+      .readFileSync(path.join(__dirname, "..", "agents", "research.md"), "utf8")
+      .replace("{{url}}", url || "(ask the user)")
+      .replace("{{count_line}}", plan.line)
+      .replace("{{rounds}}", plan.rounds)
+      .replace("{{people_rules}}", rules);
+    return { messages: [{ role: "user", content: { type: "text", text: body } }] };
+  },
+);
+
+server.registerPrompt(
+  "install",
+  { description: "Install the Usercase script on this site from its repository", argsSchema: { url: z.string().optional() } },
+  ({ url }) => {
+    const body = fs
+      .readFileSync(path.join(__dirname, "..", "agents", "install.md"), "utf8")
+      .replace(/\r\n/g, "\n")
+      .replace("{{url}}", url || "(the site in this repository)");
+    return { messages: [{ role: "user", content: { type: "text", text: body } }] };
+  },
+);
+
+server.registerPrompt(
+  "path",
+  { description: "Record the expected path of a Usercase research's tasks", argsSchema: { research: z.string().optional() } },
+  ({ research }) => {
+    const body = fs
+      .readFileSync(path.join(__dirname, "..", "agents", "path.md"), "utf8")
+      .replace(/\r\n/g, "\n")
+      .replace("{{research}}", research || "(ask the user — the dashboard shows it)");
+    return { messages: [{ role: "user", content: { type: "text", text: body } }] };
+  },
+);
+
+server.registerPrompt(
+  "question",
+  { description: "Make a Usercase question that appears at a precise moment on your site", argsSchema: { ask: z.string().optional().describe("Who to ask and what to learn, in your own words") } },
+  ({ ask }) => {
+    const body = fs
+      .readFileSync(path.join(__dirname, "..", "agents", "question.md"), "utf8")
+      .replace(/\r\n/g, "\n")
+      .replace("{{ask}}", ask || "(ask the user what moment they want to ask about, and what they want to learn)");
+    return { messages: [{ role: "user", content: { type: "text", text: body } }] };
+  },
+);
+
+async function main() {
+  // 예전에 깐 방문자 에이전트가 있으면 이 버전 것으로 바꿔 둔다 — setup 은 처음 한 번만 불려서 옛 지시문이 남는다.
+  // 리서치를 한 번도 안 쓴 사람에게는 만들지 않는다
+  try {
+    if ((fs.existsSync(AGENT_DEST) || fs.existsSync(AGENT_OLD)) && installAgent() === "updated") process.stderr.write(`Updated the visitor agent → ${AGENT_DEST}\n`);
+  } catch {}
+  await server.connect(new StdioServerTransport());
+  process.stderr.write(`Usercase MCP ready — working folder ${ws.DIR}${hub.inject ? ` · local SDK injected (${hub.inject.project})` : ""}\n`);
+}
+const bye = async () => {
+  await hub.close().catch(() => {});
+  process.exit(0);
+};
+process.on("SIGINT", bye);
+process.on("SIGTERM", bye);
+process.stdin.on("close", bye);
+main().catch((e) => {
+  process.stderr.write(`Failed to start: ${e.stack || e}\n`);
+  process.exit(1);
+});