@usercase/mcp 0.2.1-next.0 → 0.2.1-next.1

package/README.md

@@ -79,15 +79,25 @@ 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
+## 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 anything more precise, ask from your repository:
+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 people who search but don't open any result for 10 seconds
+/mcp__usercase__question
 ```
 
-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.
+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
 

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

@@ -1,56 +1,26 @@
 # 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.
+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 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
+## 3. Write and check the condition
 
-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.
+{{condition_rules}}
 
-## 5. Write the question
+## 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.
-- `triggerEn`: one plain sentence a product manager understands, saying when it appears. No paths or class names.
 
-## 6. Show the user, then save
+## 5. Show the user, then save
 
 Show the user, briefly:
 - when it appears, in plain words, and how many recent visits matched,

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

@@ -187,6 +187,9 @@ const savePath = (taskId, body) => keyed("PUT", `/agent/tasks/${encodeURICompone
 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;
 
@@ -203,5 +206,7 @@ module.exports = {
   getQuestionContext,
   checkQuestion,
   saveQuestion,
+  getStepsBrief,
+  sendSteps,
   dashboardUrl,
 };

package/mcp/server.js

@@ -406,6 +406,53 @@ server.registerTool(
   }),
 );
 
+// 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);
@@ -645,16 +692,27 @@ 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(
-  "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 } }] };
+  "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() {

package/package.json

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