@usercase/mcp 0.2.3 → 0.2.4-next.0

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)