@usercase/mcp 0.2.3 → 0.2.4-next.1

package/README.md

@@ -1,153 +1,153 @@
-# Usercase MCP
-
-Research your website with virtual users, before you have real ones.
-
-Open your repository in Claude Code and ask it to research your site. Claude reads your code to understand what the site is and who it is for, then casts a handful of virtual users. Each one visits the site in a real browser on your machine, looks around with their own goal, and answers the Usercase survey cards they happen to meet. Their visits and answers show up in your Usercase dashboard.
-
-- **Free.** The AI runs on your own Claude subscription.
-- **Runs on your machine.** Your browser, your network, your staging or demo accounts. Passwords never pass through Usercase.
-- **Visitors only see the screen.** Claude may read your code to plan the research, but the visitors cannot. A visitor who knows the code finds buttons real people can't, and the research loses its value.
-
-## Requirements
-
-- [Claude Code](https://docs.claude.com/en/docs/claude-code)
-- Node.js 18 or later
-- Google Chrome (or run `npx playwright install chromium` once)
-- A Usercase project with the SDK installed on your site, so the survey cards appear
-
-## Connect
-
-1. In the Usercase dashboard, open **Settings → Integrations → API keys** and create a key. It starts with `eb_sk_` and is shown once.
-2. In your repository folder, run:
-
-   ```sh
-   claude mcp add usercase -e USERCASE_API_KEY=eb_sk_... -- npx -y @usercase/mcp@latest
-   ```
-
-   This is saved to your Claude Code settings (`~/.claude.json`), not to your repository. `@latest` picks up new versions each time Claude Code starts.
-
-## Install the script
-
-The survey cards come from the Usercase script on your site. If it isn't there yet, let Claude Code add it:
-
-```
-/mcp__usercase__install
-```
-
-Claude gets your project's script (from the API key), puts it once in your root layout or document head, shows you the diff, and opens your local site to check that it loads. It doesn't commit or deploy. Real visitors are recorded once you deploy the change.
-
-## Run a research
-
-In Claude Code:
-
-```
-/mcp__usercase__research https://staging.example.com 5
-```
-
-The first time, Claude installs the visitor agent into `~/.claude/agents/` (not your repository) and may ask you to restart Claude Code. Then it:
-
-1. checks the site once: whether the SDK is running, whether a firewall blocks it, what the first screen shows
-2. reads your repository to understand the site
-3. casts the people and saves them to `.usercase/people.json`, where you can edit them
-4. sends one visitor per person, up to 5 at a time
-5. summarizes what happened
-
-### Keep it going
-
-The number is how many people visit in total (default 5). Above 5, Claude works in rounds of 5: you approve the first list, and after that it casts new people unlike the earlier ones, round after round, until the total is reached.
-
-```
-/mcp__usercase__research https://staging.example.com 30
-/mcp__usercase__research https://staging.example.com unlimited
-```
-
-With `unlimited` it keeps going until you press Esc. Every visit uses your Claude usage.
-
-When a visit ends, it is sent to your dashboard (**Visits**). If the upload fails, it is kept in `.usercase/outbox.jsonl` and sent with the next one.
-
-### Sites behind a sign-in
-
-Ask Claude to sign in first. It opens Chrome (or Edge) with a fresh, empty profile and **you** sign in with a demo account, once per account. Google and other sign-in buttons work there. Your usual browser profile is never touched, and the temporary profile is deleted afterwards. Several accounts keep the signed-in visitors from all sharing one history. Only the sessions are saved (`.usercase/sessions/`), never the password. Claude checks that each sign-in worked, and asks you to sign in again only when one has expired.
-
-## Record a task's expected path
-
-A research's task results separate people who **went straight** from those who **took a detour** — once the task has an expected path. The task screen in the dashboard shows a command for it:
-
-```
-/mcp__usercase__path <research id>
-```
-
-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** and copy the command it gives you:
-
-```
-/mcp__usercase__steps <window id>
-```
-
-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:
-
-```
-/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.
-- By default they don't write to your site: only `GET`, `HEAD` and `OPTIONS` requests are sent. They may still press Post, Save or Like like a person would, but nothing reaches your site, and the visitor is told it was not sent. Before the first round Claude asks whether you want those sent for real (for a test or staging site). Your answer is kept in `.usercase/settings.json`. With writes sent, signed-in visitors use the demo account as their own — they may change its profile name or settings, follow, save and post — so use demo accounts only.
-- They stay on your site and block analytics tools such as Google Analytics and Hotjar.
-- Either way they never pay, delete, connect a wallet, sign out or change a password, and never type into personal fields such as email or phone.
-- They stop when blocked. They do not solve CAPTCHAs or get around bot protection.
-- When the tool cannot do something on your site or misreads the screen, a diagnostic is sent to Usercase so the tool gets better: what failed, the page path, the HTML around the element and a screenshot of that moment. Only the Usercase team sees it, and it is kept for 30 days. Turn it off with `USERCASE_DIAGNOSTICS=off`.
-
-## Running on a production site
-
-Staging is best: bot protection is usually off and analytics are separate. If you run on production, set three things up first, or the visitors may be blocked as an attack or counted as real traffic.
-
-Every visitor request carries:
-
-| What | Value | Use it to |
-|---|---|---|
-| Header `X-Usercase-Agent` | the kind of visitor, e.g. `qa-explore` | separate them in logs and server-side analytics |
-| Header `X-Usercase-Key` | your own secret, sent only to your site | let them through your firewall or CDN |
-| User-Agent suffix | `UsercaseQA/1.0 (<kind>)` | exclude them in browser analytics and in logs that drop headers |
-
-1. **Let them through your firewall.** Make a random secret (16+ characters, e.g. `node -e "console.log(require('crypto').randomBytes(24).toString('base64url'))"`), pass it as `USERCASE_AGENT_KEY`, and allow requests whose `X-Usercase-Key` header matches it. Don't allow on `X-Usercase-Agent` alone; anyone can send that.
-2. **Exclude them from analytics.** Filter out sessions whose user agent contains `UsercaseQA`.
-3. **Separate them in logs** by the header or the user-agent suffix.
-
-## Settings
-
-Pass with `claude mcp add ... -e NAME=value`.
-
-| Name | What it does |
-|---|---|
-| `USERCASE_API_KEY` | Your project API key. Without it, visits stay on your machine only. |
-| `USERCASE_AGENT_KEY` | Your firewall secret (see above). 16+ characters. |
-| `USERCASE_ALLOW_WRITE_PATHS` | Comma-separated path patterns where non-GET requests are allowed, for sites that load pages with `POST` after sign-in. Everything else stays blocked. |
-| `USERCASE_DIAGNOSTICS` | `off` stops sending diagnostics. On by default: when the tool cannot do something or misreads the screen (a button cut off or covered, a click that landed elsewhere, a change it did not notice), Usercase receives the kind of failure, the element's shape, the page path, the HTML around the element and a screenshot of that moment, to improve the tool. Only the Usercase team sees them; they are kept for 30 days. |
-| `USERCASE_HEADED` | `1` shows the visitors' browser on screen. |
-| `USERCASE_DIR` | Working folder. Default: `.usercase` in your repository. |
-
-## Files it creates
-
-`.usercase/` in your repository:
-
-- `people.json`: the virtual users. Edit them freely; commit it if you want to reuse them.
-- `runs/`: visit records.
-- `sessions/`: one sign-in session per demo account.
-- `paths/`: screenshots of the expected paths Claude recorded, one folder per task.
-
-`runs/` and `sessions/` are git-ignored by a `.gitignore` inside the folder.
-
-## Help
-
-[usercase.io](https://usercase.io)
+# Usercase MCP
+
+Research your website with virtual users, before you have real ones.
+
+Open your repository in Claude Code and ask it to research your site. Claude reads your code to understand what the site is and who it is for, then casts a handful of virtual users. Each one visits the site in a real browser on your machine, looks around with their own goal, and answers the Usercase survey cards they happen to meet. Their visits and answers show up in your Usercase dashboard.
+
+- **Free.** The AI runs on your own Claude subscription.
+- **Runs on your machine.** Your browser, your network, your staging or demo accounts. Passwords never pass through Usercase.
+- **Visitors only see the screen.** Claude may read your code to plan the research, but the visitors cannot. A visitor who knows the code finds buttons real people can't, and the research loses its value.
+
+## Requirements
+
+- [Claude Code](https://docs.claude.com/en/docs/claude-code)
+- Node.js 18 or later
+- Google Chrome (or run `npx playwright install chromium` once)
+- A Usercase project with the SDK installed on your site, so the survey cards appear
+
+## Connect
+
+1. In the Usercase dashboard, open **Settings → Integrations → API keys** and create a key. It starts with `eb_sk_` and is shown once.
+2. In your repository folder, run:
+
+   ```sh
+   claude mcp add usercase -e USERCASE_API_KEY=eb_sk_... -- npx -y @usercase/mcp@latest
+   ```
+
+   This is saved to your Claude Code settings (`~/.claude.json`), not to your repository. `@latest` picks up new versions each time Claude Code starts.
+
+## Install the script
+
+The survey cards come from the Usercase script on your site. If it isn't there yet, let Claude Code add it:
+
+```
+/mcp__usercase__install
+```
+
+Claude gets your project's script (from the API key), puts it once in your root layout or document head, shows you the diff, and opens your local site to check that it loads. It doesn't commit or deploy. Real visitors are recorded once you deploy the change.
+
+## Run a research
+
+In Claude Code:
+
+```
+/mcp__usercase__research https://staging.example.com 5
+```
+
+The first time, Claude installs the visitor agent into `~/.claude/agents/` (not your repository) and may ask you to restart Claude Code. Then it:
+
+1. checks the site once: whether the SDK is running, whether a firewall blocks it, what the first screen shows
+2. reads your repository to understand the site
+3. casts the people and saves them to `.usercase/people.json`, where you can edit them
+4. sends one visitor per person, up to 5 at a time
+5. summarizes what happened
+
+### Keep it going
+
+The number is how many people visit in total (default 5). Above 5, Claude works in rounds of 5: you approve the first list, and after that it casts new people unlike the earlier ones, round after round, until the total is reached.
+
+```
+/mcp__usercase__research https://staging.example.com 30
+/mcp__usercase__research https://staging.example.com unlimited
+```
+
+With `unlimited` it keeps going until you press Esc. Every visit uses your Claude usage.
+
+When a visit ends, it is sent to your dashboard (**Visits**). If the upload fails, it is kept in `.usercase/outbox.jsonl` and sent with the next one.
+
+### Sites behind a sign-in
+
+Ask Claude to sign in first. It opens Chrome (or Edge) with a fresh, empty profile and **you** sign in with a demo account, once per account. Google and other sign-in buttons work there. Your usual browser profile is never touched, and the temporary profile is deleted afterwards. Several accounts keep the signed-in visitors from all sharing one history. Only the sessions are saved (`.usercase/sessions/`), never the password. Claude checks that each sign-in worked, and asks you to sign in again only when one has expired.
+
+## Record a task's expected path
+
+A research's task results separate people who **went straight** from those who **took a detour** — once the task has an expected path. The task screen in the dashboard shows a command for it:
+
+```
+/mcp__usercase__path <research id>
+```
+
+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** and copy the command it gives you:
+
+```
+/mcp__usercase__steps <window id>
+```
+
+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:
+
+```
+/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.
+- By default they don't write to your site: only `GET`, `HEAD` and `OPTIONS` requests are sent. They may still press Post, Save or Like like a person would, but nothing reaches your site, and the visitor is told it was not sent. Before the first round Claude asks whether you want those sent for real (for a test or staging site). Your answer is kept in `.usercase/settings.json`. With writes sent, signed-in visitors use the demo account as their own — they may change its profile name or settings, follow, save and post — so use demo accounts only.
+- They stay on your site and block analytics tools such as Google Analytics and Hotjar.
+- Either way they never pay, delete, connect a wallet, sign out or change a password, and never type into personal fields such as email or phone.
+- They stop when blocked. They do not solve CAPTCHAs or get around bot protection.
+- When the tool cannot do something on your site or misreads the screen, a diagnostic is sent to Usercase so the tool gets better: what failed, the page path, the HTML around the element and a screenshot of that moment. Only the Usercase team sees it, and it is kept for 30 days. Turn it off with `USERCASE_DIAGNOSTICS=off`.
+
+## Running on a production site
+
+Staging is best: bot protection is usually off and analytics are separate. If you run on production, set three things up first, or the visitors may be blocked as an attack or counted as real traffic.
+
+Every visitor request carries:
+
+| What | Value | Use it to |
+|---|---|---|
+| Header `X-Usercase-Agent` | the kind of visitor, e.g. `qa-explore` | separate them in logs and server-side analytics |
+| Header `X-Usercase-Key` | your own secret, sent only to your site | let them through your firewall or CDN |
+| User-Agent suffix | `UsercaseQA/1.0 (<kind>)` | exclude them in browser analytics and in logs that drop headers |
+
+1. **Let them through your firewall.** Make a random secret (16+ characters, e.g. `node -e "console.log(require('crypto').randomBytes(24).toString('base64url'))"`), pass it as `USERCASE_AGENT_KEY`, and allow requests whose `X-Usercase-Key` header matches it. Don't allow on `X-Usercase-Agent` alone; anyone can send that.
+2. **Exclude them from analytics.** Filter out sessions whose user agent contains `UsercaseQA`.
+3. **Separate them in logs** by the header or the user-agent suffix.
+
+## Settings
+
+Pass with `claude mcp add ... -e NAME=value`.
+
+| Name | What it does |
+|---|---|
+| `USERCASE_API_KEY` | Your project API key. Without it, visits stay on your machine only. |
+| `USERCASE_AGENT_KEY` | Your firewall secret (see above). 16+ characters. |
+| `USERCASE_ALLOW_WRITE_PATHS` | Comma-separated path patterns where non-GET requests are allowed, for sites that load pages with `POST` after sign-in. Everything else stays blocked. |
+| `USERCASE_DIAGNOSTICS` | `off` stops sending diagnostics. On by default: when the tool cannot do something or misreads the screen (a button cut off or covered, a click that landed elsewhere, a change it did not notice), Usercase receives the kind of failure, the element's shape, the page path, the HTML around the element and a screenshot of that moment, to improve the tool. Only the Usercase team sees them; they are kept for 30 days. |
+| `USERCASE_HEADED` | `1` shows the visitors' browser on screen. |
+| `USERCASE_DIR` | Working folder. Default: `.usercase` in your repository. |
+
+## Files it creates
+
+`.usercase/` in your repository:
+
+- `people.json`: the virtual users. Edit them freely; commit it if you want to reuse them.
+- `runs/`: visit records.
+- `sessions/`: one sign-in session per demo account.
+- `paths/`: screenshots of the expected paths Claude recorded, one folder per task.
+
+`runs/` and `sessions/` are git-ignored by a `.gitignore` inside the folder.
+
+## Help
+
+[usercase.io](https://usercase.io)

package/agents/steps.md

@@ -1,32 +1,42 @@
-# 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 their question, then ask about the moment
-
-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.
-
-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
-
-- 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.
-
-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.
+# Write the steps for a Usercase question or research invite
+
+Window: {{session}}
+
+The user is in the Usercase dashboard and chose Several steps for when a card appears to visitors. The card is one of two things:
+
+- **a question** (New question): one short question about the moment the visitor is in.
+- **a research invite** (Create research, or an invite on a research): an offer to take part in a short usability session about something on the site.
+
+The words on the card are theirs. **You only write when it appears** — a condition — and send it back to that window, where they see it and save.
+
+You may read the code: the routes, the components, the labels on buttons.
+
+## 1. Read their window, then ask about the moment
+
+Call `steps_brief` with the window id. It tells you whether this is a question or a research invite, the page under Where, and the words they wrote — either may still be empty, because people often choose Several steps first. 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.
+
+Then ask the user, in one short question, when the card should appear — what the visitor has done just before. If they wrote something, suggest one moment that fits it so they can just say yes. If not, just ask about the moment. 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.
+
+Use their word for the card: a question when it is a question, an invite when it is a research invite.
+
+## 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 the card:
+
+- **A question** appears when the visitor can answer it, right where the thing it asks about happened.
+- **A research invite** asks for a few minutes of someone's time. It should reach the people the research is about — visitors who just went through the part of the site it covers — at a moment when they are free to say yes: after they finished or stopped doing something, or as they are about to leave. Never in the middle of typing, paying or signing in.
+
+## 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 there. Do not save anything 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.