qaa-agent 1.8.0 → 1.8.1

package/.mcp.json

@@ -3,6 +3,10 @@
     "playwright": {
       "command": "npx",
       "args": ["@playwright/mcp@latest"]
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
     }
   }
 }

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 
 All notable changes to QAA (QA Automation Agent) are documented here.
 
+## [1.8.1] - 2026-04-16
+
+### Added
+
+- **Context7 MCP integration** — `@upstash/context7-mcp` is now bundled alongside Playwright MCP. The installer registers both MCP servers in the user-scope config (`~/.claude.json`) so they're available in every project on the machine, not just in the QAA repo. Context7 gives every QAA agent on-demand access to up-to-date library documentation (Playwright, Cypress, Jest, Vitest, pytest, and any other framework), keeping generated tests aligned with current APIs instead of outdated training data.
+- **`bin/install.cjs` installer script** — the file was referenced in `package.json` but didn't actually exist on npm, causing `npx qaa-agent` to fail silently (`No bin file found at bin/install.cjs`). The installer now performs three steps on every run: (1) copies agents, commands, skills, templates, workflows, docs, and config files into the chosen scope (`~/.claude/qaa` for global, `./.claude/qaa` for local), (2) registers both MCP servers in `~/.claude.json` with idempotency — existing entries are not duplicated, and (3) deep-merges the QAA permissions into the user's `settings.json` without overwriting their existing settings.
+
+### Changed
+
+- **MCP registration is now user-scope by default** — previously MCPs were defined only in the project-level `.mcp.json`, which meant they only activated when the user opened the QAA repo itself. They now register in `~/.claude.json`, making them available in every Claude Code project on the user's machine. The project-level `.mcp.json` is kept for QAA development purposes but is no longer the source of truth for end users.
+
+### Fixed
+
+- **Silent `npx qaa-agent` failure** — users who installed QAA via npm before this release did not get Playwright or Context7 MCPs registered because the installer script was missing from the published package. Publishing 1.8.1 restores the expected behavior: a single `npx qaa-agent` command copies all files and registers both MCPs globally.
+
 ## [1.8.0] - 2026-04-13
 
 ### Added

package/README.md

@@ -43,7 +43,9 @@ npx qaa-agent
 The interactive installer:
 
 1. Copies agents, commands, skills, templates, and workflows into your runtime directory
