mcprigor 1.5.0 → 1.5.1

package/docs/CLI-REFERENCE.md

@@ -19,7 +19,7 @@ Creates an editable plain-language example. Existing files are protected unless
 mcprigor author server.mcpr --out tests/customer.mcpr
 ```
 
-Connects to the target in `server.mcpr` and guides you through creating a test.
+Connects to the target in `server.mcpr` and guides you through creating a test. Alias: `create`.
 
 ## Validate and run
 
@@ -91,6 +91,15 @@ mcprigor workspace ./acceptance-tests --port 4173
 
 Starts a loopback-only QA interface. Alias: `web`.
 
+## MCP server for agents
+
+```bash
+mcprigor serve
+mcprigor serve path/to/project
+```
+
+Exposes MCP Rigor itself as an MCP server over stdio so coding agents can write, validate, and run suites. Alias: `mcp`. See the [MCP server guide](MCP-SERVER.md).
+
 ## Transport parity
 
 ```bash

package/docs/GETTING-STARTED.md

@@ -126,7 +126,7 @@ mcp-acceptance-tests/
 
 ## Next steps
 
-- [Plain-language cookbook](PLAIN-LANGUAGE-COOKBOOK.md)
+- [Natural-language cookbook](NATURAL-LANGUAGE-COOKBOOK.md)
 - [QA workspace](QA-WORKSPACE.md)
 - [Engineer setup and CI](ENGINEER-SETUP.md)
 - [Troubleshooting](TROUBLESHOOTING.md)

package/docs/GITHUB-ACTION.md

@@ -1,6 +1,6 @@
 # GitHub Action and pull-request reports
 
-> Available on `main`; publish by pinning the next MCP Rigor release tag.
+> Available since `v1.5.0`; pin `@v1` for the latest 1.x or `@v1.5.0` for full reproducibility.
 
 The MCP Rigor Action runs deterministic suites, optionally gates contract drift, includes flaky-history warnings, writes a rich job summary, and creates or updates one pull-request comment.
 

package/docs/LANGUAGE-SPEC.md

@@ -64,6 +64,42 @@ Server options:
     Authorization: "Bearer ${env.QA_TOKEN}"
 ```
 
+An HTTP target may fetch a bearer token at run time with `Token from` (a command whose single-line stdout becomes the `Authorization` header), or drive an interactive browser login with `OAuth`:
+
+```text
+Server options:
+  OAuth: oauth
+```
+
+`OAuth: oauth` performs an authorization-code + PKCE browser login once at the start of the run and carries the in-memory session (with automatic refresh) into every test. The block form takes optional `clientId`, `clientSecret` (use `${env.NAME}`), and `scope`. Tokens are never written to disk and are always redacted. See the [Authentication guide](AUTHENTICATION.md).
+
+### Environment variables and secrets
+
+Any string value in a target block — a header, a URL, a `cwd`, an `env` entry, a `Server options` field — may contain `${env.NAME}` placeholders. Before the suite connects, each placeholder is replaced with the value of the operating-system environment variable `NAME`:
+
+```text
+MCP URL: ${env.MCP_URL}
+
+Server options:
+  headers:
+    Authorization: "Bearer ${env.MCP_TOKEN}"
+    X-Api-Key: "${env.API_KEY}"
+```
+
+```bash
+MCP_URL=https://qa.example.com/mcp MCP_TOKEN=... API_KEY=... mcprigor test suite.mcpr
+```
+
+Rules:
+
+- The syntax is exactly `${env.NAME}`. `NAME` is a literal environment-variable name; there is no shell, no command substitution, and no default-value syntax.
+- A placeholder may be embedded in a larger string (`"Bearer ${env.MCP_TOKEN}"`) or be the whole value (`"${env.API_KEY}"`), and a value may contain several placeholders.
+- If `NAME` is not set, the run stops immediately with `Environment variable not found: NAME` — it never sends an empty header or a half-substituted URL.
+- Never write a literal secret into a suite. Keep tokens and keys in the environment (locally) or in CI secrets, and reference them with `${env.NAME}` so the committed `.mcpr` file carries no credentials.
+- Header values are registered with the redactor automatically, so a resolved token never appears in reports, evidence bundles, or published URLs.
+
+The same `${env.NAME}` placeholders work in every target surface: single-server `Server options`, per-server `Server options for "name"` in compositions, and `Target options for "name"` in parity comparisons.
+
 Multi-server compositions use named server declarations and per-test routing:
 
 ```text

package/docs/MCP-SERVER.md

