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

{
  "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:

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:

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:

cd flask-shopdb
docker compose up -d db

Verify:

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:

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):

# On VM
.\\.claude\enable-vm-ssh.ps1

Verify from host:

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

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:

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:

{
  "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:

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

2. Use Snapshots for Risky Operations

Before destructive VM operations:

Checkpoint-VM -Name "ShopDB-Test-VM" -SnapshotName "Before-$(Get-Date -Format 'yyyyMMdd-HHmm')"

3. Clean Up Test Data

After testing with MySQL:

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

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

# 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!