@usercase/mcp 0.2.1-next.1 → 0.2.1

package/README.md

@@ -83,13 +83,13 @@ Claude reads your code to work out the route each task is meant to take, tells y
 
 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:
+**You wrote the question, and want it to appear at a precise moment.** In New question, choose **Several steps** 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.
+Claude reads your question, asks you when it should appear, 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:
 

package/agents/condition.md

@@ -23,7 +23,7 @@ Rules that make a card actually appear and mean something:
 
 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`.
+- **Does not match recent visits** (matched 0, a path or word not seen): usually a wrong path or word — compare with `question_context` and the code, and fix it. But the screen or button may be new or not live yet. Then tell the user it has not been seen in recent visits, and send it with `acceptWarnings: true` only if they say so.
 - **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.

package/agents/steps.md

@@ -6,11 +6,11 @@ The user is writing a question in the Usercase dashboard (New question → Sever
 
 You may read the code: the routes, the components, the labels on buttons.
 
-## 1. Read what they wrote
+## 1. Read their question, then ask about the moment
 
-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.
+Call `steps_brief` with the window id. It gives what is in their window right now: the page under Where and their question — either may still be empty, because people often choose Several steps before writing the question. That is normal; do not point it out. 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.
+Then ask the user, in one short question, when the card should appear — what the visitor has done just before. If there is a question, suggest one moment that fits it so they can just say yes. If there is none, just ask about the moment; they will write the question in their window. If their answer is still vague, ask once more. Call `steps_brief` again before writing the condition — they may have filled in the window meanwhile.
 
 ## 2. Read the code and the visits
 
@@ -27,4 +27,6 @@ Make sure the moment fits their question: the card should appear when the visito
 
 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.
 
+If they want it changed, fix it, check it again and send it to the same window id — the new steps replace the old ones in their window.
+
 Do not change any code.

package/mcp/server.js

@@ -330,8 +330,16 @@ const QCondition = z.object({
 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}`));
+  if (r.issues.length) L.push("", "Problems — fix these; it cannot be saved with them:", ...r.issues.map((s) => `- ${s}`));
   else L.push("No problems found.");
+  const warnings = r.warnings || [];
+  if (warnings.length)
+    L.push(
+      "",
+      "Does not match recent visits — fine if the screen or button is new or not live yet, otherwise likely a wrong path or word:",
+      ...warnings.map((s) => `- ${s}`),
+      "To save anyway, tell the user, and only if they say so pass acceptWarnings: true.",
+    );
   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```"));
@@ -390,6 +398,7 @@ server.registerTool(
       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"),
+      acceptWarnings: z.boolean().optional().describe("true only after the user said to save even though it does not match recent visits"),
     },
   },
   wrap(async (args) => {
@@ -398,6 +407,7 @@ server.registerTool(
       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");
+      if (e.status === 409) throw new Error("It does not match recent visits. Tell the user; if they want it anyway (a new screen or button), save again with acceptWarnings: true");
       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)}`];
@@ -410,14 +420,13 @@ server.registerTool(
 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.",
+    description: "What the user wrote in their New question window: 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." : "",
@@ -437,14 +446,16 @@ server.registerTool(
       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"),
+      acceptWarnings: z.boolean().optional().describe("true only after the user said to send it even though it does not match recent visits"),
     },
   },
-  wrap(async ({ session, condition, triggerEn }) => {
+  wrap(async ({ session, condition, triggerEn, acceptWarnings }) => {
     let r;
     try {
-      r = await report.sendSteps(session, { condition, triggerEn });
+      r = await report.sendSteps(session, { condition, triggerEn, acceptWarnings });
     } 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");
+      if (e.status === 409) throw new Error("It does not match recent visits. Tell the user; if they want it anyway (a new screen or button), send again with acceptWarnings: true");
       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.`];

package/package.json

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