shopdb-flask/.claude/archived/README-MCP-SETUP.md

# MCP Server Setup for ShopDB Development

Quick reference for the complete MCP (Model Context Protocol) server configuration.

---

## What is MCP?

**MCP** extends Claude Code with external tool access. ShopDB uses 4 MCP servers:

| Server | Purpose | What Claude Can Do |
|--------|---------|-------------------|
| **gortex** | Project management | Track tasks, milestones, time logs |
| **mysql** | Database access | Query database, verify data, create test records |
| **browser** | Web automation | Test UI, capture screenshots, fill forms |
| **vm** | VM automation | Deploy to test VM, run commands, check logs |

Together, these enable **full-stack automated workflows** through natural language.

---

## Quick Start

### 1. Install Prerequisites

```powershell
cd flask-shopdb
.\\.claude\quick-start-mcp.ps1
```

This installs:
- Gortex executable
- Node.js packages (mysql, browser, ssh-mcp)
- Starts MySQL database
- Verifies VM connectivity
- Runs test suite

### 2. Verify Setup

```powershell
.\\.claude\test-mcp-servers.ps1
```

Expected output:
```
=========================================
ShopDB MCP Server Test Suite
=========================================

[1/7] Checking MCP configuration... OK
[2/7] Testing Gortex MCP server... OK
[3/7] Testing MySQL MCP server... OK
[4/7] Testing Browser MCP server... OK
[5/7] Testing VM SSH MCP server... OK
[6/7] Checking Hyper-V VMs... OK
[7/7] Checking VM snapshots... OK

Overall: 7/7 tests passed (100%)
```

### 3. Start Claude Code

**IMPORTANT:** Run Claude Code from the `flask-shopdb` directory to load MCP servers.

```bash
cd flask-shopdb
claude
```

### 4. Test MCP Servers

Try these commands with Claude:

```
"List all tasks in the current project"          # Tests Gortex
"Show me the first 5 endpoints in the database"  # Tests MySQL
"Take a screenshot of https://localhost:5001"    # Tests Browser
"What is the hostname of the VM?"                # Tests VM
```

---

## Configuration File

**Location:** `flask-shopdb/.claude/mcp-servers.json`

```json
{
  "mcpServers": {
    "gortex": {
      "command": "C:\\Users\\270015376\\Documents\\gortex.exe",
      "args": ["mcp"],
      "cwd": "C:\\Users\\270015376\\Documents\\github\\flask-shopdb"
    },
    "mysql": {
      "command": "npx",
      "args": [
        "-y",
        "@benborla29/mcp-server-mysql",
        "mysql://shopdb:shopdb-dev-password@127.0.0.1:3306/shopdb_flask"
      ]
    },
    "browser": {
      "command": "npx",
      "args": ["-y", "@agent-infra/mcp-server-browser"]
    },
    "vm": {
      "command": "npx",
      "args": [
        "-y",
        "ssh-mcp",
        "--host", "192.168.100.10",
        "--user", "SupportUser",
        "--password", "vos313"
      ]
    }
  }
}
```

---

## VM Setup (One-Time)

The test VM requires SSH to be enabled once:

**On the VM** (as Administrator):
```powershell
.\\.claude\enable-vm-ssh.ps1
```

This:
1. Sets password for SupportUser
2. Enables SSH password authentication
3. Restarts SSH service
4. Configures firewall

**Test from host:**
```bash
ssh SupportUser@192.168.100.10 "hostname"
```

---

## VM Snapshots

Create baseline snapshots for rapid testing:

```powershell
# Clean Windows 11
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Clean-Install"

# Docker installed
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Docker-Ready"

# SSH enabled
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "SSH-Enabled"

# ShopDB deployed
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "ShopDB-Deployed"
```

See: `.claude/VM-SNAPSHOT-GUIDE.md`

---

## Example Workflows

### End-to-End Agent Test

