shopdb-flask/.claude/setup/MCP-INTEGRATION-GUIDE.md

# MCP Server Integration Guide for ShopDB Development

Complete guide to using all four MCP servers together with Claude Code for automated development, testing, and deployment workflows.

---

## Overview

**MCP (Model Context Protocol) Servers** extend Claude Code with external tool access:

| MCP Server | Purpose | Tools Provided |
|------------|---------|----------------|
| **gortex** | Project management | Task tracking, milestones, time tracking |
| **mysql** | Database access | Query execution, schema inspection, data manipulation |
| **browser** | Web automation | Page navigation, screenshots, form filling, testing |
| **vm** | VM automation via SSH | Command execution, file transfer, process management |

Together, these enable **full-stack automated workflows**: from code changes to database migrations to VM deployment to browser testing, all through natural language conversation with Claude.

---

## Configuration

### Location

All MCP servers are configured in:
```
flask-shopdb/.claude/mcp-servers.json
```

**Important:** MCP servers only load when Claude Code runs from `flask-shopdb` directory.

### Current Configuration

```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"
      ]
    }
  }
}
```

---

## Prerequisites

### 1. Gortex MCP Server

**Install:**
```bash
curl -L -o gortex_windows_amd64.zip https://github.com/zzet/gortex/releases/latest/download/gortex_windows_amd64.zip
unzip -o gortex_windows_amd64.zip -d C:\Users\270015376\Documents\
```

**Verify:**
```bash
C:\Users\270015376\Documents\gortex.exe --version
```

**What it enables:**
- Track development tasks
- Log time spent on features
- Manage sprint milestones
- Generate reports

### 2. MySQL MCP Server

**Install:** (handled by npx, no manual install needed)

**Requires:** MySQL/Docker running locally

**Start database:**
```bash
cd flask-shopdb
docker compose up -d db
```

**Verify:**
```bash
mysql -h 127.0.0.1 -u shopdb -pshopdb-dev-password shopdb_flask -e "SELECT 1"
```

**What it enables:**
- Query database directly
- Inspect schema and indexes
- Verify migration results
- Create test data
- Debug data issues

### 3. Browser MCP Server

**Install:** (handled by npx, no manual install needed)

**Requires:** Chrome/Chromium browser installed

**Verify:**
```bash
npx -y @agent-infra/mcp-server-browser --help
```

**What it enables:**
- Automated UI testing
- Screenshot capture
- Form submission testing
- Visual regression checks
- End-to-end workflow testing

### 4. VM SSH MCP Server

**Install:** (handled by npx, no manual install needed)

**Requires:** 
- Hyper-V VM running at 192.168.100.10
- OpenSSH server enabled on VM
- User account: SupportUser (password: vos313)

**Setup VM SSH** (run on VM as Administrator):
```powershell
# On VM
.\\.claude\enable-vm-ssh.ps1
```

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

**What it enables:**
- Deploy agent to test VM
- Run commands on VM
- Transfer files to/from VM
- Monitor agent logs
- Test agent integration

---

## Testing MCP Servers

### Run Test Suite

```powershell
cd flask-shopdb
.\\.claude\test-mcp-servers.ps1
```

**Output:**
```
==========================================
ShopDB MCP Server Test Suite
==========================================

[1/7] Checking MCP configuration...
  OK: Config file exists
[2/7] Testing Gortex MCP server...
  OK: Gortex found at C:\Users\270015376\Documents\gortex.exe
[3/7] Testing MySQL MCP server...
  OK: MySQL server is reachable at 127.0.0.1:3306
[4/7] Testing Browser MCP server...
  OK: Browser MCP package exists (version 1.2.3)
[5/7] Testing VM SSH MCP server...
  OK: VM is reachable at 192.168.100.10
  OK: SSH port 22 is open on VM
[6/7] Checking Hyper-V VMs...
  OK: Found 1 VM(s)
    - ShopDB-Test-VM: Running
[7/7] Checking VM snapshots...
  OK: Found 4 snapshot(s)
    - ShopDB-Test-VM: Clean-Install (2024-09-08 10:30)
    - ShopDB-Test-VM: Docker-Ready (2024-09-08 11:45)
    - ShopDB-Test-VM: SSH-Enabled (2024-09-08 12:15)
    - ShopDB-Test-VM: ShopDB-Deployed (2024-09-09 09:00)

==========================================
Summary
==========================================

  config         : OK
  gortex         : OK
  mysql          : OK
  browser        : OK
  vm             : OK
  hyperv         : OK
  snapshots      : OK

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

### Test Individual Servers with Claude

**Start Claude Code from flask-shopdb:**
```bash
cd flask-shopdb
claude
```

**Test Gortex:**
```
You: "List all tasks in the current project"
Claude: [Uses mcp__gortex__list_tasks]
```

**Test MySQL:**
```
You: "Show me the first 5 endpoints in the database"
Claude: [Uses mcp__mysql__query]
```

**Test Browser:**
```
You: "Take a screenshot of https://localhost:5001"
Claude: [Uses mcp__browser__navigate and mcp__browser__screenshot]
```

**Test VM:**
```
You: "What is the hostname of the VM?"
Claude: [Uses mcp__vm__exec with command "hostname"]
```

---

## Integrated Workflows

### Workflow 1: Feature Development with Database Changes

**Scenario:** Add new field to endpoints table, update API, test on VM

```
You: "Add 'last_boot_time' timestamp field to endpoints"

