common-qa-mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,36 +1,53 @@
 # Common QA MCP
 
-One **product-neutral MCP** that AI clients (Claude Code, Cursor, Windsurf, …) connect to with a
-single URL + token, and which **routes** test-case-lifecycle requests to the right product:
+One **product-neutral MCP** that AI clients (Claude Code, Cursor, Windsurf, VS Code, Codex, …)
+connect to with a single URL + token, and which **routes** the whole test-case lifecycle —
+discover, author, **record**, run, triage — to the right product:
 
-- **Walnut** — directly over its REST API (`WalnutAdapter`).
+- **Walnut** — over the **Walnut agent's MCP** (`/mcp`, for the full surface **including browser +
+  mainframe recording**) or directly over the **backend REST API** (lifecycle only, no recording).
 - **SimplifyQA** — over the SimplifyQA agent's own MCP (`SimplifyQaAdapter`, an MCP client).
 
 The client sees **one tool vocabulary** and **one neutral data model** regardless of product.
 
 ```
-AI client ──MCP (url + token)──▶  COMMON QA MCP  ──▶ Walnut backend (REST)
-                                        └────────▶ SimplifyQA agent MCP ──▶ SQA backend
+                                 ┌─▶ Walnut agent /mcp ─▶ Walnut backend   (+ web & mainframe recording)
+AI client ──MCP (url+token)──▶ COMMON QA MCP ─┤─▶ Walnut backend REST                     (lifecycle only)
+                                 └─▶ SimplifyQA agent /mcp ─▶ SQA backend
 ```
 
-## What's here
-This repo is the **standalone gateway** build of the neutral core: the API lifecycle surface —
-connection, projects, discovery, drafts, validation and save-orchestration. Files under `src/`:
+## What you can do
+- **Discover** — projects, test cases, suites, and user stories.
+- **Author manual test cases** — draft plain-prose steps that cover a story's acceptance criteria
+  (`tc_draft_*`), then promote them to automated in place.
+- **Record automated test cases** — delegate a goal to a technology sub-agent that drives a **real
+  browser** (`web`) or a **TN3270 mainframe terminal** (`mainframe`), capturing real
+  locators/fields and assertions. _(Requires the Walnut agent — see below. `android` / `db` are
+  declared but not built yet.)_
+- **Run & triage** — execute a test case or a suite **local or cloud**, poll status, and report the
+  failing step + report link.
+- **Modify** — edit an existing test case's steps (loop / if-else / nested / add / remove / move)
+  without re-recording the structure.
 
-- `adapters/` — the `ProviderAdapter` contract + `walnut/` (REST) and `simplifyqa/` (remote MCP) drivers, and the adapter factory.
-- `connection.ts` / `requestConnection.ts` — the runtime connection (URL + token, in-memory, validate-before-adopt) and the header/URL-based config connection.
-- `domain/` — the neutral data model + validation.
-- `drafts/` — the edit-before-save draft store.
-- `tools/` — the client-facing tools: `connection.tools` (qa_connect / qa_switch_project / …), `discovery.tools` (list_projects / tc_list / tc_get), `testcase.tools` (tc_draft_*), plus `markdown` / `schemas`.
-- `server.ts` — assembles the MCP (`buildServer`).
-- `mount.ts` / `httpMain.ts` — the standalone Streamable-HTTP `/mcp` gateway + its entrypoint.
-- `vendor/` — three self-contained files vendored from the Walnut agent (`logger`, `actionSignatures`, `bridge`).
+## How recording works (and what it needs)
+Recording can't run inside an `npx` gateway — `web` needs a real browser/Electron window and
+`mainframe` needs an HLLAPI terminal attachment. That engine lives in the **Walnut agent**, which
+mounts this same core with the extra deps injected. So:
 
-> **Not here:** browser recording + the live editor. Those need a real browser/Electron window, so
-> they stay in the **Walnut agent**, which mounts this same core with those extra deps injected.
+- Point **`QA_MCP_URL` at the Walnut agent's `/mcp`** (default `http://127.0.0.1:4050/mcp`) and the
+  gateway **relays** the recording tools to it — you get the full surface.
+- Point it at the **backend REST URL** for a zero-agent gateway: discovery / drafts / save / run,
+  **no recording**.
+
+Recording is **non-blocking and two-step**: `web` (or `mainframe`) **starts** a session, returns a
+`sessionId` immediately, and opens a live window; you then **poll** `web_status` (or
+`mainframe_status`) until `status` is `"done"`, which returns an **unsaved draft**. Nothing is
+persisted until you explicitly save. **Mainframe** additionally needs the agent on **Windows** with
+`WINDOWS_MCP_ENABLED` and a 3270 emulator (Quick3270 `.ecf` / IBM PCOMM `.ws` / Micro Focus
+Reflection `.rd3x`).
 
 ## Install
-Nothing to install — AI clients launch it over stdio with `npx`. Requires Node >= 20.
+Nothing to build or clone — AI clients launch it over stdio with `npx`. Requires **Node ≥ 20**.
 
 `.mcp.json` (Claude Code, Cursor, Windsurf, …):
 ```json
@@ -40,21 +57,37 @@ Nothing to install — AI clients launch it over stdio with `npx`. Requires Node
       "command": "npx",
       "args": ["-y", "common-qa-mcp"],
       "env": {
-        "QA_MCP_URL": "http://localhost:8080",
+        "QA_MCP_URL": "http://127.0.0.1:4050/mcp",
         "QA_MCP_TOKEN": "<token>",
-        "QA_MCP_PROJECT_ID": "<projectId>"
+        "QA_MCP_PRODUCT": "walnut"
       }
     }
   }
 }
 ```
