@usercase/mcp 0.2.0 → 0.2.1-next.0

package/README.md

@@ -79,6 +79,16 @@ A research's task results separate people who **went straight** from those who *
 
 Claude reads your code to work out the route each task is meant to take, tells you the route, and walks it in a browser. It then walks it again in a fresh browser to make sure every step is found the same way, shows you the screenshots, and saves the path only after you approve it. Picking one item from a list (a product, a post) is not tied to the item Claude happened to open — any item of that kind counts. A local dev server is fine; only page paths are saved.
 
+## Make a question for a precise moment
+
+The dashboard's **New question** picks one simple moment (on arrival, after a pause, when leaving, after a click). For anything more precise, ask from your repository:
+
+```
+/mcp__usercase__question people who search but don't open any result for 10 seconds
+```
+
+Claude reads your code for the real routes and button labels, writes the moment as a series of steps, and runs it over your recent real visits to show how many it matches and what those visitors did. It shows you the question and its answers, and saves it only after you approve — as a draft in your Inbox. Nobody sees it until you turn it on there. Needs the API key.
+
 ## What the visitors will and won't do
 
 - They identify themselves on every request (see below), and their answers are counted separately from real visitors. This cannot be turned off.

package/agents/question.md

@@ -0,0 +1,62 @@
+# Make a Usercase question
+
+What the user wants: {{ask}}
+
+Usercase shows a small question card to real visitors of this site at a chosen moment, and the answers show the team why people get stuck. You write **when** the card appears (a condition), the question and its answers. The dashboard can only make one-step conditions; you can chain steps because **you may read the code** — the routes, the components, the labels on buttons.
+
+## 1. Understand the moment
+
+From the user's words, decide what situation they mean: which screen, what the visitor did before, and when it is fair to interrupt. If the request is vague ("ask people on checkout"), ask one short question to pin the moment down. Otherwise go on.
+
+## 2. Read the code and the visits
+
+- Find the screens and controls involved in the code: the route patterns, the text on the buttons, field names, form classes.
+- Call `question_context`. It lists the paths and element words real visitors produced recently. **Page globs and targets must match these.** The code says what exists; the visits say what is actually used and how it is labelled at runtime. If they disagree, trust the visits.
+
+## 3. Write the condition
+
+A condition has a `page` (the screen the visitor is on when the card appears), `steps` in order, and a `moment`.
+
+Step kinds (`do`): `arrive` · `back` · `click` · `input` · `submit` · `scroll` · `idle` · `hide` (tab hidden) · `error` (a JavaScript error).
+Options on a step: `page`, `from` (arrive/back), `target` (click/input/submit), `atLeast`, `percent` (scroll), `seconds` (idle: a pause between two actions), `cleared` (input: typed then deleted), `absent` (this did not happen between the previous step and the moment).
+Moment: `on_match` (as soon as the steps are met) · `idle` with `seconds` (then that long with no action) · `leave` (about to leave; on phones, a long pause instead).
+
+Globs: `*` matches anything including `/`; `:name` matches one path segment (`/project/:slug`). Use the route parameter names from the code. Never put `?` or `#` in a glob.
+
+Targets match the element's own text, field name or class — case does not matter, and the words only need to be contained. Prefer the words the visitor saw. Use `class:name` for buttons without text and `tag:BUTTON` only when the text differs every time (a list of names).
+
+Steps happen in order, with anything allowed in between. All steps must happen; there is no "or" — two situations are two questions.
+
+**It cannot see:** what is on the screen (an error message, an empty list, a price), the values typed (only length and whether it was cleared), time limits ("within 10 seconds"), who the visitor is (device, new or returning, campaign), or anything across visits. A visit is one tab; 30 minutes of nothing starts a new one. If the user asks for one of these, say so and offer the nearest thing it can do — usually a behavior that goes with it (a submit followed by no arrival at the next page, instead of "an error was shown").
+
+Rules that make a card actually appear and mean something:
+- The card must be shown on the screen where the trouble is. A click that opens another page ends the situation — use the `arrive` on the next page instead.
+- Never ask while they are typing: the last step of an `on_match` condition must not be `input`. Use `idle` or the next step.
+- Never ask the moment someone lands on a sign-in, sign-up or payment screen; use `idle` or `leave` there.
+- The page must name a real screen, not only wildcards.
+- Narrow enough to be one situation: a condition that matches a large share of all visits is too broad.
+
+## 4. Check it
+
+Call `question_check` with the condition. Read the result:
+- **Problems**: fix them and check again. Saving is refused while there are any.
+- **Matched 0** with visits present: the paths or words are wrong, or the situation has not happened recently. Compare with `question_context`.
+- **Examples**: read what the matched visitors did. If it is not the situation the user meant, the condition is wrong even if it passes.
+- **Overlaps**: an existing question fires at the same moment; only one card shows per visit. Tell the user.
+
+## 5. Write the question
+
+- English, under 15 words, about this moment ("What were you looking for?"), not opinions about the site.
+- Prefer `choice` with 3–5 short answers in the visitor's own words, one of them meaning nothing was wrong, marked `noProblem: true` — when most people pick it, the question turns itself off. Use `text` only when you genuinely cannot guess the likely answers. Avoid `yes_no`: it says that something is wrong, not what.
+- `triggerEn`: one plain sentence a product manager understands, saying when it appears. No paths or class names.
+
+## 6. Show the user, then save
+
+Show the user, briefly:
+- when it appears, in plain words, and how many recent visits matched,
+- the question and its answers,
+- any overlap or anything you could not express.
+
+On their approval, call `question_save`. Give them the Inbox link it returns and tell them it stays a draft until someone turns it on there. If they want more questions, go back to step 1.
+
+Do not change any code.