Claude:
1. [Gortex: Create task "Add last_boot_time field"]
2. [MySQL: Check current endpoints schema]
3. [Edit: Create Alembic migration]
4. [Bash: Run migration locally]
5. [MySQL: Verify column added]
6. [Edit: Update endpoint model and API]
7. [Bash: Run tests]
8. [Gortex: Update task status to "testing"]
9. [VM: Deploy to test VM]
10. [VM: Restart agent]
11. [MySQL: Check VM endpoint records include new field]
12. [Gortex: Mark task complete]

Result: Feature developed, tested, and verified end-to-end
```

### Workflow 2: UI Testing After Plugin Changes

**Scenario:** Modified plugins UI, verify it works in browser

```
You: "Test the new notifications plugin UI"

Claude:
1. [Bash: Build frontend]
2. [Bash: Restart Docker stack]
3. [Browser: Navigate to https://localhost:5001]
4. [Browser: Login as admin]
5. [Browser: Click "Notifications" in sidebar]
6. [Browser: Screenshot current state]
7. [MySQL: Insert test fleet alert]
8. [Browser: Refresh page]
9. [Browser: Verify alert appears]
10. [Browser: Screenshot alert display]
11. [MySQL: Delete test data]

Result: UI tested, screenshots captured, test data cleaned up
```

### Workflow 3: Agent Deployment and Integration Test

**Scenario:** Build new agent version, deploy to VM, verify it connects

```
You: "Build agent and deploy to VM for testing"

Claude:
1. [Gortex: Create task "Test agent v1.2.4"]
2. [Bash: Increment agent version in .csproj]
3. [Bash: dotnet publish agent]
4. [VM: Stop agent service if running]
5. [VM: Copy new agent.exe to C:\Program Files\ShopDB\]
6. [VM: Start agent service]
7. [VM: Tail agent log file]
8. [MySQL: Wait for endpoint heartbeat]
9. [MySQL: Verify endpoint version = 1.2.4]
10. [Browser: Navigate to endpoints page]
11. [Browser: Screenshot showing new version]
12. [Gortex: Mark task complete]

Result: Agent built, deployed, verified working
```

### Workflow 4: Database Migration with Rollback Test

**Scenario:** Create migration, test forward and backward migration

```
You: "Create migration to add 'tags' JSONB column to assets"

Claude:
1. [MySQL: Backup current schema]
2. [Edit: Create migration file]
3. [Bash: Run migration (upgrade)]
4. [MySQL: Verify column exists with correct type]
5. [MySQL: Insert test data with tags]
6. [Bash: Rollback migration (downgrade)]
7. [MySQL: Verify column removed]
8. [MySQL: Verify no data loss in other columns]
9. [Bash: Re-run migration (upgrade)]
10. [MySQL: Verify clean forward migration]

Result: Migration tested both directions, safe to deploy
```

### Workflow 5: End-to-End Operator Report Test

**Scenario:** Verify operator report flow from tray to database

```
You: "Test operator report submission from VM"

Claude:
1. [VM: Restore to "Agent-Running" snapshot]
2. [MySQL: Clear existing operator reports]
3. [VM: Get current timestamp]
4. [VM: Simulate tray submitting report via API]
5. [MySQL: Query for new report record]
6. [MySQL: Verify all fields populated correctly]
7. [Browser: Navigate to operator reports page]
8. [Browser: Verify report appears in UI]
9. [Browser: Screenshot report details]
10. [VM: Check agent log for submission confirmation]

Result: Operator report flow verified end-to-end
```

### Workflow 6: Performance Testing and Monitoring

**Scenario:** Load test endpoints API, monitor database performance

```
You: "Load test the endpoints API with 1000 concurrent requests"

Claude:
1. [MySQL: Record current query performance stats]
2. [Bash: Run load test script]
3. [MySQL: Monitor slow query log during test]
4. [MySQL: Check connection pool usage]
5. [MySQL: Analyze query performance after test]
6. [MySQL: Identify slow queries]
7. [MySQL: Check index usage statistics]
8. [Gortex: Create tasks for performance improvements]

Result: Performance baseline established, bottlenecks identified
```

---

## Advanced Patterns

### Pattern 1: Snapshot-Based Testing

**Use VM snapshots for rapid iteration:**

```
You: "Test 3 different agent configurations"

Claude:
1. [VM: Restore to "Agent-Installed" snapshot]
2. [VM: Configure with settings A]
3. [VM: Test and record results]
4. [VM: Restore to "Agent-Installed" snapshot]
5. [VM: Configure with settings B]
6. [VM: Test and record results]
7. [VM: Restore to "Agent-Installed" snapshot]
8. [VM: Configure with settings C]
9. [VM: Test and record results]
10. [Compare results and recommend best config]
```

### Pattern 2: Database-Driven UI Testing

**Generate test data in database, verify UI displays it correctly:**

```
You: "Test UI with various alert configurations"

Claude:
1. [MySQL: Create alert with priority=critical]
2. [Browser: Screenshot alert display]
3. [MySQL: Update alert to priority=info]
4. [Browser: Refresh and screenshot]
5. [MySQL: Create multi-line alert message]
6. [Browser: Screenshot message display]
7. [MySQL: Create alert with long title (100 chars)]
8. [Browser: Screenshot title truncation]
9. [MySQL: Delete all test alerts]
```

### Pattern 3: Parallel Testing

**Test on multiple environments simultaneously:**

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

Claude:
1. [Bash: Build frontend with new plugin]
2. [Bash: Restart local Docker stack]
3. [VM: Deploy to VM Docker stack]
4. [Parallel:]
   a. [Browser: Test on localhost:5001]
   b. [Browser: Test on 192.168.100.10:5001]
5. [Compare results]
6. [Screenshot differences if any]
```

### Pattern 4: Automated Debugging

**Use MCP tools to diagnose issues:**

```
You: "Agent on VM is not receiving alerts, debug why"

Claude:
1. [VM: Check agent service status]
2. [VM: Check agent log for errors]
3. [MySQL: Verify alerts exist in database]
4. [MySQL: Check alert has target matching VM endpoint]
5. [VM: Check network connectivity to API]
6. [VM: Check agent config BaseUrl setting]
7. [MySQL: Check endpoint record has correct IP]
8. [VM: Test manual API call]
9. [Identify root cause and suggest fix]
```

---

## Security Considerations

### Database Credentials

**In mcp-servers.json:**
```
mysql://shopdb:shopdb-dev-password@127.0.0.1:3306/shopdb_flask
```

- Only for local development
- Database not exposed beyond localhost
- Not used in production

**Production uses:**
- Environment variables for credentials
- Restricted database users
- Encrypted connections

### VM SSH Credentials

**In mcp-servers.json:**
```
"--password", "vos313"
```

- Test VM only, internal network (192.168.100.x)
- No internet access on VM
- VM destroyed/rebuilt regularly
- Not a production system

**Better approach (optional):**
- Use SSH key instead of password
- See `.claude/setup-vm-ssh.md` for key-based auth

### MCP Server Permissions

**Claude Code permission prompts:**
- First use of each MCP tool requires approval
- Approve dangerous operations (DELETE, DROP) individually
- Review SQL queries before execution

**Configure auto-approval for safe operations:**

Add to `.claude/settings.json`:
```json
{
  "permissions": {
    "allow": [
      "mcp__mysql__query(SELECT *)",
      "mcp__vm__exec(hostname)",
      "mcp__browser__screenshot(*)"
    ]
  }
}
```

---

## Troubleshooting

### MCP Server Not Loading

**Symptom:** Claude says "I don't have access to {server}"

**Fixes:**
1. Verify running Claude Code from `flask-shopdb` directory
2. Check `.claude/mcp-servers.json` exists
3. Restart Claude Code completely
4. Run `test-mcp-servers.ps1` to diagnose

### MySQL Connection Failed

**Symptom:** "Cannot connect to MySQL server"

**Fixes:**
1. Start database: `docker compose up -d db`
2. Check port: `netstat -ano | findstr 3306`
3. Test connection: `mysql -h 127.0.0.1 -u shopdb -p`
4. Check Docker network settings

### VM SSH Connection Failed

**Symptom:** "SSH connection refused" or "Authentication failed"

**Fixes:**
1. Verify VM running: `Get-VM | Where-Object State -eq 'Running'`
2. Test ping: `ping 192.168.100.10`
3. Check SSH service on VM: `Get-Service sshd`
4. Run `enable-vm-ssh.ps1` on VM
5. Verify credentials: `ssh SupportUser@192.168.100.10`

### Browser Automation Failed

**Symptom:** "Browser launch failed" or "Navigation timeout"

**Fixes:**
1. Check Chrome installed
2. Close other Chrome instances
3. Check no port conflicts
4. Try manual command: `npx -y @agent-infra/mcp-server-browser`

### Gortex Not Found

**Symptom:** "Cannot find gortex.exe"

**Fixes:**
1. Download: https://github.com/zzet/gortex/releases
2. Extract to: `C:\Users\270015376\Documents\gortex.exe`
3. Verify: `gortex.exe --version`

---

## Best Practices

### 1. Always Test MCP Setup First

**Before starting work:**
```bash
cd flask-shopdb
.\\.claude\test-mcp-servers.ps1
```

### 2. Use Snapshots for Risky Operations

**Before destructive VM operations:**
```powershell
Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Before-$(Get-Date -Format 'yyyyMMdd-HHmm')"
```

### 3. Clean Up Test Data

**After testing with MySQL:**
```sql
-- Delete test records created during testing
DELETE FROM fleetalerts WHERE title LIKE 'TEST:%';
DELETE FROM operatorreports WHERE submittedby = 'test-user';
```

### 4. Verify Results

**Don't trust logs alone:**
- Use MySQL to verify database changes
- Use Browser to verify UI changes
- Use VM commands to verify agent behavior

### 5. Keep MCP Config in Sync

**When changing database password:**
- Update `mcp-servers.json`
- Update `.env` files
- Update `docker-compose.yml` if needed

---

## Quick Reference

### Starting MCP-Enabled Session

```bash
cd C:\Users\270015376\Documents\github\flask-shopdb
claude
```

### Common MCP Commands via Claude

| Task | Example Request |
|------|----------------|
| Query database | "Show me all endpoints that have not checked in for 24 hours" |
| Execute on VM | "Run 'Get-Service shopdb*' on the VM" |
| Screenshot UI | "Take a screenshot of the notifications page" |
| Create task | "Create a task to fix endpoint heartbeat bug" |
| Copy file to VM | "Upload the latest agent build to the VM" |
| Run migration | "Apply the pending database migration" |
| Test UI flow | "Test the login flow and capture screenshots" |
| Check logs | "Show me the agent log from the VM" |

### Debugging MCP Issues

```bash
# Test each server individually
npx -y @benborla29/mcp-server-mysql --help
npx -y @agent-infra/mcp-server-browser --help
npx -y ssh-mcp --host 192.168.100.10 --user SupportUser --password vos313
C:\Users\270015376\Documents\gortex.exe mcp --help

# Check permissions
cat .claude/settings.json | grep -A 20 permissions

# Check MCP server logs
# (Claude Code shows MCP errors in transcript)
```

---

## Related Documentation

- **VM Snapshots:** `.claude/VM-SNAPSHOT-GUIDE.md`
- **VM SSH Setup:** `.claude/setup-vm-ssh.md`
- **Test MCP Servers:** `.claude/test-mcp-servers.ps1`
- **VM Deployment:** `DEPLOY-TO-VM.md`
- **Plugin Development:** `../shopdb-flask.wiki/PLUGIN-DEVELOPMENT.md`

---

## Next Steps

1. **Run test suite:** `.\\.claude\test-mcp-servers.ps1`
2. **Create baseline snapshots:** See `VM-SNAPSHOT-GUIDE.md`
3. **Try example workflow:** Pick one from "Integrated Workflows" section
4. **Document your workflows:** Add custom patterns to this guide
5. **Automate repetitive tasks:** Create aliases for common MCP operations

---

**Ready to use all four MCP servers together for rapid development!**