+- `QA_MCP_URL` — the Walnut **agent** (`…:4050/mcp`) for the full surface incl. recording, or the
+  **backend REST** URL for lifecycle only.
+- `QA_MCP_TOKEN` — your **raw** auth token (JWT, **no** `Bearer` prefix).
+- `QA_MCP_PRODUCT` — `walnut` (default) or `simplifyqa`.
+- `QA_MCP_PROJECT_ID` — **optional**; add it to pin a default project, or omit it and the agent asks
+  which project to use (then `qa_switch_project` changes it anytime).
+
 With no `QA_MCP_*` set it starts in **offline** mode — draft authoring only, zero network — and you
 can connect from chat with `qa_connect`.
 
-Install the Walnut QA agent (persona + tool guidance) into your project:
+Install the QA agent (persona + tool guidance) into your project:
 ```bash
 npx common-qa-mcp init-agents --loop=claude   # claude | cursor | windsurf | vscode | codex | all
 ```
+The installed agent asks which **technology** (web / mainframe / android / db) and **manual or
+automated** before recording, and **never saves on its own** — it persists a test case only when you
+explicitly tell it to.
+
+## Use it
+Reload your client, then drive it in plain language:
+- _"List my projects"_ → _"switch to project X"_
+- _"Record a login test on web"_ → answer the setup questions → review the draft → _"save this test case"_
+- _"Run TC_123 on cloud"_ · _"show me the login stories"_ · _"add a loop around steps 3–5 of TC_42"_
 
 ## Develop
 ```bash
@@ -66,7 +99,7 @@ npm run start:http    # HTTP gateway on http://127.0.0.1:4060/mcp  (override wit
 npm run dev:http      # HTTP gateway via tsx watch
 ```
 
-## Connect an AI client over HTTP (config-based, no chat)
+## Connect over HTTP (config-based, no chat)
 `.mcp.json`:
 ```json
 {
@@ -77,8 +110,7 @@ npm run dev:http      # HTTP gateway via tsx watch
       "headers": {
         "Authorization": "Bearer <token>",
         "x-qa-product": "walnut",
-        "x-qa-url": "http://localhost:8080",
-        "x-project-id": "<projectId>"
+        "x-qa-url": "http://127.0.0.1:4050/mcp"
       }
     }
   }
@@ -89,6 +121,28 @@ there instead. Everything after `Authorization` may also be passed as `?query` p
 back to the `QA_MCP_*` environment. At runtime, `qa_connect` / `qa_switch_project` override the
 connection without re-entering credentials.
 
+## What's inside (for contributors)
+The **standalone gateway** build of the neutral core — the lifecycle surface plus the recording
+**relay**. Files under `src/`:
+
+- `adapters/` — the `ProviderAdapter` contract + `walnut/` (REST), `remoteMcp/` (relays to the
+  Walnut agent / SimplifyQA over MCP), and the adapter factory.
+- `connection.ts` / `requestConnection.ts` — the runtime connection (URL + token, in-memory,
+  validate-before-adopt) and the header/URL-based config connection.
+- `domain/` — the neutral data model + validation.
+- `drafts/` — the edit-before-save draft store.
+- `tools/` — the client-facing tools: `connection.tools` (`qa_connect` / `qa_switch_project` / …),
+  `discovery.tools` (`list_projects` / `tc_list` / `tc_get`), `testcase.tools` (`tc_draft_*`),
+  `recording.tools` (relayed `web` / `mainframe` + their status polls), `run.tools`, plus
+  `markdown` / `schemas`.
+- `server.ts` — assembles the MCP (`buildServer`).
+- `mount.ts` / `httpMain.ts` — the standalone Streamable-HTTP `/mcp` gateway + its entrypoint.
+- `vendor/` — self-contained files vendored from the Walnut agent (`logger`, `actionSignatures`, `bridge`).
+
+> The browser/Electron recording **engine** and the live editor themselves stay in the **Walnut
+> agent** (they need a real window). This gateway **relays** those tools whenever `QA_MCP_URL`
+> targets the agent's `/mcp`.
+
 ## SimplifyQA integration
 The SimplifyQA agent implements its own MCP exposing the provider-operation tools this gateway calls
 (`info`, `list_projects`, `list_testcases`, `get_testcase`, `create_testcase`, `update_testcase`,

package/dist/server.js

@@ -9,7 +9,7 @@ import { ok, err } from './mcpResult.js';
 export { ok, err };
 const OFFLINE_TOOLS = ['actions_catalog', 'tc_draft_create', 'tc_draft_update', 'tc_draft_get', 'tc_draft_discard', 'tc_draft_open'];
 export function buildServer(deps) {
-    const server = new McpServer({ name: 'common-qa-mcp', version: '0.1.0' });
+    const server = new McpServer({ name: 'common-qa-mcp', version: '0.1.1' });
     const drafts = deps.drafts ?? new DraftStore();
     server.registerTool('project_info', {
         description: 'Validate the configured connection and return provider, org/project and entity counts.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "common-qa-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "description": "Common QA MCP — one product-neutral MCP that routes test-case lifecycle requests to Walnut or SimplifyQA for any AI client. Launch over stdio via npx; install the Walnut QA agent with `init-agents`.",
   "bin": {