QA360 MCP CLI – Zero-Friction Developer Experience

From zero to usable QA360 tools inside Claude Code in < 3 minutes

🚀 Quick Start

# Install globally
npm i -g @qa360/mcp

# Configure VS Code + Claude Code
qa360-mcp init

# Start MCP server
qa360-mcp up

# Open Claude Code and try:
/qa360.health

# Diagnostic (JSON output for CI)
qa360-mcp doctor --json

# Telemetry (opt-in, privacy-first)
qa360-mcp telemetry on|off|status

📋 Commands

| Command | Description | Options | |---------|-------------|---------| | qa360-mcp init | Configure VS Code & Claude Code | --non-interactive, --force | | qa360-mcp up | Start MCP Server (stdio mode) | --debug, --allow-run, --allow-secrets | | qa360-mcp serve | Alias for up command | Same as up | | qa360-mcp doctor | Check setup health | --json, --verbose | | qa360-mcp fix | Repair issues automatically | --force | | qa360-mcp reset | Clean all configurations | --yes | | qa360-mcp uninstall | Remove QA360 MCP completely | --force | | qa360-mcp telemetry | Manage opt-in telemetry | on\|off\|status | | qa360-mcp test:dx | Run DX compliance tests | --ci |

🎯 Features

✅ Zero Manual Configuration

• Auto-detects VS Code installation
• Auto-writes settings.json with backup
• Auto-discovers Claude Code extension

✅ Multi-Platform Support

• macOS: Full support (Intel + Apple Silicon)
• Linux: Ubuntu, Debian, Fedora, Arch
• Windows: PowerShell + WSL

✅ Auto-Recovery

• Server crashes → Auto-restart (max 3 attempts)
• Corrupted config → Auto-backup + repair
• Missing dependencies → Clear error messages

✅ Intelligent Feedback

• Human-readable messages
• No raw stacktraces
• Actionable fix suggestions

🔧 Configuration

Automatic (Recommended)

qa360-mcp init

This will:

1. Detect VS Code settings.json
2. Create backup (.qa360.backup.json)
3. Add MCP server configuration
4. Verify Claude Code extension

Manual

Add to VS Code settings.json:

{
  "claude.mcpServers": {
    "qa360": {
      "command": "qa360-mcp",
      "args": ["serve", "--stdio", "--allow-run"],
      "env": {
        "QA360_HOME": "~/.qa360"
      }
    }
  }
}

🧪 DX Testing

# Run DX compliance tests
qa360-mcp test:dx

# CI mode (exit with code on failure)
qa360-mcp test:dx --ci

Target: 100% DX Compliance

🛠️ Troubleshooting

Server won't start

qa360-mcp doctor
qa360-mcp fix

Claude Code not detecting tools

1. Restart VS Code
2. Check server logs: qa360-mcp up --verbose
3. Verify configuration: qa360-mcp doctor

Permission errors

# macOS/Linux
chmod +x $(which qa360-mcp)

# Windows (PowerShell as Admin)
Set-ExecutionPolicy RemoteSigned

Port already in use

# Use different port
qa360-mcp up --port 3001

📊 System Requirements

• Node.js: ≥ 18.0.0
• VS Code: Latest stable
• Claude Code: v2.0.0+
• Disk Space: ~50MB

🎯 From Zero to Running (< 3 min)

# Step 1: Install (30s)
npm i -g @qa360/mcp

# Step 2: Configure (30s)
qa360-mcp init

# Step 3: Start (30s)
qa360-mcp up

# Step 4: Verify (30s)
# Open Claude Code → Type: /qa360.health

Total: ~2 minutes ✅

🔐 Security & Permissions

Default (Read-Only)

• ✅ qa360.health - Health check
• ✅ qa360.history.list - List runs
• ✅ qa360.pack.validate - Validate packs

Opt-In (Explicit)

• 🔒 qa360.run - Requires --allow-run
• 🔒 qa360.secrets.* - Requires --allow-secrets

# Enable all permissions
qa360-mcp up --allow-run --allow-secrets

Supply Chain Security

SBOM (Software Bill of Materials): Automatically generated CycloneDX 1.5 SBOM with every build, including all 19 dependencies (9 production + 10 development) with cryptographic verification.

Note: During SBOM generation, you may see npm error missing: ... messages. These are harmless warnings from upstream peer/dev dependencies (ESLint, Vitest, etc.) not required at runtime. The SBOM pipeline uses package-lock.json with automatic fallback and verification (> 500 bytes). CI fails only if SBOM is absent or invalid.

🔄 CI/CD Integration

JSON Output for Automation

# Get structured health check results
qa360-mcp doctor --json

# Example output:
{
  "timestamp": "2025-10-25T14:30:00.000Z",
  "summary": {
    "total": 7,
    "passed": 7,
    "warnings": 0,
    "errors": 0,
    "status": "ok"
  },
  "checks": [...]
}

# Exit codes: 0 = PASS, 1 = FAIL

Non-Interactive Mode

# CI/CD pipeline
qa360-mcp init --non-interactive --force
qa360-mcp doctor --json
qa360-mcp uninstall --force

GitHub Actions Example

- name: Install QA360 MCP
  run: npm i -g @qa360/mcp

- name: Configure
  run: qa360-mcp init --non-interactive --force

- name: Health Check
  run: qa360-mcp doctor --json

📊 Telemetry (Opt-In, Privacy-First)

Privacy Policy

Default: Telemetry is DISABLED until you explicitly enable it.

What we collect (when enabled):

• CLI version
• Operating system (platform/arch)
• Command execution times
• Anonymous error codes

What we DO NOT collect:

• Personal information
• File paths or content
• VS Code settings
• Project names or URLs

Commands

# Enable telemetry
qa360-mcp telemetry on

# Disable telemetry
qa360-mcp telemetry off

# Check status
qa360-mcp telemetry status

All telemetry data is stored locally only in ~/.qa360/telemetry-logs/ and never sent without explicit consent.

📚 Documentation

• Full Documentation
• MCP Protocol
• Claude Code Extension

🤝 Contributing

# Clone repo
git clone https://github.com/qa360/qa360.git
cd qa360/packages/qa360-mcp-cli

# Install dependencies
pnpm install

# Build
pnpm build

# Test
pnpm test:dx

📝 License

MIT © QA360 Team

🎯 From zero to running QA360 tools in < 3 min