```
You: "Deploy the agent to the VM and test it"

Claude:
1. [Bash: Build agent]
2. [VM: Copy agent to VM]
3. [VM: Install agent service]
4. [VM: Start service]
5. [MySQL: Create test fleet alert]
6. [VM: Check agent log for alert]
7. [VM: Verify tray shows notification]
8. [MySQL: Delete test data]
```

### Database-Driven UI Test

```
You: "Test the notifications UI with different alert priorities"

Claude:
1. [MySQL: Insert critical alert]
2. [Browser: Screenshot alert]
3. [MySQL: Update to info priority]
4. [Browser: Screenshot updated alert]
5. [MySQL: Delete test alert]
```

### Multi-Environment Testing

```
You: "Test new plugin on local and VM simultaneously"

Claude:
1. [Bash: Build frontend]
2. [Bash: Restart local Docker]
3. [VM: Deploy to VM]
4. [Browser: Test localhost:5001]
5. [Browser: Test 192.168.100.10:5001]
6. [Compare results]
```

---

## Documentation

| File | Description |
|------|-------------|
| `README-MCP-SETUP.md` | This file - quick reference |
| `MCP-INTEGRATION-GUIDE.md` | Complete guide with advanced workflows |
| `VM-SNAPSHOT-GUIDE.md` | Snapshot management for testing |
| `setup-vm-ssh.md` | SSH configuration guide |
| `test-mcp-servers.ps1` | Test suite for all servers |
| `quick-start-mcp.ps1` | Automated setup script |
| `enable-vm-ssh.ps1` | Run on VM to enable SSH |

---

## Troubleshooting

### MCP Servers Not Loading

1. Verify you're in flask-shopdb directory
2. Check `.claude/mcp-servers.json` exists
3. Restart Claude Code completely
4. Run test suite: `.\\.claude\test-mcp-servers.ps1`

### MySQL Connection Failed

```bash
docker compose up -d db
mysql -h 127.0.0.1 -u shopdb -pshopdb-dev-password shopdb_flask
```

### VM Not Reachable

1. Check VM is running in Hyper-V Manager
2. Verify VM has internal network adapter
3. Ping test: `ping 192.168.100.10`
4. SSH test: `ssh SupportUser@192.168.100.10`
5. Run on VM: `.\\.claude\enable-vm-ssh.ps1`

### Browser Automation Failed

1. Check Chrome/Chromium installed
2. Close other Chrome instances
3. Test manually: `npx -y @agent-infra/mcp-server-browser`

---

## Security Notes

### Development Credentials

**Database:** `mysql://shopdb:shopdb-dev-password@127.0.0.1:3306/shopdb_flask`
- Local development only
- Not exposed beyond localhost
- Different credentials in production

**VM SSH:** `SupportUser / vos313`
- Test VM only on internal network (192.168.100.x)
- No internet access
- VM rebuilt regularly

### Production

- Environment variables for credentials
- Encrypted connections
- Restricted database users
- No MCP servers in production

---

## Next Steps

1. Run quick start: `.\\.claude\quick-start-mcp.ps1`
2. Verify all tests pass: `.\\.claude\test-mcp-servers.ps1`
3. Create VM snapshots: See `VM-SNAPSHOT-GUIDE.md`
4. Read integration guide: `MCP-INTEGRATION-GUIDE.md`
5. Start Claude Code: `claude` (from flask-shopdb directory)
6. Test with example commands

---

## Support

**Test Suite Issues:**
```powershell
.\\.claude\test-mcp-servers.ps1 -Verbose
```

**Manual Testing:**
```bash
# Test Gortex
C:\Users\270015376\Documents\gortex.exe --version

# Test MySQL
npx -y @benborla29/mcp-server-mysql --help

# Test Browser
npx -y @agent-infra/mcp-server-browser --help

# Test VM
ssh SupportUser@192.168.100.10 "hostname"
```

**Logs:**
- Claude Code logs: `~/.claude/logs/`
- Docker logs: `docker logs flask-shopdb-api-1`
- VM logs: `C:\ProgramData\ssh\logs\sshd.log` (on VM)

---

**Ready for automated full-stack development with Claude Code + MCP!**