@@ -16,7 +16,7 @@ Or with an explicit root:
 mcprigor serve path/to/project
 ```
 
-The server speaks MCP over stdio. Typical client configuration:
+The server speaks MCP over stdio (`mcp` is an alias for `serve`). Typical client configuration:
 
 ```json
 {

package/docs/{PLAIN-LANGUAGE-COOKBOOK.md → NATURAL-LANGUAGE-COOKBOOK.md}

@@ -1,4 +1,4 @@
-# Plain-language cookbook
+# Natural-language cookbook
 
 Copy a pattern, replace the names and values, then run `mcprigor check FILE`.
 
@@ -187,7 +187,7 @@ 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.
+Point the suite at the deployed endpoint and pass the token through an environment variable. The `${env.NAME}` placeholder is replaced with the value of the `NAME` environment variable before the suite connects, so no real token ever lives in the test file.
 
 ```text
 MCP Test 1
@@ -210,6 +210,15 @@ Run it with the token in the environment:
 QA_TOKEN=... mcprigor test orders.mcpr
 ```
 
+The placeholder can sit inside a larger string (`"Bearer ${env.QA_TOKEN}"`) or be the whole value, and any header works the same way — API keys, custom tenant headers, and so on:
+
+```text
+Server options:
+  headers:
+    X-Api-Key: "${env.API_KEY}"
+    X-Tenant: "acme"
+```
+
 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;
@@ -238,7 +247,7 @@ Test: "Search behaves the same"
 
 ## 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:
+When a short-lived token must be acquired non-interactively (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 \
@@ -256,7 +265,29 @@ In CI, do the same in the workflow:
   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.
+For CI and other unattended runs, obtain the token non-interactively as above. When a real user must sign in through a browser, use interactive OAuth instead (next recipe).
+
+## Sign in through the browser (interactive OAuth)
+
+When a server requires a real user login, let MCP Rigor run the browser authorization-code flow once and carry the authorized session — with automatic refresh — into every test in the run:
+
+```text
+MCP URL: https://app.example.com/mcp
+
+Server options:
+  OAuth: oauth
+
+Test: "an authenticated call succeeds"
+  Call tool "find_order" with:
+    orderId: "A-1001"
+  Expect "structuredContent.status" equals "shipped"
+```
+
+```bash
+mcprigor test orders.mcpr
+```
+
+Your browser opens to the identity provider; after you sign in, the tokens are held in memory (never written to disk, always redacted) and reused for the whole suite. For pre-registered clients or specific scopes, use the block form with `clientId`, `clientSecret: "${env.…}"`, and `scope`. Because it needs a human, keep interactive OAuth for local runs and use a non-interactive credential in CI. See the [Authentication guide](AUTHENTICATION.md) for the full flow.
 
 ## Fetch an OAuth token before connecting
 

package/docs/QA-GUIDE.md

@@ -1,6 +1,6 @@
 # QA guide
 
-Use this page as a short everyday checklist. For examples, open the [plain-language cookbook](PLAIN-LANGUAGE-COOKBOOK.md).
+Use this page as a short everyday checklist. For examples, open the [natural-language cookbook](NATURAL-LANGUAGE-COOKBOOK.md).
 
 ## Everyday workflow
 
@@ -121,7 +121,7 @@ Use values as `${row.input}` and `${row.expected}`.
 ## Where to go next
 
 - [Getting started](GETTING-STARTED.md)
-- [Plain-language cookbook](PLAIN-LANGUAGE-COOKBOOK.md)
+- [Natural-language cookbook](NATURAL-LANGUAGE-COOKBOOK.md)
 - [Guided authoring](GUIDED-AUTHORING.md)
 - [Data and reusable flows](DATA-AND-REUSE.md)
 - [Troubleshooting](TROUBLESHOOTING.md)

package/docs/README.md

@@ -5,7 +5,7 @@ Choose the path that matches your role.
 ## QA authors
 
 1. [Getting started](GETTING-STARTED.md) — install, connect, and run your first test.
-2. [Plain-language cookbook](PLAIN-LANGUAGE-COOKBOOK.md) — copy-ready scenarios and assertions.
+2. [Natural-language cookbook](NATURAL-LANGUAGE-COOKBOOK.md) — copy-ready scenarios and assertions.
 3. [QA workspace](QA-WORKSPACE.md) — edit and run tests in a browser.
 4. [Data and reusable flows](DATA-AND-REUSE.md) — tables, files, functions, and shared flows.
 5. [Troubleshooting](TROUBLESHOOTING.md) — understand errors and fix common failures.
@@ -13,8 +13,9 @@ Choose the path that matches your role.
 ## Test and platform engineers
 
 - [Engineer setup](ENGINEER-SETUP.md) — targets, credentials, project layout, and CI.
+- [Authentication and secrets](AUTHENTICATION.md) — test protected servers with bearer tokens, API keys, OAuth, and `${env.NAME}` placeholders.
 - [CLI reference](CLI-REFERENCE.md) — commands, options, outputs, and exit codes.
-- [Language reference](LANGUAGE-SPEC.md) — complete deterministic `.mcpr` syntax.
+- [Language reference](LANGUAGE-SPEC.md) — complete deterministic `.mcpr` syntax, in enforced parity with YAML via `mcprigor convert`.
 - [State and dependencies](STATE-AND-DEPENDENCIES.md) — share outputs across tests and runs.
 - [Data engineering](DATA-ENGINEERING.md) — types, filters, joins, samples, and caches.
 - [Transport parity](TRANSPORT-PARITY.md) — compare stdio and Streamable HTTP.

package/package.json

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

package/workspace-assets/index.html

@@ -38,7 +38,7 @@
       <button id="batch-clear" class="ghost small">Clear selection</button>
     </div>
     <div class="sidebar-foot">
-      <a href="https://mcprigor.com/docs/plain-language-cookbook.html" target="_blank" rel="noreferrer">📖 Cookbook — copy-ready examples</a>
+      <a href="https://mcprigor.com/docs/natural-language-cookbook.html" target="_blank" rel="noreferrer">📖 Cookbook — copy-ready examples</a>
     </div>
   </aside>
   <div class="splitter" id="split-left" role="separator" aria-orientation="vertical" aria-label="Resize file list" tabindex="0"></div>