mcprigor 1.0.0-rc.4 → 1.1.0

package/docs/ENGINEER-SETUP.md

@@ -13,7 +13,7 @@ npm install --save-dev mcprigor
 For reproducible CI runs, pin an exact version in `package.json` and update it deliberately:
 
 ```json
-{ "devDependencies": { "mcprigor": "1.0.0-rc.4" } }
+{ "devDependencies": { "mcprigor": "1.1.0" } }
 ```
 
 Release notes and tarball checksums for each version are on the [GitHub releases page](https://github.com/FusionOnePlatform/mcprigor/releases).

package/docs/GETTING-STARTED.md

@@ -10,7 +10,7 @@ You need Node.js 20 or 22. MCP Rigor is published on npm as [`mcprigor`](https:/
 mkdir mcp-acceptance-tests
 cd mcp-acceptance-tests
 npm init -y
-npm install --save-dev mcprigor
+npm install mcprigor
 ```
 
 To check the installation:
@@ -88,7 +88,7 @@ Open `report.html` or attach it to a ticket.
 npx mcprigor workspace .
 ```
 
-Open the printed local URL. Select `calculator.mcpr`, edit it, choose **Validate**, then **Run tests**.
+Open the printed local URL. Select `calculator.mcpr` — the editor gives you syntax highlighting and autocomplete — then choose **Validate** and **▶ Run tests**. You can also create new test files, run several suites at once with the checkboxes, and review run history and trends in the results panel. See the [QA workspace guide](QA-WORKSPACE.md).
 
 ## If you do not know tool names
 

package/docs/MCP-SERVER.md

@@ -0,0 +1,67 @@
+# MCP Rigor as an MCP server
+
+Expose MCP Rigor itself over the Model Context Protocol so AI agents — Claude Code, Cursor, or any MCP client — can write, validate, and run natural-language acceptance tests for the MCP server they are building. The agent gets a deterministic feedback loop: it writes a `.mcpr` file, runs it, reads structured pass/fail results, fixes the server, and repeats. No AI interprets the test wording at runtime.
+
+## Start it
+
+From your project directory:
+
+```bash
+mcprigor serve
+```
+
+Or with an explicit root:
+
+```bash
+mcprigor serve path/to/project
+```
+
+The server speaks MCP over stdio. Typical client configuration:
+
+```json
+{
+  "mcpServers": {
+    "mcprigor": {
+      "command": "npx",
+      "args": ["mcprigor", "serve", "/absolute/path/to/project"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `list_suites` | List test files under the root (`.mcpr`, YAML, JSON). |
+| `read_suite` | Read one test file. |
+| `write_suite` | Create or overwrite one `.mcpr` file (omit `text` for a starter template). |
+| `validate_suite` | Compile without running; returns test names or a diagnostic with line/column and a fix hint. |
+| `run_tests` | Run 1–20 suites; returns per-test status, duration, and failure messages. Failing runs set `isError`. |
+| `run_parity` | Run a suite's declared parity targets and compare transports. |
+| `get_history` | Read recorded run history, filterable by suite or test name. |
+
+Results are returned both as JSON text and as `structuredContent`, and test runs append to `.mcprigor/workspace-history.jsonl` — the same history the [QA workspace](QA-WORKSPACE.md) shows as trends.
+
+## The agent loop
+
+1. `write_suite` — the agent drafts acceptance tests in natural language.
+2. `validate_suite` — deterministic wording check; diagnostics carry exact line and column.
+3. `run_tests` — starts the server declared by each suite's `Server:` line, runs the tests, returns structured results.
+4. The agent fixes its MCP server (or the test) and repeats.
+5. `get_history` — spot regressions across iterations.
+
+## Trust model
+
+`run_tests` and `run_parity` start whatever command each suite's `Server:` line declares, with the workspace root as working directory — exactly like running `mcprigor test` yourself. This is the same trust model as `npm test`: point the root at a project you trust, because test suites in that project can execute code.
+
+Additional guards:
+
+- file access is confined to the workspace root, with the same path and type restrictions as the QA workspace;
+- `write_suite` only writes `.mcpr` files, capped at 1 MiB;
+- batches are capped at 20 suites per call;
+- a recursion guard refuses to start when a suite under test spawns `mcprigor serve` itself more than two levels deep.
+
+## Limits
+
+The MCP server exposes the create/validate/run loop. Renaming files, deleting files, snapshot acceptance, contract updates, and evidence comparison remain CLI (or workspace) operations by design — an agent should not silently rewrite baselines that exist to catch its own regressions.

package/docs/PLAIN-LANGUAGE-COOKBOOK.md

@@ -185,6 +185,79 @@ Test: "Search behaves the same"
 
 Run with `mcprigor parity FILE`.
 
+## Test a server that needs a bearer token
+
+Point the suite at the deployed endpoint and pass the token through an environment variable. Never paste a real token into a test file.
+
+```text
+MCP Test 1
+Suite: "Deployed order service"
+MCP URL: https://qa.example.com/mcp
+
+Server options:
+  headers:
+    Authorization: "Bearer ${env.QA_TOKEN}"
+
+Test: "an authenticated call succeeds"
+  Call tool "find_order" with:
+    orderId: "A-1001"
+  Expect "structuredContent.status" equals "shipped"
+```
+
+Run it with the token in the environment:
+
+```bash
+QA_TOKEN=... mcprigor test orders.mcpr
+```
+
+Three guarantees come with this pattern:
+
+- if `QA_TOKEN` is not set, the run stops with `Environment variable not found: QA_TOKEN` instead of sending an empty header;
+- header values are registered with the redactor automatically, so the token never appears in reports or evidence bundles;
+- a wrong or expired token surfaces the server's own response (for example `{"error":"unauthorized"}`) in the failure message.
+
+Any header works the same way — `X-Api-Key`, custom tenant headers, and so on.
+
+## Compare an open local server with a protected deployment
+
+Parity targets accept per-target options, so the local build can run without auth while the deployed target sends the token:
+
+```text
+Compare target "Local": node dist/server.js
+Compare target "QA": https://qa.example.com/mcp
+
+Target options for "QA":
+  headers:
+    Authorization: "Bearer ${env.QA_TOKEN}"
+
+Test: "Search behaves the same"
+  Call tool "search" with:
+    query: "red shoes"
+  Expect "structuredContent.total" equals 2
+```
+
+## When the token must be fetched first
+
+MCP Rigor does not perform OAuth login flows or token exchanges itself; tests stay deterministic and secrets stay outside test files. When a short-lived token must be acquired (client-credentials exchange, cloud CLI, vault), fetch it in the step before the run:
+
+```bash
+QA_TOKEN=$(curl -s -X POST https://auth.example.com/oauth/token \
+  -d grant_type=client_credentials \
+  -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET" | jq -r .access_token)
+QA_TOKEN=$QA_TOKEN mcprigor test orders.mcpr
+```
+
+In CI, do the same in the workflow:
+
+```yaml
+- name: Acceptance tests
+  env:
+    QA_TOKEN: ${{ secrets.QA_TOKEN }}
+  run: npx mcprigor test tests/*.mcpr
+```
+
+Interactive browser-redirect OAuth is out of scope by design: an acceptance run must be repeatable without a human in the loop.
+
 ## Match a snapshot
 
 ```text

package/docs/QA-WORKSPACE.md

@@ -1,6 +1,6 @@
 # QA workspace
 
-Use MCP Rigor in a browser to edit, validate, and run saved tests.
+Use MCP Rigor in a browser to create, edit, validate, and run saved tests — no terminal needed for the daily loop.
 
 ## Start it
 
@@ -18,31 +18,53 @@ mcprigor workspace . --port 4173
 
 Open the printed local URL, for example `http://127.0.0.1:4173`.
 
+Start it from a dedicated project folder rather than your home directory. Hidden directories and unreadable folders are skipped automatically, and suite discovery stops six levels deep.
+
+## First run
+
+An empty folder shows a three-step welcome screen. Choose **＋ New test file** (or press `Ctrl/⌘+N`): the file is created from a working example and opens immediately. Point the `Server:` line at your MCP server command — or replace it with `MCP URL:` for a deployed HTTP endpoint — then **Validate** and **▶ Run tests**.
+
 ## Daily workflow
 
-1. Select a `.mcpr` suite in the left panel.
-2. Edit the plain-language scenario.
-3. Choose **Validate**.
-4. Fix any diagnostic shown below the editor.
-5. Choose **Run tests** or **Run parity**.
-6. Review the result panel.
-7. Save the file.
+1. Select a `.mcpr` suite in the left panel, or create one with **＋ New test file**.
+2. Edit the plain-language scenario. The editor provides syntax highlighting, line numbers, and autocomplete: top-level declarations at the start of a line, actions and assertions when indented, and comparison phrases after `Expect "field"`. Accept with `Tab` or `Enter`; force the list open with `Ctrl+Space`.
+3. Choose **Validate** (`Ctrl/⌘+S` saves, `Ctrl/⌘+Enter` runs). A wording problem highlights the offending line and moves the cursor to it.
+4. Choose **▶ Run tests** or **Parity**.
+5. Review the results panel: per-file pass/fail with durations; select a file for its full report.
+
+The editor marks unsaved changes; running or validating saves them first. If the file changed elsewhere after you opened it, the workspace refuses to overwrite it and asks you to reload.
+
+## Batch runs
+
+Every file row has a checkbox. Selecting one or more files shows a batch bar with **Validate**, **Parity**, and **▶ Run** for the whole selection (up to 20 files per run). The Run panel lists each file with its outcome and duration.
+
+## Renaming
+
+Rename a file from the pencil icon on its row, the toolbar pencil, or by double-clicking the file name. Run history follows the new name automatically, so History and Trends stay intact. To rename an individual test, edit its `Test: "…"` line — history tracks tests by name within each suite.
+
+## History, trends, and search
+
+Test runs are recorded in `.mcprigor/workspace-history.jsonl` (most recent 2000 entries). The results panel has three tabs:
+
+- **Run** — the current run, with per-file reports.
+- **History** — past runs, expandable to per-test status, duration, and error text.
+- **Trends** — per-suite pass rate, a duration sparkline over the last 30 runs, and per-test pass-rate bars that make flaky or consistently failing tests stand out.
 
-The editor marks unsaved changes. If the file changed elsewhere after you opened it, the workspace refuses to overwrite it and asks you to reload.
+One search box filters all three tabs. It matches suite names, test names, and error text, and highlights matches, so you can answer questions like "when did `delivered` start failing?" without leaving the browser.
 
 ## What is available
 
-- Saved `.mcpr`, YAML, and JSON suites
-- Plain-language editing
-- Validation without server execution
-- Test execution
+- Creating, renaming, and editing `.mcpr` suites (YAML and JSON suites are listed and editable too)
+- Syntax highlighting and grammar-aware autocomplete
+- Validation without server execution, with line-anchored diagnostics
+- Test execution, single file or batch
 - Transport parity execution
-- Terminal-style results
+- Persistent run history with trends and search
 - Local evidence indexing
 
-## Current candidate limits
+## Current limits
 
-The browser currently focuses on the core edit/validate/run/parity loop. Use the CLI for:
+The browser focuses on the create/edit/validate/run loop. Use the CLI for:
 
 - guided test generation;
 - contract discovery and drift updates;
@@ -73,6 +95,7 @@ If a suite does not appear, confirm that:
 
 - it is under the selected workspace directory;
 - its extension is `.mcpr`, `.yaml`, `.yml`, or `.json`;
-- it is not inside `node_modules`, `.git`, or `dist`.
+- it is not inside `node_modules`, `dist`, a hidden directory (such as `.git`), or deeper than six levels;
+- the directory containing it is readable.
 
 For server and test failures, see [troubleshooting](TROUBLESHOOTING.md).

package/docs/README.md

@@ -48,7 +48,7 @@ install → create .mcpr test → check → test → add CI → enable evidence
 ```
 
 ```bash
-npm install --save-dev mcprigor
+npm install mcprigor
 npx mcprigor init tests/acceptance.mcpr
 npx mcprigor check tests/acceptance.mcpr
 npx mcprigor test tests/acceptance.mcpr --html report.html

package/docs/TROUBLESHOOTING.md

@@ -43,6 +43,12 @@ Check that the stdio server:
 
 For HTTP, verify the URL, authentication, and server logs.
 
+For token-protected endpoints:
+
+- `Environment variable not found: QA_TOKEN` — export the variable before running, or set it in the CI step's `env:` block.
+- `MCP-INIT-001 Streamable HTTP error … unauthorized` — the token was sent but rejected; check its value, expiry, and audience. The server's own response body is included in the message.
+- Tokens and header values are redacted from reports and evidence automatically; do not paste them into test files to "make them visible".
+
 ## A field was not found
 
 Example:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcprigor",
-  "version": "1.0.0-rc.4",
+  "version": "1.1.0",
   "description": "Plain-language MCP testing with isolated extensions and a local QA workspace",
   "type": "module",
   "bin": {