@usercase/mcp 0.2.0 → 0.2.1-next.1

package/README.md

@@ -79,6 +79,26 @@ 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.
 
+## Questions for a precise moment
+
+The dashboard's **New question** picks one simple moment (on arrival, after a pause, when leaving, after a click). For a moment made of several steps — "typed a search, opened no result, then did nothing for 10 seconds" — Claude writes it from your code and checks it against your recent real visits. Both need the API key.
+
+**You wrote the question, and want it to appear at a precise moment.** In New question, choose **Several steps**, describe the moment, and copy the command it gives you:
+
+```
+/mcp__usercase__steps <window id>
+```
+
+Claude reads what you wrote, writes the steps, and sends them back to that window. You see them there, and save the question as usual.
+
+**You're not sure what to ask.** Run this and tell Claude who you want to hear from:
+
+```
+/mcp__usercase__question
+```
+
+Claude suggests the moment, 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.
+
 ## 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/condition.md

@@ -0,0 +1,31 @@
+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.
+
+### Checking it
+
+Call `question_check` with the condition. Read the result:
+- **Problems**: fix them and check again. The server refuses the condition 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.
+- `idle` and `leave` moments are not counted by the check — it counts visits where the steps happened. Fewer people will actually see the card.
+
+`triggerEn`: one plain sentence a product manager understands, saying when the card appears. No paths or class names.

package/agents/question.md

@@ -0,0 +1,32 @@
+# Make a Usercase question
+
+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
+
+Ask the user, in one short question, who they want to hear from and what they want to learn — unless they already said so. Then decide what situation they mean: which screen, what the visitor did before, and when it is fair to interrupt. If it is still vague ("ask people on checkout"), ask one more short question to pin the moment down.
+
+## 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 and check the condition
+
+{{condition_rules}}
+
+## 4. 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.
+
+## 5. 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/agents/steps.md

@@ -0,0 +1,30 @@
+# Write the steps for a Usercase question
+
+Window: {{session}}
+
+The user is writing a question in the Usercase dashboard (New question → Several steps) and wants it to appear at a moment made of several steps. The question itself is theirs. **You only write when it appears** — a condition — and send it back to that window, where they see it and save the question.
+
+You may read the code: the routes, the components, the labels on buttons.
+
+## 1. Read what they wrote
+
+Call `steps_brief` with the window id. It gives the moment they described, the page they typed under Where (if any) and their question. If the window id is missing or unknown, ask the user to choose Several steps again and copy the new command.
+
+If the description is vague, 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 and check the condition
+
+{{condition_rules}}
+
+Make sure the moment fits their question: the card should appear when the visitor can answer it.
+
+## 4. Send it back
+
+Tell the user in plain words when it will appear and how many recent visits matched, and anything you could not express. Then call `steps_send` with the window id, the condition and `triggerEn`. The steps appear in their dashboard window right away; they save the question there. Do not save a question yourself.
+
+Do not change any code.

package/mcp/report.js

@@ -183,4 +183,30 @@ 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);
+/** New question 창(Several steps) — 창에 쓴 것을 읽고, 조건만 돌려보낸다 */
+const getStepsBrief = (session) => keyed("GET", `/agent/questions/steps/${encodeURIComponent(session)}`);
+const sendSteps = (session, body) => keyed("PUT", `/agent/questions/steps/${encodeURIComponent(session)}`, 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,
+  getStepsBrief,
+  sendSteps,
+  dashboardUrl,
+};

package/mcp/server.js

@@ -303,6 +303,156 @@ 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"));
+  }),
+);
+
+// New question 창(Several steps)이 기다리는 조건 — 질문 글은 사람 것이고 여기서는 조건만 보낸다
+server.registerTool(
+  "steps_brief",
+  {
+    description: "What the user wrote in their New question window: the moment they described, the page under Where, and their question. Call first in the steps procedure.",
+    inputSchema: { session: z.string().describe("The window id from the dashboard command") },
+  },
+  wrap(async ({ session }) => {
+    const b = await report.getStepsBrief(session);
+    return text(
+      [
+        `Moment they described: ${b.moment || "(nothing — ask the user)"}`,
+        `Where: ${b.where || "(empty)"}`,
+        `Their question: ${b.question || "(not written yet)"}`,
+        b.sent ? "Steps were already sent to this window once; sending again replaces them." : "",
+      ]
+        .filter(Boolean)
+        .join("\n"),
+    );
+  }),
+);
+
+server.registerTool(
+  "steps_send",
+  {
+    description:
+      "Send the condition back to the user's New question window, after question_check shows no problems. The server checks it again and refuses it if there are problems. The user saves the question there.",
+    inputSchema: {
+      session: z.string().describe("The window id from the dashboard command"),
+      condition: QCondition,
+      triggerEn: z.string().describe("English. One plain sentence: when and in what situation it appears. No paths or class names"),
+    },
+  },
+  wrap(async ({ session, condition, triggerEn }) => {
+    let r;
+    try {
+      r = await report.sendSteps(session, { condition, triggerEn });
+    } catch (e) {
+      if (e.status === 422) throw new Error("The condition did not pass the check. Run question_check, fix the problems, then send again");
+      throw e;
+    }
+    const L = [`Sent — the steps are now in the user's New question window (matched ${r.matched} of ${r.visits} recent visits). They save the question there.`];
+    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 +692,29 @@ server.registerPrompt(
   },
 );
 
+/** 조건 쓰는 규칙은 question·steps 가 같이 쓴다 — 한 벌만 둔다 */
+const agentDoc = (name, vars = {}) => {
+  let body = fs.readFileSync(path.join(__dirname, "..", "agents", name), "utf8").replace(/\r\n/g, "\n");
+  const rules = fs.readFileSync(path.join(__dirname, "..", "agents", "condition.md"), "utf8").replace(/\r\n/g, "\n").trim();
+  body = body.replace("{{condition_rules}}", rules);
+  for (const [k, v] of Object.entries(vars)) body = body.replace(`{{${k}}}`, v);
+  return { messages: [{ role: "user", content: { type: "text", text: body } }] };
+};
+
+// 인자를 두지 않는다 — Claude Code 는 명령어 인자를 공백으로 나눠 문장을 못 싣는다. 무엇을 물을지는 대화로 묻는다
+server.registerPrompt("question", { description: "Make a Usercase question for a precise moment on your site — Claude suggests the moment, question and answers" }, () =>
+  agentDoc("question.md"),
+);
+
+server.registerPrompt(
+  "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") },
+  },
+  ({ session }) => agentDoc("steps.md", { session: session || "(missing — ask the user to copy the command from the dashboard)" }),
+);
+
 async function main() {
   // 예전에 깐 방문자 에이전트가 있으면 이 버전 것으로 바꿔 둔다 — setup 은 처음 한 번만 불려서 옛 지시문이 남는다.
   // 리서치를 한 번도 안 쓴 사람에게는 만들지 않는다

package/package.json

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