@validate.qa/mcp 1.0.1 → 1.2.0

package/README.md

@@ -3,15 +3,23 @@
 MCP server for Validate.QA.
 
 This package lets AI IDEs like Claude Code and Cursor connect directly to your
-Validate.QA workspace over stdio. Your AI can create, edit, run, and heal tests
+Validate.QA workspace over **stdio**. Your AI can create, edit, run, and heal tests
 from inside the editor while Validate.QA handles execution, scheduling, and
 reporting on the platform side.
 
+**Chat apps (Claude Desktop, Grok, Grok Bot)** do not use this package. Paste the
+hosted connector URL `{API}/mcp` from Project Settings → MCP (OAuth; no PAT).
+Operator runbook: [docs/MCP-CONNECTORS.md](../../docs/MCP-CONNECTORS.md).
+
+**MCP Army (free forever).** This package works on the MCP Army plan with your own AI. Tools that use
+Validate.QA's AI (such as `heal_test`) return a `PLAN_FEATURE_LOCKED` error until the workspace upgrades to Solo Dev (everything in MCP Army, plus Validate.QA's AI and higher limits).
+Limits and the full list: [docs/MCP-ARMY.md](../../docs/MCP-ARMY.md).
+
 ## Requirements
 
 - Node.js 18+
 - A Validate.QA API URL
-- A `pat_...` personal access token
+- A `pat_...` personal access token (runner tokens `urt_` / `rt_` are rejected on `/api/mcp`)
 - A Validate.QA project ID
 
 ## Quick Start
@@ -53,7 +61,9 @@ The package resolves config in this order:
 1. CLI args: `--api-url`, `--token`, `--project-id`
 2. Environment variables: `VALIDATEQA_API_URL`, `VALIDATEQA_TOKEN`,
    `VALIDATEQA_PROJECT_ID`
-3. `.validateqa.json` in the current working directory
+3. `.validateqa.json` in the current working directory (API URL and project only)
+4. For the token only: the token `init` saved in `~/.validateqa/credentials.json`
+   for that API origin and project
 
 Example `.validateqa.json`:
 
@@ -65,11 +75,22 @@ Example `.validateqa.json`:
 ```
 
 `token` is intentionally not read from `.validateqa.json`; pass it via CLI or
-environment variable instead.
+environment variable, or let `init` save it for you.
+
+## Finding bugs with your own browser agent
+
+An agent that explores the app with its own browser tools (for example Playwright MCP) can lock in what it finds:
+
+1. `start_here({ feature })`: one read with the feature's pages, existing tests, known selectors, whether test credentials are set, open bugs, and the rules for saved test code.
+2. `save_regression_test` for each bug, with code that asserts the correct behaviour. The test runs later on an account with none of the browser's changes, so it signs in and redoes every step that made the state the agent saw. It returns at once; the test runs in the cloud while the agent keeps exploring.
+3. `collect_verdicts` at the end: for each saved test, whether it reproduces its bug, passes, or broke before its check.
+
+Set `VALIDATEQA_TOOLSET=agent` (or `--toolset agent`) to offer only the 12 tools this loop needs (about 9 KB of tool definitions instead of about 41 KB), which suits smaller models. The default is every tool.
 
 ## Claude Code Example
 
-Create `.mcp.json` in your repo:
+Create `.mcp.json` in your repo (or run `init`, below). Keep the token out of
+files you commit: set `VALIDATEQA_TOKEN` in your environment instead of `--token`.
 
 ```json
 {
@@ -80,8 +101,6 @@ Create `.mcp.json` in your repo:
         "@validate.qa/mcp",
         "--api-url",
         "https://api.myorg.validate.qa",
-        "--token",
-        "pat_xxxxxxxxxxxx",
         "--project-id",
         "proj_xxxxxxxxxxxx"
       ]
@@ -92,7 +111,7 @@ Create `.mcp.json` in your repo:
 
 ## Cursor Example
 
-Create `.cursor/mcp.json` in your repo:
+Create `.cursor/mcp.json` in your repo (token from `VALIDATEQA_TOKEN`, as above):
 
 ```json
 {
@@ -103,8 +122,6 @@ Create `.cursor/mcp.json` in your repo:
         "@validate.qa/mcp",
         "--api-url",
         "https://api.myorg.validate.qa",
-        "--token",
-        "pat_xxxxxxxxxxxx",
         "--project-id",
         "proj_xxxxxxxxxxxx"
       ]
@@ -131,9 +148,45 @@ This can create or update:
 - `.windsurf/mcp.json` for Windsurf
 - `.vscode/mcp.json` for VS Code
 
+These files hold the API URL and project, never the token, so they are safe to
+commit. The token is saved in `~/.validateqa/credentials.json` (readable only by
+you), keyed by the API origin and project; each teammate runs their own `init`.
+If that file cannot be written, the config files carry the token instead and
+`init` adds them to `.gitignore`.
+
+## Playwright Test Agents (`init-agents`)
+
+To run Playwright's planner / generator / healer agents with Validate.QA layered
+on top:
+
+```bash
+npx @validate.qa/mcp init-agents --loop claude --dir .
+```
+
+Options:
+
+- `--loop claude|vscode|opencode` (default: `claude`)
+- `--dir <repo>` (default: current directory)
+
+`init-agents`:
+
+1. Runs `npx playwright init-agents --loop=<loop>` in the target repository.
+2. Appends a delimited `<!-- validate.qa:start -->` … `<!-- validate.qa:end -->`
+   rules section to each generated planner, generator, and healer file
+   (idempotent on re-run).
+3. Adds `validate.qa` (`VALIDATEQA_TOOLSET=agent`) alongside `playwright-test` in
+   the loop's MCP config (`.mcp.json`, `.vscode/mcp.json`, or `opencode.json`)
+   without overwriting existing entries or writing any token. The server reads
+   its project from `.validateqa.json` and its token from your token store, so
+   run `init` from your dashboard once first, or set `VALIDATEQA_TOKEN`,
+   `VALIDATEQA_PROJECT_ID` and `VALIDATEQA_API_URL` (see
+   [Configuration Resolution](#configuration-resolution)).
+
 ## More Docs
 
-- Full MCP guide:
+- Full MCP guide (stdio + tool reference):
   [docs/MCP.md](https://github.com/Validate-QA/validate.qa/blob/main/docs/MCP.md)
+- Remote connectors / OAuth / directory submission:
+  [docs/MCP-CONNECTORS.md](https://github.com/Validate-QA/validate.qa/blob/main/docs/MCP-CONNECTORS.md)
 - Package source:
   [packages/mcp-server](https://github.com/Validate-QA/validate.qa/tree/main/packages/mcp-server)