-2. Configures the [Playwright MCP](https://www.npmjs.com/package/@playwright/mcp) server in your user-scope config (`~/.claude.json`) so it's available in **all projects**
+2. Registers **two MCP servers** in your user-scope config (`~/.claude.json`) so they're available in **all projects**:
+   - [Playwright MCP](https://www.npmjs.com/package/@playwright/mcp) — live browser control for E2E tests and locator extraction
+   - [Context7 MCP](https://www.npmjs.com/package/@upstash/context7-mcp) — up-to-date library documentation on demand
 3. Merges required permissions into `settings.json`
 
 **Supported runtimes:** Claude Code, OpenCode
@@ -55,48 +57,34 @@ The interactive installer:
 - [Node.js](https://nodejs.org/) 18+
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
 
-### Playwright MCP (required for E2E)
+### Bundled MCP servers
 
-QAA uses [`@playwright/mcp`](https://www.npmjs.com/package/@playwright/mcp) to open a real browser, extract locators from live pages, run E2E tests, and auto-fix locator mismatches.
+Both MCP servers are **registered automatically** in `~/.claude.json` when you run `npx qaa-agent`. No manual setup required — once installed, they're available in every Claude Code project on your machine.
 
-**You need to install the Playwright MCP server manually in your environment:**
+#### Playwright MCP — live browser control
 
-<details>
-<summary><strong>VS Code (Claude Code extension)</strong></summary>
+Uses [`@playwright/mcp`](https://www.npmjs.com/package/@playwright/mcp) to:
 
-1. Open VS Code Settings (`Ctrl+Shift+P` > `Preferences: Open User Settings (JSON)`)
-2. Add the MCP server config:
+- Open a real browser and navigate your running app
+- Extract actual locators (`data-testid`, ARIA roles, labels) from live pages
+- Run E2E tests, capture failures, and auto-fix locator mismatches
+- Build a persistent **Locator Registry** (`.qa-output/locators/`) that caches real locators across features
 
-```json
-{
-  "claude-code.mcpServers": {
-    "playwright": {
-      "command": "npx",
-      "args": ["@playwright/mcp@latest"]
-    }
-  }
-}
-```
+#### Context7 MCP — up-to-date library docs
 
-Or add it to your project's `.vscode/mcp.json`:
+Uses [`@upstash/context7-mcp`](https://www.npmjs.com/package/@upstash/context7-mcp) to:
 
-```json
-{
-  "servers": {
-    "playwright": {
-      "command": "npx",
-      "args": ["@playwright/mcp@latest"]
-    }
-  }
-}
-```
+- Fetch the latest documentation for Playwright, Cypress, Jest, Vitest, pytest, and any other library the agent is working with
+- Keep generated tests aligned with current framework APIs instead of outdated training data
+- Free tier: ~60 requests/hour, ~3,300 tokens/query
 
-</details>
+#### Verifying the MCPs are connected
 
-<details>
-<summary><strong>Claude Code CLI</strong></summary>
+Open Claude Code in any project and type `/mcp`. You should see both `playwright` and `context7` listed as connected.
 
-Add to `~/.claude.json` (user-scope, all projects):
+#### Manual config (fallback)
+
+If for any reason the automatic registration fails, you can add the servers manually to `~/.claude.json`:
 
 ```json
 {
@@ -104,21 +92,15 @@ Add to `~/.claude.json` (user-scope, all projects):
     "playwright": {
       "command": "npx",
       "args": ["@playwright/mcp@latest"]
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
     }
   }
 }
 ```
 
-Or add a `.mcp.json` file in your project root for project-scope only.
-
-</details>
-
-Once configured, Playwright MCP enables QAA to:
-- Open a real browser and navigate your running app
-- Extract actual locators (`data-testid`, ARIA roles, labels) from live pages
-- Run E2E tests, capture failures, and auto-fix locator mismatches
-- Build a persistent **Locator Registry** (`.qa-output/locators/`) that caches real locators across features
-
 ---
 
 ## Quick Start
@@ -328,7 +310,7 @@ qaa-agent/
   bin/             # Installer and CLI tools
   docs/            # User documentation
   CLAUDE.md        # QA standards (read by every agent)
-  .mcp.json        # Playwright MCP server config
+  .mcp.json        # Playwright + Context7 MCP server config
   settings.json    # Claude Code permissions
 ```
 

package/bin/install.cjs

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+
+/**
+ * QAA Agent Installer
+ *
+ * Installs QAA (QA Automation Agent) into the user's Claude Code environment.
+ *
+ * What it does:
+ *   1. Copies agents, commands, skills, templates, workflows, docs, bin, and config files
+ *      to the chosen install directory (global ~/.claude/qaa or local ./.claude/qaa)
+ *   2. Registers Playwright MCP and Context7 MCP as global MCP servers
+ *   3. Merges required permissions into Claude Code settings.json
+ *
+ * Usage:
+ *   npx qaa-agent
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { execSync } = require('child_process');
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+function log(msg) { console.log(`  ${msg}`); }
+function success(msg) { console.log(`  ✓ ${msg}`); }
+function warn(msg) { console.log(`  ⚠ ${msg}`); }
+function fail(msg) { console.error(`  ✗ ${msg}`); }
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(`  ${question} `, answer => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(src)) return 0;
+  fs.mkdirSync(dest, { recursive: true });
+  let count = 0;
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      count += copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      count++;
+    }
+  }
+  return count;
+}
+
+function deepMerge(target, source) {
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] && typeof source[key] === 'object' && !Array.isArray(source[key]) &&
+      target[key] && typeof target[key] === 'object' && !Array.isArray(target[key])
+    ) {
+      deepMerge(target[key], source[key]);
+    } else if (Array.isArray(source[key]) && Array.isArray(target[key])) {
+      // Merge arrays without duplicates
+      const merged = [...new Set([...target[key], ...source[key]])];
+      target[key] = merged;
+    } else {
+      target[key] = source[key];
+    }
+  }
+  return target;
+}
+
+// ── MCP Registration ─────────────────────────────────────────────────────────
+
+function registerMcpServers(claudeJsonPath) {
+  const mcpServers = {
+    playwright: {
+      command: 'npx',
+      args: ['@playwright/mcp@latest']
+    },
+    context7: {
+      command: 'npx',
+      args: ['-y', '@upstash/context7-mcp@latest']
+    }
+  };
+
+  let config = {};
+  if (fs.existsSync(claudeJsonPath)) {
+    try {
+      config = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf-8'));
+    } catch {
+      config = {};
+    }
+  }
+
+  if (!config.mcpServers) config.mcpServers = {};
+
+  let added = [];
+  for (const [name, serverConfig] of Object.entries(mcpServers)) {
+    if (!config.mcpServers[name]) {
+      config.mcpServers[name] = serverConfig;
+      added.push(name);
+    }
+  }
+
+  fs.writeFileSync(claudeJsonPath, JSON.stringify(config, null, 2) + '\n');
+  return added;
+}
+
+// ── Settings Merge ───────────────────────────────────────────────────────────
+
+function mergeSettings(installDir, packageDir) {
+  const srcSettings = path.join(packageDir, 'settings.json');
+  if (!fs.existsSync(srcSettings)) return false;
+
+  const claudeDir = path.dirname(installDir);
+  const destSettings = path.join(claudeDir, 'settings.json');
+
+  const source = JSON.parse(fs.readFileSync(srcSettings, 'utf-8'));
+
+  let target = {};
+  if (fs.existsSync(destSettings)) {
+    try {
+      target = JSON.parse(fs.readFileSync(destSettings, 'utf-8'));
+    } catch {
+      target = {};
+    }
+  }
+
+  deepMerge(target, source);
+  fs.writeFileSync(destSettings, JSON.stringify(target, null, 2) + '\n');
+  return true;
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log('');
+  console.log('  ╔═══════════════════════════════════════╗');
+  console.log('  ║   QAA — QA Automation Agent Installer ║');
+  console.log('  ╚═══════════════════════════════════════╝');
+  console.log('');
+
+  // Determine package root (where the npm package files are)
+  const packageDir = path.resolve(__dirname, '..');
+
+  // Check that package files exist
+  const requiredDirs = ['agents', 'commands', 'skills'];
+  const missing = requiredDirs.filter(d => !fs.existsSync(path.join(packageDir, d)));
+  if (missing.length > 0) {
+    fail(`Package incomplete — missing: ${missing.join(', ')}`);
+    process.exit(1);
+  }
+
+  // Ask install scope
+  console.log('  Install scope:');
+  console.log('    1) Global  — ~/.claude/qaa  (available in all projects)');
+  console.log('    2) Local   — ./.claude/qaa  (this project only)');
+  console.log('');
+  const scopeChoice = await ask('Choose [1/2] (default: 1):');
+  const isGlobal = scopeChoice !== '2';
+
+  const homeDir = process.env.HOME || process.env.USERPROFILE;
+  const claudeDir = isGlobal
+    ? path.join(homeDir, '.claude')
+    : path.join(process.cwd(), '.claude');
+  const installDir = path.join(claudeDir, 'qaa');
+
+  // Check for existing installation
+  if (fs.existsSync(installDir)) {
+    const overwrite = await ask('QAA already installed at this location. Overwrite? [y/N]:');
+    if (overwrite.toLowerCase() !== 'y') {
+      log('Installation cancelled.');
+      process.exit(0);
+    }
+  }
+
+  console.log('');
+  log(`Installing to: ${installDir}`);
+  console.log('');
+
+  // ── Step 1: Copy files ──────────────────────────────────────────────────
+
+  const dirsToCopy = ['agents', 'commands', 'skills', 'templates', 'workflows', 'docs', 'bin'];
+  const filesToCopy = ['CLAUDE.md', 'CHANGELOG.md', '.mcp.json', 'package.json'];
+
+  let totalFiles = 0;
+
+  for (const dir of dirsToCopy) {
+    const src = path.join(packageDir, dir);
+    const dest = path.join(installDir, dir);
+    if (fs.existsSync(src)) {
+      const count = copyDirRecursive(src, dest);
+      success(`${dir}/ — ${count} files`);
+      totalFiles += count;
+    }
+  }
+
+  for (const file of filesToCopy) {
+    const src = path.join(packageDir, file);
+    const dest = path.join(installDir, file);
+    if (fs.existsSync(src)) {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.copyFileSync(src, dest);
+      success(file);
+      totalFiles++;
+    }
+  }
+
+  console.log('');
+
+  // ── Step 2: Register MCP servers ────────────────────────────────────────
+
+  const claudeJsonPath = path.join(homeDir, '.claude.json');
+  const addedMcps = registerMcpServers(claudeJsonPath);
+
+  if (addedMcps.length > 0) {
+    success(`MCP servers registered: ${addedMcps.join(', ')} → ${claudeJsonPath}`);
+  } else {
+    success('MCP servers already configured (playwright, context7)');
+  }
+
+  // ── Step 3: Merge settings ──────────────────────────────────────────────
+
+  const settingsMerged = mergeSettings(installDir, packageDir);
+  if (settingsMerged) {
+    success('Permissions merged into settings.json');
+  }
+
+  // ── Done ────────────────────────────────────────────────────────────────
+
+  console.log('');
+  console.log('  ╔═══════════════════════════════════════╗');
+  console.log('  ║         Installation complete!        ║');
+  console.log('  ╚═══════════════════════════════════════╝');
+  console.log('');
+  log(`${totalFiles} files installed to ${installDir}`);
+  log('MCP servers: playwright, context7');
+  log('');
+  log('Restart Claude Code, then run any QAA command:');
+  log('  /qa-start --dev-repo ./your-project');
+  log('  /qa-create-test login');
+  log('  /qa-map');
+  console.log('');
+}
+
+main().catch(err => {
+  fail(err.message);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qaa-agent",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "QA Automation Agent for Claude Code — multi-agent pipeline that analyzes repos, generates tests, validates, and creates PRs",
   "bin": {
     "qaa-agent": "./bin/install.cjs"
@@ -22,7 +22,8 @@
   "author": "Backhaus7997",
   "license": "MIT",
   "dependencies": {
-    "@playwright/mcp": "latest"
+    "@playwright/mcp": "latest",
+    "@upstash/context7-mcp": "latest"
   },
   "files": [
     "bin/",