package/mcp/report.js

@@ -183,4 +183,25 @@ const getResearchTasks = (researchId) => keyed("GET", `/agent/researches/${encod
 /** 과제의 정상 경로를 통째로 바꾼다. 화면을 올리느라 오래 걸릴 수 있다 */
 const savePath = (taskId, body) => keyed("PUT", `/agent/tasks/${encodeURIComponent(taskId)}/path`, body, 90000);
 
-module.exports = { KEY_ENV, URL_ENV, RUN_REF, describeKey, getInstall, sendVisit, sendDiagnostics, getResearchTasks, savePath };
+/** 질문 만들기(question) — 최근 방문을 읽어야 해서 조금 걸린다 */
+const getQuestionContext = () => keyed("GET", "/agent/questions/context", null, 60000);
+const checkQuestion = (condition) => keyed("POST", "/agent/questions/check", { condition }, 60000);
+const saveQuestion = (body) => keyed("POST", "/agent/questions", body, 60000);
+/** 대시보드 주소. API 주소에서 /koa 를 뗀다 */
+const dashboardUrl = (p) => apiBase().replace(/\/koa$/, "") + p;
+
+module.exports = {
+  KEY_ENV,
+  URL_ENV,
+  RUN_REF,
+  describeKey,
+  getInstall,
+  sendVisit,
+  sendDiagnostics,
+  getResearchTasks,
+  savePath,
+  getQuestionContext,
+  checkQuestion,
+  saveQuestion,
+  dashboardUrl,
+};

package/mcp/server.js

@@ -303,6 +303,109 @@ server.registerTool(
   }),
 );
 
+// ── 질문 만들기 (메인 에이전트, 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);
@@ -542,6 +645,18 @@ server.registerPrompt(
   },
 );
 
+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 은 처음 한 번만 불려서 옛 지시문이 남는다.
   // 리서치를 한 번도 안 쓴 사람에게는 만들지 않는다

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usercase/mcp",
-  "version": "0.2.0",
+  "version": "0.2.1-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",
@@ -26,7 +26,11 @@
   },
   "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"
+    "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",