# QA360 MCP CLI – Zero-Friction Developer Experience

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

## 🚀 Quick Start

```bash
# 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)

```bash
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`:

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

## 🧪 DX Testing

```bash
# 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

```bash
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

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

# Windows (PowerShell as Admin)
Set-ExecutionPolicy RemoteSigned
```

### Port already in use

```bash
# 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)

```bash
# 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`

```bash
# 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

```bash
# 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

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

### GitHub Actions Example

```yaml
- 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

```bash
# 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](https://github.com/qa360/mcp)
- [MCP Protocol](https://modelcontextprotocol.io)
- [Claude Code Extension](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code)

## 🤝 Contributing

```bash
# 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**