qacito CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Build (TypeScript only)
npm run build

# Build mcp-app → dashboard → TypeScript (in order)
npm run build:all

# Run MCP server (stdio transport)
npm start

# Run MCP server (HTTP transport on port 4712)
npm run start:http

# Run all tests (unit + integration)
npx playwright test

# Run a single test file
npx playwright test src/tools/run-tests/retry-tracker.test.ts

# Build only the MCP App React bundle
npm run build:mcp-app

# Build .mcpb distributable
npm run build:mcpb

# Run headless batch orchestrator (CI mode, requires ANTHROPIC_API_KEY)
npm run batch -- --project /path/to/project --output report.json

# Register QAcito as MCP server (global — available in all projects)
claude mcp add --scope user qacito -- node "$(pwd)/dist/server/index.js"

# Register QAcito as MCP server (project-only — writes .mcp.json in the target project)
claude mcp add --scope project qacito -- node "/absolute/path/to/QAcito/dist/server/index.js"

# Verify registration and connection
claude mcp list

# (Legacy) TUI wizard — writes to settings.json, does NOT register the MCP correctly
node scripts/install.mjs

Note: install.mjs writes to ~/.claude/settings.json which Claude Code does not read for MCP servers. Always use claude mcp add instead. MCPs are stored in ~/.claude.json (user scope) or .mcp.json (project scope).

Architecture

QAcito is an MCP server with a strict separation: Claude decides, QAcito executes. The server never interprets results or chooses what to test — that's Claude's job.

Transports

src/server/index.ts boots two layers before accepting MCP connections:

1. Dashboard server (src/dashboard-server/) — Express + WebSocket on a dynamic port (50000–59999). Must start first because tools depend on its run-store and WS broadcaster.
2. MCP transport — stdio (default) or HTTP (QACITO_HTTP_PORT=4712).